@bunyad/orm 0.2.0-beta.0 → 0.2.0-beta.2

package/dist/relations.js

@@ -5,7 +5,9 @@ import { wrapSqlName } from "@bunyad/database";
 import { OrmCollection } from "./orm-collection.js";
 import { softDeleteAliasSql, nowForConnection, } from "./model-helpers.js";
 import { Model } from "./model.js";
+import { hasGlobalScopes } from "./scopes.js";
 import { isIgnoringTouch } from "./model-strictness.js";
+import { fireModelEvent, hasAnyModelEventListeners } from "./model-events.js";
 /** Register morph type aliases (`Relation::morphMap`). */
 const morphAliases = new Map();
 /** ModelQuery methods that mutate the builder and return it — forwarded onto relations. */
@@ -94,8 +96,12 @@ function installRelationQueryForwarders(ctors, writes = []) {
         }
     }
 }
-/** Strip `__pivot_*` columns onto `model.pivot`. */
-export function applyPivotAttributes(model, attrs, pivotKeys) {
+/**
+ * Strip `__pivot_*` columns onto `model.pivot` (or the `as()` accessor). With
+ * `using(PivotModel)` the pivot is an instance of that model, so its casts and
+ * methods apply.
+ */
+export function applyPivotAttributes(model, attrs, pivotKeys, options = {}) {
     if (pivotKeys.length === 0)
         return model;
     const pivot = {};
@@ -112,7 +118,15 @@ export function applyPivotAttributes(model, attrs, pivotKeys) {
         }
     }
     if (Object.keys(pivot).length > 0) {
-        self.pivot = pivot;
+        const accessor = options.accessor ?? "pivot";
+        if (options.pivotClass) {
+            const instance = new options.pivotClass(pivot);
+            instance.exists = true;
+            self[accessor] = instance;
+        }
+        else {
+            self[accessor] = pivot;
+        }
     }
     return model;
 }
@@ -124,26 +138,82 @@ function pivotSelectKeys(foreignPivotKey, relatedPivotKey, extra) {
     }
     return keys;
 }
-export function morphMap(map) {
-    for (const [alias, cls] of Object.entries(map)) {
-        morphAliases.set(alias, cls);
+/** Classes seen by the ORM (booted or used as a morph target), keyed by class name — fallback for unmapped types. */
+const knownClasses = new Map();
+let morphMapRequired = false;
+/** Class names used by two different model classes — never resolved by name alone. */
+const ambiguousClassNames = new Set();
+export function registerMorphClass(model) {
+    if (!model.name)
+        return;
+    const existing = knownClasses.get(model.name);
+    if (!existing)
+        knownClasses.set(model.name, model);
+    else if (existing !== model)
+        ambiguousClassNames.add(model.name);
+}
+export function morphMap(map, merge = true) {
+    if (map) {
+        if (!merge)
+            morphAliases.clear();
+        for (const [alias, cls] of Object.entries(map)) {
+            morphAliases.set(alias, cls);
+        }
     }
+    return Object.fromEntries(morphAliases);
+}
+/** `Relation::enforceMorphMap` — register the map and refuse unmapped classes. */
+export function enforceMorphMap(map, merge = true) {
+    requireMorphMap();
+    return morphMap(map, merge);
+}
+/** `Relation::requireMorphMap` — throw when a model without an alias is used polymorphically. */
+export function requireMorphMap(required = true) {
+    morphMapRequired = required;
+}
+export function requiresMorphMap() {
+    return morphMapRequired;
 }
 export function clearMorphMap() {
     morphAliases.clear();
+    morphMapRequired = false;
 }
 export function morphTypeFor(model) {
     for (const [alias, cls] of morphAliases) {
         if (cls === model)
             return alias;
     }
+    if (morphMapRequired) {
+        throw new Error(`No morph map defined for [${model.name}]. Add it to morphMap()/enforceMorphMap() before using it in a polymorphic relation.`);
+    }
+    registerMorphClass(model);
     return model.name;
 }
-export function resolveMorphType(type) {
+/** `Relation::getMorphedModel` — class for an alias, or undefined. */
+export function getMorphedModel(type) {
     const mapped = morphAliases.get(type);
     if (mapped)
         return mapped;
-    throw new Error(`No morph map entry for [${type}]. Call morphMap({ ${type}: Model }) first.`);
+    if (morphMapRequired || ambiguousClassNames.has(type))
+        return undefined;
+    return knownClasses.get(type);
+}
+export function resolveMorphType(type) {
+    const mapped = getMorphedModel(type);
+    if (mapped)
+        return mapped;
+    const hint = ambiguousClassNames.has(type)
+        ? ` Two model classes are named [${type}], so it cannot be resolved by name.`
+        : "";
+    throw new Error(`No morph map entry for [${type}].${hint} Call morphMap({ ${type}: Model }) first.`);
+}
+function buildDefault(Related, spec, parent, keys = {}) {
+    const model = new Related({ ...keys });
+    if (typeof spec === "function")
+        spec(model, parent);
+    else if (spec !== true)
+        Object.assign(model, spec);
+    return model;
 }
 /** MorphMany relation. */
 export class MorphMany {
@@ -154,6 +224,7 @@ export class MorphMany {
     morphType;
     localKey;
     #baseQuery = null;
+    #inverse;
     constructor(parent, related, typeColumn, idColumn, morphType, localKey) {
         this.parent = parent;
         this.related = related;
@@ -182,6 +253,30 @@ export class MorphMany {
         return this.parent[parentKey];
     }
     /** Constrained related query (`morphMany().where(…).get()`). */
+    /**
+     * `chaperone($inverse)` — set the parent on every loaded child (`post.user` without a query).
+     * The inverse name defaults to the parent class name in camelCase.
+     */
+    chaperone(inverse) {
+        this.#inverse = inverse ?? true;
+        return this;
+    }
+    /** Property the parent is set on, or `undefined` when `chaperone()` was not called. */
+    getInverse() {
+        if (this.#inverse === undefined)
+            return undefined;
+        if (typeof this.#inverse === "string")
+            return this.#inverse;
+        const name = this.parent.constructor.name;
+        return name.charAt(0).toLowerCase() + name.slice(1);
+    }
+    #hydrateInverse(rows) {
+        const inverse = this.getInverse();
+        if (inverse === undefined)
+            return;
+        for (const row of rows)
+            setInverse(row, inverse, this.parent);
+    }
     getQuery() {
         if (!this.#baseQuery) {
             this.#baseQuery = this.related
@@ -192,10 +287,15 @@ export class MorphMany {
     }
     async get() {
         const rows = await this.getQuery().get();
-        return new OrmCollection(rows.all(), { owned: true });
+        const models = rows.all();
+        this.#hydrateInverse(models);
+        return new OrmCollection(models, { owned: true });
     }
     async first() {
-        return this.getQuery().first();
+        const row = (await this.getQuery().first());
+        if (row)
+            this.#hydrateInverse([row]);
+        return row;
     }
     async create(attributes) {
         return this.related.create({
@@ -216,6 +316,7 @@ export class MorphOne {
     #ofManyColumn;
     #ofManyAggregate;
     #baseQuery = null;
+    #default;
     constructor(parent, related, typeColumn, idColumn, morphType, localKey) {
         this.parent = parent;
         this.related = related;
@@ -266,6 +367,18 @@ export class MorphOne {
         this.#ofManyAggregate = aggregate;
         return this;
     }
+    /** `withDefault` — return an empty related model instead of `null` when nothing matches. */
+    withDefault(spec = true) {
+        this.#default = spec;
+        return this;
+    }
+    hasDefault() {
+        return this.#default !== undefined;
+    }
+    /** The default model for the owner this relation was built from. */
+    makeDefault() {
+        return buildDefault(this.related, this.#default ?? true, this.parent, { [this.idColumn]: this.parent[this.getLocalKeyName()], [this.typeColumn]: this.morphType });
+    }
     getQuery() {
         if (!this.#baseQuery) {
             let q = this.related
@@ -289,6 +402,10 @@ export class MorphOne {
         return this.first();
     }
     async first() {
+        const found = await this.#firstRow();
+        return found ?? (this.#default !== undefined ? this.makeDefault() : null);
+    }
+    async #firstRow() {
         return this.getQuery().first();
     }
     async create(attributes) {
@@ -359,6 +476,7 @@ export class HasMany {
     foreignKey;
     localKey;
     #baseQuery = null;
+    #inverse;
     constructor(parent, related, foreignKey, localKey) {
         this.parent = parent;
         this.related = related;
@@ -379,6 +497,30 @@ export class HasMany {
         return this.parent[parentKey];
     }
     /** Constrained related query (`hasMany().where(…).orderBy(…).get()`). */
+    /**
+     * `chaperone($inverse)` — set the parent on every loaded child (`post.user` without a query).
+     * The inverse name defaults to the parent class name in camelCase.
+     */
+    chaperone(inverse) {
+        this.#inverse = inverse ?? true;
+        return this;
+    }
+    /** Property the parent is set on, or `undefined` when `chaperone()` was not called. */
+    getInverse() {
+        if (this.#inverse === undefined)
+            return undefined;
+        if (typeof this.#inverse === "string")
+            return this.#inverse;
+        const name = this.parent.constructor.name;
+        return name.charAt(0).toLowerCase() + name.slice(1);
+    }
+    #hydrateInverse(rows) {
+        const inverse = this.getInverse();
+        if (inverse === undefined)
+            return;
+        for (const row of rows)
+            setInverse(row, inverse, this.parent);
+    }
     getQuery() {
         if (!this.#baseQuery) {
             this.#baseQuery = this.related.where(this.foreignKey, this.#parentId());
@@ -387,10 +529,15 @@ export class HasMany {
     }
     async get() {
         const rows = await this.getQuery().get();
-        return new OrmCollection(rows.all(), { owned: true });
+        const models = rows.all();
+        this.#hydrateInverse(models);
+        return new OrmCollection(models, { owned: true });
     }
     async first() {
-        return this.getQuery().first();
+        const row = (await this.getQuery().first());
+        if (row)
+            this.#hydrateInverse([row]);
+        return row;
     }
     async create(attributes) {
         return this.related.create({
@@ -424,6 +571,8 @@ export class HasOne {
     #ofManyColumn;
     #ofManyAggregate;
     #baseQuery = null;
+    #inverse;
+    #default;
     constructor(parent, related, foreignKey, localKey) {
         this.parent = parent;
         this.related = related;
@@ -469,6 +618,42 @@ export class HasOne {
         this.#ofManyAggregate = aggregate;
         return this;
     }
+    /** `withDefault` — return an empty related model instead of `null` when nothing matches. */
+    withDefault(spec = true) {
+        this.#default = spec;
+        return this;
+    }
+    hasDefault() {
+        return this.#default !== undefined;
+    }
+    /** The default model for the owner this relation was built from. */
+    makeDefault() {
+        return buildDefault(this.related, this.#default ?? true, this.parent, { [this.foreignKey]: this.parent[this.getLocalKeyName()] });
+    }
+    /**
+     * `chaperone($inverse)` — set the parent on every loaded child (`post.user` without a query).
+     * The inverse name defaults to the parent class name in camelCase.
+     */
+    chaperone(inverse) {
+        this.#inverse = inverse ?? true;
+        return this;
+    }
+    /** Property the parent is set on, or `undefined` when `chaperone()` was not called. */
+    getInverse() {
+        if (this.#inverse === undefined)
+            return undefined;
+        if (typeof this.#inverse === "string")
+            return this.#inverse;
+        const name = this.parent.constructor.name;
+        return name.charAt(0).toLowerCase() + name.slice(1);
+    }
+    #hydrateInverse(rows) {
+        const inverse = this.getInverse();
+        if (inverse === undefined)
+            return;
+        for (const row of rows)
+            setInverse(row, inverse, this.parent);
+    }
     getQuery() {
         if (!this.#baseQuery) {
             let q = this.related.where(this.foreignKey, this.#parentId());
@@ -489,6 +674,16 @@ export class HasOne {
         return this.first();
     }
     async first() {
+        const found = await this.#firstRow();
+        return found ?? (this.#default !== undefined ? this.makeDefault() : null);
+    }
+    async #firstRow() {
+        const row = await this.#firstRowRaw();
+        if (row)
+            this.#hydrateInverse([row]);
+        return row;
+    }
+    async #firstRowRaw() {
         return this.getQuery().first();
     }
     async create(attributes) {
@@ -626,6 +821,7 @@ export class BelongsTo {
     foreignKey;
     ownerKey;
     #baseQuery = null;
+    #default;
     constructor(child, related, foreignKey, ownerKey) {
         this.child = child;
         this.related = related;
@@ -641,6 +837,18 @@ export class BelongsTo {
     getOwnerKeyName() {
         return this.ownerKey ?? this.related.primaryKey;
     }
+    /** `withDefault` — return an empty related model instead of `null` when nothing matches. */
+    withDefault(spec = true) {
+        this.#default = spec;
+        return this;
+    }
+    hasDefault() {
+        return this.#default !== undefined;
+    }
+    /** The default model for the owner this relation was built from. */
+    makeDefault() {
+        return buildDefault(this.related, this.#default ?? true, this.child, {});
+    }
     getQuery() {
         if (!this.#baseQuery) {
             const id = this.child[this.foreignKey];
@@ -659,6 +867,10 @@ export class BelongsTo {
         return this.first();
     }
     async first() {
+        const found = await this.#firstRow();
+        return found ?? (this.#default !== undefined ? this.makeDefault() : null);
+    }
+    async #firstRow() {
         return this.getQuery().first();
     }
     /** Set the foreign key from a related model (or null). */
@@ -715,6 +927,97 @@ export class BelongsTo {
     }
 }
 /** BelongsToMany relation. */
+/**
+ * Point `child[inverse]` at its parent without making it enumerable: a back-reference
+ * must not be serialized (`toJSON`) or treated as an attribute, or parent → child → parent recurses.
+ */
+export function setInverse(child, inverse, parent) {
+    Object.defineProperty(child, inverse, {
+        value: parent,
+        enumerable: false,
+        writable: true,
+        configurable: true,
+    });
+}
+/** Apply pivot wheres to a ModelQuery / QueryBuilder, qualified with the pivot table. */
+export function applyPivotWheres(q, pivotTable, wheres) {
+    const t = q;
+    for (const w of wheres) {
+        const col = `${pivotTable}.${w.column}`;
+        if (w.kind === "basic")
+            t.where(col, w.op, w.value);
+        else if (w.kind === "in")
+            (w.not ? t.whereNotIn(col, w.values) : t.whereIn(col, w.values));
+        else if (w.kind === "null")
+            (w.not ? t.whereNotNull(col) : t.whereNull(col));
+        else
+            (w.not ? t.whereNotBetween(col, w.values) : t.whereBetween(col, w.values));
+    }
+}
+/** Raw SQL for pivot wheres (` AND "col" = ?`), for the pivot-only queries (sync / detach / update). */
+function pivotWhereSql(dialect, wheres) {
+    let sql = "";
+    const params = [];
+    for (const w of wheres) {
+        const col = wrapSqlName(dialect, w.column);
+        if (w.kind === "basic") {
+            sql += ` AND ${col} ${w.op} ?`;
+            params.push(w.value);
+        }
+        else if (w.kind === "in") {
+            if (w.values.length === 0) {
+                sql += w.not ? "" : " AND 1 = 0";
+            }
+            else {
+                sql += ` AND ${col} ${w.not ? "NOT IN" : "IN"} (${w.values.map(() => "?").join(", ")})`;
+                params.push(...w.values);
+            }
+        }
+        else if (w.kind === "null") {
+            sql += ` AND ${col} IS ${w.not ? "NOT " : ""}NULL`;
+        }
+        else {
+            sql += ` AND ${col} ${w.not ? "NOT BETWEEN" : "BETWEEN"} ? AND ?`;
+            params.push(w.values[0], w.values[1]);
+        }
+    }
+    return { sql, params };
+}
+/** Multi-row INSERT into a pivot table, grouped by column set and chunked under parameter limits. */
+async function insertPivotRows(conn, table, rows) {
+    if (rows.length === 0)
+        return;
+    const d = conn.dialect;
+    const groups = new Map();
+    for (const row of rows) {
+        const cols = Object.keys(row).sort().join("\u0000");
+        const group = groups.get(cols);
+        if (group)
+            group.push(row);
+        else
+            groups.set(cols, [row]);
+    }
+    for (const [colKey, group] of groups) {
+        const cols = colKey.split("\u0000");
+        const colSql = cols.map((c) => wrapSqlName(d, c)).join(", ");
+        const rowSql = `(${cols.map(() => "?").join(", ")})`;
+        const perChunk = Math.max(1, Math.floor(900 / cols.length));
+        for (let i = 0; i < group.length; i += perChunk) {
+            const chunk = group.slice(i, i + perChunk);
+            await conn.run(`INSERT INTO ${wrapSqlName(d, table)} (${colSql}) VALUES ${chunk.map(() => rowSql).join(", ")}`, chunk.flatMap((row) => cols.map((c) => row[c])));
+        }
+    }
+}
+/** Chunked `DELETE … WHERE fk = ? AND col IN (…)`; returns deleted row count. */
+async function deletePivotIn(conn, sqlBase, baseParams, inColumn, ids) {
+    const d = conn.dialect;
+    let deleted = 0;
+    for (let i = 0; i < ids.length; i += 800) {
+        const chunk = ids.slice(i, i + 800);
+        deleted += Number((await conn.run(`${sqlBase} AND ${wrapSqlName(d, inColumn)} IN (${chunk.map(() => "?").join(", ")})`, [...baseParams, ...chunk])) ?? 0);
+    }
+    return deleted;
+}
 export class BelongsToMany {
     parent;
     related;
@@ -723,6 +1026,11 @@ export class BelongsToMany {
     relatedPivotKey;
     #baseQuery = null;
     #pivotColumns = [];
+    #pivotWheres = [];
+    #pivotOrders = [];
+    #pivotTimestamps = false;
+    #pivotAccessor = "pivot";
+    #pivotClass;
     constructor(parent, related, pivotTable, foreignPivotKey, relatedPivotKey) {
         this.parent = parent;
         this.related = related;
@@ -760,7 +1068,7 @@ export class BelongsToMany {
         return this.parent[parentKey];
     }
     #pivotKeys() {
-        if (this.#pivotColumns.length === 0)
+        if (this.#pivotColumns.length === 0 && !this.#pivotClass && this.#pivotAccessor === "pivot")
             return [];
         return pivotSelectKeys(this.foreignPivotKey, this.relatedPivotKey, this.#pivotColumns);
     }
@@ -772,6 +1080,10 @@ export class BelongsToMany {
                 .join(this.pivotTable, `${this.pivotTable}.${this.relatedPivotKey}`, "=", `${related.table}.${related.primaryKey}`)
                 .where(`${this.pivotTable}.${this.foreignPivotKey}`, this.#parentId())
                 .select(`${related.table}.*`);
+            applyPivotWheres(q, this.pivotTable, this.#pivotWheres);
+            for (const o of this.#pivotOrders) {
+                q = q.orderBy(`${this.pivotTable}.${o.column}`, o.direction);
+            }
             for (const col of this.#pivotKeys()) {
                 q = q.selectRaw(`${this.pivotTable}.${col} as __pivot_${col}`);
             }
@@ -784,7 +1096,7 @@ export class BelongsToMany {
         if (keys.length === 0)
             return;
         for (const model of models) {
-            applyPivotAttributes(model, model, keys);
+            applyPivotAttributes(model, model, keys, { accessor: this.#pivotAccessor, pivotClass: this.#pivotClass });
         }
     }
     async get() {
@@ -799,52 +1111,299 @@ export class BelongsToMany {
             this.#hydratePivot([model]);
         return model;
     }
-    async attach(ids) {
-        const list = Array.isArray(ids) ? ids : [ids];
-        const parent = this.parent.constructor;
-        for (const id of list) {
-            await parent.getConnection().run(`INSERT INTO ${this.pivotTable} (${this.foreignPivotKey}, ${this.relatedPivotKey}) VALUES (?, ?)`, [this.#parentId(), id]);
+    /** `withTimestamps` — stamp `created_at` / `updated_at` on pivot writes. */
+    withTimestamps() {
+        this.#baseQuery = null;
+        this.#pivotTimestamps = true;
+        // The timestamp columns are also read onto the pivot.
+        for (const col of ["created_at", "updated_at"]) {
+            if (!this.#pivotColumns.includes(col))
+                this.#pivotColumns.push(col);
+        }
+        return this;
+    }
+    /** `as('membership')` — expose the pivot under another property name than `pivot`. */
+    as(accessor) {
+        this.#pivotAccessor = accessor;
+        return this;
+    }
+    /**
+     * `using(MembershipPivot)` — hydrate the pivot as a model (casts and methods apply)
+     * and run pivot writes (`attach`, `sync`, `updateExistingPivot`) through its "set" casts.
+     */
+    using(pivotClass) {
+        this.#baseQuery = null;
+        this.#pivotClass = pivotClass;
+        return this;
+    }
+    getPivotAccessor() {
+        return this.#pivotAccessor;
+    }
+    getPivotClass() {
+        return this.#pivotClass;
+    }
+    /** Pivot attributes for a write, passed through the custom pivot model's set-casts. */
+    #castPivotWrite(attrs) {
+        return this.#pivotClass ? this.#pivotClass.castAttributes(attrs, "set") : attrs;
+    }
+    /** True when the custom pivot model has listeners, so pivot writes must fire its events. */
+    #pivotEvents() {
+        return this.#pivotClass !== undefined && hasAnyModelEventListeners(this.#pivotClass);
+    }
+    #pivotInstance(attrs, exists) {
+        const instance = new this.#pivotClass();
+        instance.forceFill(attrs);
+        if (exists) {
+            instance.syncOriginal();
+            instance.exists = true;
+        }
+        return instance;
+    }
+    getPivotWheres() {
+        return [...this.#pivotWheres];
+    }
+    getPivotOrders() {
+        return [...this.#pivotOrders];
+    }
+    #addPivotWhere(where) {
+        this.#baseQuery = null;
+        this.#pivotWheres.push(where);
+        return this;
+    }
+    wherePivot(column, opOrValue, value) {
+        return value === undefined
+            ? this.#addPivotWhere({ kind: "basic", column, op: "=", value: opOrValue })
+            : this.#addPivotWhere({ kind: "basic", column, op: String(opOrValue), value });
+    }
+    wherePivotIn(column, values) {
+        return this.#addPivotWhere({ kind: "in", column, values, not: false });
+    }
+    wherePivotNotIn(column, values) {
+        return this.#addPivotWhere({ kind: "in", column, values, not: true });
+    }
+    wherePivotNull(column) {
+        return this.#addPivotWhere({ kind: "null", column, not: false });
+    }
+    wherePivotNotNull(column) {
+        return this.#addPivotWhere({ kind: "null", column, not: true });
+    }
+    wherePivotBetween(column, values) {
+        return this.#addPivotWhere({ kind: "between", column, values, not: false });
+    }
+    wherePivotNotBetween(column, values) {
+        return this.#addPivotWhere({ kind: "between", column, values, not: true });
+    }
+    /** `orderByPivot` — order related rows by a pivot column. */
+    orderByPivot(column, direction = "asc") {
+        this.#baseQuery = null;
+        this.#pivotOrders.push({ column, direction });
+        return this;
+    }
+    #conn() {
+        return this.parent.constructor.getConnection();
+    }
+    /** Normalize `1`, `[1, 2]` or `{ 1: { role: "x" } }` into `[id, attributes]` pairs. */
+    #normalize(ids, attributes = {}) {
+        if (ids instanceof Model) {
+            return [[ids[this.related.primaryKey], attributes]];
+        }
+        if (Array.isArray(ids)) {
+            return ids.map((id) => [
+                id instanceof Model
+                    ? id[this.related.primaryKey]
+                    : id,
+                attributes,
+            ]);
+        }
+        if (ids !== null && typeof ids === "object") {
+            return Object.entries(ids).map(([id, attrs]) => [id, { ...attributes, ...attrs }]);
+        }
+        return [[ids, attributes]];
+    }
+    #stamp(row, created) {
+        if (!this.#pivotTimestamps)
+            return row;
+        const now = nowForConnection(this.#conn());
+        if (created && row.created_at === undefined)
+            row.created_at = now;
+        if (row.updated_at === undefined)
+            row.updated_at = now;
+        return row;
+    }
+    async #currentIds() {
+        const d = this.#conn().dialect;
+        const pw = pivotWhereSql(d, this.#pivotWheres);
+        const rows = await this.#conn().all(`SELECT ${wrapSqlName(d, this.relatedPivotKey)} AS id FROM ${wrapSqlName(d, this.pivotTable)} WHERE ${wrapSqlName(d, this.foreignPivotKey)} = ?${pw.sql}`, [this.#parentId(), ...pw.params]);
+        return new Set(rows.map((r) => String(r.id)));
+    }
+    /** `attach` — one multi-row INSERT per chunk; optional pivot attributes. */
+    async attach(ids, attributes = {}) {
+        const pairs = this.#normalize(ids, attributes);
+        if (pairs.length === 0)
+            return;
+        const d = this.#conn().dialect;
+        const parentId = this.#parentId();
+        // `wherePivot(col, value)` equality constraints become defaults for new pivot rows.
+        const defaults = {};
+        for (const w of this.#pivotWheres) {
+            if (w.kind === "basic" && w.op === "=")
+                defaults[w.column] = w.value;
+        }
+        const rows = pairs.map(([id, attrs]) => this.#castPivotWrite(this.#stamp({ ...defaults, ...attrs, [this.foreignPivotKey]: parentId, [this.relatedPivotKey]: id }, true)));
+        if (!this.#pivotEvents()) {
+            await insertPivotRows(this.#conn(), this.pivotTable, rows);
+            return;
+        }
+        // Custom pivot model with listeners: `saving` / `creating` may change or cancel each row.
+        const pending = [];
+        for (const row of rows) {
+            const pivot = this.#pivotInstance(row, false);
+            if ((await fireModelEvent(pivot, "saving")) === false)
+                continue;
+            if ((await fireModelEvent(pivot, "creating")) === false)
+                continue;
+            pending.push([pivot, pivot.getAttributes()]);
+        }
+        if (pending.length === 0)
+            return;
+        await insertPivotRows(this.#conn(), this.pivotTable, pending.map(([, attrs]) => attrs));
+        for (const [pivot] of pending) {
+            pivot.exists = true;
+            await fireModelEvent(pivot, "created");
+            await fireModelEvent(pivot, "saved");
         }
     }
+    /** `detach` — returns the number of deleted pivot rows. */
     async detach(ids) {
-        const parent = this.parent.constructor;
+        if (this.#pivotEvents())
+            return this.#detachWithEvents(ids);
+        return this.#detachRows(ids);
+    }
+    /** Load the matching pivot rows, fire `deleting`, delete the survivors, fire `deleted`. */
+    async #detachWithEvents(ids) {
+        const d = this.#conn().dialect;
+        const pw = pivotWhereSql(d, this.#pivotWheres);
+        const wanted = ids === undefined ? null : new Set(this.#normalize(ids).map(([id]) => String(id)));
+        const rows = await this.#conn().all(`SELECT * FROM ${wrapSqlName(d, this.pivotTable)} WHERE ${wrapSqlName(d, this.foreignPivotKey)} = ?${pw.sql}`, [this.#parentId(), ...pw.params]);
+        const doomed = [];
+        for (const row of rows) {
+            if (wanted && !wanted.has(String(row[this.relatedPivotKey])))
+                continue;
+            const pivot = this.#pivotInstance(row, true);
+            if ((await fireModelEvent(pivot, "deleting")) === false)
+                continue;
+            doomed.push(pivot);
+        }
+        if (doomed.length === 0)
+            return 0;
+        const deleted = await this.#detachRows(doomed.map((p) => p[this.relatedPivotKey]));
+        for (const pivot of doomed) {
+            pivot.exists = false;
+            await fireModelEvent(pivot, "deleted");
+        }
+        return deleted;
+    }
+    async #detachRows(ids) {
+        const d = this.#conn().dialect;
+        const pw = pivotWhereSql(d, this.#pivotWheres);
+        const base = `DELETE FROM ${wrapSqlName(d, this.pivotTable)} WHERE ${wrapSqlName(d, this.foreignPivotKey)} = ?${pw.sql}`;
         if (ids === undefined) {
-            await parent.getConnection().run(`DELETE FROM ${this.pivotTable} WHERE ${this.foreignPivotKey} = ?`, [this.#parentId()]);
-            return;
+            const result = await this.#conn().run(base, [this.#parentId(), ...pw.params]);
+            return Number(result ?? 0);
         }
-        const list = Array.isArray(ids) ? ids : [ids];
-        for (const id of list) {
-            await parent.getConnection().run(`DELETE FROM ${this.pivotTable}
-         WHERE ${this.foreignPivotKey} = ? AND ${this.relatedPivotKey} = ?`, [this.#parentId(), id]);
+        const list = this.#normalize(ids).map(([id]) => id);
+        let deleted = 0;
+        for (let i = 0; i < list.length; i += 900) {
+            const chunk = list.slice(i, i + 900);
+            const result = await this.#conn().run(`${base} AND ${wrapSqlName(d, this.relatedPivotKey)} IN (${chunk.map(() => "?").join(", ")})`, [this.#parentId(), ...pw.params, ...chunk]);
+            deleted += Number(result ?? 0);
+        }
+        return deleted;
+    }
+    /** `updateExistingPivot` — update pivot columns for one related id. Returns affected rows. */
+    async updateExistingPivot(id, attributes) {
+        const relatedId = this.#normalize(id)[0][0];
+        let data = this.#castPivotWrite(this.#stamp({ ...attributes }, false));
+        if (Object.keys(data).length === 0)
+            return 0;
+        const d = this.#conn().dialect;
+        const pw = pivotWhereSql(d, this.#pivotWheres);
+        let pivot = null;
+        if (this.#pivotEvents()) {
+            const [current] = await this.#conn().all(`SELECT * FROM ${wrapSqlName(d, this.pivotTable)} WHERE ${wrapSqlName(d, this.foreignPivotKey)} = ? AND ${wrapSqlName(d, this.relatedPivotKey)} = ?${pw.sql}`, [this.#parentId(), relatedId, ...pw.params]);
+            if (!current)
+                return 0;
+            pivot = this.#pivotInstance(current, true);
+            pivot.forceFill(data);
+            if ((await fireModelEvent(pivot, "saving")) === false)
+                return 0;
+            if ((await fireModelEvent(pivot, "updating")) === false)
+                return 0;
+            data = pivot.getDirty();
         }
+        const cols = Object.keys(data);
+        if (cols.length === 0)
+            return 0;
+        const result = await this.#conn().run(`UPDATE ${wrapSqlName(d, this.pivotTable)} SET ${cols.map((c) => `${wrapSqlName(d, c)} = ?`).join(", ")} WHERE ${wrapSqlName(d, this.foreignPivotKey)} = ? AND ${wrapSqlName(d, this.relatedPivotKey)} = ?${pw.sql}`, [...cols.map((c) => data[c]), this.#parentId(), relatedId, ...pw.params]);
+        if (pivot) {
+            await fireModelEvent(pivot, "updated");
+            await fireModelEvent(pivot, "saved");
+        }
+        return Number(result ?? 0);
     }
-    async sync(ids) {
-        await this.detach();
-        await this.attach(ids);
+    /**
+     * `sync` — diff against existing rows: attach new, detach removed, and update
+     * pivot attributes of kept rows when the map form supplies them.
+     */
+    async sync(ids, detaching = true) {
+        const pairs = this.#normalize(ids);
+        const existing = await this.#currentIds();
+        const result = { attached: [], detached: [], updated: [] };
+        const wanted = new Set(pairs.map(([id]) => String(id)));
+        if (detaching) {
+            const gone = [...existing].filter((id) => !wanted.has(id));
+            if (gone.length > 0) {
+                await this.detach(gone);
+                result.detached = gone;
+            }
+        }
+        const toAttach = [];
+        for (const [id, attrs] of pairs) {
+            if (!existing.has(String(id))) {
+                toAttach.push([id, attrs]);
+                result.attached.push(id);
+            }
+            else if (Object.keys(attrs).length > 0) {
+                if ((await this.updateExistingPivot(id, attrs)) > 0)
+                    result.updated.push(id);
+            }
+        }
+        if (toAttach.length > 0) {
+            await this.attach(Object.fromEntries(toAttach));
+        }
+        return result;
     }
-    /** Attach missing ids only. */
+    /** `syncWithoutDetaching`. */
     async syncWithoutDetaching(ids) {
-        const existing = new Set((await this.get()).map((m) => String(m[this.related.primaryKey])));
-        const missing = ids.filter((id) => !existing.has(String(id)));
-        if (missing.length > 0)
-            await this.attach(missing);
+        return this.sync(ids, false);
     }
-    /** Attach missing, detach present. */
+    /** `toggle` — attach missing, detach present. */
     async toggle(ids) {
-        const list = Array.isArray(ids) ? ids : [ids];
-        const existing = new Set((await this.get()).map((m) => String(m[this.related.primaryKey])));
-        const attachIds = [];
-        const detachIds = [];
-        for (const id of list) {
+        const pairs = this.#normalize(ids);
+        const existing = await this.#currentIds();
+        const attach = [];
+        const detached = [];
+        for (const [id, attrs] of pairs) {
             if (existing.has(String(id)))
-                detachIds.push(id);
+                detached.push(id);
             else
-                attachIds.push(id);
+                attach.push([id, attrs]);
         }
-        if (detachIds.length > 0)
-            await this.detach(detachIds);
-        if (attachIds.length > 0)
-            await this.attach(attachIds);
+        if (detached.length > 0)
+            await this.detach(detached);
+        if (attach.length > 0)
+            await this.attach(Object.fromEntries(attach));
+        return { attached: attach.map(([id]) => id), detached };
     }
 }
 /** Polymorphic many-to-many (e.g. Contact → Role via `model_has_roles`). */
@@ -920,6 +1479,19 @@ export class MorphToMany {
             tenantSql = ` AND ${this.pivotTable}.${this.pivotTenantKey} = ?`;
             params.push(tenantId);
         }
+        if (hasGlobalScopes(related)) {
+            // Query-builder path so the related model's global scopes apply.
+            let q = related
+                .newQuery()
+                .join(this.pivotTable, `${this.pivotTable}.${this.relatedPivotKey}`, "=", `${related.table}.${related.primaryKey}`)
+                .where(`${this.pivotTable}.${this.foreignPivotKey}`, this.#parentId())
+                .whereIn(`${this.pivotTable}.${this.morphTypeColumn}`, this.morphTypes)
+                .select(`${related.table}.*`);
+            if (this.pivotTenantKey && tenantSql) {
+                q = q.where(`${this.pivotTable}.${this.pivotTenantKey}`, tenantId);
+            }
+            return new OrmCollection((await q.get()).all(), { owned: true });
+        }
         const rows = await parent.getConnection().all(`SELECT ${related.table}.* FROM ${related.table}
        INNER JOIN ${this.pivotTable}
          ON ${this.pivotTable}.${this.relatedPivotKey} = ${related.table}.${related.primaryKey}
@@ -927,68 +1499,192 @@ export class MorphToMany {
          AND ${this.pivotTable}.${this.morphTypeColumn} IN (${this.#morphTypePlaceholders()})${tenantSql}`, params);
         return new OrmCollection(rows.map((row) => new related(row)), { owned: true });
     }
+    #conn() {
+        return this.parent.constructor.getConnection();
+    }
+    #useTenant() {
+        const tenantId = this.#tenantId();
+        return Boolean(this.pivotTenantKey && tenantId != null && tenantId !== "");
+    }
+    async #currentIds() {
+        const d = this.#conn().dialect;
+        const params = [this.#parentId(), ...this.morphTypes];
+        let tenantSql = "";
+        if (this.#useTenant()) {
+            tenantSql = ` AND ${wrapSqlName(d, this.pivotTenantKey)} = ?`;
+            params.push(this.#tenantId());
+        }
+        const rows = await this.#conn().all(`SELECT ${wrapSqlName(d, this.relatedPivotKey)} AS id FROM ${wrapSqlName(d, this.pivotTable)} WHERE ${wrapSqlName(d, this.foreignPivotKey)} = ? AND ${wrapSqlName(d, this.morphTypeColumn)} IN (${this.#morphTypePlaceholders()})${tenantSql}`, params);
+        return new Set(rows.map((r) => String(r.id)));
+    }
+    /** One multi-row INSERT per chunk (was one INSERT per id). */
     async attach(ids) {
         const list = Array.isArray(ids) ? ids : [ids];
-        const parent = this.parent.constructor;
         const morphType = this.getMorphType();
-        const tenantId = this.#tenantId();
-        const useTenant = Boolean(this.pivotTenantKey && tenantId != null && tenantId !== "");
-        for (const id of list) {
-            if (useTenant) {
-                await parent.getConnection().run(`INSERT INTO ${this.pivotTable} (${this.foreignPivotKey}, ${this.relatedPivotKey}, ${this.morphTypeColumn}, ${this.pivotTenantKey}) VALUES (?, ?, ?, ?)`, [this.#parentId(), id, morphType, tenantId]);
-            }
-            else {
-                await parent.getConnection().run(`INSERT INTO ${this.pivotTable} (${this.foreignPivotKey}, ${this.relatedPivotKey}, ${this.morphTypeColumn}) VALUES (?, ?, ?)`, [this.#parentId(), id, morphType]);
-            }
+        const useTenant = this.#useTenant();
+        await insertPivotRows(this.#conn(), this.pivotTable, list.map((id) => ({
+            [this.foreignPivotKey]: this.#parentId(),
+            [this.relatedPivotKey]: id,
+            [this.morphTypeColumn]: morphType,
+            ...(useTenant ? { [this.pivotTenantKey]: this.#tenantId() } : {}),
+        })));
+    }
+    /** Returns the number of deleted pivot rows. */
+    async detach(ids) {
+        const d = this.#conn().dialect;
+        const useTenant = this.#useTenant();
+        const tenantSql = useTenant ? ` AND ${wrapSqlName(d, this.pivotTenantKey)} = ?` : "";
+        const tenantParams = useTenant ? [this.#tenantId()] : [];
+        const base = `DELETE FROM ${wrapSqlName(d, this.pivotTable)}
+         WHERE ${wrapSqlName(d, this.foreignPivotKey)} = ?
+           AND ${wrapSqlName(d, this.morphTypeColumn)} IN (${this.#morphTypePlaceholders()})${tenantSql}`;
+        const baseParams = [this.#parentId(), ...this.morphTypes, ...tenantParams];
+        if (ids === undefined) {
+            return Number((await this.#conn().run(base, baseParams)) ?? 0);
         }
+        const list = Array.isArray(ids) ? ids : [ids];
+        return deletePivotIn(this.#conn(), base, baseParams, this.relatedPivotKey, list);
+    }
+    /** Diff-based: keeps existing rows, attaches new ids, detaches removed ones. */
+    async sync(ids) {
+        const existing = await this.#currentIds();
+        const wanted = new Set(ids.map(String));
+        const detached = [...existing].filter((id) => !wanted.has(id));
+        const attached = ids.filter((id) => !existing.has(String(id)));
+        if (detached.length > 0)
+            await this.detach(detached);
+        if (attached.length > 0)
+            await this.attach(attached);
+        return { attached, detached, updated: [] };
+    }
+    async syncWithoutDetaching(ids) {
+        const existing = await this.#currentIds();
+        const attached = ids.filter((id) => !existing.has(String(id)));
+        if (attached.length > 0)
+            await this.attach(attached);
+        return { attached, detached: [], updated: [] };
+    }
+    async toggle(ids) {
+        const list = Array.isArray(ids) ? ids : [ids];
+        const existing = await this.#currentIds();
+        const detached = list.filter((id) => existing.has(String(id)));
+        const attached = list.filter((id) => !existing.has(String(id)));
+        if (detached.length > 0)
+            await this.detach(detached);
+        if (attached.length > 0)
+            await this.attach(attached);
+        return { attached, detached };
+    }
+}
+/**
+ * `morphedByMany` — inverse of a `morphToMany` (`taggables` pivot).
+ * Parent is the "tag" side; the pivot stores the related model's id and morph type.
+ */
+export class MorphedByMany {
+    parent;
+    related;
+    pivotTable;
+    foreignPivotKey;
+    relatedPivotKey;
+    morphTypeColumn;
+    morphType;
+    constructor(parent, related, pivotTable, foreignPivotKey, relatedPivotKey, morphTypeColumn, morphType) {
+        this.parent = parent;
+        this.related = related;
+        this.pivotTable = pivotTable;
+        this.foreignPivotKey = foreignPivotKey;
+        this.relatedPivotKey = relatedPivotKey;
+        this.morphTypeColumn = morphTypeColumn;
+        this.morphType = morphType;
+    }
+    getRelated() {
+        return this.related;
+    }
+    getPivotTable() {
+        return this.pivotTable;
+    }
+    getForeignPivotKeyName() {
+        return this.foreignPivotKey;
+    }
+    getRelatedPivotKeyName() {
+        return this.relatedPivotKey;
+    }
+    getMorphTypeColumn() {
+        return this.morphTypeColumn;
+    }
+    getMorphType() {
+        return this.morphType;
+    }
+    #parentId() {
+        const parentKey = this.parent.constructor.primaryKey;
+        return this.parent[parentKey];
+    }
+    #conn() {
+        return this.parent.constructor.getConnection();
+    }
+    async get() {
+        const related = this.related;
+        const d = this.#conn().dialect;
+        const qRelated = wrapSqlName(d, related.table);
+        const qPivot = wrapSqlName(d, this.pivotTable);
+        const rows = await this.#conn().all(`SELECT ${qRelated}.* FROM ${qRelated}
+       INNER JOIN ${qPivot}
+         ON ${qPivot}.${wrapSqlName(d, this.relatedPivotKey)} = ${qRelated}.${wrapSqlName(d, related.primaryKey)}
+       WHERE ${qPivot}.${wrapSqlName(d, this.foreignPivotKey)} = ?
+         AND ${qPivot}.${wrapSqlName(d, this.morphTypeColumn)} = ?${softDeleteAliasSql(related, qRelated)}`, [this.#parentId(), this.morphType]);
+        return new OrmCollection(rows.map((row) => new related(row)), {
+            owned: true,
+        });
+    }
+    async attach(ids) {
+        const list = Array.isArray(ids) ? ids : [ids];
+        await insertPivotRows(this.#conn(), this.pivotTable, list.map((id) => ({
+            [this.foreignPivotKey]: this.#parentId(),
+            [this.relatedPivotKey]: id,
+            [this.morphTypeColumn]: this.morphType,
+        })));
     }
     async detach(ids) {
-        const parent = this.parent.constructor;
-        const tenantId = this.#tenantId();
-        const useTenant = Boolean(this.pivotTenantKey && tenantId != null && tenantId !== "");
-        const tenantSql = useTenant
-            ? ` AND ${this.pivotTenantKey} = ?`
-            : "";
-        const tenantParams = useTenant ? [tenantId] : [];
+        const d = this.#conn().dialect;
+        const base = `DELETE FROM ${wrapSqlName(d, this.pivotTable)} WHERE ${wrapSqlName(d, this.foreignPivotKey)} = ? AND ${wrapSqlName(d, this.morphTypeColumn)} = ?`;
+        const baseParams = [this.#parentId(), this.morphType];
         if (ids === undefined) {
-            await parent.getConnection().run(`DELETE FROM ${this.pivotTable}
-         WHERE ${this.foreignPivotKey} = ?
-           AND ${this.morphTypeColumn} IN (${this.#morphTypePlaceholders()})${tenantSql}`, [this.#parentId(), ...this.morphTypes, ...tenantParams]);
-            return;
+            return Number((await this.#conn().run(base, baseParams)) ?? 0);
         }
         const list = Array.isArray(ids) ? ids : [ids];
-        for (const id of list) {
-            await parent.getConnection().run(`DELETE FROM ${this.pivotTable}
-         WHERE ${this.foreignPivotKey} = ?
-           AND ${this.relatedPivotKey} = ?
-           AND ${this.morphTypeColumn} IN (${this.#morphTypePlaceholders()})${tenantSql}`, [this.#parentId(), id, ...this.morphTypes, ...tenantParams]);
-        }
+        return deletePivotIn(this.#conn(), base, baseParams, this.relatedPivotKey, list);
     }
+    async #currentIds() {
+        const d = this.#conn().dialect;
+        const rows = await this.#conn().all(`SELECT ${wrapSqlName(d, this.relatedPivotKey)} AS id FROM ${wrapSqlName(d, this.pivotTable)} WHERE ${wrapSqlName(d, this.foreignPivotKey)} = ? AND ${wrapSqlName(d, this.morphTypeColumn)} = ?`, [this.#parentId(), this.morphType]);
+        return new Set(rows.map((r) => String(r.id)));
+    }
+    /** Detach missing ids, attach new ones; keeps rows that stay */
     async sync(ids) {
-        await this.detach();
-        await this.attach(ids);
+        const existing = await this.#currentIds();
+        const wanted = new Set(ids.map(String));
+        const detach = [...existing].filter((id) => !wanted.has(id));
+        const attach = ids.filter((id) => !existing.has(String(id)));
+        if (detach.length > 0)
+            await this.detach(detach);
+        if (attach.length > 0)
+            await this.attach(attach);
     }
     async syncWithoutDetaching(ids) {
-        const existing = new Set((await this.get()).map((m) => String(m[this.related.primaryKey])));
+        const existing = await this.#currentIds();
         const missing = ids.filter((id) => !existing.has(String(id)));
         if (missing.length > 0)
             await this.attach(missing);
     }
     async toggle(ids) {
         const list = Array.isArray(ids) ? ids : [ids];
-        const existing = new Set((await this.get()).map((m) => String(m[this.related.primaryKey])));
-        const attachIds = [];
-        const detachIds = [];
-        for (const id of list) {
-            if (existing.has(String(id)))
-                detachIds.push(id);
-            else
-                attachIds.push(id);
-        }
-        if (detachIds.length > 0)
-            await this.detach(detachIds);
-        if (attachIds.length > 0)
-            await this.attach(attachIds);
+        const existing = await this.#currentIds();
+        const detach = list.filter((id) => existing.has(String(id)));
+        const attach = list.filter((id) => !existing.has(String(id)));
+        if (detach.length > 0)
+            await this.detach(detach);
+        if (attach.length > 0)
+            await this.attach(attach);
     }
 }
 /** Cached relation meta per model class (avoids `new model()` + related() per compile). */
@@ -1019,6 +1715,17 @@ export function resolveRelation(model, relation) {
             localKey: rel.getLocalKeyName(),
         };
     }
+    else if (rel instanceof MorphMany || rel instanceof MorphOne) {
+        // Same shape as hasMany plus the morph type column.
+        meta = {
+            kind: "has",
+            related: rel.getRelated(),
+            foreignKey: rel.getIdColumn(),
+            localKey: rel.getLocalKeyName(),
+            typeColumn: rel.getTypeColumn(),
+            morphType: rel.getMorphType(),
+        };
+    }
     else if (rel instanceof BelongsTo) {
         meta = {
             kind: "belongsTo",
@@ -1036,6 +1743,7 @@ export function resolveRelation(model, relation) {
             relatedPivotKey: rel.getRelatedPivotKeyName(),
             localKey: model.primaryKey,
             pivotColumns: rel.getPivotColumns(),
+            pivotWheres: rel.getPivotWheres(),
         };
     }
     else if (rel instanceof MorphToMany) {
@@ -1052,6 +1760,19 @@ export function resolveRelation(model, relation) {
             parentTenantKey: rel.getParentTenantKey(),
         };
     }
+    else if (rel instanceof MorphedByMany) {
+        // Same shape as morphToMany: pivot filtered by morph type, parent key + related key columns.
+        meta = {
+            kind: "morphToMany",
+            related: rel.getRelated(),
+            pivotTable: rel.getPivotTable(),
+            foreignPivotKey: rel.getForeignPivotKeyName(),
+            relatedPivotKey: rel.getRelatedPivotKeyName(),
+            localKey: model.primaryKey,
+            morphTypeColumn: rel.getMorphTypeColumn(),
+            morphTypes: [rel.getMorphType()],
+        };
+    }
     else if (rel instanceof HasManyThrough) {
         meta = {
             kind: "hasManyThrough",
@@ -1077,6 +1798,9 @@ export function resolveRelation(model, relation) {
     byName.set(relation, meta);
     return meta;
 }
+export function resolveAggregateRelation(model, relation) {
+    return resolveRelation(model, relation);
+}
 export async function countRelation(model, relation) {
     const value = await aggregateRelation(model, relation, "count");
     return Number(value ?? 0);
@@ -1091,6 +1815,8 @@ export async function aggregateRelation(model, relation, fn, column) {
     const id = model[ctor.primaryKey];
     if (meta.kind === "has") {
         let q = meta.related.where(meta.foreignKey, id);
+        if (meta.typeColumn)
+            q = q.where(meta.typeColumn, meta.morphType);
         if (fn === "exists")
             return (await q.exists()) ? 1 : 0;
         if (fn === "count")