Package Exports
- utility-types
This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (utility-types) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.
Readme
utility-types
Utility Types Collection for TypeScript
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 (inspired by Set Theory and functional languages) that should complement existing TypeScript Mapped Types.
The secondary goal is to provide additional utility types compatible with Flow's Utility Types. Flow and TypeScript have a lot in common. By using this library TypeScript Developers will become more familiar with differences to "Flow" and extend their static-typing toolbelt. Moreover it can help to migrate between "Flow" and "TypeScript" projects much easier.
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
- Tested for type correctness with type-testing library
dts-jest - Minimal footprint - type-level only, no third-party dependencies
Installation
npm install --save utility-typesContributing Guide
If you're planning to contribute please make sure to read the contributing guide: CONTRIBUTING.md
Sponsor
If you like what we're doing here, you can help us by funding the work on specific issues that you choose by using IssueHunt.io!
This gives you the power to prioritize our work and support project contributors. Moreover it'll guarantee the project will be updated and maintained in the long run.
I keep sponsor anonymity by default but if you'd like your brand to be featured in this repo, please contact me at: piotrek.witek@gmail.com
Table of Contents
Operations on sets
SetIntersection<A, B>SetDifference<A, B>SetComplement<A, A1>SymmetricDifference<A, B>NonNullable<A>(*standard-lib)NonUndefined<A>Exclude<A, B>(*standard-lib)Extract<A, B>(*standard-lib)
Operations on objects
FunctionKeys<T>NonFunctionKeys<T>Pick<T, K>(*standard-lib)Omit<T, K>Intersection<T, U>Diff<T, U>Subtract<T, T1>Overwrite<T, U>Assign<T, U>
Mapped Types
Partial<T>(*standard-lib)Required<T>(*standard-lib)Readonly<T>(*standard-lib)ReturnType<T>(*standard-lib)InstanceType<T>(*standard-lib)Unionize<T>PromiseType<T>(replaced deprecatedUnboxPromise<T>)DeepReadonly<T>DeepRequired<T>DeepNonNullable<T>
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>
Deprecated API (use at own risk)
getReturnOfExpression()- from TS v2.0 it's better to use type-levelReturnTypeinstead
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: () => voidSetDifference<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 | numberSetComplement<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"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"NonNullable<A>
Exclude null and undefined from set A
NonUndefined<A>
Exclude undefined from set A
Exclude<A, B>
Exclude subset B from set A
Extract<A, B>
Extract subset B from set A
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"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"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 }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; }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; }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; }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; }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; }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; }Mapped Types
Partial<T>
Make all properties of object type optional
Required<T>
Make all properties of object type non-optional
Readonly<T>
Make all properties of object type readonly
ReturnType<T>
Obtain the return type of a function
InstanceType<T>
Obtain the instance type of a class
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; }PromiseType<T>
Obtain Promise resolve type
Usage:
import { PromiseType } from 'utility-types';
type Response = PromiseType<Promise<string>>;
// Expect: stringDeepReadonly<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;
// };
// };
// }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;
// };
// };
// }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;
// };
// };
// }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"$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 $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; }> $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; }$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$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$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$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>$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: stringMIT License
Copyright (c) 2016 Piotr Witek mailto:piotrek.witek@gmail.com (http://piotrwitek.github.io)