@bunyad/orm 0.2.0-beta.1 → 0.2.0-beta.3

package/README.md

@@ -81,11 +81,10 @@ Pick one and install it next to `@bunyad/database`: `better-sqlite3`, `pg` or `m
 
 - Express on Node: [`docs/examples/orm-node-express`](https://github.com/bunyadjs/framework/tree/main/docs/examples/orm-node-express)
 - Next.js (server-only, one shared pool): [`docs/examples/orm-node-next`](https://github.com/bunyadjs/framework/tree/main/docs/examples/orm-node-next)
-- NestJS: `@bunyad/nestjs` (`BunyadOrmModule`), in the monorepo and not published yet.
 
 ## Status
 
-Beta scope: SQLite, PostgreSQL and MySQL are tested on Bun and Node 20+ (the PostgreSQL and MySQL suites run when `BUNYAD_TEST_POSTGRES_URL` / `BUNYAD_TEST_MYSQL_URL` are set). SQL Server is experimental and needs `mssql` installed. Conditional aggregate helpers (`sumCase`, `countCase`) are not available yet.
+Beta scope: SQLite, PostgreSQL and MySQL are tested on Bun and Node 20+ (the PostgreSQL and MySQL suites run when `BUNYAD_TEST_POSTGRES_URL` / `BUNYAD_TEST_MYSQL_URL` are set). SQL Server is experimental and needs `mssql` installed.
 
 ## License
 

package/dist/casts.d.ts

@@ -15,21 +15,33 @@ export declare class Attribute {
     }): Attribute;
 }
 /** Built-in cast type names. */
-export type CastType = "boolean" | "bool" | "number" | "integer" | "int" | "float" | "double" | "real" | "decimal" | "bigint" | "string" | "json" | "date" | "datetime" | "array" | "collection" | "encrypted" | "encrypted:array" | "encrypted:json" | "encrypted:collection" | "hashed";
+export type CastType = "boolean" | "bool" | "number" | "integer" | "int" | "float" | "double" | "real" | "decimal" | "bigint" | "string" | "json" | "date" | "datetime" | "array" | "collection" | "encrypted" | "encrypted:array" | "encrypted:json" | "encrypted:collection" | "hashed" | "object" | "immutable_date" | "immutable_datetime" | `decimal:${number}` | `date:${string}` | `datetime:${string}` | `immutable_date:${string}` | `immutable_datetime:${string}`;
 /**
  * A TypeScript string/number enum object (or similar value map).
  */
 export type EnumCast = Record<string, string | number>;
 /** Anything accepted in `casts` / `casts()`. */
 export type CastDefinition = CastType | EnumCast | Attribute;
+/** Base cast + optional argument for the parameterized forms (`decimal:2`, `date:Y-m-d`). */
+export type ParsedCast = {
+    type: BaseCastType;
+    arg?: string;
+};
+type BaseCastType = "boolean" | "bool" | "number" | "integer" | "int" | "float" | "double" | "real" | "decimal" | "bigint" | "string" | "json" | "date" | "datetime" | "array" | "collection" | "encrypted" | "encrypted:array" | "encrypted:json" | "encrypted:collection" | "hashed";
+export declare function parseCast(definition: string): ParsedCast | null;
 export declare function isCastType(value: unknown): value is CastType;
+/**
+ * Format a Date with a PHP-style `date()` format (`Y-m-d H:i:s`). Used by
+ * `date:FORMAT` / `datetime:FORMAT` casts when a model is serialized. UTC.
+ */
+export declare function formatPhpDate(date: Date, format: string): string;
 export declare function isAttribute(value: unknown): value is Attribute;
 export declare function isEnumCast(value: unknown): value is EnumCast;
 /** Async bcrypt for the `hashed` cast (same output as the sync path, off the event loop). */
 export declare function hashCastValue(value: string): Promise<string>;
 export declare function isAlreadyHashed(value: string): boolean;
-export declare function castFromStorage(value: unknown, type: CastType): unknown;
-export declare function castToStorage(value: unknown, type: CastType, driver?: string): unknown;
+export declare function castFromStorage(value: unknown, definition: CastType): unknown;
+export declare function castToStorage(value: unknown, definition: CastType, driver?: string): unknown;
 export declare function enumFromStorage(value: unknown, enumObj: EnumCast): unknown;
 export declare function enumToStorage(value: unknown, enumObj: EnumCast): unknown;
 /** Cast JSON column to a `Collection`. */
@@ -48,3 +60,4 @@ export declare const AsFluent: Attribute;
 export declare const AsEnumCollection: {
     of(enumObj: EnumCast): Attribute;
 };
+export {};

package/dist/casts.js

@@ -38,6 +38,18 @@ const CAST_TYPE_SET = new Set([
     "encrypted:collection",
     "hashed",
 ]);
+/** Fixed-digit string rounded half away from zero on the decimal text, so `1.005` gives `1.01`. */
+function toFixedDecimal(value, digits) {
+    const n = toNumber(value);
+    if (!Number.isFinite(n) || digits < 0 || digits > 20)
+        return n.toFixed(Math.max(0, digits));
+    const sign = n < 0 ? -1 : 1;
+    const shifted = Number(`${Math.abs(n)}e${digits}`);
+    if (!Number.isFinite(shifted))
+        return n.toFixed(digits);
+    const rounded = Number(`${Math.round(shifted)}e-${digits}`);
+    return (sign * rounded).toFixed(digits);
+}
 function toNumber(value) {
     if (typeof value === "number") {
         return Number.isFinite(value) ? value : 0;
@@ -75,8 +87,122 @@ function toBoolean(value) {
     }
     return Boolean(value);
 }
+const parsedCastCache = new Map();
+export function parseCast(definition) {
+    const hit = parsedCastCache.get(definition);
+    if (hit !== undefined)
+        return hit;
+    let parsed = null;
+    if (CAST_TYPE_SET.has(definition)) {
+        parsed = { type: definition };
+    }
+    else if (definition === "object") {
+        parsed = { type: "json" };
+    }
+    else if (definition === "immutable_date") {
+        parsed = { type: "date" };
+    }
+    else if (definition === "immutable_datetime") {
+        parsed = { type: "datetime" };
+    }
+    else {
+        const colon = definition.indexOf(":");
+        if (colon > 0) {
+            const head = definition.slice(0, colon);
+            const arg = definition.slice(colon + 1);
+            if (head === "decimal" && /^\d+$/.test(arg))
+                parsed = { type: "decimal", arg };
+            else if ((head === "date" || head === "immutable_date") && arg)
+                parsed = { type: "date", arg };
+            else if ((head === "datetime" || head === "immutable_datetime") && arg)
+                parsed = { type: "datetime", arg };
+        }
+    }
+    parsedCastCache.set(definition, parsed);
+    return parsed;
+}
 export function isCastType(value) {
-    return typeof value === "string" && CAST_TYPE_SET.has(value);
+    return typeof value === "string" && parseCast(value) !== null;
+}
+/**
+ * Format a Date with a PHP-style `date()` format (`Y-m-d H:i:s`). Used by
+ * `date:FORMAT` / `datetime:FORMAT` casts when a model is serialized. UTC.
+ */
+export function formatPhpDate(date, format) {
+    const pad = (n, w = 2) => String(n).padStart(w, "0");
+    const months = ["January", "February", "March", "April", "May", "June", "July", "August", "September", "October", "November", "December"];
+    const days = ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"];
+    const h24 = date.getUTCHours();
+    const h12 = h24 % 12 === 0 ? 12 : h24 % 12;
+    let out = "";
+    for (let i = 0; i < format.length; i++) {
+        const ch = format[i];
+        switch (ch) {
+            case "\\":
+                i++;
+                out += format[i] ?? "";
+                break;
+            case "d":
+                out += pad(date.getUTCDate());
+                break;
+            case "j":
+                out += date.getUTCDate();
+                break;
+            case "m":
+                out += pad(date.getUTCMonth() + 1);
+                break;
+            case "n":
+                out += date.getUTCMonth() + 1;
+                break;
+            case "Y":
+                out += pad(date.getUTCFullYear(), 4);
+                break;
+            case "y":
+                out += pad(date.getUTCFullYear() % 100);
+                break;
+            case "H":
+                out += pad(h24);
+                break;
+            case "G":
+                out += h24;
+                break;
+            case "h":
+                out += pad(h12);
+                break;
+            case "g":
+                out += h12;
+                break;
+            case "i":
+                out += pad(date.getUTCMinutes());
+                break;
+            case "s":
+                out += pad(date.getUTCSeconds());
+                break;
+            case "A":
+                out += h24 < 12 ? "AM" : "PM";
+                break;
+            case "a":
+                out += h24 < 12 ? "am" : "pm";
+                break;
+            case "U":
+                out += Math.floor(date.getTime() / 1000);
+                break;
+            case "M":
+                out += months[date.getUTCMonth()].slice(0, 3);
+                break;
+            case "F":
+                out += months[date.getUTCMonth()];
+                break;
+            case "D":
+                out += days[date.getUTCDay()].slice(0, 3);
+                break;
+            case "l":
+                out += days[date.getUTCDay()];
+                break;
+            default: out += ch;
+        }
+    }
+    return out;
 }
 export function isAttribute(value) {
     return value instanceof Attribute;
@@ -125,9 +251,15 @@ function decryptPayload(value) {
         return String(value ?? "");
     return Crypt.decrypt(value);
 }
-export function castFromStorage(value, type) {
+export function castFromStorage(value, definition) {
+    const parsed = parseCast(definition);
+    const type = parsed.type;
     if (value == null)
         return value;
+    // `decimal:2` keeps money-like values exact as a fixed-digit string.
+    if (type === "decimal" && parsed.arg !== undefined) {
+        return toFixedDecimal(value, Number(parsed.arg));
+    }
     switch (type) {
         case "boolean":
         case "bool":
@@ -147,6 +279,8 @@ export function castFromStorage(value, type) {
             return String(value);
         case "json":
         case "array":
+            if (value === "")
+                return null;
             return typeof value === "string" ? JSON.parse(value) : value;
         case "collection": {
             // From the database (JSON text), or already in memory: `fill()` passes a Collection or array.
@@ -174,9 +308,19 @@ export function castFromStorage(value, type) {
             return value;
     }
 }
-export function castToStorage(value, type, driver) {
+function assertValidDate(value, cast) {
+    if (Number.isNaN(toDate(value).getTime())) {
+        throw new Error(`Cannot cast ${JSON.stringify(String(value))} to ${cast}: not a valid date.`);
+    }
+}
+export function castToStorage(value, definition, driver) {
     if (value == null)
         return value;
+    const parsed = parseCast(definition);
+    const type = parsed.type;
+    if (type === "decimal" && parsed.arg !== undefined) {
+        return toFixedDecimal(value, Number(parsed.arg));
+    }
     const driverName = (driver ?? "sqlite");
     switch (type) {
         case "boolean":
@@ -201,14 +345,16 @@ export function castToStorage(value, type, driver) {
             return String(value);
         case "json":
         case "array":
-            return typeof value === "string" ? value : JSON.stringify(value);
+            return JSON.stringify(value);
         case "collection": {
             const items = collectionItems(value);
             return JSON.stringify(items);
         }
         case "date":
+            assertValidDate(value, definition);
             return dateForStorage(value);
         case "datetime":
+            assertValidDate(value, definition);
             return dateTimeForStorage(value, driverName);
         case "encrypted":
             return encryptPayload(value);

package/dist/eager.js

@@ -4,10 +4,11 @@
 import { wrapSqlName } from "@bunyad/database";
 import { OrmCollection } from "./orm-collection.js";
 import { softDeleteAliasSql, uniqueKeys, coerceEagerRelations, } from "./model-helpers.js";
+import { hasGlobalScopes } from "./scopes.js";
 import { eagerFetchByKeys } from "./eager-fetch.js";
 import { Model } from "./model.js";
 import { enterEagerLoad, leaveEagerLoad } from "./model-strictness.js";
-import { BelongsTo, BelongsToMany, HasMany, HasManyThrough, HasOne, HasOneThrough, MorphMany, MorphOne, MorphTo, MorphToMany, aggregateRelation, applyPivotAttributes, resolveMorphType, resolveRelation, } from "./relations.js";
+import { BelongsTo, BelongsToMany, HasMany, HasManyThrough, HasOne, HasOneThrough, MorphMany, MorphOne, MorphTo, MorphToMany, MorphedByMany, aggregateRelation, applyPivotAttributes, applyPivotWheres, setInverse, resolveMorphType, resolveRelation, } from "./relations.js";
 /** Eager-load named relations onto models (`with` / `load` / collections).
  * Batches BelongsTo / HasMany / HasOne / BelongsToMany / Morph* / ofMany with
  * `WHERE IN`. Nested paths like `parent.children` are supported.
@@ -110,6 +111,27 @@ function applyConstraint(q, constraint) {
         constraint(q);
     return q;
 }
+/** Apply the constraint, then lift its limit/offset off the batched query (see `takePaging`). */
+function applyConstraintPaged(q, constraint, paging) {
+    applyConstraint(q, constraint);
+    if (constraint) {
+        const taken = q.takePaging();
+        if (taken.limit !== undefined)
+            paging.limit = taken.limit;
+        if (taken.offset !== undefined)
+            paging.offset = taken.offset;
+    }
+    return q;
+}
+/** Slice every parent's list to `offset` / `limit` (rows are already in the constraint's order). */
+function pagePerParent(byParent, paging) {
+    if (paging.limit === undefined && paging.offset === undefined)
+        return;
+    const start = paging.offset ?? 0;
+    for (const [key, list] of byParent) {
+        byParent.set(key, paging.limit === undefined ? list.slice(start) : list.slice(start, start + paging.limit));
+    }
+}
 function relationFromModel(model, relation) {
     try {
         return model.related(relation);
@@ -143,7 +165,7 @@ async function forEachIdChunk(ids, run) {
     });
     await Promise.all(workers);
 }
-function eagerLoadOneRelation(models, relation, constraint) {
+function eagerLoadOneRelationRaw(models, relation, constraint) {
     const sampleRel = relationFromModel(models[0], relation);
     if (!sampleRel)
         return;
@@ -168,6 +190,9 @@ function eagerLoadOneRelation(models, relation, constraint) {
     if (sampleRel instanceof MorphToMany) {
         return eagerLoadMorphToMany(models, relation, sampleRel, constraint);
     }
+    if (sampleRel instanceof MorphedByMany) {
+        return eagerLoadMorphedByMany(models, relation, sampleRel, constraint);
+    }
     if (sampleRel instanceof MorphMany) {
         return eagerLoadMorphMany(models, relation, sampleRel, constraint);
     }
@@ -184,6 +209,45 @@ function eagerLoadOneRelation(models, relation, constraint) {
         return eagerLoadHasOneThrough(models, relation, sampleRel, constraint);
     }
 }
+function fillDefaults(models, relation) {
+    for (const model of models) {
+        const row = model;
+        if (row[relation] == null) {
+            const rel = model.related(relation);
+            row[relation] = rel.makeDefault();
+        }
+    }
+}
+/** Load one relation, then fill `withDefault()` relations that matched nothing. */
+function eagerLoadOneRelation(models, relation, constraint) {
+    const sampleRel = relationFromModel(models[0], relation);
+    const withDefault = Boolean(sampleRel?.hasDefault?.());
+    const loaded = eagerLoadOneRelationRaw(models, relation, constraint);
+    const inverseName = sampleRel?.getInverse?.();
+    if (inverseName !== undefined) {
+        const attach = () => {
+            for (const model of models) {
+                const value = model[relation];
+                const children = value == null ? [] : Array.isArray(value) ? value : typeof value.all === "function" ? value.all() : [value];
+                for (const child of children)
+                    setInverse(child, inverseName, model);
+            }
+        };
+        if (loaded instanceof Promise) {
+            const chained = loaded.then(attach);
+            if (!withDefault)
+                return chained;
+            return chained.then(() => fillDefaults(models, relation));
+        }
+        attach();
+    }
+    if (!withDefault)
+        return loaded;
+    const fill = () => fillDefaults(models, relation);
+    if (loaded instanceof Promise)
+        return loaded.then(fill);
+    fill();
+}
 /** Single-query ofMany via GROUP BY join (avoids per-row correlated subqueries). */
 async function eagerLoadHasOneOfMany(models, relation, sample, constraint) {
     const foreignKey = sample.getForeignKeyName();
@@ -360,11 +424,12 @@ async function eagerLoadHasMany(models, relation, sample, constraint) {
     const Related = sample.getRelated();
     const parentIds = uniqueKeys(models.map((model) => model[localKey]));
     const byParent = new Map();
+    const paging = {};
     await forEachIdChunk(parentIds, async (chunk) => {
         let related;
         if (constraint) {
             let q = Related.whereIn(foreignKey, chunk);
-            applyConstraint(q, constraint);
+            applyConstraintPaged(q, constraint, paging);
             related = (await q.get()).all();
         }
         else {
@@ -377,6 +442,7 @@ async function eagerLoadHasMany(models, relation, sample, constraint) {
             byParent.set(key, list);
         }
     });
+    pagePerParent(byParent, paging);
     for (const model of models) {
         const id = model[localKey];
         model[relation] = new OrmCollection(id == null ? [] : (byParent.get(String(id)) ?? []), { owned: true });
@@ -481,11 +547,16 @@ async function eagerLoadBelongsToMany(models, relation, sample, constraint) {
     const foreignPivotKey = sample.getForeignPivotKeyName();
     const relatedPivotKey = sample.getRelatedPivotKeyName();
     const pivotColumns = sample.getPivotColumns();
-    const pivotKeys = pivotColumns.length > 0
+    const pivotWheres = sample.getPivotWheres();
+    const pivotAccessor = sample.getPivotAccessor();
+    const pivotClass = sample.getPivotClass();
+    const pivotOrders = sample.getPivotOrders();
+    const pivotKeys = pivotColumns.length > 0 || pivotClass || pivotAccessor !== "pivot"
         ? [foreignPivotKey, relatedPivotKey, ...pivotColumns.filter((c) => c !== foreignPivotKey && c !== relatedPivotKey)]
         : [];
     const parentIds = uniqueKeys(models.map((model) => model[parentKey]));
     const byParent = new Map();
+    const paging = {};
     if (parentIds.length > 0) {
         const dialect = parent.getConnection().dialect;
         const qRelated = wrapSqlName(dialect, Related.table);
@@ -500,7 +571,10 @@ async function eagerLoadBelongsToMany(models, relation, sample, constraint) {
                 .join(", ")}`
             : "";
         await forEachIdChunk(parentIds, async (chunk) => {
-            if (constraint) {
+            if (constraint ||
+                hasGlobalScopes(Related) ||
+                pivotWheres.length > 0 ||
+                pivotOrders.length > 0) {
                 let q = Related.newQuery()
                     .join(pivotTable, `${pivotTable}.${relatedPivotKey}`, "=", `${Related.table}.${Related.primaryKey}`)
                     .whereIn(`${pivotTable}.${foreignPivotKey}`, chunk)
@@ -509,13 +583,16 @@ async function eagerLoadBelongsToMany(models, relation, sample, constraint) {
                 for (const col of pivotKeys) {
                     q = q.selectRaw(`${pivotTable}.${col} as __pivot_${col}`);
                 }
-                applyConstraint(q, constraint);
+                applyPivotWheres(q, pivotTable, pivotWheres);
+                for (const o of pivotOrders)
+                    q = q.orderBy(`${pivotTable}.${o.column}`, o.direction);
+                applyConstraintPaged(q, constraint, paging);
                 const related = await q.get();
                 for (const row of related.all()) {
                     const rec = row;
                     const parentId = rec.__bunyad_parent_id;
                     delete rec.__bunyad_parent_id;
-                    applyPivotAttributes(row, rec, pivotKeys);
+                    applyPivotAttributes(row, rec, pivotKeys, { accessor: pivotAccessor, pivotClass });
                     const key = String(parentId);
                     const list = byParent.get(key) ?? [];
                     list.push(row);
@@ -534,7 +611,7 @@ async function eagerLoadBelongsToMany(models, relation, sample, constraint) {
                 const { __bunyad_parent_id: _, ...attrs } = row;
                 const model = new Related(attrs);
                 model.exists = true;
-                applyPivotAttributes(model, attrs, pivotKeys);
+                applyPivotAttributes(model, attrs, pivotKeys, { accessor: pivotAccessor, pivotClass });
                 const key = String(parentId);
                 const list = byParent.get(key) ?? [];
                 list.push(model);
@@ -542,6 +619,7 @@ async function eagerLoadBelongsToMany(models, relation, sample, constraint) {
             }
         });
     }
+    pagePerParent(byParent, paging);
     for (const model of models) {
         const id = model[parentKey];
         model[relation] = new OrmCollection(id == null ? [] : (byParent.get(String(id)) ?? []), { owned: true });
@@ -560,6 +638,7 @@ async function eagerLoadMorphToMany(models, relation, sample, constraint) {
     const parentTenantKey = sample.getParentTenantKey();
     const parentIds = uniqueKeys(models.map((model) => model[parentKey]));
     const byParent = new Map();
+    const paging = {};
     if (parentIds.length > 0 && morphTypes.length > 0) {
         const dialect = parent.getConnection().dialect;
         const qRelated = wrapSqlName(dialect, Related.table);
@@ -571,7 +650,7 @@ async function eagerLoadMorphToMany(models, relation, sample, constraint) {
         const soft = softDeleteAliasSql(Related, qRelated);
         const morphPlaceholders = morphTypes.map(() => "?").join(", ");
         await forEachIdChunk(parentIds, async (chunk) => {
-            if (constraint) {
+            if (constraint || hasGlobalScopes(Related)) {
                 let q = Related.newQuery()
                     .join(pivotTable, `${pivotTable}.${relatedPivotKey}`, "=", `${Related.table}.${Related.primaryKey}`)
                     .whereIn(`${pivotTable}.${foreignPivotKey}`, chunk)
@@ -584,7 +663,7 @@ async function eagerLoadMorphToMany(models, relation, sample, constraint) {
                         q = q.whereIn(`${pivotTable}.${pivotTenantKey}`, tenantIds);
                     }
                 }
-                applyConstraint(q, constraint);
+                applyConstraintPaged(q, constraint, paging);
                 const related = await q.get();
                 for (const row of related.all()) {
                     const rec = row;
@@ -624,6 +703,42 @@ async function eagerLoadMorphToMany(models, relation, sample, constraint) {
             }
         });
     }
+    pagePerParent(byParent, paging);
+    for (const model of models) {
+        const id = model[parentKey];
+        model[relation] = new OrmCollection(id == null ? [] : (byParent.get(String(id)) ?? []), { owned: true });
+    }
+}
+async function eagerLoadMorphedByMany(models, relation, sample, constraint) {
+    const Related = sample.getRelated();
+    const parent = models[0].constructor;
+    const parentKey = parent.primaryKey;
+    const pivotTable = sample.getPivotTable();
+    const foreignPivotKey = sample.getForeignPivotKeyName();
+    const relatedPivotKey = sample.getRelatedPivotKeyName();
+    const morphTypeColumn = sample.getMorphTypeColumn();
+    const morphType = sample.getMorphType();
+    const parentIds = uniqueKeys(models.map((model) => model[parentKey]));
+    const byParent = new Map();
+    const paging = {};
+    await forEachIdChunk(parentIds, async (chunk) => {
+        const q = Related.newQuery()
+            .join(pivotTable, `${pivotTable}.${relatedPivotKey}`, "=", `${Related.table}.${Related.primaryKey}`)
+            .whereIn(`${pivotTable}.${foreignPivotKey}`, chunk)
+            .where(`${pivotTable}.${morphTypeColumn}`, morphType)
+            .select(`${Related.table}.*`)
+            .selectRaw(`${pivotTable}.${foreignPivotKey} as __bunyad_parent_id`);
+        applyConstraintPaged(q, constraint, paging);
+        for (const row of (await q.get()).all()) {
+            const rec = row;
+            const key = String(rec.__bunyad_parent_id);
+            delete rec.__bunyad_parent_id;
+            const list = byParent.get(key) ?? [];
+            list.push(row);
+            byParent.set(key, list);
+        }
+    });
+    pagePerParent(byParent, paging);
     for (const model of models) {
         const id = model[parentKey];
         model[relation] = new OrmCollection(id == null ? [] : (byParent.get(String(id)) ?? []), { owned: true });
@@ -637,9 +752,10 @@ async function eagerLoadMorphMany(models, relation, sample, constraint) {
     const localKey = sample.getLocalKeyName();
     const parentIds = uniqueKeys(models.map((model) => model[localKey]));
     const byParent = new Map();
+    const paging = {};
     await forEachIdChunk(parentIds, async (chunk) => {
         let q = Related.where(typeColumn, morphType).whereIn(idColumn, chunk);
-        applyConstraint(q, constraint);
+        applyConstraintPaged(q, constraint, paging);
         const related = await q.get();
         for (const row of related.all()) {
             const key = String(row[idColumn]);
@@ -648,6 +764,7 @@ async function eagerLoadMorphMany(models, relation, sample, constraint) {
             byParent.set(key, list);
         }
     });
+    pagePerParent(byParent, paging);
     for (const model of models) {
         const id = model[localKey];
         model[relation] = new OrmCollection(id == null ? [] : (byParent.get(String(id)) ?? []), { owned: true });
@@ -748,6 +865,8 @@ async function eagerLoadOneAggregate(models, Parent, spec) {
         const dialect = meta.related.getConnection().dialect;
         const fk = wrapSqlName(dialect, meta.foreignKey);
         let q = meta.related.whereIn(meta.foreignKey, parentIds).selectRaw(`${fk} as __bunyad_k`);
+        if (meta.typeColumn)
+            q = q.where(meta.typeColumn, meta.morphType);
         if (spec.fn === "exists") {
             q = q.selectRaw("1 as __bunyad_v");
         }

package/dist/factory.d.ts

@@ -33,6 +33,8 @@ export declare abstract class Factory<T extends Model = Model> {
     /** Public model class accessor for relationship factories. */
     modelClass(): ModelClass;
     definition(): FactoryAttributes | Promise<FactoryAttributes>;
+    /** Runs once, before the first `make` / `create` (`afterMaking`, default states, …). */
+    configure(): this;
     /** Number of models to make/create. */
     count(amount: number): this & ManyModels;
     /** Merge attribute overrides (object or callback) into every model. */
@@ -57,12 +59,29 @@ export declare abstract class Factory<T extends Model = Model> {
     /**
      * Attach related models on a belongs-to-many after create.
      */
-    hasAttached(related: Factory<any> | Model | Model[], pivot?: FactoryAttributes, relationship?: string): this;
+    hasAttached(related: Factory<any> | Model | Model[], pivot?: FactoryAttributes | ((model: Model) => FactoryAttributes), relationship?: string): this;
+    /**
+     * `recycle` — reuse existing models when this factory (or its nested `for` /
+     * `has` factories) would otherwise create a parent of the same class.
+     */
+    recycle(models: Model | Model[] | {
+        all(): Model[];
+    }): this;
     /** `Factory::new()`. */
     static new<T extends Factory>(this: new () => T): T;
     /** Build an in-memory model instance (not persisted). */
     make(attributes?: FactoryAttributes): Promise<this extends ManyModels ? T[] : T>;
     /** Persist model(s) via `Model.forceCreate` (factories set guarded columns too). */
     create(attributes?: FactoryAttributes): Promise<this extends ManyModels ? T[] : T>;
+    /** `makeOne`. */
+    makeOne(attributes?: FactoryAttributes): Promise<T>;
+    /** `createOne`. */
+    createOne(attributes?: FactoryAttributes): Promise<T>;
+    /** `createMany(3)` or `createMany([{ name: "a" }, { name: "b" }])`. */
+    createMany(records: number | FactoryAttributes[]): Promise<T[]>;
+    /** `createQuietly` — no model events. */
+    createQuietly(attributes?: FactoryAttributes): Promise<this extends ManyModels ? T[] : T>;
+    /** `createManyQuietly`. */
+    createManyQuietly(records: number | FactoryAttributes[]): Promise<T[]>;
 }
 export {};