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

@rdlabo/workers-hono-kit 0.2.0 → 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 (104) hide show

package/README.md +126 -11
package/dist/ai/gateway.d.ts +54 -16
package/dist/ai/gateway.js +37 -12
package/dist/aws/cloudfront.d.ts +23 -5
package/dist/aws/cloudfront.js +45 -6
package/dist/aws/secrets-manager.d.ts +38 -4
package/dist/aws/secrets-manager.js +48 -3
package/dist/cache/kv-cache.d.ts +173 -10
package/dist/cache/kv-cache.js +139 -7
package/dist/db/connection.d.ts +56 -14
package/dist/db/connection.js +39 -13
package/dist/db/database.d.ts +159 -23
package/dist/db/database.js +49 -5
package/dist/db/index.d.ts +11 -0
package/dist/db/index.js +11 -2
package/dist/db/jst.d.ts +89 -6
package/dist/db/jst.js +89 -23
package/dist/db/orm-config.d.ts +61 -19
package/dist/db/orm-config.js +43 -14
package/dist/db/retry.d.ts +25 -3
package/dist/db/retry.js +25 -3
package/dist/db/write-result.d.ts +27 -4
package/dist/db/write-result.js +22 -1
package/dist/firebase/firebase-verifier.d.ts +53 -4
package/dist/firebase/identity-toolkit.d.ts +54 -5
package/dist/firebase/identity-toolkit.js +51 -0
package/dist/firebase/jose-firebase-verifier.d.ts +79 -7
package/dist/firebase/jose-firebase-verifier.js +68 -7
package/dist/firebase/remote-verifier.d.ts +42 -4
package/dist/firebase/remote-verifier.js +58 -9
package/dist/http/app-env.d.ts +41 -8
package/dist/http/app-env.js +38 -8
package/dist/http/app-info.d.ts +25 -3
package/dist/http/app-info.js +16 -2
package/dist/http/http-status.d.ts +12 -3
package/dist/http/http-status.js +12 -3
package/dist/http/nest-error.d.ts +90 -29
package/dist/http/nest-error.js +59 -18
package/dist/http/user-protocol.d.ts +23 -3
package/dist/http/user-protocol.js +14 -2
package/dist/index.d.ts +15 -0
package/dist/index.js +14 -3
package/dist/middleware/auth.d.ts +74 -13
package/dist/middleware/auth.js +30 -6
package/dist/middleware/finalize-response.d.ts +30 -0
package/dist/middleware/finalize-response.js +41 -12
package/dist/middleware/validation.d.ts +83 -9
package/dist/middleware/validation.js +52 -9
package/dist/middleware/zod-coerce.d.ts +56 -2
package/dist/middleware/zod-coerce.js +68 -9
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/dist/stripe/client.d.ts +46 -9
package/dist/stripe/client.js +41 -3
package/dist/testing/auth.d.ts +58 -10
package/dist/testing/auth.js +58 -10
package/dist/testing/configurable-fake.d.ts +20 -9
package/dist/testing/configurable-fake.js +23 -11
package/dist/testing/db.d.ts +81 -12
package/dist/testing/db.js +23 -1
package/dist/testing/fakes.d.ts +77 -9
package/dist/testing/fakes.js +69 -7
package/dist/testing/index.d.ts +7 -0
package/dist/testing/index.js +10 -5
package/dist/testing/stripe-fixtures.d.ts +93 -3
package/dist/testing/stripe-fixtures.js +93 -3
package/package.json +3 -2
package/scripts/check-subrequest-fanout.mjs +86 -0
package/src/ai/gateway.ts +66 -27
package/src/aws/cloudfront.ts +46 -6
package/src/aws/secrets-manager.ts +56 -7
package/src/cache/kv-cache.ts +194 -12
package/src/db/connection.ts +56 -14
package/src/db/database.ts +160 -24
package/src/db/index.ts +11 -2
package/src/db/jst.ts +89 -23
package/src/db/orm-config.ts +61 -19
package/src/db/retry.ts +25 -3
package/src/db/write-result.ts +27 -4
package/src/firebase/firebase-verifier.ts +53 -4
package/src/firebase/identity-toolkit.ts +57 -5
package/src/firebase/jose-firebase-verifier.ts +79 -9
package/src/firebase/remote-verifier.ts +58 -9
package/src/http/app-env.ts +41 -8
package/src/http/app-info.ts +25 -3
package/src/http/http-status.ts +12 -3
package/src/http/nest-error.ts +106 -37
package/src/http/user-protocol.ts +23 -3
package/src/index.ts +17 -3
package/src/middleware/auth.ts +77 -15
package/src/middleware/finalize-response.ts +41 -12
package/src/middleware/validation.ts +89 -15
package/src/middleware/zod-coerce.ts +68 -9
package/src/queue/consumer.ts +146 -0
package/src/queue/send.ts +129 -0
package/src/stripe/client.ts +46 -9
package/src/testing/auth.ts +58 -10
package/src/testing/configurable-fake.ts +23 -11
package/src/testing/db.ts +82 -13
package/src/testing/fakes.ts +77 -9
package/src/testing/index.ts +10 -5
package/src/testing/stripe-fixtures.ts +93 -3

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/dist/stripe/client.d.ts CHANGED Viewed

@@ -1,19 +1,56 @@
 import Stripe from 'stripe';
 /**
- * Stripe クライアント生成（フリート共通 = receptray/tipsys hono）。Cloudflare Workers には Node の
- * http スタックが無いため、Stripe SDK の fetch ベース HttpClient を使う。
- *
- * `apiVersion` は **任意**: 各 repo の `/api`（NestJS）と挙動を一致させるため、固定したい repo は
- * 渡し（例 tipsys は `'2024-04-10'`）、SDK 既定で良い repo は省く（例 receptray）。
+ * Options for {@link createStripeClient}.
  */
 export interface CreateStripeClientOptions {
-    /** 固定する Stripe API バージョン。省略すると SDK 既定。 */
+    /**
+     * Stripe API version to pin the client to. When omitted, the SDK's built-in default is used.
+     * Pin it when you need stable, reproducible API behavior independent of SDK upgrades.
+     */
     apiVersion?: string;
 }
+/**
+ * Create a Stripe client configured to run on Cloudflare Workers.
+ *
+ * @remarks
+ * Workers has no Node.js `http` stack, so the client is built with `Stripe.createFetchHttpClient()`
+ * (a `fetch`-based HTTP client) instead of the SDK's default Node transport.
+ *
+ * @param secret - Stripe secret API key.
+ * @param options - Optional client configuration; see {@link CreateStripeClientOptions}.
+ * @returns A configured {@link Stripe} instance.
+ * @throws Error when `secret` is empty.
+ * @example
+ * ```ts
+ * const stripe = createStripeClient(env.STRIPE_SECRET, { apiVersion: '2024-04-10' });
+ * const customer = await stripe.customers.retrieve(customerId);
+ * ```
+ */
 export declare function createStripeClient(secret: string, options?: CreateStripeClientOptions): Stripe;
 /**
- * Webhook 署名の検証。Workers では同期版 `constructEvent` が使えない（SubtleCrypto が非同期）ため
- * `constructEventAsync` + `SubtleCryptoProvider` を使う。`secret` は署名検証には無関係だが、検証用の
- * クライアント生成に必要（API コールはしない）。
+ * Verify a Stripe webhook signature and return the parsed event.
+ *
+ * @remarks
+ * Uses `constructEventAsync` together with `Stripe.createSubtleCryptoProvider()` because the Workers
+ * crypto API (SubtleCrypto) is asynchronous and the synchronous `constructEvent` is unavailable.
+ * The `secret` is not used by signature verification itself, but a client must be constructed to
+ * perform the check; no Stripe API call is made.
+ *
+ * @param secret - Stripe secret API key, used only to construct the verifying client.
+ * @param webhookSecret - Endpoint signing secret used to validate the signature.
+ * @param payload - Raw request body exactly as received (string or `ArrayBuffer`).
+ * @param signature - Value of the `Stripe-Signature` request header.
+ * @returns The verified {@link Stripe.Event}.
+ * @throws Error when `webhookSecret` is empty, or when `secret` is empty (the verifying client cannot be constructed).
+ * @throws Stripe.errors.StripeSignatureVerificationError when the signature does not match.
+ * @example
+ * ```ts
+ * const event = await verifyStripeWebhook(
+ *   env.STRIPE_SECRET,
+ *   env.STRIPE_WEBHOOK_SECRET,
+ *   await request.text(),
+ *   request.headers.get('stripe-signature')!,
+ * );
+ * ```
  */
 export declare function verifyStripeWebhook(secret: string, webhookSecret: string, payload: string | ArrayBuffer, signature: string): Promise<Stripe.Event>;

package/dist/stripe/client.js CHANGED Viewed

@@ -1,4 +1,21 @@
 import Stripe from 'stripe';
+/**
+ * Create a Stripe client configured to run on Cloudflare Workers.
+ *
+ * @remarks
+ * Workers has no Node.js `http` stack, so the client is built with `Stripe.createFetchHttpClient()`
+ * (a `fetch`-based HTTP client) instead of the SDK's default Node transport.
+ *
+ * @param secret - Stripe secret API key.
+ * @param options - Optional client configuration; see {@link CreateStripeClientOptions}.
+ * @returns A configured {@link Stripe} instance.
+ * @throws Error when `secret` is empty.
+ * @example
+ * ```ts
+ * const stripe = createStripeClient(env.STRIPE_SECRET, { apiVersion: '2024-04-10' });
+ * const customer = await stripe.customers.retrieve(customerId);
+ * ```
+ */
 export function createStripeClient(secret, options = {}) {
     if (!secret) {
         throw new Error('Stripe secret is not set');
@@ -10,9 +27,30 @@ export function createStripeClient(secret, options = {}) {
     return new Stripe(secret, config);
 }
 /**
- * Webhook 署名の検証。Workers では同期版 `constructEvent` が使えない（SubtleCrypto が非同期）ため
- * `constructEventAsync` + `SubtleCryptoProvider` を使う。`secret` は署名検証には無関係だが、検証用の
- * クライアント生成に必要（API コールはしない）。
+ * Verify a Stripe webhook signature and return the parsed event.
+ *
+ * @remarks
+ * Uses `constructEventAsync` together with `Stripe.createSubtleCryptoProvider()` because the Workers
+ * crypto API (SubtleCrypto) is asynchronous and the synchronous `constructEvent` is unavailable.
+ * The `secret` is not used by signature verification itself, but a client must be constructed to
+ * perform the check; no Stripe API call is made.
+ *
+ * @param secret - Stripe secret API key, used only to construct the verifying client.
+ * @param webhookSecret - Endpoint signing secret used to validate the signature.
+ * @param payload - Raw request body exactly as received (string or `ArrayBuffer`).
+ * @param signature - Value of the `Stripe-Signature` request header.
+ * @returns The verified {@link Stripe.Event}.
+ * @throws Error when `webhookSecret` is empty, or when `secret` is empty (the verifying client cannot be constructed).
+ * @throws Stripe.errors.StripeSignatureVerificationError when the signature does not match.
+ * @example
+ * ```ts
+ * const event = await verifyStripeWebhook(
+ *   env.STRIPE_SECRET,
+ *   env.STRIPE_WEBHOOK_SECRET,
+ *   await request.text(),
+ *   request.headers.get('stripe-signature')!,
+ * );
+ * ```
  */
 export function verifyStripeWebhook(secret, webhookSecret, payload, signature) {
     if (!webhookSecret) {

package/dist/testing/auth.d.ts CHANGED Viewed

@@ -2,11 +2,27 @@ import type { Pool } from 'mysql2/promise';
 import type { DecodedIdToken } from '../firebase/firebase-verifier.js';
 import type { FakeFirebaseVerifier } from './fakes.js';
 /**
- * app interceptor 互換の認証ヘッダ（`x-amz-security-token` + `x-amz-meta-*`）を組む。
- * fleet 全 hono repo の route spec で同形に重複していたものを集約。
+ * Build authentication headers compatible with the client interceptor convention
+ * (`x-amz-security-token` + `x-amz-meta-*`).
  *
- * - `version` は `app_version`(varchar(10)) に入るため 10 文字以内。
- * - `contentType: null` を渡すと content-type を付けない（GET 等）。
+ * Consolidates the identically-shaped header boilerplate that route specs tend to duplicate.
+ *
+ * @remarks
+ * `version` is persisted into an `app_version` column (`varchar(10)`), so keep it to 10 characters
+ * or fewer. Passing `contentType: null` omits the `content-type` header entirely (e.g. for GET requests).
+ *
+ * @param token - Security token placed in the `x-amz-security-token` header.
+ * @param opts - Optional overrides.
+ * @param opts.version - App version for `x-amz-meta-version` (defaults to `'1.0.0'`).
+ * @param opts.uuid - Device/client UUID for `x-amz-meta-uuid` (defaults to `'test-uuid'`).
+ * @param opts.contentType - Content type; defaults to `'application/json'`. Pass `null` to omit the header.
+ * @returns A plain header record suitable for `fetch`/`app.request` calls.
+ * @example
+ * ```ts
+ * const res = await app.request('/me', { headers: authHeaders(token) });
+ * // GET without a content-type header:
+ * await app.request('/items', { headers: authHeaders(token, { contentType: null }) });
+ * ```
  */
 export declare function authHeaders(token: string, opts?: {
     version?: string;
@@ -14,15 +30,47 @@ export declare function authHeaders(token: string, opts?: {
     contentType?: string | null;
 }): Record<string, string>;
 /**
- * fake firebase にトークンを登録するだけの薄いヘルパ（DB を触らない）。戻り値はトークン。
- * `users` テーブル形が repo 固有（例: airlec は email 主）で provisionUser が合わない場合に使う。
+ * Register a token on a fake Firebase verifier without touching the database.
+ *
+ * Use this when {@link provisionUser} does not fit because the project's `users` table has a
+ * non-conventional shape (for example, keyed by email rather than `firebase_uid`); pair it with a
+ * project-specific provisioning step.
+ *
+ * @param firebase - In-memory verifier to register the token on.
+ * @param uid - Firebase UID associated with the token.
+ * @param record - Additional decoded-token fields to merge in (e.g. `email`).
+ * @param token - Token string to register (defaults to `` `tok-${uid}` ``).
+ * @returns The registered token string.
+ * @example
+ * ```ts
+ * const token = registerFirebaseToken(firebase, 'uid-1', { email: 'a@example.com' });
+ * const res = await app.request('/me', { headers: authHeaders(token) });
+ * ```
  */
 export declare function registerFirebaseToken(firebase: FakeFirebaseVerifier, uid: string, record?: Partial<DecodedIdToken>, token?: string): string;
 /**
- * fake firebase にトークンを登録し、`users(firebase_uid)` 行を用意して userId を返す。
- * `users(id, firebase_uid, agree)` の fleet 共通形を前提（foodlabel/receptray など）。同 uid の
- * 既存行があれば再利用する（冪等）。users テーブル形が異なる repo は registerFirebaseToken + 独自
- * provision を使う。
+ * Register a token on a fake Firebase verifier and ensure a matching `users` row exists, returning
+ * its id.
+ *
+ * @remarks
+ * Assumes a conventional `users(id, firebase_uid, agree)` table. The operation is idempotent: if a
+ * row with the same `firebase_uid` already exists it is reused rather than re-inserted. For projects
+ * whose `users` table has a different shape, use {@link registerFirebaseToken} plus project-specific
+ * provisioning instead.
+ *
+ * @param pool - mysql2 pool connected to the test database.
+ * @param firebase - In-memory verifier to register the token on.
+ * @param opts - Provisioning options.
+ * @param opts.uid - Firebase UID for the user.
+ * @param opts.token - Token string to register (defaults to `` `tok-${uid}` ``).
+ * @param opts.agree - Value for the `agree` column on insert (defaults to `1`).
+ * @param opts.email - Optional email merged into the decoded token record.
+ * @returns The resolved `userId`, along with the `uid` and registered `token`.
+ * @example
+ * ```ts
+ * const { userId, token } = await provisionUser(pool, firebase, { uid: 'uid-1' });
+ * const res = await app.request('/me', { headers: authHeaders(token) });
+ * ```
  */
 export declare function provisionUser(pool: Pool, firebase: FakeFirebaseVerifier, opts: {
     uid: string;

package/dist/testing/auth.js CHANGED Viewed

@@ -1,9 +1,25 @@
 /**
- * app interceptor 互換の認証ヘッダ（`x-amz-security-token` + `x-amz-meta-*`）を組む。
- * fleet 全 hono repo の route spec で同形に重複していたものを集約。
+ * Build authentication headers compatible with the client interceptor convention
+ * (`x-amz-security-token` + `x-amz-meta-*`).
  *
- * - `version` は `app_version`(varchar(10)) に入るため 10 文字以内。
- * - `contentType: null` を渡すと content-type を付けない（GET 等）。
+ * Consolidates the identically-shaped header boilerplate that route specs tend to duplicate.
+ *
+ * @remarks
+ * `version` is persisted into an `app_version` column (`varchar(10)`), so keep it to 10 characters
+ * or fewer. Passing `contentType: null` omits the `content-type` header entirely (e.g. for GET requests).
+ *
+ * @param token - Security token placed in the `x-amz-security-token` header.
+ * @param opts - Optional overrides.
+ * @param opts.version - App version for `x-amz-meta-version` (defaults to `'1.0.0'`).
+ * @param opts.uuid - Device/client UUID for `x-amz-meta-uuid` (defaults to `'test-uuid'`).
+ * @param opts.contentType - Content type; defaults to `'application/json'`. Pass `null` to omit the header.
+ * @returns A plain header record suitable for `fetch`/`app.request` calls.
+ * @example
+ * ```ts
+ * const res = await app.request('/me', { headers: authHeaders(token) });
+ * // GET without a content-type header:
+ * await app.request('/items', { headers: authHeaders(token, { contentType: null }) });
+ * ```
  */
 export function authHeaders(token, opts = {}) {
     const headers = {
@@ -17,18 +33,50 @@ export function authHeaders(token, opts = {}) {
     return headers;
 }
 /**
- * fake firebase にトークンを登録するだけの薄いヘルパ（DB を触らない）。戻り値はトークン。
- * `users` テーブル形が repo 固有（例: airlec は email 主）で provisionUser が合わない場合に使う。
+ * Register a token on a fake Firebase verifier without touching the database.
+ *
+ * Use this when {@link provisionUser} does not fit because the project's `users` table has a
+ * non-conventional shape (for example, keyed by email rather than `firebase_uid`); pair it with a
+ * project-specific provisioning step.
+ *
+ * @param firebase - In-memory verifier to register the token on.
+ * @param uid - Firebase UID associated with the token.
+ * @param record - Additional decoded-token fields to merge in (e.g. `email`).
+ * @param token - Token string to register (defaults to `` `tok-${uid}` ``).
+ * @returns The registered token string.
+ * @example
+ * ```ts
+ * const token = registerFirebaseToken(firebase, 'uid-1', { email: 'a@example.com' });
+ * const res = await app.request('/me', { headers: authHeaders(token) });
+ * ```
  */
 export function registerFirebaseToken(firebase, uid, record = {}, token = `tok-${uid}`) {
     firebase.register(token, { uid, ...record });
     return token;
 }
 /**
- * fake firebase にトークンを登録し、`users(firebase_uid)` 行を用意して userId を返す。
- * `users(id, firebase_uid, agree)` の fleet 共通形を前提（foodlabel/receptray など）。同 uid の
- * 既存行があれば再利用する（冪等）。users テーブル形が異なる repo は registerFirebaseToken + 独自
- * provision を使う。
+ * Register a token on a fake Firebase verifier and ensure a matching `users` row exists, returning
+ * its id.
+ *
+ * @remarks
+ * Assumes a conventional `users(id, firebase_uid, agree)` table. The operation is idempotent: if a
+ * row with the same `firebase_uid` already exists it is reused rather than re-inserted. For projects
+ * whose `users` table has a different shape, use {@link registerFirebaseToken} plus project-specific
+ * provisioning instead.
+ *
+ * @param pool - mysql2 pool connected to the test database.
+ * @param firebase - In-memory verifier to register the token on.
+ * @param opts - Provisioning options.
+ * @param opts.uid - Firebase UID for the user.
+ * @param opts.token - Token string to register (defaults to `` `tok-${uid}` ``).
+ * @param opts.agree - Value for the `agree` column on insert (defaults to `1`).
+ * @param opts.email - Optional email merged into the decoded token record.
+ * @returns The resolved `userId`, along with the `uid` and registered `token`.
+ * @example
+ * ```ts
+ * const { userId, token } = await provisionUser(pool, firebase, { uid: 'uid-1' });
+ * const res = await app.request('/me', { headers: authHeaders(token) });
+ * ```
  */
 export async function provisionUser(pool, firebase, opts) {
     const token = registerFirebaseToken(firebase, opts.uid, opts.email ? { email: opts.email } : {}, opts.token);

package/dist/testing/configurable-fake.d.ts CHANGED Viewed

@@ -1,14 +1,25 @@
 /**
- * 部分実装から test double を作る。設定済みメソッドはそのまま、未設定メソッドを呼ぶと
- * `${name}.${method} not configured` で明示的に失敗する。
+ * Build a test double from a partial implementation: configured members are returned as-is, while
+ * calling any unconfigured member fails explicitly with `` `${name}.${method} not configured` ``.
  *
- * 各 repo の Fake*Gateway に散っていた「`Partial<impl>` を受け取り、未設定なら throw する手書き
- * クラス」の定型を一本化する。interface がドメインごとに異なる gateway（Stripe 等）でも、これで
- * 1 行で必要メソッドだけ差した fake を作れる:
+ * @remarks
+ * Replaces the hand-written "accept a `Partial<impl>` and throw on anything unset" fake classes that
+ * tend to proliferate per gateway. Because gateway interfaces differ by domain (Stripe, etc.), this
+ * lets you stub only the members a given test exercises in a single line.
  *
- *   const stripe = configurableFake<StripeGateway>(
- *     { listPaymentIntents: async () => fakeApiList([fakePaymentIntent()]) },
- *     'FakeStripeGateway',
- *   );
+ * @typeParam T - The interface being faked.
+ * @param impl - Partial implementation; only the members the test needs.
+ * @param name - Label used in the "not configured" error message (defaults to `'fake'`).
+ * @returns A proxy typed as `T` that delegates to `impl` and throws on unconfigured members.
+ * @throws Error `` `${name}.${method} not configured` `` when an unconfigured string-keyed member is called.
+ * @example
+ * ```ts
+ * const stripe = configurableFake<StripeGateway>(
+ *   { listPaymentIntents: async () => fakeApiList([fakePaymentIntent()]) },
+ *   'FakeStripeGateway',
+ * );
+ * await stripe.listPaymentIntents(); // ok
+ * await stripe.cancelPaymentIntent('pi_1'); // throws: FakeStripeGateway.cancelPaymentIntent not configured
+ * ```
  */
 export declare function configurableFake<T extends object>(impl: Partial<T>, name?: string): T;

package/dist/testing/configurable-fake.js CHANGED Viewed

@@ -1,15 +1,26 @@
 /**
- * 部分実装から test double を作る。設定済みメソッドはそのまま、未設定メソッドを呼ぶと
- * `${name}.${method} not configured` で明示的に失敗する。
+ * Build a test double from a partial implementation: configured members are returned as-is, while
+ * calling any unconfigured member fails explicitly with `` `${name}.${method} not configured` ``.
  *
- * 各 repo の Fake*Gateway に散っていた「`Partial<impl>` を受け取り、未設定なら throw する手書き
- * クラス」の定型を一本化する。interface がドメインごとに異なる gateway（Stripe 等）でも、これで
- * 1 行で必要メソッドだけ差した fake を作れる:
+ * @remarks
+ * Replaces the hand-written "accept a `Partial<impl>` and throw on anything unset" fake classes that
+ * tend to proliferate per gateway. Because gateway interfaces differ by domain (Stripe, etc.), this
+ * lets you stub only the members a given test exercises in a single line.
  *
- *   const stripe = configurableFake<StripeGateway>(
- *     { listPaymentIntents: async () => fakeApiList([fakePaymentIntent()]) },
- *     'FakeStripeGateway',
- *   );
+ * @typeParam T - The interface being faked.
+ * @param impl - Partial implementation; only the members the test needs.
+ * @param name - Label used in the "not configured" error message (defaults to `'fake'`).
+ * @returns A proxy typed as `T` that delegates to `impl` and throws on unconfigured members.
+ * @throws Error `` `${name}.${method} not configured` `` when an unconfigured string-keyed member is called.
+ * @example
+ * ```ts
+ * const stripe = configurableFake<StripeGateway>(
+ *   { listPaymentIntents: async () => fakeApiList([fakePaymentIntent()]) },
+ *   'FakeStripeGateway',
+ * );
+ * await stripe.listPaymentIntents(); // ok
+ * await stripe.cancelPaymentIntent('pi_1'); // throws: FakeStripeGateway.cancelPaymentIntent not configured
+ * ```
  */
 export function configurableFake(impl, name = 'fake') {
     return new Proxy(impl, {
@@ -17,8 +28,9 @@ export function configurableFake(impl, name = 'fake') {
             if (prop in target) {
                 return target[prop];
             }
-            // Promise インターロップ用プロパティには「未設定メソッド」関数を返さない。返すと fake 自身が
-            // thenable 扱いされ、誤って await / Promise.resolve した瞬間に then() が呼ばれて throw する罠になる。
+            // Never return the "unconfigured member" function for Promise-interop properties. Doing so would
+            // make the fake itself look thenable, so accidentally awaiting it (or passing it to
+            // Promise.resolve) would invoke then() and throw — a subtle footgun.
             if (prop === 'then' || prop === 'catch' || prop === 'finally') {
                 return undefined;
             }