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

TypeScript's largest utility library

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

About

ts-toolbelt is the largest, and most tested type library available right now, featuring +200 utilities. Our type collection packages some of the most advanced mapped types, conditional types, and recursive types on the market.

Spend less time, build stronger. Benefit from a wide range of generic type functions to achieve better type safety.

We work just like lodash, or ramda, but applied to the type system. Our mission is to provide you with simple ways to compute, change, and create types. We abstract all those complex type checks away for you. We provide a simple, reusable, and standard API to help you get more done with TypeScript.

ts-toolbelt is a well organized package that can help you perform advanced operations on object types, union types, as well as function, and literal types. It is carefully and coherently designed for building robust, flexible, and type-safe software.

We are a community and a knowledge base. Everyone is welcome to ask questions about types. If you are stuck or you misunderstand something, you came to the right place!. We welcome beginners and advanced developers to come take part. Welcome!

Getting Started

Prerequisites

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

    // this is the lowest supported standard library
    "lib": ["es2015"],
  }
}

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}

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.

Utility Index

ANY	OBJECT	LIST	FUNCTION	STRING	UNION	CLASS	BOOLEAN	NUMBER	OBJECT.P	ITERATION
Await	Assign	Append	AutoPath	At	Diff	Class	And	Absolute	Merge	Iteration
At	AtLeast	Assign	Compose	Join	Exclude	Instance	Not	Add	Omit	IterationOf
Cast	Compulsory	AtLeast	Curry	Length	Filter	Parameters	Or	Greater	Pick	Key
Compute	CompulsoryKeys	Compulsory	Function	Replace	Has		Xor	GreaterEq	Readonly	Next
Contains	Diff	CompulsoryKeys	Length	Split	IntersectOf			IsNegative	Update	Pos
Equals	Either	Concat	NoInfer		Last			IsPositive	Record	Prev
Extends	Exclude	Diff	Parameters		Merge			IsZero
Key	ExcludeKeys	Drop	Pipe		NonNullable			Lower
Keys	Filter	Either	Promisify		Nullable			LowerEq
KnownKeys	FilterKeys	Exclude	Return		Pop			Negate
Is	Has	ExcludeKeys	UnCurry		Replace			Range
Promise	HasPath	Extract	ValidPath		Select			Sub
Try	Includes	Filter			Strict
Type	Intersect	FilterKeys			ListOf
x	IntersectKeys	Flatten
	Invert	Group
	ListOf	Has
	Merge	HasPath
	MergeAll	Head
	Modify	Includes
	NonNullable	Intersect
	NonNullableKeys	IntersectKeys
	Nullable	KeySet
	NullableKeys	Last
	Object	LastKey
	Omit	Length
	Optional	List
	OptionalKeys	Longest
	Overwrite	Merge
	Partial	MergeAll
	Patch	Modify
	PatchAll	NonNullable
	Path	NonNullableKeys
	Paths	Nullable
	Pick	NullableKeys
	Readonly	ObjectOf
	ReadonlyKeys	Omit
	Record	Optional
	Replace	OptionalKeys
	Required	Overwrite
	RequiredKeys	Partial
	Select	Patch
	SelectKeys	PatchAll
	Undefinable	Path
	UndefinableKeys	Paths
	Unionize	Pick
	UnionOf	Pop
	Update	Prepend
	Writable	Readonly
	WritableKeys	ReadonlyKeys
		Remove
		Repeat
		Replace
		Required
		RequiredKeys
		Reverse
		Select
		SelectKeys
		Shortest
		Tail
		Take
		Undefinable
		UndefinableKeys
		Unionize
		UnionOf
		UnNest
		Update
		Writable
		WritableKeys
		Zip
		ZipObj

Archives ⤢

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

Compatibility

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

ts-toolbelt	typescript
9.x.x	^4.1.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

Name	Intro
eledoc	🌒 A material dark theme for TypeDoc.
material-candy	🍬 A vscode theme to uplift your mood, stay happy and focused.
utility-types	Collection of utility types, complementing TypeScript built-in mapped types and aliases.

License