@rdlabo/workers-hono-kit 0.2.0 → 0.3.0

package/dist/cache/kv-cache.d.ts

@@ -1,29 +1,92 @@
 /**
- * Workers KV を使った cache-aside キャッシュ（フリート共通 = winecode/tipsys hono の CacheService）。
- * 同一 DB を参照する透過キャッシュなので `/api` とレスポンスは一致する（perf 層であり parity に影響しない）。
+ * Cache-aside helper backed by Cloudflare Workers KV.
  *
- * キー構成は各 repo の `/api`（旧 Valkey）と一致させる:
- *   `${appName}${version}${table}_${type}_${column}`  （column: id が string なら sha256hex、number はそのまま）
- * KV の expirationTtl は 60s 下限のため lifetime を 60 でクランプする。
+ * Provides a thin, JSON-serializing wrapper around a {@link KVNamespace} for the common
+ * "look in cache, fall back to the source of truth" pattern. Reads and writes are best-effort:
+ * any KV error, serialization failure, or oversized key is swallowed so callers transparently
+ * fall through to their backing store instead of throwing.
+ *
+ * Cache keys are namespaced as `<appName><version><table>_<type>_<id>`, where a string `id` is
+ * hashed with SHA-256 (hex) and a numeric `id` is used verbatim.
+ *
+ * @remarks
+ * Workers KV enforces a 60-second minimum on `expirationTtl`, so every write clamps its lifetime
+ * up to at least {@link KVCacheOptions.minTtlSeconds} (60 by default). Keys whose UTF-8 byte length
+ * exceeds the KV 1024-byte limit are skipped entirely, leaving the value uncached.
+ *
+ * @example
+ * ```ts
+ * const cache = new KVCache(env.KV, { appName: 'myapp' });
+ * const cached = await cache.get<User>('users', 'profile', userId);
+ * if (!cached) {
+ *   const user = await db.loadUser(userId);
+ *   await cache.set('users', 'profile', userId, user);
+ * }
+ * ```
+ */
+/**
+ * Minimal subset of `@cloudflare/workers-types`' `KVNamespace` used by {@link KVCache}.
+ *
+ * Declared locally so consumers are not forced to depend on `@cloudflare/workers-types`. Only the
+ * three operations the cache actually needs are modeled.
  */
-/** @cloudflare/workers-types の KVNamespace 最小サブセット（get/put/delete のみ使用）。 */
 export interface KVNamespace {
+    /**
+     * Read the string value stored under `key`.
+     *
+     * @param key - Fully namespaced cache key.
+     * @returns The stored value, or `null` when the key is absent or expired.
+     */
     get(key: string): Promise<string | null>;
+    /**
+     * Write `value` under `key`, optionally with a time-to-live.
+     *
+     * @param key - Fully namespaced cache key.
+     * @param value - String payload to store.
+     * @param options - Optional write options; `expirationTtl` is the lifetime in seconds.
+     * @returns A promise that resolves once the write is accepted.
+     */
     put(key: string, value: string, options?: {
         expirationTtl?: number;
     }): Promise<void>;
+    /**
+     * Remove the entry stored under `key`.
+     *
+     * @param key - Fully namespaced cache key.
+     * @returns A promise that resolves once the delete is accepted.
+     */
     delete(key: string): Promise<void>;
 }
+/**
+ * Configuration for a {@link KVCache} instance.
+ */
 export interface KVCacheOptions {
-    /** キー前置（repo 名）。例 `'winecode'` / `'tipsys'`。 */
+    /**
+     * Application-level key prefix used to isolate this app's entries within a shared namespace.
+     * For example `'myapp'`.
+     */
     appName: string;
-    /** バージョン前置。既定 `'v8_'`。 */
+    /**
+     * Schema/version prefix applied after {@link appName}, letting you invalidate every key at once
+     * by bumping it. Defaults to `'v8_'`.
+     */
     version?: string;
-    /** lifetime の下限秒（KV の最小 TTL）。既定 `60`。 */
+    /**
+     * Lower bound, in seconds, applied to every write's TTL. Matches the Workers KV 60-second
+     * minimum and defaults to `60`.
+     */
     minTtlSeconds?: number;
-    /** lifetime 未指定時の既定秒。既定 `600`。 */
+    /**
+     * Default TTL, in seconds, used by {@link KVCache.set} when no per-call `lifetime` is supplied.
+     * Defaults to `600`.
+     */
     defaultLifetime?: number;
 }
+/**
+ * A single entry to store via {@link KVCache.setMany}.
+ *
+ * @internal
+ */
 interface CacheSetItem {
     table: string;
     type: string | number;
@@ -31,21 +94,121 @@ interface CacheSetItem {
     data: unknown;
     lifetime?: number;
 }
+/**
+ * Key coordinates identifying a single entry for {@link KVCache.getMany}.
+ *
+ * @internal
+ */
 interface CacheKeyItem {
     table: string;
     type: string | number;
     id: string | number;
 }
+/**
+ * Cache-aside wrapper over a Workers {@link KVNamespace}.
+ *
+ * Serializes values to JSON, namespaces keys, and clamps TTLs to the KV minimum. All operations are
+ * fail-soft: errors are swallowed so a cache miss or backend failure degrades to a source-of-truth
+ * lookup rather than propagating.
+ *
+ * @example
+ * ```ts
+ * const cache = new KVCache(env.KV, { appName: 'myapp', defaultLifetime: 300 });
+ * await cache.set('users', 'profile', 42, { name: 'Ada' });
+ * const user = await cache.get<{ name: string }>('users', 'profile', 42);
+ * ```
+ */
 export declare class KVCache {
     #private;
+    /**
+     * Create a cache bound to a specific KV namespace.
+     *
+     * @param kv - The Workers KV namespace that backs this cache.
+     * @param options - Key-prefix and TTL configuration; see {@link KVCacheOptions}.
+     */
     constructor(kv: KVNamespace, options: KVCacheOptions);
+    /**
+     * Read and JSON-parse a cached value.
+     *
+     * @typeParam T - Expected shape of the cached value.
+     * @param table - Logical table or entity name.
+     * @param type - Sub-key discriminator.
+     * @param id - Entity identifier.
+     * @returns The parsed value, or `undefined` on a miss, oversized key, or any read/parse error.
+     * @example
+     * ```ts
+     * const user = await cache.get<User>('users', 'profile', userId);
+     * ```
+     */
     get<T>(table: string, type: string | number, id: string | number): Promise<T | undefined>;
+    /**
+     * JSON-serialize and store a value.
+     *
+     * Falsy `data` is ignored. The effective TTL is `max(minTtlSeconds, lifetime ?? defaultLifetime)`,
+     * honoring the KV 60-second floor. Oversized keys and serialization/write failures are silently
+     * skipped.
+     *
+     * @param table - Logical table or entity name.
+     * @param type - Sub-key discriminator.
+     * @param id - Entity identifier.
+     * @param data - Value to cache; serialized with `JSON.stringify`.
+     * @param lifetime - Optional TTL in seconds; defaults to {@link KVCacheOptions.defaultLifetime}.
+     * @returns A promise that resolves once the write attempt completes.
+     * @example
+     * ```ts
+     * await cache.set('users', 'profile', userId, user, 300);
+     * ```
+     */
     set(table: string, type: string | number, id: string | number, data: unknown, lifetime?: number): Promise<void>;
+    /**
+     * Store many values concurrently.
+     *
+     * Each item is written via {@link KVCache.set}, so the same fail-soft and TTL rules apply per item.
+     * An empty array is a no-op.
+     *
+     * @param items - Entries to store; see {@link CacheSetItem}.
+     * @returns A promise that resolves once every write attempt completes.
+     * @example
+     * ```ts
+     * await cache.setMany([
+     *   { table: 'users', type: 'profile', id: 1, data: userA },
+     *   { table: 'users', type: 'profile', id: 2, data: userB, lifetime: 120 },
+     * ]);
+     * ```
+     */
     setMany(items: CacheSetItem[]): Promise<void>;
+    /**
+     * Read many values concurrently.
+     *
+     * @typeParam T - Expected shape of each cached value.
+     * @param items - Key coordinates to look up; see {@link CacheKeyItem}.
+     * @returns One `{ id, value }` pair per input item, preserving order; `value` is `undefined` on miss.
+     * @example
+     * ```ts
+     * const rows = await cache.getMany<User>([
+     *   { table: 'users', type: 'profile', id: 1 },
+     *   { table: 'users', type: 'profile', id: 2 },
+     * ]);
+     * ```
+     */
     getMany<T>(items: CacheKeyItem[]): Promise<{
         id: string | number;
         value: T | undefined;
     }[]>;
+    /**
+     * Remove a cached entry.
+     *
+     * Oversized keys and delete failures are silently ignored.
+     *
+     * @param table - Logical table or entity name.
+     * @param type - Sub-key discriminator.
+     * @param id - Entity identifier.
+     * @returns A promise that resolves once the delete attempt completes.
+     * @example
+     * ```ts
+     * await cache.delete('users', 'profile', userId);
+     * ```
+     */
     delete(table: string, type: string | number, id: string | number): Promise<void>;
 }
 export {};

package/dist/cache/kv-cache.js

@@ -1,22 +1,67 @@
 /**
- * Workers KV を使った cache-aside キャッシュ（フリート共通 = winecode/tipsys hono の CacheService）。
- * 同一 DB を参照する透過キャッシュなので `/api` とレスポンスは一致する（perf 層であり parity に影響しない）。
+ * Cache-aside helper backed by Cloudflare Workers KV.
  *
- * キー構成は各 repo の `/api`（旧 Valkey）と一致させる:
- *   `${appName}${version}${table}_${type}_${column}`  （column: id が string なら sha256hex、number はそのまま）
- * KV の expirationTtl は 60s 下限のため lifetime を 60 でクランプする。
+ * Provides a thin, JSON-serializing wrapper around a {@link KVNamespace} for the common
+ * "look in cache, fall back to the source of truth" pattern. Reads and writes are best-effort:
+ * any KV error, serialization failure, or oversized key is swallowed so callers transparently
+ * fall through to their backing store instead of throwing.
+ *
+ * Cache keys are namespaced as `<appName><version><table>_<type>_<id>`, where a string `id` is
+ * hashed with SHA-256 (hex) and a numeric `id` is used verbatim.
+ *
+ * @remarks
+ * Workers KV enforces a 60-second minimum on `expirationTtl`, so every write clamps its lifetime
+ * up to at least {@link KVCacheOptions.minTtlSeconds} (60 by default). Keys whose UTF-8 byte length
+ * exceeds the KV 1024-byte limit are skipped entirely, leaving the value uncached.
+ *
+ * @example
+ * ```ts
+ * const cache = new KVCache(env.KV, { appName: 'myapp' });
+ * const cached = await cache.get<User>('users', 'profile', userId);
+ * if (!cached) {
+ *   const user = await db.loadUser(userId);
+ *   await cache.set('users', 'profile', userId, user);
+ * }
+ * ```
  */
 const encoder = new TextEncoder();
+/**
+ * Compute the lowercase hex SHA-256 digest of a UTF-8 string.
+ *
+ * @param input - String to hash.
+ * @returns The 64-character hex-encoded digest.
+ * @internal
+ */
 async function sha256Hex(input) {
     const digest = await crypto.subtle.digest('SHA-256', encoder.encode(input));
     return [...new Uint8Array(digest)].map((b) => b.toString(16).padStart(2, '0')).join('');
 }
+/**
+ * Cache-aside wrapper over a Workers {@link KVNamespace}.
+ *
+ * Serializes values to JSON, namespaces keys, and clamps TTLs to the KV minimum. All operations are
+ * fail-soft: errors are swallowed so a cache miss or backend failure degrades to a source-of-truth
+ * lookup rather than propagating.
+ *
+ * @example
+ * ```ts
+ * const cache = new KVCache(env.KV, { appName: 'myapp', defaultLifetime: 300 });
+ * await cache.set('users', 'profile', 42, { name: 'Ada' });
+ * const user = await cache.get<{ name: string }>('users', 'profile', 42);
+ * ```
+ */
 export class KVCache {
     #kv;
     #appName;
     #version;
     #minTtl;
     #defaultLifetime;
+    /**
+     * Create a cache bound to a specific KV namespace.
+     *
+     * @param kv - The Workers KV namespace that backs this cache.
+     * @param options - Key-prefix and TTL configuration; see {@link KVCacheOptions}.
+     */
     constructor(kv, options) {
         this.#kv = kv;
         this.#appName = options.appName;
@@ -24,15 +69,40 @@ export class KVCache {
         this.#minTtl = options.minTtlSeconds ?? 60;
         this.#defaultLifetime = options.defaultLifetime ?? 600;
     }
+    /**
+     * Build the fully namespaced KV key for the given coordinates.
+     *
+     * A string `id` is hashed with SHA-256 (hex); a numeric `id` is used as-is.
+     *
+     * @param table - Logical table or entity name.
+     * @param type - Sub-key discriminator (e.g. lookup variant).
+     * @param id - Entity identifier; strings are hashed, numbers used verbatim.
+     * @returns The key, or `undefined` when it would exceed the KV 1024-byte limit.
+     * @internal
+     */
     async #buildKey(table, type, id) {
         const column = typeof id === 'string' ? await sha256Hex(id) : id;
         const key = `${this.#appName}${this.#version}${table}_${type}_${column}`;
-        // KV のキーは 512〜1024 バイト上限。超えるものはキャッシュ対象外（cache-aside なので DB 直読みに落ちる）。
+        // KV keys are capped at 1024 bytes. Oversized keys are left uncached; cache-aside callers fall
+        // back to reading directly from their source of truth.
         if (encoder.encode(key).byteLength > 1024) {
             return undefined;
         }
         return key;
     }
+    /**
+     * Read and JSON-parse a cached value.
+     *
+     * @typeParam T - Expected shape of the cached value.
+     * @param table - Logical table or entity name.
+     * @param type - Sub-key discriminator.
+     * @param id - Entity identifier.
+     * @returns The parsed value, or `undefined` on a miss, oversized key, or any read/parse error.
+     * @example
+     * ```ts
+     * const user = await cache.get<User>('users', 'profile', userId);
+     * ```
+     */
     async get(table, type, id) {
         const key = await this.#buildKey(table, type, id);
         if (!key) {
@@ -49,6 +119,24 @@ export class KVCache {
             return undefined;
         }
     }
+    /**
+     * JSON-serialize and store a value.
+     *
+     * Falsy `data` is ignored. The effective TTL is `max(minTtlSeconds, lifetime ?? defaultLifetime)`,
+     * honoring the KV 60-second floor. Oversized keys and serialization/write failures are silently
+     * skipped.
+     *
+     * @param table - Logical table or entity name.
+     * @param type - Sub-key discriminator.
+     * @param id - Entity identifier.
+     * @param data - Value to cache; serialized with `JSON.stringify`.
+     * @param lifetime - Optional TTL in seconds; defaults to {@link KVCacheOptions.defaultLifetime}.
+     * @returns A promise that resolves once the write attempt completes.
+     * @example
+     * ```ts
+     * await cache.set('users', 'profile', userId, user, 300);
+     * ```
+     */
     async set(table, type, id, data, lifetime) {
         if (!data) {
             return;
@@ -67,17 +155,61 @@ export class KVCache {
         const ttl = Math.max(this.#minTtl, lifetime ?? this.#defaultLifetime);
         await this.#kv.put(key, payload, { expirationTtl: ttl }).catch(() => undefined);
     }
+    /**
+     * Store many values concurrently.
+     *
+     * Each item is written via {@link KVCache.set}, so the same fail-soft and TTL rules apply per item.
+     * An empty array is a no-op.
+     *
+     * @param items - Entries to store; see {@link CacheSetItem}.
+     * @returns A promise that resolves once every write attempt completes.
+     * @example
+     * ```ts
+     * await cache.setMany([
+     *   { table: 'users', type: 'profile', id: 1, data: userA },
+     *   { table: 'users', type: 'profile', id: 2, data: userB, lifetime: 120 },
+     * ]);
+     * ```
+     */
     async setMany(items) {
         if (items.length === 0) {
             return;
         }
         await Promise.all(items.map((i) => this.set(i.table, i.type, i.id, i.data, i.lifetime)));
     }
-    // T は呼び出し側が指定する戻り値型（get<T> と同じく ergonomics 目的）。
+    /**
+     * Read many values concurrently.
+     *
+     * @typeParam T - Expected shape of each cached value.
+     * @param items - Key coordinates to look up; see {@link CacheKeyItem}.
+     * @returns One `{ id, value }` pair per input item, preserving order; `value` is `undefined` on miss.
+     * @example
+     * ```ts
+     * const rows = await cache.getMany<User>([
+     *   { table: 'users', type: 'profile', id: 1 },
+     *   { table: 'users', type: 'profile', id: 2 },
+     * ]);
+     * ```
+     */
+    // The generic `T` is the caller-specified return type, mirroring `get<T>` for ergonomics.
     // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-parameters
     async getMany(items) {
         return Promise.all(items.map(async (i) => ({ id: i.id, value: await this.get(i.table, i.type, i.id) })));
     }
+    /**
+     * Remove a cached entry.
+     *
+     * Oversized keys and delete failures are silently ignored.
+     *
+     * @param table - Logical table or entity name.
+     * @param type - Sub-key discriminator.
+     * @param id - Entity identifier.
+     * @returns A promise that resolves once the delete attempt completes.
+     * @example
+     * ```ts
+     * await cache.delete('users', 'profile', userId);
+     * ```
+     */
     async delete(table, type, id) {
         const key = await this.#buildKey(table, type, id);
         if (!key) {

package/dist/db/connection.d.ts

@@ -1,36 +1,78 @@
 import type { Connection } from 'mysql2/promise';
 /**
- * Hyperdrive バインディングの最小形（@cloudflare/workers-types への依存を避けるための構造型）。
+ * Minimal structural shape of a Cloudflare Hyperdrive binding.
+ *
+ * @remarks
+ * Declared structurally to avoid a dependency on `@cloudflare/workers-types`; any object with these
+ * connection fields satisfies it.
  */
 export interface HyperdriveLike {
+    /** Database host to connect to. */
     host: string;
+    /** Database user. */
     user: string;
+    /** Database password. */
     password: string;
+    /** Database name. */
     database: string;
+    /** Database port. */
     port: number;
 }
 /**
- * Hyperdrive バインディングから mysql2 の createConnection 用オプションを作る。
- * `disableEval: true`（Workers で eval 不可）は既定で付与。`extra` で timezone 等を上書き/追加。
+ * Build mysql2 `createConnection` options from a Hyperdrive binding, applying the kit's defaults.
+ *
+ * @remarks
+ * Three defaults are applied and can each be overridden via `extra`:
  *
- * `decimalNumbers: true`: DECIMAL/NEWDECIMAL を文字列でなく JS number で返す。Drizzle の
- * `$inferSelect`（decimal→string）と生 SQL reads の戻り値を、各 repo の数値ドメイン型
- * （nutrition の number 等）に揃えるため既定で有効化。precision/scale が JS の安全整数域
- * （decimal(15,2) 程度まで）を超える列が無いことが前提。
+ * - `disableEval: true` — `eval` is unavailable in the Workers runtime, so the driver's eval-based
+ *   fast paths must be disabled.
+ * - `decimalNumbers: true` — return `DECIMAL`/`NEWDECIMAL` columns as JS `number` rather than
+ *   strings, so raw-SQL reads and Drizzle's inferred types align on a single numeric domain type.
+ *   This assumes no column's precision exceeds the JS safe-integer range.
+ * - `timezone: '+09:00'` — set the driver's session timezone to JST. mysql2 defaults to `'local'`,
+ *   which is UTC in the Workers runtime; pinning the driver timezone keeps `datetime`/`timestamp`
+ *   round-trips independent of the database's session timezone (only the internally stored UTC
+ *   value differs, which is invisible to the application). Non-JST deployments can override this
+ *   via `extra: { timezone: '...' }`.
  *
- * `timezone: '+09:00'`: フリートの接続先 RDB は session time_zone=Asia/Tokyo。mysql2 の driver
- * `timezone` 既定は `'local'`＝Workers では UTC で、揃わないと `datetime/timestamp` の生 Date 読みが
- * +9h・生 Date 書きが −9h ズレる（NestJS は JST 実行で一致＝移植で顕在化する潜在バグ）。driver を
- * 固定すれば round-trip の観測値は DB の session tz に非依存（内部格納 UTC 値だけ変わるが app 不可視）。
- * 非 JST repo は `extra: { timezone: '...' }` で上書き可。
+ * @param hyperdrive - the Hyperdrive binding to derive connection fields from.
+ * @param extra - additional mysql2 options merged last, overriding the defaults above.
+ * @returns a plain options object to pass to mysql2 `createConnection`.
  */
 export declare function hyperdriveConnectionOptions(hyperdrive: HyperdriveLike, extra?: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Minimal structural shape of a Workers `ExecutionContext`, limited to `waitUntil`.
+ *
+ * @remarks
+ * Declared structurally to avoid a dependency on `@cloudflare/workers-types`.
+ */
 export interface ExecutionContextLike {
+    /** Extend the request's lifetime until `promise` settles (used to close connections after the response). */
     waitUntil(promise: Promise<unknown>): void;
 }
 /**
- * primary/replica の接続を開いて `fn` を実行し、finally で `ctx.waitUntil` 越しに閉じる
- * （receptray/tipsys の worker entry の接続ライフサイクル相当）。
+ * Open primary and replica connections, run `fn` with them, and close both afterwards.
+ *
+ * The connections are always closed in a `finally` block; closing is scheduled through
+ * `ctx.waitUntil` so it can complete after the response has been returned, without blocking it.
+ *
+ * @typeParam T - resolved value produced by `fn`.
+ * @param hyperdrives - the primary and replica Hyperdrive bindings to connect to.
+ * @param ctx - the execution context whose `waitUntil` defers connection teardown past the response.
+ * @param fn - callback invoked with the open `primary` and `replica` connections.
+ * @param connectionOptions - extra mysql2 options forwarded to {@link hyperdriveConnectionOptions}.
+ * @returns the value resolved by `fn`.
+ * @example
+ * ```ts
+ * const data = await withMysqlConnections(
+ *   { primary: env.PRIMARY, replica: env.REPLICA },
+ *   ctx,
+ *   async ({ primary, replica }) => {
+ *     const [rows] = await replica.query('SELECT 1');
+ *     return rows;
+ *   },
+ * );
+ * ```
  */
 export declare function withMysqlConnections<T>(hyperdrives: {
     primary: HyperdriveLike;

package/dist/db/connection.js

@@ -1,18 +1,24 @@
 import { createConnection } from 'mysql2/promise';
 /**
- * Hyperdrive バインディングから mysql2 の createConnection 用オプションを作る。
- * `disableEval: true`（Workers で eval 不可）は既定で付与。`extra` で timezone 等を上書き/追加。
+ * Build mysql2 `createConnection` options from a Hyperdrive binding, applying the kit's defaults.
  *
- * `decimalNumbers: true`: DECIMAL/NEWDECIMAL を文字列でなく JS number で返す。Drizzle の
- * `$inferSelect`（decimal→string）と生 SQL reads の戻り値を、各 repo の数値ドメイン型
- * （nutrition の number 等）に揃えるため既定で有効化。precision/scale が JS の安全整数域
- * （decimal(15,2) 程度まで）を超える列が無いことが前提。
+ * @remarks
+ * Three defaults are applied and can each be overridden via `extra`:
  *
- * `timezone: '+09:00'`: フリートの接続先 RDB は session time_zone=Asia/Tokyo。mysql2 の driver
- * `timezone` 既定は `'local'`＝Workers では UTC で、揃わないと `datetime/timestamp` の生 Date 読みが
- * +9h・生 Date 書きが −9h ズレる（NestJS は JST 実行で一致＝移植で顕在化する潜在バグ）。driver を
- * 固定すれば round-trip の観測値は DB の session tz に非依存（内部格納 UTC 値だけ変わるが app 不可視）。
- * 非 JST repo は `extra: { timezone: '...' }` で上書き可。
+ * - `disableEval: true` — `eval` is unavailable in the Workers runtime, so the driver's eval-based
+ *   fast paths must be disabled.
+ * - `decimalNumbers: true` — return `DECIMAL`/`NEWDECIMAL` columns as JS `number` rather than
+ *   strings, so raw-SQL reads and Drizzle's inferred types align on a single numeric domain type.
+ *   This assumes no column's precision exceeds the JS safe-integer range.
+ * - `timezone: '+09:00'` — set the driver's session timezone to JST. mysql2 defaults to `'local'`,
+ *   which is UTC in the Workers runtime; pinning the driver timezone keeps `datetime`/`timestamp`
+ *   round-trips independent of the database's session timezone (only the internally stored UTC
+ *   value differs, which is invisible to the application). Non-JST deployments can override this
+ *   via `extra: { timezone: '...' }`.
+ *
+ * @param hyperdrive - the Hyperdrive binding to derive connection fields from.
+ * @param extra - additional mysql2 options merged last, overriding the defaults above.
+ * @returns a plain options object to pass to mysql2 `createConnection`.
  */
 export function hyperdriveConnectionOptions(hyperdrive, extra) {
     return {
@@ -28,8 +34,28 @@ export function hyperdriveConnectionOptions(hyperdrive, extra) {
     };
 }
 /**
- * primary/replica の接続を開いて `fn` を実行し、finally で `ctx.waitUntil` 越しに閉じる
- * （receptray/tipsys の worker entry の接続ライフサイクル相当）。
+ * Open primary and replica connections, run `fn` with them, and close both afterwards.
+ *
+ * The connections are always closed in a `finally` block; closing is scheduled through
+ * `ctx.waitUntil` so it can complete after the response has been returned, without blocking it.
+ *
+ * @typeParam T - resolved value produced by `fn`.
+ * @param hyperdrives - the primary and replica Hyperdrive bindings to connect to.
+ * @param ctx - the execution context whose `waitUntil` defers connection teardown past the response.
+ * @param fn - callback invoked with the open `primary` and `replica` connections.
+ * @param connectionOptions - extra mysql2 options forwarded to {@link hyperdriveConnectionOptions}.
+ * @returns the value resolved by `fn`.
+ * @example
+ * ```ts
+ * const data = await withMysqlConnections(
+ *   { primary: env.PRIMARY, replica: env.REPLICA },
+ *   ctx,
+ *   async ({ primary, replica }) => {
+ *     const [rows] = await replica.query('SELECT 1');
+ *     return rows;
+ *   },
+ * );
+ * ```
  */
 export async function withMysqlConnections(hyperdrives, ctx, fn, connectionOptions) {
     let primary;