Features

• Providing a set of Common Types for TypeScript projects that are idiomatic and complementary to existing TypeScript Mapped Types so you don't need to copy them between the projects.
• Providing a set of Additional Types compatible with Flow's Utility Types to allow much easier migration to TypeScript.

Goals

• Quality - thoroughly tested for type correctness with type-testing library dts-jest
• Secure and minimal - no third-party dependencies
• No runtime cost - it's type-level only

Installation

1# NPM
2npm install utility-types
3
4# YARN
5yarn add utility-types

Compatibility Notes

TypeScript support

• v3.x.x - TypeScript v3.1+
• v2.x.x - TypeScript v2.8.1+
• v1.x.x - TypeScript v2.7.2+

Funding Issues

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.

Contributing

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

---

• (built-in) - types built-in TypeScript, no need to import

Table of Contents

Aliases & Type Guards

• Primitive
• isPrimitive
• Falsy
• isFalsy
• Nullish
• isNullish

Union operators

• 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>

Object operators

• 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>

Special operators

• ReturnType<T> (built-in)
• InstanceType<T> (built-in)
• PromiseType<T>
• Unionize<T>
• Brand<T, U>
• UnionToIntersection<U>

Flow's Utility Types

• $Keys<T>
• $Values<T>
• $ReadOnly<T>
• $Diff<T, U>
• $PropertyType<T, K>
• $ElementType<T, K>
• $Call<T>
• $Shape<T>
• $NonMaybeType<T>
• Class<T>
• mixed

Deprecated API (use at own risk)

• getReturnOfExpression() - from TS v2.0 it's better to use type-level ReturnType instead

---

Primitive

Type 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

isPrimitive

This is a TypeScript Typeguard for the Primitive type.

This can be useful to control the type of a parameter as the program flows. Example:

1const consumer = (param: Primitive[] | Primitive): string => {
2    if (isPrimitive(param)) {
3        // typeof param === Primitive
4        return String(param) + ' was Primitive';
5    }
6    // typeof param === Primitive[]
7    const resultArray = param
8        .map(consumer)
9        .map(rootString => '\n\t' + rootString);
10    return resultArray.reduce((comm, newV) => comm + newV, 'this was nested:');
11};

⇧ back to top

Falsy

Type representing falsy values in TypeScript: false | "" | 0 | null | undefined

Except NaN which cannot be represented as a type literal

isFalsy

1const consumer = (param: Falsy | string): string => {
2    if (isFalsy(param)) {
3        // typeof param === Falsy
4        return String(param) + ' was Falsy';
5    }
6    // typeof param === string
7    return param.toString();
8};

⇧ back to top

Nullish

Type representing nullish values in TypeScript: null | undefined

⇧ back to top

isNullish

1const consumer = (param: Nullish | string): string => {
2    if (isNullish(param)) {
3        // typeof param === Nullish
4        return String(param) + ' was Nullish';
5    }
6    // typeof param === string
7    return param.toString();
8};

⇧ back to top

SetIntersection<A, B> (same as Extract)

Set intersection of given union types A and B

Usage:

1import { SetIntersection } from 'utility-types';
2
3// Expect: "2" | "3"
4type ResultSet = SetIntersection<'1' | '2' | '3', '2' | '3' | '4'>;
5// Expect: () => void
6type ResultSetMixed = SetIntersection<string | number | (() => void), Function>;

⇧ back to top

SetDifference<A, B> (same as Exclude)

Set difference of given union types A and B

Usage:

1import { SetDifference } from 'utility-types';
2
3// Expect: "1"
4type ResultSet = SetDifference<'1' | '2' | '3', '2' | '3' | '4'>;
5// Expect: string | number
6type ResultSetMixed = SetDifference<string | number | (() => void), Function>;

⇧ back to top

SetComplement<A, A1>

Set complement of given union types A and (it's subset) A1

Usage:

1import { SetComplement } from 'utility-types';
2
3// Expect: "1"
4type ResultSet = SetComplement<'1' | '2' | '3', '2' | '3'>;

⇧ back to top

SymmetricDifference<A, B>

Set difference of union and intersection of given union types A and B

Usage:

1import { SymmetricDifference } from 'utility-types';
2
3// Expect: "1" | "4"
4type ResultSet = SymmetricDifference<'1' | '2' | '3', '2' | '3' | '4'>;

⇧ back to top

NonNullable<A>

Exclude null and undefined from set A

⇧ back to top

NonUndefined<A>

Exclude undefined from set A

⇧ back to top

Exclude<A, B>

Exclude subset B from set A

⇧ back to top

Extract<A, B>

Extract subset B from set A

⇧ back to top

Operations on objects

FunctionKeys<T>

Get union type of keys that are functions in object type T

Usage:

1import { FunctionKeys } from 'utility-types';
2
3type MixedProps = { name: string; setName: (name: string) => void };
4
5// Expect: "setName"
6type Keys = FunctionKeys<MixedProps>;

⇧ back to top

NonFunctionKeys<T>

Get union type of keys that are non-functions in object type T

Usage:

1import { NonFunctionKeys } from 'utility-types';
2
3type MixedProps = { name: string; setName: (name: string) => void };
4
5// Expect: "name"
6type Keys = NonFunctionKeys<MixedProps>;

⇧ back to top

MutableKeys<T>

Get union type of keys that are mutable (not readonly) in object type T

Alias: WritableKeys<T>

Usage:

1import { MutableKeys } from 'utility-types';
2
3type Props = { readonly foo: string; bar: number };
4
5// Expect: "bar"
6type Keys = MutableKeys<Props>;

⇧ back to top

ReadonlyKeys<T>

Get union type of keys that are readonly in object type T

Usage:

1import { ReadonlyKeys } from 'utility-types';
2
3type Props = { readonly foo: string; bar: number };
4
5// Expect: "foo"
6type Keys = ReadonlyKeys<Props>;

⇧ back to top

RequiredKeys<T>

Get union type of keys that are required in object type T

Usage:

1import { RequiredKeys } from 'utility-types';
2
3type Props = { req: number; reqUndef: number | undefined; opt?: string; optUndef?: number | undefined; };
4
5// Expect: "req" | "reqUndef"
6type Keys = RequiredKeys<Props>;

⇧ back to top

OptionalKeys<T>

Get union type of keys that are optional in object type T

Usage:

1import { OptionalKeys } from 'utility-types';
2
3type Props = { req: number; reqUndef: number | undefined; opt?: string; optUndef?: number | undefined; };
4
5// Expect: "opt" | "optUndef"
6type Keys = OptionalKeys<Props>;

⇧ back to top

Optional<T, K>

From T make a set of properties by key K become optional

Usage:

1import { Optional } from 'utility-types';
2
3type Props = { name: string; age: number; visible: boolean; };
4
5// Expect: { name?: string; age?: number; visible?: boolean; }
6type Props = Optional<Props>
7// Expect: { name: string; age?: number; visible?: boolean; }
8type Props = Optional<Props, 'age' | 'visible'>;

⇧ back to top

Pick<T, K> (built-in)

From T pick a set of properties by key K

Usage:

1type Props = { name: string; age: number; visible: boolean };
2
3// Expect: { age: number; }
4type Props = Pick<Props, 'age'>;

⇧ back to top

PickByValue<T, ValueType>

From T pick a set of properties by value matching ValueType. (Credit: Piotr Lewandowski)

Usage:

1import { PickByValue } from 'utility-types';
2
3type Props = { req: number; reqUndef: number | undefined; opt?: string; };
4
5// Expect: { req: number }
6type Props = PickByValue<Props, number>;
7// Expect: { req: number; reqUndef: number | undefined; }
8type Props = PickByValue<Props, number | undefined>;

⇧ back to top

PickByValueExact<T, ValueType>

From T pick a set of properties by value matching exact ValueType.

Usage:

1import { PickByValueExact } from 'utility-types';
2
3type Props = { req: number; reqUndef: number | undefined; opt?: string; };
4
5// Expect: { req: number }
6type Props = PickByValueExact<Props, number>;
7// Expect: { reqUndef: number | undefined; }
8type Props = PickByValueExact<Props, number | undefined>;

⇧ back to top

Omit<T, K>

From T remove a set of properties by key K

Usage:

1import { Omit } from 'utility-types';
2
3type Props = { name: string; age: number; visible: boolean };
4
5// Expect: { name: string; visible: boolean; }
6type Props = Omit<Props, 'age'>;

⇧ back to top

OmitByValue<T, ValueType>

From T remove a set of properties by value matching ValueType. (Credit: Piotr Lewandowski)

Usage:

1import { OmitByValue } from 'utility-types';
2
3type Props = { req: number; reqUndef: number | undefined; opt?: string; };
4
5// Expect: { reqUndef: number | undefined; opt?: string; }
6type Props = OmitByValue<Props, number>;
7// Expect: { opt?: string; }
8type Props = OmitByValue<Props, number | undefined>;

⇧ back to top

OmitByValueExact<T, ValueType>

From T remove a set of properties by value matching exact ValueType.

Usage:

1import { OmitByValueExact } from 'utility-types';
2
3type Props = { req: number; reqUndef: number | undefined; opt?: string; };
4
5// Expect: { reqUndef: number | undefined; opt?: string; }
6type Props = OmitByValueExact<Props, number>;
7// Expect: { req: number; opt?: string }
8type Props = OmitByValueExact<Props, number | undefined>;

⇧ back to top

Intersection<T, U>

From T pick properties that exist in U

Usage:

1import { Intersection } from 'utility-types';
2
3type Props = { name: string; age: number; visible: boolean };
4type DefaultProps = { age: number };
5
6// Expect: { age: number; }
7type DuplicatedProps = Intersection<Props, DefaultProps>;

⇧ back to top

Diff<T, U>

From T remove properties that exist in U

Usage:

1import { Diff } from 'utility-types';
2
3type Props = { name: string; age: number; visible: boolean };
4type DefaultProps = { age: number };
5
6// Expect: { name: string; visible: boolean; }
7type RequiredProps = Diff<Props, DefaultProps>;

⇧ back to top

Subtract<T, T1>

From T remove properties that exist in T1 (T1 has a subset of the properties of T)

Usage:

1import { Subtract } from 'utility-types';
2
3type Props = { name: string; age: number; visible: boolean };
4type DefaultProps = { age: number };
5
6// Expect: { name: string; visible: boolean; }
7type RequiredProps = Subtract<Props, DefaultProps>;

⇧ back to top

Overwrite<T, U>

From U overwrite properties to T

Usage:

1import { Overwrite } from 'utility-types';
2
3type Props = { name: string; age: number; visible: boolean };
4type NewProps = { age: string; other: string };
5
6// Expect: { name: string; age: string; visible: boolean; }
7type ReplacedProps = Overwrite<Props, NewProps>;

⇧ back to top

Assign<T, U>

From U assign properties to T (just like object assign)

Usage:

1import { Assign } from 'utility-types';
2
3type Props = { name: string; age: number; visible: boolean };
4type NewProps = { age: string; other: string };
5
6// Expect: { name: string; age: string; visible: boolean; other: string; }
7type ExtendedProps = Assign<Props, NewProps>;

⇧ back to top

ValuesType<T>

Get the union type of all the values in an object, tuple, array or array-like type T.

Usage:

1import { ValuesType } from 'utility-types';
2
3type Props = { name: string; age: number; visible: boolean };
4// Expect: string | number | boolean
5type PropsValues = ValuesType<Props>;
6
7type NumberArray = number[];
8// Expect: number
9type NumberItems = ValuesType<NumberArray>;
10
11type ReadonlyNumberTuple = readonly [1, 2];
12// Expect: 1 | 2
13type AnotherNumberUnion = ValuesType<NumberTuple>;
14
15type BinaryArray = Uint8Array;
16// Expect: number
17type BinaryItems = ValuesType<BinaryArray>;

⇧ back to top

Partial<T>

Make all properties of object type optional

⇧ back to top

Required<T, K>

From T make a set of properties by key K become required

Usage:

1import { Required } from 'utility-types';
2
3type Props = { name?: string; age?: number; visible?: boolean; };
4
5// Expect: { name: string; age: number; visible: boolean; }
6type Props = Required<Props>
7// Expect: { name?: string; age: number; visible: boolean; }
8type Props = Required<Props, 'age' | 'visible'>;

⇧ back to top

Readonly<T>

Make all properties of object type readonly

⇧ back to top

Mutable<T>

From T make all properties become mutable

Alias: Writable<T>

1import { Mutable } from 'utility-types';
2
3type Props = {
4  readonly name: string;
5  readonly age: number;
6  readonly visible: boolean;
7};
8
9// Expect: { name: string; age: number; visible: boolean; }
10Mutable<Props>;

⇧ back to top

ReturnType<T>

Obtain the return type of a function

⇧ back to top

InstanceType<T>

Obtain the instance type of a class

⇧ back to top

Unionize<T>

Disjoin object to form union of objects, each with single property

Usage:

1import { Unionize } from 'utility-types';
2
3type Props = { name: string; age: number; visible: boolean };
4
5// Expect: { name: string; } | { age: number; } | { visible: boolean; }
6type UnionizedType = Unionize<Props>;

⇧ back to top

PromiseType<T>

Obtain Promise resolve type

Usage:

1import { PromiseType } from 'utility-types';
2
3// Expect: string
4type Response = PromiseType<Promise<string>>;

⇧ back to top

DeepReadonly<T>

Readonly that works for deeply nested structures

Usage:

1import { DeepReadonly } from 'utility-types';
2
3type NestedProps = {
4  first: {
5    second: {
6      name: string;
7    };
8  };
9};
10
11// Expect: {
12//   readonly first: {
13//     readonly second: {
14//       readonly name: string;
15//     };
16//   };
17// }
18type ReadonlyNestedProps = DeepReadonly<NestedProps>;

⇧ back to top

DeepRequired<T>

Required that works for deeply nested structures

Usage:

1import { DeepRequired } from 'utility-types';
2
3type NestedProps = {
4  first?: {
5    second?: {
6      name?: string;
7    };
8  };
9};
10
11// Expect: {
12//   first: {
13//     second: {
14//       name: string;
15//     };
16//   };
17// }
18type RequiredNestedProps = DeepRequired<NestedProps>;

⇧ back to top

DeepNonNullable<T>

NonNullable that works for deeply nested structure

Usage:

1import { DeepNonNullable } from 'utility-types';
2
3type NestedProps = {
4  first?: null | {
5    second?: null | {
6      name?: string | null | undefined;
7    };
8  };
9};
10
11// Expect: {
12//   first: {
13//     second: {
14//       name: string;
15//     };
16//   };
17// }
18type RequiredNestedProps = DeepNonNullable<NestedProps>;

⇧ back to top

DeepPartial<T>

Partial that works for deeply nested structures

Usage:

1import { DeepPartial } from 'utility-types';
2
3type NestedProps = {
4  first: {
5    second: {
6      name: string;
7    };
8  };
9};
10
11// Expect: {
12//   first?: {
13//     second?: {
14//       name?: string;
15//     };
16//   };
17// }
18type PartialNestedProps = DeepPartial<NestedProps>;

⇧ back to top

Brand<T, U>

Define nominal type of U based on type of T. Similar to Opaque types in Flow.

Usage:

1import { Brand } from 'utility-types';
2
3type USD = Brand<number, "USD">
4type EUR = Brand<number, "EUR">
5
6const tax = 5 as USD;
7const usd = 10 as USD;
8const eur = 10 as EUR;
9
10function gross(net: USD): USD {
11  return (net + tax) as USD;
12}
13
14gross(usd); // ok
15gross(eur); // Type '"EUR"' is not assignable to type '"USD"'.

⇧ back to top

UnionToIntersection<U>

Get intersection type given union type U

Usage:

1import { UnionToIntersection } from 'utility-types';
2
3// Expect: { name: string } & { age: number } & { visible: boolean }
4UnionToIntersection<{ name: string } | { age: number } | { visible: boolean }>

⇧ back to top

---

Flow's Utility Types

$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:

1import { $Keys } from 'utility-types';
2
3type Props = { name: string; age: number; visible: boolean };
4
5// Expect: "name" | "age" | "visible"
6type PropsKeys = $Keys<Props>;

⇧ back to top

$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:

1import { $Values } from 'utility-types';
2
3type Props = { name: string; age: number; visible: boolean };
4
5// Expect: string | number | boolean
6type PropsValues = $Values<Props>;

⇧ back to top

$ReadOnly<T>

get the read-only version of a given object type T
https://flow.org/en/docs/types/utilities/#toc-readonly

Usage:

1import { $ReadOnly } from 'utility-types';
2
3type Props = { name: string; age: number; visible: boolean };
4
5// Expect: Readonly<{ name: string; age: number; visible: boolean; }>
6type ReadOnlyProps = $ReadOnly<Props>;

⇧ back to top

$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:

1import { $Diff } from 'utility-types';
2
3type Props = { name: string; age: number; visible: boolean };
4type DefaultProps = { age: number };
5
6// Expect: { name: string; visible: boolean; }
7type RequiredProps = $Diff<Props, DefaultProps>;

⇧ back to top

$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:

1import { $PropertyType } from 'utility-types';
2
3type Props = { name: string; age: number; visible: boolean };
4// Expect: string
5type NameType = $PropertyType<Props, 'name'>;
6
7type Tuple = [boolean, number];
8// Expect: boolean
9type A = $PropertyType<Tuple, '0'>;
10// Expect: number
11type B = $PropertyType<Tuple, '1'>;

⇧ back to top

$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:

1import { $ElementType } from 'utility-types';
2
3type Props = { name: string; age: number; visible: boolean };
4// Expect: string
5type NameType = $ElementType<Props, 'name'>;
6
7type Tuple = [boolean, number];
8// Expect: boolean
9type A = $ElementType<Tuple, 0>;
10// Expect: number
11type B = $ElementType<Tuple, 1>;
12
13type Arr = boolean[];
14// Expect: boolean
15type ItemsType = $ElementType<Arr, number>;
16
17type Obj = { [key: string]: number };
18// Expect: number
19type ValuesType = $ElementType<Obj, string>;

⇧ back to top

$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:

1import { $Call } from 'utility-types';
2
3// Common use-case
4const add = (amount: number) => ({ type: 'ADD' as 'ADD', payload: amount });
5type AddAction = $Call<typeof add>; // { type: 'ADD'; payload: number }
6
7// Examples migrated from Flow docs
8type ExtractPropType<T extends { prop: any }> = (arg: T) => T['prop'];
9type Obj = { prop: number };
10type PropType = $Call<ExtractPropType<Obj>>; // number
11// type Nope = $Call<ExtractPropType<{ nope: number }>>; // Error: argument doesn't match `Obj`.
12
13type ExtractReturnType<T extends () => any> = (arg: T) => ReturnType<T>;
14type Fn = () => number;
15type FnReturnType = $Call<ExtractReturnType<Fn>>; // number

⇧ back to top

$Shape<T>

Copies the shape of the type supplied, but marks every field optional.
https://flow.org/en/docs/types/utilities/#toc-shape

Usage:

1import { $Shape } from 'utility-types';
2
3type Props = { name: string; age: number; visible: boolean };
4
5// Expect: Partial<Props>
6type PartialProps = $Shape<Props>;

⇧ back to top

$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:

1import { $NonMaybeType } from 'utility-types';
2
3type MaybeName = string | null;
4
5// Expect: string
6type Name = $NonMaybeType<MaybeName>;

⇧ back to top

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:

1import { Class } from 'utility-types';
2
3
4function makeStore(storeClass: Class<Store>): Store {
5  return new storeClass();
6}

⇧ back to top

mixed

An arbitrary type that could be anything (same as unknown)
https://flow.org/en/docs/types/mixed

⇧ back to top

---

Related Projects

• ts-toolbelt - Higher type safety for TypeScript
• $mol_type - Collection of TypeScript meta types for complex logic

---

License

MIT License

Copyright (c) 2016 Piotr Witek mailto:piotrek.witek@gmail.com (http://piotrwitek.github.io)