@shaferllc/keel 0.12.0 → 0.35.0

package/dist/core/migrations.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Schema builder + migrator. Define migrations as `{ name, up, down }`, describe
+ * tables with a fluent schema builder, and run them through your registered
+ * connection. Dialect-aware SQL (sqlite / mysql / postgres), edge-safe.
+ *
+ *   const migrations: Migration[] = [{
+ *     name: "01_create_users",
+ *     up: (s) => s.createTable("users", (t) => {
+ *       t.id();
+ *       t.string("email").unique();
+ *       t.timestamps();
+ *     }),
+ *     down: (s) => s.dropTable("users"),
+ *   }];
+ *
+ *   await new Migrator(connection, "postgres").up(migrations);
+ */
+import type { Connection, Dialect } from "./database.js";
+type ColumnType = "id" | "string" | "text" | "integer" | "bigInteger" | "boolean" | "timestamp" | "json";
+export declare class Column {
+    private column;
+    private type;
+    private length?;
+    private _nullable;
+    private _unique;
+    private _default;
+    private hasDefault;
+    constructor(column: string, type: ColumnType, length?: number | undefined);
+    nullable(): this;
+    unique(): this;
+    default(value: unknown): this;
+    toSql(dialect: Dialect): string;
+}
+export declare class TableBuilder {
+    readonly columns: Column[];
+    private add;
+    id(name?: string): Column;
+    string(name: string, length?: number): Column;
+    text(name: string): Column;
+    integer(name: string): Column;
+    bigInteger(name: string): Column;
+    boolean(name: string): Column;
+    timestamp(name: string): Column;
+    json(name: string): Column;
+    /** Adds nullable created_at + updated_at columns. */
+    timestamps(): void;
+    toCreateSql(table: string, dialect: Dialect): string;
+}
+export declare class SchemaBuilder {
+    private conn;
+    private dialect;
+    constructor(conn: Connection, dialect: Dialect);
+    createTable(name: string, build: (table: TableBuilder) => void): Promise<void>;
+    dropTable(name: string): Promise<void>;
+    raw(sql: string, bindings?: unknown[]): Promise<void>;
+}
+export interface Migration {
+    name: string;
+    up(schema: SchemaBuilder): void | Promise<void>;
+    down(schema: SchemaBuilder): void | Promise<void>;
+}
+export declare class Migrator {
+    private conn;
+    private dialect;
+    constructor(conn: Connection, dialect?: Dialect);
+    private ph;
+    private ensure;
+    /** Names of migrations already applied. */
+    ran(): Promise<string[]>;
+    private maxBatch;
+    /** Run all pending migrations. Returns the names applied. */
+    up(migrations: Migration[]): Promise<string[]>;
+    /** Roll back the most recent batch. Returns the names rolled back. */
+    down(migrations: Migration[]): Promise<string[]>;
+}
+export {};

package/dist/core/migrations.js

@@ -0,0 +1,211 @@
+/**
+ * Schema builder + migrator. Define migrations as `{ name, up, down }`, describe
+ * tables with a fluent schema builder, and run them through your registered
+ * connection. Dialect-aware SQL (sqlite / mysql / postgres), edge-safe.
+ *
+ *   const migrations: Migration[] = [{
+ *     name: "01_create_users",
+ *     up: (s) => s.createTable("users", (t) => {
+ *       t.id();
+ *       t.string("email").unique();
+ *       t.timestamps();
+ *     }),
+ *     down: (s) => s.dropTable("users"),
+ *   }];
+ *
+ *   await new Migrator(connection, "postgres").up(migrations);
+ */
+function sqlType(type, dialect, length) {
+    switch (type) {
+        case "id":
+            return dialect === "postgres"
+                ? "SERIAL PRIMARY KEY"
+                : dialect === "mysql"
+                    ? "INT AUTO_INCREMENT PRIMARY KEY"
+                    : "INTEGER PRIMARY KEY AUTOINCREMENT";
+        case "string":
+            return `VARCHAR(${length ?? 255})`;
+        case "text":
+            return "TEXT";
+        case "integer":
+            return "INTEGER";
+        case "bigInteger":
+            return "BIGINT";
+        case "boolean":
+            return dialect === "sqlite" ? "INTEGER" : "BOOLEAN";
+        case "timestamp":
+            return dialect === "sqlite" ? "DATETIME" : "TIMESTAMP";
+        case "json":
+            return dialect === "postgres" ? "JSONB" : "TEXT";
+    }
+}
+export class Column {
+    column;
+    type;
+    length;
+    _nullable = false;
+    _unique = false;
+    _default;
+    hasDefault = false;
+    constructor(column, type, length) {
+        this.column = column;
+        this.type = type;
+        this.length = length;
+    }
+    nullable() {
+        this._nullable = true;
+        return this;
+    }
+    unique() {
+        this._unique = true;
+        return this;
+    }
+    default(value) {
+        this._default = value;
+        this.hasDefault = true;
+        return this;
+    }
+    toSql(dialect) {
+        let sql = `${this.column} ${sqlType(this.type, dialect, this.length)}`;
+        if (this.type !== "id")
+            sql += this._nullable ? "" : " NOT NULL";
+        if (this._unique)
+            sql += " UNIQUE";
+        if (this.hasDefault) {
+            const v = this._default;
+            const rendered = typeof v === "string"
+                ? `'${v}'`
+                : typeof v === "boolean"
+                    ? dialect === "sqlite"
+                        ? v
+                            ? "1"
+                            : "0"
+                        : String(v)
+                    : String(v);
+            sql += ` DEFAULT ${rendered}`;
+        }
+        return sql;
+    }
+}
+export class TableBuilder {
+    columns = [];
+    add(name, type, length) {
+        const col = new Column(name, type, length);
+        this.columns.push(col);
+        return col;
+    }
+    id(name = "id") {
+        return this.add(name, "id");
+    }
+    string(name, length = 255) {
+        return this.add(name, "string", length);
+    }
+    text(name) {
+        return this.add(name, "text");
+    }
+    integer(name) {
+        return this.add(name, "integer");
+    }
+    bigInteger(name) {
+        return this.add(name, "bigInteger");
+    }
+    boolean(name) {
+        return this.add(name, "boolean");
+    }
+    timestamp(name) {
+        return this.add(name, "timestamp");
+    }
+    json(name) {
+        return this.add(name, "json");
+    }
+    /** Adds nullable created_at + updated_at columns. */
+    timestamps() {
+        this.timestamp("created_at").nullable();
+        this.timestamp("updated_at").nullable();
+    }
+    toCreateSql(table, dialect) {
+        return `CREATE TABLE ${table} (${this.columns.map((c) => c.toSql(dialect)).join(", ")})`;
+    }
+}
+export class SchemaBuilder {
+    conn;
+    dialect;
+    constructor(conn, dialect) {
+        this.conn = conn;
+        this.dialect = dialect;
+    }
+    async createTable(name, build) {
+        const table = new TableBuilder();
+        build(table);
+        await this.conn.write(table.toCreateSql(name, this.dialect), []);
+    }
+    async dropTable(name) {
+        await this.conn.write(`DROP TABLE IF EXISTS ${name}`, []);
+    }
+    async raw(sql, bindings = []) {
+        await this.conn.write(sql, bindings);
+    }
+}
+export class Migrator {
+    conn;
+    dialect;
+    constructor(conn, dialect = "sqlite") {
+        this.conn = conn;
+        this.dialect = dialect;
+    }
+    ph(sql) {
+        if (this.dialect !== "postgres")
+            return sql;
+        let i = 0;
+        return sql.replace(/\?/g, () => `$${++i}`);
+    }
+    async ensure() {
+        await this.conn.write("CREATE TABLE IF NOT EXISTS migrations (name VARCHAR(255) PRIMARY KEY, batch INTEGER NOT NULL)", []);
+    }
+    /** Names of migrations already applied. */
+    async ran() {
+        await this.ensure();
+        const rows = await this.conn.select("SELECT name FROM migrations", []);
+        return rows.map((r) => String(r.name));
+    }
+    async maxBatch() {
+        const rows = await this.conn.select("SELECT MAX(batch) AS b FROM migrations", []);
+        return Number(rows[0]?.b ?? 0);
+    }
+    /** Run all pending migrations. Returns the names applied. */
+    async up(migrations) {
+        const ran = await this.ran();
+        const batch = (await this.maxBatch()) + 1;
+        const schema = new SchemaBuilder(this.conn, this.dialect);
+        const applied = [];
+        for (const m of migrations) {
+            if (ran.includes(m.name))
+                continue;
+            await m.up(schema);
+            await this.conn.write(this.ph("INSERT INTO migrations (name, batch) VALUES (?, ?)"), [
+                m.name,
+                batch,
+            ]);
+            applied.push(m.name);
+        }
+        return applied;
+    }
+    /** Roll back the most recent batch. Returns the names rolled back. */
+    async down(migrations) {
+        await this.ensure();
+        const batch = await this.maxBatch();
+        if (!batch)
+            return [];
+        const rows = await this.conn.select(this.ph("SELECT name FROM migrations WHERE batch = ?"), [batch]);
+        const schema = new SchemaBuilder(this.conn, this.dialect);
+        const rolled = [];
+        for (const name of rows.map((r) => String(r.name)).reverse()) {
+            const migration = migrations.find((m) => m.name === name);
+            if (migration)
+                await migration.down(schema);
+            await this.conn.write(this.ph("DELETE FROM migrations WHERE name = ?"), [name]);
+            rolled.push(name);
+        }
+        return rolled;
+    }
+}

package/dist/core/model.d.ts

@@ -0,0 +1,75 @@
+/**
+ * A tiny active-record Model over the query builder. Subclass it, point it at a
+ * table, and get `find` / `all` / `create` / `save` / `delete` — no ORM to
+ * configure. Backed by whatever `Connection` you registered with
+ * `setConnection()`, so it runs on Node and the edge.
+ *
+ *   class User extends Model {
+ *     static table = "users";
+ *     declare id: number;
+ *     declare email: string;
+ *   }
+ *
+ *   const user = await User.find(1);
+ *   const created = await User.create({ email });
+ *   user.email = "new@x.com";
+ *   await user.save();
+ */
+import { type QueryBuilder, type Row } from "./database.js";
+import { BelongsTo, BelongsToMany, HasMany, HasOne } from "./relations.js";
+import { type Casts } from "./casts.js";
+type ModelClass<T extends Model> = (new (attributes?: Row) => T) & typeof Model;
+export declare class Model {
+    static table: string;
+    static primaryKey: string;
+    /** Columns mass-assignable via `create`/`fill` (allowlist). */
+    static fillable: string[];
+    /** Columns NOT mass-assignable (denylist). Ignored when `fillable` is set. */
+    static guarded: string[];
+    /** Column -> cast type; values round-trip as real JS types. */
+    static casts: Casts;
+    [key: string]: unknown;
+    constructor(attributes?: Row);
+    /** A raw query builder scoped to this model's table. */
+    static query(): QueryBuilder;
+    /** Keep only the attributes mass-assignment allows (fillable / guarded). */
+    static filterFillable(attributes: Row): Row;
+    /** Cast attributes to their storable primitives for a write. */
+    static toDatabase(attributes: Row): Row;
+    static all<T extends Model>(this: ModelClass<T>): Promise<T[]>;
+    static find<T extends Model>(this: ModelClass<T>, id: unknown): Promise<T | null>;
+    static findOrFail<T extends Model>(this: ModelClass<T>, id: unknown): Promise<T>;
+    static first<T extends Model>(this: ModelClass<T>): Promise<T | null>;
+    /** Fetch models matching a simple equality condition. */
+    static where<T extends Model>(this: ModelClass<T>, column: string, value: unknown): Promise<T[]>;
+    static create<T extends Model>(this: ModelClass<T>, attributes: Row): Promise<T>;
+    /**
+     * Eager-load relations onto an array of models with one extra query each —
+     * the fix for N+1. Each name must be a relationship method on the model.
+     */
+    static load<T extends Model>(models: T[], ...names: string[]): Promise<T[]>;
+    private ctor;
+    /** The default foreign key a child of this model would carry (e.g. `user_id`). */
+    private foreignKeyName;
+    /** This model has many `related` rows, joined by a foreign key on `related`. */
+    hasMany<T extends Model>(related: ModelClass<T>, foreignKey?: string, localKey?: string): HasMany<T>;
+    /** This model has one `related` row, joined by a foreign key on `related`. */
+    hasOne<T extends Model>(related: ModelClass<T>, foreignKey?: string, localKey?: string): HasOne<T>;
+    /** This model belongs to a `related` row via a foreign key it carries. */
+    belongsTo<T extends Model>(related: ModelClass<T>, foreignKey?: string, ownerKey?: string): BelongsTo<T>;
+    /** Many-to-many through a pivot table (default name: the two tables, sorted). */
+    belongsToMany<T extends Model>(related: ModelClass<T>, pivotTable?: string, foreignPivotKey?: string, relatedPivotKey?: string, parentKey?: string, relatedKey?: string): BelongsToMany<T>;
+    /** Store an eager-loaded relation result under `name`. */
+    setRelation(name: string, value: unknown): this;
+    /** Read a previously loaded relation (returns undefined if not loaded). */
+    getRelation<T = unknown>(name: string): T | undefined;
+    /** Insert (no primary key) or update (has one). */
+    save(): Promise<this>;
+    delete(): Promise<void>;
+    /** Merge mass-assignable attributes into the model (cast, not saved). */
+    fill(attributes: Row): this;
+    /** Force-assign attributes, bypassing mass-assignment guarding (still cast). */
+    forceFill(attributes: Row): this;
+    toJSON(): Row;
+}
+export {};

package/dist/core/model.js

@@ -0,0 +1,202 @@
+/**
+ * A tiny active-record Model over the query builder. Subclass it, point it at a
+ * table, and get `find` / `all` / `create` / `save` / `delete` — no ORM to
+ * configure. Backed by whatever `Connection` you registered with
+ * `setConnection()`, so it runs on Node and the edge.
+ *
+ *   class User extends Model {
+ *     static table = "users";
+ *     declare id: number;
+ *     declare email: string;
+ *   }
+ *
+ *   const user = await User.find(1);
+ *   const created = await User.create({ email });
+ *   user.email = "new@x.com";
+ *   await user.save();
+ */
+import { db } from "./database.js";
+import { NotFoundException } from "./exceptions.js";
+import { BelongsTo, BelongsToMany, HasMany, HasOne } from "./relations.js";
+import { applyCasts, castGet, castSet } from "./casts.js";
+/**
+ * Loaded relations live off the model itself so they never leak into `save()`
+ * (which spreads own columns) — they're keyed here by the owning instance.
+ */
+const relationStore = new WeakMap();
+function serialize(value) {
+    if (Array.isArray(value))
+        return value.map(serialize);
+    if (value instanceof Model)
+        return value.toJSON();
+    return value;
+}
+export class Model {
+    static table = "";
+    static primaryKey = "id";
+    /** Columns mass-assignable via `create`/`fill` (allowlist). */
+    static fillable = [];
+    /** Columns NOT mass-assignable (denylist). Ignored when `fillable` is set. */
+    static guarded = [];
+    /** Column -> cast type; values round-trip as real JS types. */
+    static casts = {};
+    constructor(attributes = {}) {
+        // Hydration is unguarded (rows come from the database) but always cast.
+        Object.assign(this, applyCasts(attributes, this.constructor.casts, castGet));
+    }
+    /* ------------------------------ static -------------------------------- */
+    /** A raw query builder scoped to this model's table. */
+    static query() {
+        return db(this.table);
+    }
+    /** Keep only the attributes mass-assignment allows (fillable / guarded). */
+    static filterFillable(attributes) {
+        if (this.fillable.length) {
+            const out = {};
+            for (const key of this.fillable)
+                if (key in attributes)
+                    out[key] = attributes[key];
+            return out;
+        }
+        if (this.guarded.length) {
+            const out = { ...attributes };
+            for (const key of this.guarded)
+                delete out[key];
+            return out;
+        }
+        return { ...attributes };
+    }
+    /** Cast attributes to their storable primitives for a write. */
+    static toDatabase(attributes) {
+        return applyCasts(attributes, this.casts, castSet);
+    }
+    static async all() {
+        const rows = await db(this.table).get();
+        return rows.map((row) => new this(row));
+    }
+    static async find(id) {
+        const row = await db(this.table).where(this.primaryKey, id).first();
+        return row ? new this(row) : null;
+    }
+    static async findOrFail(id) {
+        const model = await this.find(id);
+        if (!model)
+            throw new NotFoundException(`${this.name} ${String(id)} not found`);
+        return model;
+    }
+    static async first() {
+        const row = await db(this.table).first();
+        return row ? new this(row) : null;
+    }
+    /** Fetch models matching a simple equality condition. */
+    static async where(column, value) {
+        const rows = await db(this.table).where(column, value).get();
+        return rows.map((row) => new this(row));
+    }
+    static async create(attributes) {
+        const filtered = this.filterFillable(attributes);
+        const id = await db(this.table).insertGetId(this.toDatabase(filtered));
+        const model = new this(filtered);
+        if (id != null)
+            model[this.primaryKey] = id;
+        return model;
+    }
+    /**
+     * Eager-load relations onto an array of models with one extra query each —
+     * the fix for N+1. Each name must be a relationship method on the model.
+     */
+    static async load(models, ...names) {
+        if (!models.length)
+            return models;
+        for (const name of names) {
+            const method = models[0][name];
+            if (typeof method !== "function") {
+                throw new Error(`${models[0].constructor.name} has no relation "${name}"`);
+            }
+            const relation = method.call(models[0]);
+            await relation.eager(models, name);
+        }
+        return models;
+    }
+    /* ----------------------------- instance ------------------------------- */
+    ctor() {
+        return this.constructor;
+    }
+    /* --------------------------- relationships ---------------------------- */
+    /** The default foreign key a child of this model would carry (e.g. `user_id`). */
+    foreignKeyName() {
+        return `${this.constructor.name.toLowerCase()}_${this.ctor().primaryKey}`;
+    }
+    /** This model has many `related` rows, joined by a foreign key on `related`. */
+    hasMany(related, foreignKey = this.foreignKeyName(), localKey = this.ctor().primaryKey) {
+        return new HasMany(this, related, foreignKey, localKey);
+    }
+    /** This model has one `related` row, joined by a foreign key on `related`. */
+    hasOne(related, foreignKey = this.foreignKeyName(), localKey = this.ctor().primaryKey) {
+        return new HasOne(this, related, foreignKey, localKey);
+    }
+    /** This model belongs to a `related` row via a foreign key it carries. */
+    belongsTo(related, foreignKey = `${related.name.toLowerCase()}_${related.primaryKey}`, ownerKey = related.primaryKey) {
+        return new BelongsTo(this, related, foreignKey, ownerKey);
+    }
+    /** Many-to-many through a pivot table (default name: the two tables, sorted). */
+    belongsToMany(related, pivotTable = [this.constructor.name, related.name]
+        .map((n) => n.toLowerCase())
+        .sort()
+        .join("_"), foreignPivotKey = `${this.constructor.name.toLowerCase()}_${this.ctor().primaryKey}`, relatedPivotKey = `${related.name.toLowerCase()}_${related.primaryKey}`, parentKey = this.ctor().primaryKey, relatedKey = related.primaryKey) {
+        return new BelongsToMany(this, related, pivotTable, foreignPivotKey, relatedPivotKey, parentKey, relatedKey);
+    }
+    /** Store an eager-loaded relation result under `name`. */
+    setRelation(name, value) {
+        const bag = relationStore.get(this) ?? {};
+        bag[name] = value;
+        relationStore.set(this, bag);
+        return this;
+    }
+    /** Read a previously loaded relation (returns undefined if not loaded). */
+    getRelation(name) {
+        return relationStore.get(this)?.[name];
+    }
+    /** Insert (no primary key) or update (has one). */
+    async save() {
+        const ctor = this.ctor();
+        const { table, primaryKey } = ctor;
+        const data = ctor.toDatabase({ ...this });
+        const idValue = data[primaryKey];
+        delete data[primaryKey];
+        if (idValue != null) {
+            await db(table).where(primaryKey, idValue).update(data);
+        }
+        else {
+            const id = await db(table).insertGetId(data);
+            if (id != null)
+                this[primaryKey] = id;
+        }
+        return this;
+    }
+    async delete() {
+        const { table, primaryKey } = this.ctor();
+        await db(table).where(primaryKey, this[primaryKey]).delete();
+    }
+    /** Merge mass-assignable attributes into the model (cast, not saved). */
+    fill(attributes) {
+        const ctor = this.ctor();
+        Object.assign(this, applyCasts(ctor.filterFillable(attributes), ctor.casts, castGet));
+        return this;
+    }
+    /** Force-assign attributes, bypassing mass-assignment guarding (still cast). */
+    forceFill(attributes) {
+        const ctor = this.ctor();
+        Object.assign(this, applyCasts(attributes, ctor.casts, castGet));
+        return this;
+    }
+    toJSON() {
+        const data = applyCasts({ ...this }, this.ctor().casts, castGet);
+        const relations = relationStore.get(this);
+        if (relations) {
+            for (const [name, value] of Object.entries(relations))
+                data[name] = serialize(value);
+        }
+        return data;
+    }
+}

package/dist/core/queue.d.ts

@@ -0,0 +1,73 @@
+/**
+ * A small queue for background work. Dispatch a `Job` (or a plain function) and
+ * a pluggable `QueueDriver` decides when it runs — immediately (the default),
+ * held in memory for a worker to drain, or handed to a real broker. The API
+ * mirrors the database and mail layers (`setQueue` / `dispatch` are to queues
+ * what `setConnection` / `db()` are to the database). The core imports no broker,
+ * so it stays edge-safe.
+ *
+ *   class SendWelcome extends Job {
+ *     constructor(private userId: number) { super(); }
+ *     async handle() { await mail().to(...).send(); }
+ *   }
+ *
+ *   await dispatch(new SendWelcome(user.id));   // runs now with the sync driver
+ *
+ *   // Defer instead, and drain with a worker:
+ *   setQueue(new MemoryDriver());
+ *   await dispatch(new SendWelcome(user.id));   // queued
+ *   await work();                               // runs everything pending
+ */
+/** A unit of background work. Subclass and implement `handle`. */
+export declare abstract class Job {
+    abstract handle(): void | Promise<void>;
+}
+/** Anything dispatchable: a `Job` instance or a plain function. */
+export type Dispatchable = Job | (() => void | Promise<void>);
+export interface JobOptions {
+    /** Seconds to wait before the job becomes available (drivers may honor it). */
+    delay?: number;
+    /** Named queue/lane to place the job on. */
+    queue?: string;
+}
+/** The bridge to your queue backend. */
+export interface QueueDriver {
+    push(job: Dispatchable, options: JobOptions): Promise<void>;
+}
+/** A driver that holds jobs locally and can run them on demand. */
+export interface Drainable {
+    readonly size: number;
+    work(): Promise<number>;
+}
+/** Runs jobs the moment they're dispatched — the default; ideal for dev/tests. */
+export declare class SyncDriver implements QueueDriver {
+    push(job: Dispatchable, _options: JobOptions): Promise<void>;
+}
+export interface QueuedJob {
+    job: Dispatchable;
+    options: JobOptions;
+}
+/** Holds jobs in memory; `work()` drains them. Assert on `.jobs` in tests. */
+export declare class MemoryDriver implements QueueDriver, Drainable {
+    readonly jobs: QueuedJob[];
+    push(job: Dispatchable, options: JobOptions): Promise<void>;
+    get size(): number;
+    /** Run every pending job in FIFO order; returns how many ran. */
+    work(): Promise<number>;
+}
+export declare class Queue {
+    readonly driver: QueueDriver;
+    constructor(driver: QueueDriver);
+    /** Place a job on the queue (the driver decides when it runs). */
+    dispatch(job: Dispatchable, options?: JobOptions): Promise<void>;
+    /** Drain the driver if it holds jobs locally; returns how many ran. */
+    work(): Promise<number>;
+}
+/** Register the default queue driver used by `dispatch()`. */
+export declare function setQueue(driver: QueueDriver): Queue;
+/** The default queue instance. */
+export declare function getQueue(): Queue;
+/** Dispatch a job (or function) onto the default queue. */
+export declare function dispatch(job: Dispatchable, options?: JobOptions): Promise<void>;
+/** Drain the default queue's pending jobs (no-op for immediate drivers). */
+export declare function work(): Promise<number>;