Skip to main content

consistent-type-assertions

Enforce consistent usage of type assertions.

🎨

Extending "plugin:@typescript-eslint/stylistic" in an ESLint configuration enables this rule.

🔧

Some problems reported by this rule are automatically fixable by the --fix ESLint command line option.

💡

Some problems reported by this rule are manually fixable by editor suggestions.

TypeScript provides two syntaxes for "type assertions":

  • Angle brackets: <Type>value
  • As: value as Type

This rule aims to standardize the use of type assertion style across the codebase. Keeping to one syntax consistently helps with code readability.

note

Type assertions are also commonly referred as "type casting" in TypeScript. However, that term is technically slightly different to what is understood by type casting in other languages. Type assertions are a way to say to the TypeScript compiler, "I know better than you, it's actually this different type!".

const assertions are always allowed by this rule. Examples of them include let x = "hello" as const; and let x = <const>"hello";.

.eslintrc.cjs
module.exports = {
  "rules": {
    "@typescript-eslint/consistent-type-assertions": "error"
  }
};

Try this rule in the playground ↗

Options​

This rule accepts the following options:

type Options = [
  | {
      /** The expected assertion style to enforce. */
      assertionStyle:
        | 'angle-bracket'
        /** The expected assertion style to enforce. */
        | 'as';
      /** Whether to always prefer type declarations for object literals used as variable initializers, rather than type assertions. */
      objectLiteralTypeAssertions?:
        | 'allow-as-parameter'
        | 'never'
        /** Whether to always prefer type declarations for object literals used as variable initializers, rather than type assertions. */
        | 'allow';
    }
  | {
      /** The expected assertion style to enforce. */
      assertionStyle: /** The expected assertion style to enforce. */
      'never';
    },
];

const defaultOptions: Options = [
  { assertionStyle: 'as', objectLiteralTypeAssertions: 'allow' },
];

assertionStyle​

The expected assertion style to enforce. Valid values for assertionStyle are:

  • as will enforce that you always use ... as foo.
  • angle-bracket will enforce that you always use <foo>...
  • never will enforce that you do not do any type assertions.

Most codebases will want to enforce not using angle-bracket style because it conflicts with JSX syntax, and is confusing when paired with generic syntax.

Some codebases like to go for an extra level of type safety, and ban assertions altogether via the never option.

objectLiteralTypeAssertions​

Whether to always prefer type declarations for object literals used as variable initializers, rather than type assertions.

For example, this would prefer const x: T = { ... }; to const x = { ... } as T; (or similar with angle brackets). The type assertion in the latter case is either unnecessary or will probably hide an error.

The compiler will warn for excess properties with this syntax, but not missing required fields. For example: const x: { foo: number } = {}; will fail to compile, but const x = {} as { foo: number } will succeed.

The const assertion const x = { foo: 1 } as const, introduced in TypeScript 3.4, is considered beneficial and is ignored by this option.

Assertions to any are also ignored by this option.

Examples of code for { assertionStyle: 'as', objectLiteralTypeAssertions: 'never' }:

const x = { foo: 1 } as T;

function bar() {
  return { foo: 1 } as T;
}
Open in Playground

Examples of code for { assertionStyle: 'as', objectLiteralTypeAssertions: 'allow-as-parameter' }:

const x = { foo: 1 } as T;

function bar() {
  return { foo: 1 } as T;
}
Open in Playground

When Not To Use It​

If you do not want to enforce consistent type assertions.

However, keep in mind that inconsistent style can harm readability in a project. We recommend picking a single option for this rule that works best for your project.

Resources​