@rdlabo/workers-hono-kit 0.2.0 → 0.3.0

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 },

package/src/db/database.ts

@@ -5,39 +5,104 @@ import type { HyperdriveLike } from './connection.js';
 import { retryWhenDeadlock } from './retry.js';
 
 /**
- * フリート共通のデータ層（NestJS/TypeORM の master/slave + retryWhenDeadlock 置換）。
- *   - reads  → replica。透明性のため生 SQL を維持（旧 helper.slave().query 相当）。
- *   - writes → primary。型安全のため Drizzle 経由。ただし `write(fn)`/`transaction(fn)` 経由のみで、
- *     生 builder は公開しない。builder はここで await される（Drizzle builder は lazy thenable のため
- *     `return builder` が黙って no-op になるフットガンを排除）。両者とも ER_LOCK_DEADLOCK を retry。
- *
- * 重要: kit は `drizzle-orm` の **型同一性に依存しない**。各 repo が自分の drizzle-orm で作った orm を
- * 渡す（`Database` は orm 型 `TDrizzle` にジェネリック）。これにより kit と repo で drizzle-orm の
- * コピーが分かれても（symlink 構成）`MySqlTable`/`SQL` のブランド衝突が起きない。
+ * Dual-connection data layer that separates reads from writes.
+ *
+ * @remarks
+ * The two sides of the database are deliberately handled differently:
+ *
+ * - Reads go to the **replica** as raw SQL (`QueryRunner.query`) for transparency, returning plain
+ *   rows.
+ * - Writes and transactions go to the **primary** through the Drizzle ORM for type safety, but only
+ *   via `write(fn)` / `transaction(fn)` — the raw query builder is never exposed. The builder is
+ *   awaited inside those methods, which removes a foot-gun: a Drizzle builder is a lazy thenable, so
+ *   a bare `return builder` would silently become a no-op.
+ *
+ * Both sides retry on `ER_LOCK_DEADLOCK`.
+ *
+ * The kit deliberately avoids depending on the type identity of `drizzle-orm`: the consumer creates
+ * the ORM instance with its own copy of `drizzle-orm` and passes it in, and {@link Database} is
+ * generic over that ORM type (`TDrizzle`). This keeps the ORM's `MySqlTable`/`SQL` brands from
+ * clashing even when the kit and the consumer resolve separate copies of `drizzle-orm`.
  */
 
-/** reads 用の最小接続インターフェース（mysql2 Connection / Pool が構造的に満たす）。 */
+/**
+ * Minimal connection interface used for reads.
+ *
+ * @remarks
+ * A mysql2 `Connection` or `Pool` satisfies this structurally.
+ */
 export interface QueryRunner {
+  /**
+   * Run a parameterized SQL query.
+   *
+   * @param sql - the SQL text, with `?` placeholders for `params`.
+   * @param params - optional positional parameters.
+   * @returns the driver's raw result (typically `[rows, fields]`).
+   */
   query(sql: string, params?: unknown[]): Promise<unknown>;
 }
 
-/** drizzle インスタンスの `.transaction(cb)` が受け取る tx ハンドルの型を取り出す。 */
+/**
+ * Extract the transaction-handle type that a Drizzle instance passes to its `.transaction(cb)`
+ * callback.
+ *
+ * @typeParam TDrizzle - the consumer's Drizzle ORM type.
+ */
 export type TxOf<TDrizzle> = TDrizzle extends {
   transaction(cb: (tx: infer Tx) => Promise<unknown>): Promise<unknown>;
 }
   ? Tx
   : unknown;
 
+/**
+ * The read/write surface of the data layer.
+ *
+ * @typeParam TDrizzle - the consumer's Drizzle ORM type used for writes and transactions.
+ * @typeParam TTx - the transaction-handle type, inferred from `TDrizzle` by default.
+ */
 export interface Database<TDrizzle, TTx = TxOf<TDrizzle>> {
+  /**
+   * Run a raw SQL read against the replica, with deadlock retry.
+   *
+   * @typeParam T - the row shape.
+   * @param sql - the SQL text, with `?` placeholders for `params`.
+   * @param params - optional positional parameters.
+   * @returns the rows returned by the query.
+   */
   read<T>(sql: string, params?: unknown[]): Promise<T[]>;
-  /** 単一 INSERT/UPDATE/DELETE。primary で await + deadlock retry。 */
+  /**
+   * Run a single INSERT/UPDATE/DELETE against the primary, awaited with deadlock retry.
+   *
+   * @typeParam T - the value resolved by `fn`.
+   * @param fn - callback that receives the Drizzle ORM and returns the awaited write.
+   * @returns the value resolved by `fn`.
+   */
   write<T>(fn: (dz: TDrizzle) => Promise<T>): Promise<T>;
-  /** 複数 write を 1 トランザクションで。deadlock 時は全体を retry。 */
+  /**
+   * Run multiple writes inside a single transaction; the whole transaction is retried on deadlock.
+   *
+   * @typeParam T - the value resolved by `fn`.
+   * @param fn - callback that receives the transaction handle and returns the awaited work.
+   * @returns the value resolved by `fn`.
+   */
   transaction<T>(fn: (tx: TTx) => Promise<T>): Promise<T>;
 }
 
-/** dispose() を持つ Database（接続をモジュール内で開く版＝Hyperdrive / Pool 背面）。 */
+/**
+ * A {@link Database} that owns its connections and must be disposed.
+ *
+ * @remarks
+ * Used by the variants that open connections internally (Hyperdrive- or Pool-backed).
+ *
+ * @typeParam TDrizzle - the consumer's Drizzle ORM type.
+ * @typeParam TTx - the transaction-handle type, inferred from `TDrizzle` by default.
+ */
 export interface DisposableDatabase<TDrizzle, TTx = TxOf<TDrizzle>> extends Database<TDrizzle, TTx> {
+  /**
+   * Close the connections opened by this database.
+   *
+   * @returns a promise that settles once both connections are closed.
+   */
   dispose(): Promise<void>;
 }
 
@@ -45,33 +110,91 @@ interface DrizzleLike<TTx> {
   transaction<T>(cb: (tx: TTx) => Promise<T>): Promise<T>;
 }
 
+/**
+ * Options for {@link createMysqlDatabase}.
+ *
+ * @typeParam TDrizzle - the consumer's Drizzle ORM type.
+ */
 export interface CreateMysqlDatabaseOptions<TDrizzle> {
-  /** 消費側が自分の drizzle-orm で `drizzle(primary, { schema, ... })` を作って渡す（writes 用）。 */
+  /**
+   * The Drizzle ORM used for writes, created by the consumer with its own `drizzle-orm`
+   * (e.g. `drizzle(primary, { schema, ... })`).
+   */
   orm: TDrizzle;
-  /** reads（生 SQL）用の接続。 */
+  /** The connection used for reads (raw SQL). */
   replica: QueryRunner;
 }
 
 /**
- * 接続済みの orm/replica を受け取り Database を組み立てる（receptray/tipsys の MysqlDatabase 相当）。
- * 接続・orm の生成と接続の破棄は呼び出し側（worker entry）が担う。
+ * Assemble a {@link Database} from an already-connected ORM and replica.
+ *
+ * @remarks
+ * The caller (typically the worker entry point) owns creating the connections and the ORM, and is
+ * responsible for closing the connections; this variant does not manage their lifecycle.
+ *
+ * @typeParam TDrizzle - the consumer's Drizzle ORM type.
+ * @param options - the write ORM and the read connection.
+ * @returns a {@link Database} backed by the supplied ORM and replica.
+ * @example
+ * ```ts
+ * const db = createMysqlDatabase({
+ *   orm: drizzle(primary, { schema, ...DRIZZLE_ORM_OPTIONS }),
+ *   replica,
+ * });
+ * const rows = await db.read<User>('SELECT * FROM users WHERE id = ?', [id]);
+ * ```
  */
 export function createMysqlDatabase<TDrizzle>(options: CreateMysqlDatabaseOptions<TDrizzle>): Database<TDrizzle> {
   return databaseFrom(options.orm, options.replica);
 }
 
+/**
+ * Options for {@link createHyperdriveDatabase}.
+ *
+ * @typeParam TDrizzle - the consumer's Drizzle ORM type.
+ */
 export interface CreateHyperdriveDatabaseOptions<TDrizzle> {
+  /** The Hyperdrive binding for the primary (write) connection. */
   primaryHyperdrive: HyperdriveLike;
+  /** The Hyperdrive binding for the replica (read) connection. */
   replicaHyperdrive: HyperdriveLike;
-  /** 消費側の drizzle-orm で primary 接続から orm を作る factory（writes 用）。 */
+  /**
+   * Factory that builds the write ORM from the primary connection, using the consumer's
+   * `drizzle-orm`.
+   */
   createOrm: (primary: Connection) => TDrizzle;
-  /** createConnection に渡す追加オプション（timezone など）。disableEval:true は既定で付与。 */
+  /**
+   * Extra options forwarded to mysql2 `createConnection`, merged on top of the defaults applied by
+   * {@link hyperdriveConnectionOptions} (`disableEval: true`, `decimalNumbers: true`, and
+   * `timezone: '+09:00'`). Pass a field here to override any of those defaults.
+   */
   connectionOptions?: Record<string, unknown>;
 }
 
 /**
- * Hyperdrive バインディングから接続を遅延生成する Database（foodlabel の MysqlDatabase 相当）。
- * リクエスト毎に new し、レスポンス後 `dispose()` で接続を閉じる。read/write/transaction の面は同一。
+ * Create a {@link DisposableDatabase} that lazily opens its connections from Hyperdrive bindings.
+ *
+ * @remarks
+ * Construct one per request and call `dispose()` after the response to close the connections.
+ * Connections and the ORM are created on first use and reused for the lifetime of the instance; the
+ * read/write/transaction surface is identical to {@link createMysqlDatabase}.
+ *
+ * @typeParam TDrizzle - the consumer's Drizzle ORM type.
+ * @param options - the primary/replica Hyperdrive bindings, the ORM factory, and connection options.
+ * @returns a {@link DisposableDatabase} that must be disposed when done.
+ * @example
+ * ```ts
+ * const db = createHyperdriveDatabase({
+ *   primaryHyperdrive: env.PRIMARY,
+ *   replicaHyperdrive: env.REPLICA,
+ *   createOrm: (primary) => drizzle(primary, { schema, ...DRIZZLE_ORM_OPTIONS }),
+ * });
+ * try {
+ *   await db.write((dz) => dz.insert(users).values(user));
+ * } finally {
+ *   await db.dispose();
+ * }
+ * ```
  */
 export function createHyperdriveDatabase<TDrizzle>(
   options: CreateHyperdriveDatabaseOptions<TDrizzle>,
@@ -106,7 +229,15 @@ export function createHyperdriveDatabase<TDrizzle>(
   };
 }
 
-/** orm と replica 接続から Database を組み立てる内部ヘルパ。 */
+/**
+ * Internal helper that assembles a {@link Database} from an ORM and a replica connection.
+ *
+ * @typeParam TDrizzle - the consumer's Drizzle ORM type.
+ * @param orm - the Drizzle ORM used for writes and transactions.
+ * @param replica - the connection used for reads.
+ * @returns a {@link Database} wiring reads to `replica` and writes to `orm`, both with deadlock retry.
+ * @internal
+ */
 export function databaseFrom<TDrizzle>(orm: TDrizzle, replica: QueryRunner): Database<TDrizzle> {
   const drizzleLike = orm as DrizzleLike<TxOf<TDrizzle>>;
   return {
@@ -125,7 +256,12 @@ export function databaseFrom<TDrizzle>(orm: TDrizzle, replica: QueryRunner): Dat
   };
 }
 
-/** Pool/Connection は mysql2 の型。kit の QueryRunner には構造的に代入可能。 */
+/**
+ * Re-export of the mysql2 `Connection` and `Pool` types.
+ *
+ * @remarks
+ * Both are structurally assignable to the kit's {@link QueryRunner}.
+ */
 export type { Connection, Pool };
 
 function connect(hyperdrive: HyperdriveLike, extra?: Record<string, unknown>): Promise<Connection> {

package/src/db/index.ts

@@ -1,5 +1,14 @@
-// @rdlabo/workers-hono-kit/db — mysql2 依存のデータ層ヘルパ（ルート `.` は web 標準のみのため別サブパス）。
-// drizzle-orm の型同一性には依存しない（orm は消費側が渡す）。
+/**
+ * Data-layer helpers that depend on `mysql2` (exposed under the `/db` subpath because the package
+ * root is reserved for web-standard-only code).
+ *
+ * @remarks
+ * This module never depends on the type identity of `drizzle-orm`: the ORM instance is always
+ * supplied by the consumer. That keeps the kit safe to use even when the kit and the consuming app
+ * resolve separate copies of `drizzle-orm`.
+ *
+ * @packageDocumentation
+ */
 
 export { retryWhenDeadlock } from './retry.js';