no-restricted-properties - ESLint - Pluggable JavaScript Linter (original) (raw)

Disallow certain properties on certain objects

Table of Contents

  1. Rule Details
    1. Options
  2. When Not To Use It
  3. Related Rules
  4. Version
  5. Resources

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"
        }]
    }
}

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."
        }]
    }
}

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."
        }]
    }
}

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."
        }]
    }
}

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."
        }]
    }
}

Note that the allowObjects option cannot be used together with the object option since they are mutually exclusive.

Examples of incorrect code for this rule:

Open in Playground

/* 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.*/

Open in Playground

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

foo.__defineGetter__(bar, baz);

const { __defineGetter__ } = qux();

({ __defineGetter__ }) => {};

Open in Playground

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

require.resolve('foo');

Open in Playground

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

myArray.push(5);

Examples of correct code for this rule:

Open in Playground

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

const example = disallowedObjectName.somePropertyName;

allowedObjectName.disallowedPropertyName();

Open in Playground

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

require('foo');

Open in Playground

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

router.push('/home');
history.push('/about');

When Not To Use It

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

Version

This rule was introduced in ESLint v3.5.0.

Resources