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".
interface Options { timeout?: number; retries?: number } const ok: Options = { timeout: 100 };
Try it
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.
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.