@rudderjs/orm 1.5.0 → 1.7.0

package/dist/index.js

@@ -1,9 +1,12 @@
 import { castGet, castSet } from './cast.js';
+import { AGGREGATES_SYMBOL, aggregateKeysOf, loadCountOrExists, loadMissingRelations, loadNumericAggregate, normalizeWithCount, normalizeWithExists, normalizeWithNumericAggregate, } from './aggregate.js';
 export { Attribute } from './attribute.js';
 export { JsonResource, ResourceCollection } from './resource.js';
 export { ModelCollection } from './collection.js';
 export { ModelFactory, sequence } from './factory.js';
 export { Seeder } from './seeder.js';
+export { AggregateConstraintBuilder, AGGREGATES_SYMBOL } from './aggregate.js';
+export { pruneModels } from './prune.js';
 // ─── Global ORM Registry ───────────────────────────────────
 export class ModelRegistry {
     static adapter = null;
@@ -38,6 +41,7 @@ export class ModelRegistry {
             return;
         this.models.set(name, ModelClass);
         _installBelongsToManyMethods(ModelClass);
+        _installMorphPivotMethods(ModelClass);
         for (const listener of this.listeners)
             listener(name, ModelClass);
     }
@@ -179,6 +183,13 @@ export class Model {
      * }
      */
     static morphAlias;
+    /**
+     * Pruning mode for `pnpm rudder model:prune`. Override to `'mass'` for
+     * {@link MassPrunable}. The runner only considers models that also define
+     * `static prunable()`; this static just disambiguates instance- vs
+     * bulk-mode for those that do.
+     */
+    static pruneMode = 'instance';
     /**
      * Column used to resolve a route parameter into a Model instance via
      * {@link Model.findForRoute}. Defaults to the primary key. Override to
@@ -234,10 +245,9 @@ export class Model {
      * want a chainable QueryBuilder scoped to the parent record.
      *
      * Supported types: `hasMany`, `hasOne`, `belongsTo`, `belongsToMany`,
-     * `morphMany`, `morphOne`, `morphTo`. Polymorphic columns use camelCase
-     * (`commentableId` / `commentableType`) for ORM consistency — a deliberate
-     * divergence from Laravel's snake_case. `morphToMany` / `morphedByMany` are
-     * deferred (drop to the adapter for now).
+     * `morphMany`, `morphOne`, `morphTo`, `morphToMany`, `morphedByMany`.
+     * Polymorphic columns use camelCase (`commentableId` / `commentableType`)
+     * for ORM consistency — a deliberate divergence from Laravel's snake_case.
      *
      * For `belongsToMany`, pivot mutations (`attach` / `detach` / `sync`) live
      * on a separate accessor — see {@link Model.belongsToMany}. `related()`
@@ -338,6 +348,16 @@ export class Model {
     #instanceHidden;
     /** @internal */
     #instanceVisible;
+    // ── Dirty Tracking ─────────────────────────────────────
+    //
+    // Snapshot of attribute values as of the last load / save / refresh.
+    // Used by isDirty / isClean / wasChanged / getOriginal / getChanges /
+    // getDirty. Captured by hydrate(), save(), refresh(), and increment/
+    // decrement so the baseline always matches the persisted state.
+    /** @internal — own enumerable column values as of last load/save/refresh. */
+    #original = {};
+    /** @internal — diff of attributes that changed during the most recent save. */
+    #changes = {};
     // ── Scopes ─────────────────────────────────────────────
     static globalScopes = {};
     static scopes = {};
@@ -428,16 +448,80 @@ export class Model {
         const Ctor = this;
         const instance = new Ctor();
         Object.assign(instance, record);
+        instance._syncOriginal();
         return instance;
     }
     /** @internal — wrap a QueryBuilder so its read methods return Model instances. */
     static _hydratingQb(self, qb) {
         const ModelClass = self;
-        const wrap = (r) => ModelClass.hydrate.call(self, r);
+        /** Aliases stamped onto rows by the adapter for any aggregates registered
+         *  on this QB. Tagged on each hydrated instance via `aggregateKeysOf` so
+         *  `_toData()` excludes them on writes. */
+        const aggregateAliases = new Set();
+        const wrap = (r) => {
+            const inst = ModelClass.hydrate.call(self, r);
+            if (inst && aggregateAliases.size > 0) {
+                const set = aggregateKeysOf(inst);
+                for (const a of aggregateAliases)
+                    set.add(a);
+            }
+            return inst;
+        };
         const wrapMaybe = (r) => r == null ? null : wrap(r);
         const wrapMany = (rs) => rs.map(wrap);
+        const dispatchAggregates = (reqs) => {
+            for (const r of reqs)
+                aggregateAliases.add(r.alias);
+            qb.withAggregate(reqs);
+        };
         const proxy = new Proxy(qb, {
             get(target, prop, receiver) {
+                // ORM-side chainables that don't exist on the adapter QB itself —
+                // intercept before the existence check below, since `whereHas` etc.
+                // are added by this proxy, not by the adapter.
+                if (prop === 'whereHas') {
+                    return (relation, constrain) => {
+                        _attachWhereHas(ModelClass, target, relation, true, constrain);
+                        return proxy;
+                    };
+                }
+                if (prop === 'whereDoesntHave') {
+                    return (relation, constrain) => {
+                        _attachWhereHas(ModelClass, target, relation, false, constrain);
+                        return proxy;
+                    };
+                }
+                if (prop === 'withWhereHas') {
+                    return (relation, constrain) => {
+                        _attachWithWhereHas(ModelClass, target, relation, constrain);
+                        return proxy;
+                    };
+                }
+                if (prop === 'whereBelongsTo') {
+                    return (parent, relation) => {
+                        _attachWhereBelongsTo(ModelClass, target, parent, relation);
+                        return proxy;
+                    };
+                }
+                if (prop === 'withCount') {
+                    return (arg) => {
+                        dispatchAggregates(normalizeWithCount(ModelClass, arg));
+                        return proxy;
+                    };
+                }
+                if (prop === 'withExists') {
+                    return (arg) => {
+                        dispatchAggregates(normalizeWithExists(ModelClass, arg));
+                        return proxy;
+                    };
+                }
+                if (prop === 'withSum' || prop === 'withMin' || prop === 'withMax' || prop === 'withAvg') {
+                    const fn = prop.slice(4).toLowerCase();
+                    return (arg1, arg2) => {
+                        dispatchAggregates(normalizeWithNumericAggregate(ModelClass, fn, arg1, arg2));
+                        return proxy;
+                    };
+                }
                 const value = Reflect.get(target, prop, receiver);
                 if (typeof value !== 'function')
                     return value;
@@ -576,6 +660,120 @@ export class Model {
     static where(column, value) {
         return Model._q(this).where(column, value);
     }
+    /**
+     * Filter rows where the named relation has at least one matching child.
+     * The optional callback receives a sub-QueryBuilder scoped to the related
+     * model — chain `.where()` etc. on it to narrow the relation predicate
+     * further.
+     *
+     * Resolves the relation declaration on `static relations`, builds a
+     * {@link RelationExistencePredicate}, and dispatches it to the adapter via
+     * `whereRelationExists`. `morphTo` relations are not supported (the related
+     * table is dynamic) — call sites should filter on the discriminator
+     * columns directly.
+     *
+     * @example
+     * await User.whereHas('posts').get()                                         // users with at least one post
+     * await User.whereHas('posts', q => q.where('published', true)).get()        // users with at least one published post
+     * await Post.whereHas('tags', q => q.where('name', 'featured')).get()        // belongsToMany pivot path
+     * await Post.whereHas('comments').get()                                      // morphMany — adds the {morph}Type filter automatically
+     */
+    static whereHas(relation, constrain) {
+        return _attachWhereHas(this, Model._q(this), relation, true, constrain);
+    }
+    /**
+     * Inverse of {@link Model.whereHas} — rows whose named relation has zero
+     * matching children. Same constrain-callback semantics: when present,
+     * narrows the "matching" set so `whereDoesntHave` matches "no children
+     * matching the constraint" rather than "no children at all".
+     */
+    static whereDoesntHave(relation, constrain) {
+        return _attachWhereHas(this, Model._q(this), relation, false, constrain);
+    }
+    /**
+     * `whereHas` + `with` — filter by the relation predicate AND eager-load the
+     * matching rows under the same constraint when the adapter supports it
+     * (`withConstrained`). Adapters without constrained eager-load fall back to
+     * unconstrained `with(relation)` — every related row is returned even if
+     * the parent was matched on a narrower predicate.
+     */
+    static withWhereHas(relation, constrain) {
+        return _attachWithWhereHas(this, Model._q(this), relation, constrain);
+    }
+    /**
+     * Filter rows whose `belongsTo` relation points at `parent`. Sugar for
+     * `where(fk, parent.primaryKeyValue)` with the FK column resolved from the
+     * relation declaration. When `relation` is omitted, looks up the single
+     * `belongsTo` relation pointing at `parent.constructor` and throws if zero
+     * or more-than-one match.
+     *
+     * @example
+     * await Post.whereBelongsTo(user).get()             // posts whose author belongsTo this user (single FK)
+     * await Comment.whereBelongsTo(post, 'post').get()  // explicit relation name when ambiguous
+     */
+    static whereBelongsTo(parent, relation) {
+        return _attachWhereBelongsTo(this, Model._q(this), parent, relation);
+    }
+    /**
+     * Aggregate eager-loading — count related rows alongside the parent in a
+     * single query. The result is stamped onto each parent under
+     * `<relation>Count` (`postsCount` for `withCount('posts')`) without dropping
+     * into the adapter.
+     *
+     * Three call shapes:
+     *   - `withCount('posts')` — single relation, no constraint.
+     *   - `withCount(['posts', 'comments'])` — multiple, no constraints.
+     *   - `withCount({ posts: q => q.where('published', true).as('publishedPosts') })`
+     *     — map form with `where`/`orWhere` constraints + optional alias override.
+     *
+     * Closes the N+1 footgun for hot list pages. For a single instance use
+     * `instance.loadCount('posts')` instead.
+     *
+     * @example
+     * await User.query().withCount('posts').get()                                  // user.postsCount
+     * await User.query().withCount({ posts: q => q.where('published', true) }).get()
+     * await Post.query().withCount(['comments', 'tags']).paginate(1)
+     */
+    static withCount(arg) {
+        return Model._q(this).withCount(arg);
+    }
+    /**
+     * Boolean aggregate — stamps `<relation>Exists` (true/false) onto each
+     * parent. Cheap on Prisma (translates to `_count > 0`) and Drizzle
+     * (`EXISTS (...)` correlated subquery). Use this instead of `withCount`
+     * when you only need presence, not the count.
+     */
+    static withExists(arg) {
+        return Model._q(this).withExists(arg);
+    }
+    /**
+     * Aggregate eager-loading — sum a column across the related rows.
+     * Stamps `<relation>Sum<Column>` onto each parent (e.g.
+     * `withSum('orders', 'total')` → `ordersSumTotal`).
+     *
+     * Map form supports per-relation constraints + alias overrides:
+     *
+     * ```ts
+     * await User.query().withSum({
+     *   orders: { column: 'total', constraint: q => q.where('status', 'paid') },
+     * }).get()
+     * ```
+     */
+    static withSum(arg1, column) {
+        return Model._q(this).withSum(arg1, column);
+    }
+    /** Min of a column across the related rows. Stamps `<relation>Min<Column>`. */
+    static withMin(arg1, column) {
+        return Model._q(this).withMin(arg1, column);
+    }
+    /** Max of a column across the related rows. Stamps `<relation>Max<Column>`. */
+    static withMax(arg1, column) {
+        return Model._q(this).withMax(arg1, column);
+    }
+    /** Average of a column across the related rows. Stamps `<relation>Avg<Column>`. */
+    static withAvg(arg1, column) {
+        return Model._q(this).withAvg(arg1, column);
+    }
     /**
      * Find a record by attributes; if none exists, create one with `attrs` merged with `values`.
      * Returns the existing or newly-created record.
@@ -765,21 +963,39 @@ export class Model {
         return value;
     }
     /**
-     * @internal — own enumerable data fields, with framework-internal `_` keys
-     * stripped and `undefined` values dropped so a class-declared but never-set
-     * field (`id!: number`) doesn't leak into a create/update payload.
+     * @internal — current own-property column attributes, with framework `_`
+     * keys + `undefined` placeholders dropped. Aggregate-injected keys (stamped
+     * by `withCount` / `loadCount` etc.) are excluded — they're not real schema
+     * columns and would be rejected by Prisma writes / Drizzle inserts.
+     *
+     * Single source of truth shared by `_toData()` and dirty-tracking baselines.
      */
-    _toData() {
+    _currentAttrs() {
         const out = {};
+        const aggregates = this[AGGREGATES_SYMBOL];
         for (const [k, v] of Object.entries(this)) {
             if (k.startsWith('_'))
                 continue;
             if (v === undefined)
                 continue;
+            if (aggregates && aggregates.has(k))
+                continue;
             out[k] = v;
         }
         return out;
     }
+    /**
+     * @internal — own enumerable data fields, with framework-internal `_` keys
+     * stripped and `undefined` values dropped so a class-declared but never-set
+     * field (`id!: number`) doesn't leak into a create/update payload.
+     */
+    _toData() {
+        return this._currentAttrs();
+    }
+    /** @internal — capture current attrs as the new dirty-tracking baseline. */
+    _syncOriginal() {
+        this.#original = this._currentAttrs();
+    }
     /**
      * Persist this instance. Inserts when the primary key is unset; otherwise updates.
      *
@@ -797,6 +1013,14 @@ export class Model {
             ? await Model._doCreate.call(ctor, data)
             : await Model._doUpdate.call(ctor, id, data);
         Object.assign(this, persisted);
+        const next = this._currentAttrs();
+        const diff = {};
+        for (const k of new Set([...Object.keys(next), ...Object.keys(this.#original)])) {
+            if (!_attrEqual(next[k], this.#original[k]))
+                diff[k] = next[k];
+        }
+        this.#changes = diff;
+        this.#original = next;
         return this;
     }
     /**
@@ -840,6 +1064,8 @@ export class Model {
                 delete this[k];
         }
         Object.assign(this, fresh);
+        this.#changes = {};
+        this._syncOriginal();
         return this;
     }
     /**
@@ -854,6 +1080,42 @@ export class Model {
         }
         await ctor.delete(id);
     }
+    /**
+     * Restore this soft-deleted instance — clears `deletedAt` and routes through
+     * the static `restore()` so observers fire. Refreshes in-place with the
+     * canonical row returned from the database.
+     */
+    async restore() {
+        const ctor = this.constructor;
+        const id = this._getKey();
+        if (id === undefined) {
+            throw new Error(`[RudderJS ORM] Cannot restore a ${ctor.name} without a primary key.`);
+        }
+        const restored = await ctor.restore(id);
+        Object.assign(this, restored);
+        this._syncOriginal();
+        return this;
+    }
+    /**
+     * Persist this instance without firing observer / listener events.
+     * Equivalent to `await Model.withoutEvents(() => instance.save())`.
+     *
+     * Per-class — observers cascading into child classes still fire normally.
+     */
+    async saveQuietly() {
+        const ctor = this.constructor;
+        return ctor.withoutEvents(() => this.save());
+    }
+    /** Delete this instance without firing observer / listener events. */
+    async deleteQuietly() {
+        const ctor = this.constructor;
+        await ctor.withoutEvents(() => this.delete());
+    }
+    /** Restore this soft-deleted instance without firing observer / listener events. */
+    async restoreQuietly() {
+        const ctor = this.constructor;
+        return ctor.withoutEvents(() => this.restore());
+    }
     /**
      * Atomically add `amount` to `column` on this instance. The row is updated
      * via SQL `UPDATE col = col + amount` and the new value is merged back into
@@ -870,6 +1132,67 @@ export class Model {
         }
         const updated = await ctor.increment(id, column, amount, extra);
         Object.assign(this, updated);
+        this._syncOriginal();
+        return this;
+    }
+    /**
+     * Aggregate-load related rows for this single instance. Mutates in place
+     * by setting `this[<relation>Count]` (or the `.as(name)` override) and
+     * returns `this` for chaining.
+     *
+     * One round-trip per call. For batched loads on a list, prefer
+     * `Model.query().withCount(...)` on the parent query.
+     *
+     * @example
+     * const user = await User.find(1)
+     * await user!.loadCount('posts')
+     * console.log(user!.postsCount)
+     *
+     * await user!.loadCount({ posts: q => q.where('published', true).as('publishedPosts') })
+     * console.log(user!.publishedPostsCount)
+     */
+    async loadCount(arg) {
+        await loadCountOrExists(this, 'count', arg);
+        return this;
+    }
+    /** Boolean aggregate — stamps `<relation>Exists` on the instance. */
+    async loadExists(arg) {
+        await loadCountOrExists(this, 'exists', arg);
+        return this;
+    }
+    /** Sum of `column` across the related rows. Stamps `<relation>Sum<Column>`. */
+    async loadSum(arg1, column) {
+        await loadNumericAggregate(this, 'sum', arg1, column);
+        return this;
+    }
+    /** Min of `column` across the related rows. Stamps `<relation>Min<Column>`. */
+    async loadMin(arg1, column) {
+        await loadNumericAggregate(this, 'min', arg1, column);
+        return this;
+    }
+    /** Max of `column` across the related rows. Stamps `<relation>Max<Column>`. */
+    async loadMax(arg1, column) {
+        await loadNumericAggregate(this, 'max', arg1, column);
+        return this;
+    }
+    /** Average of `column` across the related rows. Stamps `<relation>Avg<Column>`. */
+    async loadAvg(arg1, column) {
+        await loadNumericAggregate(this, 'avg', arg1, column);
+        return this;
+    }
+    /**
+     * Eager-load each named relation onto the instance only when the property
+     * is currently `null` / `undefined`. Truthy properties are skipped — useful
+     * after partial hydration to backfill the relations a downstream consumer
+     * needs without refetching what's already there.
+     *
+     * @example
+     * const user = await User.query().with('profile').first()
+     * // profile already populated; only `posts` issues a query.
+     * await user!.loadMissing('profile', 'posts')
+     */
+    async loadMissing(...relations) {
+        await loadMissingRelations(this, relations);
         return this;
     }
     /**
@@ -884,6 +1207,7 @@ export class Model {
         }
         const updated = await ctor.decrement(id, column, amount, extra);
         Object.assign(this, updated);
+        this._syncOriginal();
         return this;
     }
     /**
@@ -917,6 +1241,47 @@ export class Model {
         }
         return clone;
     }
+    // ── Dirty Tracking ─────────────────────────────────────
+    /**
+     * Whether any attribute (or the named attribute) has been changed since
+     * the last save / load / refresh.
+     */
+    isDirty(key) {
+        const dirty = this.getDirty();
+        return key === undefined ? Object.keys(dirty).length > 0 : key in dirty;
+    }
+    /** Inverse of {@link isDirty}. */
+    isClean(key) {
+        return !this.isDirty(key);
+    }
+    /**
+     * Whether the named attribute (or any attribute) was actually changed on
+     * the most recent {@link save}. Stays true until the next save or refresh.
+     */
+    wasChanged(key) {
+        return key === undefined
+            ? Object.keys(this.#changes).length > 0
+            : key in this.#changes;
+    }
+    getOriginal(key) {
+        if (key === undefined)
+            return { ...this.#original };
+        return this.#original[key];
+    }
+    /** Diff map of attributes that changed during the most recent {@link save}. */
+    getChanges() {
+        return { ...this.#changes };
+    }
+    /** Diff map of attributes currently dirty (unsaved). */
+    getDirty() {
+        const out = {};
+        const current = this._currentAttrs();
+        for (const k of new Set([...Object.keys(current), ...Object.keys(this.#original)])) {
+            if (!_attrEqual(current[k], this.#original[k]))
+                out[k] = current[k];
+        }
+        return out;
+    }
     /**
      * True when `other` represents the same record — same model class (by table)
      * and same primary key.
@@ -1015,6 +1380,22 @@ export class Model {
             }
             return _belongsToManyDeferredQb(Related, def, meta, parentVal);
         }
+        if (def.type === 'morphToMany') {
+            const meta = _resolveMorphToManyMeta(ctor, Related, def);
+            const parentVal = this[meta.parentKey];
+            if (parentVal === undefined || parentVal === null) {
+                throw new Error(`[RudderJS ORM] Cannot resolve "${name}" on ${ctor.name} — ${meta.parentKey} is unset.`);
+            }
+            return _morphToManyDeferredQb(Related, def, meta, parentVal);
+        }
+        if (def.type === 'morphedByMany') {
+            const meta = _resolveMorphedByManyMeta(ctor, Related, def);
+            const parentVal = this[meta.parentKey];
+            if (parentVal === undefined || parentVal === null) {
+                throw new Error(`[RudderJS ORM] Cannot resolve "${name}" on ${ctor.name} — ${meta.parentKey} is unset.`);
+            }
+            return _morphedByManyDeferredQb(Related, def, meta, parentVal);
+        }
         if (def.type === 'belongsTo') {
             // This model holds the FK; query the related model's PK.
             const fk = def.foreignKey ?? `${fkCamel(Related.name)}Id`;
@@ -1073,6 +1454,71 @@ export class Model {
         _installBelongsToManyMethods(ctor);
         return _makeBelongsToManyAccessor(ctor, Related, def, parentVal);
     }
+    /**
+     * Pivot-mutation accessor for a `morphToMany` relation (the polymorphic
+     * owning side, e.g. `Post.tags()`). Same surface as `belongsToMany` —
+     * `attach`/`detach`/`sync` — but every pivot row carries the parent's
+     * discriminator (`{morphName}Type`) and every pivot query filters by it.
+     *
+     * @example
+     * class Post extends Model {
+     *   static override relations = {
+     *     tags: { type: 'morphToMany' as const, model: () => Tag, pivotTable: 'taggable', morphName: 'taggable' },
+     *   }
+     *   tags() { return Model.morphToMany(this, 'tags') }
+     * }
+     */
+    static morphToMany(parent, name) {
+        const ctor = parent.constructor;
+        const def = ctor.relations[name];
+        if (!def) {
+            throw new Error(`[RudderJS ORM] Relation "${name}" is not defined on ${ctor.name}.`);
+        }
+        if (def.type !== 'morphToMany') {
+            throw new Error(`[RudderJS ORM] Relation "${name}" on ${ctor.name} is "${def.type}", not "morphToMany".`);
+        }
+        const Related = def.model();
+        const meta = _resolveMorphToManyMeta(ctor, Related, def);
+        const parentVal = parent[meta.parentKey];
+        if (parentVal === undefined || parentVal === null) {
+            throw new Error(`[RudderJS ORM] Cannot use morphToMany "${name}" on ${ctor.name} — ${meta.parentKey} is unset.`);
+        }
+        _installMorphPivotMethods(ctor);
+        return _makeMorphToManyAccessor(ctor, Related, def, parentVal);
+    }
+    /**
+     * Pivot-mutation accessor for a `morphedByMany` relation (the inverse
+     * polymorphic side, e.g. `Tag.posts()`). Each `morphedByMany` declaration
+     * targets one concrete inverse class; declare one relation per target.
+     *
+     * @example
+     * class Tag extends Model {
+     *   static override relations = {
+     *     posts:  { type: 'morphedByMany' as const, model: () => Post,  pivotTable: 'taggable', morphName: 'taggable' },
+     *     videos: { type: 'morphedByMany' as const, model: () => Video, pivotTable: 'taggable', morphName: 'taggable' },
+     *   }
+     *   posts()  { return Model.morphedByMany(this, 'posts') }
+     *   videos() { return Model.morphedByMany(this, 'videos') }
+     * }
+     */
+    static morphedByMany(parent, name) {
+        const ctor = parent.constructor;
+        const def = ctor.relations[name];
+        if (!def) {
+            throw new Error(`[RudderJS ORM] Relation "${name}" is not defined on ${ctor.name}.`);
+        }
+        if (def.type !== 'morphedByMany') {
+            throw new Error(`[RudderJS ORM] Relation "${name}" on ${ctor.name} is "${def.type}", not "morphedByMany".`);
+        }
+        const Related = def.model();
+        const meta = _resolveMorphedByManyMeta(ctor, Related, def);
+        const parentVal = parent[meta.parentKey];
+        if (parentVal === undefined || parentVal === null) {
+            throw new Error(`[RudderJS ORM] Cannot use morphedByMany "${name}" on ${ctor.name} — ${meta.parentKey} is unset.`);
+        }
+        _installMorphPivotMethods(ctor);
+        return _makeMorphedByManyAccessor(ctor, Related, def, parentVal);
+    }
     /**
      * Build the `{name}Id + {name}Type` payload for a polymorphic write.
      *
@@ -1212,6 +1658,34 @@ export class Model {
         return Object.fromEntries(Object.entries(result).filter(([k]) => !effectiveHidden.includes(k)));
     }
 }
+// ─── Dirty tracking equality ───────────────────────────────
+/**
+ * @internal — value equality used by dirty tracking. Mirrors Eloquent's
+ * `originalIsEquivalent`: strict for primitives, `getTime()` for Date,
+ * structural-by-JSON for arrays / plain objects (covers `json` / `array`
+ * casts), null/undefined collapsed.
+ *
+ * Caveat: JSON.stringify is key-order sensitive, so `{a:1,b:2}` vs
+ * `{b:2,a:1}` compares unequal. Same posture Laravel takes — documented
+ * in the Dirty Tracking section of the orm README.
+ */
+function _attrEqual(a, b) {
+    if (a === b)
+        return true;
+    if (a == null && b == null)
+        return true;
+    if (a instanceof Date && b instanceof Date)
+        return a.getTime() === b.getTime();
+    if (typeof a === 'object' && a !== null && typeof b === 'object' && b !== null) {
+        try {
+            return JSON.stringify(a) === JSON.stringify(b);
+        }
+        catch {
+            return false;
+        }
+    }
+    return false;
+}
 function _camelHead(s) {
     return s.charAt(0).toLowerCase() + s.slice(1);
 }
@@ -1236,6 +1710,250 @@ function _resolveBelongsToManyMeta(Parent, Related, def) {
         relatedKey: def.relatedKey ?? Related.primaryKey,
     };
 }
+function _resolveMorphToManyMeta(Parent, Related, def) {
+    return {
+        pivotTable: def.pivotTable,
+        foreignPivotKey: `${def.morphName}Id`,
+        morphTypeKey: `${def.morphName}Type`,
+        morphTypeValue: def.morphType ?? Parent.morphAlias ?? Parent.name,
+        relatedPivotKey: def.relatedPivotKey ?? `${_camelHead(Related.name)}Id`,
+        parentKey: def.parentKey ?? Parent.primaryKey,
+        relatedKey: def.relatedKey ?? Related.primaryKey,
+    };
+}
+function _resolveMorphedByManyMeta(Parent, Related, def) {
+    return {
+        pivotTable: def.pivotTable,
+        relatedPivotKey: `${def.morphName}Id`,
+        morphTypeKey: `${def.morphName}Type`,
+        morphTypeValue: def.morphType ?? Related.morphAlias ?? Related.name,
+        foreignPivotKey: def.foreignPivotKey ?? `${_camelHead(Parent.name)}Id`,
+        parentKey: def.parentKey ?? Parent.primaryKey,
+        relatedKey: def.relatedKey ?? Related.primaryKey,
+    };
+}
+// ─── whereHas internals ────────────────────────────────────
+/**
+ * Run the constrain callback against a recording-only QueryBuilder that
+ * captures `.where()` calls into a flat `WhereClause[]` and treats every
+ * other chainable method as a no-op. Nested `whereHas` inside the callback
+ * throws — recursive predicates are deferred to v2.
+ */
+function _captureConstraintWheres(constrain) {
+    const wheres = [];
+    const recorder = new Proxy({}, {
+        get(_t, prop) {
+            const name = String(prop);
+            if (name === 'where') {
+                return (col, opOrVal, maybeVal) => {
+                    if (maybeVal === undefined) {
+                        wheres.push({ column: col, operator: '=', value: opOrVal });
+                    }
+                    else {
+                        wheres.push({ column: col, operator: opOrVal, value: maybeVal });
+                    }
+                    return recorder;
+                };
+            }
+            if (name === 'whereHas' || name === 'whereDoesntHave' || name === 'withWhereHas') {
+                return () => {
+                    throw new Error(`[RudderJS ORM] Nested ${name} inside a whereHas constrain callback is deferred to v2. ` +
+                        `Filter on flat columns inside the callback for now.`);
+                };
+            }
+            // All other chainable methods record nothing and return the recorder so
+            // `q.orderBy('x').limit(1)` chains through silently. Terminal methods
+            // (find/get/etc.) don't make sense in a constrain callback — they'd
+            // execute mid-build — but we don't intercept them here; they'd just
+            // return the recorder which then fails downstream. Keep the contract
+            // simple.
+            return () => recorder;
+        },
+    });
+    constrain(recorder);
+    return wheres;
+}
+/**
+ * Resolve the `belongsTo` relation declaration on `Self` that points at
+ * `ParentCtor`. When `relation` is given, looks it up directly. Otherwise
+ * scans `Self.relations` for a single `belongsTo` whose `model()` resolves
+ * to `ParentCtor` — throws on zero or multiple candidates.
+ */
+function _resolveBelongsToFor(Self, ParentCtor, relation) {
+    if (relation !== undefined) {
+        const def = Self.relations[relation];
+        if (!def)
+            throw new Error(`[RudderJS ORM] Relation "${relation}" is not defined on ${Self.name}.`);
+        if (def.type !== 'belongsTo') {
+            throw new Error(`[RudderJS ORM] Relation "${relation}" on ${Self.name} is "${def.type}", not "belongsTo".`);
+        }
+        return def;
+    }
+    const candidates = [];
+    for (const [name, def] of Object.entries(Self.relations)) {
+        if (def.type !== 'belongsTo')
+            continue;
+        const btDef = def;
+        if (btDef.model() === ParentCtor)
+            candidates.push([name, btDef]);
+    }
+    if (candidates.length === 0) {
+        throw new Error(`[RudderJS ORM] whereBelongsTo: ${Self.name} has no belongsTo relation pointing at ${ParentCtor.name}. ` +
+            `Pass a relation name explicitly.`);
+    }
+    if (candidates.length > 1) {
+        const names = candidates.map(([n]) => n).join(', ');
+        throw new Error(`[RudderJS ORM] whereBelongsTo: ${Self.name} has multiple belongsTo relations pointing at ${ParentCtor.name} (${names}). ` +
+            `Pass the relation name explicitly.`);
+    }
+    return candidates[0][1];
+}
+/**
+ * Build the {@link RelationExistencePredicate} for a relation declared on
+ * `Parent` by `relation` and dispatch it to the adapter via
+ * `q.whereRelationExists(predicate)`. Returns the same QueryBuilder for
+ * chaining (the adapter mutates in place).
+ *
+ * `morphTo` throws — the related table isn't statically known so a single
+ * EXISTS subquery can't represent it. Filter on the discriminator + id
+ * columns directly when you need that semantic.
+ */
+function _attachWhereHas(Parent, q, relation, exists, constrain) {
+    const def = Parent.relations[relation];
+    if (!def) {
+        throw new Error(`[RudderJS ORM] Relation "${relation}" is not defined on ${Parent.name}.`);
+    }
+    if (def.type === 'morphTo') {
+        throw new Error(`[RudderJS ORM] morphTo "${relation}" cannot be used with whereHas — the related table is dynamic. ` +
+            `Filter on ${def.morphName}Id / ${def.morphName}Type directly instead.`);
+    }
+    const constraintWheres = constrain ? _captureConstraintWheres(constrain) : [];
+    const predicate = _buildRelationPredicate(Parent, relation, def, exists, constraintWheres);
+    return q.whereRelationExists(predicate);
+}
+function _buildRelationPredicate(Parent, relation, def, exists, constraintWheres) {
+    const Related = def.model();
+    if (def.type === 'belongsToMany') {
+        const meta = _resolveBelongsToManyMeta(Parent, Related, def);
+        return {
+            relation,
+            exists,
+            relatedTable: Related.getTable(),
+            parentColumn: meta.parentKey,
+            relatedColumn: meta.relatedKey,
+            constraintWheres,
+            through: {
+                pivotTable: meta.pivotTable,
+                foreignPivotKey: meta.foreignPivotKey,
+                relatedPivotKey: meta.relatedPivotKey,
+            },
+        };
+    }
+    if (def.type === 'morphToMany') {
+        const meta = _resolveMorphToManyMeta(Parent, Related, def);
+        return {
+            relation,
+            exists,
+            relatedTable: Related.getTable(),
+            parentColumn: meta.parentKey,
+            relatedColumn: meta.relatedKey,
+            constraintWheres,
+            extraEquals: { [meta.morphTypeKey]: meta.morphTypeValue },
+            through: {
+                pivotTable: meta.pivotTable,
+                foreignPivotKey: meta.foreignPivotKey,
+                relatedPivotKey: meta.relatedPivotKey,
+            },
+        };
+    }
+    if (def.type === 'morphedByMany') {
+        const meta = _resolveMorphedByManyMeta(Parent, Related, def);
+        return {
+            relation,
+            exists,
+            relatedTable: Related.getTable(),
+            parentColumn: meta.parentKey,
+            relatedColumn: meta.relatedKey,
+            constraintWheres,
+            extraEquals: { [meta.morphTypeKey]: meta.morphTypeValue },
+            through: {
+                pivotTable: meta.pivotTable,
+                foreignPivotKey: meta.foreignPivotKey,
+                relatedPivotKey: meta.relatedPivotKey,
+            },
+        };
+    }
+    if (def.type === 'morphMany' || def.type === 'morphOne') {
+        const idCol = `${def.morphName}Id`;
+        const typeCol = `${def.morphName}Type`;
+        const localCol = def.localKey ?? Parent.primaryKey;
+        const typeVal = def.morphType ?? Parent.morphAlias ?? Parent.name;
+        return {
+            relation,
+            exists,
+            relatedTable: Related.getTable(),
+            parentColumn: localCol,
+            relatedColumn: idCol,
+            constraintWheres,
+            extraEquals: { [typeCol]: typeVal },
+        };
+    }
+    if (def.type === 'belongsTo') {
+        const fk = def.foreignKey ?? `${_camelHead(Related.name)}Id`;
+        const localCol = def.localKey ?? fk;
+        return {
+            relation,
+            exists,
+            relatedTable: Related.getTable(),
+            parentColumn: localCol,
+            relatedColumn: Related.primaryKey,
+            constraintWheres,
+        };
+    }
+    // hasOne / hasMany — related table holds the FK pointing back to Parent.
+    const fk = def.foreignKey ?? `${_camelHead(Parent.name)}Id`;
+    const localCol = def.localKey ?? Parent.primaryKey;
+    return {
+        relation,
+        exists,
+        relatedTable: Related.getTable(),
+        parentColumn: localCol,
+        relatedColumn: fk,
+        constraintWheres,
+    };
+}
+/**
+ * `withWhereHas` — run `whereHas` AND eager-load the relation under the
+ * same constraint when the adapter implements `withConstrained`. Adapters
+ * without it fall back to plain `with(relation)` (constraint applies only
+ * to the parent filter, not the eagerly loaded children).
+ */
+function _attachWithWhereHas(Parent, q, relation, constrain) {
+    const constraintWheres = constrain ? _captureConstraintWheres(constrain) : [];
+    // Reuse _attachWhereHas for the parent-side filter — it re-runs the
+    // constrain callback against a fresh recorder, so the WhereClause[] we
+    // capture above and the one captured inside _attachWhereHas come from
+    // distinct recorder instances. That's intentional: each captures the
+    // same constraint independently and neither is mutated by the adapter.
+    _attachWhereHas(Parent, q, relation, true, constrain);
+    const withConstrained = q.withConstrained;
+    if (constraintWheres.length > 0 && typeof withConstrained === 'function') {
+        return withConstrained.call(q, relation, constraintWheres);
+    }
+    return q.with(relation);
+}
+function _attachWhereBelongsTo(Self, q, parent, relation) {
+    const ParentCtor = parent.constructor;
+    const def = _resolveBelongsToFor(Self, ParentCtor, relation);
+    const Related = def.model();
+    const fk = def.foreignKey ?? `${_camelHead(Related.name)}Id`;
+    const localCol = def.localKey ?? fk;
+    const parentVal = parent[ParentCtor.primaryKey];
+    if (parentVal === undefined || parentVal === null) {
+        throw new Error(`[RudderJS ORM] whereBelongsTo: parent.${ParentCtor.primaryKey} is unset on ${ParentCtor.name}.`);
+    }
+    return q.where(localCol, parentVal);
+}
 const _CHAIN_METHODS = new Set([
     'where', 'orWhere', 'orderBy', 'limit', 'offset', 'with', 'withTrashed', 'onlyTrashed',
 ]);
@@ -1254,21 +1972,7 @@ function _replayChain(q, recorded) {
     }
     return cur;
 }
-function _belongsToManyDeferredQb(Related, _def, meta, parentVal) {
-    const recorded = [];
-    const buildResolved = async () => {
-        const adapter = ModelRegistry.getAdapter();
-        const pivotRows = await adapter
-            .query(meta.pivotTable)
-            .where(meta.foreignPivotKey, parentVal)
-            .get();
-        const ids = pivotRows.map(r => r[meta.relatedPivotKey]);
-        // Empty IN list — short-circuit with a guaranteed-empty query so
-        // adapters don't have to handle the edge case.
-        const q = Related.query()
-            .where(meta.relatedKey, 'IN', ids.length === 0 ? [] : ids);
-        return _replayChain(q, recorded);
-    };
+function _makeDeferredProxy(buildResolved, recorded, relationKind) {
     const proxy = new Proxy({}, {
         get(_t, prop) {
             const name = String(prop);
@@ -1287,8 +1991,8 @@ function _belongsToManyDeferredQb(Related, _def, meta, parentVal) {
             }
             if (_UNSUPPORTED_TERMINALS.has(name)) {
                 return () => {
-                    throw new Error(`[RudderJS ORM] "${name}" is not supported on a belongsToMany lazy-fetch query. ` +
-                        `Use Model.belongsToMany(parent, name) for pivot mutations or call methods on the related Model directly.`);
+                    throw new Error(`[RudderJS ORM] "${name}" is not supported on a ${relationKind} lazy-fetch query. ` +
+                        `Use Model.${relationKind}(parent, name) for pivot mutations or call methods on the related Model directly.`);
                 };
             }
             return undefined;
@@ -1296,6 +2000,55 @@ function _belongsToManyDeferredQb(Related, _def, meta, parentVal) {
     });
     return proxy;
 }
+function _belongsToManyDeferredQb(Related, _def, meta, parentVal) {
+    const recorded = [];
+    const buildResolved = async () => {
+        const adapter = ModelRegistry.getAdapter();
+        const pivotRows = await adapter
+            .query(meta.pivotTable)
+            .where(meta.foreignPivotKey, parentVal)
+            .get();
+        const ids = pivotRows.map(r => r[meta.relatedPivotKey]);
+        // Empty IN list — short-circuit with a guaranteed-empty query so
+        // adapters don't have to handle the edge case.
+        const q = Related.query()
+            .where(meta.relatedKey, 'IN', ids.length === 0 ? [] : ids);
+        return _replayChain(q, recorded);
+    };
+    return _makeDeferredProxy(buildResolved, recorded, 'belongsToMany');
+}
+function _morphToManyDeferredQb(Related, _def, meta, parentVal) {
+    const recorded = [];
+    const buildResolved = async () => {
+        const adapter = ModelRegistry.getAdapter();
+        const pivotRows = await adapter
+            .query(meta.pivotTable)
+            .where(meta.foreignPivotKey, parentVal)
+            .where(meta.morphTypeKey, meta.morphTypeValue)
+            .get();
+        const ids = pivotRows.map(r => r[meta.relatedPivotKey]);
+        const q = Related.query()
+            .where(meta.relatedKey, 'IN', ids.length === 0 ? [] : ids);
+        return _replayChain(q, recorded);
+    };
+    return _makeDeferredProxy(buildResolved, recorded, 'morphToMany');
+}
+function _morphedByManyDeferredQb(Related, _def, meta, parentVal) {
+    const recorded = [];
+    const buildResolved = async () => {
+        const adapter = ModelRegistry.getAdapter();
+        const pivotRows = await adapter
+            .query(meta.pivotTable)
+            .where(meta.foreignPivotKey, parentVal)
+            .where(meta.morphTypeKey, meta.morphTypeValue)
+            .get();
+        const ids = pivotRows.map(r => r[meta.relatedPivotKey]);
+        const q = Related.query()
+            .where(meta.relatedKey, 'IN', ids.length === 0 ? [] : ids);
+        return _replayChain(q, recorded);
+    };
+    return _makeDeferredProxy(buildResolved, recorded, 'morphedByMany');
+}
 function _normalizeAttachInput(input, foreignPivotKey, parentVal, relatedPivotKey, flatPivot) {
     const rows = [];
     if (Array.isArray(input)) {
@@ -1409,6 +2162,159 @@ function _installBelongsToManyMethods(ModelClass) {
         });
     }
 }
+function _makeMorphToManyAccessor(Parent, Related, def, parentVal) {
+    const meta = _resolveMorphToManyMeta(Parent, Related, def);
+    return {
+        async attach(input, flatPivot) {
+            const ids = _idsFromAttachInput(input);
+            if (ids.length === 0)
+                return;
+            const rows = _normalizeAttachInput(input, meta.foreignPivotKey, parentVal, meta.relatedPivotKey, flatPivot)
+                .map(r => ({ ...r, [meta.morphTypeKey]: meta.morphTypeValue }));
+            await ModelRegistry.getAdapter()
+                .query(meta.pivotTable)
+                .insertMany(rows);
+        },
+        async detach(ids) {
+            const adapter = ModelRegistry.getAdapter();
+            let q = adapter
+                .query(meta.pivotTable)
+                .where(meta.foreignPivotKey, parentVal)
+                .where(meta.morphTypeKey, meta.morphTypeValue);
+            if (ids !== undefined) {
+                if (ids.length === 0)
+                    return 0;
+                q = q.where(meta.relatedPivotKey, 'IN', [...ids]);
+            }
+            return q.deleteAll();
+        },
+        async sync(desiredIds, flatPivot) {
+            const adapter = ModelRegistry.getAdapter();
+            const currentRows = await adapter
+                .query(meta.pivotTable)
+                .where(meta.foreignPivotKey, parentVal)
+                .where(meta.morphTypeKey, meta.morphTypeValue)
+                .get();
+            const current = new Set(currentRows.map(r => r[meta.relatedPivotKey]));
+            const desired = new Set(desiredIds);
+            const attached = [];
+            const detached = [];
+            for (const id of desired)
+                if (!current.has(id))
+                    attached.push(id);
+            for (const id of current)
+                if (!desired.has(id))
+                    detached.push(id);
+            if (attached.length > 0) {
+                const rows = attached.map(id => ({
+                    ...(flatPivot ?? {}),
+                    [meta.foreignPivotKey]: parentVal,
+                    [meta.relatedPivotKey]: id,
+                    [meta.morphTypeKey]: meta.morphTypeValue,
+                }));
+                await adapter.query(meta.pivotTable).insertMany(rows);
+            }
+            if (detached.length > 0) {
+                await adapter
+                    .query(meta.pivotTable)
+                    .where(meta.foreignPivotKey, parentVal)
+                    .where(meta.morphTypeKey, meta.morphTypeValue)
+                    .where(meta.relatedPivotKey, 'IN', detached)
+                    .deleteAll();
+            }
+            return { attached, detached };
+        },
+    };
+}
+function _makeMorphedByManyAccessor(Parent, Related, def, parentVal) {
+    const meta = _resolveMorphedByManyMeta(Parent, Related, def);
+    return {
+        async attach(input, flatPivot) {
+            const ids = _idsFromAttachInput(input);
+            if (ids.length === 0)
+                return;
+            // Parent is the strong side, related is the polymorphic side. Each row
+            // carries: parent FK, related FK, related-class discriminator.
+            const rows = _normalizeAttachInput(input, meta.foreignPivotKey, parentVal, meta.relatedPivotKey, flatPivot)
+                .map(r => ({ ...r, [meta.morphTypeKey]: meta.morphTypeValue }));
+            await ModelRegistry.getAdapter()
+                .query(meta.pivotTable)
+                .insertMany(rows);
+        },
+        async detach(ids) {
+            const adapter = ModelRegistry.getAdapter();
+            let q = adapter
+                .query(meta.pivotTable)
+                .where(meta.foreignPivotKey, parentVal)
+                .where(meta.morphTypeKey, meta.morphTypeValue);
+            if (ids !== undefined) {
+                if (ids.length === 0)
+                    return 0;
+                q = q.where(meta.relatedPivotKey, 'IN', [...ids]);
+            }
+            return q.deleteAll();
+        },
+        async sync(desiredIds, flatPivot) {
+            const adapter = ModelRegistry.getAdapter();
+            const currentRows = await adapter
+                .query(meta.pivotTable)
+                .where(meta.foreignPivotKey, parentVal)
+                .where(meta.morphTypeKey, meta.morphTypeValue)
+                .get();
+            const current = new Set(currentRows.map(r => r[meta.relatedPivotKey]));
+            const desired = new Set(desiredIds);
+            const attached = [];
+            const detached = [];
+            for (const id of desired)
+                if (!current.has(id))
+                    attached.push(id);
+            for (const id of current)
+                if (!desired.has(id))
+                    detached.push(id);
+            if (attached.length > 0) {
+                const rows = attached.map(id => ({
+                    ...(flatPivot ?? {}),
+                    [meta.foreignPivotKey]: parentVal,
+                    [meta.relatedPivotKey]: id,
+                    [meta.morphTypeKey]: meta.morphTypeValue,
+                }));
+                await adapter.query(meta.pivotTable).insertMany(rows);
+            }
+            if (detached.length > 0) {
+                await adapter
+                    .query(meta.pivotTable)
+                    .where(meta.foreignPivotKey, parentVal)
+                    .where(meta.morphTypeKey, meta.morphTypeValue)
+                    .where(meta.relatedPivotKey, 'IN', detached)
+                    .deleteAll();
+            }
+            return { attached, detached };
+        },
+    };
+}
+/**
+ * Install per-relation prototype methods for every `morphToMany` /
+ * `morphedByMany` entry. Same idempotent shape as
+ * {@link _installBelongsToManyMethods}.
+ */
+function _installMorphPivotMethods(ModelClass) {
+    for (const [name, def] of Object.entries(ModelClass.relations)) {
+        if (def.type !== 'morphToMany' && def.type !== 'morphedByMany')
+            continue;
+        if (Object.prototype.hasOwnProperty.call(ModelClass.prototype, name))
+            continue;
+        const isOwning = def.type === 'morphToMany';
+        Object.defineProperty(ModelClass.prototype, name, {
+            configurable: true,
+            writable: true,
+            value() {
+                return isOwning
+                    ? Model.morphToMany(this, name)
+                    : Model.morphedByMany(this, name);
+            },
+        });
+    }
+}
 // ─── Compile-time contract check ───────────────────────────
 // Asserts that `Model`'s static surface conforms to the `ModelLike`
 // contract from `@rudderjs/contracts`. Downstream tools (admin panels