ts-essentials

ts-essentials

All essential TypeScript types in one place πŸ€™

Downloads Build status Software License All Contributors codechecks.io

## Install ```sh npm install --save-dev ts-essentials ``` πŸ‘‰ We require `typescript>=4.1`. If you're looking for support for older TS versions, please have a look at the [TypeScript dependency table](https://github.com/ts-essentials/ts-essentials/tree/master#TypeScript-dependency-table) πŸ‘‰ As we really want types to be stricter, we require enabled [strictNullChecks](https://www.typescriptlang.org/tsconfig#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`](/lib/built-in) - Matches primitive, function, date, error or regular expression - [`KeyofBase`](/lib/key-of-base) - [`keyofStringsOnly`](https://www.typescriptlang.org/tsconfig#keyofStringsOnly)-tolerant analogue for `PropertyKey` - [`Primitive`](/lib/primitive) - Matches any [primitive value](https://developer.mozilla.org/en-US/docs/Glossary/Primitive) - [`StrictExclude`](/lib/strict-exclude) - Constructs a type by excluding from `UnionType` all union members that are assignable to `ExcludedMembers`. This is stricter version of [`Exclude`](https://www.typescriptlang.org/docs/handbook/utility-types.html#excludeuniontype-excludedmembers) - [`StrictExtract`](/lib/strict-extract) - Constructs a type by extracting from `Type` all union members that are assignable to `Union`. This is stricter version of [`Extract`](https://www.typescriptlang.org/docs/handbook/utility-types.html#extracttype-union) - [`StrictOmit`](/lib/strict-omit) - Constructs a type by picking all properties from `Type` and then removing `Keys`. This is stricter version of [`Omit`](https://www.typescriptlang.org/docs/handbook/utility-types.html#omittype-keys) - [`Writable`](/lib/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`](/lib/async-or-sync) - Constructs a type with `Type` or `PromiseLike` - [`AsyncOrSyncType`](/lib/async-or-sync-type) - Unwraps `AsyncOrSync` type - [`Dictionary`](/lib/dictionary) - Constructs a required object type which property keys are `Keys` (`string` by default) and which property values are `Type` - [`DictionaryValues`](/lib/dictionary-values) - This type unwraps `Dictionary` value type - [`Merge`](/lib/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`](/lib/merge-n) - Constructs a type by merging objects with type `Merge` in tuple `Tuple` recursively - [`Newable`](/lib/newable) - Constructs a class type with constructor which has return type `ReturnType` - [`NonNever`](/lib/non-never) - Constructs a type by picking all properties from type `Type` which values don't equal to `never` - [`OmitProperties`](/lib/omit-properties) - Constructs a type by picking all properties from type `Type` and removing those properties which values equal to `Value` - [`Opaque`](/lib/opaque) - Constructs a type which is a subset of `Type` with a specified unique token `Token` - [`PickProperties`](/lib/pick-properties) - Constructs a type by picking all properties from type `Type` which values equal to `Value` - [`SafeDictionary`](/lib/safe-dictionary) - Constructs an optional object type which property keys are `Keys` (`string` by default) and which property values are `Type` - [`UnionToIntersection`](/lib/union-to-intersection) - Constructs a intersection type from union type `Union` - [`ValueOf`](/lib/value-of) - 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`](/lib/xor) - Construct a type which is assignable to either type `Type1` or `Type2` but not both ### Mark wrapper types - [`MarkOptional`](/lib/mark-optional) - Constructs a type by picking all properties from type `Type` where properties `Keys` are set as optional, meaning they aren't required - [`MarkReadonly`](/lib/mark-readonly) - Constructs a type by picking all properties from type `Type` where properties `Keys` are set to `readonly`, meaning they cannot be reassigned - [`MarkRequired`](/lib/mark-required) - Constructs a type by picking all properties from type `Type` where properties `Keys` are set as required - [`MarkWritable`](/lib/mark-writable) - 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`](/lib/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`](/lib/deep-non-nullable) - 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`](https://www.typescriptlang.org/docs/handbook/utility-types.html#nonnullabletype) - [`DeepNullable`](/lib/deep-nullable) - Constructs a type by picking all properties from type `Type` recursively and include `null` property values for all of them - [`DeepOmit`](/lib/deep-omit) - Constructs a type by picking all properties from type `Type` and removing properties which values are `never` or `true` in type `Filter` - [`DeepPartial`](/lib/deep-partial) - 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`](https://www.typescriptlang.org/docs/handbook/utility-types.html#partialtype) - [`DeepPick`](/lib/deep-pick) - Constructs a type by picking set of properties, which have property values `never` or `true` in type `Filter`, from type `Type` - [`DeepReadonly`](/lib/deep-readonly) - 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`](https://www.typescriptlang.org/docs/handbook/utility-types.html#readonlytype) - [`DeepRequired`](/lib/deep-required) - Constructs a type by picking all properties from type `Type` recursively and setting as required. To make properties required on one level, use [`Required`](https://www.typescriptlang.org/docs/handbook/utility-types.html#requiredtype) - [`DeepUndefinable`](/lib/deep-undefinable) - Constructs a type by picking all properties from type `Type` recursively and include `undefined` property values for all of them - [`DeepWritable`](/lib/deep-writable) - 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` ### Key types - [`OptionalKeys`](/lib/optional-keys) - Constructs a union type by picking all optional properties of object type `Type` - [`PickKeys`](/lib/pick-keys) - Constructs a union type by picking all properties of object type `Type` which values are assignable to type `Value` - [`ReadonlyKeys`](/lib/readonly-keys) - Constructs a union type by picking all `readonly` properties of object type `Type`, meaning their values cannot be reassigned - [`RequiredKeys`](/lib/required-keys) - Constructs a union type by picking all required properties of object type `Type` - [`WritableKeys`](/lib/writable-keys) - Constructs a union type by picking all writable properties of object type `Type`, meaning their values can be reassigned ### Type checkers - [`Exact`](/lib/exact) - Returns `Type` when type `Type` and `Shape` are identical. Otherwise returns `never` - [`IsAny`](/lib/is-any) - Returns `true` when type `Type` is `any`. Otherwise returns `false` - [`IsNever`](/lib/is-never) - Returns `true` when type `Type` is `never`. Otherwise returns `false` - [`IsUnknown`](/lib/is-unknown) - Returns `true` when type `Type` is `unknown`. Otherwise returns `false` - [`IsTuple`](/lib/is-tuple) - Returns `Type` when type `Type` is tuple. Otherwise returns `never` - [`NonEmptyObject`](/lib/non-empty-object) - Returns `Object` when `Object` has at least one key. Otherwise returns `never` ### Arrays and Tuples - [`AnyArray`](/lib/any-array) - Matches `Array` or `ReadonlyArray` (`Type` is `any` by default) - [`ArrayOrSingle`](/lib/array-or-single) - Matches `Type` or `Type[]` - [`ElementOf`](/lib/element-of) - Constructs a type which equals to array element type for type `Type` - [`Head`](/lib/head) - Constructs a type which equals to first element in type `Type` - [`NonEmptyArray`](/lib/non-empty-array) - Matches array with at least one element of type `Type` - [`ReadonlyArrayOrSingle`](/lib/readonly-array-or-single) - Matches `Type` or `readonly Type[]` - [`Tail`](/lib/tail) - Constructs a type which equals to elements but first one in type `Type` - [`Tuple`](/lib/tuple) - Matches type constraint for tuple with elements of type `Type` (`any` by default) ### Change case - [`CamelCase`](/lib/camel-case) - Converts type `Type` to camel case (e.g. `camelCase`) - [`DeepCamelCaseProperties`](/lib/deep-camel-case-properties) - Constructs a type by picking all properties from type `Type` recursively and converting all of them to camel case ### Function types - [`AnyFunction`](/lib/any-function) - Matches function type with arguments type `Args` (`any[]` by default) and return type `ReturnType` (`any` by default) - [`PredicateFunction`](/lib/predicate-function) - Matches type constraint for type guard, meaning first argument is used in return type and return type is [type predicate](https://www.typescriptlang.org/docs/handbook/2/narrowing.html#using-type-predicates) - [`PredicateType`](/lib/predicate-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)`](/lib/functions/unreachable-case-error) - Matches runtime class instance type that helps check exhaustiveness for `value`. When `value` isn't `never`, it shows TypeScript error - [`assert(condition, message?)`](/lib/functions/assert) - 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)`](/lib/functions/create-factory-with-constraint) - Matches runtime function, which validates that type of `value` matches `Constraint` without changing resulting type of `value`. Ponyfill for [`satisfies` operator](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-4-9.html#the-satisfies-operator) - [`isExact()(actual)`](/lib/functions/is-exact) - Matches runtime function, which validates that type of `actual` equals to `Expected`. Otherwise shows TypeScript error - [`noop(..._args)`](/lib/functions/noop) - Matches runtime function that does nothing with arguments `_args` ## Built-in types TypeScript provides several [utility types](https://www.typescriptlang.org/docs/handbook/utility-types.html) to facilitate common type transformations. These utilities are available globally. - [`Awaited`](https://www.typescriptlang.org/docs/handbook/utility-types.html#awaitedtype) - 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`](https://www.typescriptlang.org/docs/handbook/2/template-literal-types.html#capitalizestringtype) - Converts the first character in the string to an uppercase equivalent - [`ConstructParameters`](https://www.typescriptlang.org/docs/handbook/utility-types.html#constructorparameterstype) - Constructs a tuple or array type from the types of a constructor function type `Type` - [`Exclude`](https://www.typescriptlang.org/docs/handbook/utility-types.html#excludeuniontype-excludedmembers) - Constructs a type by excluding from `UnionType` all union members that are assignable to `ExcludedMembers` - [`Extract`](https://www.typescriptlang.org/docs/handbook/utility-types.html#extracttype-union) - Constructs a type by extracting from `Type` all union members that are assignable to `Union` - [`InstanceType`](https://www.typescriptlang.org/docs/handbook/utility-types.html#instancetypetype) - Constructs a type consisting of the instance type of a constructor function in `Type` - [`Lowercase`](https://www.typescriptlang.org/docs/handbook/2/template-literal-types.html#lowercasestringtype) - Converts each character in the string to the lowercase equivalent - [`NonNullable`](https://www.typescriptlang.org/docs/handbook/utility-types.html#nonnullabletype) - Constructs a type by excluding null and undefined from `Type` - [`Omit`](https://www.typescriptlang.org/docs/handbook/utility-types.html#omittype-keys) - Constructs a type by picking all properties from `Type` and then removing `Keys` - [`Parameters`](https://www.typescriptlang.org/docs/handbook/utility-types.html#parameterstype) - Constructs a tuple type from the types used in the parameters of a function type `Type` - [`Partial`](https://www.typescriptlang.org/docs/handbook/utility-types.html#partialtype) - Constructs a type with all properties of `Type` set to optional - [`Pick`](https://www.typescriptlang.org/docs/handbook/utility-types.html#picktype-keys) - Constructs a type by picking the set of properties `Keys` from `Type` - [`Readonly`](https://www.typescriptlang.org/docs/handbook/utility-types.html#readonlytype) - Constructs a type with all properties of `Type` set to `readonly`, meaning the properties of the constructed type cannot be reassigned - [`Record`](https://www.typescriptlang.org/docs/handbook/utility-types.html#recordkeys-type) - Constructs an object type whose property keys are `Keys` and whose property values are `Type` - [`Required`](https://www.typescriptlang.org/docs/handbook/utility-types.html#requiredtype) - Constructs a type consisting of all properties of `Type` set to required - [`ReturnType`](https://www.typescriptlang.org/docs/handbook/utility-types.html#returntypetype) - Constructs a type consisting of the return type of function type `Type` parameter - [`Uncapitalize`](https://www.typescriptlang.org/docs/handbook/2/template-literal-types.html#uncapitalizestringtype) - Converts the first character in the string to a lowercase equivalent - [`Uppercase`](https://www.typescriptlang.org/docs/handbook/2/template-literal-types.html#uppercasestringtype) - Converts each character in the string to the uppercase version ## TypeScript dependency table | `ts-essentials` | `typescript` / type of dependency | | --------------- | ------------------------------------------------------------------------------------- | | `^9.4.0` | `^4.1.0` / [peer optional](https://github.com/ts-essentials/ts-essentials/issues/370) | | `^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](https://allcontributors.org/docs/en/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](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome! [Read more](./CONTRIBUTING.md)