migrane 0.3.0

package/dist/safety.d.ts

@@ -0,0 +1,32 @@
+import type { Driver } from './types.js';
+/**
+ * The refusal every destructive command falls back to, and the terminal every
+ * consumer-written guard ends in.
+ *
+ * The library consults **nothing** here — no environment variable, no notion
+ * of which hosts are local. Locality was a bad proxy anyway: on a droplet
+ * running Postgres host-networked, production *is* `127.0.0.1`. Which
+ * databases are disposable is the config's opinion, so the config is where it
+ * is declared, and until it is declared nothing destructive runs.
+ */
+/**
+ * Thrown by {@link refuse}, and nothing else. A class of its own so the CLI
+ * can answer with its exit code for "the guard said no" — matching on the
+ * message would catch the next error whose wording happened to look similar.
+ */
+export declare class Refusal extends Error {
+    constructor(message: string);
+}
+/**
+ * Always throws. Its whole job is the message: a guard snippet naming the
+ * exact coordinates the driver holds, ready to paste into the config once a
+ * person has read them and decided they name a database that is theirs to
+ * lose. Reached as the default when the config declares no guard, and as the
+ * last line of a guard for whatever it did not allow — the message is written
+ * to be true from both.
+ *
+ * @param what what the command does, as a clause — `reset drops every table`.
+ * It opens the message, so the refusal reads as a sentence about the command
+ * rather than about the guard.
+ */
+export declare const refuse: (driver: Driver, what: string) => never;

package/dist/safety.js

@@ -0,0 +1,44 @@
+/**
+ * The refusal every destructive command falls back to, and the terminal every
+ * consumer-written guard ends in.
+ *
+ * The library consults **nothing** here — no environment variable, no notion
+ * of which hosts are local. Locality was a bad proxy anyway: on a droplet
+ * running Postgres host-networked, production *is* `127.0.0.1`. Which
+ * databases are disposable is the config's opinion, so the config is where it
+ * is declared, and until it is declared nothing destructive runs.
+ */
+/**
+ * Thrown by {@link refuse}, and nothing else. A class of its own so the CLI
+ * can answer with its exit code for "the guard said no" — matching on the
+ * message would catch the next error whose wording happened to look similar.
+ */
+export class Refusal extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'Refusal';
+    }
+}
+/**
+ * Always throws. Its whole job is the message: a guard snippet naming the
+ * exact coordinates the driver holds, ready to paste into the config once a
+ * person has read them and decided they name a database that is theirs to
+ * lose. Reached as the default when the config declares no guard, and as the
+ * last line of a guard for whatever it did not allow — the message is written
+ * to be true from both.
+ *
+ * @param what what the command does, as a clause — `reset drops every table`.
+ * It opens the message, so the refusal reads as a sentence about the command
+ * rather than about the guard.
+ */
+export const refuse = (driver, what) => {
+    const { host, database } = driver;
+    throw new Refusal(`${what}, and nothing says "${database}" on "${host}" is disposable.\n` +
+        `  If it is, say so in the config — the guard replaces this refusal:\n` +
+        `\n` +
+        `    guard: (driver, what) => {\n` +
+        `      if (driver.host === '${host}' && driver.database === '${database}') return;\n` +
+        `\n` +
+        `      refuse(driver, what);\n` +
+        `    },`);
+};

package/dist/seeds.d.ts

@@ -0,0 +1,50 @@
+import { type Progress } from './runner.js';
+import type { Config, Driver, Guard, Migration, Row } from './types.js';
+/**
+ * Seed units — fixtures, and the deliberate opposite of a migration.
+ *
+ * Units are **alternatives, not increments**: one directory is one dataset and
+ * you run exactly one against a fresh database. So a unit is recorded but never
+ * refused — editing a fixture set and running it again is how one is used.
+ *
+ * The row answers a different question from a migration's: *which fixtures is
+ * this database holding, and do they still match the units in hand.*
+ *
+ * Split the way migrations are: `unitsIn` in `discover.ts` reads a directory,
+ * everything here takes units already loaded. A seed that loads itself cannot
+ * ship, and an image has no `seeders/` directory to load from.
+ */
+export interface Seeded extends Row {
+    name: string;
+    checksum: string;
+    run_at: string;
+}
+export interface SeedPlan {
+    /**
+     * The units, already loaded — `loadAll(unitsIn(dir))` on a developer machine,
+     * and a generated array in an image. Paths are deliberately absent: where a
+     * unit came from was discovery's problem, and the code that runs it is the
+     * same code in both places.
+     */
+    units: readonly Migration[];
+    table: string;
+    /** Consulted by `seed` and `unseed`. Defaults to `refuse`. */
+    guard?: Guard;
+}
+/**
+ * A seed plan from a config and units already loaded — `planFrom`'s twin, and
+ * defaulting its table from the same constant for the same reason.
+ */
+export declare const seedPlanFrom: (config: Config, units: readonly Migration[]) => SeedPlan;
+export declare const seed: (driver: Driver, plan: SeedPlan, unit: string, reporter?: Progress) => Promise<void>;
+export declare const unseed: (driver: Driver, plan: SeedPlan, unit: string, reporter?: Progress) => Promise<void>;
+/**
+ * What this database was seeded with, and whether that unit still matches disk.
+ *
+ * Read from the database rather than inferred from a checkout, which is the
+ * point: the plan tells you which units exist, only the row tells you which one
+ * you are looking at. A unit the plan no longer carries still reports — it is
+ * how a database seeded from a deleted branch explains itself, and how an image
+ * explains fixtures that were dropped from a later build.
+ */
+export declare const seedStatus: (driver: Driver, plan: SeedPlan, reporter?: Progress) => Promise<Seeded[]>;

package/dist/seeds.js

@@ -0,0 +1,98 @@
+import { DEFAULTS } from './defaults.js';
+import { toConsole } from './runner.js';
+import { refuse } from './safety.js';
+import { createSql, quoteIdent } from './sql.js';
+const ensure = async (db, table) => {
+    await db.query(`
+    CREATE TABLE IF NOT EXISTS ${quoteIdent(table)} (
+      name      TEXT PRIMARY KEY,
+      checksum  TEXT NOT NULL DEFAULT '',
+      run_at    TIMESTAMPTZ NOT NULL DEFAULT now()
+    )
+  `);
+};
+/**
+ * A seed plan from a config and units already loaded — `planFrom`'s twin, and
+ * defaulting its table from the same constant for the same reason.
+ */
+export const seedPlanFrom = (config, units) => ({
+    units,
+    table: config.seedTable ?? DEFAULTS.seedTable,
+    guard: config.guard,
+});
+/**
+ * Picking the named unit out of the plan.
+ *
+ * The message says *does not exist* rather than naming a directory, because by
+ * here there is no directory to name — only the units this plan was handed.
+ */
+const chosen = (plan, unit) => {
+    const found = plan.units.find(({ name }) => name === unit);
+    if (!found)
+        throw new Error(`seed unit "${unit}" does not exist.`);
+    return found;
+};
+export const seed = async (driver, plan, unit, reporter = toConsole) => {
+    // Guarded like `reset`, and for the same reason rather than a lesser one: a
+    // unit is allowed to truncate before it inserts, so "it only adds rows" is
+    // not something the runner can promise about somebody's fixtures.
+    await (plan.guard ?? refuse)(driver, 'seed writes fixtures');
+    const loaded = chosen(plan, unit);
+    await driver.session(async (session) => {
+        await ensure(session, plan.table);
+        await session.transaction(async (tx) => {
+            await loaded.module.up({ sql: createSql(tx), db: tx });
+            // Upserted, not inserted: seeding the same unit twice is expected, and
+            // should move the timestamp rather than fail on the primary key.
+            await tx.query(`INSERT INTO ${quoteIdent(plan.table)} (name, checksum) VALUES ($1, $2)
+           ON CONFLICT (name) DO UPDATE
+              SET checksum = excluded.checksum, run_at = now()`, [unit, loaded.checksum]);
+        });
+    });
+    reporter.line(`seeded ${unit}`);
+};
+export const unseed = async (driver, plan, unit, reporter = toConsole) => {
+    await (plan.guard ?? refuse)(driver, 'unseed deletes rows a fixture set made');
+    const loaded = chosen(plan, unit);
+    const revert = loaded.module.down;
+    if (!revert)
+        throw new Error(`seed unit "${unit}" has no "down".`);
+    await driver.session(async (session) => {
+        await ensure(session, plan.table);
+        await session.transaction(async (tx) => {
+            await revert({ sql: createSql(tx), db: tx });
+            await tx.query(`DELETE FROM ${quoteIdent(plan.table)} WHERE name = $1`, [
+                unit,
+            ]);
+        });
+    });
+    reporter.line(`unseeded ${unit}`);
+};
+/**
+ * What this database was seeded with, and whether that unit still matches disk.
+ *
+ * Read from the database rather than inferred from a checkout, which is the
+ * point: the plan tells you which units exist, only the row tells you which one
+ * you are looking at. A unit the plan no longer carries still reports — it is
+ * how a database seeded from a deleted branch explains itself, and how an image
+ * explains fixtures that were dropped from a later build.
+ */
+export const seedStatus = async (driver, plan, reporter = toConsole) => {
+    await ensure(driver, plan.table);
+    const rows = await driver.query(`SELECT name, checksum, run_at FROM ${quoteIdent(plan.table)} ORDER BY run_at DESC`);
+    const present = new Map(plan.units.map(({ name, checksum }) => [name, checksum]));
+    for (const row of rows) {
+        const held = present.get(row.name);
+        const state = held === undefined
+            ? 'unit is gone'
+            : held === row.checksum
+                ? 'current'
+                : 'changed since';
+        const on = new Date(row.run_at)
+            .toISOString()
+            .slice(0, 16)
+            .replace('T', ' ');
+        reporter.line(`  seeded   ${row.name}  ${on}  (${state})`);
+    }
+    return rows;
+};

package/dist/ship.d.ts

@@ -0,0 +1,52 @@
+import { type Manifest } from './load.js';
+import { type Plan } from './runner.js';
+import { type ResetPlan } from './reset.js';
+import { type SeedPlan } from './seeds.js';
+import type { Config } from './types.js';
+/**
+ * The runtime half of the package, for **container entries**: every job that
+ * does not touch a filesystem. A generated manifest plus a config becomes
+ * plans, and the verbs below run them — the same verbs, against the same
+ * bookkeeping, as the CLI on a developer machine.
+ *
+ * Filesystem-free by construction, not by tree-shaking luck: nothing imported
+ * here reaches `node:fs`, and `tsconfig.ship.json` compiles this file for a
+ * target with no platform libs at all, so an import sneaking in fails the
+ * build rather than the review.
+ *
+ * ```ts
+ * // database/entry.ts — ordinary source in your repository
+ * import { createPlans, up, withDriver } from 'migrane/ship';
+ * import config from './config.ts';
+ * import * as manifest from './manifest.gen.ts';
+ *
+ * const plans = createPlans(config, manifest);
+ *
+ * await withDriver(config, (driver) => up(driver, plans.migrations));
+ * ```
+ */
+/** Every plan a manifest can feed, one per family of verbs. */
+export interface Plans {
+    /** For {@link up}, {@link down} and {@link status}. */
+    migrations: Plan;
+    /** For {@link seed}, {@link unseed} and {@link seedStatus}. */
+    seeds: SeedPlan;
+    /** For {@link reset}. */
+    reset: ResetPlan;
+}
+/**
+ * A config and a generated manifest, settled into every plan the verbs take.
+ *
+ * One constructor rather than four builders, because there is exactly one
+ * correct way to combine them and nothing worth deciding in between. The
+ * defaults — table names, schema — settle here from the same constants the
+ * CLI uses, so an image can never record migrations in a table the CLI does
+ * not look in.
+ */
+export declare const createPlans: (config: Config, manifest: Manifest) => Plans;
+export { withDriver } from './connect.js';
+export type { Manifest, ManifestEntry, ManifestPart } from './load.js';
+export { reset, type ResetPlan } from './reset.js';
+export { down, status, up, type Plan, type Progress, type Status, } from './runner.js';
+export { seed, seedStatus, unseed, type SeedPlan, type Seeded, } from './seeds.js';
+export { MigrationChangedError } from './storage.js';

package/dist/ship.js

@@ -0,0 +1,23 @@
+import { fromManifest } from './load.js';
+import { planFrom } from './runner.js';
+import { resetPlanFrom } from './reset.js';
+import { seedPlanFrom } from './seeds.js';
+/**
+ * A config and a generated manifest, settled into every plan the verbs take.
+ *
+ * One constructor rather than four builders, because there is exactly one
+ * correct way to combine them and nothing worth deciding in between. The
+ * defaults — table names, schema — settle here from the same constants the
+ * CLI uses, so an image can never record migrations in a table the CLI does
+ * not look in.
+ */
+export const createPlans = (config, manifest) => ({
+    migrations: planFrom(config, fromManifest(manifest.migrations)),
+    seeds: seedPlanFrom(config, fromManifest(manifest.seeds)),
+    reset: resetPlanFrom(config),
+});
+export { withDriver } from './connect.js';
+export { reset } from './reset.js';
+export { down, status, up, } from './runner.js';
+export { seed, seedStatus, unseed, } from './seeds.js';
+export { MigrationChangedError } from './storage.js';

package/dist/sql.d.ts

@@ -0,0 +1,50 @@
+import type { Fragment, Queryable, Sql } from './types.js';
+/**
+ * Splice text into a statement verbatim.
+ *
+ * DDL is mostly things that cannot be bind parameters — table names, types,
+ * defaults, whole constraint bodies — so this has to exist. Making it a
+ * function call rather than the default behaviour means every unescaped
+ * interpolation is visible in a diff.
+ */
+export declare const raw: (text: string) => Fragment;
+/**
+ * Quote an identifier as a plain string.
+ *
+ * Separate from {@link id} because the package builds statements of its own —
+ * the bookkeeping table — where a `Fragment` would have to be unwrapped again
+ * to reach the text.
+ */
+export declare const quoteIdent: (name: string) => string;
+/** Quote an identifier. `id('user table')` is `"user table"`. */
+export declare const id: (name: string) => Fragment;
+/** Join fragments — a column list, a set of constraints. */
+export declare const join: (parts: readonly Fragment[], separator?: string) => Fragment;
+export interface Statement {
+    text: string;
+    params: unknown[];
+}
+/**
+ * Turns a template into a statement and its bind parameters.
+ *
+ * Anything that is not a {@link Fragment} becomes a `$n` placeholder, so the
+ * ordinary way to interpolate a value is also the safe one and injecting SQL
+ * takes a deliberate `sql.raw`.
+ */
+export declare const build: (strings: TemplateStringsArray, values: readonly unknown[]) => Statement;
+/**
+ * The tagged template bound to one connection — the same `sql` a migration
+ * receives in its {@link Context}, constructed over any {@link Queryable}.
+ *
+ * Exported because it is the only constructor for the `Sql` and `Fragment`
+ * types (the brand is a private symbol), and because a {@link Hook} is allowed
+ * to run over a connection this package did not open. There is deliberately no
+ * second `sql` namespace object: the tag is the namespace, so there is exactly
+ * one way to spell `sql.raw` everywhere.
+ *
+ * A template with no interpolated values sends no bind parameters, which is
+ * what lets a migration write several statements in one template: PostgreSQL
+ * only restricts a request to a single statement once the extended protocol is
+ * in play, and that starts at the first parameter.
+ */
+export declare const createSql: (db: Queryable) => Sql;

package/dist/sql.js

@@ -0,0 +1,73 @@
+/**
+ * The runtime half of {@link Fragment}'s brand.
+ *
+ * `types.ts` declares the property with a `unique symbol` that has no value, so
+ * the brand costs nothing at run time and cannot be forged by writing an object
+ * literal. This is the only place that gap is bridged.
+ */
+const MARK = Symbol('migrane.fragment');
+const isFragment = (value) => typeof value === 'object' && value !== null && MARK in value;
+/**
+ * Splice text into a statement verbatim.
+ *
+ * DDL is mostly things that cannot be bind parameters — table names, types,
+ * defaults, whole constraint bodies — so this has to exist. Making it a
+ * function call rather than the default behaviour means every unescaped
+ * interpolation is visible in a diff.
+ */
+export const raw = (text) => ({ [MARK]: text });
+/**
+ * Quote an identifier as a plain string.
+ *
+ * Separate from {@link id} because the package builds statements of its own —
+ * the bookkeeping table — where a `Fragment` would have to be unwrapped again
+ * to reach the text.
+ */
+export const quoteIdent = (name) => `"${name.replaceAll('"', '""')}"`;
+/** Quote an identifier. `id('user table')` is `"user table"`. */
+export const id = (name) => raw(quoteIdent(name));
+/** Join fragments — a column list, a set of constraints. */
+export const join = (parts, separator = ', ') => raw(parts.map((part) => part[MARK]).join(separator));
+/**
+ * Turns a template into a statement and its bind parameters.
+ *
+ * Anything that is not a {@link Fragment} becomes a `$n` placeholder, so the
+ * ordinary way to interpolate a value is also the safe one and injecting SQL
+ * takes a deliberate `sql.raw`.
+ */
+export const build = (strings, values) => {
+    let text = strings[0] ?? '';
+    const params = [];
+    for (const [index, value] of values.entries()) {
+        if (isFragment(value))
+            text += value[MARK];
+        else {
+            params.push(value);
+            text += `$${params.length}`;
+        }
+        text += strings[index + 1] ?? '';
+    }
+    return { text, params };
+};
+/**
+ * The tagged template bound to one connection — the same `sql` a migration
+ * receives in its {@link Context}, constructed over any {@link Queryable}.
+ *
+ * Exported because it is the only constructor for the `Sql` and `Fragment`
+ * types (the brand is a private symbol), and because a {@link Hook} is allowed
+ * to run over a connection this package did not open. There is deliberately no
+ * second `sql` namespace object: the tag is the namespace, so there is exactly
+ * one way to spell `sql.raw` everywhere.
+ *
+ * A template with no interpolated values sends no bind parameters, which is
+ * what lets a migration write several statements in one template: PostgreSQL
+ * only restricts a request to a single statement once the extended protocol is
+ * in play, and that starts at the first parameter.
+ */
+export const createSql = (db) => {
+    const tag = (strings, ...values) => {
+        const { text, params } = build(strings, values);
+        return db.query(text, params.length ? params : undefined);
+    };
+    return Object.assign(tag, { raw, id, join });
+};

package/dist/storage.d.ts

@@ -0,0 +1,52 @@
+import type { Queryable, Row } from './types.js';
+/**
+ * The bookkeeping table, and the two questions it answers: what has run, and
+ * whether what ran is still what is on disk.
+ */
+export interface Applied extends Row {
+    name: string;
+    checksum: string;
+    run_at: string;
+}
+/**
+ * A migration was edited after it was applied.
+ *
+ * A class rather than a plain `Error` so a caller that *knows* its database is
+ * disposable — a test lane, a scratch container — can recover from exactly this
+ * and nothing else. Matching on the message would catch the next error whose
+ * wording happened to look similar, which is how a recovery path ends up
+ * dropping a schema it was never meant to touch.
+ */
+export declare class MigrationChangedError extends Error {
+    readonly migration: string;
+    constructor(migration: string);
+}
+/**
+ * Written on first contact rather than by a setup command, so a database that
+ * has never been migrated needs no preparation — `status` against an empty one
+ * answers "everything is pending" instead of failing on a missing table.
+ */
+export declare const ensure: (db: Queryable, table: string) => Promise<void>;
+export declare const applied: (db: Queryable, table: string) => Promise<Applied[]>;
+/**
+ * Refuses a migration that changed after it was applied.
+ *
+ * A migration already run is a fact about the database, and editing one makes
+ * the file stop describing what the database actually holds — silently, and
+ * only on the machines that already ran it. So it is caught before anything
+ * else runs.
+ *
+ * A name recorded but absent from disk is *not* an error: deleting or renaming
+ * migrations is what squashing them into one looks like, and refusing that
+ * would make a legitimate operation impossible.
+ */
+export declare const verify: (rows: readonly Applied[], migrations: readonly {
+    name: string;
+    checksum: string;
+}[]) => void;
+export declare const record: (db: Queryable, table: string, entry: {
+    name: string;
+    checksum: string;
+    duration: number;
+}) => Promise<void>;
+export declare const forget: (db: Queryable, table: string, name: string) => Promise<void>;

package/dist/storage.js

@@ -0,0 +1,65 @@
+import { quoteIdent } from './sql.js';
+/**
+ * A migration was edited after it was applied.
+ *
+ * A class rather than a plain `Error` so a caller that *knows* its database is
+ * disposable — a test lane, a scratch container — can recover from exactly this
+ * and nothing else. Matching on the message would catch the next error whose
+ * wording happened to look similar, which is how a recovery path ends up
+ * dropping a schema it was never meant to touch.
+ */
+export class MigrationChangedError extends Error {
+    migration;
+    constructor(migration) {
+        super(`"${migration}" changed after it was applied.\n` +
+            `  Reset the database if it is disposable, or add a new migration if it is not.`);
+        this.migration = migration;
+        this.name = 'MigrationChangedError';
+    }
+}
+/**
+ * Written on first contact rather than by a setup command, so a database that
+ * has never been migrated needs no preparation — `status` against an empty one
+ * answers "everything is pending" instead of failing on a missing table.
+ */
+export const ensure = async (db, table) => {
+    await db.query(`
+    CREATE TABLE IF NOT EXISTS ${quoteIdent(table)} (
+      name         TEXT PRIMARY KEY,
+      checksum     TEXT NOT NULL DEFAULT '',
+      run_at       TIMESTAMPTZ NOT NULL DEFAULT now(),
+      duration_ms  INTEGER
+    )
+  `);
+};
+export const applied = async (db, table) => {
+    await ensure(db, table);
+    return db.query(`SELECT name, checksum, run_at FROM ${quoteIdent(table)} ORDER BY run_at, name`);
+};
+/**
+ * Refuses a migration that changed after it was applied.
+ *
+ * A migration already run is a fact about the database, and editing one makes
+ * the file stop describing what the database actually holds — silently, and
+ * only on the machines that already ran it. So it is caught before anything
+ * else runs.
+ *
+ * A name recorded but absent from disk is *not* an error: deleting or renaming
+ * migrations is what squashing them into one looks like, and refusing that
+ * would make a legitimate operation impossible.
+ */
+export const verify = (rows, migrations) => {
+    const disk = new Map(migrations.map(({ name, checksum }) => [name, checksum]));
+    for (const row of rows) {
+        const current = disk.get(row.name);
+        if (current === undefined || current === row.checksum)
+            continue;
+        throw new MigrationChangedError(row.name);
+    }
+};
+export const record = async (db, table, entry) => {
+    await db.query(`INSERT INTO ${quoteIdent(table)} (name, checksum, duration_ms) VALUES ($1, $2, $3)`, [entry.name, entry.checksum, entry.duration]);
+};
+export const forget = async (db, table, name) => {
+    await db.query(`DELETE FROM ${quoteIdent(table)} WHERE name = $1`, [name]);
+};