Needlessly Promiscuous, Modularize!
    Have ideas to improve npm?Join in the discussion! »

    ts-toolbelt
    TypeScript icon, indicating that this package has built-in type declarations

    9.6.0 • Public • Published

    banner

    TypeScript's largest utility library

    Language grade: JavaScript

    📖 Documentation · 📣 Announcements · 🐞 Report Bug · 🍩 Request Feature · 🤔 Ask Questions

    About

    ts-toolbelt is the largest, and most tested type library available right now, featuring +200 utilities. Our type collection packages some of the most advanced mapped types, conditional types, and recursive types on the market.

    Spend less time, build stronger. Benefit from a wide range of generic type functions to achieve better type safety.

    We work just like lodash, or ramda, but applied to the type system. Our mission is to provide you with simple ways to compute, change, and create types. We abstract all those complex type checks away for you. We provide a simple, reusable, and standard API to help you get more done with TypeScript.

    ts-toolbelt is a well organized package that can help you perform advanced operations on object types, union types, as well as function, and literal types. It is carefully and coherently designed for building robust, flexible, and type-safe software.

    demo

    We are a community and a knowledge base. Everyone is welcome to ask questions about types. If you are stuck or you misunderstand something, you came to the right place!. We welcome beginners and advanced developers to come take part. Welcome!

    Getting Started

    Prerequisites

    npm install typescript@^4.1.0 --save-dev

    For best results, add this to your tsconfig.json

    {
      "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"],
      }
    }

    Installation

    npm install ts-toolbelt --save

    Hello World

    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}

    You can level-up, and re-code this library from scratch.

    Documentation ⤢

    Imports

    The project is organized around TypeScript's main concepts:

    Any Boolean Class Function Iteration List
    Number Object Object.P String Union Test

    TIP How to choose categories? Match your type with them.

    There are many ways to import the types into your project:

    • Explicit

      import {Any, Boolean, Class, Function, Iteration, List, Number, Object, String, Union} from "ts-toolbelt"
    • Compact

      import {A, B, C, F, I, L, N, O, S, U} from "ts-toolbelt"
    • Portable

      import tb from "ts-toolbelt"

    You can also import our non-official API from the community:

    import {Community} from "ts-toolbelt"

    TIP The community API is for our community to publish useful types that don't see fit in the standard API.

    Utility Index

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

    Archives ⤢

    EXAMPLE https://millsp.github.io/ts-toolbelt/4.2.1/

    Good to Know ⤢

    In this wiki, you will find some extra resources for your learning, and understanding.

    Are you missing something? Participate to the open-wiki by posting your questions.

    Running tests

    For this project

    To run the lint & type tests, simply run:

    npm test

    For your project

    Want to test your own types? Let's get started:

    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>(),
    ])

    TIP Place it in a file that won't be executed, it's just for TypeScript to test types.

    Continuous Integration

    The releases are done with Travis CI in stages & whenever a branch or PR is pushed:

    • Tests are run with npm test
    • Tests against DefinitelyTyped
    • Releases to npm@[branch-name]

    Compatibility

    The project is maintained to adapt to the constant changes of TypeScript:

    ts-toolbelt typescript
    9.x.x ^4.1.x

    Major version numbers will upgrade whenever TypeScript had breaking changes.

    Otherwise, the release versions will naturally follow the semantic versioning.

    What's next

    • Automated performance tests

      # performance is checked manually with 
      npx tsc --noEmit --extendedDiagnostics
    • Need to write more examples

    Related Projects

    Name Intro
    eledoc 🌒 A material dark theme for TypeDoc.
    material-candy 🍬 A vscode theme to uplift your mood, stay happy and focused.
    utility-types Collection of utility types, complementing TypeScript built-in mapped types and aliases.

    License

    FOSSA Status

    Install

    npm i ts-toolbelt

    DownloadsWeekly Downloads

    542,891

    Version

    9.6.0

    License

    Apache-2.0

    Unpacked Size

    248 kB

    Total Files

    246

    Last publish

    Collaborators

    • avatar