Skip to main content

TypeOrValueSpecifier

Some lint rules include options to describe specific types and/or values. These options use a standardized format exported from the type-utils package, TypeOrValueSpecifier.

TypeOrValueSpecifier allows three object forms of specifiers:

  • FileSpecifier: for types or values declared in local files
  • LibSpecifier: for types or values declared in TypeScript's built-in lib definitions
  • PackageSpecifier: for types or values imported from packages

For example, the following configuration of @typescript-eslint/no-floating-promises > allowForKnownSafeCalls marks node:test's it as safe using a package specifier:

{
  "@typescript-eslint/no-floating-promises": [
    "error",
    {
      "allowForKnownSafeCalls": [
        { "from": "package", "name": "it", "package": "node:test" }
      ]
    }
  ]
}

Each object format requires at least:

  • from: which specifier to use, as 'file' | 'lib' | 'package'
  • name: a string or string[] for type or value name(s) to match on

FileSpecifier​

interface FileSpecifier {
  from: 'file';
  name: string[] | string;
  path?: string;
}

Describes specific types or values declared in local files.

path may be used to specify a file the types or values must be declared in. If omitted, all files will be matched.

FileSpecifier Examples​

Matching all types and values named Props:

{ "from": "file", "name": "Props" }

Matching all types and values named Props in file.tsx:

{ "from": "file", "name": "Props", "path": "file.tsx" }

LibSpecifier​

interface LibSpecifier {
  from: 'lib';
  name: string[] | string;
}

Describes specific types or values declared in TypeScript's built-in lib.*.d.ts ("lib") types.

Lib types include lib.dom.d.ts globals such as Window and lib.es*.ts globals such as Array.

LibSpecifier Examples​

Matching all array-typed values:

{ "from": "lib", "name": "Array" }

Matching all Promise and PromiseLike-typed values:

{ "from": "lib", "name": ["Promise", "PromiseLike"] }

PackageSpecifier​

interface PackageSpecifier {
  from: 'package';
  name: string[] | string;
  package: string;
}

Describes specific types or values imported from packages.

package must be used to specify the package name.

PackageSpecifier Examples​

Matching the SafePromise type from @reduxjs/toolkit:

{ "from": "package", "name": "SafePromise", "package": "@reduxjs/toolkit" }

Matching the describe, it, and test values from vitest:

{ "from": "package", "name": ["describe", "it", "test"], "package": "vitest" }

Universal String Specifiers​

TypeOrValueSpecifier also allows providing a plain string specifier to match all names regardless of declaration source. For example, providing "RegExp" matches all types and values named RegExp.

danger

We strongly recommend not using universal string specifiers. Matching all names without specifying a source file, library, or package can accidentally match other types or values with a coincidentally similar name.

Universal string specifiers will be removed in a future major version of typescript-eslint.

Rule Options Using This Format​