@rdlabo/workers-hono-kit 0.10.6 → 0.11.1

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",
   "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);
-    },
-});