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
JsonArray - Matches any JSON array
JsonObject - Matches any JSON object
JsonPrimitive - Matches any JSON primitive value
JsonValue - Matches any JSON value
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
OmitNeverProperties<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
RequireAtLeastOne<Type, Keys?> - Constructs a type with at least one required key from Keys (keyof Type by default) and other keys from Type which are not part of Keys
RequireAtMostOne<Type, Keys?> - Constructs a type with at most one required key from Keys (keyof Type by default) and other keys from Type which are not part of Keys
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
DeepMarkOptional<Type, KeyPathUnion> - Constructs a type by picking all properties from type Type where properties by paths KeyPathUnion are set as optional. To mark properties optional on one level, use MarkOptional<Type, Keys>.
DeepMarkRequired<Type, KeyPathUnion> - Constructs a type by picking all properties from type Type where properties by paths KeyPathUnion are set as required. To mark properties required on one level, use MarkRequired<Type, Keys>.
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
UnionKeys<UnionType> - Constructs a union type by picking all properties from all union members of UnionType
WritableKeys<Type> - Constructs a union type by picking all writable properties of object type Type, meaning their values can be reassigned

Type checkers

IsAny<Type> - Returns true when type Type is any. Otherwise returns false
IsExact<Type, Shape> - Returns Type when type Type and Shape are identical. Otherwise returns never
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
NonUnion<Type> - Returns Type when Type is not an union. Otherwise returns never

Arrays and Tuples

AnyArray<Type?> - Matches Array or ReadonlyArray (Type is any by default)
AnyNonEmptyArray<Type> - Matches array with at least one element of type Type
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
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
ConstructorParameters<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
NoInfer<Type> - Blocks inferences to the contained type. Other than blocking inferences, NoInfer<Type> is identical to Type
Omit<Type, Keys> - Constructs a type by picking all properties from Type and then removing Keys
OmitThisParameter<Type> - Removes the this parameter from Type. If Type has no explicitly declared this parameter, the result is simply Type. Otherwise, a new function type with no this parameter is created from Type. Generics are erased and only the last overload signature is propagated into the new function type.
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
ThisParameterType<Type> - Extracts the type of the this parameter for a function type, or unknown if the function type has no this parameter
ThisType<Type> - This utility does not return a transformed type. Instead, it serves as a marker for a contextual this type. Note that the noImplicitThis flag must be enabled to use this utility
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

Limitations

This project doesn't use extends Constraints on infer Type Variables as it's introduced in TypeScript 4.7, but currently ts-essentials supports versions below, e.g. TypeScript 4.5. Read more in https://www.typescriptlang.org/docs/handbook/release-notes/typescript-4-7.html#extends-constraints-on-infer-type-variables

Contributors

Special shout-out to active contributors:

And thanks goes to these wonderful people:

💻 - contributions, i.e. links to commits by the user on this project

Contributions of any kind welcome! Read more