ts-toolbelt

👷 All the types you need for TypeScript
Explore the docs »

🎮 View Demo · 🐞 Report Bug · 🍩 Request Feature · 🤔 Ask Questions

Get Professional Support

📜 About
🍩 Features
🏁 Getting started
📖 Documentation
🧠 Good to know
🎁 Contributing
👏 Sponsoring issues
💉 Running tests
🔧 Compatibility
🔮 What's next
🙏 Acknowledgements

📜 About

ts-toolbelt completes TypeScript with a collection of more than 175 tested types. This makes it the biggest type collection out there.

It's goal is to improve type correctness while adding a whole new set of features to TypeScript. It uses the type system itself for TypeScript to compute more complex types. In other words, its API exposes types that trade CPU & RAM for higher type safety.

Goals

Answer the question to "How do I do this in TypeScript?"
Software that's more type-safe, flexible & more robust
Bring a whole new set of extra features to TypeScript
Types can be combined together to create new ones!
This package aims to be the home of all utility types
Computed types are always readable, like if you typed it
High performance, so it will not bloat TS (~ +2sec, +50MB)

🍩 Features

Here's some of the most useful features:

If you don't find the type you are looking for, you are welcome to open a feature request!

🏁 Getting Started

Prerequisites

Lowest TypeScript support starts at version 3.5

npm install typescript@^3.5.0 --save

For best results, add this to your tsconfig.json

// Optional, recommended
{
  "compilerOptions": {
    // ...
    "strict": true
  }
}

Installation

npm install ts-toolbelt --save

Hello World

import {A, B, C, F, I, N, O, S, T, U} from 'ts-toolbelt'
// Wonder what these letters mean? Check the docs below

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

📖 Documentation ⤢

The project is organized around TypeScript's main concepts:


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

TIP match the type kind you need to operate on with the above categories

The documentation is complete but needs more examples. So feel free to ask for examples, and I will update the docs.

Imports

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

Explicit

import {Any, Boolean, Class, Function, Iteration, Number, Object, String, Tuple, Union} from 'ts-toolbelt'

Compact

import {A, B, C, F, I, N, O, S, T, U} from 'ts-toolbelt'

Portable
```
import tb from 'ts-toolbelt'
```

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.

🧠 Good to Know ⤢

In this wiki, you'll find some extra resources for your learning & understanding.

It is incremental and it will be completed on demand, you can ask for this below.

Questions ⤢

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

🎁 Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated. There are many ways to contribute to the project:

Community

Codebase

Improving existing documentation
Adding new types to the collection

Pull Requests

Read the tutorial
Fork the project
Clone your fork
Create a pr/feature branch
```
git checkout -b pr/CoolFeature
```
Commit your changes

You must follow the conventional commit to be able to commit
```
git commit -m 'feat(name): Added this CoolFeature'
```
Run the tests
Push your changes
```
git push origin pr/CoolFeature
```
Open a pull request

👏 Sponsoring issues

Sponsored issues have higher priority over non-critical issues.

You can either request a new feature or a bug fix then fund it.

The money will be transparently split with an issue's assignees.

💉 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 {A, B, C, F, I, N, O, S, T, U, Test} from 'ts-toolbelt'

const {checks, check} = Test

checks([
    check<N.Plus<'1', '30'>, '31', Test.Pass>(),
    check<N.Plus<'5', '-3'>, '2',  Test.Pass>(),
])

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
1.x.x	~3.5.x
2.x.x	^3.5.x
3.x.x	^3.5.x
4.x.x	^3.5.x

Major version numbers will upgrade whenever TypeScript had breaking changes (it happened that TS had breaking changes on minor versions). 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

Improve with user feedback
Need to write the examples

🙏 Acknowledgements

Many, many thanks to all the contributors and:

💟 Friendly Projects

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