@shaferllc/keel 0.68.0 → 0.74.0

package/dist/core/console.js

@@ -0,0 +1,395 @@
+/**
+ * The console — a real command system, not a wrapper round `process.argv`.
+ *
+ *   export const greet = defineCommand({
+ *     name: "greet",
+ *     description: "Greet someone",
+ *     args: { name: arg.string({ description: "who to greet" }) },
+ *     flags: { loud: flag.boolean({ alias: "l", description: "SHOUT IT" }) },
+ *
+ *     async run({ args, flags, ui }) {
+ *       const message = `Hello, ${args.name}!`;
+ *       ui.success(flags.loud ? message.toUpperCase() : message);
+ *     },
+ *   });
+ *
+ * `args.name` is a `string` and `flags.loud` is a `boolean` — **inferred from the
+ * spec**, not cast. Declare an arg optional and its type becomes `string |
+ * undefined`; give it a default and it's a `string` again. The types can't drift
+ * from the parsing, because the parsing is generated from them.
+ *
+ * A command gets a `ui` (colors, tables, tasks, spinners) and a `prompt` (ask,
+ * confirm, choice…), both of which switch to a captured, colorless "raw" mode
+ * under test, so you can assert on what a command printed and script its answers.
+ */
+/** Positional arguments: `keel greet <name>`. */
+export const arg = {
+    string(options) {
+        return { kind: "arg", type: "string", required: true, ...options };
+    },
+    number(options) {
+        return { kind: "arg", type: "number", required: true, ...options };
+    },
+    /** Swallows every remaining value. Must be the last argument. */
+    spread(options) {
+        return { kind: "arg", type: "spread", required: true, ...options };
+    },
+};
+/** Named options: `--force`, `-f`, `--name=Ada`. */
+export const flag = {
+    /** `--force` / `-f`, and `--no-force`. Defaults to `false`, so it's never undefined. */
+    boolean(options) {
+        return { kind: "flag", type: "boolean", required: false, default: false, ...options };
+    },
+    string(options) {
+        return { kind: "flag", type: "string", required: false, ...options };
+    },
+    number(options) {
+        return { kind: "flag", type: "number", required: false, ...options };
+    },
+    /** Repeatable: `--tag a --tag b` gives `["a", "b"]`. Defaults to `[]`. */
+    array(options) {
+        return { kind: "flag", type: "array", required: false, default: [], ...options };
+    },
+};
+/**
+ * Define a command. The `args` and `flags` you declare become the types of
+ * `args` and `flags` inside `run` — the whole point of the exercise.
+ */
+export function defineCommand(definition) {
+    return definition;
+}
+/** Thrown when the argv doesn't fit the command's spec. */
+export class ConsoleError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ConsoleError";
+    }
+}
+/* --------------------------------- parsing -------------------------------- */
+function coerce(spec, raw, label) {
+    if (spec.parse)
+        return spec.parse(raw);
+    if (spec.type === "number") {
+        const value = Number(raw);
+        if (Number.isNaN(value))
+            throw new ConsoleError(`${label} expects a number, got "${raw}".`);
+        return value;
+    }
+    return raw;
+}
+/**
+ * Turn argv into a command's args and flags.
+ *
+ * Handles `--flag value`, `--flag=value`, `--no-flag`, `-f value`, bundled short
+ * flags (`-abc`), repeatable array flags, a `--` terminator, and a trailing
+ * spread argument.
+ */
+export function parseArgv(argv, definition) {
+    const argSpecs = Object.entries(definition.args ?? {});
+    const flagSpecs = Object.entries(definition.flags ?? {});
+    const byAlias = new Map();
+    for (const [name, spec] of flagSpecs)
+        if (spec.alias)
+            byAlias.set(spec.alias, name);
+    const flags = {};
+    const positional = [];
+    const rest = [];
+    const specFor = (token) => {
+        const name = byAlias.get(token) ?? token;
+        const spec = definition.flags?.[name];
+        return spec ? [name, spec] : undefined;
+    };
+    const setFlag = (name, spec, raw) => {
+        const label = `--${name}`;
+        if (spec.type === "array") {
+            const list = flags[name] ?? [];
+            list.push(String(coerce(spec, raw, label)));
+            flags[name] = list;
+        }
+        else {
+            flags[name] = coerce(spec, raw, label);
+        }
+    };
+    for (let i = 0; i < argv.length; i++) {
+        const token = argv[i];
+        // Everything after `--` is verbatim.
+        if (token === "--") {
+            rest.push(...argv.slice(i + 1));
+            break;
+        }
+        if (token.startsWith("--")) {
+            const body = token.slice(2);
+            const eq = body.indexOf("=");
+            const name = eq === -1 ? body : body.slice(0, eq);
+            const inline = eq === -1 ? undefined : body.slice(eq + 1);
+            // `--no-force` turns a boolean off.
+            if (name.startsWith("no-")) {
+                const found = specFor(name.slice(3));
+                if (found && found[1].type === "boolean") {
+                    flags[found[0]] = false;
+                    continue;
+                }
+            }
+            const found = specFor(name);
+            if (!found) {
+                if (definition.allowUnknownFlags) {
+                    rest.push(token);
+                    continue;
+                }
+                throw new ConsoleError(`Unknown flag "--${name}".`);
+            }
+            const [key, spec] = found;
+            if (spec.type === "boolean") {
+                flags[key] = inline === undefined ? true : inline !== "false";
+                continue;
+            }
+            const value = inline ?? argv[++i];
+            if (value === undefined)
+                throw new ConsoleError(`Flag "--${key}" expects a value.`);
+            setFlag(key, spec, value);
+            continue;
+        }
+        // `-f`, or bundled `-abc` where only the last may take a value.
+        if (token.startsWith("-") && token.length > 1) {
+            const letters = [...token.slice(1)];
+            for (let j = 0; j < letters.length; j++) {
+                const letter = letters[j];
+                const found = specFor(letter);
+                if (!found) {
+                    if (definition.allowUnknownFlags) {
+                        rest.push(`-${letter}`);
+                        continue;
+                    }
+                    throw new ConsoleError(`Unknown flag "-${letter}".`);
+                }
+                const [key, spec] = found;
+                if (spec.type === "boolean") {
+                    flags[key] = true;
+                    continue;
+                }
+                // A value-taking flag must be last in the bundle.
+                const value = j === letters.length - 1 ? argv[++i] : letters.slice(j + 1).join("");
+                if (value === undefined)
+                    throw new ConsoleError(`Flag "-${letter}" expects a value.`);
+                setFlag(key, spec, value);
+                break;
+            }
+            continue;
+        }
+        positional.push(token);
+    }
+    // Positionals -> declared args.
+    const args = {};
+    let cursor = 0;
+    for (const [name, spec] of argSpecs) {
+        if (spec.type === "spread") {
+            const values = positional.slice(cursor);
+            cursor = positional.length;
+            if (!values.length && spec.required && spec.default === undefined) {
+                throw new ConsoleError(`Missing argument "${name}".`);
+            }
+            args[name] = values.length ? values : (spec.default ?? []);
+            continue;
+        }
+        const raw = positional[cursor++];
+        if (raw === undefined) {
+            if (spec.default !== undefined) {
+                args[name] = spec.default;
+                continue;
+            }
+            if (spec.required)
+                throw new ConsoleError(`Missing argument "${name}".`);
+            args[name] = undefined;
+            continue;
+        }
+        args[name] = coerce(spec, raw, `Argument "${name}"`);
+    }
+    // Leftover positionals nobody claimed.
+    rest.push(...positional.slice(cursor));
+    // Defaults, then required checks.
+    for (const [name, spec] of flagSpecs) {
+        if (flags[name] === undefined && spec.default !== undefined)
+            flags[name] = spec.default;
+        if (flags[name] === undefined && spec.required) {
+            throw new ConsoleError(`Missing required flag "--${name}".`);
+        }
+    }
+    return { args, flags, rest };
+}
+/** Registers commands, parses argv, and runs the right one. */
+export class ConsoleKernel {
+    options;
+    commands = new Map();
+    aliases = new Map();
+    constructor(options = {}) {
+        this.options = options;
+    }
+    get binary() {
+        return this.options.binary ?? "keel";
+    }
+    /** Register one or more commands. */
+    register(...commands) {
+        for (const command of commands) {
+            this.commands.set(command.name, command);
+            for (const alias of command.aliases ?? [])
+                this.aliases.set(alias, command.name);
+        }
+        return this;
+    }
+    /** Every registered command, sorted by name. */
+    list() {
+        return [...this.commands.values()].sort((a, b) => a.name.localeCompare(b.name));
+    }
+    find(name) {
+        return this.commands.get(name) ?? this.commands.get(this.aliases.get(name) ?? "");
+    }
+    async ui() {
+        if (this.options.ui)
+            return this.options.ui;
+        const { createUi } = await import("./console-ui.js");
+        return createUi();
+    }
+    async prompt() {
+        if (this.options.prompt)
+            return this.options.prompt;
+        const { createPrompt } = await import("./console-prompt.js");
+        return createPrompt();
+    }
+    /**
+     * Run a command from argv (without the node/script prefix). Returns the exit
+     * code: 0 for success, 1 for a failure — never throws, because a console is a
+     * bad place to surface a stack trace to a user who mistyped a flag.
+     */
+    async run(argv) {
+        const ui = await this.ui();
+        const [name, ...rest] = argv;
+        // No command, or an explicit ask for help: list what's available.
+        if (!name || name === "help" || name === "--help" || name === "-h") {
+            const target = name === "help" ? rest[0] : undefined;
+            if (target) {
+                const command = this.find(target);
+                if (!command) {
+                    ui.error(`Unknown command "${target}".`);
+                    return 1;
+                }
+                ui.write(this.commandHelp(command));
+                return 0;
+            }
+            ui.write(this.help());
+            return 0;
+        }
+        const command = this.find(name);
+        if (!command) {
+            ui.error(`Unknown command "${name}". Run "${this.binary} help" to see what's available.`);
+            return 1;
+        }
+        // `--help` on a command shows its own help rather than running it.
+        if (rest.includes("--help") || rest.includes("-h")) {
+            ui.write(this.commandHelp(command));
+            return 0;
+        }
+        try {
+            const parsed = parseArgv(rest, command);
+            const prompt = await this.prompt();
+            const code = await command.run({
+                args: parsed.args,
+                flags: parsed.flags,
+                rest: parsed.rest,
+                ui,
+                prompt,
+                kernel: this,
+            });
+            return typeof code === "number" ? code : 0;
+        }
+        catch (error) {
+            // A usage error is the user's mistake — say what's wrong and how to fix it,
+            // don't dump a stack at them.
+            if (error instanceof ConsoleError) {
+                ui.error(error.message);
+                ui.write("");
+                ui.write(this.commandHelp(command));
+                return 1;
+            }
+            ui.error(error instanceof Error ? error.message : String(error));
+            if (error instanceof Error && error.stack && process.env.KEEL_DEBUG) {
+                ui.write(error.stack);
+            }
+            return 1;
+        }
+    }
+    /** The `keel help` screen: every command, grouped by namespace. */
+    help() {
+        const lines = [`Usage: ${this.binary} <command> [options]`, ""];
+        const groups = new Map();
+        for (const command of this.list()) {
+            const namespace = command.name.includes(":") ? command.name.split(":")[0] : "";
+            const group = groups.get(namespace) ?? [];
+            group.push(command);
+            groups.set(namespace, group);
+        }
+        // Ungrouped commands first, then each namespace.
+        const order = [...groups.keys()].sort((a, b) => (a === "" ? -1 : b === "" ? 1 : a.localeCompare(b)));
+        const width = Math.max(...this.list().map((c) => c.name.length), 0);
+        for (const namespace of order) {
+            lines.push(namespace ? `${namespace}:` : "Commands:");
+            for (const command of groups.get(namespace)) {
+                lines.push(`  ${command.name.padEnd(width + 2)}${command.description ?? ""}`);
+            }
+            lines.push("");
+        }
+        lines.push(`Run "${this.binary} help <command>" for more on one of them.`);
+        return lines.join("\n");
+    }
+    /** The help screen for a single command: its usage, args, and flags. */
+    commandHelp(command) {
+        const args = Object.entries(command.args ?? {});
+        const flags = Object.entries(command.flags ?? {});
+        const usage = [`${this.binary} ${command.name}`];
+        for (const [name, spec] of args) {
+            const label = spec.type === "spread" ? `...${name}` : name;
+            usage.push(spec.required && spec.default === undefined ? `<${label}>` : `[${label}]`);
+        }
+        if (flags.length)
+            usage.push("[options]");
+        const lines = [];
+        if (command.description)
+            lines.push(command.description, "");
+        lines.push(`Usage: ${usage.join(" ")}`, "");
+        if (args.length) {
+            lines.push("Arguments:");
+            const width = Math.max(...args.map(([n]) => n.length));
+            for (const [name, spec] of args) {
+                const meta = [];
+                if (!spec.required || spec.default !== undefined)
+                    meta.push("optional");
+                if (spec.default !== undefined)
+                    meta.push(`default: ${JSON.stringify(spec.default)}`);
+                const suffix = meta.length ? ` (${meta.join(", ")})` : "";
+                lines.push(`  ${name.padEnd(width + 2)}${spec.description ?? ""}${suffix}`);
+            }
+            lines.push("");
+        }
+        if (flags.length) {
+            lines.push("Options:");
+            const labels = flags.map(([name, spec]) => (spec.alias ? `-${spec.alias}, --${name}` : `    --${name}`));
+            const width = Math.max(...labels.map((l) => l.length));
+            flags.forEach(([, spec], i) => {
+                const meta = [];
+                if (spec.required)
+                    meta.push("required");
+                if (spec.default !== undefined && spec.type !== "boolean" && spec.type !== "array") {
+                    meta.push(`default: ${JSON.stringify(spec.default)}`);
+                }
+                const suffix = meta.length ? ` (${meta.join(", ")})` : "";
+                lines.push(`  ${labels[i].padEnd(width + 2)}${spec.description ?? ""}${suffix}`);
+            });
+            lines.push("");
+        }
+        if (command.aliases?.length)
+            lines.push(`Aliases: ${command.aliases.join(", ")}`, "");
+        if (command.help?.length)
+            lines.push(...command.help, "");
+        return lines.join("\n").replace(/\n+$/, "");
+    }
+}

package/dist/core/database.d.ts

@@ -28,11 +28,32 @@ export interface Connection {
     select(sql: string, bindings: unknown[]): Promise<Row[]>;
     /** Run an INSERT/UPDATE/DELETE and return write metadata. */
     write(sql: string, bindings: unknown[]): Promise<WriteResult>;
+    /**
+     * Start a transaction on a **dedicated** connection.
+     *
+     * This is optional, but it is not optional for a *pooled* driver, and getting
+     * that wrong is the classic way to ship a transaction that silently isn't one:
+     * a pool hands each statement to whichever connection is free, so a `BEGIN`
+     * and the `INSERT` after it can land on different connections. The `BEGIN`
+     * then wraps nothing, the `COMMIT` commits nothing, and a failure half-writes.
+     *
+     * A driver that pools MUST implement this by checking out one connection and
+     * running the whole transaction on it. A driver that owns a single connection
+     * (SQLite, libSQL, a bare `pg.Client`) can leave it out, and Keel falls back to
+     * issuing `BEGIN` / `COMMIT` / `ROLLBACK` on the connection it has.
+     */
+    begin?(): Promise<TransactionConnection>;
+}
+/** A connection with an open transaction on it. */
+export interface TransactionConnection extends Connection {
+    commit(): Promise<void>;
+    rollback(): Promise<void>;
 }
 export type Dialect = "sqlite" | "mysql" | "postgres";
 export type Operator = "=" | "!=" | "<" | "<=" | ">" | ">=" | "like";
-/** A registered connection — the driver bridge plus its SQL dialect. */
+/** A registered connection — the driver bridge, its name, and its SQL dialect. */
 interface Source {
+    name: string;
     conn: Connection;
     dialect: Dialect;
 }
@@ -124,5 +145,53 @@ export interface ConnectionHandle {
  *   const reporting = connection("reporting");
  *   await reporting.table("events").where("kind", "signup").count();
  */
+/** A handle to the transaction in flight, handed to `transaction()`'s callback. */
+export interface TransactionHandle extends ConnectionHandle {
+    /**
+     * Roll back now and abandon the rest of the transaction. The callback should
+     * return straight after — queries on a rolled-back transaction will fail.
+     */
+    rollback(): Promise<void>;
+    /** 0 for the outermost transaction; deeper values are savepoints. */
+    readonly depth: number;
+}
+/**
+ * Run `fn` inside a database transaction. It commits when `fn` returns, and
+ * **rolls back if `fn` throws** — which is the entire point: two related writes
+ * either both land or neither does, so a failure between them can't leave the row
+ * charged and the order missing.
+ *
+ *   await transaction(async () => {
+ *     await db("orders").insert(order);
+ *     await db("stock").where("id", id).decrement("count");   // a throw here undoes the insert
+ *   });
+ *
+ * Queries inside are **ambient**: `db()`, models, and relations all pick up the
+ * transaction's connection without being handed it. The callback also gets an
+ * explicit handle if you'd rather be obvious about it:
+ *
+ *   await transaction(async (tx) => {
+ *     await tx.table("orders").insert(order);
+ *   });
+ *
+ * **Nesting uses savepoints.** A `transaction()` inside another doesn't open a
+ * second transaction — databases don't have those — it takes a savepoint, so an
+ * inner failure rolls back only the inner work and the outer transaction carries
+ * on. Without that, a nested helper's failure would silently abandon its caller's
+ * writes too.
+ */
+export declare function transaction<T>(fn: (tx: TransactionHandle) => Promise<T> | T, connectionName?: string): Promise<T>;
+/** Whether a transaction is open on this connection in the current context. */
+export declare function inTransaction(connectionName?: string): boolean;
 export declare function connection(name?: string): ConnectionHandle;
+/**
+ * The raw driver bridge and dialect for a connection (or the default) — what the
+ * `Migrator` needs. Unlike `connection()`, this hands back the unadjusted
+ * `Connection` so the migrator can apply its own placeholder conversion.
+ */
+export declare function getConnection(name?: string): {
+    connection: Connection;
+    dialect: Dialect;
+    name: string;
+};
 export {};