ts-essentials

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 - flattens type and makes it more readable on the hover in your IDE
• Primitive - Matches any primitive value
• StrictExclude - Constructs a type by excluding from UnionType all union members that are assignable to ExcludedMembers. This is stricter version of Exclude
• StrictExtract - Constructs a type by extracting from Type all union members that are assignable to Union. This is stricter version of Extract
• StrictOmit - Constructs a type by picking all properties from Type and then removing Keys. This is stricter version of Omit
• Writable - Constructs a type with removed readonly for all properties of Type, meaning the properties of the constructed type can be reassigned

Utility types

• AsyncOrSync - Constructs a type with Type or PromiseLike
• AsyncOrSyncType - Unwraps AsyncOrSync type
• Dictionary - Constructs a required object type which property keys are Keys (string by default) and which property values are Type
• Merge - 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 - Constructs a type by merging objects with type Merge in tuple Tuple recursively
• Newable - Constructs a class type with constructor which has return type ReturnType
• NonNever - Constructs a type by picking all properties from type Type which values don't equal to never
• OmitProperties - Constructs a type by picking all properties from type Type and removing those properties which values equal to Value
• Opaque - Constructs a type which is a subset of Type with a specified unique token Token
• PathValue - Constructs a path value for type Type and path Path
• Paths - Constructs a union type by picking all possible paths for type Type
• PickProperties - Constructs a type by picking all properties from type Type which values equal to Value
• SafeDictionary - Constructs an optional object type which property keys are Keys (string by default) and which property values are Type
• UnionToIntersection - Constructs a intersection type from union type Union
• ValueOf - 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 - 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 - Constructs a type by picking all properties from type Type where properties Keys are set as optional, meaning they aren't required
• MarkReadonly - Constructs a type by picking all properties from type Type where properties Keys are set to readonly, meaning they cannot be reassigned
• MarkRequired - Constructs a type by picking all properties from type Type where properties Keys are set as required
• MarkWritable - 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 - 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 - 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
• DeepNullable - Constructs a type by picking all properties from type Type recursively and include null property values for all of them
• DeepOmit - 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.
• DeepPartial - 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
• DeepPick - 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.
• DeepReadonly - 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
• DeepRequired - Constructs a type by picking all properties from type Type recursively and setting as required. To make properties required on one level, use Required
• DeepUndefinable - Constructs a type by picking all properties from type Type recursively and include undefined property values for all of them
• DeepWritable - 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
• StrictDeepOmit - 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 - 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 - Constructs a union type by picking all optional properties of object type Type
• PickKeys - Constructs a union type by picking all properties of object type Type which values are assignable to type Value
• ReadonlyKeys - Constructs a union type by picking all readonly properties of object type Type, meaning their values cannot be reassigned
• RequiredKeys - Constructs a union type by picking all required properties of object type Type
• WritableKeys - Constructs a union type by picking all writable properties of object type Type, meaning their values can be reassigned

Type checkers

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

Arrays and Tuples

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

Change case

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

Function types

• AnyFunction - 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 - 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()(value) - Matches runtime function, which validates that type of value matches Constraint without changing resulting type of value. Ponyfill for satisfies operator
• isExact()(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
• Branded - Opaque
• ConditionalKeys - PickKeys
• Except - StrictOmit
• Get - PathValue
• Mutable - Writable
• Nominal - Opaque
• Set*, e.g. SetOptional - Mark*, e.g. MarkReadonly
• Unwrap - Prettify
• ValueOf - DictionaryValues

Built-in types

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

• Awaited - 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 - Converts the first character in the string to an uppercase equivalent
• ConstructParameters - Constructs a tuple or array type from the types of a constructor function type Type
• Exclude - Constructs a type by excluding from UnionType all union members that are assignable to ExcludedMembers
• Extract - Constructs a type by extracting from Type all union members that are assignable to Union
• InstanceType - Constructs a type consisting of the instance type of a constructor function in Type
• Lowercase - Converts each character in the string to the lowercase equivalent
• NonNullable - Constructs a type by excluding null and undefined from Type
• Omit - Constructs a type by picking all properties from Type and then removing Keys
• Parameters - Constructs a tuple type from the types used in the parameters of a function type Type
• Partial - Constructs a type with all properties of Type set to optional
• Pick - Constructs a type by picking the set of properties Keys from Type
• Readonly - Constructs a type with all properties of Type set to readonly, meaning the properties of the constructed type cannot be reassigned
• Record - Constructs an object type whose property keys are Keys and whose property values are Type
• Required - Constructs a type consisting of all properties of Type set to required
• ReturnType - Constructs a type consisting of the return type of function type Type parameter
• Uncapitalize - Converts the first character in the string to a lowercase equivalent
• Uppercase - Converts each character in the string to the uppercase version

TypeScript dependency table

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 💻

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