@rdlabo/workers-hono-kit 0.5.1 → 0.6.1

package/README.md

@@ -52,7 +52,8 @@ npm install ai ai-gateway-provider    # createAiGatewayProvider
 | --- | --- |
 | `finalizeResponse()` | Middleware that adds an Express-compatible weak `ETag` and JSON `charset=utf-8`. |
 | `validate(target, schema, options?)` | Zod validator → NestJS `ValidationPipe`-shaped `400` (`{ statusCode, message[], error }`). `options.onValidationError(err, c)` to report (e.g. Sentry). |
-| `createSentryValidate(sentry)` | Returns a `validate` variant that reports validation failures to an injected Sentry-like client (tags + context), avoiding a hard `@sentry/cloudflare` dependency. |
+| `createValidate({ sentry? })` | Bound `validate` factory. Pass `sentry` on Sentry apps; omit for console-only (review, cbs-ai). |
+| `createSentryValidate(sentry)` | **Deprecated** — use `createValidate({ sentry })`. |
 | `zNum` / `zNumWithDefault` / `zNumOptional` / `zNumNullable` | Number-coercion zod schemas (mirror class-transformer `@Transform`). |
 | `getAuthenticationSecret<T>(options, secretId)` / `AwsSecretsOptions` | Fetch a secret from AWS Secrets Manager (SigV4 `fetch`, per-isolate cache). |
 | `getCloudFrontSignedUrl(url, privateKeyPem, keyPairId, dateLessThan)` | CloudFront signed URL (canned policy, RSA-SHA1, URL-safe base64) — Web Crypto reimpl of `@aws-sdk/cloudfront-signer`, byte-identical query order. |
@@ -66,19 +67,24 @@ npm install ai ai-gateway-provider    # createAiGatewayProvider
 | `resolveAppEnv(env)` / `isProductionEnv(env)` / `AppEnv` | Resolve `'development'` / `'production'` from `env.APP_ENV` (defaults to `'production'` for safety). |
 | `HttpStatus` | HTTP status enum identical to NestJS `@nestjs/common`. |
 | `createNestErrorHandler(options?)` / `NestErrorHandlerOptions` | `app.onError()` handler that maps a thrown `HTTPException` to the NestJS exception-filter body (`{ statusCode, message, error? }`; `401` omits `error`). Configurable field order, reason phrases, error predicate, and unhandled-error report hook. Unhandled errors log via `console.error` (mysql2 errors include `sqlMessage` / `errno` when detectable). |
-| `createQueryFailedNestErrorHandler(options)` / `QueryFailedClassifier` / `ClassifiedDbError` | Compose a NestJS `QueryFailedExceptionFilter` analog **before** `createNestErrorHandler`: consumer supplies `classify(err)` (parity-critical messages stay in the app); classified DB errors log (`warn` for 400, `error` for 500) and trigger `onUnhandledError` on 500 only. |
-| `findMysqlDriverError(err)` / `logMysqlDriverError(err, statusCode)` / `reportClassifiedDbError(...)` | Low-level mysql2 driver-error detection (follows `err.cause`), structured logging, and classify-path reporting helpers. |
+| `createAppErrorHandler(options?)` / `CreateAppErrorHandlerOptions` | Standard `app.onError`: {@link createQueryFailedNestErrorHandler} + default {@link classifyGenericMysqlDriverError} + optional `sentry` (Sentry apps), `getReportError` / `reportError` (tests / container), or neither (no external reporting). |
+| `createQueryFailedNestErrorHandler(options)` / `QueryFailedClassifier` / `ClassifiedDbError` | Lower-level compose when you need full control over `classify` + `onUnhandledError` without defaults. |
+| `classifyGenericMysqlDriverError(err)` | Default classifier for apps without Nest filter parity: any mysql2 driver error → `{ statusCode: 500, message: 'Internal server error' }`; non-DB errors → `null`. |
+| `findMysqlDriverError(err)` / `logMysqlDriverError(err, statusCode)` | Low-level mysql2 driver-error detection (follows `err.cause`) and structured logging. For custom classifiers (e.g. odss parity). |
 | `nestNotFoundHandler(c)` | `app.notFound()` handler with the Express/Nest default `{ message: 'Cannot METHOD path', error, statusCode }` 404 body. |
 | `normalizeTrailingSlash(request)` | Strip trailing slash(es) from the request URL before routing (Express/Nest parity). Does **not** 301-redirect — preserves POST/PUT/DELETE bodies. |
 | `NEST_REASON_PHRASES` | `{ 400, 401, 403, 404 }` → NestJS reason phrases. |
 | `createAuthMiddleware(options)` / `AuthMiddlewareOptions` | Factory for a Firebase-token auth middleware: reads the token header, verifies, resolves the DB user id, and stashes the result on the context. Omit `resolveUserId` for a token-only (login) guard. |
 | `perfLog(options?)` / `PerfLogOptions` / `AnalyticsEngineDatasetLike` | Middleware that records one per-request latency data point (`t_app`, colo, cold/warm, route, status) and emits it to **Workers Logs** (`console.log`) and/or **Workers Analytics Engine** (`writeDataPoint`). Lets you measure low-traffic Workers without a live `wrangler tail`. |
 | `ErrorReporter` / `ErrorReportContext` | Types for a `reportError`-style unhandled-error reporter (e.g. wired to Sentry), paired with `createNestErrorHandler`'s `onUnhandledError`. |
+| `createSentryErrorReporter(sentry)` / `SentryExceptionReporterLike` | Build an `ErrorReporter` that forwards to Sentry with an optional `request_id` tag (no hard `@sentry/cloudflare` dependency). |
+| `DeferExecutor` / `defaultDefer` / `createWaitUntilDefer(ctx)` | Fire-and-forget executor for Workers: `defaultDefer` swallows rejections (tests); `createWaitUntilDefer` registers work via `ctx.waitUntil`. |
 | `createAiGatewayProvider(config)` / `AiGatewayConfig` / `AiGatewayProvider` | Route `@ai-sdk` models through the Cloudflare AI Gateway, via either a Workers `AI` binding or REST credentials (`accountId` / `gateway` / `token`). |
 | `KVCache` / `KVNamespace` / `KVCacheOptions` | Workers-KV cache-aside helper (key `appName+version+table_type_column`, sha256 for string ids, TTL clamped ≥60s). Set `appName` / `version` per application. |
 | `createStripeClient(secret, opts?)` / `verifyStripeWebhook(...)` / `CreateStripeClientOptions` | Workers-native Stripe client (fetch transport) + async webhook verification (SubtleCrypto). `apiVersion` optional (pin to a fixed Stripe API version). |
 | `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`). |
 
 ### Data layer — `@rdlabo/workers-hono-kit/db`
@@ -284,40 +290,71 @@ body, and `nestNotFoundHandler` gives the Express/Nest default 404. The defaults
 NestJS canonical shape (`{ statusCode, message, error? }`, `401` omits `error`); the options
 let you reproduce any byte-for-byte variation an existing API expects.
 
+#### App entry (fleet standard)
+
+Use a **singleton** Hono app and inject the request-scoped container in middleware — do **not**
+call `createApp(container).fetch(...)` on every request (rebuilds the route graph each time).
+
 ```ts
-import { createNestErrorHandler, nestNotFoundHandler } from '@rdlabo/workers-hono-kit';
+// worker.ts — once per isolate
+const app = createApp();
+export default Sentry.withSentry(/* … */, {
+  fetch: (req, env, ctx) => app.fetch(req, env, ctx),
+});
 
-app.notFound(nestNotFoundHandler);
-app.onError(createNestErrorHandler());
+// app.ts — fleet-standard onError (Sentry optional)
+import * as Sentry from '@sentry/cloudflare';
+import { createAppErrorHandler } from '@rdlabo/workers-hono-kit';
 
-// Application-specific parity deltas:
 app.onError(
-  createNestErrorHandler({
-    fieldOrder: 'message-first', // emit { message, error, statusCode } instead of statusCode-first
-    onUnhandledError: (err, c) => container.reportError?.(err, { requestId: c.get('requestId') }),
-    isHttpError: (e): e is HttpError => e instanceof HttpError, // a custom error class with a `.body` escape hatch
+  createAppErrorHandler({
+    sentry: Sentry, // omit on repos without Sentry (airlec, review, cbs-ai)
+    getReportError: (c) => c.get('container')?.reportError, // tests + scheduled paths
   }),
 );
+
+// odss-mobile: add classify: classifyQueryFailed (repo parity)
+// winecode: sentry + isHttpError / reasonPhrases in errors.ts (no container middleware)
+// foodlabel: sentry + reportError: container.reportError (per-request container closure)
 ```
 
-**Important:** `Sentry.withSentry` does **not** capture errors handled by `app.onError`. Wire
-`onUnhandledError` → `Sentry.captureException` explicitly (mirrors Nest `SentryGlobalFilter`).
+Reference: `winecode/hono` (singleton + container middleware). Legacy repos still using
+per-request `createApp(container)` should migrate to this shape where possible.
 
-Repos with a Nest `QueryFailedExceptionFilter` (e.g. odss-mobile) should use
-`createQueryFailedNestErrorHandler` so classified DB errors still log and report to Sentry:
+**Isolate-scoped memo + container runtime** (shared across the fleet):
 
 ```ts
-import { createQueryFailedNestErrorHandler } from '@rdlabo/workers-hono-kit';
+import { createContainerRuntime, createIsolateMemo } from '@rdlabo/workers-hono-kit';
 
-app.onError(
-  createQueryFailedNestErrorHandler({
-    fieldOrder: 'message-first',
-    classify: classifyQueryFailed, // app-local parity (Japanese messages, errno rules)
-    onUnhandledError: (err, c) => container.reportError?.(err, { requestId: c.get('requestId') }),
-  }),
-);
+// Secrets / env: cache successes per isolate; rejections are NOT cached (retry on next request).
+const resolveSecrets = createIsolateMemo(async (env: Env) => { /* SM or env vars */ });
+
+const { middleware: containerMiddleware, withContainer } = createContainerRuntime<Env, Container>({
+  hyperdrives: (env) => ({ primary: env.HYPERDRIVE_PRIMARY, replica: env.HYPERDRIVE_REPLICA }),
+  createContainer: async ({ env, executionCtx, primary, replica }) => {
+    const secret = await resolveSecrets(env);
+    return buildContainer({ /* db from primary/replica, secret, … */ });
+  },
+});
+```
+
+Use `withContainer` from `scheduled` / `queue` handlers; use `containerMiddleware` in `createApp`.
+
+```ts
+import { createNestErrorHandler, nestNotFoundHandler } from '@rdlabo/workers-hono-kit';
+
+app.notFound(nestNotFoundHandler);
+
+// Prefer createAppErrorHandler (see "App entry" above). Lower-level only when needed:
+app.onError(createNestErrorHandler());
 ```
 
+**Important:** `Sentry.withSentry` does **not** capture errors handled by `app.onError`. Pass `sentry`
+to `createAppErrorHandler` (or wire `getReportError` / `reportError` for tests and scheduled paths).
+
+Repos with a Nest `QueryFailedExceptionFilter` parity layer (e.g. odss-mobile) pass `classify` to
+`createAppErrorHandler` — do not call `createQueryFailedNestErrorHandler` directly unless you need full control.
+
 ### Auth middleware
 
 Encodes the shared skeleton (read token header → verify → `getAppInfo` → resolve user id →
@@ -364,7 +401,8 @@ import { perfLog } from '@rdlabo/workers-hono-kit';
 //    dataset binding) and `PERF_LOG === '1'` (Workers Logs) off `c.env`.
 app.use('*', perfLog());
 
-// B) app built without Hono env (`createApp(container).fetch(req)`): pass bindings explicitly.
+// B) bindings not on Hono env (legacy per-request createApp): pass explicitly — prefer fleet
+//    standard singleton app + container middleware so env is always on `c.env`.
 app.use('*', perfLog({ console: env.PERF_LOG === '1', dataset: env.PERF }));
 ```
 
@@ -386,7 +424,7 @@ GROUP BY path, colo ORDER BY p90 DESC
 ```
 
 > **Scope of `t_app`**: it covers everything *inside* the app; work done in `fetch` *before* the app
-> (e.g. secrets fetch / DB connect in `createApp(container)` vs. building the container in `fetch`) is
+> (e.g. secrets fetch / DB connect in container middleware vs. building the container in `worker.fetch`) is
 > not comparable across differently-wired apps. Instrument the `fetch` seam if you need a secrets/connect
 > cold breakdown. On production Workers `Date.now()` only advances at I/O boundaries, so `t_app` ≈ I/O
 > wait, not CPU time.

package/dist/container/isolate-memo.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Isolate-scoped async memoization for container bootstrap (secrets, env resolution, etc.).
+ *
+ * Successful results are reused across requests in the same isolate. Rejected initializations are
+ * **not** cached so a transient failure (e.g. Secrets Manager blip) can be retried on the next call.
+ *
+ * @remarks
+ * The memo is not keyed by argument: the loader runs once per isolate using the arguments from the
+ * first successful scheduling attempt (same semantics as hand-rolled `let promise` in Workers apps).
+ *
+ * @packageDocumentation
+ */
+/** Callable memo with an explicit reset for tests and isolate teardown. */
+export interface IsolateMemo<T, TArg> {
+    (arg: TArg): Promise<T>;
+    reset(): void;
+}
+/**
+ * Create an isolate-scoped memoized async resolver.
+ *
+ * @param loader - async factory invoked on the first call (and again after a rejection / {@link reset}).
+ * @returns a function that returns the cached promise, plus {@link IsolateMemo.reset}.
+ * @example
+ * ```ts
+ * const resolveSecrets = createIsolateMemo(async (env: Env) => {
+ *   const secret = await getAuthenticationSecret(awsOpts(env));
+ *   return { firebaseSaJson: secret.firebaseProduction };
+ * });
+ *
+ * // first request populates the cache; SM failure is not cached:
+ * await resolveSecrets(env).catch(() => undefined);
+ * await resolveSecrets(env); // retries SM
+ * ```
+ */
+export declare function createIsolateMemo<T, TArg>(loader: (arg: TArg) => Promise<T>): IsolateMemo<T, TArg>;

package/dist/container/isolate-memo.js

@@ -0,0 +1,45 @@
+/**
+ * Isolate-scoped async memoization for container bootstrap (secrets, env resolution, etc.).
+ *
+ * Successful results are reused across requests in the same isolate. Rejected initializations are
+ * **not** cached so a transient failure (e.g. Secrets Manager blip) can be retried on the next call.
+ *
+ * @remarks
+ * The memo is not keyed by argument: the loader runs once per isolate using the arguments from the
+ * first successful scheduling attempt (same semantics as hand-rolled `let promise` in Workers apps).
+ *
+ * @packageDocumentation
+ */
+/**
+ * Create an isolate-scoped memoized async resolver.
+ *
+ * @param loader - async factory invoked on the first call (and again after a rejection / {@link reset}).
+ * @returns a function that returns the cached promise, plus {@link IsolateMemo.reset}.
+ * @example
+ * ```ts
+ * const resolveSecrets = createIsolateMemo(async (env: Env) => {
+ *   const secret = await getAuthenticationSecret(awsOpts(env));
+ *   return { firebaseSaJson: secret.firebaseProduction };
+ * });
+ *
+ * // first request populates the cache; SM failure is not cached:
+ * await resolveSecrets(env).catch(() => undefined);
+ * await resolveSecrets(env); // retries SM
+ * ```
+ */
+export function createIsolateMemo(loader) {
+    let cached;
+    const resolve = (arg) => {
+        if (!cached) {
+            cached = loader(arg).catch((error) => {
+                cached = undefined;
+                throw error;
+            });
+        }
+        return cached;
+    };
+    resolve.reset = () => {
+        cached = undefined;
+    };
+    return resolve;
+}

package/dist/container/middleware.d.ts

@@ -0,0 +1,45 @@
+import type { Env, MiddlewareHandler } from 'hono';
+import type { Connection } from 'mysql2/promise';
+import type { HyperdriveLike } from '../db/connection.js';
+import type { ExecutionContextLike } from '../http/execution-context.js';
+/** Inputs available while building a per-request application container. */
+export interface ContainerBuildContext<TEnv extends Env['Bindings']> {
+    env: TEnv;
+    executionCtx: ExecutionContextLike;
+    primary: Connection;
+    replica: Connection;
+}
+/** Options for {@link createContainerRuntime}. */
+export interface ContainerRuntimeOptions<TEnv extends Env['Bindings'], TContainer> {
+    /** Resolve Hyperdrive bindings from Worker env. */
+    hyperdrives: (env: TEnv) => {
+        primary: HyperdriveLike;
+        replica: HyperdriveLike;
+    };
+    /** Forwarded to {@link withMysqlConnections} (e.g. `{ dateStrings: true }`). */
+    connectionOptions?: Record<string, unknown>;
+    /** Build the request-scoped container after primary/replica connections are open. */
+    createContainer: (ctx: ContainerBuildContext<TEnv>) => TContainer | Promise<TContainer>;
+}
+/** Pair returned by {@link createContainerRuntime}. */
+export interface ContainerRuntime<TEnv extends Env['Bindings'], TContainer> {
+    /** Hono middleware: `c.set('container', …)` then `next()`. Honors test overrides. */
+    middleware: (overrides?: {
+        container?: TContainer;
+    }) => MiddlewareHandler<{
+        Bindings: TEnv;
+        Variables: {
+            container: TContainer;
+        };
+    }>;
+    /** Shared entry for `scheduled` / `queue` handlers (same connection lifecycle as middleware). */
+    withContainer: <T>(env: TEnv, executionCtx: ExecutionContextLike, fn: (container: TContainer) => Promise<T>) => Promise<T>;
+}
+/**
+ * Standard singleton-app container wiring: per-request Hyperdrive connections + `c.set('container')`.
+ *
+ * @remarks
+ * Isolate-scoped memoization (secrets, env) stays in the app via {@link createIsolateMemo} inside
+ * `createContainer` or a helper it calls — this factory only owns the per-request DB lifecycle.
+ */
+export declare function createContainerRuntime<TEnv extends Env['Bindings'], TContainer>(options: ContainerRuntimeOptions<TEnv, TContainer>): ContainerRuntime<TEnv, TContainer>;

package/dist/container/middleware.js

@@ -0,0 +1,26 @@
+import { withMysqlConnections } from '../db/connection.js';
+/**
+ * Standard singleton-app container wiring: per-request Hyperdrive connections + `c.set('container')`.
+ *
+ * @remarks
+ * Isolate-scoped memoization (secrets, env) stays in the app via {@link createIsolateMemo} inside
+ * `createContainer` or a helper it calls — this factory only owns the per-request DB lifecycle.
+ */
+export function createContainerRuntime(options) {
+    const withContainer = async (env, executionCtx, fn) => withMysqlConnections(options.hyperdrives(env), executionCtx, async ({ primary, replica }) => {
+        const container = await options.createContainer({ env, executionCtx, primary, replica });
+        return fn(container);
+    }, options.connectionOptions);
+    const middleware = (overrides) => (async (c, next) => {
+        if (overrides?.container) {
+            c.set('container', overrides.container);
+            await next();
+            return;
+        }
+        await withContainer(c.env, c.executionCtx, async (container) => {
+            c.set('container', container);
+            await next();
+        });
+    });
+    return { middleware, withContainer };
+}

package/dist/http/app-error-handler.d.ts

@@ -0,0 +1,28 @@
+import type { Context, Env } from 'hono';
+import type { ErrorReporter, NestErrorHandlerOptions, SentryExceptionReporterLike } from './nest-error.js';
+import type { QueryFailedClassifier } from './query-failed-error.js';
+/**
+ * Options for {@link createAppErrorHandler}.
+ *
+ * @remarks
+ * Wires `createQueryFailedNestErrorHandler` with fleet defaults (`fieldOrder: 'message-first'`,
+ * {@link classifyGenericMysqlDriverError}) and optional error reporting.
+ * Pass `sentry` for Sentry-backed apps; omit it (or pass `undefined`) when not used.
+ * `getReportError` / `reportError` override `sentry` (tests, container injection, scheduled paths).
+ */
+export interface CreateAppErrorHandlerOptions<E extends Env = Env> extends Omit<NestErrorHandlerOptions<E>, 'onUnhandledError'> {
+    /** mysql2 driver error classifier. Defaults to {@link classifyGenericMysqlDriverError}. */
+    classify?: QueryFailedClassifier;
+    /** Optional Sentry client (`@sentry/cloudflare`). Omitted on repos without Sentry. */
+    sentry?: SentryExceptionReporterLike;
+    /** Static reporter (tests, worker closure). Takes precedence over {@link sentry}. */
+    reportError?: ErrorReporter;
+    /** Read reporter from Hono context (e.g. `c.get('container')?.reportError`). Takes precedence over {@link sentry}. */
+    getReportError?: (c: Context<E>) => ErrorReporter | undefined;
+    /** Override auto-wired reporting (rare; prefer sentry / reportError / getReportError). */
+    onUnhandledError?: (err: unknown, c: Context<E>) => void;
+}
+/**
+ * Standard `app.onError` factory: QueryFailed filter → Nest default filter, with optional error reporting.
+ */
+export declare function createAppErrorHandler<E extends Env = Env>(options?: CreateAppErrorHandlerOptions<E>): (err: Error, c: Context<E, any, {}>) => Response;

package/dist/http/app-error-handler.js

@@ -0,0 +1,21 @@
+import { createSentryErrorReporter } from './nest-error.js';
+import { classifyGenericMysqlDriverError, createQueryFailedNestErrorHandler } from './query-failed-error.js';
+/**
+ * Standard `app.onError` factory: QueryFailed filter → Nest default filter, with optional error reporting.
+ */
+export function createAppErrorHandler(options = {}) {
+    const { classify = classifyGenericMysqlDriverError, sentry, reportError, getReportError, onUnhandledError, fieldOrder = 'message-first', ...nestOptions } = options;
+    const sentryReporter = sentry ? createSentryErrorReporter(sentry) : undefined;
+    const resolvedOnUnhandled = onUnhandledError ??
+        ((err, c) => {
+            const reporter = getReportError?.(c) ?? reportError ?? sentryReporter;
+            const requestId = c.get('requestId');
+            reporter?.(err, { requestId });
+        });
+    return createQueryFailedNestErrorHandler({
+        fieldOrder,
+        ...nestOptions,
+        classify,
+        onUnhandledError: resolvedOnUnhandled,
+    });
+}

package/dist/http/defer.d.ts

@@ -0,0 +1,21 @@
+import type { ExecutionContextLike } from './execution-context.js';
+/**
+ * Fire-and-forget executor: registers a promise without awaiting it in the request path.
+ *
+ * @remarks
+ * On Cloudflare Workers, un-awaited work after the response may be killed unless it is registered
+ * via `ctx.waitUntil`. Inject a {@link createWaitUntilDefer} instance from the worker entry;
+ * use {@link defaultDefer} in tests and other contexts without an execution context.
+ */
+export type DeferExecutor = (promise: Promise<unknown>) => void;
+/**
+ * Default defer implementation (NestJS `void promise` equivalent). Swallows rejections.
+ * Used when no `ExecutionContext` is available (tests, partial scheduled paths).
+ */
+export declare const defaultDefer: DeferExecutor;
+/**
+ * Build a {@link DeferExecutor} that keeps the worker alive until `promise` settles.
+ *
+ * @param ctx - Workers execution context (`waitUntil`).
+ */
+export declare function createWaitUntilDefer(ctx: ExecutionContextLike): DeferExecutor;

package/dist/http/defer.js

@@ -0,0 +1,17 @@
+/**
+ * Default defer implementation (NestJS `void promise` equivalent). Swallows rejections.
+ * Used when no `ExecutionContext` is available (tests, partial scheduled paths).
+ */
+export const defaultDefer = (promise) => {
+    void promise.catch(() => undefined);
+};
+/**
+ * Build a {@link DeferExecutor} that keeps the worker alive until `promise` settles.
+ *
+ * @param ctx - Workers execution context (`waitUntil`).
+ */
+export function createWaitUntilDefer(ctx) {
+    return (promise) => {
+        ctx.waitUntil(promise.catch(() => undefined));
+    };
+}

package/dist/http/nest-error.d.ts

@@ -27,6 +27,22 @@ export interface ErrorReportContext {
  * @param context - Optional correlation context for the failing request.
  */
 export type ErrorReporter = (error: unknown, context?: ErrorReportContext) => void;
+/**
+ * Minimal Sentry-like client for {@link createSentryErrorReporter} and {@link createQueueErrorHandler}.
+ *
+ * @remarks
+ * Declared structurally to avoid a hard dependency on `@sentry/cloudflare`.
+ */
+export interface SentryExceptionReporterLike {
+    captureException(exception: unknown, captureContext?: {
+        tags?: Record<string, string>;
+        extra?: Record<string, unknown>;
+    }): void;
+}
+/**
+ * Build an {@link ErrorReporter} that forwards unhandled errors to Sentry with an optional `request_id` tag.
+ */
+export declare function createSentryErrorReporter(sentry: SentryExceptionReporterLike): ErrorReporter;
 /**
  * Minimal shape read from a value treated as an HTTP error: its status, message, and optional body.
  *

package/dist/http/nest-error.js

@@ -12,6 +12,14 @@ export const NEST_REASON_PHRASES = {
     403: 'Forbidden',
     404: 'Not Found',
 };
+/**
+ * Build an {@link ErrorReporter} that forwards unhandled errors to Sentry with an optional `request_id` tag.
+ */
+export function createSentryErrorReporter(sentry) {
+    return (error, context) => {
+        sentry.captureException(error, context?.requestId ? { tags: { request_id: context.requestId } } : undefined);
+    };
+}
 /**
  * Structurally detect Hono's `HTTPException` without relying on `instanceof`.
  *

package/dist/http/query-failed-error.d.ts

@@ -1,5 +1,5 @@
 import type { Context, Env } from 'hono';
-import type { ErrorReporter, NestErrorHandlerOptions } from './nest-error.js';
+import type { NestErrorHandlerOptions } from './nest-error.js';
 /** Nest QueryFailedExceptionFilter が返す `{ statusCode, message }` 形（error フィールド無し）。 */
 export interface ClassifiedDbError {
     statusCode: 400 | 500;
@@ -8,10 +8,10 @@ export interface ClassifiedDbError {
 /** mysql2 / Drizzle 由来の DB エラーを HTTP 応答用に分類する。非 DB エラーは null。 */
 export type QueryFailedClassifier = (err: unknown) => ClassifiedDbError | null;
 /**
- * 分類済み DB エラーをログし、500 のみ {@link ErrorReporter} へ通報する。
- * 400 はビジネスエラー扱い（warn ログのみ、Sentry 不要）。
+ * Default classifier for apps without a NestJS `QueryFailedExceptionFilter` parity layer.
+ * Maps any mysql2 driver error to generic 500 `{ statusCode, message: 'Internal server error' }`.
  */
-export declare function reportClassifiedDbError(err: unknown, classified: ClassifiedDbError, reportError?: ErrorReporter, requestId?: string): void;
+export declare function classifyGenericMysqlDriverError(err: unknown): ClassifiedDbError | null;
 export interface QueryFailedNestErrorHandlerOptions<E extends Env = Env> extends NestErrorHandlerOptions<E> {
     /** アプリ固有の分類（parity-critical な日本語メッセージ等は consumer 側で定義）。 */
     classify: QueryFailedClassifier;

package/dist/http/query-failed-error.js

@@ -1,10 +1,19 @@
-import { logMysqlDriverError } from './mysql-driver-error.js';
+import { findMysqlDriverError, logMysqlDriverError } from './mysql-driver-error.js';
 import { createNestErrorHandler } from './nest-error.js';
 /**
- * 分類済み DB エラーをログし、500 のみ {@link ErrorReporter} へ通報する。
- * 400 はビジネスエラー扱い（warn ログのみ、Sentry 不要）。
+ * Default classifier for apps without a NestJS `QueryFailedExceptionFilter` parity layer.
+ * Maps any mysql2 driver error to generic 500 `{ statusCode, message: 'Internal server error' }`.
  */
-export function reportClassifiedDbError(err, classified, reportError, requestId) {
+export function classifyGenericMysqlDriverError(err) {
+    if (!findMysqlDriverError(err)) {
+        return null;
+    }
+    return { statusCode: 500, message: 'Internal server error' };
+}
+/**
+ * @internal Used by {@link createQueryFailedNestErrorHandler} only.
+ */
+function reportClassifiedDbError(err, classified, reportError, requestId) {
     logMysqlDriverError(err, classified.statusCode);
     if (classified.statusCode === 500) {
         reportError?.(err, { requestId });
@@ -27,7 +36,7 @@ export function createQueryFailedNestErrorHandler(options) {
     return (err, c) => {
         const classified = classify(err);
         if (classified) {
-            logMysqlDriverError(err, classified.statusCode);
+            reportClassifiedDbError(err, classified);
             if (classified.statusCode === 500) {
                 try {
                     onUnhandledError?.(err, c);

package/dist/index.d.ts

@@ -10,13 +10,18 @@
  * @packageDocumentation
  */
 export { finalizeResponse } from './middleware/finalize-response.js';
-export { validate, createSentryValidate } from './middleware/validation.js';
+export { validate, createValidate } from './middleware/validation.js';
+export { createSentryValidate } from './middleware/validation.js';
 export type { ValidateOptions, ValidationTarget, ZodErrorLike, SentryLike, SentryScopeLike, } from './middleware/validation.js';
 export { zNum, zNumNullable, zNumOptional, zNumWithDefault } from './middleware/zod-coerce.js';
 export { createAuthMiddleware } from './middleware/auth.js';
 export type { AuthMiddlewareOptions } from './middleware/auth.js';
 export { perfLog } from './middleware/perf-log.js';
 export type { PerfLogOptions, AnalyticsEngineDatasetLike } from './middleware/perf-log.js';
+export { createIsolateMemo } from './container/isolate-memo.js';
+export type { IsolateMemo } from './container/isolate-memo.js';
+export { createContainerRuntime } from './container/middleware.js';
+export type { ContainerBuildContext, ContainerRuntime, ContainerRuntimeOptions } from './container/middleware.js';
 export { getUserProtocol } from './http/user-protocol.js';
 export type { IUserProtocol } from './http/user-protocol.js';
 export { getAppInfo } from './http/app-info.js';
@@ -28,10 +33,16 @@ export { createNestErrorHandler, nestNotFoundHandler, NEST_REASON_PHRASES } from
 export type { NestErrorHandlerOptions, ErrorReportContext, ErrorReporter } from './http/nest-error.js';
 export { findMysqlDriverError, logMysqlDriverError } from './http/mysql-driver-error.js';
 export type { MysqlDriverErrorLike } from './http/mysql-driver-error.js';
-export { createQueryFailedNestErrorHandler, reportClassifiedDbError } from './http/query-failed-error.js';
+export { createQueryFailedNestErrorHandler, classifyGenericMysqlDriverError } from './http/query-failed-error.js';
 export type { ClassifiedDbError, QueryFailedClassifier, QueryFailedNestErrorHandlerOptions, } from './http/query-failed-error.js';
+export { createAppErrorHandler } from './http/app-error-handler.js';
+export type { CreateAppErrorHandlerOptions } from './http/app-error-handler.js';
 export { normalizeTrailingSlash } from './http/trailing-slash.js';
 export type { ExecutionContextLike } from './http/execution-context.js';
+export { defaultDefer, createWaitUntilDefer } from './http/defer.js';
+export type { DeferExecutor } from './http/defer.js';
+export { createSentryErrorReporter } from './http/nest-error.js';
+export type { SentryExceptionReporterLike } from './http/nest-error.js';
 export { KVCache } from './cache/kv-cache.js';
 export type { KVNamespace, KVCacheOptions } from './cache/kv-cache.js';
 export { createStripeClient, verifyStripeWebhook } from './stripe/client.js';
@@ -41,6 +52,8 @@ export { sendInChunks } from './queue/send.js';
 export type { QueueLike, QueueSendMessage } from './queue/send.js';
 export { processBatch } from './queue/consumer.js';
 export type { QueueMessageLike, MessageBatchLike, ProcessBatchOptions, ProcessBatchResult } from './queue/consumer.js';
+export { createQueueErrorHandler } from './queue/error-handler.js';
+export type { CreateQueueErrorHandlerOptions } from './queue/error-handler.js';
 export { createAiGatewayProvider } from './ai/gateway.js';
 export type { AiGatewayConfig, AiGatewayProvider, AiGatewayBinding, AiGateway, AiGatewayOptions, } from './ai/gateway.js';
 export { getAuthenticationSecret } from './aws/secrets-manager.js';

package/dist/index.js

@@ -11,10 +11,15 @@
  */
 // middleware
 export { finalizeResponse } from './middleware/finalize-response.js';
-export { validate, createSentryValidate } from './middleware/validation.js';
+export { validate, createValidate } from './middleware/validation.js';
+// Backward-compat alias; prefer createValidate({ sentry }).
+// eslint-disable-next-line @typescript-eslint/no-deprecated -- intentional public re-export
+export { createSentryValidate } from './middleware/validation.js';
 export { zNum, zNumNullable, zNumOptional, zNumWithDefault } from './middleware/zod-coerce.js';
 export { createAuthMiddleware } from './middleware/auth.js';
 export { perfLog } from './middleware/perf-log.js';
+export { createIsolateMemo } from './container/isolate-memo.js';
+export { createContainerRuntime } from './container/middleware.js';
 // http
 export { getUserProtocol } from './http/user-protocol.js';
 export { getAppInfo } from './http/app-info.js';
@@ -22,8 +27,11 @@ export { resolveAppEnv, isProductionEnv } from './http/app-env.js';
 export { HttpStatus } from './http/http-status.js';
 export { createNestErrorHandler, nestNotFoundHandler, NEST_REASON_PHRASES } from './http/nest-error.js';
 export { findMysqlDriverError, logMysqlDriverError } from './http/mysql-driver-error.js';
-export { createQueryFailedNestErrorHandler, reportClassifiedDbError } from './http/query-failed-error.js';
+export { createQueryFailedNestErrorHandler, classifyGenericMysqlDriverError } from './http/query-failed-error.js';
+export { createAppErrorHandler } from './http/app-error-handler.js';
 export { normalizeTrailingSlash } from './http/trailing-slash.js';
+export { defaultDefer, createWaitUntilDefer } from './http/defer.js';
+export { createSentryErrorReporter } from './http/nest-error.js';
 // cache
 export { KVCache } from './cache/kv-cache.js';
 // stripe
@@ -33,6 +41,7 @@ export { retryWhenDeadlock } from './db/retry.js';
 // queue
 export { sendInChunks } from './queue/send.js';
 export { processBatch } from './queue/consumer.js';
+export { createQueueErrorHandler } from './queue/error-handler.js';
 // ai
 export { createAiGatewayProvider } from './ai/gateway.js';
 // aws

package/dist/middleware/validation.d.ts

@@ -108,44 +108,15 @@ export interface SentryLike {
     captureException(error: unknown): void;
 }
 /**
- * Create a {@link validate}-like factory that additionally reports DTO validation 400s to Sentry.
+ * Create a bound {@link validate} factory with optional Sentry reporting on validation failures.
  *
- * The returned function has the same signature and behavior as {@link validate}; reporting is a pure
- * side effect that does not alter validation behavior or the response. Each report is tagged with
- * `error.type=dto_validation` and carries a `validation` context of `{ errorCount, errors }`.
- *
- * @param sentry - A Sentry-like client used to capture validation failures; see {@link SentryLike}.
- * @returns A function `(target, schema) => MiddlewareHandler` mirroring {@link validate}.
- *
- * @example
- * ```ts
- * import * as Sentry from '@sentry/cloudflare';
- * import { z } from 'zod';
- * import { createSentryValidate } from '@rdlabo/workers-hono-kit';
- *
- * const validate = createSentryValidate(Sentry);
- * app.post('/users', validate('json', z.object({ name: z.string() })), handler);
- * ```
+ * @param options.sentry - When set, 400 validation errors are reported (dto_validation tag + context).
+ * @returns `(target, schema[, validateOptions])` middleware — same as {@link validate} when sentry is omitted.
  */
-export declare function createSentryValidate(sentry: SentryLike): <T>(target: ValidationTarget, schema: ZodType<T>) => import("hono").MiddlewareHandler<import("hono").Env, string, {
-    in: {
-        json?: unknown;
-        query?: {} | undefined;
-        param?: {} | undefined;
-        header?: {} | undefined;
-        cookie?: {} | undefined;
-        form?: {} | undefined;
-    };
-    out: {
-        json: T;
-        query: T;
-        param: T;
-        header: T;
-        cookie: T;
-        form: T;
-    };
-}, Response & import("hono").TypedResponse<{
-    statusCode: number;
-    message: string[];
-    error: string;
-}, 400, "json">>;
+export declare function createValidate(options?: {
+    sentry?: SentryLike;
+}): typeof validate;
+/**
+ * @deprecated Use {@link createValidate}({ sentry }) instead.
+ */
+export declare function createSentryValidate(sentry: SentryLike): typeof validate;

package/dist/middleware/validation.js

@@ -64,26 +64,16 @@ export function validate(target, schema, options) {
     });
 }
 /**
- * Create a {@link validate}-like factory that additionally reports DTO validation 400s to Sentry.
+ * Create a bound {@link validate} factory with optional Sentry reporting on validation failures.
  *
- * The returned function has the same signature and behavior as {@link validate}; reporting is a pure
- * side effect that does not alter validation behavior or the response. Each report is tagged with
- * `error.type=dto_validation` and carries a `validation` context of `{ errorCount, errors }`.
- *
- * @param sentry - A Sentry-like client used to capture validation failures; see {@link SentryLike}.
- * @returns A function `(target, schema) => MiddlewareHandler` mirroring {@link validate}.
- *
- * @example
- * ```ts
- * import * as Sentry from '@sentry/cloudflare';
- * import { z } from 'zod';
- * import { createSentryValidate } from '@rdlabo/workers-hono-kit';
- *
- * const validate = createSentryValidate(Sentry);
- * app.post('/users', validate('json', z.object({ name: z.string() })), handler);
- * ```
+ * @param options.sentry - When set, 400 validation errors are reported (dto_validation tag + context).
+ * @returns `(target, schema[, validateOptions])` middleware — same as {@link validate} when sentry is omitted.
  */
-export function createSentryValidate(sentry) {
+export function createValidate(options) {
+    if (!options?.sentry) {
+        return validate;
+    }
+    const sentry = options.sentry;
     const onValidationError = (error) => {
         const messages = zodToMessages(error);
         sentry.withScope((scope) => {
@@ -92,5 +82,11 @@ export function createSentryValidate(sentry) {
             sentry.captureException(error);
         });
     };
-    return (target, schema) => validate(target, schema, { onValidationError });
+    return (target, schema, validateOptions) => validate(target, schema, { ...validateOptions, onValidationError });
+}
+/**
+ * @deprecated Use {@link createValidate}({ sentry }) instead.
+ */
+export function createSentryValidate(sentry) {
+    return createValidate({ sentry });
 }

package/dist/queue/error-handler.d.ts

@@ -0,0 +1,24 @@
+import type { SentryExceptionReporterLike } from '../http/nest-error.js';
+import type { QueueMessageLike } from './consumer.js';
+/**
+ * Options for {@link createQueueErrorHandler}.
+ */
+export interface CreateQueueErrorHandlerOptions {
+    /** Queue name for log prefix and optional capture tags. */
+    queue: string;
+    /**
+     * When set, `captureException` is called only after the final delivery attempt
+     * (`message.attempts > maxRetries`). Cloudflare Queues uses 1-based `attempts`; the last delivery
+     * before the dead-letter queue has `attempts === maxRetries + 1`.
+     */
+    maxRetries?: number;
+    /** Optional Sentry client. Omit for console-only reporting (e.g. airlec). */
+    sentry?: SentryExceptionReporterLike;
+    /** Override {@link sentry}.captureException (custom sink). */
+    captureException?: SentryExceptionReporterLike['captureException'];
+}
+/**
+ * Factory for {@link processBatch}'s `onError` hook: logs every failure and optionally reports to
+ * Sentry (or another sink) with queue / message id / attempts / body context.
+ */
+export declare function createQueueErrorHandler(options: CreateQueueErrorHandlerOptions): (error: unknown, message: QueueMessageLike) => void;

package/dist/queue/error-handler.js

@@ -0,0 +1,21 @@
+/**
+ * Factory for {@link processBatch}'s `onError` hook: logs every failure and optionally reports to
+ * Sentry (or another sink) with queue / message id / attempts / body context.
+ */
+export function createQueueErrorHandler(options) {
+    const { queue, maxRetries, sentry, captureException } = options;
+    const capture = captureException ?? sentry?.captureException.bind(sentry);
+    return (error, message) => {
+        console.error(`[Queue:${queue}] message ${message.id} failed (attempt ${message.attempts})`, error);
+        if (!capture) {
+            return;
+        }
+        if (maxRetries !== undefined && message.attempts <= maxRetries) {
+            return;
+        }
+        capture(error, {
+            tags: { queue, queue_message_id: message.id },
+            extra: { attempts: message.attempts, body: message.body },
+        });
+    };
+}

package/package.json

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