@rdlabo/workers-hono-kit 0.10.6 → 0.11.1-beta.pr46.sha8ccc8da384f0

package/docs/cli.md

@@ -0,0 +1,33 @@
+# CLI
+
+The package ships `bin` commands that can be run with `npx` or wired into npm scripts in the consuming app. They are operational helpers: AWS credential sync, subrequest fan-out gating, and brownfield database baselining.
+
+| Command | Use |
+| --- | --- |
+| `workers-hono-kit-sync-dev-aws <wrangler-args…>` | Launch `wrangler` with AWS credentials injected as `--var`, resolved from the active AWS profile (honors `AWS_PROFILE`, supports short-lived SSO/temporary creds). Nothing is written to disk — replaces `.dev.vars`. Wire it as the `dev` script, e.g. `AWS_PROFILE=<p> workers-hono-kit-sync-dev-aws dev --var APP_ENV:development`. |
+| `workers-hono-kit-check-subrequest-fanout [dir…]` | CI gate that greps for per-item external-call fan-outs (`runWithConcurrency(` / `PromisePool` / `.withConcurrency(`) that would eventually exceed the Workers subrequest cap. Annotate a genuinely-safe site with `subrequest-ok`. Scans `src` by default; exits 1 on an un-annotated marker. |
+| `workers-hono-kit-db-baseline [--migrations ./drizzle]` | Brownfield first-deploy helper: record the baseline `0000` migration as *already applied* on an existing MySQL DB without running its DDL (the CLI wrapper around `baselineMigrations` / `readBaselineEntry`). Reads DB credentials from `DB_SECRET` (AWS RDS managed secret) or the individual `DB_*` env vars. |
+
+## `workers-hono-kit-sync-dev-aws`
+
+Use this in the `dev` npm script when you want AWS credentials from the active profile to be available inside `wrangler dev` without committing them to `.dev.vars`. It resolves short-lived SSO or temporary credentials and passes them as `--var` arguments. Nothing is written to disk.
+
+```bash
+AWS_PROFILE=my-sso-profile workers-hono-kit-sync-dev-aws dev --var APP_ENV:development
+```
+
+## `workers-hono-kit-check-subrequest-fanout`
+
+Run this in CI to catch per-item external call patterns (for example `runWithConcurrency`, `PromisePool`, or `.withConcurrency`) that could fan out beyond the Workers subrequest cap. If a call site is safe, annotate it with `subrequest-ok`. The command scans `src` by default and exits with `1` if it finds an un-annotated marker.
+
+```bash
+workers-hono-kit-check-subrequest-fanout src
+```
+
+## `workers-hono-kit-db-baseline`
+
+Use this for a brownfield first deploy against a MySQL database that already matches the schema in your first migration (`0000_*`). It records that migration as already applied without running its DDL, so later migrations can apply normally. Database credentials are read from `DB_SECRET` (an AWS RDS managed-secret JSON string) or from individual `DB_*` environment variables.
+
+```bash
+workers-hono-kit-db-baseline --migrations ./drizzle
+```

package/docs/data-layer.md

@@ -0,0 +1,54 @@
+Import database helpers from `@rdlabo/workers-hono-kit/db`. This entry point requires `drizzle-orm` and `mysql2`.
+
+## Hyperdrive database
+
+`createHyperdriveDatabase()` lazily opens primary and replica connections from Hyperdrive bindings. `read()` uses the replica query runner; `query()` provides an explicit raw primary SELECT for read-after-write consistency; writes and transactions use the primary Drizzle instance. `readTransaction()` runs Drizzle and raw reads against one primary repeatable-read snapshot. Read transactions are serialized on one separately cached connection so their boundaries cannot mix with each other or with ordinary primary operations. After a fatal mysql2 connection error, a single read or the complete read-only transaction opens a fresh connection and repeats at most once. Writes and write transactions are not repeated because their commit state may be ambiguous. Workers owns connection cleanup at invocation end.
+
+```ts
+import { createHyperdriveDatabase } from '@rdlabo/workers-hono-kit/db';
+import { drizzle } from 'drizzle-orm/mysql2';
+
+const db = createHyperdriveDatabase({
+  primaryHyperdrive: env.DB_PRIMARY,
+  replicaHyperdrive: env.DB_REPLICA,
+  createOrm: (primary) => drizzle(primary, { schema }),
+});
+
+const rows = await db.read<Item>('SELECT * FROM items WHERE id = ?', [id]);
+const freshRows = await db.query<Item[]>('SELECT * FROM items WHERE id = ?', [id]);
+await db.write((dz) => dz.insert(items).values(input));
+await db.transaction((tx) => tx.insert(items).values(input));
+
+const snapshot = await db.readTransaction(async ({ orm, query }) => ({
+  items: await orm.select().from(items),
+  count: await query<{ count: number }[]>('SELECT COUNT(*) count FROM items'),
+}));
+```
+
+MySQL enforces `READ ONLY` for every transaction attempt. Drizzle does not provide a distinct read-only transaction type, so applications can wrap `orm` in a SELECT-only facade when they also want compile-time enforcement.
+
+Do not call `readTransaction()` recursively from inside its callback. Calls share one serialized snapshot lane, so a nested call would wait for its own outer transaction to finish. Consumers that expose nested snapshot helpers should reuse the outer reader instead.
+
+Use `hyperdriveConnectionOptions()` when constructing lower-level mysql2 connections. The default JavaScript date conversion timezone is `+09:00`; it does not change the MySQL session timezone.
+
+## Writes and retries
+
+- `retryWhenDeadlock()` retries `ER_LOCK_DEADLOCK` with exponential backoff.
+- `insertIdOf()`, `affectedRowsOf()`, and `insertedIdsOf()` normalize mysql2 write results.
+- `withMysqlConnections()` opens primary and replica connections in parallel for a scoped operation.
+
+## Drizzle and JST helpers
+
+Use `jstTimestamp`, `jstDatetime`, and `jstDate` for shared date behavior. Pair update timestamps with `jstOnUpdateNow()` because custom timestamp types do not expose Drizzle's `.onUpdateNow()`. For decimal columns, use Drizzle's `decimal(name, { precision, scale, mode: 'number' })` directly.
+
+The `/business-time` entry point converts instants and business dates in the JST business timezone:
+
+```ts
+import { addBusinessDays, toBusinessDateTime } from '@rdlabo/workers-hono-kit/business-time';
+
+toBusinessDateTime(new Date('2026-07-05T21:00:00Z'));
+// '2026-07-06 06:00:00'
+
+addBusinessDays('2026-07-06', 3);
+// '2026-07-09'
+```

package/docs/development.md

@@ -0,0 +1,32 @@
+# Development
+
+These commands are used when working on the package itself:
+
+```bash
+npm install
+npm run typecheck   # tsc --noEmit
+npm run lint        # eslint
+npm test            # vitest
+npm run build       # tsc -p tsconfig.build.json → dist/
+```
+
+## Local development / linking
+
+If you consume this package via a local path (e.g. `"@rdlabo/workers-hono-kit": "../../hono-kit"`) rather than from npm, TypeScript and esbuild resolve the package's bare imports from *its own* `node_modules`, which can create a second `zod` instance. That breaks types where your zod-inferred values flow into other libraries (e.g. Drizzle inserts). Dedupe with tsconfig `paths`:
+
+```jsonc
+{
+  "compilerOptions": {
+    "baseUrl": ".",
+    "paths": {
+      "zod": ["node_modules/zod"],
+      "zod/*": ["node_modules/zod/*"],
+      "@hono/zod-validator": ["node_modules/@hono/zod-validator"]
+    }
+  }
+}
+```
+
+When installed from npm normally, package managers dedupe `zod` to a single copy and this is not needed.
+
+When developing against the kit via a direct `file:` link, run `npm install` in the kit repo itself to satisfy its peers (do not add `overrides` on the consumer side).

package/docs/http-auth.md

@@ -0,0 +1,36 @@
+## Validation
+
+`validate(target, schema, options?)` adapts a Zod schema to Hono and returns a NestJS `ValidationPipe`-shaped `400` response. Use `createValidate({ sentry })` to bind optional reporting once.
+
+```ts
+import { createValidate, zNumOptional } from '@rdlabo/workers-hono-kit';
+import { z } from 'zod';
+
+const validate = createValidate({ sentry });
+const querySchema = z.object({ page: zNumOptional() });
+
+app.get('/items', validate('query', querySchema), async (c) => {
+  const query = c.req.valid('query');
+  return c.json(await listItems(query.page));
+});
+```
+
+## Authentication
+
+`createAuthMiddleware()` reads a token header, verifies a Firebase ID token, optionally resolves the application user ID, and stores the result on the Hono context. Use `createRemoteFirebaseVerifier(projectId)` for cached remote JWKS verification or `createServiceAccountVerifier()` when Identity Toolkit `getUser` and `deleteUser` operations are required.
+
+Keep identity, reauthentication, and feature credential failures distinct with the stable auth-failure body helpers.
+
+## Error and routing contracts
+
+- `createAppErrorHandler()` composes query failure classification, generic mysql2 classification, and optional reporting.
+- `createHttpErrorHandler()` maps `HTTPException` to the shared JSON error body.
+- `notFoundHandler()` returns `Cannot METHOD path` with a 404 status.
+- `normalizeTrailingSlash()` removes trailing slashes without redirecting, preserving request bodies.
+- `finalizeResponse()` adds weak ETags and handles matching `If-None-Match` requests.
+
+Mount `createMaintenanceMiddleware()` after CORS and before container or database middleware so maintenance responses do not initialize expensive infrastructure.
+
+## Deferred work and observability
+
+`createWaitUntilDefer(ctx)` registers background work through `waitUntil` and logs rejected work. `perfLog()` emits per-request application latency, colo, cold/warm state, route, and status to Workers Logs and optionally Analytics Engine.

package/docs/realtime-offline.md

@@ -0,0 +1,27 @@
+## Durable Object realtime
+
+The root and `/realtime` entry points expose the same focused realtime primitives:
+
+- `configureHibernationAutoResponse()` configures runtime ping/pong without waking JavaScript.
+- `upgradeHibernationWebSocket()` attaches state before accepting the socket.
+- `broadcastHibernationWebSockets()` broadcasts through sockets restored by `getWebSockets()`.
+- `acknowledgeHibernationWebSocketClose()` and `closeHibernationWebSocket()` normalize close handling.
+- `retryDurableObjectOperation()` retries only errors marked `retryable` and not `overloaded`. Create a fresh stub inside the operation for every attempt.
+- `invokeDurableObjectFetch()` preserves the structured response/error contract for DO calls.
+
+WebSocket protocol parsers validate offered subprotocols before upgrade.
+
+## Offline replica contracts
+
+`@rdlabo/workers-hono-kit/offline` is table-agnostic. Product schemas, Zod objects, public-column allowlists, schema hashes, and domain policy stay in the application.
+
+`defineRestDbMethodConverter()` types a pure REST method ↔ table converter. Every represented table and column is required, including nullable/default columns. Omit an auto-increment `id` from the product-owned table scheme when a create method intentionally does not own it.
+
+Wire helpers canonicalize values:
+
+- `toReplicaIsoDatetime()` → UTC ISO-8601
+- `toReplicaDateOnly()` → `YYYY-MM-DD` or `null`
+- `toTinyIntFlag()` / `fromTinyIntFlag()` → boolean/tinyint conversion
+- `replicaNowIso(clock?)` → injectable current time
+
+Journal helpers enforce cursor coverage, retention, mutation transactions, and rebaseline behavior. Wire compatibility helpers let an application accept explicit previous fingerprints while maintaining a canonical current fingerprint.

package/docs/role-policies.md

@@ -0,0 +1,48 @@
+# Storage-agnostic role policies
+
+`createRolePolicy` builds pure RBAC checks without coupling the policy to a database schema. The application can resolve roles from a membership table, a `users.role` column, token claims, or any other source.
+
+```ts
+import { createRolePolicy } from '@rdlabo/workers-hono-kit';
+
+type Role = 'owner' | 'admin' | 'member' | 'read';
+type Permission = 'organization.manage' | 'resource.write' | 'resource.read';
+
+const policy = createRolePolicy<Role, Permission>({
+  permissions: {
+    owner: ['organization.manage', 'resource.write', 'resource.read'],
+    admin: ['resource.write', 'resource.read'],
+    member: ['resource.write', 'resource.read'],
+    read: ['resource.read'],
+  },
+  assignableRoles: {
+    owner: ['admin', 'member', 'read'],
+    admin: ['member', 'read'],
+    member: [],
+    read: [],
+  },
+  manageableRoles: {
+    owner: ['admin', 'member', 'read'],
+    admin: ['member', 'read'],
+    member: [],
+    read: [],
+  },
+});
+```
+
+## Policy fields
+
+- `permissions` maps a role to the set of permissions it grants.
+- `assignableRoles` defines which roles an actor may grant to another subject.
+- `manageableRoles` defines which existing subject roles an actor may manage.
+
+The resulting `RolePolicy` has four pure checks:
+
+```ts
+policy.hasPermission('member', 'resource.write');        // true
+policy.canAssignRole('admin', 'member');                 // true
+policy.canManageRole('owner', 'admin');                  // true
+policy.canChangeRole('owner', 'admin', 'member');        // true
+```
+
+`canChangeRole(actor, current, next)` is a combination: the actor must be able to manage the subject's current role and also be allowed to assign the next role. Keeping role lookup and policy checks separate means the same policy can be reused no matter where roles are stored.

package/docs/testing-operations.md

@@ -0,0 +1,25 @@
+## Testing entry point
+
+`@rdlabo/workers-hono-kit/testing` requires the database peers and is never loaded by production code.
+
+| Helper                                                          | Use                                                                   |
+| --------------------------------------------------------------- | --------------------------------------------------------------------- |
+| `createTestDb()`                                                | Build a Drizzle-migration-backed test database.                       |
+| `FakeFirebaseVerifier`                                          | Verify registered in-memory Firebase tokens.                          |
+| `createPoolDatabase()` / `createNoopDatabase()`                 | Provide database implementations for tests.                           |
+| `authHeaders()` / `registerFirebaseToken()` / `provisionUser()` | Prepare authenticated route tests.                                    |
+| `configurableFake()`                                            | Create a partial fake that fails explicitly for unconfigured members. |
+| `fakeKv()` / `fakeQueue()`                                      | Use in-memory Workers binding fakes.                                  |
+| Stripe fixture factories                                        | Create typed events, sessions, subscriptions, prices, and intents.    |
+
+## Queues
+
+`sendInChunks()` bounds queue sends under Workers subrequest limits. `processBatch()` handles a message batch sequentially, bounding concurrent subrequests to one; errors explicitly marked with `queueDisposition: 'discard'` are acknowledged, while other failures retry. `createQueueErrorHandler()` adds logging and optional final-attempt reporting.
+
+## Operational CLI
+
+The package publishes commands for synchronizing development AWS credentials, checking subrequest fanout, creating database baselines, checking realtime bundles, and querying Durable Object metrics. Run the exact CLI shipped with the installed package version and review its `--help` before changing infrastructure.
+
+## Trust boundaries
+
+AWS, Firebase, AI Gateway, Stripe, and database clients are configured by the consuming application. Do not place domain-specific credentials, schemas, or authorization policy inside the shared kit. Use `createRolePolicy()` only for storage-agnostic role and relation mapping; the application still owns its roles and permissions.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rdlabo/workers-hono-kit",
-  "version": "0.10.6",
+  "version": "0.11.1-beta.pr46.sha8ccc8da384f0",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -11,12 +11,12 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/rdlabo-team/workers-hono-kit.git"
+    "url": "git+https://github.com/rdlabo-dev/workers-hono-kit.git"
   },
   "bugs": {
-    "url": "https://github.com/rdlabo-team/workers-hono-kit/issues"
+    "url": "https://github.com/rdlabo-dev/workers-hono-kit/issues"
   },
-  "homepage": "https://github.com/rdlabo-team/workers-hono-kit#readme",
+  "homepage": "https://docs.rdlabo.dev/projects/workers-hono-kit",
   "keywords": [
     "hono",
     "cloudflare-workers",
@@ -43,6 +43,7 @@
   "files": [
     "dist",
     "scripts",
+    "docs",
     "!src/**/*.spec.ts"
   ],
   "bin": {

package/dist/db/decimal.d.ts

@@ -1,35 +0,0 @@
-/**
- * Drizzle `customType` params for a MySQL `DECIMAL` column.
- *
- * @remarks
- * - **Reads (SELECT)**: `fromDriver` unifies the driver value (`number` / `string` / `null`) to a JS
- *   `number | null`. Combined with the connection's `decimalNumbers: true`
- *   ({@link hyperdriveConnectionOptions} default), it aligns values to numbers even on the Drizzle
- *   builder path when strings like `"0"` / `"100.00"` slip in, without dropping `0`.
- * - **Writes (INSERT/UPDATE)**: `toDriver` binds the number to mysql2 as-is (no `String()` conversion).
- * - Raw-SQL `db.read` relies on the connection's `decimalNumbers: true`; the column's `fromDriver` is
- *   for the Drizzle `select` path.
- */
-export interface DecimalNumberConfig {
-    precision: number;
-    scale: number;
-}
-/**
- * Normalize a DECIMAL value coming from mysql2 / Drizzle to a JS `number | null`.
- * `0` is preserved as-is so it is not dropped as falsy.
- *
- * @param value - the raw driver value (`number` / `string` / `bigint` / nullish).
- * @returns the coerced finite number, or `null` when it cannot be resolved.
- */
-export declare function coerceDecimalNumber(value: unknown): number | null;
-/**
- * Params for a `customType`. For advanced use; the {@link decimalNumber} column helper is usually enough.
- *
- * @param config - the DECIMAL `precision` / `scale`.
- * @returns the `customType` params (`dataType` / `fromDriver` / `toDriver`).
- */
-export declare const decimalNumberParams: (config: DecimalNumberConfig) => {
-    dataType: () => string;
-    fromDriver: (value: unknown) => number | null;
-    toDriver: (value: number | string | null) => number | string | null;
-};

package/dist/db/decimal.js

@@ -1,58 +0,0 @@
-/**
- * Drizzle `customType` params for a MySQL `DECIMAL` column.
- *
- * @remarks
- * - **Reads (SELECT)**: `fromDriver` unifies the driver value (`number` / `string` / `null`) to a JS
- *   `number | null`. Combined with the connection's `decimalNumbers: true`
- *   ({@link hyperdriveConnectionOptions} default), it aligns values to numbers even on the Drizzle
- *   builder path when strings like `"0"` / `"100.00"` slip in, without dropping `0`.
- * - **Writes (INSERT/UPDATE)**: `toDriver` binds the number to mysql2 as-is (no `String()` conversion).
- * - Raw-SQL `db.read` relies on the connection's `decimalNumbers: true`; the column's `fromDriver` is
- *   for the Drizzle `select` path.
- */
-/**
- * Normalize a DECIMAL value coming from mysql2 / Drizzle to a JS `number | null`.
- * `0` is preserved as-is so it is not dropped as falsy.
- *
- * @param value - the raw driver value (`number` / `string` / `bigint` / nullish).
- * @returns the coerced finite number, or `null` when it cannot be resolved.
- */
-export function coerceDecimalNumber(value) {
-    if (value === null || value === undefined) {
-        return null;
-    }
-    if (typeof value === 'number') {
-        return Number.isFinite(value) ? value : null;
-    }
-    if (typeof value === 'string') {
-        const trimmed = value.trim();
-        if (trimmed === '') {
-            return null;
-        }
-        const n = Number(trimmed);
-        return Number.isFinite(n) ? n : null;
-    }
-    if (typeof value === 'bigint') {
-        return Number(value);
-    }
-    return null;
-}
-/**
- * Params for a `customType`. For advanced use; the {@link decimalNumber} column helper is usually enough.
- *
- * @param config - the DECIMAL `precision` / `scale`.
- * @returns the `customType` params (`dataType` / `fromDriver` / `toDriver`).
- */
-export const decimalNumberParams = (config) => ({
-    dataType: () => `decimal(${config.precision},${config.scale})`,
-    fromDriver: (value) => coerceDecimalNumber(value),
-    toDriver: (value) => {
-        if (value === null) {
-            return null;
-        }
-        if (typeof value === 'number') {
-            return value;
-        }
-        return coerceDecimalNumber(value);
-    },
-});