@rdlabo/workers-hono-kit 0.3.6 → 0.4.0

package/README.md

@@ -41,6 +41,7 @@ npm install ai ai-gateway-provider    # createAiGatewayProvider
 > | --- | --- | --- |
 > | `.` | `@rdlabo/workers-hono-kit` | Web-standard helpers (middleware, HTTP, Firebase, AWS, AI, Stripe, KV). |
 > | `./db` | `@rdlabo/workers-hono-kit/db` | MySQL data layer (mysql2 + Drizzle). |
+> | `./business-time` | `@rdlabo/workers-hono-kit/business-time` | JST 業務時刻 API（`toBusinessDateTime` / `normalizeBusinessDate` 等）。 |
 > | `./testing` | `@rdlabo/workers-hono-kit/testing` | Test helpers (mysql2 + Drizzle + fakes/fixtures). |
 
 ## API
@@ -66,12 +67,16 @@ npm install ai ai-gateway-provider    # createAiGatewayProvider
 | `HttpStatus` | HTTP status enum identical to NestJS `@nestjs/common`. |
 | `createNestErrorHandler(options?)` / `NestErrorHandlerOptions` | `app.onError()` handler that maps a thrown `HTTPException` to the NestJS exception-filter body (`{ statusCode, message, error? }`; `401` omits `error`). Configurable field order, reason phrases, error predicate, and unhandled-error report hook. |
 | `nestNotFoundHandler(c)` | `app.notFound()` handler with the Express/Nest default `{ message: 'Cannot METHOD path', error, statusCode }` 404 body. |
+| `normalizeTrailingSlash(request)` | Strip trailing slash(es) from the request URL before routing (Express/Nest parity). Does **not** 301-redirect — preserves POST/PUT/DELETE bodies. |
 | `NEST_REASON_PHRASES` | `{ 400, 401, 403, 404 }` → NestJS reason phrases. |
 | `createAuthMiddleware(options)` / `AuthMiddlewareOptions` | Factory for a Firebase-token auth middleware: reads the token header, verifies, resolves the DB user id, and stashes the result on the context. Omit `resolveUserId` for a token-only (login) guard. |
 | `ErrorReporter` / `ErrorReportContext` | Types for a `reportError`-style unhandled-error reporter (e.g. wired to Sentry), paired with `createNestErrorHandler`'s `onUnhandledError`. |
 | `createAiGatewayProvider(config)` / `AiGatewayConfig` / `AiGatewayProvider` | Route `@ai-sdk` models through the Cloudflare AI Gateway, via either a Workers `AI` binding or REST credentials (`accountId` / `gateway` / `token`). |
 | `KVCache` / `KVNamespace` / `KVCacheOptions` | Workers-KV cache-aside helper (key `appName+version+table_type_column`, sha256 for string ids, TTL clamped ≥60s). Set `appName` / `version` per application. |
 | `createStripeClient(secret, opts?)` / `verifyStripeWebhook(...)` / `CreateStripeClientOptions` | Workers-native Stripe client (fetch transport) + async webhook verification (SubtleCrypto). `apiVersion` optional (pin to a fixed Stripe API version). |
+| `sendInChunks(queue, messages, chunkSize?)` / `QueueLike` / `QueueSendMessage` | Send queue messages in bounded chunks to stay under the Workers subrequest cap per invocation. |
+| `processBatch(batch, handler, options?)` / `MessageBatchLike` / `QueueMessageLike` / `ProcessBatchOptions` / `ProcessBatchResult` | Process a queue batch with bounded concurrency (consumer-side counterpart to `sendInChunks`). |
+| `ExecutionContextLike` | Minimal `waitUntil`-only Workers execution context shape (for `withMysqlConnections` in worker entry modules without importing `./db`). |
 
 ### Data layer — `@rdlabo/workers-hono-kit/db`
 
@@ -81,13 +86,47 @@ Requires the `drizzle-orm` and `mysql2` peers. Reads run against a replica via r
 | --- | --- |
 | `createHyperdriveDatabase(options)` | `DisposableDatabase` that lazily opens primary/replica connections from Hyperdrive bindings per request; `dispose()` closes them. |
 | `createMysqlDatabase(options)` | Assemble a `Database` from an already-connected Drizzle ORM + replica `QueryRunner`. |
+| `databaseFrom(orm, replica)` | Build a `Database` from an existing Drizzle instance + replica handle. |
 | `Database` / `DisposableDatabase` / `QueryRunner` / `TxOf` | The `read` / `write` / `transaction` API and its supporting types. |
 | `hyperdriveConnectionOptions(hyperdrive, overrides?)` / `HyperdriveLike` / `ExecutionContextLike` | Build mysql2 `createConnection` options from a Hyperdrive binding (`disableEval`, `decimalNumbers`, `timezone '+09:00'` by default). |
 | `withMysqlConnections(...)` | Open primary/replica connections, run a function, close them in `finally` (via `ctx.waitUntil`). |
 | `retryWhenDeadlock(fn, retries?, delay?)` | Same deadlock-retry helper as the root export. |
 | `insertIdOf` / `affectedRowsOf` / `insertedIdsOf` / `DzWriteResult` | Extract `insertId` / `affectedRows` (and derive contiguous bulk-insert ids) from a mysql2 write result. |
-| `toJstDate` / `jstTimestampParams` / `jstDatetimeParams` / `jstDateParams` | JST date/time normalization applied at the Drizzle `customType` column boundary. |
+| `toJstDate` / `jstTimestampParams` / `jstDatetimeParams` / `jstDateParams` | JST date/time normalization params（高度な用途）。 |
+| `jstTimestamp` / `jstDatetime` / `jstDate` / `decimalNumber` | Drizzle 列ヘルパー（repo 側ラッパー不要）。 |
+| `jstOnUpdateNow` | `ON UPDATE CURRENT_TIMESTAMP` 用 SQL 式。`jstTimestamp` 等の customType は `.onUpdateNow()` 非対応のため `.$onUpdateFn(() => jstOnUpdateNow(fsp))` と併用。 |
+| `coerceDecimalNumber` / `decimalNumberParams` | DECIMAL 正規化 params（通常は `decimalNumber` 列ヘルパーで十分）。 |
 | `DRIZZLE_ORM_OPTIONS` / `honoDrizzleConfig(options)` / `HonoDrizzleConfigOptions` | Shared Drizzle casing (`snake_case`) for both the runtime `drizzle()` call and `drizzle.config.ts`, keeping config ↔ runtime in sync. |
+| `resolveDbSecret(options, secretId?)` / `ResolvedDbSecret` | Resolve RDS-managed or plain DB credentials from AWS Secrets Manager for CI migrate / local tooling. |
+| `baselineMigrations(options)` / `readBaselineEntry(migrationsFolder)` / `BaselineMigrationsOptions` / `BaselineResult` / `BaselineEntry` | Brownfield first-deploy helper: mark an existing `0000_*` migration as applied without re-running DDL. |
+
+#### Drizzle 列ヘルパー（`jstTimestamp` / `decimalNumber` 等）
+
+- `drizzle-orm` は **peer** のみ。kit は `drizzle-orm` を依存に含めない（publish 後も consumer の 1 本を使う）。
+- consumer は通常どおり `drizzle-orm` を `dependencies` に置くだけでよい。**`package.json` の `overrides` は不要**。
+- npm publish 物には `devDependencies` は含まれないため、インストール先で kit 専用の `drizzle-orm` は増えない（peer の 1 本のみ）。
+- 列ヘルパーは runtime で consumer の `drizzle-orm` を `import` し、型は `customType` 推論そのまま（`MySqlCustomColumnBuilder<…>`）。`any` は使わないので consumer テーブルの `$inferSelect` に列の意味型が伝播する。
+- **前提: drizzle を単一コピーに解決すること。** drizzle の `SQL` は private フィールド `shouldInlineParams` を持つ**名目型**で、kit と consumer が別コピーを解決すると `jstTimestamp(…).default(sql\`…\`)` が `TS2345 separate declarations of a private property 'shouldInlineParams'` で全 schema 落ちする。`file:` リンク開発では kit 配下に `drizzle-orm` がネストして二重コピーになるため、**consumer の `tsconfig.json` で `drizzle-orm` を自身の 1 コピーへ固定**する:
+
+  ```jsonc
+  // tsconfig.json compilerOptions（既存 paths があればマージ）
+  "paths": {
+    "drizzle-orm": ["./node_modules/drizzle-orm"],
+    "drizzle-orm/*": ["./node_modules/drizzle-orm/*"]
+  }
+  ```
+
+  `moduleResolution: "Bundler"` なら `baseUrl` 不要（`baseUrl` 設定済みなら先頭 `./` は外す）。published 版（単一コピー）ではこの `paths` は無害。**overrides は不要。**
+- `file:` で kit を直リンクする開発では、kit リポジトリ側で `npm install` して peer を満たす（consumer 側で overrides を足さない）。
+
+**`CURRENT_TIMESTAMP` と接続 `timezone:'+09:00'` の違い**
+
+| 経路 | 誰が時刻を決めるか | JST との関係 |
+| --- | --- | --- |
+| アプリが `Date` を bind（INSERT/UPDATE） | mysql2 + 接続 `timezone:'+09:00'` | ワイヤ上は JST として扱われる（`datetime-wire` テスト） |
+| `DEFAULT CURRENT_TIMESTAMP` / `ON UPDATE CURRENT_TIMESTAMP` | MySQL サーバ（セッション `time_zone`） | 接続オプションとは**別経路**。RDS の `time_zone` が `+09:00` なら JST、UTC なら UTC |
+
+`jstTimestamp` / `jstDatetime` は読書の pass-through と DATE 正規化のみ担当し、DB 既定値の時刻帯は変えない。`ON UPDATE` が必要な列は `.$onUpdateFn(() => jstOnUpdateNow(6))` で DDL 意図を維持する。
 
 ### Testing — `@rdlabo/workers-hono-kit/testing`
 

package/dist/business-time/index.d.ts

@@ -0,0 +1,49 @@
+/**
+ * JST 業務時刻の明示 API（Workers UTC instant ↔ 業務暦日/日時）。
+ *
+ * @remarks
+ * - DB は JST 運用のまま。アプリは mysql2 `timezone` に暗黙依存せず、ここ経由で JST を扱う。
+ * - MySQL ワイヤ形式への変換は {@link ../db/jst.js | db/jst} の責務。
+ * - `Date` の local getter（`getHours` 等）は業務判定に使わない。
+ *
+ * @packageDocumentation
+ */
+import { BUSINESS_TIMEZONE } from './types.js';
+import type { BusinessDate, BusinessDateTime } from './types.js';
+export { BUSINESS_TIMEZONE, type BusinessDate, type BusinessDateTime };
+/** 参照 instant の JST 業務暦日。 */
+export declare function today(ref?: Date): BusinessDate;
+/** UTC instant → JST 業務暦日。 */
+export declare function toBusinessDate(instant: Date): BusinessDate;
+/**
+ * クライアント / DB 入力を JST 業務暦日 `YYYY-MM-DD` へ正規化する。
+ *
+ * - 既に `YYYY-MM-DD` の文字列は **Date 化せず**そのまま返す（誕生日は instant ではない）。
+ * - ISO 8601 等は instant 経由で JST 暦日へ変換。
+ * - nullish / 空 / 不正は `null`。
+ */
+export declare function normalizeBusinessDate(value: string | Date | null | undefined): BusinessDate | null;
+/** UTC instant → JST 業務日時（`YYYY-MM-DD HH:mm:ss`）。 */
+export declare function toBusinessDateTime(instant: Date): BusinessDateTime;
+/** Nest / foodlabel / winecode `helper.formatDate` 既定パターン。 */
+export declare const DEFAULT_BUSINESS_DATETIME_PATTERN: "YYYY-MM-DDThh:mm:ss";
+/**
+ * Nest `helper.formatDate` 互換のパターン整形（業務 TZ）。
+ * `S` トークンは元 instant のミリ秒（Nest 正本）。
+ */
+export declare function formatBusinessDateTime(instant: Date, pattern?: string): string;
+/** JST 業務日時文字列 → UTC instant。`YYYY-MM-DD HH:mm:ss` / `T` 区切りを受け付ける。 */
+export declare function parseBusinessDateTime(value: BusinessDateTime): Date;
+/** JST 業務暦日の 00:00:00 を表す UTC instant。 */
+export declare function startOfBusinessDay(date: BusinessDate): Date;
+/** JST 業務暦日の 23:59:59 を表す UTC instant。 */
+export declare function endOfBusinessDay(date: BusinessDate): Date;
+/**
+ * JST 業務暦日 + 壁時計時刻 → UTC instant。
+ * @example businessDateTimeInstant('2026-07-05', '06:00:00')
+ */
+export declare function businessDateTimeInstant(date: BusinessDate, time: string): Date;
+/** JST 業務暦日に日数を加算（暦日単位）。 */
+export declare function addBusinessDays(date: BusinessDate, days: number): BusinessDate;
+/** 業務暦日基準の満年齢（誕生日は instant ではなく BusinessDate）。 */
+export declare function ageOnBusinessDate(birthDate: BusinessDate, asOfDate?: BusinessDate): number;

package/dist/business-time/index.js

@@ -0,0 +1,149 @@
+/**
+ * JST 業務時刻の明示 API（Workers UTC instant ↔ 業務暦日/日時）。
+ *
+ * @remarks
+ * - DB は JST 運用のまま。アプリは mysql2 `timezone` に暗黙依存せず、ここ経由で JST を扱う。
+ * - MySQL ワイヤ形式への変換は {@link ../db/jst.js | db/jst} の責務。
+ * - `Date` の local getter（`getHours` 等）は業務判定に使わない。
+ *
+ * @packageDocumentation
+ */
+import { BUSINESS_TIMEZONE } from './types.js';
+export { BUSINESS_TIMEZONE };
+const pad2 = (n) => String(n).padStart(2, '0');
+/** instant を業務 TZ 壁時計として読むためのシフト（`getUTC*` で成分を得る）。 */
+function toWallClock(instant) {
+    return new Date(instant.getTime() + BUSINESS_TIMEZONE.offsetMinutes * 60_000);
+}
+function parseYmd(date) {
+    const m = /^(\d{4})-(\d{2})-(\d{2})$/.exec(date);
+    if (!m) {
+        throw new RangeError(`Invalid BusinessDate: ${date}`);
+    }
+    return [Number(m[1]), Number(m[2]), Number(m[3])];
+}
+function parseHms(time) {
+    const m = /^(\d{1,2}):(\d{2})(?::(\d{2}))?$/.exec(time);
+    if (!m) {
+        throw new RangeError(`Invalid business time: ${time}`);
+    }
+    return [Number(m[1]), Number(m[2]), Number(m[3] || 0)];
+}
+/** 参照 instant の JST 業務暦日。 */
+export function today(ref = new Date()) {
+    return toBusinessDate(ref);
+}
+/** UTC instant → JST 業務暦日。 */
+export function toBusinessDate(instant) {
+    const wall = toWallClock(instant);
+    return `${wall.getUTCFullYear()}-${pad2(wall.getUTCMonth() + 1)}-${pad2(wall.getUTCDate())}`;
+}
+/**
+ * クライアント / DB 入力を JST 業務暦日 `YYYY-MM-DD` へ正規化する。
+ *
+ * - 既に `YYYY-MM-DD` の文字列は **Date 化せず**そのまま返す（誕生日は instant ではない）。
+ * - ISO 8601 等は instant 経由で JST 暦日へ変換。
+ * - nullish / 空 / 不正は `null`。
+ */
+export function normalizeBusinessDate(value) {
+    if (value == null) {
+        return null;
+    }
+    if (value instanceof Date) {
+        if (Number.isNaN(value.getTime())) {
+            return null;
+        }
+        return toBusinessDate(value);
+    }
+    const trimmed = value.trim();
+    if (!trimmed) {
+        return null;
+    }
+    if (/^\d{4}-\d{2}-\d{2}$/.test(trimmed)) {
+        return trimmed;
+    }
+    const isoDatePrefix = /^(\d{4}-\d{2}-\d{2})/.exec(trimmed);
+    if (isoDatePrefix && !trimmed.includes('T') && !trimmed.includes(' ')) {
+        return isoDatePrefix[1];
+    }
+    const ms = new Date(trimmed).getTime();
+    if (Number.isNaN(ms)) {
+        return null;
+    }
+    return toBusinessDate(new Date(ms));
+}
+/** UTC instant → JST 業務日時（`YYYY-MM-DD HH:mm:ss`）。 */
+export function toBusinessDateTime(instant) {
+    const wall = toWallClock(instant);
+    return `${wall.getUTCFullYear()}-${pad2(wall.getUTCMonth() + 1)}-${pad2(wall.getUTCDate())} ${pad2(wall.getUTCHours())}:${pad2(wall.getUTCMinutes())}:${pad2(wall.getUTCSeconds())}`;
+}
+/** Nest / foodlabel / winecode `helper.formatDate` 既定パターン。 */
+export const DEFAULT_BUSINESS_DATETIME_PATTERN = 'YYYY-MM-DDThh:mm:ss';
+/**
+ * Nest `helper.formatDate` 互換のパターン整形（業務 TZ）。
+ * `S` トークンは元 instant のミリ秒（Nest 正本）。
+ */
+export function formatBusinessDateTime(instant, pattern = DEFAULT_BUSINESS_DATETIME_PATTERN) {
+    const wall = toWallClock(instant);
+    let out = pattern;
+    out = out.replace(/YYYY/g, String(wall.getUTCFullYear()));
+    out = out.replace(/MM/g, pad2(wall.getUTCMonth() + 1));
+    out = out.replace(/DD/g, pad2(wall.getUTCDate()));
+    out = out.replace(/hh/g, pad2(wall.getUTCHours()));
+    out = out.replace(/mm/g, pad2(wall.getUTCMinutes()));
+    out = out.replace(/ss/g, pad2(wall.getUTCSeconds()));
+    const matched = out.match(/S/g);
+    if (matched) {
+        const milliSeconds = String(instant.getMilliseconds()).padStart(3, '0');
+        const length = matched.length;
+        for (let i = 0; i < length; i++) {
+            out = out.replace(/S/, milliSeconds.substring(i, i + 1));
+        }
+    }
+    return out;
+}
+/** JST 業務日時文字列 → UTC instant。`YYYY-MM-DD HH:mm:ss` / `T` 区切りを受け付ける。 */
+export function parseBusinessDateTime(value) {
+    const normalized = value.includes('T') ? value.replace('T', ' ') : value;
+    const m = /^(\d{4})-(\d{2})-(\d{2}) (\d{2}):(\d{2}):(\d{2})$/.exec(normalized);
+    if (!m) {
+        throw new RangeError(`Invalid BusinessDateTime: ${value}`);
+    }
+    const [, y, mo, d, h, mi, s] = m;
+    const offsetHours = BUSINESS_TIMEZONE.offsetMinutes / 60;
+    return new Date(Date.UTC(Number(y), Number(mo) - 1, Number(d), Number(h) - offsetHours, Number(mi), Number(s), 0));
+}
+/** JST 業務暦日の 00:00:00 を表す UTC instant。 */
+export function startOfBusinessDay(date) {
+    return businessDateTimeInstant(date, '00:00:00');
+}
+/** JST 業務暦日の 23:59:59 を表す UTC instant。 */
+export function endOfBusinessDay(date) {
+    return businessDateTimeInstant(date, '23:59:59');
+}
+/**
+ * JST 業務暦日 + 壁時計時刻 → UTC instant。
+ * @example businessDateTimeInstant('2026-07-05', '06:00:00')
+ */
+export function businessDateTimeInstant(date, time) {
+    const [y, mo, d] = parseYmd(date);
+    const [h, mi, s] = parseHms(time);
+    const offsetHours = BUSINESS_TIMEZONE.offsetMinutes / 60;
+    return new Date(Date.UTC(y, mo - 1, d, h - offsetHours, mi, s, 0));
+}
+/** JST 業務暦日に日数を加算（暦日単位）。 */
+export function addBusinessDays(date, days) {
+    const anchor = businessDateTimeInstant(date, '12:00:00');
+    return toBusinessDate(new Date(anchor.getTime() + days * 24 * 60 * 60 * 1000));
+}
+/** 業務暦日基準の満年齢（誕生日は instant ではなく BusinessDate）。 */
+export function ageOnBusinessDate(birthDate, asOfDate) {
+    const asOf = asOfDate ?? today();
+    const [by, bm, bd] = parseYmd(birthDate);
+    const [ay, am, ad] = parseYmd(asOf);
+    let age = ay - by;
+    if (am < bm || (am === bm && ad < bd)) {
+        age--;
+    }
+    return age;
+}

package/dist/business-time/types.d.ts

@@ -0,0 +1,9 @@
+/** JST 業務暦日 `YYYY-MM-DD`（instant ではない）。 */
+export type BusinessDate = string;
+/** JST 業務日時 `YYYY-MM-DD HH:mm:ss`（MySQL DATETIME 互換の壁時計表現）。 */
+export type BusinessDateTime = string;
+/** JST 業務タイムゾーン定数（Workers は UTC instant、業務はここで明示）。 */
+export declare const BUSINESS_TIMEZONE: {
+    readonly iana: "Asia/Tokyo";
+    readonly offsetMinutes: 540;
+};

package/dist/business-time/types.js

@@ -0,0 +1,5 @@
+/** JST 業務タイムゾーン定数（Workers は UTC instant、業務はここで明示）。 */
+export const BUSINESS_TIMEZONE = {
+    iana: 'Asia/Tokyo',
+    offsetMinutes: 540,
+};

package/dist/db/columns.d.ts

@@ -0,0 +1,46 @@
+import type { DecimalNumberConfig } from './decimal.js';
+/**
+ * `ON UPDATE CURRENT_TIMESTAMP` 用式（MySQL セッション時刻）。
+ * customType 列は `.onUpdateNow()` が無いため `.$onUpdateFn(() => jstOnUpdateNow(fsp))` と併用する。
+ */
+export declare const jstOnUpdateNow: (fsp?: number) => import("drizzle-orm").SQL<unknown>;
+/** MySQL `timestamp` — pass-through。Date は接続 `timezone:'+09:00'` で mysql2 が JST 整形。 */
+export declare const jstTimestamp: (name: string, opts?: {
+    fsp?: number;
+}) => import("drizzle-orm/mysql-core").MySqlCustomColumnBuilder<{
+    name: string;
+    dataType: "custom";
+    columnType: "MySqlCustomColumn";
+    data: string | Date;
+    driverParam: string | Date;
+    enumValues: undefined;
+}>;
+/** MySQL `datetime` — {@link jstTimestamp} と同じ pass-through 方針。 */
+export declare const jstDatetime: (name: string, opts?: {
+    fsp?: number;
+}) => import("drizzle-orm/mysql-core").MySqlCustomColumnBuilder<{
+    name: string;
+    dataType: "custom";
+    columnType: "MySqlCustomColumn";
+    data: string | Date;
+    driverParam: string | Date;
+    enumValues: undefined;
+}>;
+/** MySQL `date` — INSERT/UPDATE 時に ISO / 空文字を `YYYY-MM-DD` へ正規化（`toDriver`）。 */
+export declare const jstDate: (name: string) => import("drizzle-orm/mysql-core").MySqlCustomColumnBuilder<{
+    name: string;
+    dataType: "custom";
+    columnType: "MySqlCustomColumn";
+    data: string | null;
+    driverParam: string | null;
+    enumValues: undefined;
+}>;
+/** MySQL `decimal` — SELECT は `fromDriver` で string→number、書込は number をそのまま bind。 */
+export declare const decimalNumber: (name: string, config: DecimalNumberConfig) => import("drizzle-orm/mysql-core").MySqlCustomColumnBuilder<{
+    name: string;
+    dataType: "custom";
+    columnType: "MySqlCustomColumn";
+    data: number | null;
+    driverParam: string | number | null;
+    enumValues: undefined;
+}>;

package/dist/db/columns.js

@@ -0,0 +1,36 @@
+/**
+ * Drizzle 列ヘルパー（フリート共通）。各 repo の `custom-types.ts` / `columns.ts` 薄いラッパーは不要。
+ *
+ * @remarks
+ * `drizzle-orm` は **peer**（consumer が 1 本解決）。kit は `drizzle-orm` を bundled しない。
+ * 戻り型は `customType` 推論そのまま（`MySqlCustomColumnBuilder<…>`）で `any` を使わない。
+ * これにより consumer テーブルの `$inferSelect` に列の意味型（`string | Date` / `number | null` など）が伝播する。
+ *
+ * **前提（単一 drizzle コピー）**: drizzle の `SQL` は private フィールド `shouldInlineParams` を持つ
+ * **名目型**なので、kit と consumer が drizzle の別コピーを解決すると
+ * `jstTimestamp(…).default(sql\`…\`)` が `TS2345: separate declarations of a private property
+ * 'shouldInlineParams'` で落ちる。フリートは kit を `file:` リンク参照するため kit 配下に drizzle が
+ * ネストし二重コピーになりやすい。consumer 側 tsconfig の `paths` で `drizzle-orm` を **自身の 1 コピーへ
+ * 固定**して単一化すること（README「Drizzle 列ヘルパー」参照）。published 版（単一コピー）ではそのまま単一。
+ *
+ * **DEFAULT / ON UPDATE CURRENT_TIMESTAMP** … MySQL サーバ側の既定値（列を省略した INSERT / UPDATE）。
+ * 接続 `timezone:'+09:00'`（{@link hyperdriveConnectionOptions}）が効くのは **アプリから Date を bind するとき**。
+ * 両者を混同しないこと（`datetime-wire` / `drizzle-smoke` の JST テスト参照）。
+ */
+import { sql } from 'drizzle-orm';
+import { customType } from 'drizzle-orm/mysql-core';
+import { decimalNumberParams } from './decimal.js';
+import { jstDateParams, jstDatetimeParams, jstTimestampParams } from './jst.js';
+/**
+ * `ON UPDATE CURRENT_TIMESTAMP` 用式（MySQL セッション時刻）。
+ * customType 列は `.onUpdateNow()` が無いため `.$onUpdateFn(() => jstOnUpdateNow(fsp))` と併用する。
+ */
+export const jstOnUpdateNow = (fsp) => fsp != null ? sql `(CURRENT_TIMESTAMP(${sql.raw(String(fsp))}))` : sql `(CURRENT_TIMESTAMP)`;
+/** MySQL `timestamp` — pass-through。Date は接続 `timezone:'+09:00'` で mysql2 が JST 整形。 */
+export const jstTimestamp = (name, opts) => customType(jstTimestampParams(opts?.fsp))(name);
+/** MySQL `datetime` — {@link jstTimestamp} と同じ pass-through 方針。 */
+export const jstDatetime = (name, opts) => customType(jstDatetimeParams(opts?.fsp))(name);
+/** MySQL `date` — INSERT/UPDATE 時に ISO / 空文字を `YYYY-MM-DD` へ正規化（`toDriver`）。 */
+export const jstDate = (name) => customType(jstDateParams())(name);
+/** MySQL `decimal` — SELECT は `fromDriver` で string→number、書込は number をそのまま bind。 */
+export const decimalNumber = (name, config) => customType(decimalNumberParams(config))(name);

package/dist/db/connection.d.ts

@@ -1,4 +1,6 @@
 import type { Connection } from 'mysql2/promise';
+import type { ExecutionContextLike } from '../http/execution-context.js';
+export type { ExecutionContextLike } from '../http/execution-context.js';
 /**
  * Minimal structural shape of a Cloudflare Hyperdrive binding.
  *
@@ -40,16 +42,6 @@ export interface HyperdriveLike {
  * @returns a plain options object to pass to mysql2 `createConnection`.
  */
 export declare function hyperdriveConnectionOptions(hyperdrive: HyperdriveLike, extra?: Record<string, unknown>): Record<string, unknown>;
-/**
- * Minimal structural shape of a Workers `ExecutionContext`, limited to `waitUntil`.
- *
- * @remarks
- * Declared structurally to avoid a dependency on `@cloudflare/workers-types`.
- */
-export interface ExecutionContextLike {
-    /** Extend the request's lifetime until `promise` settles (used to close connections after the response). */
-    waitUntil(promise: Promise<unknown>): void;
-}
 /**
  * Open primary and replica connections, run `fn` with them, and close both afterwards.
  *

package/dist/db/connection.js

@@ -1,4 +1,5 @@
 import { createConnection } from 'mysql2/promise';
+import { MYSQL_TIMEZONE } from './jst.js';
 /**
  * Build mysql2 `createConnection` options from a Hyperdrive binding, applying the kit's defaults.
  *
@@ -29,7 +30,7 @@ export function hyperdriveConnectionOptions(hyperdrive, extra) {
         port: hyperdrive.port,
         disableEval: true,
         decimalNumbers: true,
-        timezone: '+09:00',
+        timezone: MYSQL_TIMEZONE,
         ...extra,
     };
 }

package/dist/db/decimal.d.ts

@@ -0,0 +1,27 @@
+/**
+ * MySQL `DECIMAL` 列向け Drizzle `customType` params。
+ *
+ * @remarks
+ * - **読込（SELECT）**: `fromDriver` で driver 値（`number` / `string` / `null`）を JS `number | null` に統一。
+ *   接続 `decimalNumbers: true`（{@link hyperdriveConnectionOptions} 既定）と併用し、Drizzle builder 経路でも
+ *   文字列 `"0"` / `"100.00"` が混ざったときに 0 を潰さず number へ揃える。
+ * - **書込（INSERT/UPDATE）**: `toDriver` で number をそのまま mysql2 に bind（`String()` 変換不要）。
+ * - 生 SQL `db.read` は接続 `decimalNumbers: true` が効く。列型の `fromDriver` は Drizzle `select` 経路向け。
+ */
+export interface DecimalNumberConfig {
+    precision: number;
+    scale: number;
+}
+/**
+ * mysql2 / Drizzle から届いた DECIMAL 値を JS `number | null` へ正規化する。
+ * `0` は falsy 落ちしないようそのまま保持する。
+ */
+export declare function coerceDecimalNumber(value: unknown): number | null;
+/**
+ * `customType` 用 params。高度な用途向け。通常は {@link decimalNumber} 列ヘルパーを使う。
+ */
+export declare const decimalNumberParams: (config: DecimalNumberConfig) => {
+    dataType: () => string;
+    fromDriver: (value: unknown) => number | null;
+    toDriver: (value: number | string | null) => number | string | null;
+};

package/dist/db/decimal.js

@@ -0,0 +1,50 @@
+/**
+ * MySQL `DECIMAL` 列向け Drizzle `customType` params。
+ *
+ * @remarks
+ * - **読込（SELECT）**: `fromDriver` で driver 値（`number` / `string` / `null`）を JS `number | null` に統一。
+ *   接続 `decimalNumbers: true`（{@link hyperdriveConnectionOptions} 既定）と併用し、Drizzle builder 経路でも
+ *   文字列 `"0"` / `"100.00"` が混ざったときに 0 を潰さず number へ揃える。
+ * - **書込（INSERT/UPDATE）**: `toDriver` で number をそのまま mysql2 に bind（`String()` 変換不要）。
+ * - 生 SQL `db.read` は接続 `decimalNumbers: true` が効く。列型の `fromDriver` は Drizzle `select` 経路向け。
+ */
+/**
+ * mysql2 / Drizzle から届いた DECIMAL 値を JS `number | null` へ正規化する。
+ * `0` は falsy 落ちしないようそのまま保持する。
+ */
+export function coerceDecimalNumber(value) {
+    if (value === null || value === undefined) {
+        return null;
+    }
+    if (typeof value === 'number') {
+        return Number.isFinite(value) ? value : null;
+    }
+    if (typeof value === 'string') {
+        const trimmed = value.trim();
+        if (trimmed === '') {
+            return null;
+        }
+        const n = Number(trimmed);
+        return Number.isFinite(n) ? n : null;
+    }
+    if (typeof value === 'bigint') {
+        return Number(value);
+    }
+    return null;
+}
+/**
+ * `customType` 用 params。高度な用途向け。通常は {@link decimalNumber} 列ヘルパーを使う。
+ */
+export const decimalNumberParams = (config) => ({
+    dataType: () => `decimal(${config.precision},${config.scale})`,
+    fromDriver: (value) => coerceDecimalNumber(value),
+    toDriver: (value) => {
+        if (value === null) {
+            return null;
+        }
+        if (typeof value === 'number') {
+            return value;
+        }
+        return coerceDecimalNumber(value);
+    },
+});

package/dist/db/index.d.ts

@@ -16,7 +16,10 @@ export { insertIdOf, affectedRowsOf, insertedIdsOf } from './write-result.js';
 export type { DzWriteResult } from './write-result.js';
 export { hyperdriveConnectionOptions, withMysqlConnections } from './connection.js';
 export type { HyperdriveLike, ExecutionContextLike } from './connection.js';
-export { toJstDate, jstTimestampParams, jstDatetimeParams, jstDateParams } from './jst.js';
+export { MYSQL_TIMEZONE, toJstDate, jstTimestampParams, jstDatetimeParams, jstDateParams } from './jst.js';
+export { coerceDecimalNumber, decimalNumberParams } from './decimal.js';
+export type { DecimalNumberConfig } from './decimal.js';
+export { jstTimestamp, jstDatetime, jstDate, decimalNumber, jstOnUpdateNow } from './columns.js';
 export { DRIZZLE_ORM_OPTIONS, honoDrizzleConfig, resolveDbSecret } from './orm-config.js';
 export type { HonoDrizzleConfigOptions, ResolvedDbSecret } from './orm-config.js';
 export { baselineMigrations, readBaselineEntry } from './migrate.js';

package/dist/db/index.js

@@ -13,6 +13,8 @@ export { retryWhenDeadlock } from './retry.js';
 export { createMysqlDatabase, createHyperdriveDatabase, databaseFrom } from './database.js';
 export { insertIdOf, affectedRowsOf, insertedIdsOf } from './write-result.js';
 export { hyperdriveConnectionOptions, withMysqlConnections } from './connection.js';
-export { toJstDate, jstTimestampParams, jstDatetimeParams, jstDateParams } from './jst.js';
+export { MYSQL_TIMEZONE, toJstDate, jstTimestampParams, jstDatetimeParams, jstDateParams } from './jst.js';
+export { coerceDecimalNumber, decimalNumberParams } from './decimal.js';
+export { jstTimestamp, jstDatetime, jstDate, decimalNumber, jstOnUpdateNow } from './columns.js';
 export { DRIZZLE_ORM_OPTIONS, honoDrizzleConfig, resolveDbSecret } from './orm-config.js';
 export { baselineMigrations, readBaselineEntry } from './migrate.js';

package/dist/db/jst.d.ts

@@ -1,60 +1,22 @@
 /**
- * Shared building blocks for normalizing JST (Asia/Tokyo) date/time values.
+ * MySQL / Drizzle 向け JST ワイヤ変換と DATE 列正規化。
  *
  * @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.
+ * 業務時刻の意味論は {@link ../business-time/index.js | business-time} に集約する。
+ * このモジュールは「MySQL 接続既定」「DATE 列の toDriver」、列 `customType` params のみを担う。
  */
+import type { BusinessDate } from '../business-time/index.js';
+/** mysql2 接続 `timezone` 既定（既存 JST DB 運用）。 */
+export declare const MYSQL_TIMEZONE = "+09:00";
 /**
- * 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.
+ * クライアント入力を MySQL `DATE` 列向け `YYYY-MM-DD`（JST 業務暦日）へ正規化。
+ * ISO 8601 / `YYYY-MM-DD` / 空文字を受け付ける。`YYYY-MM-DD` は Date 化せずそのまま渡す。
  */
-export declare function toJstDate(value: string | null | undefined): string | null;
+export declare function toJstDate(value: string | null | undefined): BusinessDate | null;
 /**
  * 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;
@@ -62,19 +24,7 @@ export declare const jstTimestampParams: (fsp?: number) => {
 /**
  * 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;
@@ -82,19 +32,7 @@ export declare const jstDatetimeParams: (fsp?: number) => {
 /**
  * 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);
- * ```
+ * @returns params with `toDriver` running {@link toJstDate}.
  */
 export declare const jstDateParams: () => {
     dataType: () => string;