@rdlabo/workers-hono-kit 0.10.6 → 0.11.0

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