@rdlabo/workers-hono-kit 0.2.0 → 0.3.0

package/dist/db/database.d.ts

@@ -1,60 +1,196 @@
 import type { Connection, Pool } from 'mysql2/promise';
 import type { HyperdriveLike } from './connection.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。
+ * Dual-connection data layer that separates reads from writes.
  *
- * 重要: kit は `drizzle-orm` の **型同一性に依存しない**。各 repo が自分の drizzle-orm で作った orm を
- * 渡す（`Database` は orm 型 `TDrizzle` にジェネリック）。これにより kit と repo で drizzle-orm の
- * コピーが分かれても（symlink 構成）`MySqlTable`/`SQL` のブランド衝突が起きない。
+ * @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`.
+ */
+/**
+ * Minimal connection interface used for reads.
+ *
+ * @remarks
+ * A mysql2 `Connection` or `Pool` satisfies this structurally.
  */
-/** reads 用の最小接続インターフェース（mysql2 Connection / Pool が構造的に満たす）。 */
 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>;
 }
+/**
+ * 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 declare function createMysqlDatabase<TDrizzle>(options: CreateMysqlDatabaseOptions<TDrizzle>): Database<TDrizzle>;
+/**
+ * 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 declare function createHyperdriveDatabase<TDrizzle>(options: CreateHyperdriveDatabaseOptions<TDrizzle>): DisposableDatabase<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 declare function databaseFrom<TDrizzle>(orm: TDrizzle, replica: QueryRunner): Database<TDrizzle>;
-/** 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 };

package/dist/db/database.js

@@ -2,15 +2,51 @@ import { createConnection } from 'mysql2/promise';
 import { hyperdriveConnectionOptions } from './connection.js';
 import { retryWhenDeadlock } from './retry.js';
 /**
- * 接続済みの 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(options) {
     return databaseFrom(options.orm, options.replica);
 }
 /**
- * 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(options) {
     const { primaryHyperdrive, replicaHyperdrive, createOrm, connectionOptions } = options;
@@ -40,7 +76,15 @@ export function createHyperdriveDatabase(options) {
         },
     };
 }
-/** 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(orm, replica) {
     const drizzleLike = orm;
     return {

package/dist/db/index.d.ts

@@ -1,3 +1,14 @@
+/**
+ * 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';
 export { createMysqlDatabase, createHyperdriveDatabase, databaseFrom } from './database.js';
 export type { Database, DisposableDatabase, QueryRunner, TxOf, CreateMysqlDatabaseOptions, CreateHyperdriveDatabaseOptions, Connection, Pool, } from './database.js';

package/dist/db/index.js

@@ -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';
 export { createMysqlDatabase, createHyperdriveDatabase, databaseFrom } from './database.js';
 export { insertIdOf, affectedRowsOf, insertedIdsOf } from './write-result.js';

package/dist/db/jst.d.ts

@@ -1,18 +1,101 @@
 /**
- * クライアント送出の日付（ISO 8601 `...Z` / `YYYY-MM-DD` / 空文字）を MySQL DATE 用の
- * `YYYY-MM-DD`（JST）へ正規化。nullish/空/解釈不能は null。MySQL DATE は ISO を弾く
- * （ER_TRUNCATED_WRONG_VALUE）ため driver では代替できず、列の toDriver に必要。
+ * 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.
+ */
+/**
+ * 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 declare function toJstDate(value: string | null | undefined): string | null;
-/** `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 declare const jstTimestampParams: (fsp?: number) => {
     dataType: () => string;
 };
-/** `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 declare const jstDatetimeParams: (fsp?: number) => {
     dataType: () => string;
 };
-/** `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 declare const jstDateParams: () => {
     dataType: () => string;
     toDriver: (value: string | null) => string | null;

package/dist/db/jst.js

@@ -1,25 +1,43 @@
-// 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) {
     if (!value) {
@@ -33,15 +51,63 @@ export function toJstDate(value) {
     const p = (n) => String(n).padStart(2, '0');
     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) => ({
     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) => ({
     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: () => 'date',
     toDriver: (value) => toJstDate(value),