hanzio 3.0.0 → 3.1.1

package/package.json

@@ -1,11 +1,14 @@
 {
   "name": "hanzio",
-  "version": "3.0.0",
+  "version": "3.1.1",
   "description": "A lightweight set of utility functions for TypeScript",
   "type": "module",
   "module": "./dist/src/index.js",
   "main": "./dist/src/index.js",
   "types": "./dist/index.d.ts",
+  "bin": {
+    "hanzio-i18n": "./dist/src/i18n/cli.js"
+  },
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -56,6 +59,12 @@
       "import": "./dist/src/api-wrapper/testing.js",
       "default": "./dist/src/api-wrapper/testing.js"
     },
+    "./api-wrapper/connection-auth": {
+      "types": "./dist/api-wrapper/connection-auth.d.ts",
+      "bun": "./src/api-wrapper/connection-auth.ts",
+      "import": "./dist/src/api-wrapper/connection-auth.js",
+      "default": "./dist/src/api-wrapper/connection-auth.js"
+    },
     "./jwt": {
       "types": "./dist/jwt/index.d.ts",
       "bun": "./src/jwt/index.ts",
@@ -86,6 +95,12 @@
       "import": "./dist/src/format/index.js",
       "default": "./dist/src/format/index.js"
     },
+    "./format/phone": {
+      "types": "./dist/format/phone.d.ts",
+      "bun": "./src/format/phone.ts",
+      "import": "./dist/src/format/phone.js",
+      "default": "./dist/src/format/phone.js"
+    },
     "./crypto": {
       "types": "./dist/crypto/index.d.ts",
       "bun": "./src/crypto/index.ts",
@@ -104,6 +119,36 @@
       "import": "./dist/src/i18n/index.js",
       "default": "./dist/src/i18n/index.js"
     },
+    "./i18n/vue": {
+      "types": "./dist/i18n/vue.d.ts",
+      "bun": "./src/i18n/vue.ts",
+      "import": "./dist/src/i18n/vue.js",
+      "default": "./dist/src/i18n/vue.js"
+    },
+    "./i18n/i18next": {
+      "types": "./dist/i18n/i18next.d.ts",
+      "bun": "./src/i18n/i18next.ts",
+      "import": "./dist/src/i18n/i18next.js",
+      "default": "./dist/src/i18n/i18next.js"
+    },
+    "./i18n/vite": {
+      "types": "./dist/i18n/vite.d.ts",
+      "bun": "./src/i18n/vite.ts",
+      "import": "./dist/src/i18n/vite.js",
+      "default": "./dist/src/i18n/vite.js"
+    },
+    "./i18n/check": {
+      "types": "./dist/i18n/check.d.ts",
+      "bun": "./src/i18n/check.ts",
+      "import": "./dist/src/i18n/check.js",
+      "default": "./dist/src/i18n/check.js"
+    },
+    "./iso": {
+      "types": "./dist/iso/index.d.ts",
+      "bun": "./src/iso/index.ts",
+      "import": "./dist/src/iso/index.js",
+      "default": "./dist/src/iso/index.js"
+    },
     "./secrets": {
       "types": "./dist/secrets/index.d.ts",
       "bun": "./src/secrets/index.ts",
@@ -121,11 +166,35 @@
       "bun": "./src/secrets/worker.ts",
       "import": "./dist/src/secrets/worker.js",
       "default": "./dist/src/secrets/worker.js"
+    },
+    "./redis": {
+      "types": "./dist/redis/index.d.ts",
+      "bun": "./src/redis/index.ts",
+      "import": "./dist/src/redis/index.js",
+      "default": "./dist/src/redis/index.js"
+    },
+    "./http": {
+      "types": "./dist/http/index.d.ts",
+      "bun": "./src/http/index.ts",
+      "import": "./dist/src/http/index.js",
+      "default": "./dist/src/http/index.js"
+    },
+    "./cli": {
+      "types": "./dist/cli/index.d.ts",
+      "bun": "./src/cli/index.ts",
+      "import": "./dist/src/cli/index.js",
+      "default": "./dist/src/cli/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing/index.d.ts",
+      "bun": "./src/testing/index.ts",
+      "import": "./dist/src/testing/index.js",
+      "default": "./dist/src/testing/index.js"
     }
   },
   "scripts": {
     "build": "rm -rf dist && bun run build:js && bun run build:types",
-    "build:js": "bun build ./src/index.ts ./src/zod/index.ts ./src/api-wrapper/index.ts ./src/api-wrapper/testing.ts ./src/jwt/index.ts ./src/sitemap/index.ts ./src/p-queue/index.ts ./src/cool-console-log/index.ts ./src/format/index.ts ./src/crypto/index.ts ./src/storage/index.ts ./src/i18n/index.ts ./src/secrets/index.ts ./src/secrets/vite.ts ./src/secrets/worker.ts --outdir ./dist --target node --packages external --splitting",
+    "build:js": "bun build ./src/index.ts ./src/zod/index.ts ./src/api-wrapper/index.ts ./src/api-wrapper/testing.ts ./src/api-wrapper/connection-auth.ts ./src/jwt/index.ts ./src/sitemap/index.ts ./src/p-queue/index.ts ./src/cool-console-log/index.ts ./src/format/index.ts ./src/format/phone.ts ./src/crypto/index.ts ./src/storage/index.ts ./src/i18n/index.ts ./src/i18n/vue.ts ./src/i18n/i18next.ts ./src/i18n/vite.ts ./src/i18n/check.ts ./src/i18n/cli.ts ./src/iso/index.ts ./src/secrets/index.ts ./src/secrets/vite.ts ./src/secrets/worker.ts ./src/redis/index.ts ./src/http/index.ts ./src/cli/index.ts ./src/testing/index.ts --outdir ./dist --target node --packages external --splitting",
     "build:types": "tsgo -p tsconfig.build.json",
     "prepublishOnly": "bun run build",
     "test": "bun test",
@@ -139,19 +208,44 @@
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.6",
+    "@intlify/message-compiler": "^11.4.16",
     "@opentelemetry/api": "^1.9.1",
     "@types/bun": "latest",
     "@typescript/native-preview": "^7.0.0-dev.20260306.1",
     "husky": "^9.1.7",
+    "i18next": "^25.10.10",
+    "libphonenumber-js": "^1.13.15",
     "miniflare": "^4.20260730.0",
     "typescript": "^5.7.0",
     "vite": "^8.2.2",
+    "vue": "^3.5.44",
+    "vue-i18n": "^11.4.16",
     "zod": "^4.3.6"
   },
   "peerDependencies": {
+    "@intlify/message-compiler": ">=10.0.0",
+    "i18next": ">=23.0.0",
+    "libphonenumber-js": "^1.10.0",
+    "vite": ">=6.0.0",
+    "vue-i18n": ">=10.0.0",
     "zod": "^4.3.6"
   },
   "peerDependenciesMeta": {
+    "@intlify/message-compiler": {
+      "optional": true
+    },
+    "i18next": {
+      "optional": true
+    },
+    "libphonenumber-js": {
+      "optional": true
+    },
+    "vite": {
+      "optional": true
+    },
+    "vue-i18n": {
+      "optional": true
+    },
     "zod": {
       "optional": true
     }

package/src/api-wrapper/README.md

@@ -648,6 +648,58 @@ Cache API:
 The cache is also exposed on the client itself as `api.cache` for use outside
 of action handlers (e.g. clearing auth on logout).
 
+### Sharing a login across clients
+
+`ctx.cache` lives for one client. When every request builds its own client
+(one per tenant or per connection, from stored credentials), use
+`ConnectionAuthCache` from `hanzio/api-wrapper/connection-auth` instead: one
+module-level cache shares a single token exchange per connection across all
+of them. It needs `node:crypto` (Bun, Node, Deno, or Workers with
+`nodejs_compat`), so it is not part of `hanzio/api-wrapper`.
+
+```ts
+import { ConnectionAuthCache } from 'hanzio/api-wrapper/connection-auth'
+
+const authCache = new ConnectionAuthCache() // keeps at most 1,000 connections
+
+export function createShopClient(connection: { id: string; apiKey: string; secret: string }) {
+	const auth = authCache.bind({
+		connectionId: connection.id,
+		authInputs: [connection.apiKey, connection.secret],
+		refreshMarginMs: 60_000,
+		exchange: () => login(connection) // resolves { token, expiresAt }
+	})
+
+	return {
+		async get(path: string, signal?: AbortSignal) {
+			for (let attempt = 0; ; attempt++) {
+				const current = await auth.get({ signal })
+				const response = await fetch(`https://shop.example.com${path}`, {
+					headers: { authorization: `Bearer ${current.token}` },
+					signal
+				})
+				// One retry with a new login when the token was refused.
+				if (response.status !== 401 || attempt > 0) return response
+				auth.reject(current)
+			}
+		}
+	}
+}
+```
+
+- Concurrent callers share one exchange, and aborting one caller's wait leaves
+  it running for the others.
+- Changing any `authInputs` value (a rotated secret) retires the old token: a
+  client still using the old credentials can finish its request but cannot
+  store its token. The inputs are kept only as an HMAC under a random key.
+- `reject(token)` drops a token the API refused, unless a newer login has
+  already replaced it. `get({ fresh: true })` always exchanges, for an explicit
+  credential check, and never falls back to the old token when it fails.
+- `clear()` forgets everything, including exchanges still in flight.
+
+`connectionAuthContract` in [`hanzio/testing`](../testing/README.md#connection-auth-contract)
+runs these races against your client.
+
 ## Endpoint Configuration Reference
 
 | Option | Required | Description |

package/src/api-wrapper/connection-auth.ts

@@ -0,0 +1,142 @@
+import { createHmac, randomBytes } from 'node:crypto'
+import { raceAbort } from '../promise'
+
+export type ConnectionAuthToken = { token: string; expiresAt: number }
+
+type Entry = {
+	identity: string
+	token?: ConnectionAuthToken
+	pending?: Promise<ConnectionAuthToken>
+}
+
+/**
+ * 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 class ConnectionAuthCache {
+	private readonly key = randomBytes(32)
+	private readonly entries = new Map<string, Entry>()
+
+	constructor(private readonly maxEntries = 1_000) {}
+
+	get size() {
+		return this.entries.size
+	}
+
+	clear() {
+		for (const entry of this.entries.values()) entry.token = undefined
+		this.entries.clear()
+	}
+
+	private prune(protectedEntry?: Entry) {
+		for (const [connectionId, entry] of this.entries) {
+			if (this.entries.size <= this.maxEntries) break
+			// In-flight work must remain discoverable by identical callers. Its
+			// ownership ends on settlement, when pruning runs again.
+			if (entry.pending || entry === protectedEntry) continue
+			entry.token = undefined
+			this.entries.delete(connectionId)
+		}
+	}
+
+	bind(input: {
+		connectionId: string
+		authInputs: readonly (string | number)[]
+		refreshMarginMs: number
+		exchange: () => Promise<ConnectionAuthToken>
+	}) {
+		const identity = createHmac('sha256', this.key)
+			.update(JSON.stringify(input.authInputs))
+			.digest('hex')
+		let entry = this.entries.get(input.connectionId)
+
+		if (!entry || entry.identity !== identity) {
+			if (entry) entry.token = undefined
+			entry = { identity }
+		}
+
+		// Map order is LRU. Eviction never cancels an exchange already in use.
+		this.entries.delete(input.connectionId)
+		this.entries.set(input.connectionId, entry)
+		this.prune(entry)
+
+		const state = entry
+		const get = (options?: { fresh?: boolean; signal?: AbortSignal }) => {
+			if (options?.signal?.aborted) {
+				return Promise.reject<ConnectionAuthToken>(options.signal.reason)
+			}
+
+			if (this.entries.get(input.connectionId) === state) {
+				this.entries.delete(input.connectionId)
+				this.entries.set(input.connectionId, state)
+			}
+
+			// Aborting cancels only this wait; the exchange belongs to every waiter.
+			if (state.pending) return raceAbort(state.pending, options?.signal)
+			if (
+				!options?.fresh &&
+				state.token &&
+				state.token.expiresAt - Date.now() > input.refreshMarginMs
+			) {
+				return Promise.resolve(state.token)
+			}
+
+			// A fresh check cannot leave the previous token usable after failure.
+			state.token = undefined
+			const pending = input
+				.exchange()
+				.then((token) => {
+					if (this.entries.get(input.connectionId) === state) {
+						state.token = token
+					}
+					return token
+				})
+				.finally(() => {
+					if (state.pending === pending) state.pending = undefined
+					this.prune()
+				})
+			state.pending = pending
+
+			return raceAbort(pending, options?.signal)
+		}
+
+		return {
+			get,
+			reject(token: ConnectionAuthToken) {
+				if (state.token === token) state.token = undefined
+			}
+		}
+	}
+}

package/src/cli/README.md

@@ -0,0 +1,220 @@
+---
+description: Typed CLIs from Zod object schemas, parsed with node:util parseArgs, with generated help, completion and consistent exit codes.
+---
+
+# hanzio/cli
+
+Each command's `input` is a Zod object: its keys become flags, Zod validates
+them, and `run` gets the typed result. Parsing is `node:util` `parseArgs`, so
+there is no extra dependency. Runs in Bun and Node 22.4+; needs `zod` 4.
+
+```ts
+// src/cli.ts
+import { z } from 'zod'
+import { defineCli, defineCommand } from 'hanzio/cli'
+
+export default defineCli({
+	name: 'better-mastra-evals',
+	version: '1.0.0',
+	commands: {
+		run: defineCommand({
+			description: 'Run eval suites',
+			input: z.object({
+				suite: z.string().meta({ positional: true }),
+				repeats: z.number().default(1).describe('Runs per case'),
+				json: z.boolean().optional()
+			}),
+			run: async (input, ctx) => {
+				// input: { suite: string; repeats: number; json?: boolean }
+			}
+		}),
+		inspect: () => import('./commands/inspect') // loaded only when used
+	}
+})
+```
+
+```ts
+#!/usr/bin/env node
+// bin.ts
+import cli from './cli.js'
+
+process.exitCode = await cli.run()
+```
+
+Use `process.exit(await cli.run())` instead when open database or Redis
+handles would keep the process alive.
+
+## Flags
+
+| Schema | Command line |
+| --- | --- |
+| `z.string()`, `z.enum([...])` | `--name value` or `--name=value` |
+| `z.number()` | `--repeats 3`, coerced before validation |
+| `z.boolean()` | `--json`; `--no-json` sets `false`; missing is `false` |
+| `z.array(z.string())` | repeatable: `--model a --model b`; missing is `[]` |
+| `.optional()`, `.default(x)` | may be left out |
+| `.describe('…')` | help text |
+| `.meta({ positional: true })` | positional, in key order; an array takes the rest |
+| `.meta({ alias: 'r' })` | `-r value` |
+| `.meta({ env: 'APP_REGION' })` | read from the environment when the flag is missing |
+
+Keys are camelCase in the schema and kebab-case on the command line (`dryRun`
+→ `--dry-run`). These are the same `.meta()` keys as `trpc-cli`, plus `env`;
+importing `hanzio/cli` types them on Zod's `GlobalMeta`.
+Pipes read their input side, so `z.stringbool()` takes `--submit true`.
+
+Every CLI gets `-h`/`--help` (root, groups and commands), `--version` when you
+pass `version`, and "Did you mean …?" for mistyped commands and flags.
+
+## Commands
+
+`commands` is a single command for a one-command CLI, or an object of
+commands and nested groups, so `{ check: { docs } }` runs as `tool check
+docs`. Groups are plain objects, so an adapter can build them from data.
+
+A command is one of:
+
+- `defineCommand({ description, input, run, output })`.
+- `() => import('./commands/heavy')`, a module whose default export is a
+  command. It loads only when it runs.
+- `defineCommand({ description, load: () => import('./commands/heavy') })`,
+  the same with a description for the command list.
+- `defineCommand({ raw: true, run })`, which skips parsing: every argument
+  after the command name is in `ctx.argv` (for `tool prisma migrate dev`).
+
+`run(input, ctx)` gets:
+
+| `ctx` | |
+| --- | --- |
+| `context` | what `defineCli({ context })` returned |
+| `globals` | the parsed global options |
+| `path` | command names, e.g. `['deal', 'list']` |
+| `passthrough` | arguments after `--` (`tool exec -- bun test`) |
+| `argv` | every argument after the command names, unparsed |
+| `json` | `--json` was passed |
+| `stdout`, `stderr`, `env` | the CLI's streams and environment |
+| `exitCode` | set it to fail without an error message |
+
+Whatever `run` returns goes to `output(result, ctx)`. The default prints
+strings as they are and anything else as indented JSON, or compact JSON with
+`--json`; `undefined` prints nothing.
+
+## Globals, context and guard
+
+```ts
+const cli = defineCli({
+	name: 'app',
+	globals: z.object({
+		org: z.string().optional(),
+		allowProduction: z.boolean().optional(),
+		json: z.boolean().optional()
+	}),
+	context: async (globals) => ({ db: await connect(), org: globals.org }),
+	guard: ({ context, globals }) => {
+		if (context.db.isProduction && !globals.allowProduction)
+			throw new CliError('Refusing production; pass --allow-production')
+	},
+	commands: { deal: { list, get } }
+})
+```
+
+Globals are accepted before or after the command names. `context` runs after
+parsing, so `--help` never connects anywhere. `guard` runs before every
+command. A command defined in its own file types its context by annotating
+`ctx`:
+
+```ts
+export const list = defineCommand({
+	input: z.object({ limit: z.number().default(20) }),
+	run: (input, { context }: CommandContext<AppContext>) =>
+		context.db.deal.findMany({ take: input.limit })
+})
+```
+
+`defineCli` rejects a command whose context type doesn't match `context`, and
+requires `context` once any command needs one.
+
+## Errors and exit codes
+
+| Exit | When |
+| --- | --- |
+| 0 | the command finished |
+| 1 | `run` threw, or set `ctx.exitCode = 1` |
+| 2 | bad arguments: unknown command or flag, failed validation |
+
+Throw `new CliError(message, { exitCode })` for expected failures: the
+message is printed without a stack. Other errors print their stack. With
+`--json`, errors print as `{"error": "…"}`. Usage errors name the flag:
+
+```
+--repeats: Invalid input: expected number, received string
+Run "better-mastra-evals run --help" for usage.
+```
+
+## Shell completion
+
+A CLI with commands also gets `tool completion bash` and `tool completion
+zsh`, which print a script that completes command names and flags:
+
+```sh
+# in ~/.zshrc (or ~/.bashrc with bash)
+source <(tool completion zsh)
+```
+
+## Testing
+
+`cli.run(argv, { stdout, stderr, env })` resolves to the exit code and never
+touches `process`, so tests don't spawn anything:
+
+```ts
+let out = ''
+const code = await cli.run(['run', 'smoke', '--json'], {
+	stdout: { write: (text) => (out += text) },
+	stderr: { write: () => {} },
+	env: {}
+})
+expect(code).toBe(0)
+```
+
+## Migrating from `parseArgs`
+
+1. Turn the `options` object into a `z.object`: `type: 'string'` becomes
+   `z.string()`, `multiple: true` becomes `z.array(...)`, `default` becomes
+   `.default()`, `short: 'r'` becomes `.meta({ alias: 'r' })`, and
+   positionals become keys with `.meta({ positional: true })`.
+2. Delete the hand-written validation (`Number(values.repeats)`, enum
+   checks, "--x required" errors): `z.number()`, `z.enum()` and required keys
+   do it, with the flag in the error.
+3. Move each `switch (positionals[0])` branch into a `defineCommand`, and its
+   help line into `description` / `.describe()`. Delete the `USAGE` string.
+4. Replace `console.error(...); process.exit(1)` with `throw new CliError(...)`,
+   and the `main().catch(...)` wrapper with `process.exitCode = await cli.run()`.
+
+```ts
+// before
+const { values, positionals } = parseArgs({
+	allowPositionals: true,
+	options: { out: { type: 'string', short: 'o' }, force: { type: 'boolean' } }
+})
+if (positionals[0] !== 'add' || !values.out) {
+	console.error(USAGE)
+	process.exit(2)
+}
+await add(positionals.slice(1), values)
+
+// after
+defineCli({
+	name: 'tool',
+	commands: {
+		add: defineCommand({
+			description: 'Copy fragments into a schema folder',
+			input: z.object({
+				fragments: z.array(z.string()).min(1).meta({ positional: true }),
+				out: z.string().meta({ alias: 'o' }),
+				force: z.boolean()
+			}),
+			run: (input) => add(input.fragments, input)
+		})
+	}
+})
+```