@bunyad/orm 0.1.0-alpha.0

package/dist/relations.js

@@ -0,0 +1,1164 @@
+/**
+ * Relation classes and morph map.
+ */
+import { wrapSqlName } from "@bunyad/database";
+import { OrmCollection } from "./orm-collection.js";
+import { softDeleteAliasSql, nowForConnection, } from "./model-helpers.js";
+import { Model } from "./model.js";
+import { isIgnoringTouch } from "./model-strictness.js";
+/** Register morph type aliases (`Relation::morphMap`). */
+const morphAliases = new Map();
+/** ModelQuery methods that mutate the builder and return it — forwarded onto relations. */
+const RELATION_QUERY_CHAIN = [
+    "where",
+    "orWhere",
+    "whereIn",
+    "whereNotIn",
+    "whereNull",
+    "whereNotNull",
+    "whereBetween",
+    "whereNotBetween",
+    "whereColumn",
+    "whereRaw",
+    "orWhereRaw",
+    "whereLike",
+    "whereDate",
+    "orderBy",
+    "orderByDesc",
+    "orderByRaw",
+    "latest",
+    "oldest",
+    "limit",
+    "offset",
+    "take",
+    "skip",
+    "forPage",
+    "select",
+    "addSelect",
+    "selectRaw",
+    "groupBy",
+    "having",
+    "havingRaw",
+    "when",
+    "unless",
+    "tap",
+];
+/** ModelQuery methods that return a value — forwarded onto relations. */
+const RELATION_QUERY_TERMINAL = [
+    "count",
+    "exists",
+    "sum",
+    "avg",
+    "min",
+    "max",
+    "toSql",
+    "toRawSql",
+    "getBindings",
+];
+/** Write terminals, forwarded only onto relations that filter one table by a foreign key. */
+const RELATION_QUERY_WRITE = ["update", "delete", "forceDelete"];
+function installRelationQueryForwarders(ctors, writes = []) {
+    for (const Ctor of writes) {
+        for (const method of RELATION_QUERY_WRITE) {
+            Object.defineProperty(Ctor.prototype, method, {
+                value: function (...args) {
+                    const q = this.getQuery();
+                    return q[method](...args);
+                },
+                configurable: true,
+                writable: true,
+            });
+        }
+    }
+    for (const Ctor of ctors) {
+        for (const method of RELATION_QUERY_CHAIN) {
+            Object.defineProperty(Ctor.prototype, method, {
+                value: function (...args) {
+                    const q = this.getQuery();
+                    q[method](...args);
+                    return this;
+                },
+                configurable: true,
+                writable: true,
+            });
+        }
+        for (const method of RELATION_QUERY_TERMINAL) {
+            Object.defineProperty(Ctor.prototype, method, {
+                value: function (...args) {
+                    const q = this.getQuery();
+                    return q[method](...args);
+                },
+                configurable: true,
+                writable: true,
+            });
+        }
+    }
+}
+/** Strip `__pivot_*` columns onto `model.pivot`. */
+export function applyPivotAttributes(model, attrs, pivotKeys) {
+    if (pivotKeys.length === 0)
+        return model;
+    const pivot = {};
+    const self = model;
+    for (const key of pivotKeys) {
+        const alias = `__pivot_${key}`;
+        if (Object.prototype.hasOwnProperty.call(attrs, alias)) {
+            pivot[key] = attrs[alias];
+            delete self[alias];
+        }
+        else if (Object.prototype.hasOwnProperty.call(self, alias)) {
+            pivot[key] = self[alias];
+            delete self[alias];
+        }
+    }
+    if (Object.keys(pivot).length > 0) {
+        self.pivot = pivot;
+    }
+    return model;
+}
+function pivotSelectKeys(foreignPivotKey, relatedPivotKey, extra) {
+    const keys = [foreignPivotKey, relatedPivotKey];
+    for (const col of extra) {
+        if (!keys.includes(col))
+            keys.push(col);
+    }
+    return keys;
+}
+export function morphMap(map) {
+    for (const [alias, cls] of Object.entries(map)) {
+        morphAliases.set(alias, cls);
+    }
+}
+export function clearMorphMap() {
+    morphAliases.clear();
+}
+export function morphTypeFor(model) {
+    for (const [alias, cls] of morphAliases) {
+        if (cls === model)
+            return alias;
+    }
+    return model.name;
+}
+export function resolveMorphType(type) {
+    const mapped = morphAliases.get(type);
+    if (mapped)
+        return mapped;
+    throw new Error(`No morph map entry for [${type}]. Call morphMap({ ${type}: Model }) first.`);
+}
+/** MorphMany relation. */
+export class MorphMany {
+    parent;
+    related;
+    typeColumn;
+    idColumn;
+    morphType;
+    localKey;
+    #baseQuery = null;
+    constructor(parent, related, typeColumn, idColumn, morphType, localKey) {
+        this.parent = parent;
+        this.related = related;
+        this.typeColumn = typeColumn;
+        this.idColumn = idColumn;
+        this.morphType = morphType;
+        this.localKey = localKey;
+    }
+    getRelated() {
+        return this.related;
+    }
+    getTypeColumn() {
+        return this.typeColumn;
+    }
+    getIdColumn() {
+        return this.idColumn;
+    }
+    getMorphType() {
+        return this.morphType;
+    }
+    getLocalKeyName() {
+        return (this.localKey ?? this.parent.constructor.primaryKey);
+    }
+    #parentId() {
+        const parentKey = this.localKey ?? this.parent.constructor.primaryKey;
+        return this.parent[parentKey];
+    }
+    /** Constrained related query (`morphMany().where(…).get()`). */
+    getQuery() {
+        if (!this.#baseQuery) {
+            this.#baseQuery = this.related
+                .where(this.typeColumn, this.morphType)
+                .where(this.idColumn, this.#parentId());
+        }
+        return this.#baseQuery;
+    }
+    async get() {
+        const rows = await this.getQuery().get();
+        return new OrmCollection(rows.all(), { owned: true });
+    }
+    async first() {
+        return this.getQuery().first();
+    }
+    async create(attributes) {
+        return this.related.create({
+            ...attributes,
+            [this.typeColumn]: this.morphType,
+            [this.idColumn]: this.#parentId(),
+        });
+    }
+}
+/** MorphOne relation. */
+export class MorphOne {
+    parent;
+    related;
+    typeColumn;
+    idColumn;
+    morphType;
+    localKey;
+    #ofManyColumn;
+    #ofManyAggregate;
+    #baseQuery = null;
+    constructor(parent, related, typeColumn, idColumn, morphType, localKey) {
+        this.parent = parent;
+        this.related = related;
+        this.typeColumn = typeColumn;
+        this.idColumn = idColumn;
+        this.morphType = morphType;
+        this.localKey = localKey;
+    }
+    getRelated() {
+        return this.related;
+    }
+    getTypeColumn() {
+        return this.typeColumn;
+    }
+    getIdColumn() {
+        return this.idColumn;
+    }
+    getMorphType() {
+        return this.morphType;
+    }
+    getLocalKeyName() {
+        return (this.localKey ?? this.parent.constructor.primaryKey);
+    }
+    isOfMany() {
+        return this.#ofManyColumn != null;
+    }
+    getOfManyColumn() {
+        return this.#ofManyColumn;
+    }
+    getOfManyAggregate() {
+        return this.#ofManyAggregate;
+    }
+    #parentId() {
+        const parentKey = this.localKey ?? this.parent.constructor.primaryKey;
+        return this.parent[parentKey];
+    }
+    latestOfMany(column) {
+        this.#baseQuery = null;
+        return this.ofMany(column ?? this.related.primaryKey, "max");
+    }
+    oldestOfMany(column) {
+        this.#baseQuery = null;
+        return this.ofMany(column ?? this.related.primaryKey, "min");
+    }
+    ofMany(column, aggregate) {
+        this.#baseQuery = null;
+        this.#ofManyColumn = column;
+        this.#ofManyAggregate = aggregate;
+        return this;
+    }
+    getQuery() {
+        if (!this.#baseQuery) {
+            let q = this.related
+                .where(this.typeColumn, this.morphType)
+                .where(this.idColumn, this.#parentId());
+            if (this.#ofManyAggregate && this.#ofManyColumn) {
+                const dialect = this.related.getConnection().dialect;
+                const table = wrapSqlName(dialect, this.related.table);
+                const col = wrapSqlName(dialect, this.#ofManyColumn);
+                const typeCol = wrapSqlName(dialect, this.typeColumn);
+                const idCol = wrapSqlName(dialect, this.idColumn);
+                const agg = this.#ofManyAggregate.toUpperCase();
+                const soft = softDeleteAliasSql(this.related, table);
+                q = q.whereRaw(`${table}.${col} = (SELECT ${agg}(${col}) FROM ${table} WHERE ${typeCol} = ? AND ${idCol} = ?${soft})`, [this.morphType, this.#parentId()]);
+            }
+            this.#baseQuery = q;
+        }
+        return this.#baseQuery;
+    }
+    async get() {
+        return this.first();
+    }
+    async first() {
+        return this.getQuery().first();
+    }
+    async create(attributes) {
+        return this.related.create({
+            ...attributes,
+            [this.typeColumn]: this.morphType,
+            [this.idColumn]: this.#parentId(),
+        });
+    }
+}
+/** Laravel MorphTo relation. */
+export class MorphTo {
+    parent;
+    typeColumn;
+    idColumn;
+    ownerKey;
+    constructor(parent, typeColumn, idColumn, ownerKey) {
+        this.parent = parent;
+        this.typeColumn = typeColumn;
+        this.idColumn = idColumn;
+        this.ownerKey = ownerKey;
+    }
+    getTypeColumn() {
+        return this.typeColumn;
+    }
+    getIdColumn() {
+        return this.idColumn;
+    }
+    getOwnerKeyName() {
+        return this.ownerKey;
+    }
+    async get() {
+        return this.first();
+    }
+    async first() {
+        const row = this.parent;
+        const type = row[this.typeColumn];
+        const id = row[this.idColumn];
+        if (type == null || id == null)
+            return null;
+        const Related = resolveMorphType(String(type));
+        if (this.ownerKey && this.ownerKey !== Related.primaryKey) {
+            return Related.where(this.ownerKey, id).first();
+        }
+        return Related.find(id);
+    }
+    /** Laravel `associate` for morphTo. */
+    associate(model) {
+        const row = this.parent;
+        const Related = model.constructor;
+        const key = this.ownerKey ?? Related.primaryKey;
+        row[this.typeColumn] = morphTypeFor(Related);
+        row[this.idColumn] = model[key];
+        return this;
+    }
+    /** Laravel `dissociate` for morphTo. */
+    dissociate() {
+        const row = this.parent;
+        row[this.typeColumn] = null;
+        row[this.idColumn] = null;
+        return this;
+    }
+}
+/** HasMany relation. */
+export class HasMany {
+    parent;
+    related;
+    foreignKey;
+    localKey;
+    #baseQuery = null;
+    constructor(parent, related, foreignKey, localKey) {
+        this.parent = parent;
+        this.related = related;
+        this.foreignKey = foreignKey;
+        this.localKey = localKey;
+    }
+    getRelated() {
+        return this.related;
+    }
+    getForeignKeyName() {
+        return this.foreignKey;
+    }
+    getLocalKeyName() {
+        return (this.localKey ?? this.parent.constructor.primaryKey);
+    }
+    #parentId() {
+        const parentKey = this.localKey ?? this.parent.constructor.primaryKey;
+        return this.parent[parentKey];
+    }
+    /** Constrained related query (`hasMany().where(…).orderBy(…).get()`). */
+    getQuery() {
+        if (!this.#baseQuery) {
+            this.#baseQuery = this.related.where(this.foreignKey, this.#parentId());
+        }
+        return this.#baseQuery;
+    }
+    async get() {
+        const rows = await this.getQuery().get();
+        return new OrmCollection(rows.all(), { owned: true });
+    }
+    async first() {
+        return this.getQuery().first();
+    }
+    async create(attributes) {
+        return this.related.create({
+            ...attributes,
+            [this.foreignKey]: this.#parentId(),
+        });
+    }
+    /** Bump `updated_at` on matching related rows. */
+    async touch() {
+        if (isIgnoringTouch(this.related))
+            return false;
+        if (this.related.timestamps === false)
+            return false;
+        const parentId = this.#parentId();
+        if (parentId === undefined || parentId === null)
+            return false;
+        const now = nowForConnection(this.related.getConnection());
+        await this.related
+            .newQuery()
+            .where(this.foreignKey, parentId)
+            .update({ updated_at: now });
+        return true;
+    }
+}
+/** HasOne relation. */
+export class HasOne {
+    parent;
+    related;
+    foreignKey;
+    localKey;
+    #ofManyColumn;
+    #ofManyAggregate;
+    #baseQuery = null;
+    constructor(parent, related, foreignKey, localKey) {
+        this.parent = parent;
+        this.related = related;
+        this.foreignKey = foreignKey;
+        this.localKey = localKey;
+    }
+    getRelated() {
+        return this.related;
+    }
+    getForeignKeyName() {
+        return this.foreignKey;
+    }
+    getLocalKeyName() {
+        return (this.localKey ?? this.parent.constructor.primaryKey);
+    }
+    isOfMany() {
+        return this.#ofManyColumn != null;
+    }
+    getOfManyColumn() {
+        return this.#ofManyColumn;
+    }
+    getOfManyAggregate() {
+        return this.#ofManyAggregate;
+    }
+    #parentId() {
+        const parentKey = this.localKey ?? this.parent.constructor.primaryKey;
+        return this.parent[parentKey];
+    }
+    /** Latest related row by column (default primary key). */
+    latestOfMany(column) {
+        this.#baseQuery = null;
+        return this.ofMany(column ?? this.related.primaryKey, "max");
+    }
+    /** Oldest related row by column (default primary key). */
+    oldestOfMany(column) {
+        this.#baseQuery = null;
+        return this.ofMany(column ?? this.related.primaryKey, "min");
+    }
+    /** Constrain to the related row with min/max of `column`. */
+    ofMany(column, aggregate) {
+        this.#baseQuery = null;
+        this.#ofManyColumn = column;
+        this.#ofManyAggregate = aggregate;
+        return this;
+    }
+    getQuery() {
+        if (!this.#baseQuery) {
+            let q = this.related.where(this.foreignKey, this.#parentId());
+            if (this.#ofManyAggregate && this.#ofManyColumn) {
+                const dialect = this.related.getConnection().dialect;
+                const table = wrapSqlName(dialect, this.related.table);
+                const col = wrapSqlName(dialect, this.#ofManyColumn);
+                const fk = wrapSqlName(dialect, this.foreignKey);
+                const agg = this.#ofManyAggregate.toUpperCase();
+                const soft = softDeleteAliasSql(this.related, table);
+                q = q.whereRaw(`${table}.${col} = (SELECT ${agg}(${col}) FROM ${table} WHERE ${fk} = ?${soft})`, [this.#parentId()]);
+            }
+            this.#baseQuery = q;
+        }
+        return this.#baseQuery;
+    }
+    async get() {
+        return this.first();
+    }
+    async first() {
+        return this.getQuery().first();
+    }
+    async create(attributes) {
+        return this.related.create({
+            ...attributes,
+            [this.foreignKey]: this.#parentId(),
+        });
+    }
+    /** Bump `updated_at` on matching related rows. */
+    async touch() {
+        if (isIgnoringTouch(this.related))
+            return false;
+        if (this.related.timestamps === false)
+            return false;
+        const parentKey = this.localKey ?? this.parent.constructor.primaryKey;
+        const parentId = this.parent[parentKey];
+        if (parentId === undefined || parentId === null)
+            return false;
+        const now = nowForConnection(this.related.getConnection());
+        await this.related
+            .newQuery()
+            .where(this.foreignKey, parentId)
+            .update({ updated_at: now });
+        return true;
+    }
+}
+/** HasManyThrough relation (Parent → Through → Related). */
+export class HasManyThrough {
+    parent;
+    related;
+    through;
+    firstKey;
+    secondKey;
+    localKey;
+    secondLocalKey;
+    #baseQuery = null;
+    constructor(parent, related, through, firstKey, secondKey, localKey, secondLocalKey) {
+        this.parent = parent;
+        this.related = related;
+        this.through = through;
+        this.firstKey = firstKey;
+        this.secondKey = secondKey;
+        this.localKey = localKey;
+        this.secondLocalKey = secondLocalKey;
+    }
+    getRelated() {
+        return this.related;
+    }
+    getThrough() {
+        return this.through;
+    }
+    getFirstKeyName() {
+        return this.firstKey;
+    }
+    getSecondKeyName() {
+        return this.secondKey;
+    }
+    getLocalKeyName() {
+        return this.localKey;
+    }
+    getSecondLocalKeyName() {
+        return this.secondLocalKey;
+    }
+    #parentId() {
+        return this.parent[this.localKey];
+    }
+    getQuery() {
+        if (!this.#baseQuery) {
+            this.#baseQuery = this.related
+                .newQuery()
+                .join(this.through.table, `${this.related.table}.${this.secondKey}`, "=", `${this.through.table}.${this.secondLocalKey}`)
+                .where(`${this.through.table}.${this.firstKey}`, this.#parentId())
+                .select(`${this.related.table}.*`);
+        }
+        return this.#baseQuery;
+    }
+    async get() {
+        const parentId = this.#parentId();
+        if (parentId == null)
+            return new OrmCollection([], { owned: true });
+        const rows = await this.getQuery().get();
+        return new OrmCollection(rows.all(), { owned: true });
+    }
+    async first() {
+        const parentId = this.#parentId();
+        if (parentId == null)
+            return null;
+        return this.getQuery().first();
+    }
+}
+/**
+ * HasOneThrough — same join as HasManyThrough, returns a single related model.
+ */
+export class HasOneThrough {
+    #many;
+    constructor(parent, related, through, firstKey, secondKey, localKey, secondLocalKey) {
+        this.#many = new HasManyThrough(parent, related, through, firstKey, secondKey, localKey, secondLocalKey);
+    }
+    getRelated() {
+        return this.#many.getRelated();
+    }
+    getThrough() {
+        return this.#many.getThrough();
+    }
+    getFirstKeyName() {
+        return this.#many.getFirstKeyName();
+    }
+    getSecondKeyName() {
+        return this.#many.getSecondKeyName();
+    }
+    getLocalKeyName() {
+        return this.#many.getLocalKeyName();
+    }
+    getSecondLocalKeyName() {
+        return this.#many.getSecondLocalKeyName();
+    }
+    /** Underlying many-through relation (for eager load reuse). */
+    asHasManyThrough() {
+        return this.#many;
+    }
+    getQuery() {
+        return this.#many.getQuery().limit(1);
+    }
+    async get() {
+        return this.first();
+    }
+    async first() {
+        return this.#many.first();
+    }
+}
+/** BelongsTo relation. */
+export class BelongsTo {
+    child;
+    related;
+    foreignKey;
+    ownerKey;
+    #baseQuery = null;
+    constructor(child, related, foreignKey, ownerKey) {
+        this.child = child;
+        this.related = related;
+        this.foreignKey = foreignKey;
+        this.ownerKey = ownerKey;
+    }
+    getRelated() {
+        return this.related;
+    }
+    getForeignKeyName() {
+        return this.foreignKey;
+    }
+    getOwnerKeyName() {
+        return this.ownerKey ?? this.related.primaryKey;
+    }
+    getQuery() {
+        if (!this.#baseQuery) {
+            const id = this.child[this.foreignKey];
+            if (id === undefined || id === null) {
+                this.#baseQuery = this.related
+                    .newQuery()
+                    .whereRaw("0 = 1");
+            }
+            else {
+                this.#baseQuery = this.related.where(this.getOwnerKeyName(), id);
+            }
+        }
+        return this.#baseQuery;
+    }
+    async get() {
+        return this.first();
+    }
+    async first() {
+        return this.getQuery().first();
+    }
+    /** Set the foreign key from a related model (or null). */
+    associate(model) {
+        const key = this.getOwnerKeyName();
+        this.child[this.foreignKey] = model
+            ? model[key]
+            : null;
+        return this;
+    }
+    /** Clear the foreign key. */
+    dissociate() {
+        this.child[this.foreignKey] = null;
+        return this;
+    }
+    /**
+     * Bump related parent's `updated_at` (query update).
+     * Honors `Model.withoutTouching` / `isIgnoringTouch` on the related class.
+     */
+    async touch() {
+        return this.#touchImpl(false);
+    }
+    /** Sync variant for Model sync-persist path. */
+    touchSync() {
+        return this.#touchImpl(true);
+    }
+    #touchImpl(sync) {
+        if (isIgnoringTouch(this.related))
+            return false;
+        if (this.related.timestamps === false)
+            return false;
+        const id = this.child[this.foreignKey];
+        if (id === undefined || id === null)
+            return false;
+        const conn = this.related.getConnection();
+        const now = nowForConnection(conn);
+        const ownerKey = this.getOwnerKeyName();
+        if (sync) {
+            if (typeof conn.runSync !== "function") {
+                throw new Error("BelongsTo.touchSync requires a sync connection.");
+            }
+            const dialect = conn.dialect;
+            const table = wrapSqlName(dialect, this.related.table);
+            const setCol = wrapSqlName(dialect, "updated_at");
+            const whereCol = wrapSqlName(dialect, ownerKey);
+            conn.runSync(`UPDATE ${table} SET ${setCol} = ? WHERE ${whereCol} = ?`, [now, id]);
+            return true;
+        }
+        return this.related
+            .newQuery()
+            .where(ownerKey, id)
+            .update({ updated_at: now })
+            .then(() => true);
+    }
+}
+/** BelongsToMany relation. */
+export class BelongsToMany {
+    parent;
+    related;
+    pivotTable;
+    foreignPivotKey;
+    relatedPivotKey;
+    #baseQuery = null;
+    #pivotColumns = [];
+    constructor(parent, related, pivotTable, foreignPivotKey, relatedPivotKey) {
+        this.parent = parent;
+        this.related = related;
+        this.pivotTable = pivotTable;
+        this.foreignPivotKey = foreignPivotKey;
+        this.relatedPivotKey = relatedPivotKey;
+    }
+    getRelated() {
+        return this.related;
+    }
+    getPivotTable() {
+        return this.pivotTable;
+    }
+    getForeignPivotKeyName() {
+        return this.foreignPivotKey;
+    }
+    getRelatedPivotKeyName() {
+        return this.relatedPivotKey;
+    }
+    getPivotColumns() {
+        return [...this.#pivotColumns];
+    }
+    /** Include extra pivot table columns on related models as `model.pivot`. */
+    withPivot(...columns) {
+        this.#baseQuery = null;
+        for (const col of columns.flat()) {
+            if (typeof col === "string" && col.trim() && !this.#pivotColumns.includes(col)) {
+                this.#pivotColumns.push(col);
+            }
+        }
+        return this;
+    }
+    #parentId() {
+        const parentKey = this.parent.constructor.primaryKey;
+        return this.parent[parentKey];
+    }
+    #pivotKeys() {
+        if (this.#pivotColumns.length === 0)
+            return [];
+        return pivotSelectKeys(this.foreignPivotKey, this.relatedPivotKey, this.#pivotColumns);
+    }
+    getQuery() {
+        if (!this.#baseQuery) {
+            const related = this.related;
+            let q = related
+                .newQuery()
+                .join(this.pivotTable, `${this.pivotTable}.${this.relatedPivotKey}`, "=", `${related.table}.${related.primaryKey}`)
+                .where(`${this.pivotTable}.${this.foreignPivotKey}`, this.#parentId())
+                .select(`${related.table}.*`);
+            for (const col of this.#pivotKeys()) {
+                q = q.selectRaw(`${this.pivotTable}.${col} as __pivot_${col}`);
+            }
+            this.#baseQuery = q;
+        }
+        return this.#baseQuery;
+    }
+    #hydratePivot(models) {
+        const keys = this.#pivotKeys();
+        if (keys.length === 0)
+            return;
+        for (const model of models) {
+            applyPivotAttributes(model, model, keys);
+        }
+    }
+    async get() {
+        const rows = await this.getQuery().get();
+        const models = rows.all();
+        this.#hydratePivot(models);
+        return new OrmCollection(models, { owned: true });
+    }
+    async first() {
+        const model = (await this.getQuery().first());
+        if (model)
+            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]);
+        }
+    }
+    async detach(ids) {
+        const parent = this.parent.constructor;
+        if (ids === undefined) {
+            await parent.getConnection().run(`DELETE FROM ${this.pivotTable} WHERE ${this.foreignPivotKey} = ?`, [this.#parentId()]);
+            return;
+        }
+        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]);
+        }
+    }
+    async sync(ids) {
+        await this.detach();
+        await this.attach(ids);
+    }
+    /** Attach missing ids only. */
+    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);
+    }
+    /** 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) {
+            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);
+    }
+}
+/** Polymorphic many-to-many (e.g. Contact → Role via `model_has_roles`). */
+export class MorphToMany {
+    parent;
+    related;
+    pivotTable;
+    foreignPivotKey;
+    relatedPivotKey;
+    morphTypeColumn;
+    morphTypes;
+    pivotTenantKey;
+    parentTenantKey;
+    constructor(parent, related, pivotTable, foreignPivotKey, relatedPivotKey, morphTypeColumn, morphTypes, pivotTenantKey, parentTenantKey) {
+        this.parent = parent;
+        this.related = related;
+        this.pivotTable = pivotTable;
+        this.foreignPivotKey = foreignPivotKey;
+        this.relatedPivotKey = relatedPivotKey;
+        this.morphTypeColumn = morphTypeColumn;
+        this.morphTypes = morphTypes;
+        this.pivotTenantKey = pivotTenantKey;
+        this.parentTenantKey = parentTenantKey;
+    }
+    getRelated() {
+        return this.related;
+    }
+    getPivotTable() {
+        return this.pivotTable;
+    }
+    getForeignPivotKeyName() {
+        return this.foreignPivotKey;
+    }
+    getRelatedPivotKeyName() {
+        return this.relatedPivotKey;
+    }
+    getMorphTypeColumn() {
+        return this.morphTypeColumn;
+    }
+    getMorphTypes() {
+        return [...this.morphTypes];
+    }
+    getPivotTenantKey() {
+        return this.pivotTenantKey;
+    }
+    getParentTenantKey() {
+        return this.parentTenantKey ?? this.pivotTenantKey;
+    }
+    /** Primary morph type written on attach (first configured type). */
+    getMorphType() {
+        return this.morphTypes[0] ?? morphTypeFor(this.parent.constructor);
+    }
+    #parentId() {
+        const parentKey = this.parent.constructor.primaryKey;
+        return this.parent[parentKey];
+    }
+    #tenantId() {
+        const key = this.getParentTenantKey();
+        if (!this.pivotTenantKey || !key)
+            return undefined;
+        return this.parent[key];
+    }
+    #morphTypePlaceholders() {
+        return this.morphTypes.map(() => "?").join(", ");
+    }
+    async get() {
+        const parent = this.parent.constructor;
+        const related = this.related;
+        const params = [this.#parentId(), ...this.morphTypes];
+        let tenantSql = "";
+        const tenantId = this.#tenantId();
+        if (this.pivotTenantKey && tenantId != null && tenantId !== "") {
+            tenantSql = ` AND ${this.pivotTable}.${this.pivotTenantKey} = ?`;
+            params.push(tenantId);
+        }
+        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}
+       WHERE ${this.pivotTable}.${this.foreignPivotKey} = ?
+         AND ${this.pivotTable}.${this.morphTypeColumn} IN (${this.#morphTypePlaceholders()})${tenantSql}`, params);
+        return new OrmCollection(rows.map((row) => new related(row)), { owned: true });
+    }
+    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]);
+            }
+        }
+    }
+    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] : [];
+        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;
+        }
+        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]);
+        }
+    }
+    async sync(ids) {
+        await this.detach();
+        await this.attach(ids);
+    }
+    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);
+    }
+    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);
+    }
+}
+/** Cached relation meta per model class (avoids `new model()` + related() per compile). */
+const relationMetaCache = new WeakMap();
+export function resolveRelation(model, relation) {
+    let byName = relationMetaCache.get(model);
+    if (!byName) {
+        byName = new Map();
+        relationMetaCache.set(model, byName);
+    }
+    if (byName.has(relation))
+        return byName.get(relation);
+    const instance = new model();
+    let rel;
+    try {
+        rel = instance.related(relation);
+    }
+    catch {
+        byName.set(relation, null);
+        return null;
+    }
+    let meta = null;
+    if (rel instanceof HasMany || rel instanceof HasOne) {
+        meta = {
+            kind: "has",
+            related: rel.getRelated(),
+            foreignKey: rel.getForeignKeyName(),
+            localKey: rel.getLocalKeyName(),
+        };
+    }
+    else if (rel instanceof BelongsTo) {
+        meta = {
+            kind: "belongsTo",
+            related: rel.getRelated(),
+            foreignKey: rel.getForeignKeyName(),
+            ownerKey: rel.getOwnerKeyName(),
+        };
+    }
+    else if (rel instanceof BelongsToMany) {
+        meta = {
+            kind: "belongsToMany",
+            related: rel.getRelated(),
+            pivotTable: rel.getPivotTable(),
+            foreignPivotKey: rel.getForeignPivotKeyName(),
+            relatedPivotKey: rel.getRelatedPivotKeyName(),
+            localKey: model.primaryKey,
+            pivotColumns: rel.getPivotColumns(),
+        };
+    }
+    else if (rel instanceof MorphToMany) {
+        meta = {
+            kind: "morphToMany",
+            related: rel.getRelated(),
+            pivotTable: rel.getPivotTable(),
+            foreignPivotKey: rel.getForeignPivotKeyName(),
+            relatedPivotKey: rel.getRelatedPivotKeyName(),
+            localKey: model.primaryKey,
+            morphTypeColumn: rel.getMorphTypeColumn(),
+            morphTypes: rel.getMorphTypes(),
+            pivotTenantKey: rel.getPivotTenantKey(),
+            parentTenantKey: rel.getParentTenantKey(),
+        };
+    }
+    else if (rel instanceof HasManyThrough) {
+        meta = {
+            kind: "hasManyThrough",
+            related: rel.getRelated(),
+            through: rel.getThrough(),
+            firstKey: rel.getFirstKeyName(),
+            secondKey: rel.getSecondKeyName(),
+            localKey: rel.getLocalKeyName(),
+            secondLocalKey: rel.getSecondLocalKeyName(),
+        };
+    }
+    else if (rel instanceof HasOneThrough) {
+        meta = {
+            kind: "hasOneThrough",
+            related: rel.getRelated(),
+            through: rel.getThrough(),
+            firstKey: rel.getFirstKeyName(),
+            secondKey: rel.getSecondKeyName(),
+            localKey: rel.getLocalKeyName(),
+            secondLocalKey: rel.getSecondLocalKeyName(),
+        };
+    }
+    byName.set(relation, meta);
+    return meta;
+}
+export async function countRelation(model, relation) {
+    const value = await aggregateRelation(model, relation, "count");
+    return Number(value ?? 0);
+}
+/** Run COUNT/SUM/AVG/MIN/MAX/EXISTS for a relation on one model instance. */
+export async function aggregateRelation(model, relation, fn, column) {
+    const ctor = model.constructor;
+    const meta = resolveRelation(ctor, relation);
+    if (!meta) {
+        throw new Error(`Unknown relation [${relation}] for load aggregate.`);
+    }
+    const id = model[ctor.primaryKey];
+    if (meta.kind === "has") {
+        let q = meta.related.where(meta.foreignKey, id);
+        if (fn === "exists")
+            return (await q.exists()) ? 1 : 0;
+        if (fn === "count")
+            return q.count();
+        if (fn === "sum")
+            return q.sum(column);
+        if (fn === "avg")
+            return q.avg(column);
+        if (fn === "min")
+            return q.min(column);
+        return q.max(column);
+    }
+    if (meta.kind === "belongsTo") {
+        const fk = model[meta.foreignKey];
+        if (fk == null)
+            return fn === "exists" ? 0 : fn === "count" || fn === "sum" ? 0 : null;
+        let q = meta.related.where(meta.ownerKey, fk);
+        if (fn === "exists")
+            return (await q.exists()) ? 1 : 0;
+        if (fn === "count")
+            return q.count();
+        if (fn === "sum")
+            return q.sum(column);
+        if (fn === "avg")
+            return q.avg(column);
+        if (fn === "min")
+            return q.min(column);
+        return q.max(column);
+    }
+    if (meta.kind === "hasManyThrough" || meta.kind === "hasOneThrough") {
+        // Through-relations have no pivot table — the SQL below only applies to
+        // belongsToMany/morphToMany. Previously this fell through unguarded and
+        // built a query with `undefined` in place of a pivot table/column.
+        throw new Error(`aggregateRelation() does not support "${meta.kind}" relations yet (relation [${relation}]).`);
+    }
+    const morphSql = meta.kind === "morphToMany"
+        ? ` AND ${meta.pivotTable}.${meta.morphTypeColumn} IN (${meta.morphTypes.map(() => "?").join(", ")})`
+        : "";
+    const morphParams = meta.kind === "morphToMany" ? [...meta.morphTypes] : [];
+    let tenantSql = "";
+    const tenantParams = [];
+    if (meta.kind === "morphToMany" && meta.pivotTenantKey && meta.parentTenantKey) {
+        const tenantId = model[meta.parentTenantKey];
+        if (tenantId != null && tenantId !== "") {
+            tenantSql = ` AND ${meta.pivotTable}.${meta.pivotTenantKey} = ?`;
+            tenantParams.push(tenantId);
+        }
+    }
+    const row = await ctor.getConnection().get(fn === "exists"
+        ? `SELECT 1 as v FROM ${meta.related.table}
+     INNER JOIN ${meta.pivotTable}
+       ON ${meta.pivotTable}.${meta.relatedPivotKey} = ${meta.related.table}.${meta.related.primaryKey}
+         WHERE ${meta.pivotTable}.${meta.foreignPivotKey} = ?${morphSql}${tenantSql} LIMIT 1`
+        : `SELECT ${fn === "count" ? "COUNT(*)" : `${fn.toUpperCase()}(${column ?? "*"})`} as v FROM ${meta.related.table}
+         INNER JOIN ${meta.pivotTable}
+           ON ${meta.pivotTable}.${meta.relatedPivotKey} = ${meta.related.table}.${meta.related.primaryKey}
+         WHERE ${meta.pivotTable}.${meta.foreignPivotKey} = ?${morphSql}${tenantSql}`, [id, ...morphParams, ...tenantParams]);
+    if (fn === "exists")
+        return row ? 1 : 0;
+    return row?.v ?? (fn === "count" || fn === "sum" ? 0 : null);
+}
+installRelationQueryForwarders([
+    MorphMany,
+    MorphOne,
+    HasMany,
+    HasOne,
+    HasManyThrough,
+    HasOneThrough,
+    BelongsTo,
+    BelongsToMany,
+], [MorphMany, MorphOne, HasMany, HasOne]);