Options
All
  • Public
  • Public/Protected
  • All
Menu

logo

ts-toolbelt

Get the most out of TypeScript


๐Ÿ“– Read Docs ยท ๐ŸŽฎ View Demo ยท ๐Ÿž Report Bug ยท ๐Ÿฉ Request Feature ยท ๐Ÿค” Ask Questions

Support Me Join Tidelift Fund an Issue

Table of Contents

๐Ÿ“œ About

If your goal is to avoid bugs by writing quality types, this library is made for you.


ts-toolbelt is a type library that provides simple ways to update, change, and compute TypeScript types.

With its programmatic API, you can write type-safe software more easily and in less time than you do today.

It brings new capabilities to TypeScript with +200 tested type utilities. This makes it the largest, and 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.

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

Goals

  • Answer the question to "How do I do this in TypeScript?"
  • Provide a lodash-like programmatic API for the type system
  • Promote type evolution & reusability within your codebase
  • Computed types are always readable, like if you typed it
  • Software that is more type-safe, flexible, and robust
  • Bring a whole new set of extra features to TypeScript
  • This package aims to be the home of all utility types
  • High performance, so it will not bloat TS (~ +2sec, +50MB)

๐Ÿฉ Features

Here's some of the most useful features:

Object List Function Any
Exclude Append NoInfer Promisable
Filter Drop Promisify
MergeUp Flatten
NonNullable Concat
Nullable Pop
Optional Reverse
P/Update Tail
PathUp
Required
Select
Update
Writable

TIP Add something to this list

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

{
  "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.MergeUp<{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 โคข

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 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, List, Number, Object, String, Union} from 'ts-toolbelt'
  • Compact

    import {A, B, C, F, I, N, O, S, L, 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 will find some extra resources for your learning, and understanding.

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

๐Ÿ“ฃ Announcements โคข

Stay up to date with the latest announcements with this regular digest of important changes.

๐ŸŽ 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

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

๐Ÿ’‰ 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
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 (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, and then fund it.

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


๐Ÿ”ฎ 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:

๐Ÿ’Ÿ Friendly Projects

  • eledoc - ๐ŸŒ’ A material dark theme for TypeDoc
  • utility-types - Collection of utility types, complementing TypeScript built-in mapped types and aliases
  • Inherited
  • Protected
  • Private
  • Static
  • Module
  • Object
  • Property
  • Function
  • Variable
  • Index
  • Type
  • Class
  • Interface
  • Enum
  • Constructor
  • Getter/Setter
Made with โค๏ธ by pirix-gh. Documentation generated by TypeDoc.