no-restricted-properties

Disallow certain properties on certain objects

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.

Rule Details

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. This rule applies to both properties accessed by dot notation and destructuring.

Options

This rule takes a list of objects, where the object name and property names are specified:

{
    "rules": {
        "no-restricted-properties": [2, {
            "object": "disallowedObjectName",
            "property": "disallowedPropertyName"
        }]
    }
}
1
2
3
4
5
6
7
8

Multiple object/property values can be disallowed, and you can specify an optional message:

{
    "rules": {
        "no-restricted-properties": [2, {
            "object": "disallowedObjectName",
            "property": "disallowedPropertyName"
        }, {
            "object": "disallowedObjectName",
            "property": "anotherDisallowedPropertyName",
            "message": "Please use allowedObjectName.allowedPropertyName."
        }]
    }
}
1
2
3
4
5
6
7
8
9
10
11
12

If the object name is omitted, the property is disallowed for all objects:

{
    "rules": {
        "no-restricted-properties": [2, {
            "property": "__defineGetter__",
            "message": "Please use Object.defineProperty instead."
        }]
    }
}
1
2
3
4
5
6
7
8

If the property name is omitted, accessing any property of the given object is disallowed:

{
    "rules": {
        "no-restricted-properties": [2, {
            "object": "require",
            "message": "Please call require() directly."
        }]
    }
}
1
2
3
4
5
6
7
8

If you want to restrict a property globally but allow specific objects to use it, you can use the allowObjects option:

{
    "rules": {
        "no-restricted-properties": [2, {
            "property": "push",
            "allowObjects": ["router"],
            "message": "Prefer [...array, newValue] because it does not mutate the array in place."
        }]
    }
}
1
2
3
4
5
6
7
8
9

If you want to restrict all properties on an object except for specific ones, you can use the allowProperties option:

{
    "rules": {
        "no-restricted-properties": [2, {
            "object": "config",
            "allowProperties": ["settings", "version"],
            "message": "Accessing other properties is restricted."
        }]
    }
}
1
2
3
4
5
6
7
8
9

Note that the allowObjects option cannot be used together with the object option since they are mutually exclusive. Similarly, the allowProperties option cannot be used together with the property option since they are also mutually exclusive.

Examples of incorrect code for this rule:

/* eslint no-restricted-properties: [2, {
    "object": "disallowedObjectName",
    "property": "disallowedPropertyName"
}] */

const example = disallowedObjectName.disallowedPropertyName; /*error Disallowed object property: disallowedObjectName.disallowedPropertyName.*/

disallowedObjectName.disallowedPropertyName(); /*error Disallowed object property: disallowedObjectName.disallowedPropertyName.*/
1
2
3
4
5
6
7
8

/* eslint no-restricted-properties: [2, {
    "property": "__defineGetter__"
}] */

foo.__defineGetter__(bar, baz);

const { __defineGetter__ } = qux();

({ __defineGetter__ }) => {};
1
2
3
4
5
6
7
8
9

/* eslint no-restricted-properties: [2, {
    "object": "require"
}] */

require.resolve('foo');
1
2
3
4
5

/* eslint no-restricted-properties: [2, {
    "property": "push",
    "allowObjects": ["router"],
}] */

myArray.push(5);
1
2
3
4
5
6

/* eslint no-restricted-properties: [2, {
    "object": "config",
    "allowProperties": ["settings", "version"]
}] */

config.apiKey = "12345";
config.timeout = 5000;
1
2
3
4
5
6
7

Examples of correct code for this rule:

/* eslint no-restricted-properties: [2, {
    "object": "disallowedObjectName",
    "property": "disallowedPropertyName"
}] */

const example = disallowedObjectName.somePropertyName;

allowedObjectName.disallowedPropertyName();
1
2
3
4
5
6
7
8

/* eslint no-restricted-properties: [2, {
    "object": "require"
}] */

require('foo');
1
2
3
4
5

/* eslint no-restricted-properties: [2, {
    "property": "push",
    "allowObjects": ["router", "history"],
}] */

router.push('/home');
history.push('/about');
1
2
3
4
5
6
7

/* eslint no-restricted-properties: [2, {
    "object": "config",
    "allowProperties": ["settings", "version"]
}] */

config.settings = { theme: "dark" };
config.version = "1.0.0";  
1
2
3
4
5
6
7

When Not To Use It

If you don’t have any object/property combinations to restrict, you should not use this rule.

Related Rules

• no-restricted-globals
• no-restricted-syntax

Version

This rule was introduced in ESLint v3.5.0.

Resources

• Rule source
• Tests source