@rdlabo/workers-hono-kit 0.2.1 → 0.3.2

package/dist/firebase/firebase-verifier.d.ts

@@ -53,6 +53,21 @@ export interface FirebaseVerifier {
         uid: string;
         email?: string;
     } | null>;
+    /**
+     * Look up multiple user records by uid in as few requests as the backing service allows.
+     *
+     * Batched equivalent of {@link getUser}, intended to replace N single-uid lookups with a
+     * handful of requests.
+     *
+     * @param uids - The users' unique ids to look up.
+     * @returns The `uid`/`email` of every matching user. Uids that do not resolve to a user are
+     *   simply absent from the result (never `null` entries).
+     * @throws If the backing user-management service is not configured or the lookup fails.
+     */
+    getUsers(uids: string[]): Promise<{
+        uid: string;
+        email?: string;
+    }[]>;
     /**
      * Delete a user by uid.
      *

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

@@ -48,6 +48,17 @@ export declare class IdentityToolkit {
      * @internal
      */
     private getAccessToken;
+    /**
+     * Call the `accounts:lookup` endpoint for a single chunk of `localId`s.
+     *
+     * @param localIds - Up to {@link LOOKUP_CHUNK_SIZE} `localId`s to look up in one request.
+     * @param nowSeconds - The current Unix time in seconds, used for access-token caching.
+     * @returns The raw `users` entries returned by the endpoint (empty when the request is
+     *   unsuccessful or no matching users are returned).
+     * @throws If acquiring an access token fails.
+     * @internal
+     */
+    private lookupChunk;
     /**
      * Look up a user record by uid via the `accounts:lookup` endpoint.
      *
@@ -61,6 +72,24 @@ export declare class IdentityToolkit {
         uid: string;
         email?: string;
     } | null>;
+    /**
+     * Look up multiple user records by uid via the `accounts:lookup` endpoint.
+     *
+     * `uids` are chunked into groups of at most {@link LOOKUP_CHUNK_SIZE} (the maximum `localId`
+     * array size the endpoint accepts), issuing one `accounts:lookup` request per chunk. This lets
+     * callers replace N single-uid lookups with `ceil(N / LOOKUP_CHUNK_SIZE)` requests.
+     *
+     * @param uids - The users' unique ids (`localId`s) to look up.
+     * @param nowSeconds - The current Unix time in seconds, used for access-token caching.
+     * @returns The `uid`/`email` of every matching user. Uids Firebase does not recognize are
+     *   simply absent from the result (never `null` entries), so callers can treat "missing from
+     *   the result" as "not found/invalid".
+     * @throws If acquiring an access token fails.
+     */
+    lookupMany(uids: string[], nowSeconds: number): Promise<{
+        uid: string;
+        email?: string;
+    }[]>;
     /**
      * Delete a user by uid via the `accounts:delete` endpoint.
      *

package/dist/firebase/identity-toolkit.js

@@ -5,6 +5,8 @@ const TOKEN_URL = 'https://oauth2.googleapis.com/token';
 const IDENTITY_TOOLKIT = 'https://identitytoolkit.googleapis.com/v1';
 /** OAuth2 scopes required for Identity Toolkit account lookup and deletion. */
 const SCOPE = 'https://www.googleapis.com/auth/identitytoolkit https://www.googleapis.com/auth/firebase';
+/** Maximum number of `localId`s the `accounts:lookup` endpoint accepts in a single request. */
+const LOOKUP_CHUNK_SIZE = 100;
 /**
  * Minimal Google Identity Toolkit REST client for the user-management operations that token
  * verification does not cover: `accounts:lookup` (getUser) and `accounts:delete` (deleteUser).
@@ -71,27 +73,68 @@ export class IdentityToolkit {
         return json.access_token;
     }
     /**
-     * Look up a user record by uid via the `accounts:lookup` endpoint.
+     * Call the `accounts:lookup` endpoint for a single chunk of `localId`s.
      *
-     * @param uid - The user's unique id (`localId`).
+     * @param localIds - Up to {@link LOOKUP_CHUNK_SIZE} `localId`s to look up in one request.
      * @param nowSeconds - The current Unix time in seconds, used for access-token caching.
-     * @returns The user's `uid` and optional `email`, or `null` when the request is unsuccessful
-     *   or no matching user is returned.
+     * @returns The raw `users` entries returned by the endpoint (empty when the request is
+     *   unsuccessful or no matching users are returned).
      * @throws If acquiring an access token fails.
+     * @internal
      */
-    async lookup(uid, nowSeconds) {
+    async lookupChunk(localIds, nowSeconds) {
         const token = await this.getAccessToken(nowSeconds);
         const res = await fetch(`${IDENTITY_TOOLKIT}/projects/${this.sa.project_id}/accounts:lookup`, {
             method: 'POST',
             headers: { authorization: `Bearer ${token}`, 'content-type': 'application/json' },
-            body: JSON.stringify({ localId: [uid] }),
+            body: JSON.stringify({ localId: localIds }),
         });
         if (!res.ok) {
-            return null;
+            return [];
         }
         const json = (await res.json());
-        const user = json.users?.[0];
-        return user ? { uid: user.localId, email: user.email } : null;
+        return json.users ?? [];
+    }
+    /**
+     * Look up a user record by uid via the `accounts:lookup` endpoint.
+     *
+     * @param uid - The user's unique id (`localId`).
+     * @param nowSeconds - The current Unix time in seconds, used for access-token caching.
+     * @returns The user's `uid` and optional `email`, or `null` when the request is unsuccessful
+     *   or no matching user is returned.
+     * @throws If acquiring an access token fails.
+     */
+    async lookup(uid, nowSeconds) {
+        const users = await this.lookupChunk([uid], nowSeconds);
+        return users.length > 0 ? { uid: users[0].localId, email: users[0].email } : null;
+    }
+    /**
+     * Look up multiple user records by uid via the `accounts:lookup` endpoint.
+     *
+     * `uids` are chunked into groups of at most {@link LOOKUP_CHUNK_SIZE} (the maximum `localId`
+     * array size the endpoint accepts), issuing one `accounts:lookup` request per chunk. This lets
+     * callers replace N single-uid lookups with `ceil(N / LOOKUP_CHUNK_SIZE)` requests.
+     *
+     * @param uids - The users' unique ids (`localId`s) to look up.
+     * @param nowSeconds - The current Unix time in seconds, used for access-token caching.
+     * @returns The `uid`/`email` of every matching user. Uids Firebase does not recognize are
+     *   simply absent from the result (never `null` entries), so callers can treat "missing from
+     *   the result" as "not found/invalid".
+     * @throws If acquiring an access token fails.
+     */
+    async lookupMany(uids, nowSeconds) {
+        if (uids.length === 0) {
+            return [];
+        }
+        const results = [];
+        for (let i = 0; i < uids.length; i += LOOKUP_CHUNK_SIZE) {
+            const chunk = uids.slice(i, i + LOOKUP_CHUNK_SIZE);
+            const users = await this.lookupChunk(chunk, nowSeconds);
+            for (const user of users) {
+                results.push({ uid: user.localId, email: user.email });
+            }
+        }
+        return results;
     }
     /**
      * Delete a user by uid via the `accounts:delete` endpoint.

package/dist/firebase/jose-firebase-verifier.d.ts

@@ -85,6 +85,21 @@ export declare class JoseFirebaseVerifier implements FirebaseVerifier {
         uid: string;
         email?: string;
     } | null>;
+    /**
+     * Look up multiple user records by uid via the Identity Toolkit REST API.
+     *
+     * Batches the lookups into `ceil(uids.length / 100)` `accounts:lookup` requests instead of
+     * one request per uid.
+     *
+     * @param uids - The users' unique ids to look up.
+     * @returns The `uid`/`email` of every matching user. Uids Firebase does not recognize are
+     *   simply absent from the result (never `null` entries).
+     * @throws If no Identity Toolkit client was configured on this verifier.
+     */
+    getUsers(uids: string[]): Promise<{
+        uid: string;
+        email?: string;
+    }[]>;
     /**
      * Delete a user by uid via the Identity Toolkit REST API.
      *

package/dist/firebase/jose-firebase-verifier.js

@@ -88,6 +88,23 @@ export class JoseFirebaseVerifier {
         }
         return this.opts.identity.lookup(uid, this.nowSeconds());
     }
+    /**
+     * Look up multiple user records by uid via the Identity Toolkit REST API.
+     *
+     * Batches the lookups into `ceil(uids.length / 100)` `accounts:lookup` requests instead of
+     * one request per uid.
+     *
+     * @param uids - The users' unique ids to look up.
+     * @returns The `uid`/`email` of every matching user. Uids Firebase does not recognize are
+     *   simply absent from the result (never `null` entries).
+     * @throws If no Identity Toolkit client was configured on this verifier.
+     */
+    async getUsers(uids) {
+        if (!this.opts.identity) {
+            throw new Error('Identity Toolkit not configured');
+        }
+        return this.opts.identity.lookupMany(uids, this.nowSeconds());
+    }
     /**
      * Delete a user by uid via the Identity Toolkit REST API.
      *

package/dist/index.d.ts

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

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

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

package/dist/queue/send.d.ts

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

@@ -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/dist/testing/fakes.d.ts

@@ -43,6 +43,16 @@ export declare class FakeFirebaseVerifier implements FirebaseVerifier {
         uid: string;
         email?: string;
     } | null>;
+    /**
+     * Return minimal user records echoing each requested UID.
+     *
+     * @param uids - UIDs to look up.
+     * @returns One `{ uid }` entry per requested uid (never omits any, in this fake).
+     */
+    getUsers(uids: string[]): Promise<{
+        uid: string;
+        email?: string;
+    }[]>;
     /**
      * Record a user deletion by appending the UID to {@link FakeFirebaseVerifier.deleted}.
      *

package/dist/testing/fakes.js

@@ -48,6 +48,15 @@ export class FakeFirebaseVerifier {
     async getUser(uid) {
         return { uid };
     }
+    /**
+     * Return minimal user records echoing each requested UID.
+     *
+     * @param uids - UIDs to look up.
+     * @returns One `{ uid }` entry per requested uid (never omits any, in this fake).
+     */
+    async getUsers(uids) {
+        return uids.map((uid) => ({ uid }));
+    }
     /**
      * Record a user deletion by appending the UID to {@link FakeFirebaseVerifier.deleted}.
      *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rdlabo/workers-hono-kit",
-  "version": "0.2.1",
+  "version": "0.3.2",
   "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

@@ -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/firebase/firebase-verifier.ts

@@ -51,6 +51,18 @@ export interface FirebaseVerifier {
    * @throws If the backing user-management service is not configured or the lookup fails.
    */
   getUser(uid: string): Promise<{ uid: string; email?: string } | null>;
+  /**
+   * Look up multiple user records by uid in as few requests as the backing service allows.
+   *
+   * Batched equivalent of {@link getUser}, intended to replace N single-uid lookups with a
+   * handful of requests.
+   *
+   * @param uids - The users' unique ids to look up.
+   * @returns The `uid`/`email` of every matching user. Uids that do not resolve to a user are
+   *   simply absent from the result (never `null` entries).
+   * @throws If the backing user-management service is not configured or the lookup fails.
+   */
+  getUsers(uids: string[]): Promise<{ uid: string; email?: string }[]>;
   /**
    * Delete a user by uid.
    *

package/src/firebase/identity-toolkit.ts

@@ -21,6 +21,8 @@ const TOKEN_URL = 'https://oauth2.googleapis.com/token';
 const IDENTITY_TOOLKIT = 'https://identitytoolkit.googleapis.com/v1';
 /** OAuth2 scopes required for Identity Toolkit account lookup and deletion. */
 const SCOPE = 'https://www.googleapis.com/auth/identitytoolkit https://www.googleapis.com/auth/firebase';
+/** Maximum number of `localId`s the `accounts:lookup` endpoint accepts in a single request. */
+const LOOKUP_CHUNK_SIZE = 100;
 
 /**
  * Minimal Google Identity Toolkit REST client for the user-management operations that token
@@ -89,27 +91,70 @@ export class IdentityToolkit {
   }
 
   /**
-   * Look up a user record by uid via the `accounts:lookup` endpoint.
+   * Call the `accounts:lookup` endpoint for a single chunk of `localId`s.
    *
-   * @param uid - The user's unique id (`localId`).
+   * @param localIds - Up to {@link LOOKUP_CHUNK_SIZE} `localId`s to look up in one request.
    * @param nowSeconds - The current Unix time in seconds, used for access-token caching.
-   * @returns The user's `uid` and optional `email`, or `null` when the request is unsuccessful
-   *   or no matching user is returned.
+   * @returns The raw `users` entries returned by the endpoint (empty when the request is
+   *   unsuccessful or no matching users are returned).
    * @throws If acquiring an access token fails.
+   * @internal
    */
-  async lookup(uid: string, nowSeconds: number): Promise<{ uid: string; email?: string } | null> {
+  private async lookupChunk(localIds: string[], nowSeconds: number): Promise<{ localId: string; email?: string }[]> {
     const token = await this.getAccessToken(nowSeconds);
     const res = await fetch(`${IDENTITY_TOOLKIT}/projects/${this.sa.project_id}/accounts:lookup`, {
       method: 'POST',
       headers: { authorization: `Bearer ${token}`, 'content-type': 'application/json' },
-      body: JSON.stringify({ localId: [uid] }),
+      body: JSON.stringify({ localId: localIds }),
     });
     if (!res.ok) {
-      return null;
+      return [];
     }
     const json = (await res.json()) as { users?: { localId: string; email?: string }[] };
-    const user = json.users?.[0];
-    return user ? { uid: user.localId, email: user.email } : null;
+    return json.users ?? [];
+  }
+
+  /**
+   * Look up a user record by uid via the `accounts:lookup` endpoint.
+   *
+   * @param uid - The user's unique id (`localId`).
+   * @param nowSeconds - The current Unix time in seconds, used for access-token caching.
+   * @returns The user's `uid` and optional `email`, or `null` when the request is unsuccessful
+   *   or no matching user is returned.
+   * @throws If acquiring an access token fails.
+   */
+  async lookup(uid: string, nowSeconds: number): Promise<{ uid: string; email?: string } | null> {
+    const users = await this.lookupChunk([uid], nowSeconds);
+    return users.length > 0 ? { uid: users[0].localId, email: users[0].email } : null;
+  }
+
+  /**
+   * Look up multiple user records by uid via the `accounts:lookup` endpoint.
+   *
+   * `uids` are chunked into groups of at most {@link LOOKUP_CHUNK_SIZE} (the maximum `localId`
+   * array size the endpoint accepts), issuing one `accounts:lookup` request per chunk. This lets
+   * callers replace N single-uid lookups with `ceil(N / LOOKUP_CHUNK_SIZE)` requests.
+   *
+   * @param uids - The users' unique ids (`localId`s) to look up.
+   * @param nowSeconds - The current Unix time in seconds, used for access-token caching.
+   * @returns The `uid`/`email` of every matching user. Uids Firebase does not recognize are
+   *   simply absent from the result (never `null` entries), so callers can treat "missing from
+   *   the result" as "not found/invalid".
+   * @throws If acquiring an access token fails.
+   */
+  async lookupMany(uids: string[], nowSeconds: number): Promise<{ uid: string; email?: string }[]> {
+    if (uids.length === 0) {
+      return [];
+    }
+    const results: { uid: string; email?: string }[] = [];
+    for (let i = 0; i < uids.length; i += LOOKUP_CHUNK_SIZE) {
+      const chunk = uids.slice(i, i + LOOKUP_CHUNK_SIZE);
+      const users = await this.lookupChunk(chunk, nowSeconds);
+      for (const user of users) {
+        results.push({ uid: user.localId, email: user.email });
+      }
+    }
+    return results;
   }
 
   /**

package/src/firebase/jose-firebase-verifier.ts

@@ -115,6 +115,24 @@ export class JoseFirebaseVerifier implements FirebaseVerifier {
     return this.opts.identity.lookup(uid, this.nowSeconds());
   }
 
+  /**
+   * Look up multiple user records by uid via the Identity Toolkit REST API.
+   *
+   * Batches the lookups into `ceil(uids.length / 100)` `accounts:lookup` requests instead of
+   * one request per uid.
+   *
+   * @param uids - The users' unique ids to look up.
+   * @returns The `uid`/`email` of every matching user. Uids Firebase does not recognize are
+   *   simply absent from the result (never `null` entries).
+   * @throws If no Identity Toolkit client was configured on this verifier.
+   */
+  async getUsers(uids: string[]): Promise<{ uid: string; email?: string }[]> {
+    if (!this.opts.identity) {
+      throw new Error('Identity Toolkit not configured');
+    }
+    return this.opts.identity.lookupMany(uids, this.nowSeconds());
+  }
+
   /**
    * Delete a user by uid via the Identity Toolkit REST API.
    *

package/src/index.ts

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

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

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

package/src/testing/fakes.ts

@@ -56,6 +56,16 @@ export class FakeFirebaseVerifier implements FirebaseVerifier {
     return { uid };
   }
 
+  /**
+   * Return minimal user records echoing each requested UID.
+   *
+   * @param uids - UIDs to look up.
+   * @returns One `{ uid }` entry per requested uid (never omits any, in this fake).
+   */
+  async getUsers(uids: string[]): Promise<{ uid: string; email?: string }[]> {
+    return uids.map((uid) => ({ uid }));
+  }
+
   /**
    * Record a user deletion by appending the UID to {@link FakeFirebaseVerifier.deleted}.
    *