@rdlabo/workers-hono-kit 0.9.6 → 0.9.7

package/README.md

@@ -2,10 +2,10 @@
 
 Infrastructure toolkit for building APIs on [Hono](https://hono.dev) + [Cloudflare Workers](https://workers.cloudflare.com).
 
-It provides the building blocks a NestJS-style API needs but that don't run on `workerd` (no Node.js AWS SDK, no `firebase-admin`), plus middleware for common HTTP response concerns:
+It provides Workers-oriented building blocks for a NestJS-style API, plus middleware for common HTTP response concerns:
 
 - **Firebase ID-token verification** on Workers via [`jose`](https://github.com/panva/jose) (RS256 against Google's securetoken JWKS), with optional Identity Toolkit REST for `getUser` / `deleteUser`.
-- **AWS Secrets Manager / STS AssumeRole / CloudFront signed URLs** via SigV4-signed `fetch` ([`aws4fetch`](https://github.com/mhart/aws4fetch)) or Web Crypto — no AWS SDK.
+- **AWS Secrets Manager / STS AssumeRole / CloudFront signed URLs** via focused SigV4-signed `fetch` ([`aws4fetch`](https://github.com/mhart/aws4fetch)) or Web Crypto, avoiding a broad SDK dependency when only a few AWS APIs are needed.
 - **Middleware**: `finalizeResponse` (weak ETag via `hono/etag`), `validate` (NestJS `ValidationPipe`-shaped 400), and zod number-coercion helpers.
 - **Standard API errors**: `createHttpErrorHandler` / `notFoundHandler` / `HttpStatus`.
 - **Deadlock retry** (`ER_LOCK_DEADLOCK` exponential backoff) and an optional **MySQL data layer** (`@rdlabo/workers-hono-kit/db`) for Hyperdrive + Drizzle.
@@ -106,7 +106,7 @@ npm install ai ai-gateway-provider    # createAiGatewayProvider
 | `sendInChunks(queue, messages, options?)` / `QueueLike` / `QueueSendMessage` | Send queue messages in bounded chunks to stay under the Workers subrequest cap per invocation. `options.chunkSize` sets the per-batch size (defaults to and is capped at 100). |
 | `processBatch(batch, handler, options?)` / `MessageBatchLike` / `QueueMessageLike` / `ProcessBatchOptions` / `ProcessBatchResult` | Process a queue batch with bounded concurrency (consumer-side counterpart to `sendInChunks`). |
 | `createQueueErrorHandler(options)` / `CreateQueueErrorHandlerOptions` | Factory for `processBatch`'s `onError`: logs every failure; optional Sentry capture with queue/message context; optional `maxRetries` gate (report only on final attempt). |
-| `ExecutionContextLike` | Minimal `waitUntil`-only Workers execution context shape (for `withMysqlConnections` in worker entry modules without importing `./db`). |
+| `ExecutionContextLike` | Minimal `waitUntil`-only Workers execution context shape used by lifecycle-compatible APIs and deferred work helpers. |
 
 ### Data layer — `@rdlabo/workers-hono-kit/db`
 
@@ -114,12 +114,12 @@ Requires the `drizzle-orm` and `mysql2` peers. Reads run against a replica via r
 
 | Export | Description |
 | --- | --- |
-| `createHyperdriveDatabase(options)` | `DisposableDatabase` that lazily opens primary/replica connections from Hyperdrive bindings per request; `dispose()` closes them. |
+| `createHyperdriveDatabase(options)` | `DisposableDatabase` that lazily opens primary/replica connections from Hyperdrive bindings per request. Workers cleans them up at invocation end; the legacy `dispose()` is a no-op. |
 | `createMysqlDatabase(options)` | Assemble a `Database` from an already-connected Drizzle ORM + replica `QueryRunner`. |
 | `databaseFrom(orm, replica)` | Build a `Database` from an existing Drizzle instance + replica handle. |
 | `Database` / `DisposableDatabase` / `QueryRunner` / `TxOf` | The `read` / `write` / `transaction` API and its supporting types. |
-| `hyperdriveConnectionOptions(hyperdrive, overrides?)` / `HyperdriveLike` / `ExecutionContextLike` | Build mysql2 `createConnection` options from a Hyperdrive binding (`disableEval`, `decimalNumbers`, `timezone '+09:00'` by default). `ExecutionContextLike` is the same type as the root export, re-exported here so `withMysqlConnections` callers don't need the root import. |
-| `withMysqlConnections(...)` | Open primary/replica connections, run a function, close them in `finally` (via `ctx.waitUntil`). |
+| `hyperdriveConnectionOptions(hyperdrive, overrides?)` / `HyperdriveLike` / `ExecutionContextLike` | Build mysql2 `createConnection` options from a Hyperdrive binding (`disableEval`, `decimalNumbers`, `timezone '+09:00'` by default). `timezone` controls mysql2's JavaScript `Date` conversion; it does not change the MySQL session timezone. |
+| `withMysqlConnections(...)` | Open primary/replica connections in parallel and run a function. Workers cleans them up at invocation end. |
 | `retryWhenDeadlock(fn, retries?, delay?)` | Same deadlock-retry helper as the root export. |
 | `insertIdOf` / `affectedRowsOf` / `insertedIdsOf` / `DzWriteResult` | Extract `insertId` / `affectedRows` (and derive contiguous bulk-insert ids) from a mysql2 write result. |
 | `toJstDate` / `jstTimestampParams` / `jstDatetimeParams` / `jstDateParams` | JST date/time normalization params (advanced use). |
@@ -588,12 +588,8 @@ const db = createHyperdriveDatabase({
   createOrm: (conn) => drizzle(conn, { ...DRIZZLE_ORM_OPTIONS, schema }),
 });
 
-try {
-  const rows = await db.read('SELECT * FROM users WHERE id = ?', [id]); // replica, raw SQL
-  await db.write((dz) => dz.insert(users).values({ name })); // primary, deadlock-retried
-} finally {
-  await db.dispose();
-}
+const rows = await db.read('SELECT * FROM users WHERE id = ?', [id]); // replica, raw SQL
+await db.write((dz) => dz.insert(users).values({ name })); // primary, deadlock-retried
 ```
 
 ### KV cache

package/dist/aws/secrets-manager.d.ts

@@ -2,7 +2,7 @@
  * AWS credentials used to sign Secrets Manager requests.
  *
  * @remarks
- * Cloudflare Workers have neither the AWS SDK nor IAM role credentials, so static AWS keys are supplied
+ * Cloudflare Workers do not provide the AWS default credential chain, so AWS credentials are supplied
  * as Workers secrets and used to produce a SigV4 signature.
  */
 export interface AwsSecretsOptions {
@@ -19,7 +19,7 @@ export interface AwsSecretsOptions {
  * Fetch and parse a secret from AWS Secrets Manager, caching the result per isolate.
  *
  * Issues a `GetSecretValue` call to Secrets Manager via a SigV4-signed `fetch` (using aws4fetch), with no
- * AWS SDK involved. The parsed `SecretString` is cached per isolate keyed by region, access key ID, and
+ * broad AWS SDK dependency involved. The parsed `SecretString` is cached per isolate keyed by region, access key ID, and
  * secret ID; concurrent first-time callers share one in-flight request, and a rejected fetch clears the
  * cache entry so the next call retries.
  *

package/dist/aws/secrets-manager.js

@@ -15,7 +15,7 @@ let cache = null;
  * Fetch and parse a secret from AWS Secrets Manager, caching the result per isolate.
  *
  * Issues a `GetSecretValue` call to Secrets Manager via a SigV4-signed `fetch` (using aws4fetch), with no
- * AWS SDK involved. The parsed `SecretString` is cached per isolate keyed by region, access key ID, and
+ * broad AWS SDK dependency involved. The parsed `SecretString` is cached per isolate keyed by region, access key ID, and
  * secret ID; concurrent first-time callers share one in-flight request, and a rejected fetch clears the
  * cache entry so the next call retries.
  *

package/dist/db/connection.d.ts

@@ -31,11 +31,9 @@ export interface HyperdriveLike {
  * - `decimalNumbers: true` — return `DECIMAL`/`NEWDECIMAL` columns as JS `number` rather than
  *   strings, so raw-SQL reads and Drizzle's inferred types align on a single numeric domain type.
  *   This assumes no column's precision exceeds the JS safe-integer range.
- * - `timezone: '+09:00'` — set the driver's session timezone to JST. mysql2 defaults to `'local'`,
- *   which is UTC in the Workers runtime; pinning the driver timezone keeps `datetime`/`timestamp`
- *   round-trips independent of the database's session timezone (only the internally stored UTC
- *   value differs, which is invisible to the application). Non-JST deployments can override this
- *   via `extra: { timezone: '...' }`.
+ * - `timezone: '+09:00'` — interpret and serialize JavaScript `Date` values as JST. This is a
+ *   mysql2 client-side conversion option; it does not issue `SET time_zone` or change the MySQL
+ *   session timezone. Non-JST deployments can override it via `extra: { timezone: '...' }`.
  *
  * @param hyperdrive - the Hyperdrive binding to derive connection fields from.
  * @param extra - additional mysql2 options merged last, overriding the defaults above.
@@ -43,14 +41,15 @@ export interface HyperdriveLike {
  */
 export declare function hyperdriveConnectionOptions(hyperdrive: HyperdriveLike, extra?: Record<string, unknown>): Record<string, unknown>;
 /**
- * Open primary and replica connections, run `fn` with them, and close both afterwards.
+ * Open primary and replica connections in parallel and run `fn` with them.
  *
- * The connections are always closed in a `finally` block; closing is scheduled through
- * `ctx.waitUntil` so it can complete after the response has been returned, without blocking it.
+ * Cloudflare Workers automatically cleans up connections created during an invocation. Calling
+ * `Connection.end()` is unnecessary and can race work registered with `waitUntil`. The `ctx`
+ * parameter remains for API compatibility and is intentionally not used for connection teardown.
  *
  * @typeParam T - resolved value produced by `fn`.
  * @param hyperdrives - the primary and replica Hyperdrive bindings to connect to.
- * @param ctx - the execution context whose `waitUntil` defers connection teardown past the response.
+ * @param ctx - the request execution context, retained for API compatibility.
  * @param fn - callback invoked with the open `primary` and `replica` connections.
  * @param connectionOptions - extra mysql2 options forwarded to {@link hyperdriveConnectionOptions}.
  * @returns the value resolved by `fn`.

package/dist/db/connection.js

@@ -11,11 +11,9 @@ import { MYSQL_TIMEZONE } from './jst.js';
  * - `decimalNumbers: true` — return `DECIMAL`/`NEWDECIMAL` columns as JS `number` rather than
  *   strings, so raw-SQL reads and Drizzle's inferred types align on a single numeric domain type.
  *   This assumes no column's precision exceeds the JS safe-integer range.
- * - `timezone: '+09:00'` — set the driver's session timezone to JST. mysql2 defaults to `'local'`,
- *   which is UTC in the Workers runtime; pinning the driver timezone keeps `datetime`/`timestamp`
- *   round-trips independent of the database's session timezone (only the internally stored UTC
- *   value differs, which is invisible to the application). Non-JST deployments can override this
- *   via `extra: { timezone: '...' }`.
+ * - `timezone: '+09:00'` — interpret and serialize JavaScript `Date` values as JST. This is a
+ *   mysql2 client-side conversion option; it does not issue `SET time_zone` or change the MySQL
+ *   session timezone. Non-JST deployments can override it via `extra: { timezone: '...' }`.
  *
  * @param hyperdrive - the Hyperdrive binding to derive connection fields from.
  * @param extra - additional mysql2 options merged last, overriding the defaults above.
@@ -35,14 +33,15 @@ export function hyperdriveConnectionOptions(hyperdrive, extra) {
     };
 }
 /**
- * Open primary and replica connections, run `fn` with them, and close both afterwards.
+ * Open primary and replica connections in parallel and run `fn` with them.
  *
- * The connections are always closed in a `finally` block; closing is scheduled through
- * `ctx.waitUntil` so it can complete after the response has been returned, without blocking it.
+ * Cloudflare Workers automatically cleans up connections created during an invocation. Calling
+ * `Connection.end()` is unnecessary and can race work registered with `waitUntil`. The `ctx`
+ * parameter remains for API compatibility and is intentionally not used for connection teardown.
  *
  * @typeParam T - resolved value produced by `fn`.
  * @param hyperdrives - the primary and replica Hyperdrive bindings to connect to.
- * @param ctx - the execution context whose `waitUntil` defers connection teardown past the response.
+ * @param ctx - the request execution context, retained for API compatibility.
  * @param fn - callback invoked with the open `primary` and `replica` connections.
  * @param connectionOptions - extra mysql2 options forwarded to {@link hyperdriveConnectionOptions}.
  * @returns the value resolved by `fn`.
@@ -59,17 +58,10 @@ export function hyperdriveConnectionOptions(hyperdrive, extra) {
  * ```
  */
 export async function withMysqlConnections(hyperdrives, ctx, fn, connectionOptions) {
-    let primary;
-    let replica;
-    try {
-        primary = await createConnection(hyperdriveConnectionOptions(hyperdrives.primary, connectionOptions));
-        replica = await createConnection(hyperdriveConnectionOptions(hyperdrives.replica, connectionOptions));
-        return await fn({ primary, replica });
-    }
-    finally {
-        const closing = [primary, replica].filter((c) => c !== undefined).map((c) => c.end());
-        if (closing.length > 0) {
-            ctx.waitUntil(Promise.allSettled(closing));
-        }
-    }
+    void ctx;
+    const [primary, replica] = await Promise.all([
+        createConnection(hyperdriveConnectionOptions(hyperdrives.primary, connectionOptions)),
+        createConnection(hyperdriveConnectionOptions(hyperdrives.replica, connectionOptions)),
+    ]);
+    return fn({ primary, replica });
 }

package/dist/db/database.d.ts

@@ -79,19 +79,22 @@ export interface Database<TDrizzle, TTx = TxOf<TDrizzle>> {
     transaction<T>(fn: (tx: TTx) => Promise<T>): Promise<T>;
 }
 /**
- * A {@link Database} that owns its connections and must be disposed.
+ * A {@link Database} that opens its own connections.
  *
  * @remarks
- * Used by the variants that open connections internally (Hyperdrive- or Pool-backed).
+ * Used by variants that open connections internally. Lifecycle behavior depends on the backing
+ * implementation: pool-backed databases close their pool, while Hyperdrive-backed databases leave
+ * invocation-scoped connection cleanup to the Workers runtime.
  *
  * @typeParam TDrizzle - the consumer's Drizzle ORM type.
  * @typeParam TTx - the transaction-handle type, inferred from `TDrizzle` by default.
  */
 export interface DisposableDatabase<TDrizzle, TTx = TxOf<TDrizzle>> extends Database<TDrizzle, TTx> {
     /**
-     * Close the connections opened by this database.
+     * Release resources owned by the implementation. Hyperdrive-backed databases keep this method as
+     * a compatibility no-op; pool-backed databases use it to close their pool.
      *
-     * @returns a promise that settles once both connections are closed.
+     * @returns a promise that resolves after implementation-specific cleanup.
      */
     dispose(): Promise<void>;
 }
@@ -155,13 +158,15 @@ export interface CreateHyperdriveDatabaseOptions<TDrizzle> {
  * Create a {@link DisposableDatabase} that lazily opens its connections from Hyperdrive bindings.
  *
  * @remarks
- * Construct one per request and call `dispose()` after the response to close the connections.
- * Connections and the ORM are created on first use and reused for the lifetime of the instance; the
- * read/write/transaction surface is identical to {@link createMysqlDatabase}.
+ * Construct one per request. Connections and the ORM are created on first use and reused for the
+ * lifetime of the instance; the read/write/transaction surface is identical to
+ * {@link createMysqlDatabase}. Workers automatically cleans up connections at the end of the
+ * invocation, so callers do not need to close them manually.
  *
  * @typeParam TDrizzle - the consumer's Drizzle ORM type.
  * @param options - the primary/replica Hyperdrive bindings, the ORM factory, and connection options.
- * @returns a {@link DisposableDatabase} that must be disposed when done.
+ * @returns a {@link DisposableDatabase} whose compatibility `dispose()` method is a no-op; Workers
+ *   cleans up its invocation-scoped connections automatically.
  * @example
  * ```ts
  * const db = createHyperdriveDatabase({
@@ -169,11 +174,7 @@ export interface CreateHyperdriveDatabaseOptions<TDrizzle> {
  *   replicaHyperdrive: env.REPLICA,
  *   createOrm: (primary) => drizzle(primary, { schema, ...DRIZZLE_ORM_OPTIONS }),
  * });
- * try {
- *   await db.write((dz) => dz.insert(users).values(user));
- * } finally {
- *   await db.dispose();
- * }
+ * await db.write((dz) => dz.insert(users).values(user));
  * ```
  */
 export declare function createHyperdriveDatabase<TDrizzle>(options: CreateHyperdriveDatabaseOptions<TDrizzle>): DisposableDatabase<TDrizzle>;

package/dist/db/database.js

@@ -27,13 +27,15 @@ export function createMysqlDatabase(options) {
  * Create a {@link DisposableDatabase} that lazily opens its connections from Hyperdrive bindings.
  *
  * @remarks
- * Construct one per request and call `dispose()` after the response to close the connections.
- * Connections and the ORM are created on first use and reused for the lifetime of the instance; the
- * read/write/transaction surface is identical to {@link createMysqlDatabase}.
+ * Construct one per request. Connections and the ORM are created on first use and reused for the
+ * lifetime of the instance; the read/write/transaction surface is identical to
+ * {@link createMysqlDatabase}. Workers automatically cleans up connections at the end of the
+ * invocation, so callers do not need to close them manually.
  *
  * @typeParam TDrizzle - the consumer's Drizzle ORM type.
  * @param options - the primary/replica Hyperdrive bindings, the ORM factory, and connection options.
- * @returns a {@link DisposableDatabase} that must be disposed when done.
+ * @returns a {@link DisposableDatabase} whose compatibility `dispose()` method is a no-op; Workers
+ *   cleans up its invocation-scoped connections automatically.
  * @example
  * ```ts
  * const db = createHyperdriveDatabase({
@@ -41,11 +43,7 @@ export function createMysqlDatabase(options) {
  *   replicaHyperdrive: env.REPLICA,
  *   createOrm: (primary) => drizzle(primary, { schema, ...DRIZZLE_ORM_OPTIONS }),
  * });
- * try {
- *   await db.write((dz) => dz.insert(users).values(user));
- * } finally {
- *   await db.dispose();
- * }
+ * await db.write((dz) => dz.insert(users).values(user));
  * ```
  */
 export function createHyperdriveDatabase(options) {
@@ -71,8 +69,9 @@ export function createHyperdriveDatabase(options) {
             const dz = (await ormFor());
             return retryWhenDeadlock(() => dz.transaction(fn));
         },
-        async dispose() {
-            await Promise.all([primaryConn?.then((c) => c.end()), replicaConn?.then((c) => c.end())]);
+        /** @deprecated Workers cleans up invocation-scoped connections automatically. */
+        dispose() {
+            return Promise.resolve();
         },
     };
 }

package/dist/firebase/identity-toolkit.d.ts

@@ -16,8 +16,8 @@ export interface ServiceAccount {
  * Minimal Google Identity Toolkit REST client for the user-management operations that token
  * verification does not cover: `accounts:lookup` (getUser) and `accounts:delete` (deleteUser).
  *
- * This replaces the parts of the `firebase-admin` Node SDK that cannot run on Cloudflare
- * Workers (workerd).
+ * This is a focused REST alternative for projects that only need a small subset of Firebase Auth
+ * administration and do not want to bundle the broader `firebase-admin` SDK.
  *
  * @remarks
  * Authentication follows the JWT-bearer flow: a JWT assertion is signed with the service

package/dist/firebase/identity-toolkit.js

@@ -11,8 +11,8 @@ const LOOKUP_CHUNK_SIZE = 100;
  * Minimal Google Identity Toolkit REST client for the user-management operations that token
  * verification does not cover: `accounts:lookup` (getUser) and `accounts:delete` (deleteUser).
  *
- * This replaces the parts of the `firebase-admin` Node SDK that cannot run on Cloudflare
- * Workers (workerd).
+ * This is a focused REST alternative for projects that only need a small subset of Firebase Auth
+ * administration and do not want to bundle the broader `firebase-admin` SDK.
  *
  * @remarks
  * Authentication follows the JWT-bearer flow: a JWT assertion is signed with the service
@@ -152,6 +152,12 @@ export class IdentityToolkit {
             body: JSON.stringify({ localId: uid }),
         });
         if (!res.ok) {
+            const body = (await res.json().catch(() => undefined));
+            // Account deletion is an idempotent operation for callers. A retry after a lost response may
+            // legitimately find that the preceding request already removed the Firebase user.
+            if (body?.error?.message === 'USER_NOT_FOUND') {
+                return;
+            }
             throw new Error(`Identity Toolkit delete failed: ${res.status}`);
         }
     }

package/dist/queue/send.d.ts

@@ -2,11 +2,13 @@
  * Producer-side helper for fanning a large list of items into a Cloudflare Queue without letting the
  * producer's own subrequest count scale linearly with the list.
  *
- * A Worker may issue at most 50 (free) / 1000 (paid) subrequests per invocation, and each
- * {@link QueueLike.send} counts as one subrequest. Enqueuing `N` items with per-item `send()` calls
- * therefore reintroduces the very unbounded fan-out that queues exist to remove. {@link sendInChunks}
- * instead groups items into batches and issues one {@link QueueLike.sendBatch} per batch, so the
- * producer spends `ceil(N / chunkSize)` subrequests regardless of how large `N` grows.
+ * Queue bindings call a Cloudflare internal service. The internal-service subrequest budget is
+ * 1,000 on Workers Free and matches the configured subrequest limit on Paid (10,000 by default,
+ * configurable up to 10 million). Each {@link QueueLike.send} counts as one subrequest. Enqueuing
+ * `N` items with per-item `send()` calls therefore reintroduces the very unbounded fan-out that
+ * queues exist to remove. {@link sendInChunks} instead groups items into batches and issues one
+ * {@link QueueLike.sendBatch} per batch, so the producer spends `ceil(N / chunkSize)` subrequests
+ * regardless of how large `N` grows.
  *
  * The heavy per-item work (external API calls, etc.) is expected to run in the queue *consumer*,
  * where each invocation processes only `max_batch_size` messages and thus enjoys its own bounded

package/dist/queue/send.js

@@ -2,11 +2,13 @@
  * Producer-side helper for fanning a large list of items into a Cloudflare Queue without letting the
  * producer's own subrequest count scale linearly with the list.
  *
- * A Worker may issue at most 50 (free) / 1000 (paid) subrequests per invocation, and each
- * {@link QueueLike.send} counts as one subrequest. Enqueuing `N` items with per-item `send()` calls
- * therefore reintroduces the very unbounded fan-out that queues exist to remove. {@link sendInChunks}
- * instead groups items into batches and issues one {@link QueueLike.sendBatch} per batch, so the
- * producer spends `ceil(N / chunkSize)` subrequests regardless of how large `N` grows.
+ * Queue bindings call a Cloudflare internal service. The internal-service subrequest budget is
+ * 1,000 on Workers Free and matches the configured subrequest limit on Paid (10,000 by default,
+ * configurable up to 10 million). Each {@link QueueLike.send} counts as one subrequest. Enqueuing
+ * `N` items with per-item `send()` calls therefore reintroduces the very unbounded fan-out that
+ * queues exist to remove. {@link sendInChunks} instead groups items into batches and issues one
+ * {@link QueueLike.sendBatch} per batch, so the producer spends `ceil(N / chunkSize)` subrequests
+ * regardless of how large `N` grows.
  *
  * The heavy per-item work (external API calls, etc.) is expected to run in the queue *consumer*,
  * where each invocation processes only `max_batch_size` messages and thus enjoys its own bounded

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rdlabo/workers-hono-kit",
-  "version": "0.9.6",
+  "version": "0.9.7",
   "private": false,
   "publishConfig": {
     "access": "public"

package/scripts/check-subrequest-fanout.mjs

@@ -2,7 +2,8 @@
 /**
  * check-subrequest-fanout — flag per-item external-call fan-outs that scale with data size.
  *
- * Cloudflare Workers cap subrequests per invocation (50 free / 1000 paid). Looping an external call
+ * Cloudflare Workers cap external subrequests per invocation (50 on Free; 10,000 by default on
+ * Paid, configurable up to 10 million). Looping an external call
  * (fetch / AI / Stripe / push / ES) once per row reintroduces an unbounded fan-out that eventually
  * exceeds the cap as the userbase/data grows. This gate greps for the concurrency-loop markers that
  * usually wrap such fan-outs and fails CI unless the site is explicitly annotated as safe.