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

Contributors

Special shout-out to active contributors:

• Kris Kaczor / 💻
• Xiao Liang / 💻
• Mateusz Burzyński / 💻
• Artur Kozak / 💻
• Zihua Wu / 💻
• Alexey Berezin / 💻
• Som Shekhar Mukherjee / 💻

And thanks goes to these wonderful people:

• Maciej Bembenista / 💻
• Michael Tontchev / 💻
• Thomas den Hollander / 💻
• Esa-Matti Suuronen
• Ilya Semenov / 💻
• Patricio Palladino
• Kevin Peno / 💻
• Dom Parfitt
• Eduardo Rafael / 💻
• Andrew C. Dvorak / 💻
• Adam Russell / 💻
• Piotr Szlachciak / 💻
• Mikhail Swift / 💻
• Ryan Zhang
• Francesco Borzì / 💻
• Marnick L'Eau
• Egor Gorbachev
• Bill Barry / 💻
• Andrzej Wódkiewicz / 💻
• Christian Junker
• Matthew Leffler / 💻
• studds / 💻
• Robert Vitonsky
• Itay Ronen / 💻
• Yaroslav Larin
• liaoyinglong / 💻
• Yannick Stachelscheid / 💻
• Peter Smolinský / 💻
• Anurag Hazra / 💻
• Bishwajit Jha / 💻
• Sergey Ukustov / 💻
• Homa Wong / 💻
• polyipseity / 💻
• Kristóf Poduszló / 💻
• MT Lewis / 💻
• Daniel Bertocci / 💻
• Myles J / 💻

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

Contributions of any kind welcome! Read more

ts-essentials

10.0.4

Patch Changes

• ecb490b: Head<Type> no longer includes an extraneous | undefined when instantiated with a union of empty and non-empty tuple, like [] | [1, 2]
• 859d85c: MarkOptional<Type, Keys> is now assignable to Partial<Type>
• dda4def: Tail<Type> now works with readonly arrays and also correctly returns the tail for tuples with all optional members. Additionally, it now acts as an identity for non-tuple arrays, i.e., it returns Type when Type is a non-tuple array, such as string[], number[], etc.
• d02bf22: Fix MarkRequired<Type, Keys> & MarkWritable<Type, Keys> types when Keys is any
• d3b56d7: Prettify the output of Mark-* and Merge types

10.0.3

Patch Changes

• cc7b838: ReadonlyKeys<Type> and WritableKeys<Type> now return only the readonly and writable keys, respectively, for arrays and tuples
• d6867ea: Prettify<Type> returns the same type when the type parameter is a function
• bc51ac5: OptionalKeys<Type> returns never for primitives and returns only optional indices for arrays and tuples
• d0ad79f: Improve Paths performance by limiting the depth of paths to 7 (default)
• 162fd9d: Add Paths<Type, { anyArrayIndexAccessor: '*' }>, a string literal representing a catch-all or "wildcard" when indexing on arrays.

10.0.2

Patch Changes

• 490712c: Deprecated DictionaryValues in favour of ValueOf
• c311536: Added a support of interfaces for PathValue

10.0.1

Patch Changes

• 365612c: Use key remapping in PickKeys, OmitProperties and PickProperties that reduced the number of instantiations by ~20-40% on average
• 39eb424: Remove XOR union element with all properties excluded from the intersection

10.0.0

Major Changes

• b127a8a: Use TypeScript@^4.2.0 because of excessively deep and possibly infinite type instantiation limitation for PathValue and Paths
• 26be790: Fixed assignability of Mark* utility types which required removing support of TypeScript@<4.5
• 9935d80: Added StrictDeepOmit and StrictDeepPick that support generic type and removed generic constraint on the second type parameter of DeepOmit and DeepPick

Minor Changes

• 5b7650a: Add variadic XOR, up to 50 generic types
• b127a8a: Implement Paths and PathValue to access object properties, array/tuple indices

Patch Changes

• d2dbcf9: Added CONVENTIONS.md for reliable, consistent and predictable development
• ed57101: Add support for types which explicitly extend Array inside types passed to DeepRequired.
• 25f3f60: Add support of union types for arrays, tuples, objects and primitive in isExact

9.4.2

Patch Changes

• f88f757: Add TypeScript 5.3 and 5.4 support (fix a bug with WeakKey for WeakSet and WeakMap)

9.4.1

Patch Changes

• bc3c474: Fix regression in TypeScript 5.1 with CamelCase

9.4.0

Minor Changes

• ddb1bea: Make typescript optional as a peer dependency

9.3.2

Patch Changes

• 8761667: DeepPartial, DeepRequired, DeepWritable and DeepReadonly can update structure of Error or interface which extends Error
• afccd35: Fix handling of readonly arrays in isTuple, DeepNullable, DeepPartial, and DeepUndefinable

9.3.1

Patch Changes

• 0c215b9: Changed the Tuple's type implementation to only use a tuple type (instead of a union of a tuple type and an array type).
• 544742e: Fix unique symbol __OPAQUE_TYPE__ in Opaque that cannot be used outside of ts-essentials
• 4c45165: Improve the object constraint for NonEmptyObject<T> to not allow primitives
• 66a6169: Improve the ValueOf utility type to cover the edge cases

9.3.0

Minor Changes

• a86c5b5: Add ReadonlyArrayOrSingle which is a counterpart to ArrayOrSingle with the array being readonly
• 14cfa7c: Add utility function createFactoryWithConstraint

Patch Changes

• c63e30e: Refactor Tail to use variadic tuple type
• 8a28c53: Fix DeepReadonly for a union with an array of itself
• 5989dda: Add union support to all Mark* methods: MarkRequired, MarkOptional, MarkReadonly and MarkWritable
• 8abe8a6: Fix StrictExtract usage for TypeScript@^4.6.0

9.2.0

Minor Changes

• 5aa1f26: Add NonEmptyArray which ensures an array to have at least one item
• fa03dda: Add StrictExclude, a stricter version of Exclude
• 6b27ee4: Add MarkWritable which unsets readonly for specified keys
• e76a08a: Add MarkReadonly which sets readonly for specific keys

Patch Changes

• 13504d0: Fix DeepPartial for normal arrays

9.1.2

Patch Changes

• 08adddd: Remove postinstall script

9.1.1

Patch Changes

• bf05a7e: Fix DeepPick and DeepOmit for project with TypeScript 4.5 or newer
• c338a99: Fix DeepOmit and DeepPick for WeakMap in TypeScript 4.1 and 4.2

9.1.0

Minor Changes

• a2ac470: Add IsAny which returns true if it's any, otherwise false
• a2ac470: Add ArrayOrSingle
• a2ac470: Add DeepPick with the validation of the filter
• a2ac470: Add CamelCase and DeepCamelCaseProperties for converting it from other cases

Patch Changes

• a2ac470: Properly infer required fields for set, map, array and promise in DeepOmit and DeepPick
• a2ac470: Improve DeepOmit by removing 4 intersections for objects and applying generic restriction for Filter
• 3541ee9: Replace PropertyKey with KeyofBase to tolerate keyofStringsOnly option in TypeScript
• a2ac470: Adapt OptionalKeys and RequiredKeys for union of objects

9.0.0

Major Changes

• aa879ca: Use TypeScript@^4.1.0 because of introduced recursive conditional types

Minor Changes

• e39426b: Add IsUnknown which returns true if it's unknown, otherwise false
• 6d10f69: Add IsNever which returns true if it's never, otherwise false
• b580ac1: Add isExact function

8.1.0

Minor Changes

• 7bf4fdb: Make DeepRequired as recursive Required without removing null and undefined

Patch Changes

• c463c70: Align ReadonlySet and ReadonlyMap in DeepUndefinable with other sets and maps
• 374431f: Fix DeepPartial and Buildable for unknown
• 83458c0: Align ReadonlySet and ReadonlyMap in DeepNullable with other sets and maps
• 7bf4fdb: Add difference between DeepRequired and DeepNonNullable in README
• ec8d796: Allow only objects to be used in StrictOmit
• f045817: Fix DictionaryValues for SafeDictionary with number and string literals keys
• ec8d796: StrictOmit returns never for arrays and tuples

8.0.0

Major Changes

• 239e7e3: Use typescript@^4.0.0

Minor Changes

• ab6f68e: Add StrictExtract to check the original structure of type and extract it correctly
• 239e7e3: Add MergeN: you can pass tuple of size N and it will recursively apply Merge

Patch Changes

• b39ce66: Improve readme description about what's this project is all about
• 239e7e3: Add DeepReadonly support for unknown type
• 35e73b6: IsTuple now works with any tuple length
• 239e7e3: Update readme description of Opaque

7.0.3

Patch Changes

• f917f9b: Refactor Opaque, now __TYPE__ is not accessible at all