skip to content

In typescript-eslint, why does the @typescript-eslint/no-floating-promises rule need type information, and how do you enable typed linting in a flat config?

level: middleimportance: must knowfreq 22%

answer

  1. a call looks the same either way
  2. the return type may live elsewhere
  3. only the type checker knows
  4. swap to the TypeChecked preset
  5. parserOptions.projectService: true

basics

~20 s

Whether a call like saveRefill(order) returns a Promise depends on its declared type, often in another file, which only TypeScript's checker knows. Use recommendedTypeChecked and set parserOptions.projectService to true so the parser asks TypeScript for each file's types.

solid answer

~40 s

`@typescript-eslint/no-floating-promises` reports a Promise-valued statement nobody handles: not awaited, not returned, no one-argument `.catch()`, no two-argument `.then()`, not marked with `void`. The statement `saveRefill(order);` looks like any other call; only the declared return type of `saveRefill`, which may live in another module or a library's `.d.ts`, says it is a Promise, and only TypeScript's type checker can resolve that. The compiler accepts the line, because an unawaited Promise is legal TypeScript. To give the rule types, make two changes: replace `tseslint.configs.recommended` with `tseslint.configs.recommendedTypeChecked`, which contains all of `recommended` plus the typed rules, and set `languageOptions.parserOptions.projectService: true`, which asks TypeScript's project service for each file's types through its nearest `tsconfig.json`. A typed rule enabled without those parser options fails with an error instead of skipping quietly.

code

javascript · 13 lines
javascript
// eslint.config.mjs
import js from '@eslint/js';
import tseslint from 'typescript-eslint';

export default [
  js.configs.recommended,
  ...tseslint.configs.recommendedTypeChecked,
  {
    languageOptions: {
      parserOptions: { projectService: true },
    },
  },
];

go deeper

for a junior

Remember that an unawaited Promise is legal TypeScript, so the compiler stays quiet, and that typescript-eslint's no-floating-promises rule catches it once typed linting is on.

for a middle

Explain why the rule needs the type checker, then name the two changes: the TypeChecked preset and parserOptions.projectService. Know which handling patterns the rule accepts and why void is not error handling.

for a senior

Show the switch in a real repository: the files that suddenly report not found by the project service, the rule failing loudly without parser options, and any values typed as any hiding Promises from the rule.

for a principal

Weigh typed rules as a deliberate purchase: they catch async and unsafe-any bugs the compiler accepts, and they cost a project analysis on every lint run.

## The bug the compiler lets through A prescription-refill portal has a handler like this: ```ts export async function handleRefill(req: RefillRequest): Promise<Response> { const order = buildOrder(req); saveRefill(order); // returns Promise<void>, never awaited return Response.json({ status: 'queued' }); } ``` The handler answers before the write finishes, and if `saveRefill` rejects, nobody handles the rejection. The type check passes, because calling an async function without awaiting it is valid TypeScript. This is exactly the class of bug **typed lint rules** exist for. ## Why syntax alone is not enough - In the syntax tree, `saveRefill(order);` is an expression statement wrapping a call. A `logRefill(order);` that returns nothing has the same shape. - The difference lives in **types**: `saveRefill` is declared `async`, or returns `Promise<void>`, possibly in another module or in a library's declaration file. - Rules in the untyped presets see one file's tree at a time. They cannot follow an import to learn a return type. - Typed rules ask TypeScript's **type checker**, through services the parser provides, what type a node has. For that, TypeScript has to analyse the project, not just the file, which makes typed rules slower and much more powerful. Typed rules also trust the compiler's answer. If `saveRefill` were typed `any` because its declarations were missing, the rule would have no Promise to see. ## Untyped and type-checked presets | Untyped preset | Type-checked version | Typed rules it adds, among others | |---|---|---| | `recommended` | `recommendedTypeChecked` | `no-floating-promises`, `no-misused-promises`, `await-thenable`, the `no-unsafe-*` rules | | `strict` | `strictTypeChecked` | `no-unnecessary-condition`, `no-deprecated` | | `stylistic` | `stylisticTypeChecked` | `prefer-nullish-coalescing`, `prefer-optional-chain` | Each type-checked version **contains its untyped preset**, so you replace one with the other rather than listing both. `strictTypeChecked` also contains `recommendedTypeChecked`, and `stylistic` sits beside `recommended` or `strict` rather than replacing them. ## Turning typed linting on 1. Replace `tseslint.configs.recommended` with `tseslint.configs.recommendedTypeChecked` (and `strict` or `stylistic` with their `TypeChecked` versions, if you use them). 2. Add `languageOptions.parserOptions.projectService: true`, so the parser asks TypeScript's project service for each file's type information, using the `tsconfig.json` nearest to that file. ```js // eslint.config.mjs import js from '@eslint/js'; import tseslint from 'typescript-eslint'; export default [ js.configs.recommended, ...tseslint.configs.recommendedTypeChecked, { languageOptions: { parserOptions: { projectService: true }, }, }, ]; ``` You can also keep the untyped `recommended` preset and switch on only `'@typescript-eslint/no-floating-promises': 'error'`. The rule still needs the same `parserOptions`, so the project still has to be analysed. Expect one follow-up error after the switch: a file that no `tsconfig.json` includes, often the ESLint config file itself, now reports a parsing error saying it was not found by the project service. Including it in a tsconfig, allowing it as a default-project file, or turning typed linting off for it are the fixes. A typed rule left on with **no** parser options at all fails with an error that it requires type information; it never skips quietly. ## Other typed rules the preset brings `recommendedTypeChecked` is more than one rule. The typed rules a team meets first are worth knowing by what they report: - `await-thenable`: awaiting a value that is not a thenable, usually a sign the code expected a Promise. - `no-misused-promises`: a Promise passed where something else is expected (more below). - the **`no-unsafe-*` rules**, such as `no-unsafe-assignment` and `no-unsafe-member-access`: a value typed `any` assigned onward or dereferenced, which is how unchecked data escapes into typed code. - `require-await`: an `async` function that neither awaits nor returns a Promise. - `restrict-template-expressions`: a template literal interpolating something other than a string, such as an object that prints `[object Object]`. - `unbound-method`: a class method detached from its object and called without its expected `this`. ## What the rule accepts as handled The rule stops reporting a Promise statement once it is: - `await`ed, or `return`ed to the caller; - given a rejection handler with `.catch(handler)`, or with the two-argument `.then(onFulfilled, onRejected)`; - marked with `void` (the rule's `ignoreVoid` option) as deliberate fire-and-forget. `void` changes nothing at runtime: the rule's documentation is explicit that a voided rejection is still unhandled, so it is an annotation of intent, not error handling. An array of Promises, such as `orders.map(async (o) => save(o))`, is reported too; combine it with `Promise.all()` or `Promise.allSettled()` and handle the result. `no-floating-promises` only looks at unhandled Promise **statements**. Its companion `no-misused-promises` covers Promises handed to places that expect something else, such as an `if` condition or a callback whose return value is ignored. Both ship in `recommendedTypeChecked`.

  • Is void saveRefill(order); a fix for the floating promise?
    It silences `no-floating-promises` (through its `ignoreVoid` option) but changes nothing at runtime: a rejection is still unhandled. Use `void` only for deliberate fire-and-forget calls whose failures are handled inside the called function; otherwise `await` it or attach a `.catch()` handler.
  • Can you turn on no-floating-promises without adopting the whole type-checked preset?
    Yes. Keep `tseslint.configs.recommended`, set `'@typescript-eslint/no-floating-promises': 'error'` in `rules`, and still set `languageOptions.parserOptions.projectService`. The rule needs type information either way, so you pay for TypeScript analysing the project as soon as typed linting is configured.
  • What does no-misused-promises catch that no-floating-promises does not?
    Promises used where a non-Promise value is expected: an async check in an `if` condition, which is always truthy, or an async function passed as a callback whose return value is ignored, so its rejection floats. `no-floating-promises` only examines unhandled Promise statements.

  • The TypeScript compiler already reports a missing await, so this rule adds nothing.
  • no-floating-promises works under the plain recommended preset with no parser options.
  • Typed rules read types from the current file's annotations, so no tsconfig is involved.
  • Putting void in front of the call handles the rejection.
  • You must list recommended and recommendedTypeChecked together, since the typed preset lacks the basic rules.