@rdlabo/workers-hono-kit 0.11.2 → 0.12.0-beta.pr48.sha371f5792ce8a

package/dist/db/migrate.js

@@ -1,109 +0,0 @@
-/**
- * Brownfield baseline for Drizzle MySQL migrations.
- *
- * An existing (in-production) DB already has its schema, so running the committed baseline migration
- * (`drizzle/0000_*.sql` = the CREATE TABLE statements introspected from the current schema) via
- * `db:migrate` fails as every table collides. Instead, 0000 is **recorded as "applied" without being
- * executed**.
- *
- * How "applied" is decided (drizzle-orm/mysql-core dialect.migrate): it determines the pending set from
- * **only the maximum `created_at`** in `__drizzle_migrations(id, hash, created_at)`, running just the
- * migrations where `max(created_at) < entry.when`. The hash is stored but not used for the decision. So
- * inserting one row as the 0000 marker — `(hash, created_at = that entry's when)` — makes subsequent
- * `db:migrate` runs apply only the later 0001+ (larger `when`) and skip 0000. A fresh / test DB has no
- * marker, so the full chain runs (behavior unchanged).
- *
- * This function does not depend on `drizzle-orm` (it reads the journal/SQL itself and hashes with the
- * same sha256 as drizzle). It runs raw SQL against a QueryRunner (a mysql2 `Connection`/`Pool` is
- * structurally assignable).
- *
- * @packageDocumentation
- */
-import { createHash } from 'node:crypto';
-import { existsSync, readFileSync } from 'node:fs';
-import { join } from 'node:path';
-/** The default migration-tracking table name used by drizzle. */
-const MIGRATIONS_TABLE = '__drizzle_migrations';
-/**
- * Read the baseline (first) entry from `migrationsFolder` (drizzle's `out`, e.g. `./drizzle`).
- *
- * @param migrationsFolder - the folder containing `meta/_journal.json` and `<tag>.sql`.
- * @returns the baseline entry (tag/when/hash).
- * @throws Error when the journal is missing, the entries are empty, or `<tag>.sql` is missing.
- */
-export function readBaselineEntry(migrationsFolder) {
-    const journalPath = join(migrationsFolder, 'meta', '_journal.json');
-    if (!existsSync(journalPath)) {
-        throw new Error(`Can't find meta/_journal.json under ${migrationsFolder}. Run \`drizzle-kit generate\` first.`);
-    }
-    const journal = JSON.parse(readFileSync(journalPath, 'utf8'));
-    const entries = journal.entries ?? [];
-    if (entries.length === 0) {
-        throw new Error(`No migration entries in ${journalPath}.`);
-    }
-    // The origin is always the first entry (0000). Later 0001+ are "new changes" that should run even on
-    // an existing DB.
-    const first = entries[0];
-    const sqlPath = join(migrationsFolder, `${first.tag}.sql`);
-    if (!existsSync(sqlPath)) {
-        throw new Error(`Can't find ${first.tag}.sql under ${migrationsFolder}.`);
-    }
-    const sql = readFileSync(sqlPath, 'utf8');
-    return { tag: first.tag, when: first.when, hash: createHash('sha256').update(sql).digest('hex') };
-}
-async function rowsOf(db, sql, params) {
-    const result = (await db.query(sql, params));
-    return result[0] ?? [];
-}
-/**
- * Record the baseline (0000) as "applied" on an existing DB. Idempotent, with safety guards.
- *
- * @remarks
- * Guards:
- * - If a baseline marker (`created_at = when`) already exists → **no-op** (`already-baselined`).
- * - If there is no marker but `__drizzle_migrations` has other rows → **abort** (unexpected state).
- * - If the target DB has no base tables (an empty DB) → **abort** (skipping 0000 on an empty DB would
- *   never create the tables; use `db:migrate` for a fresh DB).
- *
- * @param options - the connection and migrations folder; see {@link BaselineMigrationsOptions}.
- * @returns whether a marker was inserted or the DB was already baselined.
- * @throws Error when one of the guards above trips.
- */
-export async function baselineMigrations(options) {
-    const { db, migrationsFolder = './drizzle' } = options;
-    const baseline = readBaselineEntry(migrationsFolder);
-    // Same DDL as the migrator (a no-op if it already exists).
-    await db.query(`create table if not exists \`${MIGRATIONS_TABLE}\` (
-      id serial primary key,
-      hash text not null,
-      created_at bigint
-    )`);
-    // If a baseline marker already exists, this is an idempotent no-op.
-    const existing = await rowsOf(db, `select id from \`${MIGRATIONS_TABLE}\` where created_at = ? limit 1`, [
-        baseline.when,
-    ]);
-    if (existing.length > 0) {
-        return { status: 'already-baselined', tag: baseline.tag, when: baseline.when };
-    }
-    // No marker but rows exist = already in some other state. Abort to avoid misfiring.
-    const countRows = await rowsOf(db, `select count(*) as n from \`${MIGRATIONS_TABLE}\``);
-    const rowCount = Number(countRows[0]?.n ?? 0);
-    if (rowCount > 0) {
-        throw new Error(`${MIGRATIONS_TABLE} already has ${rowCount} row(s) but no baseline marker (created_at=${baseline.when}). ` +
-            `Migration state is unexpected — refusing to insert. Inspect \`${MIGRATIONS_TABLE}\` manually.`);
-    }
-    // Baselining an empty DB is dangerous (treating 0000 as skipped would never create the tables).
-    // Confirm this is a brownfield DB.
-    const tableRows = await rowsOf(db, `select count(*) as n from information_schema.tables
-      where table_schema = DATABASE() and table_type = 'BASE TABLE' and table_name <> ?`, [MIGRATIONS_TABLE]);
-    const baseTableCount = Number(tableRows[0]?.n ?? 0);
-    if (baseTableCount === 0) {
-        throw new Error(`Target DB has no base tables. baseline records 0000 as applied WITHOUT creating tables — this is only ` +
-            `for existing (brownfield) DBs. For a fresh/empty DB run \`drizzle-kit migrate\` instead.`);
-    }
-    await db.query(`insert into \`${MIGRATIONS_TABLE}\` (\`hash\`, \`created_at\`) values (?, ?)`, [
-        baseline.hash,
-        baseline.when,
-    ]);
-    return { status: 'inserted', tag: baseline.tag, when: baseline.when, hash: baseline.hash };
-}

package/dist/db/orm-config.d.ts

@@ -1,127 +0,0 @@
-/**
- * Centralizes Drizzle column-name casing so it is fixed (standard: `snake_case`) in both the
- * config and the runtime ORM.
- *
- * @remarks
- * Casing is configured in two distinct places:
- *
- * 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}).
- *
- * 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 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 declare const DRIZZLE_ORM_OPTIONS: {
-    readonly mode: "default";
-    readonly casing: "snake_case";
-};
-/**
- * Options for {@link honoDrizzleConfig}.
- */
-export interface HonoDrizzleConfigOptions {
-    /** 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;
-    /** Path to the schema directory; defaults to `'./src/db/schemes'`. */
-    schema?: string;
-    /** Output directory for generated migrations; defaults to `'./drizzle'`. */
-    out?: string;
-    /**
-     * 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[];
-    /**
-     * 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';
-    };
-}
-/**
- * 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 declare function honoDrizzleConfig(options: HonoDrizzleConfigOptions): {
-    dbCredentials: {
-        host: string;
-        port: number;
-        user: string;
-        password: string;
-        database: string;
-    };
-    introspect?: {
-        casing: "camel" | "preserve";
-    } | undefined;
-    tablesFilter?: string[] | undefined;
-    dialect: "mysql";
-    schema: string;
-    out: string;
-    casing: "snake_case";
-};
-/** The return value of {@link resolveDbSecret} (normalized connection info). */
-export interface ResolvedDbSecret {
-    host: string;
-    port: number;
-    dbname: string;
-    username: string;
-    password: string;
-}
-/**
- * Resolve an AWS RDS managed secret (a JSON string placed in `DB_SECRET`).
- *
- * @remarks
- * - `DB_SECRET` unset → `undefined` (the normal local / `db:generate` fallback).
- * - When set, it must be complete connection info: **invalid JSON / a missing required key throws**
- *   (rather than silently falling back to localhost and causing an incident). A missing `port` alone
- *   defaults to 3306.
- *
- * Both `honoDrizzleConfig` (db:migrate) and the `workers-hono-kit-db-baseline` bin use this same logic.
- *
- * @returns the resolved connection info, or `undefined` when `DB_SECRET` is unset.
- * @throws Error when `DB_SECRET` is set but is not valid JSON or is missing a required key.
- */
-export declare function resolveDbSecret(): ResolvedDbSecret | undefined;

package/dist/db/orm-config.js

@@ -1,122 +0,0 @@
-/**
- * Centralizes Drizzle column-name casing so it is fixed (standard: `snake_case`) in both the
- * config and the runtime ORM.
- *
- * @remarks
- * Casing is configured in two distinct places:
- *
- * 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}).
- *
- * 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 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' };
-/**
- * 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) {
-    const { database, host, port, user, password, schema = './src/db/schemes', out = './drizzle', tablesFilter, introspect, } = options;
-    // CI/production migrate absorbs the pattern of passing a whole AWS Secrets Manager RDS managed secret
-    // (keys host/port/dbname/username/password) via `DB_SECRET`. It is parsed with JSON.parse, so key-name
-    // differences (host ≠ DB_HOST) can be mapped and special characters in the password stay shell-safe.
-    // When `DB_SECRET` is set, it is treated as a complete secret and fully determines the connection
-    // (missing/invalid → throw). Only when it is unset do we fall back to the individual DB_* env vars
-    // and then the defaults (the local / db:generate path).
-    const secret = resolveDbSecret();
-    const dbCredentials = secret
-        ? {
-            host: secret.host,
-            port: secret.port,
-            user: secret.username,
-            password: secret.password,
-            database: secret.dbname,
-        }
-        : {
-            host: host ?? process.env.DB_HOST ?? '127.0.0.1',
-            port: port ?? Number(process.env.DB_PORT ?? 3306),
-            user: user ?? process.env.DB_USER ?? 'root',
-            password: password ?? process.env.DB_PASSWORD ?? 'root',
-            database,
-        };
-    return {
-        dialect: 'mysql',
-        schema,
-        out,
-        casing: 'snake_case',
-        ...(tablesFilter ? { tablesFilter } : {}),
-        ...(introspect ? { introspect } : {}),
-        dbCredentials,
-    };
-}
-/**
- * Resolve an AWS RDS managed secret (a JSON string placed in `DB_SECRET`).
- *
- * @remarks
- * - `DB_SECRET` unset → `undefined` (the normal local / `db:generate` fallback).
- * - When set, it must be complete connection info: **invalid JSON / a missing required key throws**
- *   (rather than silently falling back to localhost and causing an incident). A missing `port` alone
- *   defaults to 3306.
- *
- * Both `honoDrizzleConfig` (db:migrate) and the `workers-hono-kit-db-baseline` bin use this same logic.
- *
- * @returns the resolved connection info, or `undefined` when `DB_SECRET` is unset.
- * @throws Error when `DB_SECRET` is set but is not valid JSON or is missing a required key.
- */
-export function resolveDbSecret() {
-    const raw = process.env.DB_SECRET;
-    if (!raw) {
-        return undefined;
-    }
-    let parsed;
-    try {
-        parsed = JSON.parse(raw);
-    }
-    catch {
-        throw new Error('DB_SECRET is set but is not valid JSON (expected an AWS RDS managed secret string).');
-    }
-    const { host, dbname, username, password } = parsed;
-    if (typeof host !== 'string' ||
-        typeof dbname !== 'string' ||
-        typeof username !== 'string' ||
-        typeof password !== 'string') {
-        throw new Error('DB_SECRET must contain string host, dbname, username, password (AWS RDS managed secret shape).');
-    }
-    return { host, dbname, username, password, port: parsed.port === undefined ? 3306 : Number(parsed.port) };
-}

package/dist/db/retry.d.ts

@@ -1,28 +0,0 @@
-/**
- * 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 declare function retryWhenDeadlock<T>(fn: () => Promise<T>, retries?: number, delay?: number): Promise<T>;

package/dist/db/retry.js

@@ -1,56 +0,0 @@
-/**
- * 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(fn, retries = 3, delay = 100) {
-    for (let attempt = 0; attempt < retries; attempt++) {
-        const invoke = async () => fn();
-        const outcome = await invoke().then((value) => ({ ok: true, value }), (error) => ({ ok: false, error }));
-        if (outcome.ok) {
-            return outcome.value;
-        }
-        if (isDeadlock(outcome.error) && attempt < retries - 1) {
-            await new Promise((resolve) => setTimeout(resolve, delay * (attempt + 1)));
-            continue;
-        }
-        throw outcome.error;
-    }
-    // Unreachable: the loop returns on success and throws on the final failed attempt.
-    throw new Error('retryWhenDeadlock: exhausted retries');
-}
-function isDeadlock(error) {
-    let current = error;
-    const seen = new Set();
-    while (typeof current === 'object' && current !== null && !seen.has(current)) {
-        seen.add(current);
-        const value = current;
-        if (value.code === 'ER_LOCK_DEADLOCK') {
-            return true;
-        }
-        current = value.cause;
-    }
-    return false;
-}

package/dist/db/write-result.d.ts

@@ -1,39 +0,0 @@
-/**
- * Shape of a Drizzle (mysql2) write result, narrowed to the fields callers actually read.
- *
- * @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 declare function insertIdOf(result: DzWriteResult): number;
-/**
- * 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 declare function affectedRowsOf(result: DzWriteResult): number;
-/**
- * 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 declare function insertedIdsOf(result: DzWriteResult, count: number): number[];

package/dist/db/write-result.js

@@ -1,34 +0,0 @@
-/**
- * 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) {
-    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) {
-    return result[0].affectedRows;
-}
-/**
- * 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, count) {
-    const base = result[0].insertId;
-    return Array.from({ length: count }, (_, i) => base + i);
-}