{"id":12188,"library":"ts-toolbelt","title":"TypeScript Type Toolbelt","description":"ts-toolbelt is a comprehensive collection of over 200 advanced type utilities for TypeScript, serving as a 'Lodash for types'. It enables complex type computations, transformations, and creations, abstracting away intricate conditional, mapped, and recursive type definitions. Currently at version 9.6.0, the library maintains an active development pace with releases tied to TypeScript's breaking changes, adhering to semantic versioning. Its key differentiators include an extensive suite of rigorously tested utilities, robust design for manipulating object, union, function, and literal types, and a commitment to providing a standardized API for enhancing type safety in large-scale TypeScript projects. It aims to improve type correctness and introduce new features to the TypeScript type system itself, trading compilation CPU/RAM for higher type safety.","status":"active","version":"9.6.0","language":"javascript","source_language":"en","source_url":"https://github.com/millsp/ts-toolbelt","tags":["javascript","safe","tools","types","typesafe","typescript"],"install":[{"cmd":"npm install ts-toolbelt","lang":"bash","label":"npm"},{"cmd":"yarn add ts-toolbelt","lang":"bash","label":"yarn"},{"cmd":"pnpm add ts-toolbelt","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for type-checking and library functionality during development. ts-toolbelt 9.x.x requires TypeScript v4.1.0 or newer.","package":"typescript","optional":false}],"imports":[{"note":"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.","wrong":"import { Merge } from 'ts-toolbelt';","symbol":"Object.Merge","correct":"import { Object } from 'ts-toolbelt';\ntype MergedType = Object.Merge<{ a: string }, { b: number }>;"},{"note":"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.","wrong":"const O = require('ts-toolbelt').O;","symbol":"O.Merge","correct":"import { O } from 'ts-toolbelt';\ntype MergedType = O.Merge<{ a: string }, { b: number }>;"},{"note":"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`).","wrong":"import type { Exclude } from 'ts-toolbelt';","symbol":"U.Exclude","correct":"import { U } from 'ts-toolbelt';\ntype MyUnion = 'a' | 'b' | 'c';\ntype ExcludedUnion = U.Exclude<MyUnion, 'b'>;"}],"quickstart":{"code":"npm install ts-toolbelt --save-dev\n# For best results, ensure tsconfig.json includes:\n# {\n#   \"compilerOptions\": {\n#     \"strictNullChecks\": true,\n#     \"strict\": true,\n#     \"lib\": [\"es2015\"]\n#   }\n# }\n\nimport { O, L, U } from 'ts-toolbelt';\n\n// 1. Merge two object types, handling optional properties gracefully\ntype User = { id: string; name?: string; };\ntype Address = { street: string; zip: number; };\ntype MergedUserAddress = O.Merge<User, Address>;\n// Expected: { id: string; name?: string; street: string; zip: number; }\n\n// 2. Append an element to a tuple type\ntype MyTuple = [1, 2];\ntype AppendedTuple = L.Append<MyTuple, 3>;\n// Expected: [1, 2, 3]\n\n// 3. Exclude types from a union\ntype EventStatus = 'pending' | 'success' | 'failed' | 'cancelled';\ntype ActiveStatus = U.Exclude<EventStatus, 'failed' | 'cancelled'>;\n// Expected: 'pending' | 'success'\n\ninterface Config {\n  theme: 'dark' | 'light';\n  version: number;\n  options?: { debug: boolean; };\n}\n\n// 4. Update a nested property (requires Object.Path and Object.Update)\nimport { Object } from 'ts-toolbelt';\ntype UpdatedConfig = Object.Update<Config, ['options', 'debug'], true>;\n// Expected: { theme: 'dark' | 'light'; version: number; options?: { debug: true; }; }","lang":"typescript","description":"Demonstrates installation, recommended TypeScript compiler options, and basic usage of object, list, and union type utilities."},"warnings":[{"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`.","message":"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.","severity":"breaking","affected_versions":">=9.0.0"},{"fix":"Add `\"strictNullChecks\": true` and `\"strict\": true` to your `tsconfig.json` under `compilerOptions` for optimal type safety and compatibility.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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`.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"Using overly complex or recursive type definitions, often when combining multiple ts-toolbelt utilities, can exceed TypeScript's type instantiation depth limit.","error":"TS2589: Type instantiation is excessively deep and possibly infinite."},{"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`.","cause":"The ts-toolbelt package is not installed, or your TypeScript configuration cannot find its declaration files (`.d.ts`).","error":"TS2307: Cannot find module 'ts-toolbelt' or its corresponding type declarations."},{"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<...>;`.","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`).","error":"TS2339: Property 'Merge' does not exist on type 'typeof import(\"ts-toolbelt\")'. Did you mean 'Object'?"}],"ecosystem":"npm"}