@rdlabo/workers-hono-kit 0.1.0 → 0.2.1

package/src/db/database.ts

@@ -1,43 +1,108 @@
 import { createConnection } from 'mysql2/promise';
 import type { Connection, Pool } from 'mysql2/promise';
-import { hyperdriveConnectionOptions } from './connection';
-import type { HyperdriveLike } from './connection';
-import { retryWhenDeadlock } from './retry';
+import { hyperdriveConnectionOptions } from './connection.js';
+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,9 +1,18 @@
-// @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';
+export { retryWhenDeadlock } from './retry.js';
 
-export { createMysqlDatabase, createHyperdriveDatabase, databaseFrom } from './database';
+export { createMysqlDatabase, createHyperdriveDatabase, databaseFrom } from './database.js';
 export type {
   Database,
   DisposableDatabase,
@@ -13,15 +22,15 @@ export type {
   CreateHyperdriveDatabaseOptions,
   Connection,
   Pool,
-} from './database';
+} from './database.js';
 
-export { insertIdOf, affectedRowsOf, insertedIdsOf } from './write-result';
-export type { DzWriteResult } from './write-result';
+export { insertIdOf, affectedRowsOf, insertedIdsOf } from './write-result.js';
+export type { DzWriteResult } from './write-result.js';
 
-export { hyperdriveConnectionOptions, withMysqlConnections } from './connection';
-export type { HyperdriveLike, ExecutionContextLike } from './connection';
+export { hyperdriveConnectionOptions, withMysqlConnections } from './connection.js';
+export type { HyperdriveLike, ExecutionContextLike } from './connection.js';
 
-export { toJstDate, jstTimestampParams, jstDatetimeParams, jstDateParams } from './jst';
+export { toJstDate, jstTimestampParams, jstDatetimeParams, jstDateParams } from './jst.js';
 
-export { DRIZZLE_ORM_OPTIONS, honoDrizzleConfig } from './orm-config';
-export type { HonoDrizzleConfigOptions } from './orm-config';
+export { DRIZZLE_ORM_OPTIONS, honoDrizzleConfig } from './orm-config.js';
+export type { HonoDrizzleConfigOptions } from './orm-config.js';

package/src/db/jst.ts

@@ -1,27 +1,45 @@
-// JST 日時の整形を「DB 書き込みの副作用」として列の境界に寄せるための共有部品。
-// drizzle-orm の値・型は import しない（kit の脱・型同一性方針）。kit で完成した customType 列を
-// export すると、消費側と drizzle-orm のコピーが分かれた場合に `.default(sql\`…\`)` 等で `SQL` の
-// private プロパティ（shouldInlineParams）が nominal 不一致になり型衝突する（実測で確認）。そのため
-// 列生成は消費側の `customType` に委ね、kit は params とヘルパだけ供給する:
-//
-//   import { customType } from 'drizzle-orm/mysql-core';
-//   import { jstTimestampParams, jstDateParams } from '@rdlabo/workers-hono-kit/db';
-//   export const jstTimestamp = (name: string, opts?: { fsp?: number }) =>
-//     customType<{ data: string | Date; driverData: string | Date }>(jstTimestampParams(opts?.fsp))(name);
-//   export const jstDate = (name: string) =>
-//     customType<{ data: string | null; driverData: string | null }>(jstDateParams())(name);
-//
-// timestamp/datetime は toDriver を置かず Date を素通し → 接続の `timezone:'+09:00'`（hyperdrive
-// 既定）で mysql2 が JST 整形、整形済み文字列も素通し。Drizzle ネイティブ `mode:'date'` は Date を
-// tz 層より前に UTC 文字列化して −9h で壊れるため使わない（customType pass-through が唯一クリーン）。
-// date 列はクライアントの ISO/空文字を MySQL DATE が弾く＋JST 日跨ぎ正規化が要るので toJstDate を残す。
+/**
+ * Shared building blocks for normalizing JST (Asia/Tokyo) date/time values.
+ *
+ * @remarks
+ * JST normalization is applied at the column boundary as a write-time side effect, and neither
+ * values nor types from `drizzle-orm` are imported here on purpose. Exporting a fully-built
+ * `customType` column from the kit would cause type collisions when the kit and the consumer
+ * resolve separate copies of `drizzle-orm` (the private `SQL` brand stops being nominally
+ * compatible). Instead the kit ships only the params and helpers, and the consumer builds the
+ * column with its own `customType`:
+ *
+ * ```ts
+ * import { customType } from 'drizzle-orm/mysql-core';
+ * import { jstTimestampParams, jstDateParams } from '@rdlabo/workers-hono-kit/db';
+ *
+ * export const jstTimestamp = (name: string, opts?: { fsp?: number }) =>
+ *   customType<{ data: string | Date; driverData: string | Date }>(jstTimestampParams(opts?.fsp))(name);
+ * export const jstDate = (name: string) =>
+ *   customType<{ data: string | null; driverData: string | null }>(jstDateParams())(name);
+ * ```
+ *
+ * `timestamp`/`datetime` columns omit `toDriver` and pass `Date` values straight through, so the
+ * connection's `timezone: '+09:00'` default makes mysql2 format them as JST; pre-formatted strings
+ * also pass through. Drizzle's native `mode: 'date'` is avoided because it stringifies `Date` to
+ * UTC before the timezone layer, shifting values by -9h. `date` columns keep `toJstDate` because
+ * MySQL `DATE` rejects ISO/empty strings and a JST day-boundary normalization is required.
+ */
 
 const JST_OFFSET_MS = 9 * 60 * 60 * 1000;
 
 /**
- * クライアント送出の日付（ISO 8601 `...Z` / `YYYY-MM-DD` / 空文字）を MySQL DATE 用の
- * `YYYY-MM-DD`（JST）へ正規化。nullish/空/解釈不能は null。MySQL DATE は ISO を弾く
- * （ER_TRUNCATED_WRONG_VALUE）ため driver では代替できず、列の toDriver に必要。
+ * Normalize a client-supplied date to the `YYYY-MM-DD` (JST) form accepted by a MySQL `DATE` column.
+ *
+ * Accepts ISO 8601 (`...Z`), `YYYY-MM-DD`, or an empty string. Nullish, empty, or unparseable input
+ * resolves to `null`.
+ *
+ * @remarks
+ * MySQL `DATE` rejects ISO strings with `ER_TRUNCATED_WRONG_VALUE`, so this cannot be handled by the
+ * driver alone; it is needed as the `toDriver` transform for a `date` column.
+ *
+ * @param value - the raw date string from the client (ISO 8601, `YYYY-MM-DD`, or empty), or nullish.
+ * @returns the JST calendar date as `YYYY-MM-DD`, or `null` when the input is empty or unparseable.
  */
 export function toJstDate(value: string | null | undefined): string | null {
   if (!value) {
@@ -36,17 +54,65 @@ export function toJstDate(value: string | null | undefined): string | null {
   return `${jst.getUTCFullYear()}-${p(jst.getUTCMonth() + 1)}-${p(jst.getUTCDate())}`;
 }
 
-/** `customType` に渡す params: `timestamp(fsp)` 列（created_at 群）。Date 素通し（pass-through）。 */
+/**
+ * Build the params for a `customType` backing a MySQL `timestamp` column with `Date` pass-through.
+ *
+ * The column omits `toDriver`, so `Date` values flow straight to mysql2 and are formatted as JST by
+ * the connection's `timezone: '+09:00'` default.
+ *
+ * @param fsp - optional fractional-seconds precision; when provided, emits `timestamp(fsp)`.
+ * @returns the `customType` params object exposing the column's `dataType`.
+ * @example
+ * ```ts
+ * import { customType } from 'drizzle-orm/mysql-core';
+ * import { jstTimestampParams } from '@rdlabo/workers-hono-kit/db';
+ *
+ * const jstTimestamp = (name: string) =>
+ *   customType<{ data: string | Date; driverData: string | Date }>(jstTimestampParams())(name);
+ * ```
+ */
 export const jstTimestampParams = (fsp?: number): { dataType: () => string } => ({
   dataType: () => (fsp != null ? `timestamp(${fsp})` : 'timestamp'),
 });
 
-/** `customType` に渡す params: `datetime` 列（payment.limit_at 等）。Date 素通し（pass-through）。 */
+/**
+ * Build the params for a `customType` backing a MySQL `datetime` column with `Date` pass-through.
+ *
+ * Behaves like {@link jstTimestampParams} but emits a `datetime` data type; `Date` values pass
+ * through and are formatted as JST by the connection's `timezone: '+09:00'` default.
+ *
+ * @param fsp - optional fractional-seconds precision; when provided, emits `datetime(fsp)`.
+ * @returns the `customType` params object exposing the column's `dataType`.
+ * @example
+ * ```ts
+ * import { customType } from 'drizzle-orm/mysql-core';
+ * import { jstDatetimeParams } from '@rdlabo/workers-hono-kit/db';
+ *
+ * const jstDatetime = (name: string) =>
+ *   customType<{ data: string | Date; driverData: string | Date }>(jstDatetimeParams())(name);
+ * ```
+ */
 export const jstDatetimeParams = (fsp?: number): { dataType: () => string } => ({
   dataType: () => (fsp != null ? `datetime(${fsp})` : 'datetime'),
 });
 
-/** `customType` に渡す params: `date` 列（expiry_date 等）。toJstDate で文字列を正規化。 */
+/**
+ * Build the params for a `customType` backing a MySQL `date` column with JST normalization.
+ *
+ * Unlike the timestamp/datetime params, this defines a `toDriver` transform that runs
+ * {@link toJstDate} so client-supplied ISO/empty strings are normalized to a JST `YYYY-MM-DD` value
+ * the column accepts.
+ *
+ * @returns the `customType` params object exposing the column's `dataType` and `toDriver`.
+ * @example
+ * ```ts
+ * import { customType } from 'drizzle-orm/mysql-core';
+ * import { jstDateParams } from '@rdlabo/workers-hono-kit/db';
+ *
+ * const jstDate = (name: string) =>
+ *   customType<{ data: string | null; driverData: string | null }>(jstDateParams())(name);
+ * ```
+ */
 export const jstDateParams = (): {
   dataType: () => string;
   toDriver: (value: string | null) => string | null;

package/src/db/orm-config.ts

@@ -1,45 +1,87 @@
 /**
- * Drizzle の列名 casing をフリートで一元管理する（標準: snake_case を「config」と「runtime」の両方で固定）。
+ * Centralizes Drizzle column-name casing so it is fixed (standard: `snake_case`) in both the
+ * config and the runtime ORM.
  *
- * casing は2か所にあり別物:
- *   ① drizzle.config.ts の top-level `casing` … `db:generate` が **作る列名** を決める（→ honoDrizzleConfig）
- *   ② database.ts の `drizzle(conn, { …casing })` … **実行時の書き込みビルダが参照する列名** を決める（→ DRIZZLE_ORM_OPTIONS）
+ * @remarks
+ * Casing is configured in two distinct places:
  *
- * この2つが食い違うと、明示列名を書き忘れた camelCase 複数単語列で generate と実行時がズレて実行時
- * `Unknown column` になる（typecheck もマイグレーションも正常に見えるので発覚が遅い）。両方ここから取れば
- * ズレが構造的に起きない。明示列名がある列では casing は無視されるので、既存挙動は変えない純粋な安全網。
+ * 1. The top-level `casing` in `drizzle.config.ts` decides the column names that `db:generate`
+ *    **creates** (see {@link honoDrizzleConfig}).
+ * 2. The `drizzle(conn, { …casing })` call decides the column names the **runtime write builder**
+ *    resolves to (see {@link DRIZZLE_ORM_OPTIONS}).
  *
- * 注: runtime の `drizzle()` 呼び出し自体は **消費側 repo が自分の drizzle-orm で行う**（kit が drizzle() を
- * 呼ぶと kit と repo で drizzle-orm が別コピーになり型同一性が壊れるため）。kit は「値」だけを提供する。
+ * If these two disagree, a multi-word camelCase column without an explicit column name will be
+ * generated with one name but queried with another, producing a runtime `Unknown column` error —
+ * something neither the type-check nor the migration surface, so it is caught late. Sourcing both
+ * from here makes the mismatch structurally impossible. Casing is ignored for columns that declare
+ * an explicit name, so this is a pure safety net that does not change existing behavior.
+ *
+ * The runtime `drizzle()` call itself is made by the consuming app with its own `drizzle-orm`; the
+ * kit only ever provides values, never the ORM instance, to avoid splitting `drizzle-orm` into two
+ * copies and breaking type identity.
  */
 
 /**
- * runtime 用。消費側 repo の database.ts で `drizzle(conn, { schema, ...DRIZZLE_ORM_OPTIONS })` と spread して使う。
- * mode/casing を kit が固定し、書き込みビルダの列名解決を snake_case に揃える。
+ * Runtime ORM options shared by the consuming app's `drizzle()` call.
+ *
+ * Spread into the runtime ORM as `drizzle(conn, { schema, ...DRIZZLE_ORM_OPTIONS })` so the write
+ * builder resolves column names as `snake_case`, matching what `db:generate` creates.
+ *
+ * @remarks
+ * Fixes `mode: 'default'` and `casing: 'snake_case'`. See the module-level documentation for why
+ * the same casing must be used by both the config and the runtime ORM.
  */
 export const DRIZZLE_ORM_OPTIONS = { mode: 'default', casing: 'snake_case' } as const;
 
+/**
+ * Options for {@link honoDrizzleConfig}.
+ */
 export interface HonoDrizzleConfigOptions {
-  /** drizzle-kit の dbCredentials.database（localConnectionString とは別）。 */
+  /** drizzle-kit `dbCredentials.database` — the database name to connect to. */
   database: string;
+  /** Database host; defaults to `process.env.DB_HOST` then `127.0.0.1`. */
   host?: string;
+  /** Database port; defaults to `process.env.DB_PORT` then `3306`. */
   port?: number;
+  /** Database user; defaults to `process.env.DB_USER` then `root`. */
   user?: string;
+  /** Database password; defaults to `process.env.DB_PASSWORD` then `root`. */
   password?: string;
-  /** 既定 './src/db/schemes'。 */
+  /** Path to the schema directory; defaults to `'./src/db/schemes'`. */
   schema?: string;
-  /** 既定 './drizzle'。 */
+  /** Output directory for generated migrations; defaults to `'./drizzle'`. */
   out?: string;
-  /** /api と DB を共有する repo は schema 由来テーブルに限定する（省略可）。 */
+  /**
+   * Optional table allow-list. Use this to restrict drizzle-kit to the schema's own tables when the
+   * database is shared with another application.
+   */
   tablesFilter?: string[];
-  /** db:introspect（DB→JS）の casing。生成方向の `casing:'snake_case'` とは別軸（省略可）。 */
+  /**
+   * Optional `db:introspect` (DB → JS) casing. This is an independent axis from the generation-side
+   * `casing: 'snake_case'` and only affects introspection output.
+   */
   introspect?: { casing: 'camel' | 'preserve' };
 }
 
 /**
- * drizzle.config.ts 用ファクトリ。`export default honoDrizzleConfig({ database })` で使う。
- * casing:'snake_case'・schema/out・dbCredentials（env 既定）を kit が owner として固定する。
- * drizzle-kit を kit の依存にしないため plain object を返す（drizzle-kit CLI は default export を読むだけ）。
+ * Build a `drizzle.config.ts` configuration object with the kit's standard defaults.
+ *
+ * Fixes `casing: 'snake_case'`, the `schema`/`out` paths, and `dbCredentials` (with env-based
+ * defaults), while leaving `tablesFilter` and `introspect` opt-in.
+ *
+ * @remarks
+ * Returns a plain object rather than a typed drizzle-kit config so that `drizzle-kit` need not be a
+ * dependency of the kit; the drizzle-kit CLI only reads the default export.
+ *
+ * @param options - configuration overrides; only `database` is required.
+ * @returns a plain configuration object suitable for `export default` in `drizzle.config.ts`.
+ * @example
+ * ```ts
+ * // drizzle.config.ts
+ * import { honoDrizzleConfig } from '@rdlabo/workers-hono-kit/db';
+ *
+ * export default honoDrizzleConfig({ database: 'app' });
+ * ```
  */
 export function honoDrizzleConfig(options: HonoDrizzleConfigOptions) {
   const {

package/src/db/retry.ts

@@ -1,7 +1,29 @@
 /**
- * ER_LOCK_DEADLOCK を指数バックオフで retry する（NestJS/TypeORM の retryWhenDeadlock 相当）。
- * MySQL はデッドロック時にトランザクション全体をロールバックするため、同じ作業単位の再実行は安全。
- * `fn` は単一文（write）またはトランザクション全体（transaction）であること — retry は `fn` 全体を再実行する。
+ * Run an async unit of work, retrying it on MySQL deadlock errors with exponential backoff.
+ *
+ * Retries are triggered only by the `ER_LOCK_DEADLOCK` error code. Each failed attempt waits
+ * `delay * attempt` milliseconds (linear growth of the base delay) before the next try, and any
+ * non-deadlock error is rethrown immediately without retrying.
+ *
+ * @remarks
+ * MySQL rolls back the entire transaction when it detects a deadlock, so re-running the same unit
+ * of work is safe. Pass a `fn` that represents one complete unit — a single statement or an entire
+ * transaction — because the whole `fn` is re-executed on each retry.
+ *
+ * @typeParam T - resolved value produced by `fn`.
+ * @param fn - the unit of work to execute; it is invoked again from scratch on each retry.
+ * @param retries - maximum number of attempts (default `3`).
+ * @param delay - base backoff in milliseconds; attempt N waits `delay * N` (default `100`).
+ * @returns the value resolved by the first successful call to `fn`.
+ * @throws the last error thrown by `fn` once retries are exhausted, or any non-deadlock error on
+ * the first occurrence.
+ * @example
+ * ```ts
+ * await retryWhenDeadlock(() => db.transaction(async (tx) => {
+ *   await tx.insert(orders).values(order);
+ *   await tx.update(stock).set({ qty: sql`qty - 1` }).where(eq(stock.id, order.itemId));
+ * }));
+ * ```
  */
 export async function retryWhenDeadlock<T>(fn: () => Promise<T>, retries = 3, delay = 100): Promise<T> {
   for (let attempt = 0; attempt < retries; attempt++) {

package/src/db/write-result.ts

@@ -1,21 +1,44 @@
 /**
- * Drizzle(mysql2) の write 結果から insertId / affectedRows を型安全に取り出すヘルパ。
- * 生の builder/ResultSetHeader を repo 側に晒さずに、よく使う値だけを取り出す。
+ * Shape of a Drizzle (mysql2) write result, narrowed to the fields callers actually read.
  *
- * mysql2 の INSERT/UPDATE/DELETE 結果は `[ResultSetHeader, FieldPacket[]]` 形。
+ * @remarks
+ * A mysql2 INSERT/UPDATE/DELETE result is the tuple `[ResultSetHeader, FieldPacket[]]`. Typing the
+ * result this way lets repositories extract the common values without exposing the raw query
+ * builder or the full `ResultSetHeader` to the rest of the codebase.
  */
 export type DzWriteResult = readonly [{ insertId: number; affectedRows: number }, ...unknown[]];
 
+/**
+ * Extract the auto-increment `insertId` from a write result.
+ *
+ * @param result - the result of a Drizzle (mysql2) INSERT/UPDATE/DELETE.
+ * @returns the `insertId` reported by mysql2 (the id of the first inserted row).
+ */
 export function insertIdOf(result: DzWriteResult): number {
   return result[0].insertId;
 }
 
+/**
+ * Extract the number of affected rows from a write result.
+ *
+ * @param result - the result of a Drizzle (mysql2) INSERT/UPDATE/DELETE.
+ * @returns the `affectedRows` count reported by mysql2.
+ */
 export function affectedRowsOf(result: DzWriteResult): number {
   return result[0].affectedRows;
 }
 
 /**
- * 一括 INSERT で連番採番された行の id 群を返す（mysql2 は先頭 insertId のみ返すため count 分を生成）。
+ * Reconstruct the auto-increment ids assigned by a bulk INSERT.
+ *
+ * @remarks
+ * mysql2 reports only the first `insertId` for a multi-row INSERT, so the remaining ids are derived
+ * by assuming a contiguous sequence (`base`, `base + 1`, …). This holds for tables with a standard
+ * `AUTO_INCREMENT` column and the default `innodb_autoinc_lock_mode`.
+ *
+ * @param result - the result of a bulk INSERT.
+ * @param count - the number of rows that were inserted.
+ * @returns an array of the `count` auto-increment ids, starting at the reported `insertId`.
  */
 export function insertedIdsOf(result: DzWriteResult, count: number): number[] {
   const base = result[0].insertId;