Declaration Merging and Modules

// a library's surface: explicit, generated, tested
// src/index.ts (the only entry): re-export what is meant; nothing else is reachable
export { createClient } from './client'
export type { Client, ClientOptions, Result } from './client'          // consumers must be able to name these

// src/client.ts
export interface ClientOptions { baseUrl: string; timeoutMs?: number; retries?: number }   // an interface: consumers may augment (merging)
export type Result<T, E = ClientError> = { ok: true; value: T } | { ok: false; error: E }
export interface Client { get<T>(path: string): Promise<Result<T>>; close(): void }
export function createClient(options: ClientOptions): Client {                          // explicit return type: the internal class never leaks
  return new ClientImpl(options)
}
/** @internal */ export class ClientImpl implements Client { … }                         // stripInternal drops it from the .d.ts

// tests/types.test-d.ts: the contract, tested by the checker in CI
import { expectTypeOf } from 'expect-type'
import { createClient, type Result } from '../src'
const c = createClient({ baseUrl: 'x' })
expectTypeOf(c.get<number>('/n')).resolves.toEqualTypeOf<Result<number>>()
expectTypeOf(createClient).parameter(0).toHaveProperty('timeoutMs').toEqualTypeOf<number | undefined>()
// @ts-expect-error: retries must be a number
createClient({ baseUrl: 'x', retries: '3' })

// tsconfig.build.json: "declaration": true, "declarationMap": true, "stripInternal": true, "isolatedDeclarations": true
// package.json: "exports": { ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" } }, "files": ["dist"]
// release: api-extractor diffs dist/index.d.ts against the last release; a removed or narrowed export is a major