ts-toolbelt

library9.6.0jsnpmunverified

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.

type-stubs

npm install ts-toolbelt

github ↗package ↗

INSTALL

IMPORT

SIG · TS-TOOLBELT

ts-toolbelt

type-stubsjavascriptv9.6.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Object.Merge

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

✗ import { Merge } from 'ts-toolbelt';

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

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

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

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

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

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

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`).

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; }; }

Debug

Known issues

breakingts-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`.

affects: >=9.0.0

gotchaMany 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.

affects: >=1.0.0

gotchaWhen 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.

affects: >=1.0.0

gotchaDo 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.

affects: >=1.0.0

Errors

Common errors & fixes

TS2589: Type instantiation is excessively deep and possibly infinite.

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.

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'?

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<...>;`.

Upgrade

Version history

9.6.0latest on npm

Audit

Dependencies

typescriptrequiredRequired for type-checking and library functionality during development. ts-toolbelt 9.x.x requires TypeScript v4.1.0 or newer.

Agent activity

25 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/millsp/ts-toolbelt ↗

packagehttps://www.npmjs.com/package/ts-toolbelt ↗