TypeScript types you should know about

In my daily work with TypeScript, there are a lot of utility types and standard
types I use across most if not all projects. This article contains the following subjects:

• Types in type-fest
• Other types (custom, built-in or utility-types)
• Common patterns
  • Overloaded type guards
  • const arrays and union type
  • Custom errors
  • Setting this

type-fest

A collection of essential TypeScript types.

This npm package contains quite a few that are not (yet) built-in. I sometimes use this package (and import from there) and sometimes copy these to an ambient declarations file in my project.

SafeOmit<T, K> 🌐

Create a type from an object type without certain keys.

The use-case is a safe(r) version than the built-in Omit, which doesn't check
the keys K against T, but instead check them against any.

export type SafeOmit<T, K extends keyof T> = Pick<T, Exclude<keyof T, K>> type ExecutionOptions = { debug: boolean; dry?: boolean; tag: 'default' | 'name'; } type ExecutionFlags = SafeOmit<ExecutionOptions, 'tag'> // => { // debug: boolean; // dry?: boolean | undefined; // } 

ReadonlyDeep<T> 🌐

Convert objects, Maps, Sets, and Arrays and all of their properties/elements into immutable structures recursively.

My use-case is primarily when I'm imported JSON, or dealing with Abstract Syntax Trees. These need to be completely immutable (until they're cloned) and this enforces that. The built-in Readonly<T> only works shallowly.

import { ReadonlyDeep } from 'type-fest' import dataJson = require('./data.json') const data: ReadonlyDeep<typeof dataJson> = dataJson data.property.value.push('bar') //=> error TS2339: Property 'push' does not exist on type 'readonly string[]' 

RequireAtLeastOnce<T, K> 🌐

Create a type that requires at least one of the given properties. The remaining
properties are kept as is.

My use-case is primarily when I have to make sure one of the known interface methods is present (usually api, service, transform/conversion style objects), but the rest of the type consists of properties and members that are always available.

import { RequireAtLeastOne } from 'type-fest' type Responder = { text?: () => string; json?: () => string; secure?: boolean; } const responder: RequireAtLeastOne<Responder, 'text' | 'json'> = { json: () => '{"message": "ok"}', secure: true } 

Merge<A, B> 🌐

Merge two types into a new type. Keys of the second type overrides keys of the
first type.

My use-case is primarily when I want to use Object.assign instead of using destructuring/spread to build my merged object. In the example below, you can see that the default for Object.assign produces an incorrect type.

type Stringy = { bar: string, foo: string } type NotStri = { foo: number other: boolean } const stringy: Stringy = { bar: 'bar', foo: 'foo' } const notstri: NotStri = { foo: 42, other: true } const result1 = Object.assign(stringy, notstri) // infers Object.assign<Stringy, NotStri> result1.foo // => string & number export type Merge<T, V> = Omit<T, Extract<keyof T, keyof V>> & V; const result2: Merge<Stringy, NotStri> = Object.assign(stringy, notstri) result2.foo // => number const result3 = { ...stringy, ...notstri } // => number 

Mutable<T> 🌐

Convert an object with readonly properties into a mutable object. Inverse of
Readonly<T>.

I personally use this very sparingly as I tend to Object.freeze those variables that are "truly" Readonly. As Required<T> is the inverse of Partial<T>, Mutable<T> is the inverse of Readonly<T>.

import {Mutable} from 'type-fest'; type Foo = { readonly a: number; readonly b: string; }; const mutableFoo: Mutable<Foo> = { a: 1, b: '2' }; mutableFoo.a = 3; 

Other types

WithFoo<T>

Whenever I have some data T and modify it so that it has more data, I generally use a wrapping type, so that it's easy to compose the type as I go.

interface MyType { bar: 'string'; } type WithFoo<T> = T & { foo: number } const data: MyType[] = [{ bar: 'first' }, { bar: 'second' }] const dataWithFoo: WithFoo<MyType>[] = data.map((item, index) => ({ ...item, foo: index })) // The inverse uses SafeOmit type WithoutFoo<T> = Omit<T, 'foo'> 

AtLeastOne

Sometimes I want to ensure that an array has at least one item. There are type libraries that actually define a whole lot more than just this simple alias, but that's out of the scope for this article.

type AtLeastOne<T> = [T, ...T[]] 

PromiseType<T> 🌐

One of the more interesting unwrappers. This gives the inner type T of a Promise<T> type. Usefull when something will unwrap the type, or you want to work outside of the context of promises or construct a new promise type (e.g. Promise<WithLabel<PromiseType<Original>>>).

import { PromiseType } from 'utility-types'; type Response = PromiseType<Promise<string>>; // => string 

ReturnType<T> (built-in)

Obtain the return type of a function type.

This is one of the more powerful inferred types I use all the type. Instead of
duplicating a type expectation over and over, if I know a function is guaranteed to call (or expected to call) a function foo, and I return the result, I give it the return type ReturnType<typeof foo>, which forwards the return type from the function declaration of foo to the current function.

type T10 = ReturnType<() => string> // => string type T11 = ReturnType<(s: string) => void> // => void function foo(): Promise<number> { return Promise.resolve(42) } type FooResult = ReturnType<typeof foo> // => Promise<number> 

InstanceType<T> (built-in)

Obtain the instance type of a constructor function type.

I use this if I have a constructor type (a type that is constructible), but I need to work with the ReturnType<T> of said constructor. More or less the inverse of ConstructorType<T>.

class C {} type T20 = InstanceType<typeof C>; // => C 

ConstructorType<T>

Matches a class constructor

I use this when I have a type (T) and I create a factory that generates these, or when I need the constructor type, given an instance type. More or less the inverse of InstanceType<T>.

export type ConstructorType<T> = new(...arguments_: any[]) => T 

Common patterns

Overloaded type guards

I often have custom type guard in order to easily narrow a very broad type. The issue with a broad type is that you only have access to the intersection until you check for presence or narrow it.

Sometimes you want to check more than just a broad type, and don't want the typeguard to assign never if it doesn't match some narrowing predicate. See the example below.

import { AST_NODE_TYPES, TSESTree } from "@typescript-eslint/typescript-estree"; // Aliases for these types, so they are easy to access type Node = TSESTree.Node type BinaryExpression = TSESTree.BinaryExpression // Store all the possible values for the operator property type BinaryOperator = BinaryExpression['operator'] // Define a special type that narrows the operator type BinaryExpressionWithOperator<T extends BinaryOperator> = BinaryExpression & { operator: T } // Generic overload that doesn't test for operator export function isBinaryExpression(node: Node): node is BinaryExpression // Special overload that only matches if the opertor matches export function isBinaryExpression<T extends BinaryOperator>(node: Node, operator: T): node is BinaryExpressionWithOperator<T> // Implementation that allows both arguments export function isBinaryExpression(node: Node, operator?: string): node is BinaryExpression { return node.type === AST_NODE_TYPES.BinaryExpression && ( operator === undefined || node.operator === operator ) } const generic: Node = { type: 'BinaryExpression', operator: '+', /*...*/ } as Node // => TSESTree.ArrayExpression // | TSESTree.ArrayPattern // | TSESTree.ArrowFunctionExpression // | TSESTree.AssignmentExpression // | TSESTree.AssignmentPattern // | TSESTree.AwaitExpression // | ... 150 more ... // | TSESTree.YieldExpression if (isBinaryExpression(generic)) { // typeof generic is now // => { type: 'BinaryExpression', operator: BinaryOperator, left: ..., } } else { // typeof generic is now anything except for // ~> { type: 'BinaryExpression' } } if (isBinaryExpression(generic, '+')) { // typeof generic is now // => { type: 'BinaryExpression', operator: '+', left: ..., } } else { // typeof generic is still Node } 

const arrays and OneOf<const Array>

Often you have a distinct set of values you want to allow. Since TypeScript 3.4
there is no need to do weird transformations using helper functions.

The example below has a set of options in A and defines the union type OneOfA which is one of the options of A.

export type OneOf<T extends ReadonlyArray<any>> = T[number] const A = ['foo', 'bar', 'baz'] as const type OneOfA = OneOf<typeof A> // => 'foo' | 'bar' | 'baz' function indexOf(key: OneOfA): number { return A.indexOf(key) // never returns -1 } 

Custom errors

As per TypeScript 2.1, transpilation of built-ins is weird. If you don't need to support IE10 or lower, the following pattern works well:

class EarlyFinalization extends Error { constructor() { super('Early finalization') // Doesn't work on IE10- Object.setPrototypeOf(this, EarlyFinalization.prototype); // Adds proper stacktrace Error.captureStackTrace(this, this.constructor) } } 

Setting this

There are (at least) two ways to tell TypeScript what the current contextual this value of a function is. The first one is adding a parameter this to your function:

interface Traverser { break(): void } function walker(this: Traverser, root: Node) { this.break() // no error } 

This can be very helpful if you're declaring functions outside the scope of a class or similar, but you know what the this value will be bound to.

The second method actually allows you to define it outside of the function:

interface HelperContext { logError: (error: string) => void; } const helperFunctions: { [name: string]: (() => void) } & ThisType<HelperContext> = { hello: function() { this.logError("Error: Something went wrong!"); // TypeScript successfully recognizes that "logError" is a part of "this". this.update(); // TS2339: Property 'update' does not exist on HelperContext. } } 

This can be very helpful if you're binding a collection of functions.

Conclusion

TypeScript has a lot of gems 💎 and even moreso in userland. Make sure that you check the built-in types, type-fest and your own collection of snippets, before you resort to as unknown as X or : any. A lot of the times there really is a proper way to do thing.