@venturekit/data 0.0.0-dev.20260427225816 → 0.0.0-dev.20260429114130

package/dist/migrations/runners/custom.js

@@ -0,0 +1,167 @@
+/**
+ * Built-in pure-SQL migration / seed runner.
+ *
+ * Used by both `runMigrations` (when `MigrationConfig.tool === 'custom'`)
+ * and `runSeeds` (always). The only difference between the two callers is
+ * the source directory and the tracking-table name; the apply / skip /
+ * hash-check logic is identical.
+ *
+ * ### Tracking table
+ *
+ * Auto-created on first run with this shape:
+ *
+ *   CREATE TABLE IF NOT EXISTS <table> (
+ *     version    text        PRIMARY KEY,
+ *     hash       text        NOT NULL,
+ *     applied_at timestamptz NOT NULL DEFAULT now()
+ *   )
+ *
+ * `version` is the file basename without the `.sql` extension. `hash` is a
+ * sha-256 of the file contents at apply time; on subsequent runs we
+ * compare the stored hash to the current file hash and hard-fail (via
+ * `MigrationHashMismatchError`) if they differ — migrations and seeds are
+ * immutable once applied.
+ *
+ * ### Atomicity
+ *
+ * Each pending file runs inside its own transaction with
+ * `statement_timeout = 0` (migrations / seeds can legitimately take
+ * minutes — e.g. building large indexes — and we don't want the data-
+ * package's default 10-second cap killing them mid-flight). On any
+ * exception the transaction rolls back, the tracking-row is NOT inserted,
+ * and the runner re-throws so the operator sees the failing file.
+ */
+import crypto from 'node:crypto';
+import { readdir, readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { query } from '../../query/index.js';
+import { beginTransaction } from '../../query/transaction.js';
+import { MigrationHashMismatchError } from '../errors.js';
+/**
+ * Apply pending `.sql` files in `opts.dir`, tracked in `opts.trackingTable`.
+ *
+ * Returns `{ applied, skipped }` — both arrays of file basenames, in
+ * filesystem order. A file lands in `skipped` when its tracking row
+ * already exists AND its current hash matches the stored hash.
+ *
+ * Throws `MigrationHashMismatchError` if any already-applied file has
+ * been edited.
+ */
+export async function runSqlFiles(opts) {
+    validateIdentifier(opts.trackingTable);
+    await ensureTrackingTable(opts.trackingTable);
+    const files = await listSqlFiles(opts.dir);
+    const applied = await loadAppliedRows(opts.trackingTable);
+    const result = { applied: [], skipped: [] };
+    for (const f of files) {
+        const existing = applied.get(f.version);
+        if (existing) {
+            if (existing.hash !== f.hash) {
+                throw new MigrationHashMismatchError(f.version, existing.hash, f.hash, opts.trackingTable);
+            }
+            result.skipped.push(f.version);
+            continue;
+        }
+        if (opts.onApply)
+            opts.onApply(f.version);
+        await applyOne(opts.trackingTable, f.version, f.hash, f.sql);
+        result.applied.push(f.version);
+    }
+    return result;
+}
+/**
+ * Read-only counterpart of `runSqlFiles`. Returns one entry per `.sql` file
+ * in `opts.dir`, with `applied` true for files that have a matching
+ * tracking row.
+ *
+ * Files whose tracking row is hash-mismatched are reported with
+ * `applied: false` (so the operator sees them as "pending again") — this
+ * is a status query and shouldn't throw.
+ */
+export async function getSqlFilesStatus(opts) {
+    validateIdentifier(opts.trackingTable);
+    await ensureTrackingTable(opts.trackingTable);
+    const files = await listSqlFiles(opts.dir);
+    const applied = await loadAppliedRows(opts.trackingTable);
+    return files.map((f) => {
+        const a = applied.get(f.version);
+        if (a && a.hash === f.hash) {
+            return { version: f.version, applied: true, appliedAt: a.appliedAt };
+        }
+        return { version: f.version, applied: false };
+    });
+}
+// ─── internals ───────────────────────────────────────────────────────────
+async function listSqlFiles(dir) {
+    let entries;
+    try {
+        entries = await readdir(dir);
+    }
+    catch (err) {
+        if (err.code === 'ENOENT') {
+            // Empty / missing dir is a valid no-op (e.g. a project with no seeds).
+            return [];
+        }
+        throw err;
+    }
+    const sqlFiles = entries.filter((n) => n.endsWith('.sql')).sort();
+    const out = [];
+    for (const name of sqlFiles) {
+        const full = path.join(dir, name);
+        const sql = await readFile(full, 'utf8');
+        out.push({
+            version: name.replace(/\.sql$/, ''),
+            path: full,
+            sql,
+            hash: crypto.createHash('sha256').update(sql).digest('hex'),
+        });
+    }
+    return out;
+}
+async function ensureTrackingTable(table) {
+    await query(`CREATE TABLE IF NOT EXISTS ${table} (
+       version    text        PRIMARY KEY,
+       hash       text        NOT NULL,
+       applied_at timestamptz NOT NULL DEFAULT now()
+     )`);
+}
+async function loadAppliedRows(table) {
+    // Pin `camelCase: false` so the runner reads `applied_at` regardless of
+    // whatever global mapper config the consumer set on `@venturekit/data`.
+    // Internal bookkeeping must not be affected by application-level toggles.
+    const rows = await query(`SELECT version, hash, applied_at FROM ${table}`, [], undefined, { camelCase: false });
+    const out = new Map();
+    for (const r of rows) {
+        out.set(r.version, { hash: r.hash, appliedAt: r.applied_at });
+    }
+    return out;
+}
+async function applyOne(table, version, hash, sql) {
+    // statementTimeoutMs: 0 disables the data-package's 10s default; long
+    // index builds and bulk seeds shouldn't be killed mid-flight.
+    const tx = await beginTransaction({ statementTimeoutMs: 0 });
+    try {
+        // node-postgres lets us send multi-statement SQL in a single query call
+        // when no parameters are bound — exactly what a CREATE-heavy migration
+        // file looks like. The seed file is similarly structured.
+        await tx.query(sql);
+        await tx.query(`INSERT INTO ${table} (version, hash) VALUES ($1, $2)`, [version, hash]);
+        await tx.commit();
+    }
+    catch (err) {
+        await tx.rollback();
+        throw err;
+    }
+}
+/**
+ * Tracking-table names are interpolated directly into SQL (Postgres
+ * doesn't accept parameter placeholders for identifiers). Restrict to a
+ * conservative ASCII whitelist so injection is structurally impossible.
+ */
+function validateIdentifier(name) {
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) {
+        throw new Error(`[migrate] invalid SQL identifier: '${name}'. ` +
+            `Tracking-table names must match /^[A-Za-z_][A-Za-z0-9_]*$/.`);
+    }
+}
+//# sourceMappingURL=custom.js.map

package/dist/migrations/runners/custom.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"custom.js","sourceRoot":"","sources":["../../../src/migrations/runners/custom.ts"],"names":[],"mappings":"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"}

package/dist/migrations/runners/drizzle.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Stub for `MigrationConfig.tool === 'drizzle'`.
+ *
+ * Drizzle Kit ships its own `drizzle-kit migrate` CLI that handles
+ * `_journal.json` + tracking tables internally. Wiring it up here would
+ * require synthesizing a config file, journal, and spawning the CLI — non-
+ * trivial work and not yet justified by demand. For now this throws so
+ * the dispatcher gives a clear error instead of a silent
+ * fallthrough.
+ */
+export declare function drizzleNotImplemented(): never;
+//# sourceMappingURL=drizzle.d.ts.map

package/dist/migrations/runners/drizzle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"drizzle.d.ts","sourceRoot":"","sources":["../../../src/migrations/runners/drizzle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,wBAAgB,qBAAqB,IAAI,KAAK,CAO7C"}

package/dist/migrations/runners/drizzle.js

@@ -0,0 +1,17 @@
+/**
+ * Stub for `MigrationConfig.tool === 'drizzle'`.
+ *
+ * Drizzle Kit ships its own `drizzle-kit migrate` CLI that handles
+ * `_journal.json` + tracking tables internally. Wiring it up here would
+ * require synthesizing a config file, journal, and spawning the CLI — non-
+ * trivial work and not yet justified by demand. For now this throws so
+ * the dispatcher gives a clear error instead of a silent
+ * fallthrough.
+ */
+import { MigrationToolNotImplementedError } from '../errors.js';
+export function drizzleNotImplemented() {
+    throw new MigrationToolNotImplementedError('drizzle', 'Run `drizzle-kit migrate` directly with your own drizzle.config.ts, ' +
+        "or set MigrationConfig.tool to 'custom' and ship pure-SQL files in " +
+        'the migrations directory.');
+}
+//# sourceMappingURL=drizzle.js.map

package/dist/migrations/runners/drizzle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"drizzle.js","sourceRoot":"","sources":["../../../src/migrations/runners/drizzle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,gCAAgC,EAAE,MAAM,cAAc,CAAC;AAEhE,MAAM,UAAU,qBAAqB;IACnC,MAAM,IAAI,gCAAgC,CACxC,SAAS,EACT,sEAAsE;QACpE,qEAAqE;QACrE,2BAA2B,CAC9B,CAAC;AACJ,CAAC"}

package/dist/migrations/runners/flyway.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Stub for `MigrationConfig.tool === 'flyway'`.
+ *
+ * Flyway is a Java CLI; running it from inside `@venturekit/data` would
+ * require either spawning the `flyway` binary (relies on a Java install
+ * being available) or shipping the Flyway runtime as a peer dep. Neither
+ * has been wired up yet.
+ *
+ * The package already exports `getFlywayEnv(config, dbUrl)` for the
+ * env-only integration path — set up the env vars from that helper and
+ * shell out to `flyway migrate` yourself in your deploy pipeline.
+ */
+export declare function flywayNotImplemented(): never;
+//# sourceMappingURL=flyway.d.ts.map

package/dist/migrations/runners/flyway.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flyway.d.ts","sourceRoot":"","sources":["../../../src/migrations/runners/flyway.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,wBAAgB,oBAAoB,IAAI,KAAK,CAQ5C"}

package/dist/migrations/runners/flyway.js

@@ -0,0 +1,20 @@
+/**
+ * Stub for `MigrationConfig.tool === 'flyway'`.
+ *
+ * Flyway is a Java CLI; running it from inside `@venturekit/data` would
+ * require either spawning the `flyway` binary (relies on a Java install
+ * being available) or shipping the Flyway runtime as a peer dep. Neither
+ * has been wired up yet.
+ *
+ * The package already exports `getFlywayEnv(config, dbUrl)` for the
+ * env-only integration path — set up the env vars from that helper and
+ * shell out to `flyway migrate` yourself in your deploy pipeline.
+ */
+import { MigrationToolNotImplementedError } from '../errors.js';
+export function flywayNotImplemented() {
+    throw new MigrationToolNotImplementedError('flyway', 'Use the `getFlywayEnv()` helper to populate FLYWAY_* env vars and ' +
+        'invoke the `flyway` CLI directly in your deploy pipeline. To run ' +
+        'pure-SQL migrations through `vk migrate`, set MigrationConfig.tool ' +
+        "to 'custom' instead.");
+}
+//# sourceMappingURL=flyway.js.map

package/dist/migrations/runners/flyway.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"flyway.js","sourceRoot":"","sources":["../../../src/migrations/runners/flyway.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,gCAAgC,EAAE,MAAM,cAAc,CAAC;AAEhE,MAAM,UAAU,oBAAoB;IAClC,MAAM,IAAI,gCAAgC,CACxC,QAAQ,EACR,oEAAoE;QAClE,mEAAmE;QACnE,qEAAqE;QACrE,sBAAsB,CACzB,CAAC;AACJ,CAAC"}

package/dist/migrations/runners/golang-migrate.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Stub for `MigrationConfig.tool === 'golang-migrate'`.
+ *
+ * `golang-migrate/migrate` is a Go CLI; integrating it would mean
+ * spawning the binary and parsing its output. Not yet wired up.
+ */
+export declare function golangMigrateNotImplemented(): never;
+//# sourceMappingURL=golang-migrate.d.ts.map

package/dist/migrations/runners/golang-migrate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"golang-migrate.d.ts","sourceRoot":"","sources":["../../../src/migrations/runners/golang-migrate.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,wBAAgB,2BAA2B,IAAI,KAAK,CAOnD"}

package/dist/migrations/runners/golang-migrate.js

@@ -0,0 +1,13 @@
+/**
+ * Stub for `MigrationConfig.tool === 'golang-migrate'`.
+ *
+ * `golang-migrate/migrate` is a Go CLI; integrating it would mean
+ * spawning the binary and parsing its output. Not yet wired up.
+ */
+import { MigrationToolNotImplementedError } from '../errors.js';
+export function golangMigrateNotImplemented() {
+    throw new MigrationToolNotImplementedError('golang-migrate', 'Invoke the `migrate` CLI directly from your deploy pipeline, or set ' +
+        "MigrationConfig.tool to 'custom' to run pure-SQL files through " +
+        'the bundled VentureKit runner.');
+}
+//# sourceMappingURL=golang-migrate.js.map

package/dist/migrations/runners/golang-migrate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"golang-migrate.js","sourceRoot":"","sources":["../../../src/migrations/runners/golang-migrate.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,gCAAgC,EAAE,MAAM,cAAc,CAAC;AAEhE,MAAM,UAAU,2BAA2B;IACzC,MAAM,IAAI,gCAAgC,CACxC,gBAAgB,EAChB,sEAAsE;QACpE,iEAAiE;QACjE,gCAAgC,CACnC,CAAC;AACJ,CAAC"}

package/dist/migrations/runners/prisma.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Stub for `MigrationConfig.tool === 'prisma'`.
+ *
+ * Prisma Migrate is part of the Prisma toolchain and assumes a
+ * `schema.prisma` + `prisma migrate` workflow. It doesn't make sense to
+ * adopt it inside `@venturekit/data` without first depending on Prisma
+ * itself. Not yet wired up.
+ */
+export declare function prismaNotImplemented(): never;
+//# sourceMappingURL=prisma.d.ts.map

package/dist/migrations/runners/prisma.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prisma.d.ts","sourceRoot":"","sources":["../../../src/migrations/runners/prisma.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,wBAAgB,oBAAoB,IAAI,KAAK,CAO5C"}

package/dist/migrations/runners/prisma.js

@@ -0,0 +1,15 @@
+/**
+ * Stub for `MigrationConfig.tool === 'prisma'`.
+ *
+ * Prisma Migrate is part of the Prisma toolchain and assumes a
+ * `schema.prisma` + `prisma migrate` workflow. It doesn't make sense to
+ * adopt it inside `@venturekit/data` without first depending on Prisma
+ * itself. Not yet wired up.
+ */
+import { MigrationToolNotImplementedError } from '../errors.js';
+export function prismaNotImplemented() {
+    throw new MigrationToolNotImplementedError('prisma', 'Run `prisma migrate` directly from your project, or set ' +
+        "MigrationConfig.tool to 'custom' to run pure-SQL files through " +
+        'the bundled VentureKit runner.');
+}
+//# sourceMappingURL=prisma.js.map

package/dist/migrations/runners/prisma.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prisma.js","sourceRoot":"","sources":["../../../src/migrations/runners/prisma.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,gCAAgC,EAAE,MAAM,cAAc,CAAC;AAEhE,MAAM,UAAU,oBAAoB;IAClC,MAAM,IAAI,gCAAgC,CACxC,QAAQ,EACR,0DAA0D;QACxD,iEAAiE;QACjE,gCAAgC,CACnC,CAAC;AACJ,CAAC"}

package/dist/migrations/seeds.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Seed runner — applies pure-SQL files from a `db/seeds/` directory,
+ * tracked in `__vk_seeds`.
+ *
+ * Seeds and migrations share the same runner core (`runSqlFiles` from
+ * `runners/custom.ts`) — the only differences are:
+ *
+ *   - Source directory:   `db/seeds/`              vs `db/migrations/`
+ *   - Tracking table:     `__vk_seeds`             vs `__vk_migrations`
+ *   - Dispatch path:      always the VK runner     vs `MigrationConfig.tool`
+ *
+ * Seed files are strict literal SQL. There is **no `${VAR}` interpolation**
+ * — operators bake values directly into the file (forking projects edit
+ * the SQL once before first deploy, then manage subsequent changes through
+ * their app's UI). This avoids an entire class of injection / escaping
+ * concerns and keeps the seed runner as small as the migration runner.
+ *
+ * Like migrations, seeds are run-once-and-tracked. Editing an already-
+ * applied seed file fails loudly with `MigrationHashMismatchError`.
+ */
+import type { RunResult, SeedRunOptions, StatusEntry } from './types.js';
+/** Tracking-table name for seeds. Mirrors `__vk_migrations` for migrations. */
+export declare const SEEDS_TRACKING_TABLE = "__vk_seeds";
+/**
+ * Apply pending seed files in `opts.seedsDir`. Returns `{ applied, skipped }`
+ * — basenames of files in filesystem order.
+ *
+ * Idempotent: re-running with no new files is a no-op (everything goes
+ * into `skipped`). Throws `MigrationHashMismatchError` if any already-
+ * applied file has been edited.
+ */
+export declare function runSeeds(opts: SeedRunOptions): Promise<RunResult>;
+/**
+ * Read-only status query: one `StatusEntry` per `.sql` file in
+ * `opts.seedsDir`, with `applied: true` when a tracking row exists AND the
+ * file hash still matches.
+ */
+export declare function getSeedStatus(opts: SeedRunOptions): Promise<StatusEntry[]>;
+//# sourceMappingURL=seeds.d.ts.map

package/dist/migrations/seeds.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"seeds.d.ts","sourceRoot":"","sources":["../../src/migrations/seeds.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAEzE,+EAA+E;AAC/E,eAAO,MAAM,oBAAoB,eAAe,CAAC;AAEjD;;;;;;;GAOG;AACH,wBAAsB,QAAQ,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,SAAS,CAAC,CAMvE;AAED;;;;GAIG;AACH,wBAAsB,aAAa,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,CAKhF"}

package/dist/migrations/seeds.js

@@ -0,0 +1,50 @@
+/**
+ * Seed runner — applies pure-SQL files from a `db/seeds/` directory,
+ * tracked in `__vk_seeds`.
+ *
+ * Seeds and migrations share the same runner core (`runSqlFiles` from
+ * `runners/custom.ts`) — the only differences are:
+ *
+ *   - Source directory:   `db/seeds/`              vs `db/migrations/`
+ *   - Tracking table:     `__vk_seeds`             vs `__vk_migrations`
+ *   - Dispatch path:      always the VK runner     vs `MigrationConfig.tool`
+ *
+ * Seed files are strict literal SQL. There is **no `${VAR}` interpolation**
+ * — operators bake values directly into the file (forking projects edit
+ * the SQL once before first deploy, then manage subsequent changes through
+ * their app's UI). This avoids an entire class of injection / escaping
+ * concerns and keeps the seed runner as small as the migration runner.
+ *
+ * Like migrations, seeds are run-once-and-tracked. Editing an already-
+ * applied seed file fails loudly with `MigrationHashMismatchError`.
+ */
+import { runSqlFiles, getSqlFilesStatus } from './runners/custom.js';
+/** Tracking-table name for seeds. Mirrors `__vk_migrations` for migrations. */
+export const SEEDS_TRACKING_TABLE = '__vk_seeds';
+/**
+ * Apply pending seed files in `opts.seedsDir`. Returns `{ applied, skipped }`
+ * — basenames of files in filesystem order.
+ *
+ * Idempotent: re-running with no new files is a no-op (everything goes
+ * into `skipped`). Throws `MigrationHashMismatchError` if any already-
+ * applied file has been edited.
+ */
+export async function runSeeds(opts) {
+    return runSqlFiles({
+        dir: opts.seedsDir,
+        trackingTable: SEEDS_TRACKING_TABLE,
+        onApply: opts.onApply,
+    });
+}
+/**
+ * Read-only status query: one `StatusEntry` per `.sql` file in
+ * `opts.seedsDir`, with `applied: true` when a tracking row exists AND the
+ * file hash still matches.
+ */
+export async function getSeedStatus(opts) {
+    return getSqlFilesStatus({
+        dir: opts.seedsDir,
+        trackingTable: SEEDS_TRACKING_TABLE,
+    });
+}
+//# sourceMappingURL=seeds.js.map

package/dist/migrations/seeds.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"seeds.js","sourceRoot":"","sources":["../../src/migrations/seeds.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAGrE,+EAA+E;AAC/E,MAAM,CAAC,MAAM,oBAAoB,GAAG,YAAY,CAAC;AAEjD;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,IAAoB;IACjD,OAAO,WAAW,CAAC;QACjB,GAAG,EAAE,IAAI,CAAC,QAAQ;QAClB,aAAa,EAAE,oBAAoB;QACnC,OAAO,EAAE,IAAI,CAAC,OAAO;KACtB,CAAC,CAAC;AACL,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,IAAoB;IACtD,OAAO,iBAAiB,CAAC;QACvB,GAAG,EAAE,IAAI,CAAC,QAAQ;QAClB,aAAa,EAAE,oBAAoB;KACpC,CAAC,CAAC;AACL,CAAC"}

package/dist/migrations/types.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Types for the migration / seed runners.
+ *
+ * NOTE: `MigrationConfig` (the project-level config shape with the
+ * `tool` enum) lives in `../types/migration.ts`. This file only contains
+ * the input/output shapes for the runner functions themselves.
+ */
+/**
+ * Result of a single `runMigrations` / `runSeeds` invocation.
+ *
+ * `applied` and `skipped` are file basenames (without `.sql`), in the
+ * order they appeared on disk. A file is `skipped` when its tracking-table
+ * row already exists AND its hash still matches what was applied.
+ */
+export interface RunResult {
+    applied: string[];
+    skipped: string[];
+}
+/**
+ * Per-file status reported by `getMigrationStatus` / `getSeedStatus`.
+ */
+export interface StatusEntry {
+    /** File basename without `.sql`, e.g. `0000_init`. */
+    version: string;
+    /** True if a tracking row exists AND the file hash still matches. */
+    applied: boolean;
+    /** Set when `applied` is true. */
+    appliedAt?: Date;
+}
+/**
+ * Optional knobs shared by `runMigrations` and `runSeeds`.
+ */
+export interface RunOptions {
+    /**
+     * Called immediately before each pending file is applied. Useful for
+     * streaming progress to stdout from the CLI without coupling the runner
+     * to a logging library.
+     */
+    onApply?: (version: string) => void;
+}
+/**
+ * Input for `runSeeds` / `getSeedStatus`.
+ */
+export interface SeedRunOptions extends RunOptions {
+    /** Directory containing seed `.sql` files. */
+    seedsDir: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/migrations/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/migrations/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;GAMG;AACH,MAAM,WAAW,SAAS;IACxB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,sDAAsD;IACtD,OAAO,EAAE,MAAM,CAAC;IAChB,qEAAqE;IACrE,OAAO,EAAE,OAAO,CAAC;IACjB,kCAAkC;IAClC,SAAS,CAAC,EAAE,IAAI,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB;;;;OAIG;IACH,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACrC;AAED;;GAEG;AACH,MAAM,WAAW,cAAe,SAAQ,UAAU;IAChD,8CAA8C;IAC9C,QAAQ,EAAE,MAAM,CAAC;CAClB"}

package/dist/migrations/types.js

@@ -0,0 +1,9 @@
+/**
+ * Types for the migration / seed runners.
+ *
+ * NOTE: `MigrationConfig` (the project-level config shape with the
+ * `tool` enum) lives in `../types/migration.ts`. This file only contains
+ * the input/output shapes for the runner functions themselves.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/migrations/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/migrations/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

package/dist/query/index.d.ts

@@ -44,11 +44,13 @@
  * - An empty result set is **not** an error — it returns `[]` (or whatever
  *   your mapper produces for an empty array).
  */
+import { type MapperOptions } from './mapper.js';
 import type { ResultsMapper } from './transaction.js';
-export { getPool } from './pool.js';
-export { mapResults, mapRow } from './mapper.js';
+export { getPool, applyDatabaseUrlToEnv } from './pool.js';
+export { mapResults, mapRow, configureMapper, getMapperConfig, } from './mapper.js';
+export type { MapperOptions } from './mapper.js';
 export { beginTransaction, withTransaction, buildTransaction, } from './transaction.js';
-export type { Transaction, ResultsMapper } from './transaction.js';
+export type { Transaction, ResultsMapper, Querier } from './transaction.js';
 /**
  * Execute a SQL query against the connection pool.
  *
@@ -83,5 +85,5 @@ export type { Transaction, ResultsMapper } from './transaction.js';
  * );
  * ```
  */
-export declare function query<T = Record<string, unknown>[]>(sqlQuery: string, queryParams?: unknown[], resultsMapper?: ResultsMapper<T>): Promise<T>;
+export declare function query<T = Record<string, unknown>[]>(sqlQuery: string, queryParams?: unknown[], resultsMapper?: ResultsMapper<T>, mapperOptions?: MapperOptions): Promise<T>;
 //# sourceMappingURL=index.d.ts.map

package/dist/query/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/query/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAKH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEtD,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EACL,gBAAgB,EAChB,eAAe,EACf,gBAAgB,GACjB,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEnE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAsB,KAAK,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,EACvD,QAAQ,EAAE,MAAM,EAChB,WAAW,CAAC,EAAE,OAAO,EAAE,EACvB,aAAa,CAAC,EAAE,aAAa,CAAC,CAAC,CAAC,GAC/B,OAAO,CAAC,CAAC,CAAC,CAKZ"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/query/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAIH,OAAO,EAAsB,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AACrE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEtD,OAAO,EAAE,OAAO,EAAE,qBAAqB,EAAE,MAAM,WAAW,CAAC;AAC3D,OAAO,EACL,UAAU,EACV,MAAM,EACN,eAAe,EACf,eAAe,GAChB,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EACL,gBAAgB,EAChB,eAAe,EACf,gBAAgB,GACjB,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EAAE,WAAW,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAE5E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAsB,KAAK,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,EACvD,QAAQ,EAAE,MAAM,EAChB,WAAW,CAAC,EAAE,OAAO,EAAE,EACvB,aAAa,CAAC,EAAE,aAAa,CAAC,CAAC,CAAC,EAChC,aAAa,CAAC,EAAE,aAAa,GAC5B,OAAO,CAAC,CAAC,CAAC,CAKZ"}

package/dist/query/index.js

@@ -46,8 +46,8 @@
  */
 import { getPool } from './pool.js';
 import { mapResults } from './mapper.js';
-export { getPool } from './pool.js';
-export { mapResults, mapRow } from './mapper.js';
+export { getPool, applyDatabaseUrlToEnv } from './pool.js';
+export { mapResults, mapRow, configureMapper, getMapperConfig, } from './mapper.js';
 export { beginTransaction, withTransaction, buildTransaction, } from './transaction.js';
 /**
  * Execute a SQL query against the connection pool.
@@ -83,10 +83,10 @@ export { beginTransaction, withTransaction, buildTransaction, } from './transact
  * );
  * ```
  */
-export async function query(sqlQuery, queryParams, resultsMapper) {
+export async function query(sqlQuery, queryParams, resultsMapper, mapperOptions) {
     const pool = getPool();
     const res = await pool.query(sqlQuery, queryParams);
-    const mapped = mapResults(res.rows);
+    const mapped = mapResults(res.rows, mapperOptions);
     return resultsMapper ? resultsMapper(mapped) : mapped;
 }
 //# sourceMappingURL=index.js.map

package/dist/query/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/query/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAGH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,UAAU,EAAU,MAAM,aAAa,CAAC;AAGjD,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EACL,gBAAgB,EAChB,eAAe,EACf,gBAAgB,GACjB,MAAM,kBAAkB,CAAC;AAG1B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,MAAM,CAAC,KAAK,UAAU,KAAK,CACzB,QAAgB,EAChB,WAAuB,EACvB,aAAgC;IAEhC,MAAM,IAAI,GAAG,OAAO,EAAE,CAAC;IACvB,MAAM,GAAG,GAAgB,MAAM,IAAI,CAAC,KAAK,CAAC,QAAQ,EAAE,WAAW,CAAC,CAAC;IACjE,MAAM,MAAM,GAAG,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACpC,OAAO,aAAa,CAAC,CAAC,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAsB,CAAC;AACxE,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/query/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAGH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,UAAU,EAA8B,MAAM,aAAa,CAAC;AAGrE,OAAO,EAAE,OAAO,EAAE,qBAAqB,EAAE,MAAM,WAAW,CAAC;AAC3D,OAAO,EACL,UAAU,EACV,MAAM,EACN,eAAe,EACf,eAAe,GAChB,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,gBAAgB,EAChB,eAAe,EACf,gBAAgB,GACjB,MAAM,kBAAkB,CAAC;AAG1B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,MAAM,CAAC,KAAK,UAAU,KAAK,CACzB,QAAgB,EAChB,WAAuB,EACvB,aAAgC,EAChC,aAA6B;IAE7B,MAAM,IAAI,GAAG,OAAO,EAAE,CAAC;IACvB,MAAM,GAAG,GAAgB,MAAM,IAAI,CAAC,KAAK,CAAC,QAAQ,EAAE,WAAW,CAAC,CAAC;IACjE,MAAM,MAAM,GAAG,UAAU,CAAC,GAAG,CAAC,IAAI,EAAE,aAAa,CAAC,CAAC;IACnD,OAAO,aAAa,CAAC,CAAC,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAsB,CAAC;AACxE,CAAC"}