@shaferllc/keel 0.80.0 → 0.81.1

package/dist/core/model.js

@@ -17,8 +17,41 @@
  */
 import { db } from "./database.js";
 import { NotFoundException } from "./exceptions.js";
-import { BelongsTo, BelongsToMany, HasMany, HasOne } from "./relations.js";
+import { BelongsTo, BelongsToMany, HasMany, HasOne, MorphMany, MorphOne, MorphTo } from "./relations.js";
 import { applyCasts, castGet, castSet } from "./casts.js";
+import { addModelHook, addModelObserver, fireModelEvent, } from "./model-events.js";
+import { ModelQuery } from "./model-query.js";
+/** Registered global scopes, keyed by the model class they were declared on. */
+const globalScopes = new WeakMap();
+/**
+ * Every scope that applies to `cls`, including ones declared on its ancestors.
+ *
+ * Inheritance is the whole point: a base class exists so its subclasses are
+ * constrained by it.
+ *
+ *   class TenantModel extends Model {}
+ *   TenantModel.addGlobalScope("tenant", (q) => q.where("teamId", currentTeam()));
+ *   class Post extends TenantModel {}     // Post must be scoped too
+ *
+ * Looking only at the concrete class would leave `Post.query()` completely
+ * unconstrained — and a scope that silently does nothing fails *open*, which for
+ * a tenancy scope means returning every customer's rows.
+ *
+ * Walked root-first so a subclass can override an ancestor's scope by reusing its
+ * name — the nearest declaration of a given name wins.
+ */
+function scopesFor(cls) {
+    const chain = [];
+    for (let c = cls; c && c !== Function.prototype; c = Object.getPrototypeOf(c)) {
+        chain.unshift(c);
+    }
+    const merged = new Map();
+    for (const link of chain) {
+        for (const [name, scope] of globalScopes.get(link) ?? [])
+            merged.set(name, scope);
+    }
+    return merged;
+}
 /**
  * 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.
@@ -46,14 +79,137 @@ export class Model {
     static timestamps = false;
     static createdAtColumn = "created_at";
     static updatedAtColumn = "updated_at";
+    /** Columns stripped from `toJSON()` output (e.g. `["password"]`). */
+    static hidden = [];
+    /** If set, ONLY these keys survive `toJSON()` — an allowlist that wins over `hidden`. */
+    static visible = [];
+    /** Computed accessor names (getters or zero-arg methods) added to `toJSON()`. */
+    static appends = [];
+    /** Soft deletes: `delete()` sets `deleted_at` instead of removing the row. */
+    static softDeletes = false;
+    static deletedAtColumn = "deleted_at";
     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. */
+    /* ---------------------------- scopes & events ------------------------- */
+    /** Register a global scope — a constraint applied to every query this model builds. */
+    static addGlobalScope(name, scope) {
+        let map = globalScopes.get(this);
+        if (!map)
+            globalScopes.set(this, (map = new Map()));
+        map.set(name, scope);
+    }
+    /** Build this model's base query, applying global scopes and the soft-delete filter. */
+    static baseQuery(trashed = "exclude", skip) {
+        const query = db(this.table, this.connection);
+        for (const [name, scope] of scopesFor(this)) {
+            if (skip?.has(name))
+                continue;
+            scope(query, this);
+        }
+        if (this.softDeletes) {
+            if (trashed === "exclude")
+                query.whereNull(this.deletedAtColumn);
+            else if (trashed === "only")
+                query.whereNotNull(this.deletedAtColumn);
+        }
+        return query;
+    }
+    /** A query builder scoped to this model's table (global scopes applied). */
     static query() {
-        return db(this.table, this.connection);
+        return this.baseQuery();
+    }
+    /**
+     * Drop named global scopes from this query.
+     *
+     * Deliberately explicit and greppable: a query that escapes a tenancy scope is
+     * exactly the thing you want to be able to find at audit time, so it has to be
+     * *typed out*, not arrived at by forgetting something.
+     */
+    static withoutGlobalScope(...names) {
+        return this.baseQuery("exclude", new Set(names));
+    }
+    /** Drop every global scope. Same warning, louder. */
+    static withoutGlobalScopes() {
+        return this.baseQuery("exclude", new Set(scopesFor(this).keys()));
+    }
+    /** Include soft-deleted rows (bypasses the soft-delete scope). */
+    static withTrashed() {
+        return this.baseQuery("with");
+    }
+    /** Only soft-deleted rows. */
+    static onlyTrashed() {
+        return this.baseQuery("only");
+    }
+    /* --------------------- model-aware query (eager, has) ----------------- */
+    /** A model-aware query — hydrates to models and supports `with`/`withCount`/`whereHas`. */
+    static newQuery() {
+        return new ModelQuery(this, this.baseQuery());
+    }
+    /** Start a query eager-loading the given relations (dotted paths nest). */
+    static with(...names) {
+        return this.newQuery().with(...names);
+    }
+    /** Start a query counting the given relations into `<relation>_count`. */
+    static withCount(...names) {
+        return this.newQuery().withCount(...names);
+    }
+    /** Start a query constrained to models that have at least one related row. */
+    static has(name) {
+        return this.newQuery().has(name);
+    }
+    /** Start a query constrained to models whose related rows match `constrain`. */
+    static whereHas(name, constrain) {
+        return this.newQuery().whereHas(name, constrain);
+    }
+    /** Start a query constrained to models with no matching related row. */
+    static doesntHave(name, constrain) {
+        return this.newQuery().doesntHave(name, constrain);
+    }
+    /** Construct a model from a row and fire its `retrieved` event. */
+    static async hydrate(row) {
+        const model = new this(row);
+        await fireModelEvent(this, "retrieved", model);
+        return model;
+    }
+    static creating(hook) {
+        addModelHook(this, "creating", hook);
+    }
+    static created(hook) {
+        addModelHook(this, "created", hook);
+    }
+    static updating(hook) {
+        addModelHook(this, "updating", hook);
+    }
+    static updated(hook) {
+        addModelHook(this, "updated", hook);
+    }
+    static saving(hook) {
+        addModelHook(this, "saving", hook);
+    }
+    static saved(hook) {
+        addModelHook(this, "saved", hook);
+    }
+    static deleting(hook) {
+        addModelHook(this, "deleting", hook);
+    }
+    static deleted(hook) {
+        addModelHook(this, "deleted", hook);
+    }
+    static restoring(hook) {
+        addModelHook(this, "restoring", hook);
+    }
+    static restored(hook) {
+        addModelHook(this, "restored", hook);
+    }
+    static retrieved(hook) {
+        addModelHook(this, "retrieved", hook);
+    }
+    /** Register an observer whose methods are named after the events they handle. */
+    static observe(observer) {
+        addModelObserver(this, observer);
     }
     /** Keep only the attributes mass-assignment allows (fillable / guarded). */
     static filterFillable(attributes) {
@@ -88,12 +244,12 @@ export class Model {
         return out;
     }
     static async all() {
-        const rows = await db(this.table, this.connection).get();
-        return rows.map((row) => new this(row));
+        const rows = await this.baseQuery().get();
+        return Promise.all(rows.map((row) => this.hydrate(row)));
     }
     static async find(id) {
-        const row = await db(this.table, this.connection).where(this.primaryKey, id).first();
-        return row ? new this(row) : null;
+        const row = await this.baseQuery().where(this.primaryKey, id).first();
+        return row ? this.hydrate(row) : null;
     }
     static async findOrFail(id) {
         const model = await this.find(id);
@@ -102,54 +258,49 @@ export class Model {
         return model;
     }
     static async first() {
-        const row = await db(this.table, this.connection).first();
-        return row ? new this(row) : null;
+        const row = await this.baseQuery().first();
+        return row ? this.hydrate(row) : null;
     }
     /** Fetch models matching a simple equality condition. */
     static async where(column, value) {
-        const rows = await db(this.table, this.connection).where(column, value).get();
-        return rows.map((row) => new this(row));
+        const rows = await this.baseQuery().where(column, value).get();
+        return Promise.all(rows.map((row) => this.hydrate(row)));
     }
     static async create(attributes) {
-        const filtered = this.filterFillable(attributes);
-        const write = this.stampTimestamps(this.toDatabase(filtered), true);
-        const id = await db(this.table, this.connection).insertGetId(write);
-        const model = new this(filtered);
-        if (this.timestamps) {
-            model[this.createdAtColumn] = write[this.createdAtColumn];
-            model[this.updatedAtColumn] = write[this.updatedAtColumn];
-        }
-        if (id != null)
-            model[this.primaryKey] = id;
+        // Route through save() so mass-assignment, timestamps, and the saving/creating
+        // lifecycle events all apply in one place.
+        const model = new this();
+        model.fill(attributes);
+        await model.save();
         return model;
     }
     /** A page of models plus pagination metadata. */
     static async paginate(page = 1, perPage = 15) {
-        const result = await db(this.table, this.connection).paginate(page, perPage);
-        return { ...result, data: result.data.map((row) => new this(row)) };
+        const result = await this.baseQuery().paginate(page, perPage);
+        return { ...result, data: await Promise.all(result.data.map((row) => this.hydrate(row))) };
     }
     /** Find the first row matching `match`, or create one from `{ ...match, ...values }`. */
     static async firstOrCreate(match, values = {}) {
         const row = await this.matching(match).first();
         if (row)
-            return new this(row);
+            return this.hydrate(row);
         return this.create({ ...match, ...values });
     }
     /** Update the first row matching `match` with `values`, or create it. */
     static async updateOrCreate(match, values = {}) {
         const row = await this.matching(match).first();
         if (row) {
-            const model = new this(row);
+            const model = await this.hydrate(row);
             await model.forceFill(values).save();
             return model;
         }
         return this.create({ ...match, ...values });
     }
-    /** A query scoped to every column/value in `match`. */
+    /** A query scoped to every column/value in `match` (global scopes applied). */
     static matching(match) {
-        let q = db(this.table, this.connection);
+        const q = this.baseQuery();
         for (const [column, value] of Object.entries(match))
-            q = q.where(column, value);
+            q.where(column, value);
         return q;
     }
     /**
@@ -197,6 +348,18 @@ export class Model {
         .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);
     }
+    /** Polymorphic one-to-many: children carry `<name>_id` + `<name>_type`. */
+    morphMany(related, name, localKey = this.ctor().primaryKey) {
+        return new MorphMany(this, related, this.constructor.name, `${name}_id`, `${name}_type`, localKey);
+    }
+    /** Polymorphic one-to-one. */
+    morphOne(related, name, localKey = this.ctor().primaryKey) {
+        return new MorphOne(this, related, this.constructor.name, `${name}_id`, `${name}_type`, localKey);
+    }
+    /** The owning side of a polymorphic relation — resolves via `<name>_type` (see `registerMorphType`). */
+    morphTo(name, idColumn = `${name}_id`, typeColumn = `${name}_type`) {
+        return new MorphTo(this, idColumn, typeColumn);
+    }
     /** Store an eager-loaded relation result under `name`. */
     setRelation(name, value) {
         const bag = relationStore.get(this) ?? {};
@@ -208,12 +371,18 @@ export class Model {
     getRelation(name) {
         return relationStore.get(this)?.[name];
     }
-    /** Insert (no primary key) or update (has one). */
+    /** Insert (no primary key) or update (has one). Fires save/create/update events. */
     async save() {
         const ctor = this.ctor();
+        const cls = this.constructor;
         const { table, primaryKey, connection } = ctor;
         const idValue = this[primaryKey];
         const forInsert = idValue == null;
+        // `*ing` hooks run before the write and may mutate the model or veto it.
+        if (!(await fireModelEvent(cls, "saving", this)))
+            return this;
+        if (!(await fireModelEvent(cls, forInsert ? "creating" : "updating", this)))
+            return this;
         const data = ctor.stampTimestamps(ctor.toDatabase({ ...this }), forInsert);
         // Reflect the stamps back onto the instance.
         if (ctor.timestamps) {
@@ -230,6 +399,8 @@ export class Model {
             if (id != null)
                 this[primaryKey] = id;
         }
+        await fireModelEvent(cls, forInsert ? "created" : "updated", this);
+        await fireModelEvent(cls, "saved", this);
         return this;
     }
     /** Mass-assign then save — `fill` + `save` in one call. */
@@ -244,9 +415,51 @@ export class Model {
             Object.assign(this, applyCasts(row, ctor.casts, castGet));
         return this;
     }
+    /** Delete the row — or, with soft deletes on, set `deleted_at`. Fires delete events. */
     async delete() {
-        const { table, primaryKey, connection } = this.ctor();
-        await db(table, connection).where(primaryKey, this[primaryKey]).delete();
+        const ctor = this.ctor();
+        const cls = this.constructor;
+        const { table, primaryKey, connection } = ctor;
+        if (!(await fireModelEvent(cls, "deleting", this)))
+            return;
+        if (ctor.softDeletes) {
+            const now = new Date().toISOString();
+            await db(table, connection)
+                .where(primaryKey, this[primaryKey])
+                .update({ [ctor.deletedAtColumn]: now });
+            this[ctor.deletedAtColumn] = now;
+        }
+        else {
+            await db(table, connection).where(primaryKey, this[primaryKey]).delete();
+        }
+        await fireModelEvent(cls, "deleted", this);
+    }
+    /** Permanently delete a soft-deletable row (bypasses soft deletes). */
+    async forceDelete() {
+        const ctor = this.ctor();
+        const cls = this.constructor;
+        if (!(await fireModelEvent(cls, "deleting", this)))
+            return;
+        await db(ctor.table, ctor.connection).where(ctor.primaryKey, this[ctor.primaryKey]).delete();
+        await fireModelEvent(cls, "deleted", this);
+    }
+    /** Restore a soft-deleted row (clears `deleted_at`). Fires restore events. */
+    async restore() {
+        const ctor = this.ctor();
+        const cls = this.constructor;
+        if (!(await fireModelEvent(cls, "restoring", this)))
+            return this;
+        await db(ctor.table, ctor.connection)
+            .where(ctor.primaryKey, this[ctor.primaryKey])
+            .update({ [ctor.deletedAtColumn]: null });
+        this[ctor.deletedAtColumn] = null;
+        await fireModelEvent(cls, "restored", this);
+        return this;
+    }
+    /** Whether this soft-deletable model is currently trashed. */
+    trashed() {
+        const ctor = this.ctor();
+        return ctor.softDeletes && this[ctor.deletedAtColumn] != null;
     }
     /** Merge mass-assignable attributes into the model (cast, not saved). */
     fill(attributes) {
@@ -261,7 +474,25 @@ export class Model {
         return this;
     }
     toJSON() {
-        const data = applyCasts({ ...this }, this.ctor().casts, castGet);
+        const ctor = this.ctor();
+        let data = applyCasts({ ...this }, ctor.casts, castGet);
+        // Appended computed attributes: a getter (value) or a zero-arg method.
+        for (const name of ctor.appends) {
+            const value = this[name];
+            data[name] = typeof value === "function" ? value.call(this) : value;
+        }
+        // `visible` is an allowlist and wins; otherwise `hidden` is a denylist.
+        if (ctor.visible.length) {
+            const kept = {};
+            for (const key of ctor.visible)
+                if (key in data)
+                    kept[key] = data[key];
+            data = kept;
+        }
+        else if (ctor.hidden.length) {
+            for (const key of ctor.hidden)
+                delete data[key];
+        }
         const relations = relationStore.get(this);
         if (relations) {
             for (const [name, value] of Object.entries(relations))

package/dist/core/relations.d.ts

@@ -49,6 +49,9 @@ export declare class HasMany<T extends Model> extends Relation<T, T[]> {
     query(): QueryBuilder;
     get(): Promise<T[]>;
     eager(models: Model[], name: string): Promise<void>;
+    parentColumn(): string;
+    matchingParentKeys(constrain?: (q: QueryBuilder) => void): Promise<unknown[]>;
+    countsByParent(parentKeys: unknown[]): Promise<Map<unknown, number>>;
 }
 export declare class HasOne<T extends Model> extends Relation<T, T | null> {
     private foreignKey;
@@ -58,6 +61,9 @@ export declare class HasOne<T extends Model> extends Relation<T, T | null> {
     query(): QueryBuilder;
     get(): Promise<T | null>;
     eager(models: Model[], name: string): Promise<void>;
+    parentColumn(): string;
+    matchingParentKeys(constrain?: (q: QueryBuilder) => void): Promise<unknown[]>;
+    countsByParent(parentKeys: unknown[]): Promise<Map<unknown, number>>;
 }
 export declare class BelongsTo<T extends Model> extends Relation<T, T | null> {
     private foreignKey;
@@ -67,6 +73,9 @@ export declare class BelongsTo<T extends Model> extends Relation<T, T | null> {
     query(): QueryBuilder;
     get(): Promise<T | null>;
     eager(models: Model[], name: string): Promise<void>;
+    parentColumn(): string;
+    matchingParentKeys(constrain?: (q: QueryBuilder) => void): Promise<unknown[]>;
+    countsByParent(parentKeys: unknown[]): Promise<Map<unknown, number>>;
 }
 export declare class BelongsToMany<T extends Model> extends Relation<T, T[]> {
     private pivotTable;
@@ -86,5 +95,49 @@ export declare class BelongsToMany<T extends Model> extends Relation<T, T[]> {
     detach(id?: unknown): Promise<void>;
     /** Make the pivot contain exactly `ids` (detach the rest, attach the new). */
     sync(ids: unknown[]): Promise<void>;
+    parentColumn(): string;
+    matchingParentKeys(constrain?: (q: QueryBuilder) => void): Promise<unknown[]>;
+    countsByParent(parentKeys: unknown[]): Promise<Map<unknown, number>>;
+}
+/** Register a model under a morph type string (usually its class name). */
+export declare function registerMorphType(type: string, related: ModelClass<Model>): void;
+/** The parent side of a polymorphic one-to-many (`Post.comments()` over `commentable`). */
+export declare class MorphMany<T extends Model> extends Relation<T, T[]> {
+    private morphType;
+    private idColumn;
+    private typeColumn;
+    private localKey;
+    constructor(parent: Model, related: ModelClass<T>, morphType: string, idColumn: string, typeColumn: string, localKey: string);
+    private localValue;
+    query(): QueryBuilder;
+    get(): Promise<T[]>;
+    eager(models: Model[], name: string): Promise<void>;
+    parentColumn(): string;
+    matchingParentKeys(constrain?: (q: QueryBuilder) => void): Promise<unknown[]>;
+    countsByParent(parentKeys: unknown[]): Promise<Map<unknown, number>>;
+    /** Create a related row with the morph keys (`*_id` / `*_type`) filled in. */
+    create(attributes: Row): Promise<T>;
+}
+/** The parent side of a polymorphic one-to-one. */
+export declare class MorphOne<T extends Model> extends Relation<T, T | null> {
+    private morphType;
+    private idColumn;
+    private typeColumn;
+    private localKey;
+    constructor(parent: Model, related: ModelClass<T>, morphType: string, idColumn: string, typeColumn: string, localKey: string);
+    query(): QueryBuilder;
+    get(): Promise<T | null>;
+    eager(models: Model[], name: string): Promise<void>;
+}
+/** The owning side of a polymorphic relation — resolves its parent by stored type + id. */
+export declare class MorphTo implements PromiseLike<Model | null> {
+    private parent;
+    private idColumn;
+    private typeColumn;
+    constructor(parent: Model, idColumn: string, typeColumn: string);
+    private relatedClass;
+    get(): Promise<Model | null>;
+    eager(models: Model[], name: string): Promise<void>;
+    then<R1 = Model | null, R2 = never>(onFulfilled?: ((value: Model | null) => R1 | PromiseLike<R1>) | null, onRejected?: ((reason: unknown) => R2 | PromiseLike<R2>) | null): PromiseLike<R1 | R2>;
 }
 export {};