@rudderjs/orm 1.9.0 → 1.9.2

package/dist/relations/pivot-accessors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pivot-accessors.js","sourceRoot":"","sources":["../../src/relations/pivot-accessors.ts"],"names":[],"mappings":"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"}

package/dist/relations/pivot-deferred.d.ts

@@ -0,0 +1,13 @@
+import type { QueryBuilder } from '@rudderjs/contracts';
+import { Model } from '../index.js';
+import type { BelongsToManyDef, BelongsToManyMeta, MorphParentDef, MorphToManyDef, MorphToManyMeta, MorphedByManyDef, MorphedByManyMeta } from './pivot-meta.js';
+/**
+ * Build a non-deferred QueryBuilder that fetches the polymorphic children
+ * of `self` for `morphMany` / `morphOne` declarations. Direct fetch — no
+ * pivot table — so no Proxy/deferred wrapping needed.
+ */
+export declare function morphParentQuery(self: Model, ctor: typeof Model, def: MorphParentDef, name: string): QueryBuilder<Model>;
+export declare function belongsToManyDeferredQb(Related: typeof Model, _def: BelongsToManyDef, meta: BelongsToManyMeta, parentVal: unknown): QueryBuilder<Model>;
+export declare function morphToManyDeferredQb(Related: typeof Model, _def: MorphToManyDef, meta: MorphToManyMeta, parentVal: unknown): QueryBuilder<Model>;
+export declare function morphedByManyDeferredQb(Related: typeof Model, _def: MorphedByManyDef, meta: MorphedByManyMeta, parentVal: unknown): QueryBuilder<Model>;
+//# sourceMappingURL=pivot-deferred.d.ts.map

package/dist/relations/pivot-deferred.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pivot-deferred.d.ts","sourceRoot":"","sources":["../../src/relations/pivot-deferred.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AACvD,OAAO,EAAE,KAAK,EAAiB,MAAM,aAAa,CAAA;AAClD,OAAO,KAAK,EACV,gBAAgB,EAChB,iBAAiB,EACjB,cAAc,EACd,cAAc,EACd,eAAe,EACf,gBAAgB,EAChB,iBAAiB,EAClB,MAAM,iBAAiB,CAAA;AAIxB;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,KAAK,EACX,IAAI,EAAE,OAAO,KAAK,EAClB,GAAG,EAAG,cAAc,EACpB,IAAI,EAAE,MAAM,GACX,YAAY,CAAC,KAAK,CAAC,CAWrB;AAuJD,wBAAgB,uBAAuB,CACrC,OAAO,EAAI,OAAO,KAAK,EACvB,IAAI,EAAO,gBAAgB,EAC3B,IAAI,EAAO,iBAAiB,EAC5B,SAAS,EAAE,OAAO,GACjB,YAAY,CAAC,KAAK,CAAC,CA0BrB;AAED,wBAAgB,qBAAqB,CACnC,OAAO,EAAI,OAAO,KAAK,EACvB,IAAI,EAAO,cAAc,EACzB,IAAI,EAAO,eAAe,EAC1B,SAAS,EAAE,OAAO,GACjB,YAAY,CAAC,KAAK,CAAC,CAyBrB;AAED,wBAAgB,uBAAuB,CACrC,OAAO,EAAI,OAAO,KAAK,EACvB,IAAI,EAAO,gBAAgB,EAC3B,IAAI,EAAO,iBAAiB,EAC5B,SAAS,EAAE,OAAO,GACjB,YAAY,CAAC,KAAK,CAAC,CAyBrB"}

package/dist/relations/pivot-deferred.js

@@ -0,0 +1,210 @@
+import { ModelRegistry } from '../index.js';
+// ─── morphMany / morphOne read query ───────────────────────
+/**
+ * Build a non-deferred QueryBuilder that fetches the polymorphic children
+ * of `self` for `morphMany` / `morphOne` declarations. Direct fetch — no
+ * pivot table — so no Proxy/deferred wrapping needed.
+ */
+export function morphParentQuery(self, ctor, def, name) {
+    const Related = def.model();
+    const idCol = `${def.morphName}Id`;
+    const typeCol = `${def.morphName}Type`;
+    const localCol = def.localKey ?? ctor.primaryKey;
+    const localVal = self[localCol];
+    const typeVal = def.morphType ?? ctor.morphAlias ?? ctor.name;
+    if (localVal === undefined || localVal === null) {
+        throw new Error(`[RudderJS ORM] Cannot resolve "${name}" on ${ctor.name} — ${localCol} is unset.`);
+    }
+    return Related.where(idCol, localVal).where(typeCol, typeVal);
+}
+// ─── Deferred Proxy machinery ──────────────────────────────
+const CHAIN_METHODS = new Set([
+    'where', 'orWhere', 'orderBy', 'limit', 'offset', 'with', 'withTrashed', 'onlyTrashed',
+]);
+const TERMINAL_METHODS = new Set([
+    'first', 'find', 'get', 'all', 'count', 'paginate',
+]);
+const UNSUPPORTED_TERMINALS = new Set([
+    'create', 'update', 'delete', 'restore', 'forceDelete', 'increment', 'decrement', 'insertMany', 'deleteAll', 'updateAll',
+]);
+function replayChain(q, recorded) {
+    let cur = q;
+    for (const [m, args] of recorded) {
+        const fn = cur[m];
+        if (fn)
+            cur = fn.apply(cur, args);
+    }
+    return cur;
+}
+/**
+ * Build a deferred QueryBuilder that runs the pivot lookup on terminal
+ * evaluation. Chain methods (where/orderBy/etc.) are recorded and replayed
+ * against `Related.where(relatedKey, 'IN', ids)` once ids are resolved.
+ *
+ * Mutations (`create`/`update`/`delete`/`insertMany`/`deleteAll`) throw —
+ * write the pivot via `belongsToMany().attach/detach/sync` and write the
+ * related rows via the related model directly.
+ */
+function makeDeferredProxy(buildResolved, recorded, relationKind, hooks = {}) {
+    const proxy = new Proxy({}, {
+        get(_t, prop) {
+            const name = String(prop);
+            if (name === 'withPivot') {
+                return (...cols) => {
+                    if (cols.length === 0) {
+                        throw new Error('[RudderJS ORM] withPivot() requires at least one column name.');
+                    }
+                    hooks.onWithPivot?.(cols);
+                    return proxy;
+                };
+            }
+            if (CHAIN_METHODS.has(name)) {
+                return (...args) => {
+                    recorded.push([name, args]);
+                    return proxy;
+                };
+            }
+            if (TERMINAL_METHODS.has(name)) {
+                return async (...args) => {
+                    const q = await buildResolved();
+                    const fn = q[name];
+                    const raw = fn ? await fn.apply(q, args) : undefined;
+                    return hooks.postProcess ? hooks.postProcess(raw, name) : raw;
+                };
+            }
+            if (UNSUPPORTED_TERMINALS.has(name)) {
+                return () => {
+                    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;
+        },
+    });
+    return proxy;
+}
+// ─── Pivot stamping (read-side) ────────────────────────────
+/**
+ * Stamp `row.pivot = { col: value, ... }` for every row in `rows` whose
+ * `relatedKey` matches a pivot row. Used by the three deferred QBs after the
+ * second-step `Related` query resolves. Mutates rows in place; rows whose
+ * pivot row is absent are left untouched (`pivot` stays undefined).
+ */
+function stampPivotOnRows(rows, relatedKey, pivotRows, relatedPivotKey, pivotColumns) {
+    if (pivotColumns.length === 0)
+        return;
+    const byId = new Map();
+    for (const p of pivotRows)
+        byId.set(p[relatedPivotKey], p);
+    for (const row of rows) {
+        if (row === null || row === undefined)
+            continue;
+        const pivot = byId.get(row[relatedKey]);
+        if (!pivot)
+            continue;
+        const projected = {};
+        for (const col of pivotColumns)
+            projected[col] = pivot[col];
+        row['pivot'] = projected;
+    }
+}
+/**
+ * Stamp `pivot` onto a single result (object or array). Used by the deferred
+ * proxy's `postProcess` hook — the terminal name (`first` / `find` / `get` /
+ * `all` / `paginate`) determines whether to walk the result.
+ */
+function stampPivotOnResult(result, terminal, relatedKey, pivotRows, relatedPivotKey, pivotColumns) {
+    if (pivotColumns.length === 0)
+        return result;
+    if (result === null || result === undefined)
+        return result;
+    if (terminal === 'first' || terminal === 'find') {
+        stampPivotOnRows([result], relatedKey, pivotRows, relatedPivotKey, pivotColumns);
+        return result;
+    }
+    if (terminal === 'get' || terminal === 'all') {
+        stampPivotOnRows(result, relatedKey, pivotRows, relatedPivotKey, pivotColumns);
+        return result;
+    }
+    if (terminal === 'paginate') {
+        const page = result;
+        stampPivotOnRows(page.data, relatedKey, pivotRows, relatedPivotKey, pivotColumns);
+        return result;
+    }
+    return result;
+}
+// ─── Public deferred-QB builders ───────────────────────────
+export function belongsToManyDeferredQb(Related, _def, meta, parentVal) {
+    const recorded = [];
+    const pivotColumns = [];
+    let lastPivotRows = [];
+    const buildResolved = async () => {
+        const adapter = ModelRegistry.getAdapter();
+        const pivotRows = await adapter
+            .query(meta.pivotTable)
+            .where(meta.foreignPivotKey, parentVal)
+            .get();
+        lastPivotRows = pivotRows;
+        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', {
+        onWithPivot(cols) { pivotColumns.push(...cols); },
+        postProcess(result, terminal) {
+            return stampPivotOnResult(result, terminal, meta.relatedKey, lastPivotRows, meta.relatedPivotKey, pivotColumns);
+        },
+    });
+}
+export function morphToManyDeferredQb(Related, _def, meta, parentVal) {
+    const recorded = [];
+    const pivotColumns = [];
+    let lastPivotRows = [];
+    const buildResolved = async () => {
+        const adapter = ModelRegistry.getAdapter();
+        const pivotRows = await adapter
+            .query(meta.pivotTable)
+            .where(meta.foreignPivotKey, parentVal)
+            .where(meta.morphTypeKey, meta.morphTypeValue)
+            .get();
+        lastPivotRows = pivotRows;
+        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', {
+        onWithPivot(cols) { pivotColumns.push(...cols); },
+        postProcess(result, terminal) {
+            return stampPivotOnResult(result, terminal, meta.relatedKey, lastPivotRows, meta.relatedPivotKey, pivotColumns);
+        },
+    });
+}
+export function morphedByManyDeferredQb(Related, _def, meta, parentVal) {
+    const recorded = [];
+    const pivotColumns = [];
+    let lastPivotRows = [];
+    const buildResolved = async () => {
+        const adapter = ModelRegistry.getAdapter();
+        const pivotRows = await adapter
+            .query(meta.pivotTable)
+            .where(meta.foreignPivotKey, parentVal)
+            .where(meta.morphTypeKey, meta.morphTypeValue)
+            .get();
+        lastPivotRows = pivotRows;
+        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', {
+        onWithPivot(cols) { pivotColumns.push(...cols); },
+        postProcess(result, terminal) {
+            return stampPivotOnResult(result, terminal, meta.relatedKey, lastPivotRows, meta.relatedPivotKey, pivotColumns);
+        },
+    });
+}
+//# sourceMappingURL=pivot-deferred.js.map

package/dist/relations/pivot-deferred.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pivot-deferred.js","sourceRoot":"","sources":["../../src/relations/pivot-deferred.ts"],"names":[],"mappings":"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"}

package/dist/relations/pivot-meta.d.ts

@@ -0,0 +1,50 @@
+import type { Model, RelationDefinition } from '../index.js';
+export type BelongsToManyDef = Extract<RelationDefinition, {
+    type: 'belongsToMany';
+}>;
+export type MorphParentDef = Extract<RelationDefinition, {
+    type: 'morphMany' | 'morphOne';
+}>;
+export type MorphToManyDef = Extract<RelationDefinition, {
+    type: 'morphToMany';
+}>;
+export type MorphedByManyDef = Extract<RelationDefinition, {
+    type: 'morphedByMany';
+}>;
+export interface BelongsToManyMeta {
+    pivotTable: string;
+    foreignPivotKey: string;
+    relatedPivotKey: string;
+    parentKey: string;
+    relatedKey: string;
+}
+export interface MorphToManyMeta {
+    pivotTable: string;
+    /** `{morphName}Id` — pivot column for the parent (the polymorphic side). */
+    foreignPivotKey: string;
+    /** `{morphName}Type` — discriminator column on the pivot. */
+    morphTypeKey: string;
+    /** Discriminator value to write/match for the parent class. */
+    morphTypeValue: string;
+    /** Pivot column for the related (strong) row. */
+    relatedPivotKey: string;
+    parentKey: string;
+    relatedKey: string;
+}
+export interface MorphedByManyMeta {
+    pivotTable: string;
+    /** `{morphName}Id` — pivot column for the related (polymorphic-side) row. */
+    relatedPivotKey: string;
+    /** `{morphName}Type` — discriminator column on the pivot. */
+    morphTypeKey: string;
+    /** Discriminator value used to match rows that point at Related. */
+    morphTypeValue: string;
+    /** Pivot column for the parent (strong) row. */
+    foreignPivotKey: string;
+    parentKey: string;
+    relatedKey: string;
+}
+export declare function resolveBelongsToManyMeta(Parent: typeof Model, Related: typeof Model, def: BelongsToManyDef): BelongsToManyMeta;
+export declare function resolveMorphToManyMeta(Parent: typeof Model, Related: typeof Model, def: MorphToManyDef): MorphToManyMeta;
+export declare function resolveMorphedByManyMeta(Parent: typeof Model, Related: typeof Model, def: MorphedByManyDef): MorphedByManyMeta;
+//# sourceMappingURL=pivot-meta.d.ts.map

package/dist/relations/pivot-meta.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pivot-meta.d.ts","sourceRoot":"","sources":["../../src/relations/pivot-meta.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAA;AAK5D,MAAM,MAAM,gBAAgB,GAAG,OAAO,CAAC,kBAAkB,EAAE;IAAE,IAAI,EAAE,eAAe,CAAA;CAAE,CAAC,CAAA;AACrF,MAAM,MAAM,cAAc,GAAK,OAAO,CAAC,kBAAkB,EAAE;IAAE,IAAI,EAAE,WAAW,GAAG,UAAU,CAAA;CAAE,CAAC,CAAA;AAC9F,MAAM,MAAM,cAAc,GAAK,OAAO,CAAC,kBAAkB,EAAE;IAAE,IAAI,EAAE,aAAa,CAAA;CAAE,CAAC,CAAA;AACnF,MAAM,MAAM,gBAAgB,GAAG,OAAO,CAAC,kBAAkB,EAAE;IAAE,IAAI,EAAE,eAAe,CAAA;CAAE,CAAC,CAAA;AAIrF,MAAM,WAAW,iBAAiB;IAChC,UAAU,EAAO,MAAM,CAAA;IACvB,eAAe,EAAE,MAAM,CAAA;IACvB,eAAe,EAAE,MAAM,CAAA;IACvB,SAAS,EAAQ,MAAM,CAAA;IACvB,UAAU,EAAO,MAAM,CAAA;CACxB;AAED,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAO,MAAM,CAAA;IACvB,4EAA4E;IAC5E,eAAe,EAAE,MAAM,CAAA;IACvB,6DAA6D;IAC7D,YAAY,EAAK,MAAM,CAAA;IACvB,+DAA+D;IAC/D,cAAc,EAAG,MAAM,CAAA;IACvB,iDAAiD;IACjD,eAAe,EAAE,MAAM,CAAA;IACvB,SAAS,EAAQ,MAAM,CAAA;IACvB,UAAU,EAAO,MAAM,CAAA;CACxB;AAED,MAAM,WAAW,iBAAiB;IAChC,UAAU,EAAO,MAAM,CAAA;IACvB,6EAA6E;IAC7E,eAAe,EAAE,MAAM,CAAA;IACvB,6DAA6D;IAC7D,YAAY,EAAK,MAAM,CAAA;IACvB,oEAAoE;IACpE,cAAc,EAAG,MAAM,CAAA;IACvB,gDAAgD;IAChD,eAAe,EAAE,MAAM,CAAA;IACvB,SAAS,EAAQ,MAAM,CAAA;IACvB,UAAU,EAAO,MAAM,CAAA;CACxB;AAID,wBAAgB,wBAAwB,CACtC,MAAM,EAAG,OAAO,KAAK,EACrB,OAAO,EAAE,OAAO,KAAK,EACrB,GAAG,EAAM,gBAAgB,GACxB,iBAAiB,CAQnB;AAED,wBAAgB,sBAAsB,CACpC,MAAM,EAAG,OAAO,KAAK,EACrB,OAAO,EAAE,OAAO,KAAK,EACrB,GAAG,EAAM,cAAc,GACtB,eAAe,CAUjB;AAED,wBAAgB,wBAAwB,CACtC,MAAM,EAAG,OAAO,KAAK,EACrB,OAAO,EAAE,OAAO,KAAK,EACrB,GAAG,EAAM,gBAAgB,GACxB,iBAAiB,CAUnB"}

package/dist/relations/pivot-meta.js

@@ -0,0 +1,34 @@
+import { camelHead } from '../utils.js';
+// ─── Resolvers ─────────────────────────────────────────────
+export function resolveBelongsToManyMeta(Parent, Related, def) {
+    return {
+        pivotTable: def.pivotTable,
+        foreignPivotKey: def.foreignPivotKey ?? `${camelHead(Parent.name)}Id`,
+        relatedPivotKey: def.relatedPivotKey ?? `${camelHead(Related.name)}Id`,
+        parentKey: def.parentKey ?? Parent.primaryKey,
+        relatedKey: def.relatedKey ?? Related.primaryKey,
+    };
+}
+export 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,
+    };
+}
+export 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,
+    };
+}
+//# sourceMappingURL=pivot-meta.js.map

package/dist/relations/pivot-meta.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pivot-meta.js","sourceRoot":"","sources":["../../src/relations/pivot-meta.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AA+CvC,8DAA8D;AAE9D,MAAM,UAAU,wBAAwB,CACtC,MAAqB,EACrB,OAAqB,EACrB,GAAyB;IAEzB,OAAO;QACL,UAAU,EAAO,GAAG,CAAC,UAAU;QAC/B,eAAe,EAAE,GAAG,CAAC,eAAe,IAAI,GAAG,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI;QACrE,eAAe,EAAE,GAAG,CAAC,eAAe,IAAI,GAAG,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI;QACtE,SAAS,EAAQ,GAAG,CAAC,SAAS,IAAU,MAAM,CAAC,UAAU;QACzD,UAAU,EAAO,GAAG,CAAC,UAAU,IAAS,OAAO,CAAC,UAAU;KAC3D,CAAA;AACH,CAAC;AAED,MAAM,UAAU,sBAAsB,CACpC,MAAqB,EACrB,OAAqB,EACrB,GAAuB;IAEvB,OAAO;QACL,UAAU,EAAO,GAAG,CAAC,UAAU;QAC/B,eAAe,EAAE,GAAG,GAAG,CAAC,SAAS,IAAI;QACrC,YAAY,EAAK,GAAG,GAAG,CAAC,SAAS,MAAM;QACvC,cAAc,EAAG,GAAG,CAAC,SAAS,IAAI,MAAM,CAAC,UAAU,IAAI,MAAM,CAAC,IAAI;QAClE,eAAe,EAAE,GAAG,CAAC,eAAe,IAAI,GAAG,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI;QACtE,SAAS,EAAQ,GAAG,CAAC,SAAS,IAAU,MAAM,CAAC,UAAU;QACzD,UAAU,EAAO,GAAG,CAAC,UAAU,IAAS,OAAO,CAAC,UAAU;KAC3D,CAAA;AACH,CAAC;AAED,MAAM,UAAU,wBAAwB,CACtC,MAAqB,EACrB,OAAqB,EACrB,GAAyB;IAEzB,OAAO;QACL,UAAU,EAAO,GAAG,CAAC,UAAU;QAC/B,eAAe,EAAE,GAAG,GAAG,CAAC,SAAS,IAAI;QACrC,YAAY,EAAK,GAAG,GAAG,CAAC,SAAS,MAAM;QACvC,cAAc,EAAG,GAAG,CAAC,SAAS,IAAI,OAAO,CAAC,UAAU,IAAI,OAAO,CAAC,IAAI;QACpE,eAAe,EAAE,GAAG,CAAC,eAAe,IAAI,GAAG,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI;QACrE,SAAS,EAAQ,GAAG,CAAC,SAAS,IAAU,MAAM,CAAC,UAAU;QACzD,UAAU,EAAO,GAAG,CAAC,UAAU,IAAS,OAAO,CAAC,UAAU;KAC3D,CAAA;AACH,CAAC"}

package/dist/relations/where-has.d.ts

@@ -0,0 +1,53 @@
+import type { QueryBuilder, RelationExistencePredicate, WhereClause } from '@rudderjs/contracts';
+import type { Model, RelationDefinition } from '../index.js';
+/**
+ * Variant shape of `RelationDefinition` for `hasOne | hasMany | belongsTo`.
+ * Those three live in a single union member with a literal-union `type`
+ * field, so `Extract<RelationDefinition, { type: 'belongsTo' }>` evaluates
+ * to `never` (the wider literal union doesn't extend the narrower one). We
+ * model the merged variant explicitly and runtime-check `type === 'belongsTo'`.
+ */
+export type HasOrBelongsToDef = Exclude<RelationDefinition, {
+    type: 'belongsToMany' | 'morphMany' | 'morphOne' | 'morphTo' | 'morphToMany' | 'morphedByMany';
+}>;
+/**
+ * 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.
+ */
+export declare function captureConstraintWheres(constrain: (q: QueryBuilder<Model>) => void): WhereClause[];
+/**
+ * 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.
+ */
+export declare function resolveBelongsToFor(Self: typeof Model, ParentCtor: typeof Model, relation?: string): HasOrBelongsToDef;
+/**
+ * Build the {@link RelationExistencePredicate} for a relation declared on
+ * `Parent`. `morphTo` is rejected before reaching this function (the related
+ * table is dynamic).
+ */
+export declare function buildRelationPredicate(Parent: typeof Model, relation: string, def: Exclude<RelationDefinition, {
+    type: 'morphTo';
+}>, exists: boolean, constraintWheres: WhereClause[]): RelationExistencePredicate;
+/**
+ * Build the predicate for a relation declared on `Parent` 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.
+ */
+export declare function attachWhereHas<TQ>(Parent: typeof Model, q: QueryBuilder<TQ>, relation: string, exists: boolean, constrain?: (q: QueryBuilder<Model>) => void): QueryBuilder<TQ>;
+/**
+ * `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).
+ */
+export declare function attachWithWhereHas<TQ>(Parent: typeof Model, q: QueryBuilder<TQ>, relation: string, constrain?: (q: QueryBuilder<Model>) => void): QueryBuilder<TQ>;
+export declare function attachWhereBelongsTo<TQ>(Self: typeof Model, q: QueryBuilder<TQ>, parent: Model, relation?: string): QueryBuilder<TQ>;
+//# sourceMappingURL=where-has.d.ts.map

package/dist/relations/where-has.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"where-has.d.ts","sourceRoot":"","sources":["../../src/relations/where-has.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,YAAY,EACZ,0BAA0B,EAC1B,WAAW,EAEZ,MAAM,qBAAqB,CAAA;AAC5B,OAAO,KAAK,EAAE,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAA;AAQ5D;;;;;;GAMG;AACH,MAAM,MAAM,iBAAiB,GAAG,OAAO,CACrC,kBAAkB,EAClB;IAAE,IAAI,EAAE,eAAe,GAAG,WAAW,GAAG,UAAU,GAAG,SAAS,GAAG,aAAa,GAAG,eAAe,CAAA;CAAE,CACnG,CAAA;AAID;;;;;GAKG;AACH,wBAAgB,uBAAuB,CACrC,SAAS,EAAE,CAAC,CAAC,EAAE,YAAY,CAAC,KAAK,CAAC,KAAK,IAAI,GAC1C,WAAW,EAAE,CA2Cf;AAID;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAQ,OAAO,KAAK,EACxB,UAAU,EAAE,OAAO,KAAK,EACxB,QAAQ,CAAC,EAAG,MAAM,GACjB,iBAAiB,CA6BnB;AAID;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAY,OAAO,KAAK,EAC9B,QAAQ,EAAU,MAAM,EACxB,GAAG,EAAe,OAAO,CAAC,kBAAkB,EAAE;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,CAAC,EAClE,MAAM,EAAY,OAAO,EACzB,gBAAgB,EAAE,WAAW,EAAE,GAC9B,0BAA0B,CAgG5B;AAID;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,EAAE,EAC/B,MAAM,EAAK,OAAO,KAAK,EACvB,CAAC,EAAU,YAAY,CAAC,EAAE,CAAC,EAC3B,QAAQ,EAAG,MAAM,EACjB,MAAM,EAAK,OAAO,EAClB,SAAS,CAAC,EAAE,CAAC,CAAC,EAAE,YAAY,CAAC,KAAK,CAAC,KAAK,IAAI,GAC3C,YAAY,CAAC,EAAE,CAAC,CAelB;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,EAAE,EACnC,MAAM,EAAK,OAAO,KAAK,EACvB,CAAC,EAAU,YAAY,CAAC,EAAE,CAAC,EAC3B,QAAQ,EAAG,MAAM,EACjB,SAAS,CAAC,EAAE,CAAC,CAAC,EAAE,YAAY,CAAC,KAAK,CAAC,KAAK,IAAI,GAC3C,YAAY,CAAC,EAAE,CAAC,CAalB;AAED,wBAAgB,oBAAoB,CAAC,EAAE,EACrC,IAAI,EAAO,OAAO,KAAK,EACvB,CAAC,EAAU,YAAY,CAAC,EAAE,CAAC,EAC3B,MAAM,EAAK,KAAK,EAChB,QAAQ,CAAC,EAAE,MAAM,GAChB,YAAY,CAAC,EAAE,CAAC,CAalB"}