ts-toolbelt

What is ts-toolbelt?

The ts-toolbelt package provides a comprehensive set of type utilities to improve TypeScript typing and enable type transformations, checks, and more complex operations. It enhances TypeScript's static typing capabilities and helps in building more robust type-safe applications.

What are ts-toolbelt's main functionalities?

Object Manipulation

Merge two types into one. This is useful for combining properties from multiple objects into a single type.

{ type Merged = Merge<{name: string}, {age: number}>; // Result: {name: string, age: number} }

Type Checking

Check if two types are equivalent. This utility helps in validating type structures for consistency.

{ type check = Equals<{a: string}, {a: string, b: number}>; // Result: false }

Conditional Types

Apply conditional logic to types. This feature allows for conditional type assignments based on certain conditions.

{ type Conditional = If<true, 'Yes', 'No'>; // Result: 'Yes' }

Other packages similar to ts-toolbelt

utility-types

Provides a collection of utility types for TypeScript, similar to ts-toolbelt. While utility-types focuses more on transformations and mappings, ts-toolbelt offers a broader range of type operations including type checks and advanced manipulations.

type-fest

A package that includes a variety of utility types for TypeScript. Type-fest is similar to ts-toolbelt but tends to be simpler and more focused on everyday use cases, whereas ts-toolbelt provides more comprehensive and complex utilities for advanced type manipulation.

README

ts-toolbelt

👷 Higher type safety 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
• 👏 Sponsoring issues
• 💉 Running tests
• 🔧 Compatibility
• 🔮 What's next
• 🙏 Acknowledgments

📜 About

ts-toolbelt is a collection of types that makes TypeScript even safer. 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.

ts-toolbelt completes TypeScript with a collection of more than 150 tested types.

Goals

• This package aims to be the home of all utility types
• Keep reasonable performance, so it will not bloat TS
• Computed types are always readable, like if you typed it
• 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!

🍩 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

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

🏁 Getting Started

Prerequisites

npm install typescript@^3.5.0 --save

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:

A(ny)	C(lass)	I(teration)	O(bject)	T(uple)
B(boolean)	F(unction)	N(umber)	S(tring)	U(nion)

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 will find more extra resources for your leaning & understanding.

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

   git commit -m 'Added this CoolFeature'
   

6. Run the tests
7. Commit your changes

   git push origin pr/CoolFeature
   

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

🔧 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

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

• André Staltz
• Joe Calzaretta
• Matt McCutchen

💟 Friendly Projects