utility-types
Advanced tools
The utility-types package provides a collection of utility types for TypeScript, which can be used to manipulate and transform type definitions in a type-safe manner. It includes types for common operations like picking, omitting, and mapping properties of other types, as well as more advanced utility types for conditional types, type inference, and more.
Transformation Types
Transformation types allow you to create new types based on existing ones by picking, omitting, or modifying their properties. For example, $Keys<T> extracts the keys of an object type T.
{"$Keys<T>": "Extracts the keys of an object type T as a union of literal types."}Conditional Types
Conditional types enable you to create types that depend on a condition. For instance, $Diff<T, U> creates a type by removing properties from T that are also in U.
{"$Diff<T, U>": "Computes the set difference of types T and U, essentially removing properties from T that are in U."}Mapped Types
Mapped types allow you to create new types by transforming properties of an existing type. $Call<F, T> is used to infer the return type of a function type F.
{"$Call<F, T>": "Infers the return type of a function type F when called with arguments of type T."}Type Inference Helpers
Type inference helpers assist in inferring types within other types. $ElementType<T, K> extracts the type of property K from type T.
{"$ElementType<T, K>": "Extracts the type of a property K from type T."}ts-essentials offers a wide range of utility types for TypeScript, similar to utility-types. It includes deep read-only types, writable types, and many more. It is comparable to utility-types but may have a different set of utilities or slightly different implementations.
type-fest is a collection of essential TypeScript types, with a focus on providing a rich set of utility types. It has a broad range of types, some of which overlap with utility-types, but it also includes unique types that cater to different use cases.
type-zoo contains a zoo of utility types for TypeScript. It is similar to utility-types in that it provides a variety of helper types to manipulate and compose TypeScript types. The specific types offered and their API might differ from utility-types.
Collection of utility types, complementing TypeScript built-in mapped types and aliases (think "lodash" for static types).
Found it useful? Want more updates?
Show your support by giving a :star:
:tada: Now updated to support TypeScript v3.7 :tada:
TypeScript.dts-jest# NPM
npm install utility-types
# YARN
yarn add utility-types
TypeScript support
v3.x.x - TypeScript v3.1+v2.x.x - TypeScript v2.8.1+v1.x.x - TypeScript v2.7.2+Utility-Types is an open-source project created by people investing their time for the benefit of our community.
Issues like bug fixes or feature requests can be very quickly resolved when funded through the IssueHunt platform.
I highly recommend adding a bounty to the issue that you're waiting for to attract some contributors willing to work on it.
We are open for contributions. If you're planning to contribute please make sure to read the contributing guide as it can save you from wasting your time: CONTRIBUTING.md
SetIntersection<A, B>SetDifference<A, B>SetComplement<A, A1>SymmetricDifference<A, B>Exclude<A, B> (built-in)Extract<A, B> (built-in)NonNullable<T> (built-in)NonUndefined<T>FunctionKeys<T>NonFunctionKeys<T>MutableKeys<T>ReadonlyKeys<T>RequiredKeys<T>OptionalKeys<T>Optional<T, K>Partial<T> (built-in)DeepPartial<T>Required<T, K>DeepRequired<T>Readonly<T> (built-in)DeepReadonly<T>Mutable<T>Pick<T, K> (built-in)Omit<T, K> (built-in)PickByValue<T, ValueType>PickByValueExact<T, ValueType>OmitByValue<T, ValueType>OmitByValueExact<T, ValueType>Intersection<T, U>Diff<T, U>Subtract<T, T1>Overwrite<T, U>Assign<T, U>ValuesType<T>ReturnType<T> (built-in)InstanceType<T> (built-in)PromiseType<T>Unionize<T>Brand<T, U>UnionToIntersection<U>$Keys<T>$Values<T>$ReadOnly<T>$Diff<T, U>$PropertyType<T, K>$ElementType<T, K>$Call<T>$Shape<T>$NonMaybeType<T>Class<T>mixedgetReturnOfExpression() - from TS v2.0 it's better to use type-level ReturnType insteadPrimitiveType representing primitive types in JavaScript, and thus TypeScript: string | number | bigint | boolean | symbol | null | undefined
You can test for singular of these types with typeof
isPrimitiveThis is a TypeScript Typeguard for the Primitive type.
This can be useful to control the type of a parameter as the program flows. Example:
const consumer = (param: Primitive[] | Primitive): string => {
if (isPrimitive(param)) {
// typeof param === Primitive
return String(param) + ' was Primitive';
}
// typeof param === Primitive[]
const resultArray = param
.map(consumer)
.map(rootString => '\n\t' + rootString);
return resultArray.reduce((comm, newV) => comm + newV, 'this was nested:');
};
FalsyType representing falsy values in TypeScript: false | "" | 0 | null | undefined
Except
NaNwhich cannot be represented as a type literal
isFalsyconst consumer = (param: Falsy | string): string => {
if (isFalsy(param)) {
// typeof param === Falsy
return String(param) + ' was Falsy';
}
// typeof param === string
return param.toString();
};
NullishType representing nullish values in TypeScript: null | undefined
isNullishconst consumer = (param: Nullish | string): string => {
if (isNullish(param)) {
// typeof param === Nullish
return String(param) + ' was Nullish';
}
// typeof param === string
return param.toString();
};
SetIntersection<A, B> (same as Extract)Set intersection of given union types A and B
Usage:
import { SetIntersection } from 'utility-types';
// Expect: "2" | "3"
type ResultSet = SetIntersection<'1' | '2' | '3', '2' | '3' | '4'>;
// Expect: () => void
type ResultSetMixed = SetIntersection<string | number | (() => void), Function>;
SetDifference<A, B> (same as Exclude)Set difference of given union types A and B
Usage:
import { SetDifference } from 'utility-types';
// Expect: "1"
type ResultSet = SetDifference<'1' | '2' | '3', '2' | '3' | '4'>;
// Expect: string | number
type ResultSetMixed = SetDifference<string | number | (() => void), Function>;
SetComplement<A, A1>Set complement of given union types A and (it's subset) A1
Usage:
import { SetComplement } from 'utility-types';
// Expect: "1"
type ResultSet = SetComplement<'1' | '2' | '3', '2' | '3'>;
SymmetricDifference<A, B>Set difference of union and intersection of given union types A and B
Usage:
import { SymmetricDifference } from 'utility-types';
// Expect: "1" | "4"
type ResultSet = SymmetricDifference<'1' | '2' | '3', '2' | '3' | '4'>;
NonNullable<A>Exclude null and undefined from set A
NonUndefined<A>Exclude undefined from set A
Exclude<A, B>Exclude subset B from set A
Extract<A, B>Extract subset B from set A
FunctionKeys<T>Get union type of keys that are functions in object type T
Usage:
import { FunctionKeys } from 'utility-types';
type MixedProps = { name: string; setName: (name: string) => void };
// Expect: "setName"
type Keys = FunctionKeys<MixedProps>;
NonFunctionKeys<T>Get union type of keys that are non-functions in object type T
Usage:
import { NonFunctionKeys } from 'utility-types';
type MixedProps = { name: string; setName: (name: string) => void };
// Expect: "name"
type Keys = NonFunctionKeys<MixedProps>;
MutableKeys<T>Get union type of keys that are mutable (not readonly) in object type T
Alias: WritableKeys<T>
Usage:
import { MutableKeys } from 'utility-types';
type Props = { readonly foo: string; bar: number };
// Expect: "bar"
type Keys = MutableKeys<Props>;
ReadonlyKeys<T>Get union type of keys that are readonly in object type T
Usage:
import { ReadonlyKeys } from 'utility-types';
type Props = { readonly foo: string; bar: number };
// Expect: "foo"
type Keys = ReadonlyKeys<Props>;
RequiredKeys<T>Get union type of keys that are required in object type T
Usage:
import { RequiredKeys } from 'utility-types';
type Props = { req: number; reqUndef: number | undefined; opt?: string; optUndef?: number | undefined; };
// Expect: "req" | "reqUndef"
type Keys = RequiredKeys<Props>;
OptionalKeys<T>Get union type of keys that are optional in object type T
Usage:
import { OptionalKeys } from 'utility-types';
type Props = { req: number; reqUndef: number | undefined; opt?: string; optUndef?: number | undefined; };
// Expect: "opt" | "optUndef"
type Keys = OptionalKeys<Props>;
Optional<T, K>From T make a set of properties by key K become optional
Usage:
import { Optional } from 'utility-types';
type Props = { name: string; age: number; visible: boolean; };
// Expect: { name?: string; age?: number; visible?: boolean; }
type Props = Optional<Props>
// Expect: { name: string; age?: number; visible?: boolean; }
type Props = Optional<Props, 'age' | 'visible'>;
Pick<T, K> (built-in)From T pick a set of properties by key K
Usage:
type Props = { name: string; age: number; visible: boolean };
// Expect: { age: number; }
type Props = Pick<Props, 'age'>;
PickByValue<T, ValueType>From T pick a set of properties by value matching ValueType.
(Credit: Piotr Lewandowski)
Usage:
import { PickByValue } from 'utility-types';
type Props = { req: number; reqUndef: number | undefined; opt?: string; };
// Expect: { req: number }
type Props = PickByValue<Props, number>;
// Expect: { req: number; reqUndef: number | undefined; }
type Props = PickByValue<Props, number | undefined>;
PickByValueExact<T, ValueType>From T pick a set of properties by value matching exact ValueType.
Usage:
import { PickByValueExact } from 'utility-types';
type Props = { req: number; reqUndef: number | undefined; opt?: string; };
// Expect: { req: number }
type Props = PickByValueExact<Props, number>;
// Expect: { reqUndef: number | undefined; }
type Props = PickByValueExact<Props, number | undefined>;
Omit<T, K>From T remove a set of properties by key K
Usage:
import { Omit } from 'utility-types';
type Props = { name: string; age: number; visible: boolean };
// Expect: { name: string; visible: boolean; }
type Props = Omit<Props, 'age'>;
OmitByValue<T, ValueType>From T remove a set of properties by value matching ValueType.
(Credit: Piotr Lewandowski)
Usage:
import { OmitByValue } from 'utility-types';
type Props = { req: number; reqUndef: number | undefined; opt?: string; };
// Expect: { reqUndef: number | undefined; opt?: string; }
type Props = OmitByValue<Props, number>;
// Expect: { opt?: string; }
type Props = OmitByValue<Props, number | undefined>;
OmitByValueExact<T, ValueType>From T remove a set of properties by value matching exact ValueType.
Usage:
import { OmitByValueExact } from 'utility-types';
type Props = { req: number; reqUndef: number | undefined; opt?: string; };
// Expect: { reqUndef: number | undefined; opt?: string; }
type Props = OmitByValueExact<Props, number>;
// Expect: { req: number; opt?: string }
type Props = OmitByValueExact<Props, number | undefined>;
Intersection<T, U>From T pick properties that exist in U
Usage:
import { Intersection } from 'utility-types';
type Props = { name: string; age: number; visible: boolean };
type DefaultProps = { age: number };
// Expect: { age: number; }
type DuplicatedProps = Intersection<Props, DefaultProps>;
Diff<T, U>From T remove properties that exist in U
Usage:
import { Diff } from 'utility-types';
type Props = { name: string; age: number; visible: boolean };
type DefaultProps = { age: number };
// Expect: { name: string; visible: boolean; }
type RequiredProps = Diff<Props, DefaultProps>;
Subtract<T, T1>From T remove properties that exist in T1 (T1 has a subset of the properties of T)
Usage:
import { Subtract } from 'utility-types';
type Props = { name: string; age: number; visible: boolean };
type DefaultProps = { age: number };
// Expect: { name: string; visible: boolean; }
type RequiredProps = Subtract<Props, DefaultProps>;
Overwrite<T, U>From U overwrite properties to T
Usage:
import { Overwrite } from 'utility-types';
type Props = { name: string; age: number; visible: boolean };
type NewProps = { age: string; other: string };
// Expect: { name: string; age: string; visible: boolean; }
type ReplacedProps = Overwrite<Props, NewProps>;
Assign<T, U>From U assign properties to T (just like object assign)
Usage:
import { Assign } from 'utility-types';
type Props = { name: string; age: number; visible: boolean };
type NewProps = { age: string; other: string };
// Expect: { name: string; age: string; visible: boolean; other: string; }
type ExtendedProps = Assign<Props, NewProps>;
ValuesType<T>Get the union type of all the values in an object, tuple, array or array-like type T.
Usage:
import { ValuesType } from 'utility-types';
type Props = { name: string; age: number; visible: boolean };
// Expect: string | number | boolean
type PropsValues = ValuesType<Props>;
type NumberArray = number[];
// Expect: number
type NumberItems = ValuesType<NumberArray>;
type ReadonlyNumberTuple = readonly [1, 2];
// Expect: 1 | 2
type AnotherNumberUnion = ValuesType<NumberTuple>;
type BinaryArray = Uint8Array;
// Expect: number
type BinaryItems = ValuesType<BinaryArray>;
Partial<T>Make all properties of object type optional
Required<T, K>From T make a set of properties by key K become required
Usage:
import { Required } from 'utility-types';
type Props = { name?: string; age?: number; visible?: boolean; };
// Expect: { name: string; age: number; visible: boolean; }
type Props = Required<Props>
// Expect: { name?: string; age: number; visible: boolean; }
type Props = Required<Props, 'age' | 'visible'>;
Readonly<T>Make all properties of object type readonly
Mutable<T>From T make all properties become mutable
Alias: Writable<T>
import { Mutable } from 'utility-types';
type Props = {
readonly name: string;
readonly age: number;
readonly visible: boolean;
};
// Expect: { name: string; age: number; visible: boolean; }
Mutable<Props>;
ReturnType<T>Obtain the return type of a function
InstanceType<T>Obtain the instance type of a class
Unionize<T>Disjoin object to form union of objects, each with single property
Usage:
import { Unionize } from 'utility-types';
type Props = { name: string; age: number; visible: boolean };
// Expect: { name: string; } | { age: number; } | { visible: boolean; }
type UnionizedType = Unionize<Props>;
PromiseType<T>Obtain Promise resolve type
Usage:
import { PromiseType } from 'utility-types';
// Expect: string
type Response = PromiseType<Promise<string>>;
DeepReadonly<T>Readonly that works for deeply nested structures
Usage:
import { DeepReadonly } from 'utility-types';
type NestedProps = {
first: {
second: {
name: string;
};
};
};
// Expect: {
// readonly first: {
// readonly second: {
// readonly name: string;
// };
// };
// }
type ReadonlyNestedProps = DeepReadonly<NestedProps>;
DeepRequired<T>Required that works for deeply nested structures
Usage:
import { DeepRequired } from 'utility-types';
type NestedProps = {
first?: {
second?: {
name?: string;
};
};
};
// Expect: {
// first: {
// second: {
// name: string;
// };
// };
// }
type RequiredNestedProps = DeepRequired<NestedProps>;
DeepNonNullable<T>NonNullable that works for deeply nested structure
Usage:
import { DeepNonNullable } from 'utility-types';
type NestedProps = {
first?: null | {
second?: null | {
name?: string | null | undefined;
};
};
};
// Expect: {
// first: {
// second: {
// name: string;
// };
// };
// }
type RequiredNestedProps = DeepNonNullable<NestedProps>;
DeepPartial<T>Partial that works for deeply nested structures
Usage:
import { DeepPartial } from 'utility-types';
type NestedProps = {
first: {
second: {
name: string;
};
};
};
// Expect: {
// first?: {
// second?: {
// name?: string;
// };
// };
// }
type PartialNestedProps = DeepPartial<NestedProps>;
Brand<T, U>Define nominal type of U based on type of T. Similar to Opaque types in Flow.
Usage:
import { Brand } from 'utility-types';
type USD = Brand<number, "USD">
type EUR = Brand<number, "EUR">
const tax = 5 as USD;
const usd = 10 as USD;
const eur = 10 as EUR;
function gross(net: USD): USD {
return (net + tax) as USD;
}
gross(usd); // ok
gross(eur); // Type '"EUR"' is not assignable to type '"USD"'.
UnionToIntersection<U>Get intersection type given union type U
Usage:
import { UnionToIntersection } from 'utility-types';
// Expect: { name: string } & { age: number } & { visible: boolean }
UnionToIntersection<{ name: string } | { age: number } | { visible: boolean }>
$Keys<T>get the union type of all the keys in an object type T
https://flow.org/en/docs/types/utilities/#toc-keys
Usage:
import { $Keys } from 'utility-types';
type Props = { name: string; age: number; visible: boolean };
// Expect: "name" | "age" | "visible"
type PropsKeys = $Keys<Props>;
$Values<T>get the union type of all the values in an object type T
https://flow.org/en/docs/types/utilities/#toc-values
Usage:
import { $Values } from 'utility-types';
type Props = { name: string; age: number; visible: boolean };
// Expect: string | number | boolean
type PropsValues = $Values<Props>;
$ReadOnly<T>get the read-only version of a given object type T
https://flow.org/en/docs/types/utilities/#toc-readonly
Usage:
import { $ReadOnly } from 'utility-types';
type Props = { name: string; age: number; visible: boolean };
// Expect: Readonly<{ name: string; age: number; visible: boolean; }>
type ReadOnlyProps = $ReadOnly<Props>;
$Diff<T, U>get the set difference of a given object types T and U (T \ U)
https://flow.org/en/docs/types/utilities/#toc-diff
Usage:
import { $Diff } from 'utility-types';
type Props = { name: string; age: number; visible: boolean };
type DefaultProps = { age: number };
// Expect: { name: string; visible: boolean; }
type RequiredProps = $Diff<Props, DefaultProps>;
$PropertyType<T, K>get the type of property of an object at a given key K
https://flow.org/en/docs/types/utilities/#toc-propertytype
Usage:
import { $PropertyType } from 'utility-types';
type Props = { name: string; age: number; visible: boolean };
// Expect: string
type NameType = $PropertyType<Props, 'name'>;
type Tuple = [boolean, number];
// Expect: boolean
type A = $PropertyType<Tuple, '0'>;
// Expect: number
type B = $PropertyType<Tuple, '1'>;
$ElementType<T, K>get the type of elements inside of array, tuple or object of type T, that matches the given index type K
https://flow.org/en/docs/types/utilities/#toc-elementtype
Usage:
import { $ElementType } from 'utility-types';
type Props = { name: string; age: number; visible: boolean };
// Expect: string
type NameType = $ElementType<Props, 'name'>;
type Tuple = [boolean, number];
// Expect: boolean
type A = $ElementType<Tuple, 0>;
// Expect: number
type B = $ElementType<Tuple, 1>;
type Arr = boolean[];
// Expect: boolean
type ItemsType = $ElementType<Arr, number>;
type Obj = { [key: string]: number };
// Expect: number
type ValuesType = $ElementType<Obj, string>;
$Call<T>get the return type of a given expression type
https://flow.org/en/docs/types/utilities/#toc-call
The built-in ReturnType can be used to accomplish the same goal, although it may have some subtle differences.
Usage:
import { $Call } from 'utility-types';
// Common use-case
const add = (amount: number) => ({ type: 'ADD' as 'ADD', payload: amount });
type AddAction = $Call<typeof add>; // { type: 'ADD'; payload: number }
// Examples migrated from Flow docs
type ExtractPropType<T extends { prop: any }> = (arg: T) => T['prop'];
type Obj = { prop: number };
type PropType = $Call<ExtractPropType<Obj>>; // number
// type Nope = $Call<ExtractPropType<{ nope: number }>>; // Error: argument doesn't match `Obj`.
type ExtractReturnType<T extends () => any> = (arg: T) => ReturnType<T>;
type Fn = () => number;
type FnReturnType = $Call<ExtractReturnType<Fn>>; // number
$Shape<T>Copies the shape of the type supplied, but marks every field optional.
https://flow.org/en/docs/types/utilities/#toc-shape
Usage:
import { $Shape } from 'utility-types';
type Props = { name: string; age: number; visible: boolean };
// Expect: Partial<Props>
type PartialProps = $Shape<Props>;
$NonMaybeType<T>Converts a type T to a non-maybe type. In other words, the values of $NonMaybeType<T> are the values of T except for null and undefined.
https://flow.org/en/docs/types/utilities/#toc-nonmaybe
Usage:
import { $NonMaybeType } from 'utility-types';
type MaybeName = string | null;
// Expect: string
type Name = $NonMaybeType<MaybeName>;
Class<T>Given a type T representing instances of a class C, the type Class is the type of the class C
https://flow.org/en/docs/types/utilities/#toc-class
* Differs from original Flow's util - implements only constructor part and won't include any static members. Additionally classes in Typescript are not treated as nominal
Usage:
import { Class } from 'utility-types';
function makeStore(storeClass: Class<Store>): Store {
return new storeClass();
}
An arbitrary type that could be anything (same as unknown)
https://flow.org/en/docs/types/mixed
ts-toolbelt - Higher type safety for TypeScript$mol_type - Collection of TypeScript meta types for complex logicCopyright (c) 2016 Piotr Witek mailto:piotrek.witek@gmail.com (http://piotrwitek.github.io)
FAQs
Utility Types Collection for TypeScript
We found that utility-types demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.
Security News
The Ultralytics' PyPI Package was compromised four times in one weekend through GitHub Actions cache poisoning and failure to rotate previously compromised API tokens.