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

This project follows the all-contributors specification. Contributions of any kind welcome! Read more