Utility Types Collection for TypeScript
npm install utility-typesCollection 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:
:tada: _Now updated to support TypeScript v3.7_ :tada:
* 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.
* 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
``bashNPM
npm install 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
* isNullishUnion operators
SetIntersection _(built-in)_ _(built-in)_* FunctionKeys
* NonFunctionKeys
* MutableKeys
* ReadonlyKeys
* RequiredKeys
* OptionalKeys
* Optional
* Partial
* DeepPartial
* Required
* DeepRequired
* Readonly
* DeepReadonly
* Mutable
* Pick _(built-in)_
* Omit
* PickByValue
* PickByValueExact
* OmitByValue
* OmitByValueExact
* Intersection
* Diff
* Subtract
* Overwrite
* Assign
* ValuesType
* ReturnType
* InstanceType
* PromiseType
* Unionize
* Brand
* UnionToIntersection
* $Keys
* $Values
* $ReadOnly
* $Diff
* $PropertyType
* $ElementType
* $Call
* $Shape
* $NonMaybeType
* Class
* mixed
- from TS v2.0 it's better to use type-level ReturnType instead---
$3
Type representing primitive types in JavaScript, and thus TypeScript:
string | number | bigint | boolean | symbol | null | undefinedtypeof$3
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:
`ts
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:');
};
`$3
Type representing falsy values in TypeScript:
false | "" | 0 | null | undefined
> Except NaN which cannot be represented as a type literal$3
`ts
const consumer = (param: Falsy | string): string => {
if (isFalsy(param)) {
// typeof param === Falsy
return String(param) + ' was Falsy';
}
// typeof param === string
return param.toString();
};
`$3
Type representing nullish values in TypeScript:
null | undefined$3
`ts
const consumer = (param: Nullish | string): string => {
if (isNullish(param)) {
// typeof param === Nullish
return String(param) + ' was Nullish';
}
// typeof param === string
return param.toString();
};
`$3
Set intersection of given union types
A and BUsage:
`ts
import { SetIntersection } from 'utility-types';// Expect: "2" | "3"
type ResultSet = SetIntersection<'1' | '2' | '3', '2' | '3' | '4'>;
// Expect: () => void
type ResultSetMixed = SetIntersection void), Function>;
`$3
Set difference of given union types
A and BUsage:
`ts
import { SetDifference } from 'utility-types';// Expect: "1"
type ResultSet = SetDifference<'1' | '2' | '3', '2' | '3' | '4'>;
// Expect: string | number
type ResultSetMixed = SetDifference void), Function>;
`$3
Set complement of given union types
A and (it's subset) A1Usage:
`ts
import { SetComplement } from 'utility-types';// Expect: "1"
type ResultSet = SetComplement<'1' | '2' | '3', '2' | '3'>;
`$3
Set difference of union and intersection of given union types
A and BUsage:
`ts
import { SymmetricDifference } from 'utility-types';// Expect: "1" | "4"
type ResultSet = SymmetricDifference<'1' | '2' | '3', '2' | '3' | '4'>;
`$3
Exclude
null and undefined from set A$3
Exclude
undefined from set A$3
Exclude subset
B from set A$3
Extract subset
B from set AOperations on objects
$3
Get union type of keys that are functions in object type
TUsage:
`ts
import { FunctionKeys } from 'utility-types';type MixedProps = { name: string; setName: (name: string) => void };
// Expect: "setName"
type Keys = FunctionKeys;
`$3
Get union type of keys that are non-functions in object type
TUsage:
`ts
import { NonFunctionKeys } from 'utility-types';type MixedProps = { name: string; setName: (name: string) => void };
// Expect: "name"
type Keys = NonFunctionKeys;
`$3
Get union type of keys that are mutable (not readonly) in object type
TAlias:
WritableKeysUsage:
`ts
import { MutableKeys } from 'utility-types';type Props = { readonly foo: string; bar: number };
// Expect: "bar"
type Keys = MutableKeys;
`$3
Get union type of keys that are readonly in object type
TUsage:
`ts
import { ReadonlyKeys } from 'utility-types';type Props = { readonly foo: string; bar: number };
// Expect: "foo"
type Keys = ReadonlyKeys;
`$3
Get union type of keys that are required in object type
TUsage:
`ts
import { RequiredKeys } from 'utility-types';type Props = { req: number; reqUndef: number | undefined; opt?: string; optUndef?: number | undefined; };
// Expect: "req" | "reqUndef"
type Keys = RequiredKeys;
`$3
Get union type of keys that are optional in object type
TUsage:
`ts
import { OptionalKeys } from 'utility-types';type Props = { req: number; reqUndef: number | undefined; opt?: string; optUndef?: number | undefined; };
// Expect: "opt" | "optUndef"
type Keys = OptionalKeys;
`$3
From
T make a set of properties by key K become optionalUsage:
`ts
import { Optional } from 'utility-types';type Props = { name: string; age: number; visible: boolean; };
// Expect: { name?: string; age?: number; visible?: boolean; }
type Props = Optional
// Expect: { name: string; age?: number; visible?: boolean; }
type Props = Optional;
`
$3
From
T pick a set of properties by key KUsage:
`ts
type Props = { name: string; age: number; visible: boolean };// Expect: { age: number; }
type Props = Pick;
`$3
From
T pick a set of properties by value matching ValueType.
_(Credit: Piotr Lewandowski)_Usage:
`ts
import { PickByValue } from 'utility-types';type Props = { req: number; reqUndef: number | undefined; opt?: string; };
// Expect: { req: number }
type Props = PickByValue;
// Expect: { req: number; reqUndef: number | undefined; }
type Props = PickByValue;
`$3
From
T pick a set of properties by value matching exact ValueType.Usage:
`ts
import { PickByValueExact } from 'utility-types';type Props = { req: number; reqUndef: number | undefined; opt?: string; };
// Expect: { req: number }
type Props = PickByValueExact;
// Expect: { reqUndef: number | undefined; }
type Props = PickByValueExact;
`$3
From
T remove a set of properties by key KUsage:
`ts
import { Omit } from 'utility-types';type Props = { name: string; age: number; visible: boolean };
// Expect: { name: string; visible: boolean; }
type Props = Omit;
`$3
From
T remove a set of properties by value matching ValueType.
_(Credit: Piotr Lewandowski)_Usage:
`ts
import { OmitByValue } from 'utility-types';type Props = { req: number; reqUndef: number | undefined; opt?: string; };
// Expect: { reqUndef: number | undefined; opt?: string; }
type Props = OmitByValue;
// Expect: { opt?: string; }
type Props = OmitByValue;
`$3
From
T remove a set of properties by value matching exact ValueType.Usage:
`ts
import { OmitByValueExact } from 'utility-types';type Props = { req: number; reqUndef: number | undefined; opt?: string; };
// Expect: { reqUndef: number | undefined; opt?: string; }
type Props = OmitByValueExact;
// Expect: { req: number; opt?: string }
type Props = OmitByValueExact;
`$3
From
T pick properties that exist in UUsage:
`ts
import { Intersection } from 'utility-types';type Props = { name: string; age: number; visible: boolean };
type DefaultProps = { age: number };
// Expect: { age: number; }
type DuplicatedProps = Intersection;
`$3
From
T remove properties that exist in UUsage:
`ts
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;
`$3
From
T remove properties that exist in T1 (T1 has a subset of the properties of T)Usage:
`ts
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;
`$3
From
U overwrite properties to TUsage:
`ts
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;
`$3
From
U assign properties to T (just like object assign)Usage:
`ts
import { Assign } from 'utility-types';type Props = { name: string; age: number; visible: boolean };
type NewProps = { age: string; other: string };
// Expect: { name: string; age: string; visible: boolean; other: string; }
type ExtendedProps = Assign;
`$3
Get the union type of all the values in an object, tuple, array or array-like type
T.Usage:
`ts
import { ValuesType } from 'utility-types';type Props = { name: string; age: number; visible: boolean };
// Expect: string | number | boolean
type PropsValues = ValuesType;
type NumberArray = number[];
// Expect: number
type NumberItems = ValuesType;
type ReadonlyNumberTuple = readonly [1, 2];
// Expect: 1 | 2
type AnotherNumberUnion = ValuesType;
type BinaryArray = Uint8Array;
// Expect: number
type BinaryItems = ValuesType;
`$3
Make all properties of object type optional
$3
From
T make a set of properties by key K become requiredUsage:
`ts
import { Required } from 'utility-types';type Props = { name?: string; age?: number; visible?: boolean; };
// Expect: { name: string; age: number; visible: boolean; }
type Props = Required
// Expect: { name?: string; age: number; visible: boolean; }
type Props = Required;
`$3
Make all properties of object type readonly
$3
From
T make all properties become mutableAlias:
Writable`ts
import { Mutable } from 'utility-types';type Props = {
readonly name: string;
readonly age: number;
readonly visible: boolean;
};
// Expect: { name: string; age: number; visible: boolean; }
Mutable;
`$3
Obtain the return type of a function
$3
Obtain the instance type of a class
$3
Disjoin object to form union of objects, each with single property
Usage:
`ts
import { Unionize } from 'utility-types';type Props = { name: string; age: number; visible: boolean };
// Expect: { name: string; } | { age: number; } | { visible: boolean; }
type UnionizedType = Unionize;
`$3
Obtain Promise resolve type
Usage:
`ts
import { PromiseType } from 'utility-types';// Expect: string
type Response = PromiseType>;
`$3
Readonly that works for deeply nested structures
Usage:
`ts
import { DeepReadonly } from 'utility-types';type NestedProps = {
first: {
second: {
name: string;
};
};
};
// Expect: {
// readonly first: {
// readonly second: {
// readonly name: string;
// };
// };
// }
type ReadonlyNestedProps = DeepReadonly;
`$3
Required that works for deeply nested structures
Usage:
`ts
import { DeepRequired } from 'utility-types';type NestedProps = {
first?: {
second?: {
name?: string;
};
};
};
// Expect: {
// first: {
// second: {
// name: string;
// };
// };
// }
type RequiredNestedProps = DeepRequired;
`$3
NonNullable that works for deeply nested structure
Usage:
`ts
import { DeepNonNullable } from 'utility-types';type NestedProps = {
first?: null | {
second?: null | {
name?: string | null | undefined;
};
};
};
// Expect: {
// first: {
// second: {
// name: string;
// };
// };
// }
type RequiredNestedProps = DeepNonNullable;
`$3
Partial that works for deeply nested structures
Usage:
`ts
import { DeepPartial } from 'utility-types';type NestedProps = {
first: {
second: {
name: string;
};
};
};
// Expect: {
// first?: {
// second?: {
// name?: string;
// };
// };
// }
type PartialNestedProps = DeepPartial;
`$3
Define nominal type of
U based on type of T. Similar to Opaque types in Flow.Usage:
`ts
import { Brand } from 'utility-types';type USD = Brand
type EUR = Brand
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"'.
`$3
Get intersection type given union type
UUsage:
`ts
import { UnionToIntersection } from 'utility-types';// Expect: { name: string } & { age: number } & { visible: boolean }
UnionToIntersection<{ name: string } | { age: number } | { visible: boolean }>
`---
Flow's Utility Types
$3
get the union type of all the keys in an object type
T
https://flow.org/en/docs/types/utilities/#toc-keysUsage:
`ts
import { $Keys } from 'utility-types';type Props = { name: string; age: number; visible: boolean };
// Expect: "name" | "age" | "visible"
type PropsKeys = $Keys;
`$3
get the union type of all the values in an object type
T
https://flow.org/en/docs/types/utilities/#toc-valuesUsage:
`ts
import { $Values } from 'utility-types';type Props = { name: string; age: number; visible: boolean };
// Expect: string | number | boolean
type PropsValues = $Values;
`$3
get the read-only version of a given object type
T
https://flow.org/en/docs/types/utilities/#toc-readonlyUsage:
`ts
import { $ReadOnly } from 'utility-types';type Props = { name: string; age: number; visible: boolean };
// Expect: Readonly<{ name: string; age: number; visible: boolean; }>
type ReadOnlyProps = $ReadOnly;
`$3
get the set difference of a given object types
T and U (T \ U)
https://flow.org/en/docs/types/utilities/#toc-diffUsage:
`ts
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;
`$3
get the type of property of an object at a given key
K
https://flow.org/en/docs/types/utilities/#toc-propertytypeUsage:
`ts
import { $PropertyType } from 'utility-types';type Props = { name: string; age: number; visible: boolean };
// Expect: string
type NameType = $PropertyType;
type Tuple = [boolean, number];
// Expect: boolean
type A = $PropertyType;
// Expect: number
type B = $PropertyType;
`$3
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-elementtypeUsage:
`ts
import { $ElementType } from 'utility-types';type Props = { name: string; age: number; visible: boolean };
// Expect: string
type NameType = $ElementType;
type Tuple = [boolean, number];
// Expect: boolean
type A = $ElementType;
// Expect: number
type B = $ElementType;
type Arr = boolean[];
// Expect: boolean
type ItemsType = $ElementType;
type Obj = { [key: string]: number };
// Expect: number
type ValuesType = $ElementType;
`$3
get the return type of a given expression type
https://flow.org/en/docs/types/utilities/#toc-call
ReturnType can be used to accomplish the same goal, although it may have some subtle differences.Usage:
`ts
import { $Call } from 'utility-types';// Common use-case
const add = (amount: number) => ({ type: 'ADD' as 'ADD', payload: amount });
type AddAction = $Call; // { type: 'ADD'; payload: number }
// Examples migrated from Flow docs
type ExtractPropType = (arg: T) => T['prop'];
type Obj = { prop: number };
type PropType = $Call>; // number
// type Nope = $Call>; // Error: argument doesn't match
Obj.type ExtractReturnType any> = (arg: T) => ReturnType;
type Fn = () => number;
type FnReturnType = $Call>; // number
`$3
Copies the shape of the type supplied, but marks every field optional.
https://flow.org/en/docs/types/utilities/#toc-shape
Usage:
`ts
import { $Shape } from 'utility-types';type Props = { name: string; age: number; visible: boolean };
// Expect: Partial
type PartialProps = $Shape;
`$3
Converts a type
T to a non-maybe type. In other words, the values of $NonMaybeType are the values of T except for null and undefined.
https://flow.org/en/docs/types/utilities/#toc-nonmaybeUsage:
`ts
import { $NonMaybeType } from 'utility-types';type MaybeName = string | null;
// Expect: string
type Name = $NonMaybeType;
`$3
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:
`ts
import { Class } from 'utility-types';
function makeStore(storeClass: Class): Store {
return new storeClass();
}
`$3
An arbitrary type that could be anything (same as
unknown)
https://flow.org/en/docs/types/mixed---
Related Projects
ts-toolbelt - Higher type safety for TypeScript
- $mol_type` - Collection of TypeScript meta types for complex logic---
Copyright (c) 2016 Piotr Witek