TypeScript's largest utility library

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

About

ts-toolbelt ships utility types that provide simple ways to update, change, and compute TypeScript types. It offers unique dynamic features, allowing you to write type-safe software more easily and in less time than you do today.

Its programmatic API brings new capabilities to TypeScript with +200 tested type utilities. This makes it the largest and the most reliable type collection out there. It uses the type system itself for TypeScript to compute complex types. So its API exposes types that trade CPU & RAM for higher type safety.

Goals

• Answer the question to "How can I do this in TypeScript?"
• Provide a programmatic standard API for the type system
• Promote type evolution/reusability within your codebase
• Software that is more type-safe, flexible, and robust
• Bring a whole new set of extra features to TypeScript
• Extensively tested type utilities for maximum type safety
• This package aims to be the home of all utility types
• Answer questions about types and share knowledge

You'll find all the types you can ever need in this single and well organized package.

Getting Started

Prerequisites

Lowest TypeScript support starts at v3.5

npm install typescript@^3.8.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,
  }
}

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}

TIP You can also grab the demo over here.

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.

Internal Docs

If you're interested to learn how the internals work, this tutorial will get you on track to start writing your own types.

Archives ⤢

Access older docs at https://millsp.github.io/ts-toolbelt/version/

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.Plus<"1", "30">, "31", Test.Pass>(),
    check<Number.Plus<"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]

If you wrote tests & would like your project to be tested too, please open an issue.

Compatibility

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

ts-toolbelt	typescript
8.x.x	^4.0.x
6.x.x	^3.7.x
4.x.x	^3.5.x
2.x.x	^3.5.x
3.x.x	^3.5.x
1.x.x	~3.5.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

• eledoc - 🌒 A material dark theme for TypeDoc
• utility-types - Collection of utility types, complementing TypeScript built-in mapped types and aliases

License