Awesome
<p align="center"> <img src="/logo.png" width="120" alt="ts-essentials"> <h3 align="center">ts-essentials</h3> <p align="center">All essential TypeScript types in one place 馃</p> <p align="center"> <a href="https://www.npmjs.com/package/ts-essentials" title="View this project on NPM"> <img alt="Version" src="https://img.shields.io/npm/v/ts-essentials.svg"> </a> <img alt="Downloads" src="https://img.shields.io/npm/dm/ts-essentials.svg"> <a href="https://github.com/ts-essentials/ts-essentials/actions?query=branch%3Amaster" title="View Github Build status"> <img alt="Build status" src="https://github.com/ts-essentials/ts-essentials/actions/workflows/ci.yml/badge.svg"> </a> <a href="https://t.me/ts_essentials" title="Get support in Telegram"> <img alt="Telegram" src="https://img.shields.io/badge/-telegram-red?color=white&logo=telegram"> </a> <a href="/package.json"><img alt="Software License" src="https://img.shields.io/badge/license-MIT-brightgreen.svg?style=flat-square"></a> <a href="https://codechecks.io"><img src="https://raw.githubusercontent.com/codechecks/docs/master/images/badges/badge-default.svg?sanitize=true" alt="codechecks.io"></a> </p> </p>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 expressionKeyofBase
-keyofStringsOnly
-tolerant analogue forPropertyKey
Prettify<Type>
- flattens type and makes it more readable on the hover in your IDEPrimitive
- Matches any primitive valueStrictExclude<UnionType, ExcludedMembers>
- Constructs a type by excluding fromUnionType
all union members that are assignable toExcludedMembers
. This is stricter version ofExclude
StrictExtract<Type, Union>
- Constructs a type by extracting fromType
all union members that are assignable toUnion
. This is stricter version ofExtract
StrictOmit<Type, Keys>
- Constructs a type by picking all properties fromType
and then removingKeys
. This is stricter version ofOmit
Writable<Type>
- Constructs a type with removedreadonly
for all properties ofType
, meaning the properties of the constructed type can be reassigned
Utility types
AsyncOrSync<Type>
- Constructs a type withType
orPromiseLike<Type>
AsyncOrSyncType<Type>
- UnwrapsAsyncOrSync
typeDictionary<Type, Keys?>
- Constructs a required object type which property keys areKeys
(string
by default) and which property values areType
Merge<Object1, Object2>
- Constructs a type by picking all properties fromObject1
andObject2
. Property values fromObject2
override property values fromObject1
when property keys are the sameMergeN<Tuple>
- Constructs a type by merging objects with typeMerge
in tupleTuple
recursivelyNewable<ReturnType>
- Constructs a class type with constructor which has return typeReturnType
NonNever<Type>
- Constructs a type by picking all properties from typeType
which values don't equal tonever
OmitProperties<Type, Value>
- Constructs a type by picking all properties from typeType
and removing those properties which values equal toValue
Opaque<Type, Token>
- Constructs a type which is a subset ofType
with a specified unique tokenToken
PathValue<Type, Path>
- Constructs a path value for typeType
and pathPath
Paths<Type>
- Constructs a union type by picking all possible paths for typeType
PickProperties<Type, Value>
- Constructs a type by picking all properties from typeType
which values equal toValue
SafeDictionary<Type, Keys?>
- Constructs an optional object type which property keys areKeys
(string
by default) and which property values areType
UnionToIntersection<Union>
- Constructs a intersection type from union typeUnion
ValueOf<Type>
- Constructs a type for typeType
and equals to a primitive for primitives, array elements for arrays, function return type for functions or object property values for objectsXOR<Type1, Type2, Type3?, ..., Type50?>
- Construct a type which is assignable to either typeType1
,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 typeType
where propertiesKeys
are set as optional, meaning they aren't requiredMarkReadonly<Type, Keys>
- Constructs a type by picking all properties from typeType
where propertiesKeys
are set toreadonly
, meaning they cannot be reassignedMarkRequired<Type, Keys>
- Constructs a type by picking all properties from typeType
where propertiesKeys
are set as requiredMarkWritable<Type, Keys>
- Constructs a type by picking all properties from typeType
where propertiesKeys
removereadonly
modifier, meaning they can be reassigned
Deep wrapper types
Buildable<Type>
- Constructs a type by combiningDeepPartial
andDeepWritable
, meaning all properties from typeType
are recursively set as non-readonly
and optional, meaning they can be reassigned and aren't requiredDeepNonNullable<Type>
- Constructs a type by picking all properties from typeType
recursively and excludenull
andundefined
property values from all of them. To make properties non-nullable on one level, useNonNullable<Type>
DeepNullable<Type>
- Constructs a type by picking all properties from typeType
recursively and includenull
property values for all of themDeepOmit<Type, Filter>
- Constructs a type by picking all properties from typeType
and removing properties which values arenever
ortrue
in typeFilter
. If you'd like typeFilter
to be validated against a structure ofType
, please useStrictDeepOmit<Type, Filter>
.DeepPartial<Type>
- Constructs a type by picking all properties from typeType
recursively and setting them as optional, meaning they aren't required. To make properties optional on one level, usePartial<Type>
DeepPick<Type, Filter>
- Constructs a type by picking set of properties, which have property valuesnever
ortrue
in typeFilter
, from typeType
. If you'd like typeFilter
to be validated against a structure ofType
, please useStrictDeepPick<Type, Filter>
.DeepReadonly<Type>
- Constructs a type by picking all properties from typeType
recursively and settingreadonly
modifier, meaning they cannot be reassigned. To make propertiesreadonly
on one level, useReadonly<Type>
DeepRequired<Type>
- Constructs a type by picking all properties from typeType
recursively and setting as required. To make properties required on one level, useRequired<Type>
DeepUndefinable<Type>
- Constructs a type by picking all properties from typeType
recursively and includeundefined
property values for all of themDeepWritable<Type>
- Constructs a type by picking all properties from typeType
recursively and removingreadonly
modifier, meaning they can be reassigned. To make properties writable on one level, useWritable<Type>
StrictDeepOmit<Type, Filter>
- Constructs a type by picking all properties from typeType
and removing properties which values arenever
ortrue
in typeFilter
. The typeFilter
is validated against a structure ofType
.StrictDeepPick<Type, Filter>
- Constructs a type by picking set of properties, which have property valuesnever
ortrue
in typeFilter
, from typeType
. The typeFilter
is validated against a structure ofType
.
Key types
OptionalKeys<Type>
- Constructs a union type by picking all optional properties of object typeType
PickKeys<Type, Value>
- Constructs a union type by picking all properties of object typeType
which values are assignable to typeValue
ReadonlyKeys<Type>
- Constructs a union type by picking allreadonly
properties of object typeType
, meaning their values cannot be reassignedRequiredKeys<Type>
- Constructs a union type by picking all required properties of object typeType
WritableKeys<Type>
- Constructs a union type by picking all writable properties of object typeType
, meaning their values can be reassigned
Type checkers
Exact<Type, Shape>
- ReturnsType
when typeType
andShape
are identical. Otherwise returnsnever
IsAny<Type>
- Returnstrue
when typeType
isany
. Otherwise returnsfalse
IsNever<Type>
- Returnstrue
when typeType
isnever
. Otherwise returnsfalse
IsUnknown<Type>
- Returnstrue
when typeType
isunknown
. Otherwise returnsfalse
IsTuple<Type>
- ReturnsType
when typeType
is tuple. Otherwise returnsnever
NonEmptyObject<Object>
- ReturnsObject
whenObject
has at least one key. Otherwise returnsnever
Arrays and Tuples
AnyArray<Type?>
- MatchesArray
orReadonlyArray
(Type
isany
by default)ArrayOrSingle<Type>
- MatchesType
orType[]
ElementOf<Type>
- Constructs a type which equals to array element type for typeType
Head<Type>
- Constructs a type which equals to first element in typeType
NonEmptyArray<Type>
- Matches array with at least one element of typeType
ReadonlyArrayOrSingle
- MatchesType
orreadonly Type[]
Tail<Type>
- Constructs a type which equals to elements but first one in typeType
Tuple<Type?>
- Matches type constraint for tuple with elements of typeType
(any
by default)
Change case
CamelCase<Type>
- Converts typeType
to camel case (e.g.camelCase
)DeepCamelCaseProperties<Type>
- Constructs a type by picking all properties from typeType
recursively and converting all of them to camel case
Function types
AnyFunction<Args?, ReturnType?>
- Matches function type with arguments typeArgs
(any[]
by default) and return typeReturnType
(any
by default)PredicateFunction
- Matches type constraint for type guard, meaning first argument is used in return type and return type is type predicatePredicateType<Type>
- Constructs a type which equals to narrowed type in predicate functionType
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 forvalue
. Whenvalue
isn'tnever
, it shows TypeScript errorassert(condition, message?)
- Matches runtime function that helps assertcondition
. Whencondition
is falsy, it throws an error withAssertion Error: ${message}
(message is"no additional info provided"
by default)createFactoryWithConstraint<Constraint>()(value)
- Matches runtime function, which validates that type ofvalue
matchesConstraint
without changing resulting type ofvalue
. Ponyfill forsatisfies
operatorisExact<Expected>()(actual)
- Matches runtime function, which validates that type ofactual
equals toExpected
. Otherwise shows TypeScript errornoop(..._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 likeawait
inasync
functions, or the.then()
method onPromise
s - specifically, the way that they recursively unwrapPromise
sCapitalize<StringType>
- Converts the first character in the string to an uppercase equivalentConstructParameters<Type>
- Constructs a tuple or array type from the types of a constructor function typeType
Exclude<UnionType, ExcludedMembers>
- Constructs a type by excluding fromUnionType
all union members that are assignable toExcludedMembers
Extract<Type, Union>
- Constructs a type by extracting fromType
all union members that are assignable toUnion
InstanceType<Type>
- Constructs a type consisting of the instance type of a constructor function inType
Lowercase<StringType>
- Converts each character in the string to the lowercase equivalentNonNullable<Type>
- Constructs a type by excluding null and undefined fromType
Omit<Type, Keys>
- Constructs a type by picking all properties fromType
and then removingKeys
Parameters<Type>
- Constructs a tuple type from the types used in the parameters of a function typeType
Partial<Type>
- Constructs a type with all properties ofType
set to optionalPick<Type, Keys>
- Constructs a type by picking the set of propertiesKeys
fromType
Readonly<Type>
- Constructs a type with all properties ofType
set toreadonly
, meaning the properties of the constructed type cannot be reassignedRecord<Keys, Type>
- Constructs an object type whose property keys areKeys
and whose property values areType
Required<Type>
- Constructs a type consisting of all properties ofType
set to requiredReturnType<Type>
- Constructs a type consisting of the return type of function typeType
parameterUncapitalize<StringType>
- Converts the first character in the string to a lowercase equivalentUppercase<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
Special shout-out to active contributors:
- Kris Kaczor / 馃捇
- Xiao Liang / 馃捇
- Mateusz Burzy艅ski / 馃捇
- Artur Kozak / 馃捇
- Zihua Wu / 馃捇
- Alexey Berezin / 馃捇
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 / 馃捇
- Som Shekhar Mukherjee / 馃捇
馃捇 - contributions, i.e. links to commits by the user on this project
Contributions of any kind welcome! Read more