@shaferllc/keel 0.80.0 → 0.81.0

package/dist/core/model-query.js

@@ -0,0 +1,234 @@
+/**
+ * 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 { fireModelEvent } from "./model-events.js";
+/** Group dotted eager-load paths by their first segment. */
+function groupPaths(paths) {
+    const groups = new Map();
+    for (const path of paths) {
+        const [top, ...rest] = path.split(".");
+        const nested = groups.get(top) ?? [];
+        if (rest.length)
+            nested.push(rest.join("."));
+        groups.set(top, nested);
+    }
+    return groups;
+}
+/** Recursively eager-load dotted relation paths onto a set of models. */
+async function eagerLoad(models, paths) {
+    if (!models.length)
+        return;
+    for (const [top, nested] of groupPaths(paths)) {
+        const relation = models[0][top]?.();
+        if (!relation)
+            throw new Error(`${models[0].constructor.name} has no relation "${top}"`);
+        await relation.eager(models, top);
+        if (nested.length) {
+            const children = [];
+            for (const model of models) {
+                const loaded = model.getRelation(top);
+                if (Array.isArray(loaded))
+                    children.push(...loaded);
+                else if (loaded)
+                    children.push(loaded);
+            }
+            await eagerLoad(children, nested);
+        }
+    }
+}
+export class ModelQuery {
+    cls;
+    builder;
+    eagers = [];
+    counts = [];
+    hasConstraints = [];
+    constructor(cls, builder) {
+        this.cls = cls;
+        this.builder = builder;
+    }
+    /** The wrapped builder, for anything `ModelQuery` doesn't proxy. */
+    toBase() {
+        return this.builder;
+    }
+    /* --------------------------- builder passthrough --------------------------- */
+    where(column, opOrValue, value) {
+        if (value === undefined)
+            this.builder.where(column, opOrValue);
+        else
+            this.builder.where(column, opOrValue, value);
+        return this;
+    }
+    orWhere(column, opOrValue, value) {
+        if (value === undefined)
+            this.builder.orWhere(column, opOrValue);
+        else
+            this.builder.orWhere(column, opOrValue, value);
+        return this;
+    }
+    whereIn(column, values) {
+        this.builder.whereIn(column, values);
+        return this;
+    }
+    whereNotIn(column, values) {
+        this.builder.whereNotIn(column, values);
+        return this;
+    }
+    whereNull(column) {
+        this.builder.whereNull(column);
+        return this;
+    }
+    whereNotNull(column) {
+        this.builder.whereNotNull(column);
+        return this;
+    }
+    whereBetween(column, range) {
+        this.builder.whereBetween(column, range);
+        return this;
+    }
+    whereLike(column, pattern) {
+        this.builder.whereLike(column, pattern);
+        return this;
+    }
+    orderBy(column, direction = "asc") {
+        this.builder.orderBy(column, direction);
+        return this;
+    }
+    latest(column = "created_at") {
+        this.builder.latest(column);
+        return this;
+    }
+    oldest(column = "created_at") {
+        this.builder.oldest(column);
+        return this;
+    }
+    limit(n) {
+        this.builder.limit(n);
+        return this;
+    }
+    offset(n) {
+        this.builder.offset(n);
+        return this;
+    }
+    /* ---------------------------- relationship ops ----------------------------- */
+    /** Eager-load relations (dotted paths for nesting: `"posts.comments"`). */
+    with(...names) {
+        this.eagers.push(...names);
+        return this;
+    }
+    /** Add a `<relation>_count` to each result. */
+    withCount(...names) {
+        this.counts.push(...names);
+        return this;
+    }
+    /** Constrain to models that have at least one related row. */
+    has(name) {
+        this.hasConstraints.push({ name, negate: false });
+        return this;
+    }
+    /** Constrain to models whose related rows match `constrain`. */
+    whereHas(name, constrain) {
+        this.hasConstraints.push({ name, ...(constrain ? { constrain } : {}), negate: false });
+        return this;
+    }
+    /** Constrain to models with no matching related row. */
+    doesntHave(name, constrain) {
+        this.hasConstraints.push({ name, ...(constrain ? { constrain } : {}), negate: true });
+        return this;
+    }
+    /* -------------------------------- terminals -------------------------------- */
+    async get() {
+        await this.resolveHasConstraints();
+        const rows = await this.builder.get();
+        const models = await Promise.all(rows.map((row) => this.hydrate(row)));
+        if (this.eagers.length)
+            await eagerLoad(models, this.eagers);
+        if (this.counts.length)
+            await this.loadCounts(models);
+        return models;
+    }
+    async first() {
+        this.builder.limit(1);
+        const [model] = await this.get();
+        return model ?? null;
+    }
+    async count() {
+        await this.resolveHasConstraints();
+        return this.builder.count();
+    }
+    async exists() {
+        return (await this.count()) > 0;
+    }
+    async paginate(page = 1, perPage = 15) {
+        await this.resolveHasConstraints();
+        const result = await this.builder.paginate(page, perPage);
+        const data = await Promise.all(result.data.map((row) => this.hydrate(row)));
+        if (this.eagers.length)
+            await eagerLoad(data, this.eagers);
+        if (this.counts.length)
+            await this.loadCounts(data);
+        return { ...result, data };
+    }
+    /* -------------------------------- internals -------------------------------- */
+    async hydrate(row) {
+        const model = new this.cls(row);
+        await fireModelEvent(this.cls, "retrieved", model);
+        return model;
+    }
+    relationFor(name) {
+        const probe = new this.cls();
+        const method = probe[name];
+        if (typeof method !== "function") {
+            throw new Error(`${this.cls.name} has no relation "${name}"`);
+        }
+        return method.call(probe);
+    }
+    /** Turn recorded has/doesntHave constraints into `whereIn`/`whereNotIn` on the builder. */
+    async resolveHasConstraints() {
+        for (const { name, constrain, negate } of this.hasConstraints) {
+            const relation = this.relationFor(name);
+            const keys = await relation.matchingParentKeys(constrain);
+            const column = relation.parentColumn();
+            if (negate) {
+                if (keys.length)
+                    this.builder.whereNotIn(column, keys);
+            }
+            else if (keys.length) {
+                this.builder.whereIn(column, keys);
+            }
+            else {
+                // No related rows exist → nothing can match. A contradiction yields zero
+                // rows without an invalid empty `IN ()`.
+                this.builder.whereNull(column).whereNotNull(column);
+            }
+        }
+        this.hasConstraints = [];
+    }
+    async loadCounts(models) {
+        for (const name of this.counts) {
+            const relation = this.relationFor(name);
+            const column = relation.parentColumn();
+            const keys = [...new Set(models.map((m) => m[column]).filter((v) => v != null))];
+            const counts = await relation.countsByParent(keys);
+            for (const model of models) {
+                model[`${name}_count`] = counts.get(model[column]) ?? 0;
+            }
+        }
+    }
+}

package/dist/core/model.d.ts

@@ -16,8 +16,14 @@
  *   await user.save();
  */
 import { type QueryBuilder, type Row, type Paginated } from "./database.js";
-import { BelongsTo, BelongsToMany, HasMany, HasOne } from "./relations.js";
+import { BelongsTo, BelongsToMany, HasMany, HasOne, MorphMany, MorphOne, MorphTo } from "./relations.js";
 import { type Casts } from "./casts.js";
+import { type ModelHook, type ModelObserver } from "./model-events.js";
+import { ModelQuery } from "./model-query.js";
+/** A global scope: a constraint applied to every query a model builds. */
+export type GlobalScope = (query: QueryBuilder) => void;
+/** How a model query treats soft-deleted rows. */
+type TrashedMode = "exclude" | "with" | "only";
 type ModelClass<T extends Model> = (new (attributes?: Row) => T) & typeof Model;
 export declare class Model {
     static table: string;
@@ -34,10 +40,78 @@ export declare class Model {
     static timestamps: boolean;
     static createdAtColumn: string;
     static updatedAtColumn: string;
+    /** Columns stripped from `toJSON()` output (e.g. `["password"]`). */
+    static hidden: string[];
+    /** If set, ONLY these keys survive `toJSON()` — an allowlist that wins over `hidden`. */
+    static visible: string[];
+    /** Computed accessor names (getters or zero-arg methods) added to `toJSON()`. */
+    static appends: string[];
+    /** Soft deletes: `delete()` sets `deleted_at` instead of removing the row. */
+    static softDeletes: boolean;
+    static deletedAtColumn: string;
     [key: string]: unknown;
     constructor(attributes?: Row);
-    /** A raw query builder scoped to this model's table. */
+    /** Register a global scope — a constraint applied to every query this model builds. */
+    static addGlobalScope(name: string, scope: GlobalScope): void;
+    /** Build this model's base query, applying global scopes and the soft-delete filter. */
+    protected static baseQuery(trashed?: TrashedMode): QueryBuilder;
+    /** A query builder scoped to this model's table (global scopes applied). */
     static query(): QueryBuilder;
+    /** Include soft-deleted rows (bypasses the soft-delete scope). */
+    static withTrashed(): QueryBuilder;
+    /** Only soft-deleted rows. */
+    static onlyTrashed(): QueryBuilder;
+    /** A model-aware query — hydrates to models and supports `with`/`withCount`/`whereHas`. */
+    static newQuery<T extends Model>(this: ModelClass<T>): ModelQuery<T>;
+    /** Start a query eager-loading the given relations (dotted paths nest). */
+    static with<T extends Model>(this: ModelClass<T>, ...names: string[]): ModelQuery<T>;
+    /** Start a query counting the given relations into `<relation>_count`. */
+    static withCount<T extends Model>(this: ModelClass<T>, ...names: string[]): ModelQuery<T>;
+    /** Start a query constrained to models that have at least one related row. */
+    static has<T extends Model>(this: ModelClass<T>, name: string): ModelQuery<T>;
+    /** Start a query constrained to models whose related rows match `constrain`. */
+    static whereHas<T extends Model>(this: ModelClass<T>, name: string, constrain?: (q: QueryBuilder) => void): ModelQuery<T>;
+    /** Start a query constrained to models with no matching related row. */
+    static doesntHave<T extends Model>(this: ModelClass<T>, name: string, constrain?: (q: QueryBuilder) => void): ModelQuery<T>;
+    /** Construct a model from a row and fire its `retrieved` event. */
+    protected static hydrate<T extends Model>(this: ModelClass<T>, row: Row): Promise<T>;
+    static creating<T extends Model>(this: {
+        new (...args: never[]): T;
+    }, hook: ModelHook<T>): void;
+    static created<T extends Model>(this: {
+        new (...args: never[]): T;
+    }, hook: ModelHook<T>): void;
+    static updating<T extends Model>(this: {
+        new (...args: never[]): T;
+    }, hook: ModelHook<T>): void;
+    static updated<T extends Model>(this: {
+        new (...args: never[]): T;
+    }, hook: ModelHook<T>): void;
+    static saving<T extends Model>(this: {
+        new (...args: never[]): T;
+    }, hook: ModelHook<T>): void;
+    static saved<T extends Model>(this: {
+        new (...args: never[]): T;
+    }, hook: ModelHook<T>): void;
+    static deleting<T extends Model>(this: {
+        new (...args: never[]): T;
+    }, hook: ModelHook<T>): void;
+    static deleted<T extends Model>(this: {
+        new (...args: never[]): T;
+    }, hook: ModelHook<T>): void;
+    static restoring<T extends Model>(this: {
+        new (...args: never[]): T;
+    }, hook: ModelHook<T>): void;
+    static restored<T extends Model>(this: {
+        new (...args: never[]): T;
+    }, hook: ModelHook<T>): void;
+    static retrieved<T extends Model>(this: {
+        new (...args: never[]): T;
+    }, hook: ModelHook<T>): void;
+    /** Register an observer whose methods are named after the events they handle. */
+    static observe<T extends Model>(this: {
+        new (...args: never[]): T;
+    }, observer: ModelObserver<T>): void;
     /** Keep only the attributes mass-assignment allows (fillable / guarded). */
     static filterFillable(attributes: Row): Row;
     /** Cast attributes to their storable primitives for a write. */
@@ -57,7 +131,7 @@ export declare class Model {
     static firstOrCreate<T extends Model>(this: ModelClass<T>, match: Row, values?: Row): Promise<T>;
     /** Update the first row matching `match` with `values`, or create it. */
     static updateOrCreate<T extends Model>(this: ModelClass<T>, match: Row, values?: Row): Promise<T>;
-    /** A query scoped to every column/value in `match`. */
+    /** A query scoped to every column/value in `match` (global scopes applied). */
     private static matching;
     /**
      * Eager-load relations onto an array of models with one extra query each —
@@ -75,17 +149,30 @@ export declare class Model {
     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>;
+    /** Polymorphic one-to-many: children carry `<name>_id` + `<name>_type`. */
+    morphMany<T extends Model>(related: ModelClass<T>, name: string, localKey?: string): MorphMany<T>;
+    /** Polymorphic one-to-one. */
+    morphOne<T extends Model>(related: ModelClass<T>, name: string, localKey?: string): MorphOne<T>;
+    /** The owning side of a polymorphic relation — resolves via `<name>_type` (see `registerMorphType`). */
+    morphTo(name: string, idColumn?: string, typeColumn?: string): MorphTo;
     /** 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). */
+    /** Insert (no primary key) or update (has one). Fires save/create/update events. */
     save(): Promise<this>;
     /** Mass-assign then save — `fill` + `save` in one call. */
     update(attributes: Row): Promise<this>;
     /** Reload this model's columns from the database. */
     refresh(): Promise<this>;
+    /** Delete the row — or, with soft deletes on, set `deleted_at`. Fires delete events. */
     delete(): Promise<void>;
+    /** Permanently delete a soft-deletable row (bypasses soft deletes). */
+    forceDelete(): Promise<void>;
+    /** Restore a soft-deleted row (clears `deleted_at`). Fires restore events. */
+    restore(): Promise<this>;
+    /** Whether this soft-deletable model is currently trashed. */
+    trashed(): boolean;
     /** Merge mass-assignable attributes into the model (cast, not saved). */
     fill(attributes: Row): this;
     /** Force-assign attributes, bypassing mass-assignment guarding (still cast). */