Skip to content
Utility Types for TypeScript (provide migration from Flow's Utility Types)
Branch: master
Clone or download
Latest commit 868b599 Mar 3, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
experimental New test setup (#40) Dec 19, 2018
src Updated ci-script Mar 2, 2019
utils Cleaned up testType Dec 20, 2018
.editorconfig New test setup (#40) Dec 19, 2018
.gitignore updated scripts, build process and build workflow tools May 16, 2018
.npmignore updated scripts, build process and build workflow tools May 16, 2018
.prettierrc updated scripts, build process and build workflow tools May 16, 2018
CONTRIBUTING.md Added contributing guide Sep 18, 2018
LICENSE updated docs Jan 16, 2017
README.md Add Brand type (#67) Feb 24, 2019
jest.config.json Enabled value testing for dts-jest Dec 26, 2018
package-lock.json 3.4.1 Jan 19, 2019
package.json
tsconfig.build.json New test setup (#40) Dec 19, 2018
tsconfig.json
tslint.json New test setup (#40) Dec 19, 2018

README.md

utility-types

Collection of generic types for TypeScript, complementing built-in mapped types and aliases - think lodash for reusable types.

Latest Stable Version Build Status Dependency Status peerDependency Status License

NPM Downloads NPM Downloads

Found it useful? Want more updates? Show your support by giving a ⭐️

TypeScript compatibility notes

  • v1 - minimum TS v2.7.2
  • v2 - minimum TS v2.8.1 (rewritten to conditional types)
  • v3 - minimum TS v3.1.0

Motivation

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.

Goals

  • 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

Features

  • 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

Installation

npm install --save utility-types

Contributing Guide

We are open for contributions. If you're planning to contribute please make sure to read the contributing guide: CONTRIBUTING.md

Sponsor

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.

Let's fund issues in this repository


Table of Contents

Operations on sets

Operations on objects

Mapped Types

Flow's Utility Types

Deprecated API (use at own risk)

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

Operations on sets

SetIntersection<A, B> (same as Extract)

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

⇧ back to top

SetDifference<A, B> (same as Exclude)

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

⇧ back to top

SetComplement<A, A1>

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"

⇧ back to top

SymmetricDifference<A, B>

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"

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

import { FunctionKeys } from 'utility-types';

type MixedProps = { name: string; setName: (name: string) => void };
type FunctionKeysProps = FunctionKeys<MixedProps>;
// Expect: "setName"

⇧ back to top

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 };
type NonFunctionKeysProps = NonFunctionKeys<MixedProps>;
// Expect: "name"

⇧ back to top

Pick<T, K>

From T pick a set of properties K

(part of standard-lib)

Usage:

type Props = { name: string; age: number; visible: boolean };

type RequiredProps = Pick<Props, 'name'>;
// Expect: { name: string }

⇧ back to top

Omit<T, K>

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; }

⇧ back to top

PickByValue<T, ValueType>

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 }

⇧ back to top

OmitByValue<T, ValueType>

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 }

⇧ back to top

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 };

type DuplicatedProps = Intersection<Props, DefaultProps>;
// Expect: { age: number; }

⇧ back to top

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 };

type RequiredProps = Diff<Props, DefaultProps>;
// Expect: { name: string; visible: boolean; }

⇧ back to top

Subtract<T, T1>

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; }

⇧ back to top

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 };

type ReplacedProps = Overwrite<Props, NewProps>;
// Expect: { name: string; age: string; visible: boolean; }

⇧ back to top

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 };

type ExtendedProps = Assign<Props, NewProps>;
// Expect: { name: string; age: number; visible: boolean; other: string; }

⇧ back to top

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 };
type ReadonlyProps = ReadonlyKeys<Props>;
// Expect: "foo"

⇧ back to top

WritableKeys<T>

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"

⇧ back to top


Mapped Types

Partial<T>

Make all properties of object type optional

⇧ back to top

Required<T>

Make all properties of object type non-optional

⇧ back to top

Readonly<T>

Make all properties of object type readonly

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

import { Unionize } from 'utility-types';

type Props = { name: string; age: number; visible: boolean };

type UnionizedType = Unionize<Props>;
// Expect: { name: string; } | { age: number; } | { visible: boolean; }

⇧ back to top

PromiseType<T>

Obtain Promise resolve type

Usage:

import { PromiseType } from 'utility-types';

type Response = PromiseType<Promise<string>>;
// Expect: string

⇧ back to top

DeepReadonly<T>

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;
//     };
//   };
// }

⇧ back to top


DeepRequired<T>

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;
//     };
//   };
// }

⇧ back to top


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;
    };
  };
};
type RequiredNestedProps = DeepNonNullable<NestedProps>;
// Expect: {
//   first: {
//     second: {
//       name: string;
//     };
//   };
// }

⇧ back to top


DeepPartial<T>

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;
//     };
//   };
// }

⇧ back to top


Brand<T, U>

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"'.

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

import { $Keys } from 'utility-types';

type Props = { name: string; age: number; visible: boolean };

type PropsKeys = $Keys<Props>;
// Expect: "name" | "age" | "visible"

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

import { $Values } from 'utility-types';

type Props = { name: string; age: number; visible: boolean };

type PropsValues = $Values<Props>;
// Expect: string | number | boolean

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

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; }>

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

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; }

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

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

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

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

⇧ back to top

$Call<T>

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

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

import { $Shape } from 'utility-types';

type Props = { name: string; age: number; visible: boolean };

type PartialProps = $Shape<Props>;
// Expect: Partial<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:

import { $NonMaybeType } from 'utility-types';

type MaybeName = string | null;

type Name = $NonMaybeType<MaybeName>;
// Expect: string

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

import { Class } from 'utility-types';

class Store {}

function makeStore(storeClass: Class<Store>): Store {
  return new storeClass();
}

⇧ back to top


MIT License

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

You can’t perform that action at this time.