@shaferllc/keel 0.80.0 → 0.81.0

package/dist/core/database.js

@@ -122,6 +122,10 @@ export class QueryBuilder {
     columns = "*";
     _limit;
     _offset;
+    joins = [];
+    groups = [];
+    havings = [];
+    _distinct = false;
     // The connection is resolved lazily, when a query actually runs — so building
     // a query never throws, and an unregistered connection surfaces as a rejected
     // read/write rather than a synchronous error at construction.
@@ -177,10 +181,57 @@ export class QueryBuilder {
         this.wheres.push({ boolean: "AND", sql: `${column} LIKE ?`, bindings: [pattern] });
         return this;
     }
+    /** Compare two columns (no binding): `whereColumn("updated_at", ">", "created_at")`. */
+    whereColumn(first, opOrSecond, second) {
+        const [op, col] = second === undefined ? ["=", opOrSecond] : [opOrSecond, second];
+        this.wheres.push({ boolean: "AND", sql: `${first} ${op} ${col}`, bindings: [] });
+        return this;
+    }
+    /** A raw WHERE fragment with its own bindings. */
+    whereRaw(sql, bindings = []) {
+        this.wheres.push({ boolean: "AND", sql, bindings });
+        return this;
+    }
+    join(table, first, opOrSecond, second) {
+        const [op, col] = second === undefined ? ["=", opOrSecond] : [opOrSecond, second];
+        this.joins.push(`INNER JOIN ${table} ON ${first} ${op} ${col}`);
+        return this;
+    }
+    leftJoin(table, first, opOrSecond, second) {
+        const [op, col] = second === undefined ? ["=", opOrSecond] : [opOrSecond, second];
+        this.joins.push(`LEFT JOIN ${table} ON ${first} ${op} ${col}`);
+        return this;
+    }
+    groupBy(...columns) {
+        this.groups.push(...columns);
+        return this;
+    }
+    having(column, opOrValue, value) {
+        const [op, val] = value === undefined ? ["=", opOrValue] : [opOrValue, value];
+        this.havings.push({ boolean: "AND", sql: `${column} ${op} ?`, bindings: [val] });
+        return this;
+    }
+    distinct() {
+        this._distinct = true;
+        return this;
+    }
+    /** Apply `then` only when `condition` is truthy (optionally `otherwise`). */
+    when(condition, then, otherwise) {
+        if (condition)
+            then(this, condition);
+        else
+            otherwise?.(this, condition);
+        return this;
+    }
     orderBy(column, direction = "asc") {
         this.orders.push(`${column} ${direction.toUpperCase()}`);
         return this;
     }
+    /** A raw ORDER BY fragment, e.g. `orderByRaw("LENGTH(name) DESC")`. */
+    orderByRaw(sql) {
+        this.orders.push(sql);
+        return this;
+    }
     /** Newest-first / oldest-first by a timestamp column (default `created_at`). */
     latest(column = "created_at") {
         return this.orderBy(column, "desc");
@@ -203,17 +254,32 @@ export class QueryBuilder {
             this.wheres.map((w, i) => (i === 0 ? "" : `${w.boolean} `) + w.sql).join(" ");
         return { sql, bindings: this.wheres.flatMap((w) => w.bindings) };
     }
+    havingClause() {
+        if (!this.havings.length)
+            return { sql: "", bindings: [] };
+        const sql = " HAVING " +
+            this.havings.map((w, i) => (i === 0 ? "" : `${w.boolean} `) + w.sql).join(" ");
+        return { sql, bindings: this.havings.flatMap((w) => w.bindings) };
+    }
+    joinSql() {
+        return this.joins.length ? ` ${this.joins.join(" ")}` : "";
+    }
     /* ------------------------------- reads ------------------------------- */
     async get() {
         const where = this.whereClause();
-        let sql = `SELECT ${this.columns} FROM ${this.table}${where.sql}`;
+        const having = this.havingClause();
+        let sql = `SELECT ${this._distinct ? "DISTINCT " : ""}${this.columns} FROM ${this.table}`;
+        sql += this.joinSql() + where.sql;
+        if (this.groups.length)
+            sql += ` GROUP BY ${this.groups.join(", ")}`;
+        sql += having.sql;
         if (this.orders.length)
             sql += ` ORDER BY ${this.orders.join(", ")}`;
         if (this._limit != null)
             sql += ` LIMIT ${this._limit}`;
         if (this._offset != null)
             sql += ` OFFSET ${this._offset}`;
-        return (await this.runSelect(sql, where.bindings));
+        return (await this.runSelect(sql, [...where.bindings, ...having.bindings]));
     }
     async first() {
         this._limit = 1;
@@ -222,7 +288,7 @@ export class QueryBuilder {
     }
     async count() {
         const where = this.whereClause();
-        const rows = (await this.runSelect(`SELECT COUNT(*) AS count FROM ${this.table}${where.sql}`, where.bindings));
+        const rows = (await this.runSelect(`SELECT COUNT(*) AS count FROM ${this.table}${this.joinSql()}${where.sql}`, where.bindings));
         return Number(rows[0]?.count ?? 0);
     }
     async exists() {
@@ -230,7 +296,7 @@ export class QueryBuilder {
     }
     async aggregate(fn, column) {
         const where = this.whereClause();
-        const rows = (await this.runSelect(`SELECT ${fn}(${column}) AS agg FROM ${this.table}${where.sql}`, where.bindings));
+        const rows = (await this.runSelect(`SELECT ${fn}(${column}) AS agg FROM ${this.table}${this.joinSql()}${where.sql}`, where.bindings));
         return Number(rows[0]?.agg ?? 0);
     }
     sum(column) {
@@ -295,6 +361,77 @@ export class QueryBuilder {
         const where = this.whereClause();
         return this.runWrite(`DELETE FROM ${this.table}${where.sql}`, where.bindings);
     }
+    /** Atomically add to a numeric column (optionally setting other columns too). */
+    increment(column, amount = 1, extra = {}) {
+        const where = this.whereClause();
+        const sets = [`${column} = ${column} + ?`, ...Object.keys(extra).map((k) => `${k} = ?`)];
+        const bindings = [amount, ...Object.values(extra), ...where.bindings];
+        return this.runWrite(`UPDATE ${this.table} SET ${sets.join(", ")}${where.sql}`, bindings);
+    }
+    /** Atomically subtract from a numeric column. */
+    decrement(column, amount = 1, extra = {}) {
+        const where = this.whereClause();
+        const sets = [`${column} = ${column} - ?`, ...Object.keys(extra).map((k) => `${k} = ?`)];
+        const bindings = [amount, ...Object.values(extra), ...where.bindings];
+        return this.runWrite(`UPDATE ${this.table} SET ${sets.join(", ")}${where.sql}`, bindings);
+    }
+    /** Insert one or more rows, ignoring any that violate a unique constraint. */
+    async insertOrIgnore(rows) {
+        const list = Array.isArray(rows) ? rows : [rows];
+        if (!list.length)
+            return { rowsAffected: 0 };
+        const dialect = this.getSource().dialect;
+        const keys = Object.keys(list[0]);
+        const values = list.map(() => `(${keys.map(() => "?").join(", ")})`).join(", ");
+        const bindings = list.flatMap((r) => keys.map((k) => r[k]));
+        const verb = dialect === "mysql" ? "INSERT IGNORE" : "INSERT";
+        const suffix = dialect === "postgres" || dialect === "sqlite" ? " ON CONFLICT DO NOTHING" : "";
+        return this.runWrite(`${verb} INTO ${this.table} (${keys.join(", ")}) VALUES ${values}${suffix}`, bindings);
+    }
+    /**
+     * Insert rows, updating `update` columns on a conflict against `uniqueBy`.
+     * Dialect-aware: `ON CONFLICT … DO UPDATE` (sqlite/postgres) or
+     * `ON DUPLICATE KEY UPDATE` (mysql).
+     */
+    async upsert(rows, uniqueBy, update) {
+        const list = Array.isArray(rows) ? rows : [rows];
+        if (!list.length)
+            return { rowsAffected: 0 };
+        const dialect = this.getSource().dialect;
+        const keys = Object.keys(list[0]);
+        const cols = update ?? keys.filter((k) => !uniqueBy.includes(k));
+        const values = list.map(() => `(${keys.map(() => "?").join(", ")})`).join(", ");
+        const bindings = list.flatMap((r) => keys.map((k) => r[k]));
+        let sql = `INSERT INTO ${this.table} (${keys.join(", ")}) VALUES ${values}`;
+        if (dialect === "mysql") {
+            sql += ` ON DUPLICATE KEY UPDATE ${cols.map((c) => `${c} = VALUES(${c})`).join(", ")}`;
+        }
+        else {
+            sql += ` ON CONFLICT (${uniqueBy.join(", ")}) DO UPDATE SET ${cols
+                .map((c) => `${c} = excluded.${c}`)
+                .join(", ")}`;
+        }
+        return this.runWrite(sql, bindings);
+    }
+    /**
+     * Process results in pages of `size`, so a large table never loads at once.
+     * The callback runs per page; return `false` from it to stop early.
+     */
+    async chunk(size, callback) {
+        let offset = 0;
+        for (;;) {
+            this._limit = size;
+            this._offset = offset;
+            const rows = await this.get();
+            if (!rows.length)
+                return;
+            if ((await callback(rows)) === false)
+                return;
+            if (rows.length < size)
+                return;
+            offset += size;
+        }
+    }
 }
 /** Start a query against a table, on the default connection or a named one. */
 export function db(table, connectionName) {

package/dist/core/index.d.ts

@@ -40,8 +40,11 @@ export type { CsrfOptions } from "./csrf.js";
 export { db, connection, getConnection, setConnection, addConnection, setDefaultConnection, connectionNames, clearConnections, transaction, inTransaction, QueryBuilder, } from "./database.js";
 export type { Connection, TransactionConnection, TransactionHandle, ConnectionHandle, WriteResult, Row, Dialect, Operator, Paginated, } from "./database.js";
 export { Model } from "./model.js";
+export type { GlobalScope } from "./model.js";
+export { ModelQuery } from "./model-query.js";
+export type { ModelEvent, ModelHook, ModelObserver } from "./model-events.js";
 export type { CastType, Casts } from "./casts.js";
-export { Relation, HasOne, HasMany, BelongsTo, BelongsToMany } from "./relations.js";
+export { Relation, HasOne, HasMany, BelongsTo, BelongsToMany, MorphOne, MorphMany, MorphTo, registerMorphType, } from "./relations.js";
 export { Faker, Factory as ModelFactory, factory, Seeder, seed } from "./factory.js";
 export type { Definition } from "./factory.js";
 export { Mailer, FakeMailer, PendingMail, BaseMail, SendMailJob, ArrayTransport, LogTransport, fetchTransport, mail, mailer, send, sendLater, setMailer, getMailer, fakeMail, restoreMail, } from "./mail.js";
@@ -55,7 +58,7 @@ export { Redis, MemoryRedis, redis, setRedis, redisStore } from "./redis.js";
 export type { RedisConnection, SetOptions } from "./redis.js";
 export { Notification, Notifier, MailChannel, DatabaseChannel, ArrayChannel, routeFor, notify, setNotifier, getNotifier, } from "./notification.js";
 export type { Notifiable, MailContent, Channel } from "./notification.js";
-export { SchemaBuilder, Migrator, TableBuilder, Column } from "./migrations.js";
+export { SchemaBuilder, Migrator, TableBuilder, AlterTableBuilder, ForeignKeyBuilder, Column, } from "./migrations.js";
 export type { Migration } from "./migrations.js";
 export { ctx, json, text, html, redirect, param, query, header, body, request, response, } from "./request.js";
 export { decorateRequest, hasRequestDecorator, decorated, setRequestValue, clearRequestDecorators, } from "./decorators.js";

package/dist/core/index.js

@@ -22,7 +22,8 @@ export { securityHeaders } from "./shield.js";
 export { csrf, csrfToken, csrfField } from "./csrf.js";
 export { db, connection, getConnection, setConnection, addConnection, setDefaultConnection, connectionNames, clearConnections, transaction, inTransaction, QueryBuilder, } from "./database.js";
 export { Model } from "./model.js";
-export { Relation, HasOne, HasMany, BelongsTo, BelongsToMany } from "./relations.js";
+export { ModelQuery } from "./model-query.js";
+export { Relation, HasOne, HasMany, BelongsTo, BelongsToMany, MorphOne, MorphMany, MorphTo, registerMorphType, } from "./relations.js";
 export { Faker, Factory as ModelFactory, factory, Seeder, seed } from "./factory.js";
 export { Mailer, FakeMailer, PendingMail, BaseMail, SendMailJob, ArrayTransport, LogTransport, fetchTransport, mail, mailer, send, sendLater, setMailer, getMailer, fakeMail, restoreMail, } from "./mail.js";
 export { Job, Queue, FakeQueue, SyncDriver, MemoryDriver, dispatch, work, setQueue, getQueue, fakeQueue, restoreQueue, exponentialBackoff, linearBackoff, fixedBackoff, noBackoff, } from "./queue.js";
@@ -30,7 +31,7 @@ export { Scheduler, ScheduledTask, scheduler, setScheduler, schedule, cronMatche
 export { MemoryBroadcaster, broadcast, setBroadcaster, getBroadcaster, channelAuth, authorizeChannel, clearChannels, } from "./broadcasting.js";
 export { Redis, MemoryRedis, redis, setRedis, redisStore } from "./redis.js";
 export { Notification, Notifier, MailChannel, DatabaseChannel, ArrayChannel, routeFor, notify, setNotifier, getNotifier, } from "./notification.js";
-export { SchemaBuilder, Migrator, TableBuilder, Column } from "./migrations.js";
+export { SchemaBuilder, Migrator, TableBuilder, AlterTableBuilder, ForeignKeyBuilder, Column, } from "./migrations.js";
 export { ctx, json, text, html, redirect, param, query, header, body, request, response, } from "./request.js";
 export { decorateRequest, hasRequestDecorator, decorated, setRequestValue, clearRequestDecorators, } from "./decorators.js";
 export { View } from "./view.js";

package/dist/core/migrations.d.ts

@@ -31,9 +31,29 @@ export declare class Column {
     default(value: unknown): this;
     toSql(dialect: Dialect): string;
 }
-export declare class TableBuilder {
+/** A foreign-key constraint, built fluently: `foreign("user_id").references("id").on("users")`. */
+export declare class ForeignKeyBuilder {
+    private column;
+    private _refTable;
+    private _refColumn;
+    private _onDelete?;
+    private _onUpdate?;
+    constructor(column: string);
+    references(column: string): this;
+    on(table: string): this;
+    onDelete(action: string): this;
+    onUpdate(action: string): this;
+    toSql(): string;
+}
+interface IndexDef {
+    columns: string[];
+    unique: boolean;
+    name?: string;
+}
+/** Column-declaring methods shared by `createTable` and `alterTable` builders. */
+declare abstract class ColumnBag {
     readonly columns: Column[];
-    private add;
+    protected add(name: string, type: ColumnType, length?: number): Column;
     id(name?: string): Column;
     string(name: string, length?: number): Column;
     text(name: string): Column;
@@ -44,13 +64,43 @@ export declare class TableBuilder {
     json(name: string): Column;
     /** Adds nullable created_at + updated_at columns. */
     timestamps(): void;
+}
+export declare class TableBuilder extends ColumnBag {
+    readonly indexes: IndexDef[];
+    readonly foreignKeys: ForeignKeyBuilder[];
+    /** A (possibly composite) index. */
+    index(columns: string | string[], name?: string): this;
+    /** A (possibly composite) unique index. */
+    uniqueIndex(columns: string | string[], name?: string): this;
+    /** A foreign key: `foreign("user_id").references("id").on("users")`. */
+    foreign(column: string): ForeignKeyBuilder;
+    /** The `CREATE TABLE` plus any `CREATE INDEX` statements, in order. */
+    toStatements(table: string, dialect: Dialect): string[];
+    /** @deprecated Use `toStatements`. Kept for callers that build the SQL directly. */
     toCreateSql(table: string, dialect: Dialect): string;
 }
+/** Alterations to an existing table: add/drop/rename columns, add/drop indexes. */
+export declare class AlterTableBuilder extends ColumnBag {
+    private readonly drops;
+    private readonly renames;
+    private readonly addIndexes;
+    private readonly dropIndexes;
+    /** Drop a column. */
+    dropColumn(name: string): this;
+    /** Rename a column. */
+    renameColumn(from: string, to: string): this;
+    index(columns: string | string[], name?: string): this;
+    uniqueIndex(columns: string | string[], name?: string): this;
+    dropIndex(name: string): this;
+    toStatements(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>;
+    /** Alter an existing table — add/drop/rename columns, add/drop indexes. */
+    alterTable(name: string, build: (table: AlterTableBuilder) => void): Promise<void>;
     dropTable(name: string): Promise<void>;
     raw(sql: string, bindings?: unknown[]): Promise<void>;
 }

package/dist/core/migrations.js

@@ -87,7 +87,49 @@ export class Column {
         return sql;
     }
 }
-export class TableBuilder {
+/** A foreign-key constraint, built fluently: `foreign("user_id").references("id").on("users")`. */
+export class ForeignKeyBuilder {
+    column;
+    _refTable = "";
+    _refColumn = "id";
+    _onDelete;
+    _onUpdate;
+    constructor(column) {
+        this.column = column;
+    }
+    references(column) {
+        this._refColumn = column;
+        return this;
+    }
+    on(table) {
+        this._refTable = table;
+        return this;
+    }
+    onDelete(action) {
+        this._onDelete = action;
+        return this;
+    }
+    onUpdate(action) {
+        this._onUpdate = action;
+        return this;
+    }
+    toSql() {
+        let sql = `FOREIGN KEY (${this.column}) REFERENCES ${this._refTable}(${this._refColumn})`;
+        if (this._onDelete)
+            sql += ` ON DELETE ${this._onDelete}`;
+        if (this._onUpdate)
+            sql += ` ON UPDATE ${this._onUpdate}`;
+        return sql;
+    }
+}
+function toArray(value) {
+    return Array.isArray(value) ? value : [value];
+}
+function indexName(table, columns, unique) {
+    return `${table}_${columns.join("_")}_${unique ? "unique" : "index"}`;
+}
+/** Column-declaring methods shared by `createTable` and `alterTable` builders. */
+class ColumnBag {
     columns = [];
     add(name, type, length) {
         const col = new Column(name, type, length);
@@ -123,8 +165,89 @@ export class TableBuilder {
         this.timestamp("created_at").nullable();
         this.timestamp("updated_at").nullable();
     }
+}
+export class TableBuilder extends ColumnBag {
+    indexes = [];
+    foreignKeys = [];
+    /** A (possibly composite) index. */
+    index(columns, name) {
+        this.indexes.push({ columns: toArray(columns), unique: false, ...(name ? { name } : {}) });
+        return this;
+    }
+    /** A (possibly composite) unique index. */
+    uniqueIndex(columns, name) {
+        this.indexes.push({ columns: toArray(columns), unique: true, ...(name ? { name } : {}) });
+        return this;
+    }
+    /** A foreign key: `foreign("user_id").references("id").on("users")`. */
+    foreign(column) {
+        const fk = new ForeignKeyBuilder(column);
+        this.foreignKeys.push(fk);
+        return fk;
+    }
+    /** The `CREATE TABLE` plus any `CREATE INDEX` statements, in order. */
+    toStatements(table, dialect) {
+        const parts = [
+            ...this.columns.map((c) => c.toSql(dialect)),
+            ...this.foreignKeys.map((fk) => fk.toSql()),
+        ];
+        const create = `CREATE TABLE ${table} (${parts.join(", ")})`;
+        return [create, ...this.indexes.map((i) => createIndexSql(table, i))];
+    }
+    /** @deprecated Use `toStatements`. Kept for callers that build the SQL directly. */
     toCreateSql(table, dialect) {
-        return `CREATE TABLE ${table} (${this.columns.map((c) => c.toSql(dialect)).join(", ")})`;
+        return this.toStatements(table, dialect)[0];
+    }
+}
+function createIndexSql(table, index) {
+    const name = index.name ?? indexName(table, index.columns, index.unique);
+    return `CREATE ${index.unique ? "UNIQUE " : ""}INDEX ${name} ON ${table} (${index.columns.join(", ")})`;
+}
+/** Alterations to an existing table: add/drop/rename columns, add/drop indexes. */
+export class AlterTableBuilder extends ColumnBag {
+    drops = [];
+    renames = [];
+    addIndexes = [];
+    dropIndexes = [];
+    /** Drop a column. */
+    dropColumn(name) {
+        this.drops.push(name);
+        return this;
+    }
+    /** Rename a column. */
+    renameColumn(from, to) {
+        this.renames.push({ from, to });
+        return this;
+    }
+    index(columns, name) {
+        this.addIndexes.push({ columns: toArray(columns), unique: false, ...(name ? { name } : {}) });
+        return this;
+    }
+    uniqueIndex(columns, name) {
+        this.addIndexes.push({ columns: toArray(columns), unique: true, ...(name ? { name } : {}) });
+        return this;
+    }
+    dropIndex(name) {
+        this.dropIndexes.push(name);
+        return this;
+    }
+    toStatements(table, dialect) {
+        const stmts = [];
+        // Drop indexes first, so a column an index references can then be dropped.
+        for (const name of this.dropIndexes) {
+            // MySQL drops indexes through ALTER TABLE; sqlite/postgres use DROP INDEX.
+            stmts.push(dialect === "mysql" ? `ALTER TABLE ${table} DROP INDEX ${name}` : `DROP INDEX ${name}`);
+        }
+        for (const col of this.columns)
+            stmts.push(`ALTER TABLE ${table} ADD COLUMN ${col.toSql(dialect)}`);
+        for (const { from, to } of this.renames) {
+            stmts.push(`ALTER TABLE ${table} RENAME COLUMN ${from} TO ${to}`);
+        }
+        for (const name of this.drops)
+            stmts.push(`ALTER TABLE ${table} DROP COLUMN ${name}`);
+        for (const index of this.addIndexes)
+            stmts.push(createIndexSql(table, index));
+        return stmts;
     }
 }
 export class SchemaBuilder {
@@ -137,7 +260,15 @@ export class SchemaBuilder {
     async createTable(name, build) {
         const table = new TableBuilder();
         build(table);
-        await this.conn.write(table.toCreateSql(name, this.dialect), []);
+        for (const sql of table.toStatements(name, this.dialect))
+            await this.conn.write(sql, []);
+    }
+    /** Alter an existing table — add/drop/rename columns, add/drop indexes. */
+    async alterTable(name, build) {
+        const table = new AlterTableBuilder();
+        build(table);
+        for (const sql of table.toStatements(name, this.dialect))
+            await this.conn.write(sql, []);
     }
     async dropTable(name) {
         await this.conn.write(`DROP TABLE IF EXISTS ${name}`, []);

package/dist/core/model-events.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Model lifecycle events. A model fires these as it is retrieved, saved, and
+ * deleted, so an app can hook behaviour onto a model without editing every call
+ * site — slug a title on `creating`, bust a cache on `saved`, cascade on
+ * `deleting`. The `*ing` events are cancelable: a hook returning `false` aborts
+ * the operation (the write never runs).
+ *
+ *   User.creating((user) => { user.uuid = crypto.randomUUID(); });
+ *   User.deleting((user) => user.isAdmin ? false : undefined); // veto
+ *   User.observe(new UserObserver());
+ *
+ * Hooks are keyed by the exact model class (subclasses don't inherit a parent's
+ * hooks), stored off the class in a WeakMap so they never leak into instances or
+ * `save()`'s column spread.
+ */
+import type { Model } from "./model.js";
+export type ModelEvent = "retrieved" | "creating" | "created" | "updating" | "updated" | "saving" | "saved" | "deleting" | "deleted" | "restoring" | "restored";
+/** A lifecycle hook. Returning `false` from a cancelable event aborts the op. */
+export type ModelHook<T extends Model = Model> = (model: T) => void | boolean | Promise<void | boolean>;
+/** An observer: an object whose methods are named after the events they handle. */
+export type ModelObserver<T extends Model = Model> = Partial<Record<ModelEvent, ModelHook<T>>>;
+/** The full event list, for wiring up an observer. */
+export declare const MODEL_EVENTS: ModelEvent[];
+/** Register a hook for `event` on a model class. */
+export declare function addModelHook(cls: object, event: ModelEvent, hook: ModelHook): void;
+/** Attach every matching method of an observer object as a hook. */
+export declare function addModelObserver(cls: object, observer: ModelObserver): void;
+/** Drop a class's hooks (or all of them) — a test helper for a clean slate. */
+export declare function clearModelHooks(cls?: object): void;
+/**
+ * Fire an event's hooks in registration order. Returns `false` only when a
+ * cancelable event had a hook return `false` — the caller then skips the write.
+ */
+export declare function fireModelEvent(cls: object, event: ModelEvent, model: Model): Promise<boolean>;

package/dist/core/model-events.js

@@ -0,0 +1,71 @@
+/**
+ * Model lifecycle events. A model fires these as it is retrieved, saved, and
+ * deleted, so an app can hook behaviour onto a model without editing every call
+ * site — slug a title on `creating`, bust a cache on `saved`, cascade on
+ * `deleting`. The `*ing` events are cancelable: a hook returning `false` aborts
+ * the operation (the write never runs).
+ *
+ *   User.creating((user) => { user.uuid = crypto.randomUUID(); });
+ *   User.deleting((user) => user.isAdmin ? false : undefined); // veto
+ *   User.observe(new UserObserver());
+ *
+ * Hooks are keyed by the exact model class (subclasses don't inherit a parent's
+ * hooks), stored off the class in a WeakMap so they never leak into instances or
+ * `save()`'s column spread.
+ */
+/** Events whose hooks can veto the operation by returning `false`. */
+const CANCELABLE = new Set(["creating", "updating", "saving", "deleting", "restoring"]);
+/** The full event list, for wiring up an observer. */
+export const MODEL_EVENTS = [
+    "retrieved",
+    "creating",
+    "created",
+    "updating",
+    "updated",
+    "saving",
+    "saved",
+    "deleting",
+    "deleted",
+    "restoring",
+    "restored",
+];
+// Class object → event → hooks. A WeakMap so unloaded classes are collectable.
+const registry = new WeakMap();
+/** Register a hook for `event` on a model class. */
+export function addModelHook(cls, event, hook) {
+    let byEvent = registry.get(cls);
+    if (!byEvent)
+        registry.set(cls, (byEvent = new Map()));
+    const hooks = byEvent.get(event) ?? [];
+    hooks.push(hook);
+    byEvent.set(event, hooks);
+}
+/** Attach every matching method of an observer object as a hook. */
+export function addModelObserver(cls, observer) {
+    for (const event of MODEL_EVENTS) {
+        const hook = observer[event];
+        if (typeof hook === "function")
+            addModelHook(cls, event, hook);
+    }
+}
+/** Drop a class's hooks (or all of them) — a test helper for a clean slate. */
+export function clearModelHooks(cls) {
+    if (cls)
+        registry.delete(cls);
+}
+/**
+ * Fire an event's hooks in registration order. Returns `false` only when a
+ * cancelable event had a hook return `false` — the caller then skips the write.
+ */
+export async function fireModelEvent(cls, event, model) {
+    const hooks = registry.get(cls)?.get(event);
+    if (!hooks?.length)
+        return true;
+    const cancelable = CANCELABLE.has(event);
+    for (const hook of hooks) {
+        const result = await hook(model);
+        if (cancelable && result === false)
+            return false;
+    }
+    return true;
+}

package/dist/core/model-query.d.ts

@@ -0,0 +1,68 @@
+/**
+ * A model-aware query builder — what `Model.query()` sugar and eager loading are
+ * built on. It wraps the plain `QueryBuilder`, hydrates rows into models (firing
+ * `retrieved`), and adds the relationship-aware operations Eloquent has and a raw
+ * builder can't: `with()` (nested eager loading), `withCount()`, and existence
+ * filters `has()` / `whereHas()` / `doesntHave()`.
+ *
+ *   const users = await User.query()
+ *     .where("active", true)
+ *     .with("posts.comments")
+ *     .withCount("posts")
+ *     .whereHas("posts", (q) => q.where("published", true))
+ *     .get();
+ *
+ * Existence filters use the same two-query strategy as the relations themselves
+ * (a `whereIn` over keys gathered from the related table), so everything stays on
+ * the driver-agnostic builder — no JOIN or correlated subquery required. They're
+ * recorded and resolved at `get()`/`first()`/`count()` time so the chain stays
+ * synchronous.
+ */
+import type { QueryBuilder, Row, Paginated } from "./database.js";
+import type { Model } from "./model.js";
+type ModelClass<T extends Model> = new (attributes?: Row) => T;
+type Constrain = (q: QueryBuilder) => void;
+export declare class ModelQuery<T extends Model> {
+    private cls;
+    private builder;
+    private eagers;
+    private counts;
+    private hasConstraints;
+    constructor(cls: ModelClass<T>, builder: QueryBuilder);
+    /** The wrapped builder, for anything `ModelQuery` doesn't proxy. */
+    toBase(): QueryBuilder;
+    where(column: string, opOrValue: unknown, value?: unknown): this;
+    orWhere(column: string, opOrValue: unknown, value?: unknown): this;
+    whereIn(column: string, values: unknown[]): this;
+    whereNotIn(column: string, values: unknown[]): this;
+    whereNull(column: string): this;
+    whereNotNull(column: string): this;
+    whereBetween(column: string, range: [unknown, unknown]): this;
+    whereLike(column: string, pattern: string): this;
+    orderBy(column: string, direction?: "asc" | "desc"): this;
+    latest(column?: string): this;
+    oldest(column?: string): this;
+    limit(n: number): this;
+    offset(n: number): this;
+    /** Eager-load relations (dotted paths for nesting: `"posts.comments"`). */
+    with(...names: string[]): this;
+    /** Add a `<relation>_count` to each result. */
+    withCount(...names: string[]): this;
+    /** Constrain to models that have at least one related row. */
+    has(name: string): this;
+    /** Constrain to models whose related rows match `constrain`. */
+    whereHas(name: string, constrain?: Constrain): this;
+    /** Constrain to models with no matching related row. */
+    doesntHave(name: string, constrain?: Constrain): this;
+    get(): Promise<T[]>;
+    first(): Promise<T | null>;
+    count(): Promise<number>;
+    exists(): Promise<boolean>;
+    paginate(page?: number, perPage?: number): Promise<Paginated<T>>;
+    private hydrate;
+    private relationFor;
+    /** Turn recorded has/doesntHave constraints into `whereIn`/`whereNotIn` on the builder. */
+    private resolveHasConstraints;
+    private loadCounts;
+}
+export {};