@rdlabo/workers-hono-kit 0.1.0 → 0.2.1

package/src/aws/cloudfront.ts

@@ -1,10 +1,28 @@
 /**
- * CloudFront 署名付き URL 生成（`@aws-sdk/cloudfront-signer` の getSignedUrl を Web Crypto で再実装）。
- * Cloudflare Workers ネイティブ（aws-sdk 不要）。フリート共通 = tipsys/winecode hono。
+ * Generate a CloudFront signed URL using a canned policy, implemented natively for Cloudflare Workers.
  *
- * canned policy を RSASSA-PKCS1-v1_5 + SHA-1 で署名し、AWS の URL-safe base64 変換
- *   '+' -> '-' , '/' -> '~' , '=' -> '_'
- * を施して `Expires` / `Key-Pair-Id` / `Signature` の順でクエリを付与する（aws-sdk の出力とバイト一致）。
+ * Reimplements `getSignedUrl` from `@aws-sdk/cloudfront-signer` on top of the Web Crypto API, so no
+ * `@aws-sdk` dependency is required. The canned policy is signed with RSASSA-PKCS1-v1_5 and SHA-1, the
+ * signature is converted to AWS URL-safe base64 (`+` -> `-`, `/` -> `~`, `=` -> `_`), and the query
+ * parameters are appended in the order `Expires`, `Key-Pair-Id`, `Signature`.
+ *
+ * @remarks
+ * The output is byte-for-byte identical to that of `@aws-sdk/cloudfront-signer`.
+ *
+ * @param url - The resource URL to sign.
+ * @param privateKeyPem - The CloudFront key group private key in PKCS#8 PEM format.
+ * @param keyPairId - The CloudFront public key (key pair) ID associated with the private key.
+ * @param dateLessThan - Expiry time, accepted as a `Date`, epoch-millisecond number, or date string.
+ * @returns The signed URL with the `Expires`, `Key-Pair-Id`, and `Signature` query parameters appended.
+ * @example
+ * ```ts
+ * const signedUrl = await getCloudFrontSignedUrl(
+ *   'https://cdn.example.com/private/video.mp4',
+ *   env.CLOUDFRONT_PRIVATE_KEY,
+ *   env.CLOUDFRONT_KEY_PAIR_ID,
+ *   Date.now() + 60 * 60 * 1000, // valid for one hour
+ * );
+ * ```
  */
 export async function getCloudFrontSignedUrl(
   url: string,
@@ -34,14 +52,29 @@ export async function getCloudFrontSignedUrl(
   const signature = toUrlSafeBase64(arrayBufferToBase64(signatureBuffer));
   const separator = url.includes('?') ? '&' : '?';
 
-  // @aws-sdk/cloudfront-signer のクエリ順: Expires -> Key-Pair-Id -> Signature
+  // Query order used by @aws-sdk/cloudfront-signer: Expires -> Key-Pair-Id -> Signature
   return `${url}${separator}Expires=${epochSeconds}&Key-Pair-Id=${keyPairId}&Signature=${signature}`;
 }
 
+/**
+ * Convert standard base64 to the URL-safe alphabet expected in CloudFront signatures.
+ *
+ * @param value - A standard base64 string.
+ * @returns The base64 string with `+` -> `-`, `=` -> `_`, and `/` -> `~`.
+ * @internal
+ */
+
 function toUrlSafeBase64(value: string): string {
   return value.replace(/\+/g, '-').replace(/=/g, '_').replace(/\//g, '~');
 }
 
+/**
+ * Encode an `ArrayBuffer` to standard base64.
+ *
+ * @param buffer - The raw bytes to encode.
+ * @returns The standard base64 representation of the buffer.
+ * @internal
+ */
 function arrayBufferToBase64(buffer: ArrayBuffer): string {
   const bytes = new Uint8Array(buffer);
   let binary = '';
@@ -51,6 +84,13 @@ function arrayBufferToBase64(buffer: ArrayBuffer): string {
   return btoa(binary);
 }
 
+/**
+ * Decode a PKCS#8 PEM private key into its DER `ArrayBuffer`.
+ *
+ * @param pem - The PEM-encoded key, including the BEGIN/END armor.
+ * @returns The decoded DER bytes, suitable for `crypto.subtle.importKey('pkcs8', ...)`.
+ * @internal
+ */
 function pemToDer(pem: string): ArrayBuffer {
   const base64 = pem
     .replace(/-----BEGIN [^-]+-----/, '')

package/src/aws/secrets-manager.ts

@@ -1,26 +1,66 @@
 import { AwsClient } from 'aws4fetch';
 
 /**
- * AWS Secrets Manager の GetSecretValue を aws4fetch（SigV4 署名 fetch）で叩く汎用ヘルパ。
- * Cloudflare Workers には AWS SDK も IAM ロールも無いため、AWS の静的キーを Workers secrets として
- * 渡して署名する（移植元 `api/src/secrets-manager.ts` 相当）。DB 認証情報は Hyperdrive 側に持つので対象外。
+ * AWS credentials used to sign Secrets Manager requests.
  *
- * Secret の中身（スキーマ）と secretId は repo ごとに異なるため、`<T>` と `secretId` を呼び出し側が渡す。
+ * @remarks
+ * Cloudflare Workers have neither the AWS SDK nor IAM role credentials, so static AWS keys are supplied
+ * as Workers secrets and used to produce a SigV4 signature.
  */
 export interface AwsSecretsOptions {
+  /** AWS access key ID. */
   accessKeyId: string;
+  /** AWS secret access key. */
   secretAccessKey: string;
+  /** Optional STS session token, required when using temporary credentials. */
   sessionToken?: string;
+  /** AWS region of the Secrets Manager endpoint, e.g. `ap-northeast-1`. */
   region: string;
 }
 
 /**
- * Per-isolate cache: Secrets Manager は isolate ごと 1 回だけ叩く。region+accessKeyId+secretId を
- * キーにし、資格情報ローテーション時は再取得する。promise をキャッシュして同時初回リクエストが 1 回の
- * 呼び出しを共有する。reject 時はキャッシュをクリアして retry を許す。
+ * Per-isolate cache for the fetched secret.
+ *
+ * @remarks
+ * Secrets Manager is queried at most once per isolate. The entry is keyed by
+ * `region:accessKeyId:secretId`, so rotating credentials triggers a fresh fetch. The in-flight promise
+ * itself is cached so that concurrent first-time callers share a single request. On rejection the cache
+ * is cleared so a failed fetch can be retried.
+ *
+ * @internal
  */
 let cache: { key: string; value: Promise<unknown> } | null = null;
 
+/**
+ * Fetch and parse a secret from AWS Secrets Manager, caching the result per isolate.
+ *
+ * Issues a `GetSecretValue` call to Secrets Manager via a SigV4-signed `fetch` (using aws4fetch), with no
+ * AWS SDK involved. The parsed `SecretString` is cached per isolate keyed by region, access key ID, and
+ * secret ID; concurrent first-time callers share one in-flight request, and a rejected fetch clears the
+ * cache entry so the next call retries.
+ *
+ * @typeParam T - The shape of the JSON-parsed secret payload, supplied by the caller.
+ * @param options - AWS credentials and region used to sign the request.
+ * @param secretId - The Secrets Manager secret ID or ARN to retrieve.
+ * @returns The parsed secret value cast to `T`.
+ * @throws Error When the Secrets Manager response is not OK, or when it contains no `SecretString`.
+ * @example
+ * ```ts
+ * interface DbSecret {
+ *   username: string;
+ *   password: string;
+ * }
+ *
+ * const secret = await getAuthenticationSecret<DbSecret>(
+ *   {
+ *     accessKeyId: env.AWS_ACCESS_KEY_ID,
+ *     secretAccessKey: env.AWS_SECRET_ACCESS_KEY,
+ *     region: 'ap-northeast-1',
+ *   },
+ *   'prod/db/credentials',
+ * );
+ * ```
+ */
 export function getAuthenticationSecret<T>(options: AwsSecretsOptions, secretId: string): Promise<T> {
   const key = `${options.region}:${options.accessKeyId}:${secretId}`;
   if (cache?.key !== key) {
@@ -33,6 +73,15 @@ export function getAuthenticationSecret<T>(options: AwsSecretsOptions, secretId:
   return cache.value as Promise<T>;
 }
 
+/**
+ * Perform the SigV4-signed `GetSecretValue` request and parse the returned `SecretString`.
+ *
+ * @param options - AWS credentials and region used to sign the request.
+ * @param secretId - The Secrets Manager secret ID or ARN to retrieve.
+ * @returns The JSON-parsed secret payload.
+ * @throws Error When the response is not OK, or when it contains no `SecretString`.
+ * @internal
+ */
 async function fetchSecret(options: AwsSecretsOptions, secretId: string): Promise<unknown> {
   const aws = new AwsClient({
     accessKeyId: options.accessKeyId,

package/src/cache/kv-cache.ts

@@ -1,30 +1,93 @@
 /**
- * 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);
+ * }
+ * ```
  */
 
-/** @cloudflare/workers-types の KVNamespace 最小サブセット（get/put/delete のみ使用）。 */
+/**
+ * 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.
+ */
 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;
@@ -33,6 +96,11 @@ interface CacheSetItem {
   lifetime?: number;
 }
 
+/**
+ * Key coordinates identifying a single entry for {@link KVCache.getMany}.
+ *
+ * @internal
+ */
 interface CacheKeyItem {
   table: string;
   type: string | number;
@@ -41,11 +109,32 @@ interface CacheKeyItem {
 
 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: string): Promise<string> {
   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 {
   readonly #kv: KVNamespace;
   readonly #appName: string;
@@ -53,6 +142,12 @@ export class KVCache {
   readonly #minTtl: number;
   readonly #defaultLifetime: number;
 
+  /**
+   * 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) {
     this.#kv = kv;
     this.#appName = options.appName;
@@ -61,16 +156,41 @@ export class KVCache {
     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: string, type: string | number, id: string | number): Promise<string | undefined> {
     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<T>(table: string, type: string | number, id: string | number): Promise<T | undefined> {
     const key = await this.#buildKey(table, type, id);
     if (!key) {
@@ -87,6 +207,24 @@ export class KVCache {
     }
   }
 
+  /**
+   * 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: string,
     type: string | number,
@@ -111,6 +249,22 @@ export class KVCache {
     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: CacheSetItem[]): Promise<void> {
     if (items.length === 0) {
       return;
@@ -118,12 +272,40 @@ export class KVCache {
     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<T>(items: CacheKeyItem[]): Promise<{ id: string | number; value: T | undefined }[]> {
     return Promise.all(items.map(async (i) => ({ id: i.id, value: await this.get<T>(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: string, type: string | number, id: string | number): Promise<void> {
     const key = await this.#buildKey(table, type, id);
     if (!key) {

package/src/db/connection.ts

@@ -2,30 +2,45 @@ import { createConnection } from 'mysql2/promise';
 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 function hyperdriveConnectionOptions(
   hyperdrive: HyperdriveLike,
@@ -44,13 +59,40 @@ export function hyperdriveConnectionOptions(
   };
 }
 
+/**
+ * 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 async function withMysqlConnections<T>(
   hyperdrives: { primary: HyperdriveLike; replica: HyperdriveLike },