ts-essentials

All essential TypeScript types in one place 🤙

= { a: "A", b: "B", }; // Specify second type argument to change dictionary keys type const dictOfNumbers: Dictionary = { 420: "four twenty", 1337: "HAX", }; // You may specify union types as key to cover all possible cases. It acts the same as Record from TS's standard library export type DummyOptions = "open" | "closed" | "unknown"; const dictFromUnionType: Dictionary = { closed: 1, open: 2, unknown: 3, }; // and get dictionary values type stringDictValues = DictionaryValues; // Result: string // When building a map using JS objects consider using SafeDictionary const safeDict: SafeDictionary = {}; const value: number | undefined = safeDict["foo"]; // With SafeDictionary you don't need to use all of the sub-types of a finite type. // If you care about the key exhaustiveness, use a regular Dictionary. type ConfigKeys = "LOGLEVEL" | "PORT" | "DEBUG"; const configSafeDict: SafeDictionary = { LOGLEVEL: 2, }; const maybePort: number | undefined = configSafeDict["PORT"]; const configDict: Dictionary = { LOGLEVEL: 2, PORT: 8080, DEBUG: 1, }; const port: number = configDict["PORT"]; ``` ### Deep\* wrapper types - DeepPartial - DeepRequired - DeepReadonly - DeepNonNullable - DeepNullable - DeepUndefinable _keywords: recursive, nested, optional_ ```typescript type ComplexObject = { simple: number; nested: { a: string; array: [{ bar: number }]; }; }; type ComplexObjectPartial = DeepPartial; const samplePartial: ComplexObjectPartial = { nested: { array: [{}], }, }; type ComplexObjectAgain = DeepRequired; const sampleRequired: ComplexObjectAgain = { simple: 5, nested: { a: "test", array: [{ bar: 1 }], }, }; type ComplexObjectReadonly = DeepReadonly; type ComplexNullableObject = { simple: number | null | undefined; nested: { a: string | null | undefined; array: [{ bar: number | null | undefined }] | null | undefined; }; }; type ComplexObjectNonNullable = DeepNonNullable; const sampleNonNullable: ComplexObjectNonNullable = { simple: 5, nested: { a: "test", array: [{ bar: null }], // Error: Type 'null' is not assignable to type 'number' }, }; type ComplexObjectNullable = DeepNullable; const sampleDeepNullable1: ComplexObjectNullable = { simple: null, nested: { a: null, array: [{ bar: null }], }, }; const sampleDeepNullable2: ComplexObjectNullable = { simple: 1, nested: { array: [null], // OK // error -- property `a` missing, should be `number | null` }, }; // DeepUndefinable will come in handy if: // - you want to explicitly assign values to all of the properties // AND // - the expression used for the assignment can return an `undefined` value // In most situations DeepPartial will suffice. declare function tryGet(name: string): string | undefined; type ComplexObjectUndefinable = DeepUndefinable; const sampleDeepUndefinable1: ComplexObjectUndefinable = { simple: undefined, nested: { a: tryGet("a-value"), array: [{ bar: tryGet("bar-value") }], }, }; const sampleDeepUndefinable2: ComplexObjectUndefinable = { // error -- property `simple` missing, should be `number | undefined` nested: { array: [[{ bar: undefined }]], // error -- property `a` missing, should be `string | undefined` }, }; ``` ### Writable Make all attributes of object writable. ```typescript type Foo = { readonly a: number; readonly b: string; }; const foo: Foo = ({ a: 1, b: "b" }(foo as Writable).a = 42); ``` ```typescript type Foo = { readonly foo: string; bar: { readonly x: number; }; }[]; const test: DeepWritable = [ { foo: "a", bar: { x: 5, }, }, ]; // we can freely write to this object test[0].foo = "b"; test[0].bar.x = 2; ``` ### Buildable _keywords: builder_ A combination of both `DeepWritable` and `DeepPartial`. This type allows building an object step-by-step by assigning values to its attributes in multiple statements. ```typescript interface ReadonlyObject extends Readonly<{ simple: number; nested: Readonly<{ a: string; array: ReadonlyArray>; }>; }> {} const buildable: Buildable = {}; buildable.simple = 7; buildable.nested = {}; buildable.nested.a = "test"; buildable.nested.array = []; buildable.nested.array.push({ bar: 1 }); const finished = buildable as ReadonlyObject; ``` ### Omit Our version of `Omit` is renamed to `StrictOmit` in `v3`, since the builtin `Omit` has become part of TypeScript 3.5 ### StrictOmit Usage is similar to the builtin version, but checks the filter type more strictly. ```typescript type ComplexObject = { simple: number; nested: { a: string; array: [{ bar: number }]; }; }; type SimplifiedComplexObject = StrictOmit; // Result: // { // simple: number // } // if you want to Omit multiple properties just use union type: type SimplifiedComplexObject = StrictOmit; // Result: // { } (empty type) ``` #### Comparison between `Omit` and `StrictOmit` Following the code above, we can compare the behavior of `Omit` and `StrictOmit`. ```typescript type SimplifiedComplexObjectWithStrictOmit = StrictOmit; // Result: error // Type '"simple" | "nested" | "nonexistent"' does not satisfy the constraint '"simple" | "nested"'. // Type '"nonexistent"' is not assignable to type '"simple" | "nested"'. type SimplifiedComplexObjectWithOmit = Omit; // Result: no error ``` As is shown in the example, `StrictOmit` ensures that no extra key is specified in the filter. ### DeepOmit Recursively omit deep properties according to key names. Here is the `Teacher` interface. ```typescript interface Teacher { name: string; gender: string; students: { name: string; score: number }[]; } ``` Now suppose you want to omit `gender` property of `Teacher`, and `score` property of `students`. You can achieve this with a simple type filter. In the filter, the properties to be omitted completely should be defined as `never`. For the properties you want to partially omit, you should recursively define the sub-properties to be omitted. ```typescript type TeacherSimple = DeepOmit< Teacher, { gender: never; students: { score: never; }; } >; // The result will be: // { // name: string, // students: {name: string}[] // } ``` NOTE - `DeepOmit` works fine with `Array`s and `Set`s. When applied to a `Map`, the filter is only applied to its value. - If there exists any property in the filter which is not in the original type, an error will occur. ### OmitProperties _keywords: filter, props_ Removes all properties extending type `P` in type `T`. NOTE: it works opposite to filtering. ```typescript interface Example { log(): void; version: string; } type ExampleWithoutMethods = OmitProperties; // Result: // { // version: string; // } // if you want to Omit multiple properties just use union type like type ExampleWithoutMethods = OmitProperties; // Result: // { } (empty type) ``` ### PickProperties Pick only properties extending type `P` in type `T`. ```typescript interface Example { log(): void; version: string; versionNumber: number; } type ExampleOnlyMethods = PickProperties; // Result: // { // log(): void; // } // if you want to pick multiple properties just use union type like type ExampleOnlyMethodsAndString = PickProperties; // Result: // { // log(): void; // version: string; // } ``` ### NonNever Useful for purifying object types. It improves intellisense but also allows for extracting keys satisfying a conditional type. ```typescript type GetDefined = keyof NonNever< { [T in keyof TypesMap]: TypesMap[T] extends undefined ? never : TypesMap[T] } >; ``` ### NonEmptyObject Useful for accepting only objects with keys, great after a filter like OmitProperties or PickProperties. ```typescript /* return never if the object doesn't have any number value*/ type NumberDictionary = NonEmptyObject>; // return { a: number } type SomeObject = NumberDictionary<{ a: number; b: string }>; // return never type EmptyObject = NumberDictionary<{}>; ``` ### Merge _keywords: override_ ```typescript type Foo = { a: number; b: string; }; type Bar = { b: number; }; const xyz: Merge = { a: 4, b: 2 }; // Result: // { // a: number, // b: number, // } ``` ### MarkRequired Useful when you're sure some optional properties will be set. A real life example: when selecting an object with its related entities from an ORM. ```typescript class User { id: number; posts?: Post[]; photos?: Photo[]; } type UserWithPosts = MarkRequired; // example usage with a TypeORM repository -- `posts` are now required, `photos` are still optional async function getUserWithPosts(id: number): Promise { return userRepo.findOneOrFail({ id }, { relations: ["posts"] }) as Promise; } ``` ### MarkOptional Useful when you want to make some properties optional without creating a separate type. ```typescript interface User { id: number; name: string; email: string; password: string; } type UserWithoutPassword = MarkOptional; // Result: // { // id: number; // name: string; // email: string; // password?: string; // } ``` ### ReadonlyKeys Gets keys of an object which are readonly. ```typescript type T = { readonly a: number; b: string; }; type Result = ReadonlyKeys; // Result: // "a" ``` ### WritableKeys Gets keys of an object which are writable. ```typescript type T = { readonly a: number; b: string; }; type Result = WritableKeys; // Result: // "b" ``` ### OptionalKeys Gets keys of an object which are optional. ```typescript type T = { a: number; b?: string; c: string | undefined; d?: string; }; type Result = OptionalKeys; // Result: // "b" | "d" ``` ### RequiredKeys Gets keys of an object which are required. ```typescript type T = { a: number; b?: string; c: string | undefined; d?: string; }; type Result = RequiredKeys; // Result: // "a" | "c" ``` ### UnionToIntersection Useful for converting mapped types with function values to intersection type (so in this case - overloaded function). ```typescript type Foo = { bar: string; xyz: number; }; type Fn = UnionToIntersection<{ [K in keyof Foo]: (type: K, arg: Foo[K]) => any }[keyof Foo]>; ``` ### Opaque types Opaque types allow you to create unique type that can't be assigned to base type by accident. Good examples of opaque types include: - JWTs or other tokens - these are special kinds of string used for authorization purposes. If your app uses multiple types of tokens each should be a separate opaque type to avoid confusion. - specific currencies - amount of different currencies shouldn't be mixed - bitcoin address - special kind of string It's **critical** to understand that each token (second argument to `Opaque`) has to be unique across your codebase. We encourage you to leverage a pattern where you have single function to validate base type and create opaque type. ```typescript type PositiveNumber = Opaque; function makePositiveNumber(n: number): PositiveNumber { if (n <= 0) { throw new Error(`Value ${n} is not positive !`); } return (n as any) as PositiveNumber; // this ugly cast is required but only when "producing" opaque types } type NegativeNumber = Opaque; function makeNegativeNumber(n: number): NegativeNumber { if (n >= 0) { throw new Error(`Value ${n} is not negative !`); } return (n as any) as NegativeNumber; // this ugly cast is required but only when "producing" opaque types } let a = makePositiveNumber(5); // runtime check let b = makeNegativeNumber(-10); // runtime check a = b; // error at compile time ``` ### Tuple constraint ```typescript function foo(tuple: T): T { return tuple; } const ret = foo(["s", 1]); // return type of [string, number] ``` You can also parametrize `Tuple` type with a type argument to constraint it to certain types, i.e. `Tuple`. ### Exhaustive switch cases ```typescript function actOnDummyOptions(options: DummyOptions): string { switch (options) { case "open": return "it's open!"; case "closed": return "it's closed"; case "unknown": return "i have no idea"; default: // if you would add another option to DummyOptions, you'll get error here! throw new UnreachableCaseError(options); } } ``` ### ValueOf type ```typescript const obj = { id: "123e4567-e89b-12d3-a456-426655440000", name: "Test object", timestamp: 1548768231486, }; type objKeys = ValueOf; // Result: string | number ``` ### ElementOf type ```typescript const array = [1, 2, true, false]; type arrayElement = ElementOf; // Result: number | boolean ``` ### AsyncOrSync type Useful as a return type in interfaces or abstract classes with missing implementation ```typescript interface CiProvider { getSHA(): AsyncOrSync; // same as getSHA(): Promise | string; } class Circle implements CiProvider { // implementation can use sync version getSHA() { return "abc"; } } class Travis implements CiProvider { // implementation can use async version when needed async getSHA() { // do async call return "def"; } } // to get original type use AsyncOrSyncType AsyncOrSyncType> // return 'number' ``` ### Awaited type Unwrap promised type: ```typescript Awaited> // number ``` ### Newable _keywords: constructor, class_ Type useful when working with classes (not their instances). ```typescript class TestCls { constructor(arg1: string) {} } const t1: Newable = TestCls; ``` ### Assertions _keywords: invariant_ Simple runtime assertion that narrows involved types using [assertion functions](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-7.html#assertion-functions). Note: This function is not purely type level and leaves minimal runtime trace in generated code. ```typescript const something: string | undefined = "abc" as any; assert(something, "Something has to be defined!"); // from now on `something` is string, if this wouldn't be a case, assert would throw const anything = "abc" as any; assert(anything instanceof String, "anything has to be a string!"); // from now on `anything` is string ``` ### Exact _keywords: same, equals, equality_ `Exact` Checks if `TYPE` is exactly the same as `SHAPE`, if yes than `TYPE` is returned otherwise `never`. ```typescript type ABC = { a: number; b: number; c: number } type BC = { b: number; c: number } type C = { c: number } Exact // returns NEVER Exact // returns C ``` ### XOR Gets the XOR (Exclusive-OR) type which could make 2 types exclude each other. ```typescript type A = { a: string }; type B = { a: number; b: boolean }; type C = { c: number }; let A_XOR_B: XOR; let A_XOR_C: XOR; // fail A_XOR_B = { a: 0 }; A_XOR_B = { b: true }; A_XOR_B = { a: "", b: true }; A_XOR_C = { a: "", c: 0 }; // would be allowed with `A | C` type // ok A_XOR_B = { a: 0, b: true }; A_XOR_B = { a: "" }; A_XOR_C = { c: 0 }; ``` ### Functional type essentials `Head` & `Tail`: useful for functional programming, or as building blocks for more complex functional types. ```typescript function tail(array: T): Tail { return array.slice(1) as Tail; } type FirstParameter any> = FnT extends (...args: infer ArgsT) => any ? Head : never; ``` ## Contributors Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):

Chris Kaczor 💻 💼 💡 📖	Xiao Liang 💻 🤔 📖	Mateusz Burzyński 💻 🤔 📖	Maciej Bembenista 💻 🤔 📖	Michael Tontchev 💻 🤔 📖	Thomas den Hollander 💻 🤔 📖	Esa-Matti Suuronen 💻 🤔 📖
Ilya Semenov 💻 🤔 📖	Code Checks 👀	Patricio Palladino 🤔	Artur Kozak 💻 🤔 📖 👀	Zihua Wu 💻 🤔 📖	Kevin Peno 💻	Dom Parfitt 🤔
EduardoRFS 💻 📖	Andrew C. Dvorak 📖	Adam Russell 💻 📖	Piotr Szlachciak 💻 🤔 📖	Mikhail Swift 💻	Ryan Zhang 💻 🤔 📖	Francesco Borzì 📖 💻
Marnick L'Eau 💻 🤔 📖	kubk 💻	Bill Barry 💻 📖	Andrzej Wódkiewicz 💻 📖 🤔	Christian 🤔	Matthew Leffler 📖	studds 💻

This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome! [Read more](./CONTRIBUTING.md)