Neuron Powered Motorization

    utility-types
    TypeScript icon, indicating that this package has built-in type declarations

    3.10.0 • Public • Published

    utility-types

    Collection of utility types, complementing TypeScript built-in mapped types and aliases (think "lodash" for static types).

    Latest Stable Version NPM Downloads NPM Downloads Bundlephobia Size

    Build Status Dependency Status License Join the community on Spectrum

    Found it useful? Want more updates?

    Show your support by giving a ⭐️

    Buy Me a Coffee Become a Patron



    What's new?

    🎉 Now updated to support TypeScript v3.7 🎉



    Features

    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.

    Let's fund issues in this repository

    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

    Union operators

    Object operators

    Special operators

    Flow's Utility Types

    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

    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

    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; visible: boolean };
     
    // Expect: { name: string; visible: boolean; }
    type 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:

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

    ⇧ back to top

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

    ⇧ 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 };
     
    // Expect: { age: number; }
    type DuplicatedProps = Intersection<Props, DefaultProps>;

    ⇧ 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 };
     
    // Expect: { name: string; visible: boolean; }
    type 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:

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

    ⇧ 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 };
     
    // Expect: { name: string; age: string; visible: boolean; }
    type ReplacedProps = Overwrite<Props, NewProps>;

    ⇧ 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 };
     
    // Expect: { name: string; age: number; visible: boolean; other: string; }
    type 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:

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

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

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

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

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

    ⇧ 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 };
     
    // Expect: { name: string; } | { age: number; } | { visible: boolean; }
    type UnionizedType = Unionize<Props>;

    ⇧ back to top

    PromiseType<T>

    Obtain Promise resolve type

    Usage:

    import { PromiseType } from 'utility-types';
     
    // Expect: string
    type Response = PromiseType<Promise<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;
        };
      };
    };
     
    // Expect: {
    //   readonly first: {
    //     readonly second: {
    //       readonly name: string;
    //     };
    //   };
    // }
    type ReadonlyNestedProps = DeepReadonly<NestedProps>;

    ⇧ back to top

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

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

    ⇧ back to top

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

    ⇧ back to top

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

    ⇧ back to top

    UnionToIntersection<U>

    Get intersection type given union type U

    Usage:

    import { UnionToIntersection } from 'utility-types';
     
    // Expect: { name: string } & { age: number } & { visible: boolean }
    UnionToIntersection<{ namestring } | { agenumber } | { visibleboolean }>

    ⇧ 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 };
     
    // Expect: "name" | "age" | "visible"
    type 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:

    import { $Values } from 'utility-types';
     
    type Props = { name: string; age: number; visible: boolean };
     
    // Expect: string | number | boolean
    type 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:

    import { $ReadOnly } from 'utility-types';
     
    type Props = { name: string; age: number; visible: boolean };
     
    // Expect: Readonly<{ name: string; age?: number | undefined; visible: boolean; }>
    type 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:

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

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

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

    ⇧ 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 };
     
    // Expect: Partial<Props>
    type 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:

    import { $NonMaybeType } from 'utility-types';
     
    type MaybeName = string | null;
     
    // Expect: string
    type 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:

    import { Class } from 'utility-types';
     
     
    function makeStore(storeClass: Class<Store>): Store {
      return new storeClass();
    }

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

    Install

    npm i utility-types

    DownloadsWeekly Downloads

    890,460

    Version

    3.10.0

    License

    MIT

    Unpacked Size

    62.2 kB

    Total Files

    21

    Last publish

    Collaborators

    • piotrwitek