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 ⭐
- v1 - minimum TS v2.7.2
- v2 - minimum TS v2.8.1 (rewritten to conditional types)
- v3 - minimum TS v3.1.0
The primary goal of this library is to provide a set of proven Utility Types that should complement existing TypeScript Mapped Types.
The secondary goal is to provide a few additional utility types compatible with Flow's Utility Types helping with gradual migration between "Flow" and "TypeScript" projects.
- provide a set of consistent Utility Types that are idiomatic and complementary to existing TypeScript Mapped Types
- provide migration from Flow's Utility Types
- clean idiomatic implementation based on composition of smaller generic types that are easy to follow and learn how they work
- Thoroughly tested for type correctness with type-testing library
dts-jest
- Safe with minimal footprint - no third-party dependencies
- No runtime cost - it's type-level only
npm install --save utility-types
We are open for contributions. If you're planning to contribute please make sure to read the contributing guide: CONTRIBUTING.md
Utility-Types is an independent open-source project created by people investing their free time for the benefit of our community.
If you are using Utility-Types please consider donating as this will guarantee the project will be updated and maintained in the long run.
Issues can be funded by anyone and the money will be transparently distributed to the contributors handling a particular issue.
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>
ReadonlyKeys<T>
WritableKeys<T>
Partial<T>
(*built-in)DeepPartial<T>
Required<T>
(*built-in)DeepRequired<T>
Readonly<T>
(*built-in)DeepReadonly<T>
Pick<T, K>
(*built-in)Omit<T, K>
WIPPickByValue<T, ValueType>
WIPOmitByValue<T, ValueType>
Intersection<T, U>
Diff<T, U>
Subtract<T, T1>
Overwrite<T, U>
Assign<T, U>
ReturnType<T>
(*built-in)InstanceType<T>
(*built-in)PromiseType<T>
Unionize<T>
Brand<T, U>
$Keys<T>
$Values<T>
$ReadOnly<T>
$Diff<T, U>
$PropertyType<T, K>
$ElementType<T, K>
$Call<T>
$Shape<T>
$NonMaybeType<T>
Class<T>
getReturnOfExpression()
- from TS v2.0 it's better to use type-levelReturnType
instead
Type representing primitive types in TypeScript: number | boolean | string | symbol
Type representing falsey values in TypeScript: null | undefined | false | 0 | ''
Except
NaN
which cannot be represented as a type literal
Set intersection of given union types A
and B
Usage:
import { SetIntersection } from 'utility-types';
type ResultSet = SetIntersection<'1' | '2' | '3', '2' | '3' | '4'>;
// Expect: "2" | "3"
type ResultSetMixed = SetIntersection<string | number | (() => void), Function>;
// Expect: () => void
Set difference of given union types A
and B
Usage:
import { SetDifference } from 'utility-types';
type ResultSet = SetDifference<'1' | '2' | '3', '2' | '3' | '4'>;
// Expect: "1"
type ResultSetMixed = SetDifference<string | number | (() => void), Function>;
// Expect: string | number
Set complement of given union types A
and (it's subset) A1
Usage:
import { SetComplement } from 'utility-types';
type ResultSet = SetComplement<'1' | '2' | '3', '2' | '3'>;
// Expect: "1"
Set difference of union and intersection of given union types A
and B
Usage:
import { SymmetricDifference } from 'utility-types';
type ResultSet = SymmetricDifference<'1' | '2' | '3', '2' | '3' | '4'>;
// Expect: "1" | "4"
Exclude null
and undefined
from set A
Exclude undefined
from set A
Exclude subset B
from set A
Extract subset B
from set A
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 };
type FunctionKeysProps = FunctionKeys<MixedProps>;
// Expect: "setName"
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 };
type NonFunctionKeysProps = NonFunctionKeys<MixedProps>;
// Expect: "name"
From T
pick a set of properties K
(part of built-in)
Usage:
type Props = { name: string; age: number; visible: boolean };
type RequiredProps = Pick<Props, 'name'>;
// Expect: { name: string }
From T
remove a set of properties K
Usage:
import { Omit } from 'utility-types';
type Props = { name: string; age: number; visible: boolean };
type RequiredProps = Omit<Props, 'age'>;
// Expect: { name: string; visible: boolean; }
From T
pick a set of properties with value type of ValueType
.
Credit: Piotr Lewandowski
Usage:
import { PickByValue } from 'utility-types';
type Props = { name: string; age: number; visible: boolean };
type RequiredProps = PickByValue<Props, string | number>;
// Expect: { name: string; age: number }
From T
remove a set of properties with value type of ValueType
.
Credit: Piotr Lewandowski
Usage:
import { OmitByValue } from 'utility-types';
type Props = { name: string; age: number; visible: boolean };
type RequiredProps = OmitByValue<Props, string | number>;
// Expect: { visible: boolean }
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 };
type DuplicatedProps = Intersection<Props, DefaultProps>;
// Expect: { age: number; }
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 };
type RequiredProps = Diff<Props, DefaultProps>;
// Expect: { name: string; visible: boolean; }
From T
remove properties that exist in T1
(T1
is a subtype of T
)
Usage:
import { Subtract } from 'utility-types';
type Props = { name: string; age: number; visible: boolean };
type DefaultProps = { age: number };
type RequiredProps = Subtract<Props, DefaultProps>;
// Expect: { name: string; visible: boolean; }
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 };
type ReplacedProps = Overwrite<Props, NewProps>;
// Expect: { name: string; age: string; visible: boolean; }
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 };
type ExtendedProps = Assign<Props, NewProps>;
// Expect: { name: string; age: number; visible: boolean; other: string; }
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 };
type ReadonlyProps = ReadonlyKeys<Props>;
// Expect: "foo"
Get union type of keys that are writable (not readonly) in object type T
Usage:
import { WritableKeys } from 'utility-types';
type Props = { readonly foo: string; bar: number };
type WritableProps = WritableKeys<Props>;
// Expect: "bar"
Make all properties of object type optional
Make all properties of object type non-optional
Make all properties of object type readonly
Obtain the return type of a function
Obtain the instance type of a class
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 };
type UnionizedType = Unionize<Props>;
// Expect: { name: string; } | { age: number; } | { visible: boolean; }
Obtain Promise resolve type
Usage:
import { PromiseType } from 'utility-types';
type Response = PromiseType<Promise<string>>;
// Expect: string
Readonly that works for deeply nested structures
Usage:
import { DeepReadonly } from 'utility-types';
type NestedProps = {
first: {
second: {
name: string;
};
};
};
type ReadonlyNestedProps = DeepReadonly<NestedProps>;
// Expect: {
// readonly first: {
// readonly second: {
// readonly name: string;
// };
// };
// }
Required that works for deeply nested structures
Usage:
import { DeepRequired } from 'utility-types';
type NestedProps = {
first?: {
second?: {
name?: string;
};
};
};
type RequiredNestedProps = DeepRequired<NestedProps>;
// Expect: {
// first: {
// second: {
// name: string;
// };
// };
// }
NonNullable that works for deeply nested structure
Usage:
import { DeepNonNullable } from 'utility-types';
type NestedProps = {
first?: null | {
second?: null | {
name?: string | null | undefined;
};
};
};
type RequiredNestedProps = DeepNonNullable<NestedProps>;
// Expect: {
// first: {
// second: {
// name: string;
// };
// };
// }
Partial that works for deeply nested structures
Usage:
import { DeepPartial } from 'utility-types';
type NestedProps = {
first: {
second: {
name: string;
};
};
};
type PartialNestedProps = DeepPartial<NestedProps>;
// Expect: {
// first?: {
// second?: {
// name?: string;
// };
// };
// }
Define nominal type of U
based on type of T
.
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"'.
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 };
type PropsKeys = $Keys<Props>;
// Expect: "name" | "age" | "visible"
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 };
type PropsValues = $Values<Props>;
// Expect: string | number | boolean
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 };
type ReadOnlyProps = $ReadOnly<Props>;
// Expect: Readonly<{ name: string; age?: number | undefined; visible: boolean; }>
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 };
type RequiredProps = $Diff<Props, DefaultProps>;
// Expect: { name: string; visible: boolean; }
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 };
type NameType = $PropertyType<Props, 'name'>;
// Expect: string
type Tuple = [boolean, number];
type A = $PropertyType<Tuple, '0'>;
// Expect: boolean
type B = $PropertyType<Tuple, '1'>;
// Expect: number
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 };
type NameType = $ElementType<Props, 'name'>;
// Expect: string
type Tuple = [boolean, number];
type A = $ElementType<Tuple, 0>;
// Expect: boolean
type B = $ElementType<Tuple, 1>;
// Expect: number
type Arr = boolean[];
type ItemsType = $ElementType<Arr, number>;
// Expect: boolean
type Obj = { [key: string]: number };
type ValuesType = $ElementType<Obj, string>;
// Expect: number
get the return type of a given expression type https://flow.org/en/docs/types/utilities/#toc-call
Usage:
import { $Call } from 'utility-types';
// Common use-case
const add = (amount: number) => ({ type: 'ADD' as 'ADD', payload: amount });
type AddAction = $Call<typeof returnOfIncrement>; // { 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
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 };
type PartialProps = $Shape<Props>;
// Expect: Partial<Props>
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;
type Name = $NonMaybeType<MaybeName>;
// Expect: string
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();
}
MIT License
Copyright (c) 2016 Piotr Witek mailto:piotrek.witek@gmail.com (http://piotrwitek.github.io)