hanzio 2.1.0 → 3.0.0

package/src/i18n/README.md

@@ -0,0 +1,65 @@
+---
+description: Typed `{name}` placeholders, interpolation and a small typed translator.
+---
+
+# hanzio/i18n
+
+A typed helper for `{name}` message templates, not an i18n framework: no
+plurals, ICU, locale negotiation or escaping.
+
+```ts
+import { createTranslator, extractPlaceholders, interpolate } from 'hanzio/i18n'
+
+interpolate('Hi {name}, you have {count} messages', { name: 'Ada', count: 3 })
+// 'Hi Ada, you have 3 messages'
+
+interpolate('Hi {name}') // type error: params required
+interpolate('Hi {name}', { nam: 'Ada' }) // type error: misspelled
+
+extractPlaceholders('{name} has {count} items, {name}') // ['name', 'count']
+```
+
+## Placeholders
+
+A placeholder is `{` + word characters (`[A-Za-z0-9_]`) + `}`. Anything else is
+plain text: `{ name }`, `{}`, `{count, plural, ...}`. The types and the runtime
+use the same rule.
+
+- A placeholder without a param (or with `null`/`undefined`) stays as `{name}`.
+- Only own properties of `params` are used, so `{toString}` is never filled from
+  `Object.prototype`.
+- Values are `string | number`, converted with `String()`.
+
+Types:
+
+| Type                     | `'Hi {name}, {count}'`                       |
+| ------------------------ | -------------------------------------------- |
+| `PlaceholderNames<S>`    | `'name' \| 'count'`                          |
+| `PlaceholderParams<S>`   | `{ name: string \| number; count: ... }`     |
+| `PlaceholderArgs<S>`     | `[params: PlaceholderParams<S>]`, `[]` if none |
+
+For a non-literal `string` template, names are `string` and params are optional.
+
+## Translator
+
+```ts
+const messages = {
+	common: { save: 'Save' },
+	greeting: 'Hi {name}'
+} as const
+
+const t = createTranslator(messages)
+
+t('common.save') // 'Save'
+t('greeting', { name: 'Ada' }) // 'Hi Ada'
+t('greeting') // type error: params required
+t('common.save', { name: 'Ada' }) // type error: no placeholders
+t('common.missing') // type error: unknown key
+```
+
+Keys are the dot paths of the string leaves (`MessageKeys<T>`). Pass the
+messages inline or `as const` so the templates stay literal; with plain
+`Record<string, string>` messages (for example JSON imports) keys are `string`
+and params are optional. A key that is missing at runtime returns the key.
+
+`flattenMessages(messages)` gives the flat map: `{ 'common.save': 'Save', greeting: 'Hi {name}' }`.

package/src/jwt/README.md

@@ -0,0 +1,70 @@
+---
+description: JWT sign/verify/decode using built-in Web Crypto HMAC (HS256/HS384/HS512).
+---
+
+# hanzio/jwt
+
+```ts
+import { jwtDecode, jwtSign, jwtVerify, jwtVerifyResult } from 'hanzio/jwt'
+
+const token = await jwtSign({ sub: 'user-1' }, secret, {
+	expiresIn: 60 * 60, // seconds
+	issuer: 'api',
+	audience: 'web'
+})
+
+// Payload or null
+const payload = await jwtVerify<{ sub: string }>(token, secret)
+
+// Result with a reason
+const result = await jwtVerifyResult(token, secret, {
+	issuer: 'api',
+	audience: 'web',
+	leewaySec: 30
+})
+if (!result.ok) console.log(result.error.code) // 'expired', 'invalid_signature', …
+
+// Unverified: for reading claims client-side, never for auth
+const decoded = jwtDecode(token) // { header, payload } | null
+```
+
+## Signing
+
+`jwtSign(payload, secret, options?)`
+
+| Option       | Claim | Notes                               |
+| ------------ | ----- | ----------------------------------- |
+| `expiresIn`  | `exp` | seconds from now                    |
+| `notBefore`  | `nbf` | seconds from now                    |
+| `issuer`     | `iss` |                                     |
+| `audience`   | `aud` | `string \| string[]`                |
+| `algorithm`  | —     | `'HS256'` (default), `'HS384'`, `'HS512'` |
+
+- `iat` is always set to the current time.
+- Options win: a claim set through an option replaces the same claim in `payload`.
+  Payload claims are kept when the option is omitted.
+- Non-finite `expiresIn`/`notBefore` throw a `TypeError`.
+- The header is `{ alg, typ: 'JWT' }`.
+
+## Verifying
+
+`jwtVerifyResult(token, secret, options?)` returns
+`Result<Payload, JwtVerifyError>` (see `hanzio` promise helpers). `error.code` is one of
+`'malformed' | 'unsupported_alg' | 'invalid_signature' | 'expired' | 'not_yet_valid' | 'invalid_issuer' | 'invalid_audience'`.
+
+| Option       | Default                 | Notes                                      |
+| ------------ | ----------------------- | ------------------------------------------ |
+| `leewaySec`  | `0`                     | clock skew tolerance for `exp` / `nbf`     |
+| `issuer`     | —                       | required `iss`                             |
+| `audience`   | —                       | must equal `aud` or be one of its entries  |
+| `algorithms` | `['HS256','HS384','HS512']` | the header `alg` must be in this list |
+
+- The signature is checked before any claim, so unsigned claims never decide the error code.
+- `alg: 'none'` and anything outside `algorithms` is rejected as `unsupported_alg`.
+- Configuration errors (no Web Crypto, empty secret) throw. `jwtVerify` swallows them
+  and returns `null`, like any other failure.
+
+Imported `CryptoKey`s are cached per secret, algorithm and usage (up to 100 entries).
+
+The base64url and UTF-8 helpers this module uses are public in
+[`hanzio/crypto`](../crypto/README.md) (`encodeBase64Url`, `decodeBase64Url`, …).

package/src/p-queue/README.md

@@ -0,0 +1,237 @@
+---
+description: Promise queue with concurrency, priority, timeout, cancellation, and rate-limit controls.
+---
+
+# hanzio/p-queue
+
+`hanzio/p-queue` is a small dependency-free promise queue inspired by
+`p-queue`. Use it when you need to run async work with bounded concurrency,
+priority ordering, basic rate limiting, or queue lifecycle hooks.
+
+```ts
+import PQueue from 'hanzio/p-queue'
+
+const queue = new PQueue({ concurrency: 2 })
+
+const results = await Promise.all([
+	queue.add(async () => fetchUser('1')),
+	queue.add(async () => fetchUser('2')),
+	queue.add(async () => fetchUser('3'))
+])
+
+await queue.onIdle()
+```
+
+## Common Usage
+
+### Limit Concurrency
+
+```ts
+const queue = new PQueue({ concurrency: 3 })
+
+for (const id of userIds) {
+	queue.add(async () => syncUser(id))
+}
+
+await queue.onIdle()
+```
+
+Only three tasks run at the same time. Queued tasks start as running tasks
+finish.
+
+### Add Multiple Tasks
+
+```ts
+const results = await queue.addAll([
+	async () => 'first',
+	async () => 'second'
+])
+```
+
+`addAll` resolves results in the same order as the input functions.
+
+### Pause And Resume
+
+```ts
+const queue = new PQueue({ autoStart: false })
+
+queue.add(async () => syncUser('1'))
+queue.add(async () => syncUser('2'))
+
+queue.start()
+await queue.onIdle()
+```
+
+Use `pause()` to stop starting new queued tasks. Running tasks continue.
+
+```ts
+queue.pause()
+queue.start()
+```
+
+### Priority
+
+Higher priority tasks run first. Tasks with the same priority keep FIFO order.
+
+```ts
+const queue = new PQueue({ concurrency: 1, autoStart: false })
+
+queue.add(async () => 'low', { priority: 0, id: 'low' })
+queue.add(async () => 'high', { priority: 10, id: 'high' })
+
+queue.start()
+```
+
+You can update queued task priority by id before it starts:
+
+```ts
+queue.setPriority('low', 20)
+```
+
+### Timeout
+
+Timeouts begin when the task starts running, not while it is waiting in the
+queue.
+
+```ts
+import PQueue, { TimeoutError } from 'hanzio/p-queue'
+
+const queue = new PQueue({ timeout: 1000 })
+
+try {
+	await queue.add(async () => slowTask())
+} catch (error) {
+	if (error instanceof TimeoutError) {
+		console.log('Task timed out')
+	}
+}
+```
+
+Override the timeout per task:
+
+```ts
+await queue.add(async () => slowTask(), { timeout: 5000 })
+```
+
+### Cancellation
+
+Pass an `AbortSignal` to remove a queued task or reject a running task. The task
+also receives the same signal.
+
+```ts
+const controller = new AbortController()
+
+const promise = queue.add(
+	async ({ signal }) => {
+		const response = await fetch(url, { signal })
+		return response.json()
+	},
+	{ signal: controller.signal }
+)
+
+controller.abort(new Error('Cancelled'))
+await promise
+```
+
+### Rate Limiting
+
+Use `intervalCap` and `interval` to limit how many tasks start during a time
+window.
+
+```ts
+const queue = new PQueue({
+	concurrency: 5,
+	intervalCap: 10,
+	interval: 1000
+})
+```
+
+Enable `strict` to use a sliding window instead of a fixed window.
+
+```ts
+const queue = new PQueue({
+	intervalCap: 10,
+	interval: 1000,
+	strict: true
+})
+```
+
+## Waiting For Queue State
+
+```ts
+await queue.onEmpty()
+await queue.onIdle()
+await queue.onPendingZero()
+await queue.onSizeLessThan(10)
+await queue.onRateLimit()
+await queue.onRateLimitCleared()
+```
+
+- `onEmpty()` resolves when there are no queued tasks waiting to start.
+- `onIdle()` resolves when there are no queued or running tasks.
+- `onPendingZero()` resolves when all currently running tasks finish.
+- `onSizeLessThan(limit)` resolves when `queue.size < limit`.
+- `onRateLimit()` resolves when the queue becomes rate-limited.
+- `onRateLimitCleared()` resolves when rate limiting clears.
+
+## Events
+
+```ts
+queue.on('active', () => {
+	console.log('A task started')
+})
+
+queue.on('completed', (result) => {
+	console.log('Task completed', result)
+})
+
+queue.on('error', (error) => {
+	console.error('Task failed', error)
+})
+```
+
+Supported events:
+
+- `add`
+- `active`
+- `completed`
+- `error`
+- `empty`
+- `idle`
+- `pendingZero`
+- `next`
+- `rateLimit`
+- `rateLimitCleared`
+
+Use `off(event, listener)` to remove a listener.
+
+## State
+
+```ts
+queue.size
+queue.pending
+queue.isPaused
+queue.isRateLimited
+queue.isSaturated
+queue.runningTasks
+queue.concurrency = 5
+queue.timeout = 2000
+```
+
+- `size` is the number of queued tasks waiting to start.
+- `pending` is the number of running tasks.
+- `runningTasks` returns task metadata for currently running tasks.
+- `clear()` removes queued tasks but does not cancel tasks already running.
+
+## Exports
+
+```ts
+import PQueue, {
+	PriorityQueue,
+	TimeoutError,
+	type Options,
+	type Queue,
+	type QueueAddOptions,
+	type TaskOptions
+} from 'hanzio/p-queue'
+```