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
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
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
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
Change case
Function types
Utility functions
⚠️ Make sure you add ts-essentials
to your dependencies
(npm install --save ts-essentials
) to avoid runtime errors
Search
When one of utility types is known by a different name, kindly ask adding it here for the better search.
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 Promise
s - specifically, the way that
they recursively unwrap Promise
s
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 |
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