---
id: type-or-value-specifier
title: 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`](#filespecifier): for types or values declared in local files
- [`LibSpecifier`](#libspecifier): for types or values declared in TypeScript's built-in lib definitions
- [`PackageSpecifier`](#packagespecifier): for types or values imported from packages

For example, the following configuration of [`@typescript-eslint/no-floating-promises` > `allowForKnownSafeCalls`](/rules/no-floating-promises#allowforknownsafecalls) marks `node:test`'s `it` as safe using a package specifier:

```json
{
  "@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

```ts
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`:

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

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

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

## LibSpecifier

```ts
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 strings:

```json
{ "from": "lib", "name": "string" }
```

Matching all array-typed values:

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

Matching all `Promise` and `PromiseLike`-typed values:

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

## PackageSpecifier

```ts
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`:

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

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

```json
{ "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

- [`@typescript-eslint/no-floating-promises` > `allowForKnownSafeCalls`](/rules/no-floating-promises#allowforknownsafecalls)
- [`@typescript-eslint/no-floating-promises` > `allowForKnownSafePromises`](/rules/no-floating-promises#allowforknownsafepromises)
- [`@typescript-eslint/only-throw-error` > `allow`](/rules/only-throw-error/#allow)
- [`@typescript-eslint/prefer-readonly-parameter-types` > `allow`](/rules/prefer-readonly-parameter-types/#allow)
