Typing a Library Versus an App

// a library surface done well: explicit types, brands, overloads where shapes are few, a Result at the boundary, exhaustive internally
export type UserId = string & { readonly __brand: 'UserId' }                       // nominal on demand
export const UserId = (s: string): UserId => { if (!/^u_[a-z0-9]{8}$/.test(s)) throw new TypeError('bad UserId'); return s as UserId }   // the only way to make one

export type Result<T, E = ClientError> = { ok: true; value: T } | { ok: false; error: E }
export type ClientError = { kind: 'network'; retryable: true } | { kind: 'http'; status: number; body: unknown } | { kind: 'parse'; message: string }

export interface Client {
  getUser(id: UserId): Promise<Result<User>>                                        // explicit: never an inferred internal shape
  on(event: 'connect', handler: () => void): () => void                              // overloads: few, distinct shapes, documented
  on(event: 'error', handler: (e: ClientError) => void): () => void
}

// internally: exhaustive over the error union; adding a kind fails to compile here
export function describe(e: ClientError): string {
  switch (e.kind) {
    case 'network': return 'Could not reach the server.'
    case 'http':    return `The server answered ${e.status}.`
    case 'parse':   return `The response could not be read: ${e.message}`
    default:        return assertNever(e)
  }
}
export function assertNever(x: never): never { throw new Error('unexpected: ' + JSON.stringify(x)) }

// the app side consuming it: the Result must be handled; the brand must be constructed; the states are a union
const r = await client.getUser(UserId('u_3f9a2k1x'))
if (!r.ok) { show(describe(r.error)); return }                                     // r.error: ClientError; below, r.value: User
render(r.value)