The Five Custom TS Utility Types I Add to Every Project

// NonEmptyArray<T>: a tuple-like type that guarantees at least one element
// at the type level. Lets you call arr[0] without `| undefined` in noUncheckedIndexedAccess.

type NonEmptyArray<T> = [T, ...T[]];

function firstWord(words: NonEmptyArray<string>): string {
    // No `?? throw` needed; the type guarantees words[0] is a string.
    return words[0];
}

// Branded<T, B>: nominal typing for primitives. Stops you from passing a
// raw string where a UserId is expected.

type Brand<T, B extends string> = T & { readonly __brand: B };
type UserId = Brand<string, 'UserId'>;
type OrgId = Brand<string, 'OrgId'>;

function asUserId(s: string): UserId { return s as UserId; }
function asOrgId(s: string): OrgId { return s as OrgId; }

function lookupUser(id: UserId) { return 'user:' + id; }

const u = asUserId('u_42');
const o = asOrgId('o_7');
console.log(lookupUser(u));
// lookupUser(o);            // would be a type error: OrgId is not UserId
// lookupUser('u_42');       // would be a type error: raw string is not UserId

// Demonstrate NonEmptyArray.
console.log(firstWord(['hello', 'world']));
// firstWord([]);            // would be a type error at compile time

// Readonly<T> only freezes the top level. DeepReadonly walks objects, arrays,
// tuples, Maps, and Sets recursively. I use it on every config value loaded
// from disk so a stray mutation in a deeply-nested option becomes a compile error.

type DeepReadonly<T> =
    T extends (infer U)[]
        ? ReadonlyArray<DeepReadonly<U>>
        : T extends Map<infer K, infer V>
        ? ReadonlyMap<DeepReadonly<K>, DeepReadonly<V>>
        : T extends Set<infer V>
        ? ReadonlySet<DeepReadonly<V>>
        : T extends object
        ? { readonly [P in keyof T]: DeepReadonly<T[P]> }
        : T;

type RawConfig = {
    api: { baseUrl: string; retries: number };
    flags: { darkMode: boolean; betaCohorts: string[] };
};

declare const cfg: DeepReadonly<RawConfig>;
// cfg.api.retries = 5;            // compile error
// cfg.flags.betaCohorts.push('x'); // compile error

// Runtime demo: build a nested object and confirm the runtime view.
const config: RawConfig = {
    api: { baseUrl: 'https://api.example.com', retries: 3 },
    flags: { darkMode: true, betaCohorts: ['internal'] },
};

function freezeDeep(obj: unknown): unknown {
    if (obj && typeof obj === 'object' && !Object.isFrozen(obj)) {
        for (const v of Object.values(obj as Record<string, unknown>)) freezeDeep(v);
        Object.freeze(obj);
    }
    return obj;
}

const frozen = freezeDeep(config) as DeepReadonly<RawConfig>;
console.log('baseUrl:', frozen.api.baseUrl);
console.log('retries:', frozen.api.retries);
console.log('cohorts:', frozen.flags.betaCohorts);
console.log('top-level frozen:', Object.isFrozen(frozen));
console.log('nested  frozen :', Object.isFrozen(frozen.api));

// Awaited<T> exists since TS 4.5 and unwraps a promise. The inverse (turn a
// function returning T into a function returning Promise<T>) is what I need
// for migrating sync APIs to async.

type Promisify<F> = F extends (...args: infer A) => infer R
    ? (...args: A) => Promise<Awaited<R>>
    : never;

type RetryStrategy = (attempt: number) => number;
type AsyncRetryStrategy = Promisify<RetryStrategy>;
//   ^? (attempt: number) => Promise<number>

// Practical use: typed event emitter where the listener can be sync or async.
type Listener<T> = (event: T) => void | Promise<void>;

function makeEmitter<E>() {
    const listeners: Listener<E>[] = [];
    return {
        on(fn: Listener<E>) { listeners.push(fn); },
        async emit(event: E) {
            for (const fn of listeners) {
                const r = fn(event);
                if (r && typeof (r as Promise<void>).then === 'function') {
                    await r;
                }
            }
        },
    };
}

const emitter = makeEmitter<{ kind: 'user-signed-up'; id: string }>();
emitter.on((e) => console.log('sync :', e.kind, e.id));
emitter.on(async (e) => {
    await Promise.resolve();
    console.log('async:', e.kind, e.id);
});

(async () => {
    await emitter.emit({ kind: 'user-signed-up', id: 'u_42' });
    console.log('all listeners ran');
})();

// TypeScript object types are 'open': passing { a: 1, b: 2 } where { a: number }
// is expected works fine. ExactKeys flips that to 'closed': any unknown key is
// a type error. Useful for option bags where typos are bug factories.

type ExactKeys<T, U extends T> = U & Record<Exclude<keyof U, keyof T>, never>;

function makeRequest<U extends RequestOptions>(opts: ExactKeys<RequestOptions, U>) {
    return { url: opts.url, method: opts.method ?? 'GET', timeout: opts.timeout ?? 5000 };
}

type RequestOptions = {
    url: string;
    method?: 'GET' | 'POST';
    timeout?: number;
};

// Allowed: every key is in RequestOptions.
console.log(makeRequest({ url: '/api/users', method: 'GET' }));
console.log(makeRequest({ url: '/api/users', timeout: 3000 }));

// Disallowed at compile time:
// makeRequest({ url: '/x', tiemout: 3000 });   // typo on 'timeout' is a type error
// makeRequest({ url: '/x', headers: {} });     // 'headers' is not a known option

// Show the runtime behavior is identical; the type does the heavy lifting.
console.log('default method:', makeRequest({ url: '/x' }).method);
console.log('default timeout:', makeRequest({ url: '/x' }).timeout);