eslint/docs/src/rules/no-restricted-properties.md

   1 ---
   2 title: no-restricted-properties
   3 layout: doc
   4 rule_type: suggestion
   5 related_rules:
   6 - no-restricted-globals
   7 - no-restricted-syntax
   8 ---
   9
  10
  11 Certain properties on objects may be disallowed in a codebase. This is useful for deprecating an API or restricting usage of a module's methods. For example, you may want to disallow using `describe.only` when using Mocha or telling people to use `Object.assign` instead of `_.extend`.
  12
  13 ## Rule Details
  14
  15 This rule looks for accessing a given property key on a given object name, either when reading the property's value or invoking it as a function. You may specify an optional message to indicate an alternative API or a reason for the restriction.
  16
  17 ### Options
  18
  19 This rule takes a list of objects, where the object name and property names are specified:
  20
  21 ```json
  22 {
  23     "rules": {
  24         "no-restricted-properties": [2, {
  25             "object": "disallowedObjectName",
  26             "property": "disallowedPropertyName"
  27         }]
  28     }
  29 }
  30 ```
  31
  32 Multiple object/property values can be disallowed, and you can specify an optional message:
  33
  34 ```json
  35 {
  36     "rules": {
  37         "no-restricted-properties": [2, {
  38             "object": "disallowedObjectName",
  39             "property": "disallowedPropertyName"
  40         }, {
  41             "object": "disallowedObjectName",
  42             "property": "anotherDisallowedPropertyName",
  43             "message": "Please use allowedObjectName.allowedPropertyName."
  44         }]
  45     }
  46 }
  47 ```
  48
  49 If the object name is omitted, the property is disallowed for all objects:
  50
  51 ```json
  52 {
  53     "rules": {
  54         "no-restricted-properties": [2, {
  55             "property": "__defineGetter__",
  56             "message": "Please use Object.defineProperty instead."
  57         }]
  58     }
  59 }
  60 ```
  61
  62 If the property name is omitted, accessing any property of the given object is disallowed:
  63
  64 ```json
  65 {
  66     "rules": {
  67         "no-restricted-properties": [2, {
  68             "object": "require",
  69             "message": "Please call require() directly."
  70         }]
  71     }
  72 }
  73 ```
  74
  75 Examples of **incorrect** code for this rule:
  76
  77 ::: incorrect
  78
  79 ```js
  80 /* eslint no-restricted-properties: [2, {
  81     "object": "disallowedObjectName",
  82     "property": "disallowedPropertyName"
  83 }] */
  84
  85 var example = disallowedObjectName.disallowedPropertyName; /*error Disallowed object property: disallowedObjectName.disallowedPropertyName.*/
  86
  87 disallowedObjectName.disallowedPropertyName(); /*error Disallowed object property: disallowedObjectName.disallowedPropertyName.*/
  88 ```
  89
  90 :::
  91
  92 ::: incorrect
  93
  94 ```js
  95 /* eslint no-restricted-properties: [2, {
  96     "property": "__defineGetter__"
  97 }] */
  98
  99 foo.__defineGetter__(bar, baz);
 100 ```
 101
 102 :::
 103
 104 ::: incorrect
 105
 106 ```js
 107 /* eslint no-restricted-properties: [2, {
 108     "object": "require"
 109 }] */
 110
 111 require.resolve('foo');
 112 ```
 113
 114 :::
 115
 116 Examples of **correct** code for this rule:
 117
 118 ::: correct
 119
 120 ```js
 121 /* eslint no-restricted-properties: [2, {
 122     "object": "disallowedObjectName",
 123     "property": "disallowedPropertyName"
 124 }] */
 125
 126 var example = disallowedObjectName.somePropertyName;
 127
 128 allowedObjectName.disallowedPropertyName();
 129 ```
 130
 131 :::
 132
 133 ::: correct
 134
 135 ```js
 136 /* eslint no-restricted-properties: [2, {
 137     "object": "require"
 138 }] */
 139
 140 require('foo');
 141 ```
 142
 143 :::
 144
 145 ## When Not To Use It
 146
 147 If you don't have any object/property combinations to restrict, you should not use this rule.