DOCSEARCHbyAlgolia
Submit Docs

ts-toolbelt

repository·master·Indexed 27 days ago

https://github.com/millsp/ts-toolbelt

A large-scale TypeScript utility library providing over 200 advanced type functions for object, union, function, and literal types. It simplifies complex type computations involving mapped, conditional, and recursive types, offering categorized namespaces such as Object, List, Union, and Number. Version 9.6.0 supports TypeScript ^4.1.x.

Tokens
1.7K
Snippets
4
Records
8
Agent score
43%

What's inside ts-toolbelt

  1. Configure TypeScript for ts-toolbelt

    master

    To ensure compatibility and best results with ts-toolbelt, configure your tsconfig.json with the following settings:

    • strictNullChecks: Highly recommended (required by some utilities).
    • strict: Optional, but recommended to enable whenever possible.
    • lib: Must include at least ["es2015"].
    {
  "compilerOptions": {
    // highly recommended (required by few utilities)
    "strictNullChecks": true,

    // this is optional, but enable whenever possible
    "strict": true,

    // this is the lowest supported standard library
    "lib": ["es2015"],
  }
}

  3. Import ts-toolbelt utilities

    master

    The project is organized into categories based on TypeScript concepts. You can import utilities using several patterns:

    • Explicit: Import specific named utilities.
    • Compact: Use single-letter aliases for a more concise syntax.
    • Portable: Import the entire library as a single namespace object.
    • Community API: Access non-official utilities published by the community via the Community export.

  4. Use ts-toolbelt utilities

    master

    Import specific utility namespaces (like Object) from ts-toolbelt to perform advanced type operations. Common tasks include merging objects or making specific fields optional.

    import {Object} from "ts-toolbelt"
// Check the docs below for more

// Merge two `object` together
type merge = Object.Merge<{name: string}, {age?: number}>
// {name: string, age?: number}

// Make a field of an `object` optional
type optional = Object.Optional<{id: number, name: string}, "name">
// {id: number, name?: string}

  5. Test your own types with Test utility

    master

    You can verify your type logic using the Test utility from ts-toolbelt. Use Test.checks to run a collection of type assertions. Each assertion is created using Test.check<ActualType, ExpectedType, ResultType>().

    Note: Place these tests in a file that is not executed at runtime (e.g., a .ts file used only for type checking), as they are designed for TypeScript's type system rather than runtime execution.

    import {Number, Test} from "ts-toolbelt"

const {checks, check} = Test

checks([
    check<Number.Add<1, 30>, 31, Test.Pass>(),
    check<Number.Add<5, -3>, 2,  Test.Pass>(),
])

  6. Reference the ts-toolbelt utility index

    master

    Utilities are categorized by the TypeScript type they operate on. Use these categories to find the appropriate tool for your type manipulation needs:

    CategoryUtilities
    AnyAwait, At, Cast, Compute, Contains, Equals, Extends, Key, Keys, KnownKeys, Is, Promise, Try, Type, x
    BooleanAnd, Not, Or, Xor
    ClassClass, Instance, Parameters
    FunctionAutoPath, Compose, Curry, Exact, Function, Length, Narrow, NoInfer, Parameters, Pipe, Promisify, Return, UnCurry, ValidPath
    IterationIteration, IterationOf, Key, Next, Pos, Prev
    ListAppend, Assign, AtLeast, Compulsory, CompulsoryKeys, Concat, Diff, Drop, Either, Exclude, ExcludeKeys, Extract, Filter, FilterKeys, Flatten, Group, Has, HasPath, Head, Includes, Intersect, IntersectKeys, KeySet, Last, LastKey, Length, List, Longest, Merge, MergeAll, Modify, NonNullable, NonNullableKeys, Nullable, NullableKeys, ObjectOf, Omit, Optional, OptionalKeys, Overwrite, Partial, Patch, PatchAll, Path, Paths, Pick, Pop, Prepend, Readonly, ReadonlyKeys, Remove, Repeat, Replace, Required, RequiredKeys, Reverse, Select, SelectKeys, Shortest, Tail, Take, Undefinable, UndefinableKeys, Unionize, UnionOf, UnNest, Update, Writable, WritableKeys, Zip, ZipObj
    NumberAbsolute, Add, Greater, GreaterEq, IsNegative, IsPositive, IsZero, Lower, LowerEq, Negate, Range, Sub
    ObjectAssign, AtLeast, Compulsory, CompulsoryKeys, Diff, Either, Exclude, ExcludeKeys, Filter, FilterKeys, Has, HasPath, Includes, Intersect, IntersectKeys, Invert, ListOf, Merge, MergeAll, Modify, NonNullable, NonNullableKeys, Nullable, NullableKeys, Object, Omit, Optional, OptionalKeys, Overwrite, Partial, Patch, PatchAll, Path, Paths, Pick, Readonly, ReadonlyKeys, Record, Replace, Required, RequiredKeys, Select, SelectKeys, Undefinable, UndefinableKeys, Unionize, UnionOf, Update, Writable, WritableKeys
    Object.PMerge, Omit, Pick, Readonly, Record, Update
    StringAt, Join, Length, Replace, Split
    UnionDiff, Exclude, Filter, Has, IntersectOf, Last, Merge, NonNullable, Nullable, Pop, Replace, Select, Strict, ListOf

  7. Check compatibility with TypeScript

    master

    The ts-toolbelt project is maintained to stay compatible with TypeScript updates. Major version changes in ts-toolbelt typically coincide with breaking changes in TypeScript.

    For ts-toolbelt version 9.x.x, the supported TypeScript version is ^4.1.x.

  8. Reference the ts-toolbelt namespace map

    master

    The following namespaces are exported by the main entrypoint. Use these to access categorized utility types and functions:

    • Any / A: Any-related utilities
    • Boolean / B: Boolean-related utilities
    • Class / C: Class-related utilities
    • Community: Community-contributed utilities
    • Function / F: Function-related utilities
    • Iteration / I: Iteration-related utilities
    • List / L / Tuple / T: List and Tuple-related utilities
    • Misc / M: Miscellaneous utilities
    • Number / N: Number-related utilities
    • Object / O: Object-related utilities
    • String / S: String-related utilities
    • Union / U: Union-related utilities