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:

---

What's new?

:tada: Added new utilities :tada:

---

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

# NPM
npm install utility-types

# YARN
yarn 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>
• UnionKeys<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:

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:');
};

⇧ 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

const consumer = (param: Falsy | string): string => {
    if (isFalsy(param)) {
        // typeof param === Falsy
        return String(param) + ' was Falsy';
    }
    // typeof param === string
    return param.toString();
};

⇧ back to top

Nullish

Type representing nullish values in TypeScript: null | undefined

⇧ back to top

isNullish

const consumer = (param: Nullish | string): string => {
    if (isNullish(param)) {
        // typeof param === Nullish
        return String(param) + ' was Nullish';
    }
    // typeof param === string
    return param.toString();
};

⇧ back to top

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

⇧ back to top

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

⇧ back to top

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

⇧ 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';

// Expect: "1" | "4"
type 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:

import { FunctionKeys } from 'utility-types';

type MixedProps = { name: string; setName: (name: string) => void };

// Expect: "setName"
type Keys = FunctionKeys<MixedProps>;

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

// Expect: "name"
type 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:

import { MutableKeys } from 'utility-types';

type Props = { readonly foo: string; bar: number };

// Expect: "bar"
type Keys = MutableKeys<Props>;

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

// Expect: "foo"
type Keys = ReadonlyKeys<Props>;

⇧ back to top

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

⇧ back to top

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

⇧ back to top

UnionKeys<U>

Get keys of all objects in the union type U

Usage:

import { UnionKeys } from 'utility-types';

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

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

⇧ back to top

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

⇧ back to top

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

⇧ back to top

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

⇧ back to top

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

⇧ back to top

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;