utility-types
Flow's Utility Types)
Utility Types for TypeScript (provide migration from- v1.X - compatible with TS v2.7.2
- v2.X - compatible with TS v2.8.1 (rewritten to conditional types)
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 a compatibility layer 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
- No third-party dependencies
- Provides multiple output formats (es5-commonjs, es5-module, jsnext)
Installation
npm install --save utility-types
Contributing 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)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>
Flow's Utility Types
Deprecated API (use at own risk)
getReturnOfExpression()
- from TS v2.0 it's better to use type-levelReturnType
insteadUnboxPromise
- please usePromiseType
instead (they are equivalent)
Flow to TypeScript Migration Guides
- Mixed Types in TypeScript (wip)
Operations on sets
SetIntersection<A, B>
Set intersection of given literal union types A
and B
Usage:
; ;// Expect: "2" | "3";// Expect: () => void
SetDifference<A, B>
Set difference of given literal union types A
and B
Usage:
; ;// Expect: "1";// Expect: string | number
SetComplement<A, A1>
Set complement of given literal union types A
and (it's subset) A1
Usage:
; ;// Expect: "1"
SymmetricDifference<A, B>
Set difference of the union and the intersection of given literal union types A
and B
Usage:
; ;// Expect: "1" | "4"
NonNullable<A>
Exclude null
and 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:
; ;;// Expect: "setName"
NonFunctionKeys<T>
Get union type of keys that are non-functions in object type T
Usage:
; ;;// Expect: "name"
Pick<T, K>
From T
pick a set of properties K
(part of standard-lib)
Usage:
; ;// Expect: { name: string }
Omit<T, K>
From T
remove a set of properties K
Usage:
; ; ;// Expect: { name: string; visible: boolean; }
Intersection<T, U>
From T
pick properties that exist in U
Usage:
; ;; ;// Expect: { age: number; }
Diff<T, U>
From T
remove properties that exist in U
Usage:
; ;; ;// Expect: { name: string; visible: boolean; }
Subtract<T, T1>
From T
remove properties that exist in T1
(T1
is a subtype of T
)
Usage:
; ;; ;// Expect: { name: string; visible: boolean; }
Overwrite<T, U>
From U
overwrite properties to T
Usage:
; ;; ;// Expect: { name: string; age: string; visible: boolean; }
Assign<T, U>
From U
assign properties to T
(just like object assign)
Usage:
; ;; ;// 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 union of one-property objects types
Usage:
; ; ;// Expect: { name: string; } | { age: number; } | { visible: boolean; }
PromiseType<T>
Obtain Promise resolve type
Usage:
; ;// Expect: string
DeepReadonly<T>
Readonly that works for deeply nested structures
Usage:
; ;;// Expect: {// readonly first: {// readonly second: {// readonly 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:
; ; ;// 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:
; ; ;// 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:
; ; ;// 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:
; ;; ;// 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:
; ;;// Expect: string ;;// Expect: boolean;// 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:
; ;;// Expect: string ;;// Expect: boolean;// Expect: number ;;// Expect: boolean ;;// Expect: number
$Call<T>
get the return type of a given expression type https://flow.org/en/docs/types/utilities/#toc-call
Usage:
; // Common use-case;; // { type: 'ADD'; payload: number } // Examples migrated from Flow docs;;; // number// type Nope = $Call<ExtractPropType<{ nope: number }>>; // Error: argument doesn't match `Obj`. ;;; // number
MIT License
Copyright (c) 2016 Piotr Witek mailto:piotrek.witek@gmail.com (http://piotrwitek.github.io)