hanzio 3.0.0 → 3.1.0

package/README.md

@@ -9,7 +9,7 @@ logging.
 
 ```bash
 bun add hanzio
-# only needed for hanzio/zod, hanzio/api-wrapper and hanzio/secrets
+# only needed for hanzio/zod, hanzio/api-wrapper, hanzio/secrets and hanzio/cli
 bun add zod
 ```
 
@@ -19,6 +19,11 @@ from `dist`. `zod` is an optional peer dependency: the Zod helpers, the API
 wrapper and the secrets loader share the consumer application's Zod instance,
 while the root entry never loads it.
 
+The other optional peers belong to one subpath each: `libphonenumber-js` for
+`hanzio/format/phone`, `vue-i18n` for `hanzio/i18n/vue`, `i18next` for
+`hanzio/i18n/i18next`, `vite` for `hanzio/i18n/vite`, and
+`@intlify/message-compiler` for checking vue-i18n catalogs with `hanzio-i18n`.
+
 ## Imports
 
 The root export contains only dependency-free, runtime-neutral helpers (array,
@@ -37,17 +42,28 @@ subpath export:
 | `hanzio/zod` | Branded IDs, JSON schemas, schema introspection and defaults, schema-to-type rendering, min/max filters |
 | `hanzio/api-wrapper` | Typed HTTP clients ([docs](src/api-wrapper/README.md)) |
 | `hanzio/api-wrapper/testing` | `createMockFetch` / `jsonResponse` for testing API clients |
+| `hanzio/api-wrapper/connection-auth` | One shared token exchange per connection for API clients; needs `node:crypto` ([docs](src/api-wrapper/README.md#sharing-a-login-across-clients)) |
 | `hanzio/jwt` | HS256/384/512 JWTs via Web Crypto ([docs](src/jwt/README.md)) |
 | `hanzio/sitemap` | Sitemap discovery and crawling ([docs](src/sitemap/README.md)) |
 | `hanzio/p-queue` | Promise queue ([docs](src/p-queue/README.md)) |
 | `hanzio/cool-console-log` | Colored terminal logging |
-| `hanzio/format` | Cached `Intl` formatters: numbers, currency, bytes, durations, relative time ([docs](src/format/README.md)) |
+| `hanzio/format` | Cached `Intl` formatters: numbers, currency, bytes, durations, dates, relative time ([docs](src/format/README.md)) |
+| `hanzio/format/phone` | Phone numbers as people read them; needs `libphonenumber-js` ([docs](src/format/README.md#phone-numbers)) |
 | `hanzio/crypto` | Web Crypto helpers: constant-time compare, HMAC/webhook verification, sealing, tokens ([docs](src/crypto/README.md)) |
 | `hanzio/storage` | Typed localStorage/AsyncStorage items that never throw ([docs](src/storage/README.md)) |
-| `hanzio/i18n` | Typed `{placeholder}` interpolation and translators ([docs](src/i18n/README.md)) |
+| `hanzio/i18n` | Typed `{placeholder}` interpolation, translators, `TypedTranslate` and locale registries ([docs](src/i18n/README.md)) |
+| `hanzio/i18n/vue` | vue-i18n setup with locale persistence and a typed composer ([docs](src/i18n/README.md#vue-i18n)) |
+| `hanzio/i18n/i18next` | i18next setup with device locale, persistence and server sync ([docs](src/i18n/README.md#i18next)) |
+| `hanzio/i18n/vite` | Vite dev plugin that reloads edited vue-i18n catalogs ([docs](src/i18n/README.md#vue-i18n)) |
+| `hanzio/i18n/check` | Catalog checks behind the `hanzio-i18n` bin ([docs](src/i18n/README.md#catalog-checks)) |
+| `hanzio/iso` | ISO country, currency and language codes with English names ([docs](src/iso/README.md)) |
 | `hanzio/secrets` | Typed secret sets from env/Infisical ([docs](src/secrets/README.md)) |
 | `hanzio/secrets/vite` | Vite `define` helpers for secret sets |
 | `hanzio/secrets/worker` | Secret sets for Cloudflare Workers |
+| `hanzio/redis` | Bun Redis: self-healing client with shared subscriptions, fleet-wide concurrency limiter ([docs](src/redis/README.md)) |
+| `hanzio/http` | SSE keep-alive comments and anti-buffering headers ([docs](src/http/README.md)) |
+| `hanzio/cli` | Typed CLIs from Zod schemas: flags, help, completion, exit codes; needs `node:util` ([docs](src/cli/README.md)) |
+| `hanzio/testing` | `bun:test` kit: restorable module mocks, Prisma deep mock, window shim, auth race contract ([docs](src/testing/README.md)) |
 
 `scripts/verify-exports.mjs` imports every entry above from the packed tarball
 in CI, so this table and `package.json#exports` can't drift apart.
@@ -257,6 +273,28 @@ if (parsed.ok) parsed.data
 new RegExp(`\\b${escapeRegExp(term)}\\b`, 'i')
 ```
 
+`escapeHtml` escapes text for HTML. `stripEmoji` removes emoji from text that
+is spoken, tidying the spaces they leave. `fileExtension` reads a lowercased
+extension, or `undefined`.
+
+```ts
+import { escapeHtml, fileExtension, stripEmoji } from 'hanzio'
+
+`<title>${escapeHtml(name)}</title>`
+stripEmoji('Hi there 👋, welcome') // "Hi there, welcome"
+fileExtension('uploads/Photo.JPG') // "jpg"
+fileExtension('README') ?? 'bin' // "bin"
+```
+
+`toJsonValue` normalizes a value the way a JSON round trip does (dropping
+`undefined` properties), so it can go into a JSON column.
+
+```ts
+import { toJsonValue } from 'hanzio'
+
+toJsonValue({ ok: true, error: undefined }) // { ok: true }
+```
+
 ### Promise
 
 `tryCatch` converts a promise, or a function that may throw synchronously, into
@@ -300,6 +338,19 @@ import { pMap } from 'hanzio'
 const users = await pMap(ids, (id) => fetchUser(id), { concurrency: 4 })
 ```
 
+`createTaskPool` bounds work that arrives over time, such as pages a crawler
+discovers. The first failure or an abort discards queued tasks, and `drain`
+rejects with it once the active tasks settle. Pass `stopOnError: false` to keep
+going after a failed task.
+
+```ts
+import { createTaskPool } from 'hanzio'
+
+const pool = createTaskPool({ concurrency: 4, signal })
+for await (const page of discoverPages(signal)) void pool.run(() => scrape(page, signal))
+await pool.drain()
+```
+
 `promiseTimeout` resolves after a delay (and rejects early if its signal
 aborts). `backgroundPromise` runs async work and reports success or failure
 through hooks; `backgroundPromiseSync` schedules it in a microtask.
@@ -773,6 +824,17 @@ type UserId = GenericId<'User'>
 const userId: UserId = UserId.parse('usr_123')
 ```
 
+`zOptionalE164` is a form field for an optional phone number: `''` and `null`
+parse to `null`, anything else must match `E164_REGEX`.
+
+```ts
+import { E164_REGEX, zOptionalE164 } from 'hanzio/zod'
+
+zOptionalE164.parse('+4512345678') // '+4512345678'
+zOptionalE164.parse('') // null
+z.string().regex(E164_REGEX, 'Use E.164, e.g. +4512345678')
+```
+
 `zSingleOrArray` accepts either one schema value or an array of schema values.
 
 ```ts
@@ -1160,6 +1222,55 @@ Cloudflare bindings without Node compatibility. See the
 [migration notes](src/secrets/README.md#migration-notes) for stricter environment
 validation and browser exposure rules.
 
+### Redis (`hanzio/redis`)
+
+For Bun servers. `createManagedRedis` keeps one command connection and one
+subscriber connection that reconnect on their own; subscriptions are shared
+per channel and come back after a reconnect. `createRedisConcurrencyLimit` caps
+how many calls run at once across every process, using Redis' clock, and runs
+uncapped when Redis is unreachable. See the [Redis docs](src/redis/README.md).
+
+```ts
+import { createManagedRedis, createRedisConcurrencyLimit } from 'hanzio/redis'
+
+const redis = createManagedRedis({ url: () => getSecret('REDIS_URL') })
+const unsubscribe = await redis.subscribe('events', (message) => handle(message))
+
+const withLimit = createRedisConcurrencyLimit({
+	key: 'openai',
+	max: 20,
+	slotTtlMs: 30_000,
+	send: (command, args) => redis.getClient().send(command, args)
+})
+await withLimit(() => callOpenAi(request), signal)
+```
+
+### HTTP (`hanzio/http`)
+
+`withSseKeepAlive(response)` adds `:` comments to a quiet SSE stream and
+headers that stop proxies from buffering it. See the [HTTP docs](src/http/README.md).
+
+```ts
+import { withSseKeepAlive } from 'hanzio/http'
+
+return withSseKeepAlive(createUIMessageStreamResponse({ stream }))
+```
+
+### Testing (`hanzio/testing`)
+
+Helpers for `bun:test`: a `mock.module` that can be undone, a deep Prisma mock,
+a minimal `window` for browser-facing code, and a contract suite for API
+clients built on `ConnectionAuthCache`. See the [testing docs](src/testing/README.md).
+
+```ts
+import { createPrismaMock, ModuleMocker } from 'hanzio/testing'
+
+const prismaMock = createPrismaMock<typeof prisma>(mock)
+const moduleMocker = new ModuleMocker()
+await moduleMocker.mock(posthogModulePath, () => ({ captureException: mock() }))
+afterAll(() => moduleMocker.clear())
+```
+
 ## Development
 
 ```bash

package/dist/api-wrapper/connection-auth.d.ts

@@ -0,0 +1,61 @@
+export type ConnectionAuthToken = {
+    token: string;
+    expiresAt: number;
+};
+/**
+ * Shares one login per connection across every client instance in the process,
+ * for APIs that exchange credentials for a short-lived token.
+ *
+ * - Concurrent callers share one exchange; aborting one caller's wait leaves the
+ *   exchange running for the others.
+ * - Changing any of `authInputs` (rotated password, new client id) retires the
+ *   old token: a retired client may finish its request but cannot store its
+ *   token. Inputs are kept only as an HMAC under a random per-cache key, so
+ *   the cache never holds, and cannot be used to guess, the credentials.
+ * - On a 401, `reject(token)` drops the refused token, unless a newer one has
+ *   already replaced it, and the next `get()` exchanges again.
+ * - `get({ fresh: true })` always exchanges, for an explicit credential check;
+ *   its failure never falls back to the previous token.
+ * - At most `maxEntries` connections are kept, least recently used first;
+ *   connections with an exchange in flight are never evicted.
+ *
+ * @example
+ * const auth = new ConnectionAuthCache()
+ *
+ * class ShopApi {
+ *   private readonly token
+ *   constructor(credentials: { connectionId: string; apiKey: string; secret: string }) {
+ *     this.token = auth.bind({
+ *       connectionId: credentials.connectionId,
+ *       authInputs: [credentials.apiKey, credentials.secret],
+ *       refreshMarginMs: 60_000,
+ *       exchange: () => login(credentials) // resolves { token, expiresAt }
+ *     })
+ *   }
+ *   async read(signal?: AbortSignal) {
+ *     const current = await this.token.get({ signal })
+ *     // On a 401: this.token.reject(current), then retry once with this.token.get().
+ *   }
+ * }
+ */
+export declare class ConnectionAuthCache {
+    private readonly maxEntries;
+    private readonly key;
+    private readonly entries;
+    constructor(maxEntries?: number);
+    get size(): number;
+    clear(): void;
+    private prune;
+    bind(input: {
+        connectionId: string;
+        authInputs: readonly (string | number)[];
+        refreshMarginMs: number;
+        exchange: () => Promise<ConnectionAuthToken>;
+    }): {
+        get: (options?: {
+            fresh?: boolean | undefined;
+            signal?: AbortSignal | undefined;
+        } | undefined) => Promise<ConnectionAuthToken>;
+        reject(token: ConnectionAuthToken): void;
+    };
+}

package/dist/cli/fields.d.ts

@@ -0,0 +1,30 @@
+import { z } from 'zod';
+/** Thrown for bad argv. The CLI prints it with a `--help` hint and exits 2. */
+export declare class UsageError extends Error {
+}
+/** One key of an input or globals object, read as a flag or a positional. */
+export type Field = {
+    key: string;
+    flag: string;
+    kind: 'string' | 'number' | 'boolean';
+    multiple: boolean;
+    positional: boolean;
+    optional: boolean;
+    hasDefault: boolean;
+    defaultValue: unknown;
+    description?: string;
+    alias?: string;
+    env?: string;
+    choices?: string[];
+};
+export declare function fieldsOf(schema: z.ZodObject | undefined): Field[];
+/**
+ * Builds the raw object Zod validates: flag values and positionals by key,
+ * numbers coerced, `.meta({ env })` as fallback, and a missing required
+ * boolean or array read as `false` or `[]`.
+ */
+export declare function readFields(fields: Field[], values: Record<string, string | boolean | (string | boolean)[] | undefined>, positionals: string[], env: Record<string, string | undefined>): Record<string, unknown>;
+export declare function fieldLabel(field: Field): string;
+export declare function fieldHelp(field: Field): string;
+/** Closest candidate within a few edits, for "Did you mean ...?" hints. */
+export declare function closest(input: string, candidates: readonly string[]): string | undefined;

package/dist/cli/index.d.ts

@@ -0,0 +1,122 @@
+import type { z } from 'zod';
+declare module 'zod' {
+    interface GlobalMeta {
+        /** hanzio/cli: read this key from positional arguments, in key order. */
+        positional?: boolean;
+        /** hanzio/cli: one-letter short flag, e.g. `'r'` for `-r`. */
+        alias?: string;
+        /** hanzio/cli: environment variable read when the flag is missing. */
+        env?: string;
+    }
+}
+declare const commandKey: unique symbol;
+/**
+ * An expected failure: the CLI prints the message without a stack trace and
+ * exits with `exitCode` (default 1).
+ */
+export declare class CliError extends Error {
+    readonly exitCode: number;
+    constructor(message: string, options?: {
+        exitCode?: number;
+        cause?: unknown;
+    });
+}
+export type CliWriter = {
+    write(text: string): unknown;
+};
+/** Where `cli.run()` writes and reads env fallbacks; defaults to `process`. */
+export type CliIO = {
+    stdout?: CliWriter;
+    stderr?: CliWriter;
+    env?: Record<string, string | undefined>;
+};
+export type CommandContext<C = unknown> = {
+    /** What `defineCli({ context })` returned. */
+    readonly context: C;
+    /** The validated `defineCli({ globals })` values. */
+    readonly globals: Record<string, unknown>;
+    /** Command names from the root, e.g. `['deal', 'list']`. */
+    readonly path: readonly string[];
+    /** Every argument after the command names, unparsed. */
+    readonly argv: readonly string[];
+    /** Arguments after `--`. */
+    readonly passthrough: readonly string[];
+    /** `--json` was passed (as a global or a command option). */
+    readonly json: boolean;
+    readonly stdout: CliWriter;
+    readonly stderr: CliWriter;
+    readonly env: Record<string, string | undefined>;
+    /** Set to exit non-zero without printing an error. */
+    exitCode: number;
+};
+export type Command<C = unknown> = {
+    readonly [commandKey]: true;
+    readonly description?: string;
+    readonly input?: AnyObject;
+    readonly raw?: boolean;
+    readonly run?: (input: never, ctx: CommandContext<C>) => unknown;
+    readonly output?: (result: never, ctx: CommandContext<C>) => unknown;
+    readonly load?: LazyCommand<C>;
+};
+/** `() => import('./commands/heavy')`: loaded only when the command runs. */
+export type LazyCommand<C = unknown> = () => Promise<Command<C> | {
+    default: Command<C>;
+}>;
+export type CommandGroup<C = unknown> = {
+    readonly [name: string]: CommandNode<C>;
+};
+export type CommandNode<C = unknown> = Command<C> | LazyCommand<C> | CommandGroup<C>;
+type AnyObject = z.ZodObject<z.core.$ZodShape, z.core.$ZodObjectConfig>;
+type EmptyObject = z.ZodObject<Record<never, never>>;
+export type Cli = {
+    readonly name: string;
+    /** Runs the CLI and resolves to its exit code: 0 ok, 1 failure, 2 usage error. */
+    run(argv?: readonly string[], io?: CliIO): Promise<number>;
+};
+export type CliConfig<G extends AnyObject, C> = {
+    name: string;
+    version?: string;
+    description?: string;
+    /** Options accepted before or after any command, e.g. `--org`. */
+    globals?: G;
+    /** Runs before every command; throw a `CliError` to refuse it. */
+    guard?: (call: {
+        path: readonly string[];
+        input: Record<string, unknown>;
+        globals: z.output<G>;
+        context: C;
+    }) => unknown;
+    /** A command (single-command CLI) or nested groups of commands. */
+    commands: CommandNode<C>;
+} & (undefined extends C ? {
+    context?: ContextFunction<G, C>;
+} : {
+    context: ContextFunction<G, C>;
+});
+/** Builds the `ctx.context` every command receives. */
+type ContextFunction<G extends AnyObject, C> = (globals: z.output<G>) => C | Promise<C>;
+/**
+ * A command. `input` is a Zod object whose keys become `--kebab-case` flags,
+ * or positionals with `.meta({ positional: true })`. `run`'s return value is
+ * printed by `output` (default: strings as-is, anything else as JSON).
+ */
+export declare function defineCommand<S extends AnyObject = EmptyObject, R = unknown, C = unknown>(definition: {
+    description?: string;
+    input?: S;
+    run: (input: z.output<S>, ctx: CommandContext<C>) => R;
+    output?: (result: Awaited<R>, ctx: CommandContext<C>) => unknown;
+}): Command<C>;
+/** A command that skips parsing: everything after its name is in `ctx.argv`. */
+export declare function defineCommand<R = unknown, C = unknown>(definition: {
+    description?: string;
+    raw: true;
+    run: (input: Record<string, never>, ctx: CommandContext<C>) => R;
+    output?: (result: Awaited<R>, ctx: CommandContext<C>) => unknown;
+}): Command<C>;
+/** A lazy command whose description shows in help before it loads. */
+export declare function defineCommand<C = unknown>(definition: {
+    description?: string;
+    load: LazyCommand<C>;
+}): Command<C>;
+export declare function defineCli<G extends AnyObject = EmptyObject, C = undefined>(config: CliConfig<G, C>): Cli;
+export {};

package/dist/format/index.d.ts

@@ -17,6 +17,12 @@ export declare function formatPercent(value: number, locale: string, options?: I
  * `{ maximumFractionDigits: 0 }` for whole-unit prices.
  */
 export declare function formatCurrency(amount: number, currency: string, locale: string, options?: Intl.NumberFormatOptions): string;
+/**
+ * A price: whole amounts without minor units (`'2.500 kr.'`), fractional ones
+ * with the currency's usual digits (`'199,95 kr.'`) instead of rounding them
+ * into a price nobody charges.
+ */
+export declare function formatPrice(amount: number, currency: string, locale: string): string;
 /** Short compact notation: `1234` -> `"1.2K"` (en-US), `"1,2 t"` (da-DK). */
 export declare function formatCompactNumber(value: number, locale: string): string;
 export type FormatBytesOptions = {
@@ -88,8 +94,79 @@ export declare function formatWait(value: DateInput, locale: string, options?: {
  * and friends combine with that default.
  */
 export declare function formatDateRange(start: DateInput, end: DateInput, locale: string, options?: Intl.DateTimeFormatOptions): string;
+declare const DATE_PRESETS: {
+    readonly 'DD/MM/YYYY': {
+        readonly day: "2-digit";
+        readonly month: "2-digit";
+        readonly year: "numeric";
+    };
+    readonly 'DD/MM/YYYY HH:mm': {
+        readonly day: "2-digit";
+        readonly month: "2-digit";
+        readonly year: "numeric";
+        readonly hour: "2-digit";
+        readonly minute: "2-digit";
+        readonly hourCycle: "h23";
+    };
+    readonly 'HH:mm': {
+        readonly hour: "2-digit";
+        readonly minute: "2-digit";
+        readonly hourCycle: "h23";
+    };
+    readonly ddd: {
+        readonly weekday: "short";
+    };
+    readonly 'D MMM': {
+        readonly day: "numeric";
+        readonly month: "short";
+    };
+    readonly 'D MMM YYYY': {
+        readonly day: "numeric";
+        readonly month: "short";
+        readonly year: "numeric";
+    };
+    readonly 'dddd, MMMM D': {
+        readonly weekday: "long";
+        readonly day: "numeric";
+        readonly month: "long";
+    };
+    readonly 'MMMM YYYY': {
+        readonly month: "long";
+        readonly year: "numeric";
+    };
+};
+/**
+ * A named date layout. The names read like dayjs tokens, but the output
+ * follows the locale: `'D MMM'` is "5 Mar" in en-GB and "Mar 5" in en-US.
+ */
+export type DatePreset = keyof typeof DATE_PRESETS;
+/** A date in one of the `DatePreset` layouts, in local time. */
+export declare function formatDate(date: DateInput, preset: DatePreset, locale: string): string;
+/** Medium date and short time: "5 Mar 2026, 14:30" (en-GB). */
+export declare function formatDateTime(date: DateInput, locale: string): string;
+/**
+ * Compact activity timestamp for a list row: the time today, "yesterday",
+ * else the date (with the year when it is not this year). Unparseable input
+ * returns `''`.
+ */
+export declare function formatCompactTime(date: DateInput, locale: string, options?: {
+    now?: DateInput;
+}): string;
+/**
+ * Day-divider label for a chat timeline: "today", "yesterday", else weekday
+ * and date (with the year when it is not this year). Unparseable input
+ * returns `''`.
+ */
+export declare function formatDayDivider(date: DateInput, locale: string, options?: {
+    now?: DateInput;
+}): string;
 /** "a, b, and c". Falls back to a comma join where `Intl.ListFormat` is missing. */
 export declare function formatList(items: readonly string[], locale: string, options?: Intl.ListFormatOptions): string;
+/**
+ * Stands for "no value" in a cell or detail row that must keep its height, so
+ * absent values cannot drift between a hyphen and an em dash. Not translated.
+ */
+export declare const EM_DASH = "\u2014";
 /** Badge count: `150` -> `"99+"`. Negative or NaN is `"0"`. */
 export declare function formatCappedCount(count: number, max?: number): string;
 /**
@@ -99,4 +176,18 @@ export declare function formatCappedCount(count: number, max?: number): string;
 export declare function pluralize(count: number, forms: Partial<Record<Intl.LDMLPluralRule, string>> & {
     other: string;
 }, locale: string): string;
+/**
+ * The date formatters with the locale read on every call, for apps whose
+ * locale lives in their i18n runtime:
+ * `export const fmt = withLocale(() => uiLocales.tag(appI18n.locale()))`.
+ */
+export declare function withLocale(getLocale: () => string): {
+    formatDate: (date: DateInput, preset: "D MMM" | "D MMM YYYY" | "DD/MM/YYYY" | "DD/MM/YYYY HH:mm" | "HH:mm" | "MMMM YYYY" | "ddd" | "dddd, MMMM D") => string;
+    formatDateTime: (date: DateInput) => string;
+    formatCompactTime: (date: DateInput) => string;
+    formatDayDivider: (date: DateInput) => string;
+    formatRelativeTime: (date: DateInput, options?: FormatRelativeTimeOptions | undefined) => string;
+    formatNumber: (value: number, options?: Intl.NumberFormatOptions | undefined) => string;
+    formatPrice: (amount: number, currency: string) => string;
+};
 export {};

package/dist/format/phone.d.ts

@@ -0,0 +1,19 @@
+/**
+ * A stored phone number as a person reads it. `country` is the READER's ISO
+ * 3166-1 alpha-2 country (the organization's, say), not the number's: a local
+ * number prints the local way, any other with its country code.
+ *
+ * ```ts
+ * formatPhone('+4520304050', 'DK') // '20 30 40 50'
+ * formatPhone('+4520304050') // '+45 20 30 40 50'
+ * formatPhone('+4915112345678', 'DK') // '+49 1511 2345678'
+ * ```
+ *
+ * Nothing is lost: an unparseable value comes back trimmed but verbatim, and
+ * the national form is used only for a VALID number (`+4512345678` parses as
+ * DK but is not a real number, so it keeps its `+45`). A country
+ * libphonenumber cannot dial falls back to international. Empty input is
+ * `''`; the caller decides what stands in for "no number". Use the raw E.164
+ * value in `tel:` links.
+ */
+export declare function formatPhone(value: string | null | undefined, country?: string | null): string;

package/dist/http/index.d.ts

@@ -0,0 +1,14 @@
+export declare const SSE_KEEPALIVE_COMMENT: NodeJS.NonSharedUint8Array;
+/** Passes bytes through, writing a comment first and after every `intervalMs` of silence. */
+export declare function createSseKeepAliveTransform(intervalMs?: number, timers?: {
+    setTimeout: (fn: () => void, ms: number) => unknown;
+    clearTimeout: (id: unknown) => void;
+}): TransformStream<Uint8Array<ArrayBufferLike>, Uint8Array<ArrayBufferLike>>;
+/**
+ * Copies an SSE response with keep-alive comments in its body and headers that
+ * stop proxies from buffering it.
+ *
+ * @example
+ * return withSseKeepAlive(createUIMessageStreamResponse({ stream }))
+ */
+export declare function withSseKeepAlive(response: Response, intervalMs?: number): Response;

package/dist/i18n/catalog.d.ts

@@ -0,0 +1,47 @@
+import { type Messages } from '.';
+/** How a catalog's runtime reads its messages: plural syntax and escaping. */
+export type CatalogRuntime = 'vue-i18n' | 'i18next' | 'plain';
+export type CatalogConfig = {
+    /** Shown in check output. */
+    name: string;
+    /** Folder of `<locale>.json` files, relative to the config file. */
+    dir: string;
+    runtime: CatalogRuntime;
+    /** Where `hanzio-i18n generate` writes the key → placeholder map. */
+    generatedTypes?: string;
+    /** Exported type name in `generatedTypes`. Default `TranslationParams`. */
+    generatedTypeName?: string;
+    /**
+     * Source folders scanned for key references. Set them and the check also
+     * fails on keys nothing references. Leave unset when keys are built at
+     * runtime from a prefix (`t(\`widget.${key}\`)` everywhere), since every key
+     * would read as used.
+     */
+    sourceRoots?: readonly string[];
+    /**
+     * Key prefixes composed from data rather than written in source (labels
+     * sent by the backend, for example), kept even when nothing references them.
+     * A prefix a template literal spells out is found by the scan already.
+     */
+    dynamicKeyPrefixes?: readonly string[];
+};
+export type CatalogIssue = {
+    catalog: string;
+    locale?: string;
+    message: string;
+};
+/**
+ * Validates one parsed JSON catalog: every leaf a string, no empty or dotted
+ * key segments, NFC-normalized text and no mojibake.
+ */
+export declare function parseMessages(value: unknown, catalog: string, locale: string): {
+    messages?: Messages;
+    issues: CatalogIssue[];
+};
+export declare function flattenCatalog(messages: Messages): Map<string, string>;
+/**
+ * The TypeScript key → placeholder-name map for `TypedTranslate`, generated
+ * from the base catalog. Plural messages also take `count`: vue-i18n's
+ * `a | b | c` forms, and i18next's `key_one`/`key_other` (merged into `key`).
+ */
+export declare function generateCatalogTypes(catalog: Pick<CatalogConfig, 'runtime' | 'generatedTypeName'>, baseMessages: Messages, command?: string): string;

package/dist/i18n/check.d.ts

@@ -0,0 +1,45 @@
+import { type CatalogConfig, type CatalogIssue } from './catalog';
+import { type ContentRulesConfig } from './content-rules';
+export type { CatalogConfig, CatalogIssue, CatalogRuntime } from './catalog';
+export { generateCatalogTypes, parseMessages } from './catalog';
+export type { ContentRulesConfig } from './content-rules';
+export type I18nConfig<Locale extends string = string, Catalog extends string = string> = {
+    /** The source-of-truth locale; usually `'en'`. */
+    baseLocale: NoInfer<Locale>;
+    /** Every shipped locale, the base included. Each needs a catalog file. */
+    locales: readonly Locale[];
+    catalogs: readonly (CatalogConfig & {
+        name: Catalog;
+    })[];
+    /**
+     * Groups of catalogs merged into one runtime (`{ ...platform, ...widget }`),
+     * so their top-level keys must not overlap.
+     */
+    disjointNamespaces?: readonly (readonly NoInfer<Catalog>[])[];
+    rules?: ContentRulesConfig<NoInfer<Locale>>;
+};
+/**
+ * Types an `i18n.config.ts` default export: `baseLocale`, the catalog names
+ * in `disjointNamespaces` and the locales in `rules.identical.allowKeys` must
+ * be ones the config declares.
+ */
+export declare function defineI18nConfig<const Locale extends string, const Catalog extends string>(config: I18nConfig<Locale, Catalog>): I18nConfig<Locale, Catalog>;
+/**
+ * Every problem in the configured catalogs, empty when they are valid. Paths
+ * in `config` are relative to `root`.
+ */
+export declare function validateCatalogs(config: I18nConfig, options: {
+    root: string;
+    checkGeneratedTypes?: boolean;
+}): Promise<CatalogIssue[]>;
+/**
+ * Writes each catalog's `generatedTypes` from its base locale. Returns the
+ * written paths, or the issues that stopped generation (nothing is written
+ * when any base catalog is invalid).
+ */
+export declare function writeCatalogTypes(config: I18nConfig, options: {
+    root: string;
+}): {
+    written: string[];
+    issues: CatalogIssue[];
+};

package/dist/i18n/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};