ts-essentials

All essential TypeScript types in one place 🤙

Install

npm install --save-dev ts-essentials

👉 We require typescript>=4.5. If you're looking for support for older TS versions, please have a look at the TypeScript dependency table

👉 As we really want types to be stricter, we require enabled strictNullChecks in your project

API

ts-essentials is a set of high-quality, useful TypeScript types that make writing type-safe code easier.

Basic

Builtin - Matches primitive, function, date, error or regular expression
KeyofBase - keyofStringsOnly-tolerant analogue for PropertyKey
Prettify<Type> - flattens type and makes it more readable on the hover in your IDE
Primitive - Matches any primitive value
StrictExclude<UnionType, ExcludedMembers> - Constructs a type by excluding from UnionType all union members that are assignable to ExcludedMembers. This is stricter version of Exclude
StrictExtract<Type, Union> - Constructs a type by extracting from Type all union members that are assignable to Union. This is stricter version of Extract
StrictOmit<Type, Keys> - Constructs a type by picking all properties from Type and then removing Keys. This is stricter version of Omit
Writable<Type> - Constructs a type with removed readonly for all properties of Type, meaning the properties of the constructed type can be reassigned

Utility types

AsyncOrSync<Type> - Constructs a type with Type or PromiseLike<Type>
AsyncOrSyncType<Type> - Unwraps AsyncOrSync type
Dictionary<Type, Keys?> - Constructs a required object type which property keys are Keys (string by default) and which property values are Type
Merge<Object1, Object2> - Constructs a type by picking all properties from Object1 and Object2. Property values from Object2 override property values from Object1 when property keys are the same
MergeN<Tuple> - Constructs a type by merging objects with type Merge in tuple Tuple recursively
Newable<ReturnType> - Constructs a class type with constructor which has return type ReturnType
NonNever<Type> - Constructs a type by picking all properties from type Type which values don't equal to never
OmitProperties<Type, Value> - Constructs a type by picking all properties from type Type and removing those properties which values equal to Value
Opaque<Type, Token> - Constructs a type which is a subset of Type with a specified unique token Token
PathValue<Type, Path> - Constructs a path value for type Type and path Path
Paths<Type> - Constructs a union type by picking all possible paths for type Type
PickProperties<Type, Value> - Constructs a type by picking all properties from type Type which values equal to Value
SafeDictionary<Type, Keys?> - Constructs an optional object type which property keys are Keys (string by default) and which property values are Type
UnionToIntersection<Union> - Constructs a intersection type from union type Union
ValueOf<Type> - Constructs a type for type Type and equals to a primitive for primitives, array elements for arrays, function return type for functions or object property values for objects
XOR<Type1, Type2, Type3?, ..., Type50?> - Construct a type which is assignable to either type Type1, Type2 but not both. Starting in ts-essentials@10, it supports up to 50 generic types.

Mark wrapper types

MarkOptional<Type, Keys> - Constructs a type by picking all properties from type Type where properties Keys are set as optional, meaning they aren't required
MarkReadonly<Type, Keys> - Constructs a type by picking all properties from type Type where properties Keys are set to readonly, meaning they cannot be reassigned
MarkRequired<Type, Keys> - Constructs a type by picking all properties from type Type where properties Keys are set as required
MarkWritable<Type, Keys> - Constructs a type by picking all properties from type Type where properties Keys remove readonly modifier, meaning they can be reassigned

Deep wrapper types

Buildable<Type> - Constructs a type by combining DeepPartial and DeepWritable, meaning all properties from type Type are recursively set as non-readonly and optional, meaning they can be reassigned and aren't required
DeepNonNullable<Type> - Constructs a type by picking all properties from type Type recursively and exclude null and undefined property values from all of them. To make properties non-nullable on one level, use NonNullable<Type>
DeepNullable<Type> - Constructs a type by picking all properties from type Type recursively and include null property values for all of them
DeepOmit<Type, Filter> - Constructs a type by picking all properties from type Type and removing properties which values are never or true in type Filter. If you'd like type Filter to be validated against a structure of Type, please use StrictDeepOmit<Type, Filter>.
DeepPartial<Type> - Constructs a type by picking all properties from type Type recursively and setting them as optional, meaning they aren't required. To make properties optional on one level, use Partial<Type>
DeepPick<Type, Filter> - Constructs a type by picking set of properties, which have property values never or true in type Filter, from type Type. If you'd like type Filter to be validated against a structure of Type, please use StrictDeepPick<Type, Filter>.
DeepReadonly<Type> - Constructs a type by picking all properties from type Type recursively and setting readonly modifier, meaning they cannot be reassigned. To make properties readonly on one level, use Readonly<Type>
DeepRequired<Type> - Constructs a type by picking all properties from type Type recursively and setting as required. To make properties required on one level, use Required<Type>
DeepUndefinable<Type> - Constructs a type by picking all properties from type Type recursively and include undefined property values for all of them
DeepWritable<Type> - Constructs a type by picking all properties from type Type recursively and removing readonly modifier, meaning they can be reassigned. To make properties writable on one level, use Writable<Type>
StrictDeepOmit<Type, Filter> - Constructs a type by picking all properties from type Type and removing properties which values are never or true in type Filter. The type Filter is validated against a structure of Type.
StrictDeepPick<Type, Filter> - Constructs a type by picking set of properties, which have property values never or true in type Filter, from type Type. The type Filter is validated against a structure of Type.

Key types

OptionalKeys<Type> - Constructs a union type by picking all optional properties of object type Type
PickKeys<Type, Value> - Constructs a union type by picking all properties of object type Type which values are assignable to type Value
ReadonlyKeys<Type> - Constructs a union type by picking all readonly properties of object type Type, meaning their values cannot be reassigned
RequiredKeys<Type> - Constructs a union type by picking all required properties of object type Type
WritableKeys<Type> - Constructs a union type by picking all writable properties of object type Type, meaning their values can be reassigned

Type checkers

Exact<Type, Shape> - Returns Type when type Type and Shape are identical. Otherwise returns never
IsAny<Type> - Returns true when type Type is any. Otherwise returns false
IsNever<Type> - Returns true when type Type is never. Otherwise returns false
IsUnknown<Type> - Returns true when type Type is unknown. Otherwise returns false
IsTuple<Type> - Returns Type when type Type is tuple. Otherwise returns never
NonEmptyObject<Object> - Returns Object when Object has at least one key. Otherwise returns never

Arrays and Tuples

AnyArray<Type?> - Matches Array or ReadonlyArray (Type is any by default)
ArrayOrSingle<Type> - Matches Type or Type[]
ElementOf<Type> - Constructs a type which equals to array element type for type Type
Head<Type> - Constructs a type which equals to first element in type Type
NonEmptyArray<Type> - Matches array with at least one element of type Type
ReadonlyArrayOrSingle - Matches Type or readonly Type[]
Tail<Type> - Constructs a type which equals to elements but first one in type Type
Tuple<Type?> - Matches type constraint for tuple with elements of type Type (any by default)

Change case

CamelCase<Type> - Converts type Type to camel case (e.g. camelCase)
DeepCamelCaseProperties<Type> - Constructs a type by picking all properties from type Type recursively and converting all of them to camel case

Function types

AnyFunction<Args?, ReturnType?> - Matches function type with arguments type Args (any[] by default) and return type ReturnType (any by default)
PredicateFunction - Matches type constraint for type guard, meaning first argument is used in return type and return type is type predicate
PredicateType<Type> - Constructs a type which equals to narrowed type in predicate function Type

Utility functions

⚠️ Make sure you add ts-essentials to your dependencies (npm install --save ts-essentials) to avoid runtime errors

new UnreachableCaseError(value) - Matches runtime class instance type that helps check exhaustiveness for value. When value isn't never, it shows TypeScript error
assert(condition, message?) - Matches runtime function that helps assert condition. When condition is falsy, it throws an error with Assertion Error: ${message} (message is "no additional info provided" by default)
createFactoryWithConstraint<Constraint>()(value) - Matches runtime function, which validates that type of value matches Constraint without changing resulting type of value. Ponyfill for satisfies operator
isExact<Expected>()(actual) - Matches runtime function, which validates that type of actual equals to Expected. Otherwise shows TypeScript error
noop(..._args) - Matches runtime function that does nothing with arguments _args

Search

When one of utility types is known by a different name, kindly ask adding it here for the better search.

ArrayValues - ValueOf<Type>
Branded - Opaque<Type, Token>
ConditionalKeys - PickKeys<Type, Value>
Except - StrictOmit<Type, Keys>
Get - PathValue<Type, Path>
Mutable - Writable<Type>
Nominal - Opaque<Type, Token>
Set*, e.g. SetOptional - Mark*, e.g. MarkReadonly<Type, Keys>
Unwrap - Prettify<Type>
ValueOf - DictionaryValues

Built-in types

TypeScript provides several utility types to facilitate common type transformations. These utilities are available globally.

Awaited<Type> - This type is meant to model operations like await in async functions, or the .then() method on Promises - specifically, the way that they recursively unwrap Promises
Capitalize<StringType> - Converts the first character in the string to an uppercase equivalent
ConstructParameters<Type> - Constructs a tuple or array type from the types of a constructor function type Type
Exclude<UnionType, ExcludedMembers> - Constructs a type by excluding from UnionType all union members that are assignable to ExcludedMembers
Extract<Type, Union> - Constructs a type by extracting from Type all union members that are assignable to Union
InstanceType<Type> - Constructs a type consisting of the instance type of a constructor function in Type
Lowercase<StringType> - Converts each character in the string to the lowercase equivalent
NonNullable<Type> - Constructs a type by excluding null and undefined from Type
Omit<Type, Keys> - Constructs a type by picking all properties from Type and then removing Keys
Parameters<Type> - Constructs a tuple type from the types used in the parameters of a function type Type
Partial<Type> - Constructs a type with all properties of Type set to optional
Pick<Type, Keys> - Constructs a type by picking the set of properties Keys from Type
Readonly<Type> - Constructs a type with all properties of Type set to readonly, meaning the properties of the constructed type cannot be reassigned
Record<Keys, Type> - Constructs an object type whose property keys are Keys and whose property values are Type
Required<Type> - Constructs a type consisting of all properties of Type set to required
ReturnType<Type> - Constructs a type consisting of the return type of function type Type parameter
Uncapitalize<StringType> - Converts the first character in the string to a lowercase equivalent
Uppercase<StringType> - Converts each character in the string to the uppercase version

TypeScript dependency table

`ts-essentials`	`typescript` / type of dependency
`^10.0.0`	`^4.5.0` / peer optional
`^9.4.0`	`^4.1.0` / peer optional
`^8.0.0`	`^4.1.0` / peer
`^5.0.0`	`^3.7.0` / peer
`^3.0.1`	`^3.5.0` / peer
`^1.0.1`	`^3.2.2` / dev
`^1.0.0`	`^3.0.3` / dev

Contributors

Thanks goes to these wonderful people (emoji key):

_{Chris Kaczor} 💻 💼 💡 📖	_{Xiao Liang} 💻 🤔 📖	_{Mateusz Burzyński} 💻 🤔 📖	_{Maciej Bembenista} 💻 🤔 📖	_{Michael Tontchev} 💻 🤔 📖	_{Thomas den Hollander} 💻 🤔 📖	_{Esa-Matti Suuronen} 💻 🤔 📖
_{Ilya Semenov} 💻 🤔 📖	_{Code Checks} 👀	_{Patricio Palladino} 🤔	_{Artur Kozak} 💻 🤔 📖 👀	_{Zihua Wu} 💻 🤔 📖	_{Kevin Peno} 💻	_{Dom Parfitt} 🤔
_EduardoRFS 💻 📖	_{Andrew C. Dvorak} 📖	_{Adam Russell} 💻 📖	_{Piotr Szlachciak} 💻 🤔 📖	_{Mikhail Swift} 💻	_{Ryan Zhang} 💻 🤔 📖	_{Francesco Borzì} 📖 💻
_{Marnick L'Eau} 💻 🤔 📖	_kubk 💻	_{Bill Barry} 💻 📖	_{Andrzej Wódkiewicz} 💻 📖 🤔	_Christian 🤔	_{Matthew Leffler} 📖	_studds 💻
_{Alex Berezin} 💻 📖	_vitonsky 📖	_{Itay Ronen} 💻	_{Yaroslav Larin} 💻