npm - @rdlabo/workers-hono-kit - Versions diffs - 0.2.1 → 0.3.0 - Mend

@rdlabo/workers-hono-kit 0.2.1 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (11) hide show

package/dist/index.d.ts +4 -0
package/dist/index.js +3 -0
package/dist/queue/consumer.d.ts +112 -0
package/dist/queue/consumer.js +80 -0
package/dist/queue/send.d.ts +90 -0
package/dist/queue/send.js +85 -0
package/package.json +3 -2
package/scripts/check-subrequest-fanout.mjs +86 -0
package/src/index.ts +6 -0
package/src/queue/consumer.ts +146 -0
package/src/queue/send.ts +129 -0

package/dist/index.d.ts CHANGED Viewed

@@ -29,6 +29,10 @@ export type { KVNamespace, KVCacheOptions } from './cache/kv-cache.js';
 export { createStripeClient, verifyStripeWebhook } from './stripe/client.js';
 export type { CreateStripeClientOptions } from './stripe/client.js';
 export { retryWhenDeadlock } from './db/retry.js';
+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 { 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 CHANGED Viewed

@@ -26,6 +26,9 @@ export { KVCache } from './cache/kv-cache.js';
 export { createStripeClient, verifyStripeWebhook } from './stripe/client.js';
 // db
 export { retryWhenDeadlock } from './db/retry.js';
+// queue
+export { sendInChunks } from './queue/send.js';
+export { processBatch } from './queue/consumer.js';
 // ai
 export { createAiGatewayProvider } from './ai/gateway.js';
 // aws

package/dist/queue/consumer.d.ts ADDED Viewed

@@ -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 ADDED Viewed

@@ -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 };
+}

package/dist/queue/send.d.ts ADDED Viewed

@@ -0,0 +1,90 @@
+/**
+ * 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.
+ *
+ * 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
+ * subrequest budget. See {@link processBatch} for the consumer side.
+ *
+ * @example
+ * ```ts
+ * // In a Cron Trigger `scheduled` handler: enqueue every billing user, then let the consumer
+ * // re-derive payment state one user per message.
+ * const userIds = await query.getUserIdForReloadCustomer(); // DB read — not a subrequest
+ * await sendInChunks(env.PAYMENT_RELOAD_QUEUE, userIds);     // ceil(N / 100) subrequests
+ * ```
+ *
+ * @packageDocumentation
+ */
+/**
+ * Minimal subset of `@cloudflare/workers-types`' `Queue` used by {@link sendInChunks}.
+ *
+ * Declared locally so consumers are not forced to depend on `@cloudflare/workers-types`. Only the
+ * batch-send operation the helper actually needs is modeled.
+ *
+ * @typeParam Body - Type of each message body enqueued onto this queue.
+ */
+export interface QueueLike<Body = unknown> {
+    /**
+     * Enqueue up to 100 messages in a single operation (one subrequest).
+     *
+     * @param messages - The message envelopes to enqueue; at most 100 per call, 256 KB per batch.
+     * @param options - Optional batch-level options, e.g. a `delaySeconds` applied to every message.
+     * @returns A promise that resolves once the batch is accepted. The resolved value is ignored, so a
+     *   real `Queue` binding (whose `sendBatch` resolves to a `QueueSendBatchResponse`) is assignable.
+     */
+    sendBatch: (messages: Iterable<QueueSendMessage<Body>>, options?: {
+        delaySeconds?: number;
+    }) => Promise<unknown>;
+}
+/**
+ * A single message envelope passed to {@link QueueLike.sendBatch}.
+ *
+ * @typeParam Body - Type of the message body.
+ */
+export interface QueueSendMessage<Body = unknown> {
+    /** The message payload; structured-cloned by the Queues runtime. */
+    body: Body;
+    /** Optional content type hint (`'json'` by default for object bodies). */
+    contentType?: 'text' | 'bytes' | 'json' | 'v8';
+    /** Optional per-message delivery delay, in seconds. */
+    delaySeconds?: number;
+}
+/**
+ * Enqueue every item in `items` using batched sends so the producer's subrequest count stays
+ * bounded at `ceil(items.length / chunkSize)` rather than growing per item.
+ *
+ * Each element becomes one queue message (`{ body: item }`); wrap or map your rows into small,
+ * self-describing payloads (e.g. an id plus a discriminator) before calling. Keep each batch under
+ * the Queues 256 KB limit — with `chunkSize <= 100` and small id-shaped payloads this is not a
+ * concern, but large bodies may require a smaller `chunkSize`.
+ *
+ * Batches are sent sequentially so a mid-list failure surfaces promptly (the already-sent batches
+ * are durably enqueued; the throw lets the caller decide whether to retry the remainder). An empty
+ * `items` is a no-op.
+ *
+ * @typeParam Body - Type of each message body.
+ * @param queue - The producer binding to send onto.
+ * @param items - The full list of message bodies to enqueue; may be arbitrarily large.
+ * @param options - Tuning options.
+ * @param options.chunkSize - Messages per `sendBatch` call. Defaults to and is capped at 100 (the
+ *   Queues per-batch maximum); values below 1 are clamped to 1.
+ * @returns The number of `sendBatch` calls issued (i.e. subrequests spent), useful for asserting the
+ *   fan-out stayed bounded in tests.
+ * @example
+ * ```ts
+ * const batches = await sendInChunks(env.MY_QUEUE, ids);        // one send per 100 ids
+ * const batches = await sendInChunks(env.MY_QUEUE, rows, {      // custom batch size for larger bodies
+ *   chunkSize: 25,
+ * });
+ * ```
+ */
+export declare function sendInChunks<Body>(queue: QueueLike<Body>, items: readonly Body[], options?: {
+    chunkSize?: number;
+}): Promise<number>;

package/dist/queue/send.js ADDED Viewed

@@ -0,0 +1,85 @@
+/**
+ * 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.
+ *
+ * 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
+ * subrequest budget. See {@link processBatch} for the consumer side.
+ *
+ * @example
+ * ```ts
+ * // In a Cron Trigger `scheduled` handler: enqueue every billing user, then let the consumer
+ * // re-derive payment state one user per message.
+ * const userIds = await query.getUserIdForReloadCustomer(); // DB read — not a subrequest
+ * await sendInChunks(env.PAYMENT_RELOAD_QUEUE, userIds);     // ceil(N / 100) subrequests
+ * ```
+ *
+ * @packageDocumentation
+ */
+/**
+ * The Cloudflare Queues hard limit on messages per {@link QueueLike.sendBatch} call.
+ */
+const MAX_BATCH_SIZE = 100;
+/**
+ * Split a list into fixed-size chunks (order preserving).
+ *
+ * @typeParam T - Element type.
+ * @param items - Source list.
+ * @param size - Maximum chunk length (assumed `>= 1`).
+ * @returns An array of chunks, each at most `size` long.
+ * @internal
+ */
+function chunk(items, size) {
+    const result = [];
+    for (let i = 0; i < items.length; i += size) {
+        result.push(items.slice(i, i + size));
+    }
+    return result;
+}
+/**
+ * Enqueue every item in `items` using batched sends so the producer's subrequest count stays
+ * bounded at `ceil(items.length / chunkSize)` rather than growing per item.
+ *
+ * Each element becomes one queue message (`{ body: item }`); wrap or map your rows into small,
+ * self-describing payloads (e.g. an id plus a discriminator) before calling. Keep each batch under
+ * the Queues 256 KB limit — with `chunkSize <= 100` and small id-shaped payloads this is not a
+ * concern, but large bodies may require a smaller `chunkSize`.
+ *
+ * Batches are sent sequentially so a mid-list failure surfaces promptly (the already-sent batches
+ * are durably enqueued; the throw lets the caller decide whether to retry the remainder). An empty
+ * `items` is a no-op.
+ *
+ * @typeParam Body - Type of each message body.
+ * @param queue - The producer binding to send onto.
+ * @param items - The full list of message bodies to enqueue; may be arbitrarily large.
+ * @param options - Tuning options.
+ * @param options.chunkSize - Messages per `sendBatch` call. Defaults to and is capped at 100 (the
+ *   Queues per-batch maximum); values below 1 are clamped to 1.
+ * @returns The number of `sendBatch` calls issued (i.e. subrequests spent), useful for asserting the
+ *   fan-out stayed bounded in tests.
+ * @example
+ * ```ts
+ * const batches = await sendInChunks(env.MY_QUEUE, ids);        // one send per 100 ids
+ * const batches = await sendInChunks(env.MY_QUEUE, rows, {      // custom batch size for larger bodies
+ *   chunkSize: 25,
+ * });
+ * ```
+ */
+export async function sendInChunks(queue, items, options) {
+    if (items.length === 0) {
+        return 0;
+    }
+    const rawChunkSize = options?.chunkSize ?? MAX_BATCH_SIZE;
+    const chunkSize = Math.min(MAX_BATCH_SIZE, Math.max(1, Math.trunc(Number.isNaN(rawChunkSize) ? MAX_BATCH_SIZE : rawChunkSize)));
+    const batches = chunk(items, chunkSize);
+    for (const batch of batches) {
+        await queue.sendBatch(batch.map((body) => ({ body })));
+    }
+    return batches.length;
+}

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@rdlabo/workers-hono-kit",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -40,7 +40,8 @@
     "!src/**/*.spec.ts"
   ],
   "bin": {
-    "workers-hono-kit-sync-dev-aws": "./scripts/sync-dev-aws.mjs"
+    "workers-hono-kit-sync-dev-aws": "./scripts/sync-dev-aws.mjs",
+    "workers-hono-kit-check-subrequest-fanout": "./scripts/check-subrequest-fanout.mjs"
   },
   "exports": {
     ".": {

package/scripts/check-subrequest-fanout.mjs ADDED Viewed

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+/**
+ * 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
+ * (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.
+ *
+ * Markers: `runWithConcurrency(`, `PromisePool`, `.withConcurrency(`.
+ *
+ * To allow a genuinely-safe site (e.g. the loop body only writes to the DB over TCP, which is NOT a
+ * subrequest, or the iteration count is hard-capped), put `subrequest-ok` in a comment on the same
+ * line or the line immediately above. Prefer a short reason, e.g. `// subrequest-ok: DB writes only`.
+ *
+ * Usage:
+ *   node node_modules/@rdlabo/workers-hono-kit/scripts/check-subrequest-fanout.mjs [dir ...]
+ * Defaults to scanning `src`. Exits 1 if any un-annotated marker is found.
+ */
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+const MARKER = /runWithConcurrency\(|PromisePool|\.withConcurrency\(/;
+const ALLOW = /subrequest-ok/;
+const SKIP_DIRS = new Set(['node_modules', 'dist', '.git', 'coverage']);
+/** Recursively collect .ts files (excluding *.spec.ts / *.test.ts). */
+function collect(dir) {
+  const out = [];
+  let entries;
+  try {
+    entries = readdirSync(dir);
+  } catch {
+    return out;
+  }
+  for (const name of entries) {
+    const full = join(dir, name);
+    const st = statSync(full);
+    if (st.isDirectory()) {
+      if (!SKIP_DIRS.has(name)) {
+        out.push(...collect(full));
+      }
+    } else if (name.endsWith('.ts') && !name.endsWith('.spec.ts') && !name.endsWith('.test.ts')) {
+      out.push(full);
+    }
+  }
+  return out;
+}
+const targets = process.argv.slice(2);
+const roots = targets.length > 0 ? targets : ['src'];
+const violations = [];
+for (const root of roots) {
+  for (const file of collect(root)) {
+    const lines = readFileSync(file, 'utf8').split('\n');
+    lines.forEach((line, i) => {
+      if (!MARKER.test(line)) {
+        return;
+      }
+      // Only flag executable code, not porting notes / JSDoc that merely mention the markers.
+      const trimmed = line.trim();
+      if (trimmed.startsWith('//') || trimmed.startsWith('*') || trimmed.startsWith('/*')) {
+        return;
+      }
+      const prev = i > 0 ? lines[i - 1] : '';
+      if (ALLOW.test(line) || ALLOW.test(prev)) {
+        return;
+      }
+      violations.push({ file, line: i + 1, text: trimmed });
+    });
+  }
+}
+if (violations.length > 0) {
+  console.error('✖ subrequest fan-out gate: un-annotated concurrency loop(s) found.');
+  console.error('  Each may loop an external call per item (fetch/AI/Stripe/push/ES) and blow the');
+  console.error('  Workers subrequest cap as data grows. Move it behind a queue / cap it, or, if the');
+  console.error('  loop body is DB-only or hard-capped, annotate with `// subrequest-ok: <reason>`.\n');
+  for (const v of violations) {
+    console.error(`  ${v.file}:${v.line}  ${v.text}`);
+  }
+  process.exit(1);
+}
+console.log('✓ subrequest fan-out gate: no un-annotated concurrency loops.');

package/src/index.ts CHANGED Viewed

@@ -46,6 +46,12 @@ export type { CreateStripeClientOptions } from './stripe/client.js';
 // db
 export { retryWhenDeadlock } from './db/retry.js';
+// queue
+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';
 // ai
 export { createAiGatewayProvider } from './ai/gateway.js';
 export type {

package/src/queue/consumer.ts ADDED Viewed

@@ -0,0 +1,146 @@
+/**
+ * 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 async function processBatch<Body>(
+  batch: MessageBatchLike<Body>,
+  handler: (body: Body, message: QueueMessageLike<Body>) => Promise<void>,
+  options?: ProcessBatchOptions<Body>,
+): Promise<ProcessBatchResult> {
+  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 };
+}

package/src/queue/send.ts ADDED Viewed

@@ -0,0 +1,129 @@
+/**
+ * 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.
+ *
+ * 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
+ * subrequest budget. See {@link processBatch} for the consumer side.
+ *
+ * @example
+ * ```ts
+ * // In a Cron Trigger `scheduled` handler: enqueue every billing user, then let the consumer
+ * // re-derive payment state one user per message.
+ * const userIds = await query.getUserIdForReloadCustomer(); // DB read — not a subrequest
+ * await sendInChunks(env.PAYMENT_RELOAD_QUEUE, userIds);     // ceil(N / 100) subrequests
+ * ```
+ *
+ * @packageDocumentation
+ */
+/**
+ * Minimal subset of `@cloudflare/workers-types`' `Queue` used by {@link sendInChunks}.
+ *
+ * Declared locally so consumers are not forced to depend on `@cloudflare/workers-types`. Only the
+ * batch-send operation the helper actually needs is modeled.
+ *
+ * @typeParam Body - Type of each message body enqueued onto this queue.
+ */
+export interface QueueLike<Body = unknown> {
+  /**
+   * Enqueue up to 100 messages in a single operation (one subrequest).
+   *
+   * @param messages - The message envelopes to enqueue; at most 100 per call, 256 KB per batch.
+   * @param options - Optional batch-level options, e.g. a `delaySeconds` applied to every message.
+   * @returns A promise that resolves once the batch is accepted. The resolved value is ignored, so a
+   *   real `Queue` binding (whose `sendBatch` resolves to a `QueueSendBatchResponse`) is assignable.
+   */
+  sendBatch: (messages: Iterable<QueueSendMessage<Body>>, options?: { delaySeconds?: number }) => Promise<unknown>;
+}
+/**
+ * A single message envelope passed to {@link QueueLike.sendBatch}.
+ *
+ * @typeParam Body - Type of the message body.
+ */
+export interface QueueSendMessage<Body = unknown> {
+  /** The message payload; structured-cloned by the Queues runtime. */
+  body: Body;
+  /** Optional content type hint (`'json'` by default for object bodies). */
+  contentType?: 'text' | 'bytes' | 'json' | 'v8';
+  /** Optional per-message delivery delay, in seconds. */
+  delaySeconds?: number;
+}
+/**
+ * The Cloudflare Queues hard limit on messages per {@link QueueLike.sendBatch} call.
+ */
+const MAX_BATCH_SIZE = 100;
+/**
+ * Split a list into fixed-size chunks (order preserving).
+ *
+ * @typeParam T - Element type.
+ * @param items - Source list.
+ * @param size - Maximum chunk length (assumed `>= 1`).
+ * @returns An array of chunks, each at most `size` long.
+ * @internal
+ */
+function chunk<T>(items: readonly T[], size: number): T[][] {
+  const result: T[][] = [];
+  for (let i = 0; i < items.length; i += size) {
+    result.push(items.slice(i, i + size));
+  }
+  return result;
+}
+/**
+ * Enqueue every item in `items` using batched sends so the producer's subrequest count stays
+ * bounded at `ceil(items.length / chunkSize)` rather than growing per item.
+ *
+ * Each element becomes one queue message (`{ body: item }`); wrap or map your rows into small,
+ * self-describing payloads (e.g. an id plus a discriminator) before calling. Keep each batch under
+ * the Queues 256 KB limit — with `chunkSize <= 100` and small id-shaped payloads this is not a
+ * concern, but large bodies may require a smaller `chunkSize`.
+ *
+ * Batches are sent sequentially so a mid-list failure surfaces promptly (the already-sent batches
+ * are durably enqueued; the throw lets the caller decide whether to retry the remainder). An empty
+ * `items` is a no-op.
+ *
+ * @typeParam Body - Type of each message body.
+ * @param queue - The producer binding to send onto.
+ * @param items - The full list of message bodies to enqueue; may be arbitrarily large.
+ * @param options - Tuning options.
+ * @param options.chunkSize - Messages per `sendBatch` call. Defaults to and is capped at 100 (the
+ *   Queues per-batch maximum); values below 1 are clamped to 1.
+ * @returns The number of `sendBatch` calls issued (i.e. subrequests spent), useful for asserting the
+ *   fan-out stayed bounded in tests.
+ * @example
+ * ```ts
+ * const batches = await sendInChunks(env.MY_QUEUE, ids);        // one send per 100 ids
+ * const batches = await sendInChunks(env.MY_QUEUE, rows, {      // custom batch size for larger bodies
+ *   chunkSize: 25,
+ * });
+ * ```
+ */
+export async function sendInChunks<Body>(
+  queue: QueueLike<Body>,
+  items: readonly Body[],
+  options?: { chunkSize?: number },
+): Promise<number> {
+  if (items.length === 0) {
+    return 0;
+  }
+  const rawChunkSize = options?.chunkSize ?? MAX_BATCH_SIZE;
+  const chunkSize = Math.min(
+    MAX_BATCH_SIZE,
+    Math.max(1, Math.trunc(Number.isNaN(rawChunkSize) ? MAX_BATCH_SIZE : rawChunkSize)),
+  );
+  const batches = chunk(items, chunkSize);
+  for (const batch of batches) {
+    await queue.sendBatch(batch.map((body) => ({ body })));
+  }
+  return batches.length;
+}