@rdlabo/workers-hono-kit 0.2.0 → 0.3.0

package/dist/middleware/finalize-response.js

@@ -1,14 +1,13 @@
 /**
- * レスポンス最終化ミドルウェア。Express/Nest（移植元 `../api`）との byte 一致のため 2 点を行う
- * （フリート共通仕様 = receptray/winecode hono と同一）:
+ * Compute an Express `etag`-package compatible weak ETag for a response body.
  *
- * 1. **JSON の charset**: Express の res.json は `application/json; charset=utf-8` を返すが、
- *    Hono の c.json は `application/json`（charset 無し）なので合わせる。
- * 2. **weak ETag**: Express/`etag` パッケージ互換の
- *    `W/"<byteLength(16進)>-<sha1(body)をbase64して先頭27文字>"`。Express(=Nest) は GET 等のレスポンスに
- *    既定で付与するため、hono/etag の独自形式ではなく Express の算法に厳密一致させる。
+ * The format is `W/"<byteLength-in-hex>-<first 27 chars of base64(sha1(body))>"`, byte-for-byte
+ * identical to the weak ETag produced by the Express `etag` package. This deliberately differs
+ * from `hono/etag`'s own format so responses match an Express/Nest backend exactly.
  *
- * SSE（text/event-stream）はストリームを buffer できないため両方スキップ。
+ * @param body - The raw response body bytes to hash.
+ * @returns The weak ETag header value (e.g. `W/"1a-Qwerty..."`).
+ * @internal
  */
 async function weakEtag(body) {
     const digest = await crypto.subtle.digest('SHA-1', body);
@@ -20,18 +19,48 @@ async function weakEtag(body) {
     const b64 = btoa(bin).substring(0, 27);
     return `W/"${body.byteLength.toString(16)}-${b64}"`;
 }
+/**
+ * Create a Hono middleware that finalizes responses for byte-parity with an Express/Nest backend.
+ *
+ * After the downstream handler runs, it performs two adjustments:
+ *
+ * 1. **JSON charset**: Express's `res.json` emits `application/json; charset=utf-8`, whereas Hono's
+ *    `c.json` emits a bare `application/json`. A bare `application/json` content type is rewritten
+ *    to include `; charset=utf-8`.
+ * 2. **Weak ETag**: An Express `etag`-package compatible weak ETag is added, matching the format an
+ *    Express/Nest backend applies to responses by default. See {@link weakEtag} for the exact format.
+ *
+ * Server-Sent Events (`text/event-stream`) are skipped entirely because the stream cannot be
+ * buffered. ETag generation is also skipped for `204`/`304` responses, responses that already carry
+ * an `etag` header, and responses without a body.
+ *
+ * @returns A {@link MiddlewareHandler} that rewrites the response headers (and body, when an ETag
+ * must be computed) in place.
+ *
+ * @example
+ * ```ts
+ * import { Hono } from 'hono';
+ * import { finalizeResponse } from '@rdlabo/workers-hono-kit';
+ *
+ * const app = new Hono();
+ * app.use('*', finalizeResponse());
+ * app.get('/users', (c) => c.json({ ok: true }));
+ * // → Content-Type: application/json; charset=utf-8
+ * // → ETag: W/"b-..." (b = 0xb = 11 bytes, the length of `{"ok":true}`)
+ * ```
+ */
 export function finalizeResponse() {
     return async (c, next) => {
         await next();
         const status = c.res.status;
         const contentType = c.res.headers.get('content-type') ?? '';
-        // SSE / ストリームは触らない。
+        // Leave SSE / streaming responses untouched.
         if (contentType.includes('text/event-stream')) {
             return;
         }
-        // charset 補正対象（JSON で charset 未指定なら付与）。
+        // Charset target: add the charset when a JSON response leaves it unspecified.
         const needsCharset = contentType === 'application/json';
-        // ETag 対象（Express は 204/304 では付けない・既存 ETag は尊重）。
+        // ETag target: Express omits it on 204/304 and respects an existing ETag.
         const needsEtag = status !== 204 && status !== 304 && !c.res.headers.has('etag') && !!c.res.body;
         if (!needsCharset && !needsEtag) {
             return;
@@ -46,7 +75,7 @@ export function finalizeResponse() {
             c.res = new Response(buf, { status, statusText: c.res.statusText, headers });
         }
         else {
-            // body を読まずヘッダだけ差し替え。
+            // Swap only the headers without reading the body.
             c.res = new Response(c.res.body, { status, statusText: c.res.statusText, headers });
         }
     };

package/dist/middleware/validation.d.ts

@@ -1,21 +1,65 @@
 import type { Context } from 'hono';
 import type { ZodType } from 'zod';
-/** zod v3(ZodError) / v4(core $ZodError) どちらの error でも受けられる最小形 */
+/**
+ * Minimal structural shape that accepts either a zod v3 `ZodError` or a zod v4 core `$ZodError`.
+ *
+ * @remarks
+ * Declaring only the `issues` array (with `path` and `message`) keeps the kit independent of a
+ * specific zod major version while still exposing enough to format human-readable messages.
+ */
 export interface ZodErrorLike {
+    /** The validation issues reported by zod, each with a property path and a message. */
     issues: readonly {
         path: PropertyKey[];
         message: string;
     }[];
 }
+/** Request part that a validator inspects, mirroring the targets supported by `@hono/zod-validator`. */
 export type ValidationTarget = 'json' | 'query' | 'param' | 'header' | 'cookie' | 'form';
+/** Options controlling the optional side effects of {@link validate}. */
 export interface ValidateOptions {
     /**
-     * 検証失敗時のフック（Sentry 通報など）。**検証の挙動は変えない** — レスポンスは常に
-     * NestJS ValidationPipe 同形の 400 を返す。例外を投げても握り潰す。
-     * 既定は no-op（receptray 互換 = 4xx を通報しない）。foodlabel は Sentry 実通報を差し込む。
+     * Hook invoked when validation fails (e.g. to report to Sentry).
+     *
+     * @remarks
+     * This never changes validation behavior — the response is always a NestJS `ValidationPipe`-shaped
+     * 400. Exceptions thrown by the hook are swallowed. The default is a no-op (4xx errors are not
+     * reported); pass a hook to forward failures to an error tracker.
+     *
+     * @param error - The zod error describing the failed validation.
+     * @param c - The Hono context for the failing request.
      */
     onValidationError?: (error: ZodErrorLike, c: Context) => void;
 }
+/**
+ * Create a zod validation middleware that returns a NestJS `ValidationPipe`-shaped 400 on failure.
+ *
+ * On success the parsed value is made available through `@hono/zod-validator` as usual. On failure
+ * the response body is `{ statusCode: 400, message: string[], error: 'Bad Request' }`, the failing
+ * field paths are logged via `console.warn` (so 400s are visible in `wrangler dev`/Workers logs),
+ * and {@link ValidateOptions.onValidationError} is invoked if provided.
+ *
+ * @remarks
+ * The exact message strings differ from class-validator because they are produced by zod, but the
+ * envelope shape matches NestJS so clients can parse failures identically.
+ *
+ * @typeParam T - The type produced by the zod schema.
+ * @param target - The request part to validate.
+ * @param schema - The zod schema to validate the target against.
+ * @param options - Optional hooks; see {@link ValidateOptions}.
+ * @returns A Hono middleware that validates `target` and short-circuits with a 400 on failure.
+ *
+ * @example
+ * ```ts
+ * import { z } from 'zod';
+ * import { validate } from '@rdlabo/workers-hono-kit';
+ *
+ * app.post('/users', validate('json', z.object({ name: z.string() })), (c) => {
+ *   const { name } = c.req.valid('json');
+ *   return c.json({ name });
+ * });
+ * ```
+ */
 export declare function validate<T>(target: ValidationTarget, schema: ZodType<T>, options?: ValidateOptions): import("hono").MiddlewareHandler<import("hono").Env, string, {
     in: {
         json?: unknown;
@@ -38,20 +82,50 @@ export declare function validate<T>(target: ValidationTarget, schema: ZodType<T>
     message: string[];
     error: string;
 }, 400, "json">>;
-/** Sentry の最小形（`@sentry/cloudflare` 等への直接依存を避けるための構造型）。 */
+/**
+ * Minimal structural shape of a Sentry scope, covering only the methods this kit calls.
+ *
+ * @remarks
+ * Declaring the shape structurally avoids a direct dependency on `@sentry/cloudflare`; any object
+ * exposing these methods (such as the real Sentry scope) is accepted.
+ */
 export interface SentryScopeLike {
+    /** Attach a string tag to the current scope. */
     setTag(key: string, value: string): void;
+    /** Attach (or clear, with `null`) a structured context entry on the current scope. */
     setContext(key: string, context: Record<string, unknown> | null): void;
 }
+/**
+ * Minimal structural shape of the Sentry client, covering only the methods this kit calls.
+ *
+ * @remarks
+ * Like {@link SentryScopeLike}, this avoids a hard dependency on `@sentry/cloudflare`.
+ */
 export interface SentryLike {
+    /** Run a callback with an isolated scope, restoring the previous scope afterward. */
     withScope(callback: (scope: SentryScopeLike) => void): void;
+    /** Report an exception to Sentry. */
     captureException(error: unknown): void;
 }
 /**
- * DTO 検証 400 を Sentry に通報する `validate` を返すファクトリ（foodlabel/tipsys/winecode で重複していた
- * reportValidationToSentry を集約）。kit は `@sentry/cloudflare` に依存せず、Sentry モジュールを注入する。
- * 通報は `tag error.type=dto_validation` ＋ `context validation={errorCount, errors}`（各 /api の
- * sentry-validation.pipe.ts 準拠）。検証の挙動・レスポンスは `validate` と同一（通報は副作用のみ）。
+ * Create a {@link validate}-like factory that additionally reports DTO validation 400s to Sentry.
+ *
+ * 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);
+ * ```
  */
 export declare function createSentryValidate(sentry: SentryLike): <T>(target: ValidationTarget, schema: ZodType<T>) => import("hono").MiddlewareHandler<import("hono").Env, string, {
     in: {

package/dist/middleware/validation.js

@@ -1,11 +1,11 @@
 import { zValidator } from '@hono/zod-validator';
 /**
- * Zod 検証ミドルウェア（フリート共通 = receptray/winecode hono と同一仕様）。
- * 失敗時は NestJS の ValidationPipe と同形の body を返す:
- *   { statusCode: 400, message: string[], error: 'Bad Request' }
+ * Convert a {@link ZodErrorLike} into NestJS `ValidationPipe`-style message strings.
  *
- * NOTE(parity): message の文字列内容は class-validator と Zod で異なる。各 repo の固定 app の
- * 正常系では DTO 検証 400 は発生しない前提（ビジネス 400 は各エンドポイントで HttpError 忠実再現）。
+ * Each issue becomes `"<dotted.path>: <message>"`, or just `"<message>"` when the path is empty.
+ *
+ * @param error - The zod error to flatten.
+ * @returns One message string per issue.
  */
 function zodToMessages(error) {
     return error.issues.map((issue) => {
@@ -13,6 +13,35 @@ function zodToMessages(error) {
         return path ? `${path}: ${issue.message}` : issue.message;
     });
 }
+/**
+ * Create a zod validation middleware that returns a NestJS `ValidationPipe`-shaped 400 on failure.
+ *
+ * On success the parsed value is made available through `@hono/zod-validator` as usual. On failure
+ * the response body is `{ statusCode: 400, message: string[], error: 'Bad Request' }`, the failing
+ * field paths are logged via `console.warn` (so 400s are visible in `wrangler dev`/Workers logs),
+ * and {@link ValidateOptions.onValidationError} is invoked if provided.
+ *
+ * @remarks
+ * The exact message strings differ from class-validator because they are produced by zod, but the
+ * envelope shape matches NestJS so clients can parse failures identically.
+ *
+ * @typeParam T - The type produced by the zod schema.
+ * @param target - The request part to validate.
+ * @param schema - The zod schema to validate the target against.
+ * @param options - Optional hooks; see {@link ValidateOptions}.
+ * @returns A Hono middleware that validates `target` and short-circuits with a 400 on failure.
+ *
+ * @example
+ * ```ts
+ * import { z } from 'zod';
+ * import { validate } from '@rdlabo/workers-hono-kit';
+ *
+ * app.post('/users', validate('json', z.object({ name: z.string() })), (c) => {
+ *   const { name } = c.req.valid('json');
+ *   return c.json({ name });
+ * });
+ * ```
+ */
 export function validate(target, schema, options) {
     return zValidator(target, schema, (result, c) => {
         if (!result.success) {
@@ -35,10 +64,24 @@ export function validate(target, schema, options) {
     });
 }
 /**
- * DTO 検証 400 を Sentry に通報する `validate` を返すファクトリ（foodlabel/tipsys/winecode で重複していた
- * reportValidationToSentry を集約）。kit は `@sentry/cloudflare` に依存せず、Sentry モジュールを注入する。
- * 通報は `tag error.type=dto_validation` ＋ `context validation={errorCount, errors}`（各 /api の
- * sentry-validation.pipe.ts 準拠）。検証の挙動・レスポンスは `validate` と同一（通報は副作用のみ）。
+ * Create a {@link validate}-like factory that additionally reports DTO validation 400s to Sentry.
+ *
+ * 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);
+ * ```
  */
 export function createSentryValidate(sentry) {
     const onValidationError = (error) => {

package/dist/middleware/zod-coerce.d.ts

@@ -1,9 +1,63 @@
 import { z } from 'zod';
 /**
- * 数値強制スキーマ。`inner` に `z.number().int()` 等を渡して制約を足せる（既定は z.number()）。
- * 例: zNum(z.number().int()) で整数必須。
+ * Build a required number schema that coerces string input to a number.
+ *
+ * @param inner - The inner number schema to apply after coercion; pass e.g. `z.number().int()` to add
+ * constraints. Defaults to `z.number()`.
+ * @returns A zod schema yielding a `number`.
+ *
+ * @example
+ * ```ts
+ * // Require an integer path param:
+ * const schema = z.object({ id: zNum(z.number().int()) });
+ * // '42' → 42, '' / '  ' → NaN (rejected)
+ * ```
  */
 export declare const zNum: (inner?: z.ZodNumber) => z.ZodType<number>;
+/**
+ * Build a number schema that coerces string input and substitutes a default for missing values.
+ *
+ * `undefined` or an empty string yields `defaultValue`; a whitespace-only string yields `NaN`
+ * (rejected by the inner schema); anything else is passed through `Number`.
+ *
+ * @param defaultValue - The value used when the input is `undefined` or an empty string.
+ * @param inner - The inner number schema applied after coercion. Defaults to `z.number()`.
+ * @returns A zod schema yielding a `number`.
+ *
+ * @example
+ * ```ts
+ * // Default page to 1 when the query param is absent:
+ * const schema = z.object({ page: zNumWithDefault(1) });
+ * ```
+ */
 export declare const zNumWithDefault: (defaultValue: number, inner?: z.ZodNumber) => z.ZodType<number>;
+/**
+ * Build an optional number schema that coerces string input.
+ *
+ * `undefined`, `null`, or an empty string yields `undefined`; a whitespace-only string yields `NaN`
+ * (rejected); anything else is passed through `Number`.
+ *
+ * @param inner - The inner number schema applied after coercion. Defaults to `z.number()`.
+ * @returns A zod schema yielding `number | undefined`.
+ *
+ * @example
+ * ```ts
+ * const schema = z.object({ limit: zNumOptional(z.number().int()) });
+ * ```
+ */
 export declare const zNumOptional: (inner?: z.ZodNumber) => z.ZodType<number | undefined>;
+/**
+ * Build a nullable, optional number schema that coerces string input.
+ *
+ * `null`/`undefined` pass through unchanged; an empty string yields `undefined`; a whitespace-only
+ * string yields `NaN` (rejected); anything else is passed through `Number`.
+ *
+ * @param inner - The inner number schema applied after coercion. Defaults to `z.number()`.
+ * @returns A zod schema yielding `number | null | undefined`.
+ *
+ * @example
+ * ```ts
+ * const schema = z.object({ parentId: zNumNullable(z.number().int()) });
+ * ```
+ */
 export declare const zNumNullable: (inner?: z.ZodNumber) => z.ZodType<number | null | undefined>;

package/dist/middleware/zod-coerce.js

@@ -1,13 +1,18 @@
 import { z } from 'zod';
 /**
- * `/api` の class-transformer @Transform（number-transform.util.ts）を Zod preprocess で忠実再現する。
- * path/query は常に文字列で来るため数値強制が必要。空白のみ文字列は NaN にして後段の数値スキーマで弾く
- * （class-validator の @IsInt/@IsNumber が NaN を拒否する挙動と一致。zod v4 は z.number() が NaN を既定拒否）。
+ * Zod preprocessors that coerce string path/query parameters into numbers.
+ *
+ * @remarks
+ * These mirror a class-transformer `@Transform(() => Number)` coercion: path and query parameters
+ * always arrive as strings, so they must be forced to numbers before number validation. Whitespace-only
+ * strings are mapped to `NaN` so the downstream number schema rejects them (matching class-validator's
+ * `@IsInt`/`@IsNumber`, which reject `NaN`; zod v4's `z.number()` also rejects `NaN` by default).
  */
+/** Return `true` when `value` is a string that is empty or contains only whitespace. */
 const isBlankString = (value) => typeof value === 'string' && value.trim() === '';
-// toNumber: 空白文字列 → NaN、それ以外 → Number(value)
+// toNumber: blank string → NaN, otherwise → Number(value).
 const rawToNumber = (value) => (isBlankString(value) ? Number(undefined) : Number(value));
-// toNumberWithDefault: undefined/'' → default、空白 → NaN、else Number
+// toNumberWithDefault: undefined/'' → default, blank → NaN, else Number.
 const rawToNumberWithDefault = (defaultValue) => (value) => {
     if (value === undefined || value === '') {
         return defaultValue;
@@ -17,7 +22,7 @@ const rawToNumberWithDefault = (defaultValue) => (value) => {
     }
     return Number(value);
 };
-// toOptionalNumber: undefined/null/'' → undefined、空白 → NaN、else Number
+// toOptionalNumber: undefined/null/'' → undefined, blank → NaN, else Number.
 const rawToOptionalNumber = (value) => {
     if (value === undefined || value === null || value === '') {
         return undefined;
@@ -27,7 +32,7 @@ const rawToOptionalNumber = (value) => {
     }
     return Number(value);
 };
-// toNullableNumber: null/undefined → passthrough、'' → undefined、空白 → NaN、else Number
+// toNullableNumber: null/undefined → passthrough, '' → undefined, blank → NaN, else Number.
 const rawToNullableNumber = (value) => {
     if (value === null || value === undefined) {
         return value;
@@ -41,10 +46,64 @@ const rawToNullableNumber = (value) => {
     return Number(value);
 };
 /**
- * 数値強制スキーマ。`inner` に `z.number().int()` 等を渡して制約を足せる（既定は z.number()）。
- * 例: zNum(z.number().int()) で整数必須。
+ * Build a required number schema that coerces string input to a number.
+ *
+ * @param inner - The inner number schema to apply after coercion; pass e.g. `z.number().int()` to add
+ * constraints. Defaults to `z.number()`.
+ * @returns A zod schema yielding a `number`.
+ *
+ * @example
+ * ```ts
+ * // Require an integer path param:
+ * const schema = z.object({ id: zNum(z.number().int()) });
+ * // '42' → 42, '' / '  ' → NaN (rejected)
+ * ```
  */
 export const zNum = (inner = z.number()) => z.preprocess(rawToNumber, inner);
+/**
+ * Build a number schema that coerces string input and substitutes a default for missing values.
+ *
+ * `undefined` or an empty string yields `defaultValue`; a whitespace-only string yields `NaN`
+ * (rejected by the inner schema); anything else is passed through `Number`.
+ *
+ * @param defaultValue - The value used when the input is `undefined` or an empty string.
+ * @param inner - The inner number schema applied after coercion. Defaults to `z.number()`.
+ * @returns A zod schema yielding a `number`.
+ *
+ * @example
+ * ```ts
+ * // Default page to 1 when the query param is absent:
+ * const schema = z.object({ page: zNumWithDefault(1) });
+ * ```
+ */
 export const zNumWithDefault = (defaultValue, inner = z.number()) => z.preprocess(rawToNumberWithDefault(defaultValue), inner);
+/**
+ * Build an optional number schema that coerces string input.
+ *
+ * `undefined`, `null`, or an empty string yields `undefined`; a whitespace-only string yields `NaN`
+ * (rejected); anything else is passed through `Number`.
+ *
+ * @param inner - The inner number schema applied after coercion. Defaults to `z.number()`.
+ * @returns A zod schema yielding `number | undefined`.
+ *
+ * @example
+ * ```ts
+ * const schema = z.object({ limit: zNumOptional(z.number().int()) });
+ * ```
+ */
 export const zNumOptional = (inner = z.number()) => z.preprocess(rawToOptionalNumber, inner.optional());
+/**
+ * Build a nullable, optional number schema that coerces string input.
+ *
+ * `null`/`undefined` pass through unchanged; an empty string yields `undefined`; a whitespace-only
+ * string yields `NaN` (rejected); anything else is passed through `Number`.
+ *
+ * @param inner - The inner number schema applied after coercion. Defaults to `z.number()`.
+ * @returns A zod schema yielding `number | null | undefined`.
+ *
+ * @example
+ * ```ts
+ * const schema = z.object({ parentId: zNumNullable(z.number().int()) });
+ * ```
+ */
 export const zNumNullable = (inner = z.number()) => z.preprocess(rawToNullableNumber, inner.nullish());

package/dist/queue/consumer.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Consumer-side helper for processing a Cloudflare Queues `MessageBatch` with per-message success and
+ * failure handling.
+ *
+ * A queue consumer invocation receives at most `max_batch_size` messages (configured in
+ * `wrangler.toml`), which is precisely the mechanism that bounds its subrequest budget: with a small
+ * `max_batch_size`, each invocation performs a fixed, small number of external calls no matter how
+ * many messages are backed up in the queue. {@link processBatch} applies the standard
+ * ack-on-success / retry-on-failure discipline so one poison message does not fail its whole batch.
+ *
+ * Messages are processed sequentially. This keeps the number of *simultaneously open* subrequests at
+ * one, staying well clear of the Workers concurrent-connection ceiling, and makes the per-invocation
+ * subrequest count deterministic (`<= max_batch_size`). For a queue consumer — which is not on a
+ * user-facing latency path — sequential processing is the safer default.
+ *
+ * @example
+ * ```ts
+ * // Worker `queue` handler
+ * export default {
+ *   async queue(batch: MessageBatchLike<{ userId: number }>, env: Env) {
+ *     await processBatch(batch, async ({ userId }) => {
+ *       await reloadOneCustomer(env, userId); // exactly one external payment call
+ *     });
+ *   },
+ * };
+ * ```
+ *
+ * @packageDocumentation
+ */
+/**
+ * Minimal subset of `@cloudflare/workers-types`' `Message` used by {@link processBatch}.
+ *
+ * Declared locally so consumers are not forced to depend on `@cloudflare/workers-types`.
+ *
+ * @typeParam Body - Type of the message body.
+ */
+export interface QueueMessageLike<Body = unknown> {
+    /** Unique id assigned by the Queues runtime. */
+    readonly id: string;
+    /** Number of delivery attempts so far (starts at 1 on first delivery). */
+    readonly attempts: number;
+    /** The message payload. */
+    readonly body: Body;
+    /** Explicitly acknowledge this message so it is not redelivered. */
+    ack: () => void;
+    /** Mark this message for redelivery, optionally after a delay. */
+    retry: (options?: {
+        delaySeconds?: number;
+    }) => void;
+}
+/**
+ * Minimal subset of `@cloudflare/workers-types`' `MessageBatch` used by {@link processBatch}.
+ *
+ * @typeParam Body - Type of each message body in the batch.
+ */
+export interface MessageBatchLike<Body = unknown> {
+    /** Name of the queue this batch was delivered from. */
+    readonly queue: string;
+    /** The messages in this batch; length is bounded by the consumer's `max_batch_size`. */
+    readonly messages: readonly QueueMessageLike<Body>[];
+}
+/**
+ * Options for {@link processBatch}.
+ *
+ * @typeParam Body - Type of each message body.
+ */
+export interface ProcessBatchOptions<Body = unknown> {
+    /**
+     * Invoked when `handler` throws for a message, immediately before the message is marked for retry.
+     * Use it to log or report; it must not throw. Defaults to `console.error`.
+     */
+    onError?: (error: unknown, message: QueueMessageLike<Body>) => void;
+    /**
+     * Delay, in seconds, applied when re-queuing a failed message. Omit to retry with the queue's
+     * default backoff.
+     */
+    retryDelaySeconds?: number;
+}
+/**
+ * Outcome counts returned by {@link processBatch}.
+ */
+export interface ProcessBatchResult {
+    /** Messages whose handler completed successfully and were acked. */
+    processed: number;
+    /** Messages whose handler threw and were marked for retry. */
+    failed: number;
+}
+/**
+ * Process every message in `batch` sequentially, acking on success and retrying on failure.
+ *
+ * Each message is passed to `handler`; if it resolves the message is acked, and if it throws the
+ * error is routed to {@link ProcessBatchOptions.onError} and the message is marked for retry (honoring
+ * {@link ProcessBatchOptions.retryDelaySeconds}). One failing message never affects the others, and
+ * the returned counts let tests assert that the per-invocation workload — and therefore the
+ * subrequest count — stayed bounded by the batch size.
+ *
+ * @typeParam Body - Type of each message body.
+ * @param batch - The delivered message batch.
+ * @param handler - Async work for a single message; performs the bounded external call(s). Receives
+ *   the decoded `body` and the raw message (for `attempts`, `id`, etc.).
+ * @param options - Error reporting and retry tuning; see {@link ProcessBatchOptions}.
+ * @returns The number of processed and failed messages.
+ * @example
+ * ```ts
+ * const { processed, failed } = await processBatch(
+ *   batch,
+ *   async ({ id }) => sendOneMail(id),
+ *   { retryDelaySeconds: 30, onError: (e, m) => report(e, m.id) },
+ * );
+ * ```
+ */
+export declare function processBatch<Body>(batch: MessageBatchLike<Body>, handler: (body: Body, message: QueueMessageLike<Body>) => Promise<void>, options?: ProcessBatchOptions<Body>): Promise<ProcessBatchResult>;

package/dist/queue/consumer.js

@@ -0,0 +1,80 @@
+/**
+ * Consumer-side helper for processing a Cloudflare Queues `MessageBatch` with per-message success and
+ * failure handling.
+ *
+ * A queue consumer invocation receives at most `max_batch_size` messages (configured in
+ * `wrangler.toml`), which is precisely the mechanism that bounds its subrequest budget: with a small
+ * `max_batch_size`, each invocation performs a fixed, small number of external calls no matter how
+ * many messages are backed up in the queue. {@link processBatch} applies the standard
+ * ack-on-success / retry-on-failure discipline so one poison message does not fail its whole batch.
+ *
+ * Messages are processed sequentially. This keeps the number of *simultaneously open* subrequests at
+ * one, staying well clear of the Workers concurrent-connection ceiling, and makes the per-invocation
+ * subrequest count deterministic (`<= max_batch_size`). For a queue consumer — which is not on a
+ * user-facing latency path — sequential processing is the safer default.
+ *
+ * @example
+ * ```ts
+ * // Worker `queue` handler
+ * export default {
+ *   async queue(batch: MessageBatchLike<{ userId: number }>, env: Env) {
+ *     await processBatch(batch, async ({ userId }) => {
+ *       await reloadOneCustomer(env, userId); // exactly one external payment call
+ *     });
+ *   },
+ * };
+ * ```
+ *
+ * @packageDocumentation
+ */
+/**
+ * Process every message in `batch` sequentially, acking on success and retrying on failure.
+ *
+ * Each message is passed to `handler`; if it resolves the message is acked, and if it throws the
+ * error is routed to {@link ProcessBatchOptions.onError} and the message is marked for retry (honoring
+ * {@link ProcessBatchOptions.retryDelaySeconds}). One failing message never affects the others, and
+ * the returned counts let tests assert that the per-invocation workload — and therefore the
+ * subrequest count — stayed bounded by the batch size.
+ *
+ * @typeParam Body - Type of each message body.
+ * @param batch - The delivered message batch.
+ * @param handler - Async work for a single message; performs the bounded external call(s). Receives
+ *   the decoded `body` and the raw message (for `attempts`, `id`, etc.).
+ * @param options - Error reporting and retry tuning; see {@link ProcessBatchOptions}.
+ * @returns The number of processed and failed messages.
+ * @example
+ * ```ts
+ * const { processed, failed } = await processBatch(
+ *   batch,
+ *   async ({ id }) => sendOneMail(id),
+ *   { retryDelaySeconds: 30, onError: (e, m) => report(e, m.id) },
+ * );
+ * ```
+ */
+export async function processBatch(batch, handler, options) {
+    const onError = options?.onError ??
+        ((error, message) => {
+            console.error(`[queue:${batch.queue}] message ${message.id} failed`, error);
+        });
+    const retryOptions = options?.retryDelaySeconds === undefined ? undefined : { delaySeconds: options.retryDelaySeconds };
+    let processed = 0;
+    let failed = 0;
+    for (const message of batch.messages) {
+        try {
+            await handler(message.body, message);
+            message.ack();
+            processed++;
+        }
+        catch (error) {
+            try {
+                onError(error, message);
+            }
+            catch {
+                // onError contract says "must not throw"; guard defensively so retry() and remaining messages still run.
+            }
+            message.retry(retryOptions);
+            failed++;
+        }
+    }
+    return { processed, failed };
+}