Skip to content
Tutorials Center
My learning

Topics

TypeScript Reference ยท Literal and Object Types

TypeScript weak types

Reference for TypeScript weak types: object types whose properties are all optional, the no-overlap error (TS2559), and how to fix it safely.

A weak type is an object type in which every property is optional (and which has at least one property). Typical examples are options objects: { timeout?: number; retries?: number }. Because everything is optional, almost any object would be structurally assignable, including objects that have nothing to do with the options. That makes typos silent.

Weak type detection closes the gap: assigning a value to a weak type is an error unless the value shares at least one property with it. The error is TS2559, "Type X has no properties in common with type Y".

TypeScript
interface Options { timeout?: number; retries?: number }
const ok: Options = { timeout: 100 };

Try it

TypeScript The no-overlap error

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.

TypeScript What is and is not weak

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.

Concepts

The rule

For an assignment S to T, if T is weak and S has properties but none of them occur in T, the compiler rejects the assignment. It also applies to function calls, returns, and comparisons for assignability. It does not apply when S has no properties at all ({}), or when S is any.

What the check is not

It is separate from the excess property check. Excess checks look at fresh object literals and flag any unknown property. Weak type detection looks at any source type, fresh or not, and flags only the complete absence of overlap. A value can pass the weak check yet fail the excess check (a literal { timeout: 1, typo: 2 }).

Where it shows up

Options and config types, partial-update types (Partial<User>), and function-with-properties patterns. Partial<T> always produces a weak type, so passing the wrong object to a patch function is caught.

Usage notes

  • Add a required property if the type should not be weak; an index signature also disables detection.
  • Intersections: Weak & { required: string } is not weak.
  • Union members: each member is considered separately; a union containing a non-weak member is not weak.
  • Disabling: there is no compiler flag; use a type assertion or restructure the types.
  • Callback arguments: because functions have no properties of their own in the relevant sense, passing a function to a weak object type is an error; a function with extra properties may pass if they overlap.
  • Introduced in TypeScript 2.4.