JSPM

ts-toolbelt

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

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

Table of Contents

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

📜 About

ts-toolbelt brings new capabilities to TypeScript with a collection of more than 200 tested types. This makes it the largest, and most reliable type collection out there. On a higher level, it abstracts the complexity & knowledge you would need to properly type your software - you can stay focused.

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

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

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:

• Merge two types together
• Update the field of a type
• Make some fields optional
• Change a type at any depth!
• Concat two tuples together
• Get the last item of a tuple
• ... and so much more

TIP 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 v3.5

npm install typescript@^3.6.0 --save-dev

For best results, add this to your tsconfig.json

// Optional, recommended
{
  "compilerOptions": {
    // ...
    "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.MergeUp<{name: string}, {age?: number}>

TIP You can also grab the demo over here

📖 Documentation ⤢

The project is organized around TypeScript's main concepts:

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.

Archives ⤢

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

EXAMPLE https://pirix-gh.github.io/ts-toolbelt/4.2.1/

🧠 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

• Help the community with answers on Gitter
• Reporting bugs or requesting new features

Codebase

• Improving existing documentation
• Adding new types to the collection

Pull Requests

1. Read the tutorial

2. Fork the project

3. Clone your fork

4. Create a pr/feature branch

   git checkout -b pr/CoolFeature

5. Commit your changes

   You must follow the conventional commit to be able to commit

   git commit -m 'feat(name): Added this CoolFeature'

6. Run the tests

7. Push your changes

   npm run release -- --no-tags

8. Open a pull request

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 {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:

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.

💼 For enterprise

Available as part of the Tidelift Subscription.

The maintainers of ts-toolbelt and thousands of other packages are working with Tidelift to deliver commercial support and maintenance for the open source dependencies you use to build your applications. Save time, reduce risk, and improve code health, while paying the maintainers of the exact dependencies you use. Learn more.

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

🔮 What's next

• Automated performance tests

  # performance is checked manually with 
  npx tsc --noEmit --extendedDiagnostics

• Need to write the examples

🙏 Acknowledgements

Many, many thanks to all the contributors and:

• André Staltz
• Joe Calzaretta
• Matt McCutchen
• Regev Brody
• Titian C.-Dragomir

💟 Friendly Projects

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