TypeScript Type Toolbelt

Common errors

• TS2589: Type instantiation is excessively deep and possibly infinite.

  cause Using overly complex or recursive type definitions, often when combining multiple ts-toolbelt utilities, can exceed TypeScript's type instantiation depth limit.
  fix Refactor your type logic to be less deeply nested or recursive. Break down large type transformations into smaller, intermediate types. Consider if the complexity is truly necessary.

• TS2307: Cannot find module 'ts-toolbelt' or its corresponding type declarations.

  cause The ts-toolbelt package is not installed, or your TypeScript configuration cannot find its declaration files (`.d.ts`).
  fix Run `npm install ts-toolbelt --save-dev` (or `--save`) and ensure your `tsconfig.json` correctly includes `node_modules` (usually default) and has a compatible `target` and `module`.

• TS2339: Property 'Merge' does not exist on type 'typeof import("ts-toolbelt")'. Did you mean 'Object'?

  cause Attempting to import a specific utility type (like `Merge`) directly from the top-level `ts-toolbelt` package instead of from its designated namespace (e.g., `Object`).
  fix Import the relevant namespace first, then access the utility. For example, use `import { Object } from 'ts-toolbelt'; type Merged = Object.Merge<...>;` or `import { O } from 'ts-toolbelt'; type Merged = O.Merge<...>;`.

Warnings

• breaking ts-toolbelt's major versions often align with breaking changes in TypeScript. For ts-toolbelt 9.x.x, TypeScript 4.1.0 or higher is required. Using an older TypeScript version can lead to compilation errors or incorrect type inference.
  Fix: Ensure your project's `typescript` dev dependency is `^4.1.0` or newer. Update your `tsconfig.json` to specify `"typescript": "^4.1.0"` if using `npm install typescript@latest`.
• gotcha Many advanced utilities in ts-toolbelt rely on TypeScript's strict mode, particularly `strictNullChecks: true`. Without it, certain types may behave unexpectedly or lead to less precise results.
  Fix: Add `"strictNullChecks": true` and `"strict": true` to your `tsconfig.json` under `compilerOptions` for optimal type safety and compatibility.
• gotcha When working with complex or deeply recursive type manipulations, TypeScript may report `Type instantiation is excessively deep and possibly infinite` errors (TS2589). This indicates that the compiler cannot resolve the type within its internal recursion limits.
  Fix: Simplify your type definitions where possible, break down complex types into smaller, more manageable ones, or try to reduce the depth of recursive structures. Occasionally, increasing TypeScript's recursion limit via `"--declarationDepth N"` (though not a standard `tsconfig` option) or specific compiler flags might help, but often points to an overly complex type definition.
• gotcha Do not attempt to `require()` ts-toolbelt or its modules in CommonJS environments. ts-toolbelt consists purely of TypeScript types and has no runtime JavaScript output. Attempting `const { O } = require('ts-toolbelt');` will result in a runtime error or `undefined`.
  Fix: Always use TypeScript's `import` syntax (`import { O } from 'ts-toolbelt';` or `import type { O } from 'ts-toolbelt';`) as ts-toolbelt is a type-only library.

Install

• npm install ts-toolbelt npm
• yarn add ts-toolbelt yarn
• pnpm add ts-toolbelt pnpm

Imports

• Object.Merge
  wrong:

  import { Merge } from 'ts-toolbelt';

  correct:

  import { Object } from 'ts-toolbelt';
  type MergedType = Object.Merge<{ a: string }, { b: number }>;

  Types are organized into namespaces (e.g., `Object`, `List`, `Union`). Import the namespace itself, then access the utility. Explicit `import type` is good practice, though TypeScript often infers correctly.
• O.Merge
  wrong:

  const O = require('ts-toolbelt').O;

  correct:

  import { O } from 'ts-toolbelt';
  type MergedType = O.Merge<{ a: string }, { b: number }>;

  For brevity, common namespaces have single-letter aliases (e.g., `O` for `Object`, `L` for `List`). The library exports only types, so `require()` is fundamentally incorrect for runtime usage.
• U.Exclude
  wrong:

  import type { Exclude } from 'ts-toolbelt';

  correct:

  import { U } from 'ts-toolbelt';
  type MyUnion = 'a' | 'b' | 'c';
  type ExcludedUnion = U.Exclude<MyUnion, 'b'>;

  TypeScript's built-in `Exclude<T, U>` exists, but `ts-toolbelt` offers its own, often more powerful or specific, version under its namespaces. Always use the prefixed version (e.g., `U.Exclude`).

Quickstart

Demonstrates installation, recommended TypeScript compiler options, and basic usage of object, list, and union type utilities.

npm install ts-toolbelt --save-dev
# For best results, ensure tsconfig.json includes:
# {
#   "compilerOptions": {
#     "strictNullChecks": true,
#     "strict": true,
#     "lib": ["es2015"]
#   }
# }

import { O, L, U } from 'ts-toolbelt';

// 1. Merge two object types, handling optional properties gracefully
type User = { id: string; name?: string; };
type Address = { street: string; zip: number; };
type MergedUserAddress = O.Merge<User, Address>;
// Expected: { id: string; name?: string; street: string; zip: number; }

// 2. Append an element to a tuple type
type MyTuple = [1, 2];
type AppendedTuple = L.Append<MyTuple, 3>;
// Expected: [1, 2, 3]

// 3. Exclude types from a union
type EventStatus = 'pending' | 'success' | 'failed' | 'cancelled';
type ActiveStatus = U.Exclude<EventStatus, 'failed' | 'cancelled'>;
// Expected: 'pending' | 'success'

interface Config {
  theme: 'dark' | 'light';
  version: number;
  options?: { debug: boolean; };
}

// 4. Update a nested property (requires Object.Path and Object.Update)
import { Object } from 'ts-toolbelt';
type UpdatedConfig = Object.Update<Config, ['options', 'debug'], true>;
// Expected: { theme: 'dark' | 'light'; version: number; options?: { debug: true; }; }