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

package/dist/model-query.js

@@ -1,11 +1,11 @@
 import { DatabaseManager as Db, CursorPaginator, LengthAwarePaginator, Paginator, dateTimeForStorage, hasQueryListeners, resolvePaginatorPage, wrapSqlName, } from "@bunyad/database";
-import { Collection } from "@bunyad/common";
+import { Collection, LazyCollection } from "@bunyad/common";
 import { OrmCollection } from "./orm-collection.js";
 import { bootIfNotBooted, fireModelEvent, hasModelEventListeners, } from "./model-events.js";
 import { getGlobalScopes, hasGlobalScopes, } from "./scopes.js";
 import { resolveModelBuilder } from "./decorators.js";
 import { deletedAtColumn, normalizeWithRelations, nowForConnection, parseRelationAlias, singular, usesSoftDeletes, } from "./model-helpers.js";
-import { BelongsTo, BelongsToMany, HasMany, HasManyThrough, HasOne, MorphMany, MorphOne, MorphTo, MorphToMany, morphTypeFor, resolveRelation, } from "./relations.js";
+import { BelongsTo, BelongsToMany, HasMany, HasManyThrough, HasOne, MorphMany, MorphOne, MorphTo, MorphToMany, morphTypeFor, resolveRelation, resolveAggregateRelation, applyPivotWheres, } from "./relations.js";
 import { eagerLoadAggregates, eagerLoadModels } from "./eager.js";
 import {} from "./casts.js";
 import { Model, ModelNotFoundException, attributesNeedModelCasts, filterFillable, resolveConnection, } from "./model.js";
@@ -19,7 +19,17 @@ export function unwrapModelQuery(query) {
     const target = query[MODEL_QUERY_TARGET];
     return target ?? query;
 }
-/** Shared empty array — copy-on-write before mutate (ModelQuery ctor hot path). */
+/** `whereNot('col', v)` / `whereNot('col', op, v)` become a negated one-condition group. */
+function notGroupCallback(callbackOrColumn, opOrValue, value) {
+    if (typeof callbackOrColumn === "function")
+        return callbackOrColumn;
+    return (q) => {
+        if (value === undefined)
+            q.where(callbackOrColumn, opOrValue);
+        else
+            q.where(callbackOrColumn, String(opOrValue), value);
+    };
+}
 const MQ_EMPTY = Object.freeze([]);
 const MQ_EMPTY_OBJ = Object.freeze({});
 /** Copy-on-write: return a mutable array (clone shared MQ_EMPTY). */
@@ -526,15 +536,22 @@ export class ModelQuery {
     whereUlid(column, value) {
         return this.where(column, value);
     }
-    /** `whereNot(closure)` nested group. */
-    whereNot(callback) {
+    whereNot(callbackOrColumn, opOrValue, value) {
         this.#simple = false;
-        (this.#nestedGroups = mqMut(this.#nestedGroups)).push({ boolean: "and", not: true, callback });
+        (this.#nestedGroups = mqMut(this.#nestedGroups)).push({
+            boolean: "and",
+            not: true,
+            callback: notGroupCallback(callbackOrColumn, opOrValue, value),
+        });
         return this;
     }
-    orWhereNot(callback) {
+    orWhereNot(callbackOrColumn, opOrValue, value) {
         this.#simple = false;
-        (this.#nestedGroups = mqMut(this.#nestedGroups)).push({ boolean: "or", not: true, callback });
+        (this.#nestedGroups = mqMut(this.#nestedGroups)).push({
+            boolean: "or",
+            not: true,
+            callback: notGroupCallback(callbackOrColumn, opOrValue, value),
+        });
         return this;
     }
     firstWhere(column, opOrValue, value) {
@@ -581,120 +598,132 @@ export class ModelQuery {
         const model = await this.sole();
         return model[column];
     }
-    /** `withCount` — `'posts'`, `'posts as post_total'`, a string list, or `{ products: { as: 'productsCount' } }`. */
-    withCount(...relations) {
-        for (const arg of relations) {
+    #pushAggregate(relation, fn, column, constraint, alias) {
+        const parsed = parseRelationAlias(relation);
+        const base = parsed.relation;
+        const suffix = fn === "count" || fn === "exists" ? fn : `${fn}_${column}`;
+        this.#simple = false;
+        (this.#withAggregates = mqMut(this.#withAggregates)).push({
+            relation: base,
+            alias: alias ?? parsed.alias ?? `${base}_${suffix}`,
+            fn,
+            column: fn === "count" || fn === "exists" ? undefined : column,
+            constraint,
+        });
+    }
+    /** `['posts', 'comments as c' => fn]` — string, list, or map of relation → constraint / alias. */
+    #pushAggregates(specs, fn, column) {
+        for (const arg of specs) {
             if (Array.isArray(arg)) {
-                this.withCount(...arg);
+                this.#pushAggregates(arg, fn, column);
                 continue;
             }
             if (typeof arg === "string") {
-                const parsed = parseRelationAlias(arg);
-                this.#simple = false;
-                (this.#withAggregates = mqMut(this.#withAggregates)).push({
-                    relation: parsed.relation,
-                    alias: parsed.alias ?? `${parsed.relation}_count`,
-                    fn: "count",
-                });
-                (this.#withCounts = mqMut(this.#withCounts)).push(arg);
+                this.#pushAggregate(arg, fn, column);
                 continue;
             }
             for (const [relation, value] of Object.entries(arg)) {
-                let alias = `${relation}_count`;
-                if (value === true) {
-                    // default alias
+                if (typeof value === "function") {
+                    this.#pushAggregate(relation, fn, column, value);
                 }
                 else if (typeof value === "string") {
-                    alias = value;
+                    this.#pushAggregate(relation, fn, column, undefined, value);
                 }
-                else if (typeof value === "function") {
-                    // constrained count — store as aggregate without callback support yet (count all)
+                else if (value && typeof value === "object" && value.as) {
+                    this.#pushAggregate(relation, fn, column, undefined, value.as);
                 }
-                else if (value && typeof value === "object" && "as" in value && value.as) {
-                    alias = value.as;
+                else {
+                    this.#pushAggregate(relation, fn, column);
                 }
-                this.#simple = false;
-                (this.#withAggregates = mqMut(this.#withAggregates)).push({ relation, alias, fn: "count" });
-                (this.#withCounts = mqMut(this.#withCounts)).push(relation);
             }
         }
+    }
+    /**
+     * `withCount` — `'posts'`, `'posts as post_total'`, a list, or a map such as
+     * `{ "payments as paid": (q) => q.where("status", "paid") }`.
+     */
+    withCount(...relations) {
+        this.#pushAggregates(relations, "count");
         return this;
     }
-    /** `withSum($relation, $column)`. */
+    /** `withSum($relation, $column)` — relation may be a constrained map. */
     withSum(relation, column) {
-        const parsed = parseRelationAlias(relation);
-        const base = parsed.relation;
-        this.#simple = false;
-        (this.#withAggregates = mqMut(this.#withAggregates)).push({
-            relation: base,
-            alias: parsed.alias ?? `${base}_sum_${column}`,
-            fn: "sum",
-            column,
-        });
+        this.#pushAggregates([relation], "sum", column);
         return this;
     }
     withAvg(relation, column) {
-        const parsed = parseRelationAlias(relation);
-        const base = parsed.relation;
-        this.#simple = false;
-        (this.#withAggregates = mqMut(this.#withAggregates)).push({
-            relation: base,
-            alias: parsed.alias ?? `${base}_avg_${column}`,
-            fn: "avg",
-            column,
-        });
+        this.#pushAggregates([relation], "avg", column);
         return this;
     }
     withMin(relation, column) {
-        const parsed = parseRelationAlias(relation);
-        const base = parsed.relation;
-        this.#simple = false;
-        (this.#withAggregates = mqMut(this.#withAggregates)).push({
-            relation: base,
-            alias: parsed.alias ?? `${base}_min_${column}`,
-            fn: "min",
-            column,
-        });
+        this.#pushAggregates([relation], "min", column);
         return this;
     }
     withMax(relation, column) {
-        const parsed = parseRelationAlias(relation);
-        const base = parsed.relation;
-        this.#simple = false;
-        (this.#withAggregates = mqMut(this.#withAggregates)).push({
-            relation: base,
-            alias: parsed.alias ?? `${base}_max_${column}`,
-            fn: "max",
-            column,
-        });
+        this.#pushAggregates([relation], "max", column);
         return this;
     }
     /** `withExists($relation)`. */
     withExists(...relations) {
-        for (const raw of relations.flat()) {
-            const parsed = parseRelationAlias(raw);
-            this.#simple = false;
-            (this.#withAggregates = mqMut(this.#withAggregates)).push({
-                relation: parsed.relation,
-                alias: parsed.alias ?? `${parsed.relation}_exists`,
-                fn: "exists",
-            });
-        }
+        this.#pushAggregates(relations, "exists");
         return this;
     }
     /** `withAggregate($relation, $column, $function)`. */
     withAggregate(relation, column, fn) {
-        const parsed = parseRelationAlias(relation);
-        const base = parsed.relation;
+        this.#pushAggregates([relation], fn, column);
+        return this;
+    }
+    // ── Subqueries, unions and joins on subqueries (forwarded to the query builder) ──
+    #sub(query) {
+        return query instanceof ModelQuery ? query.toBase() : query;
+    }
+    #extra(apply) {
         this.#simple = false;
-        (this.#withAggregates = mqMut(this.#withAggregates)).push({
-            relation: base,
-            alias: parsed.alias ?? `${base}_${fn}_${column}`,
-            fn,
-            column: fn === "count" ? undefined : column,
-        });
+        (this.#builderExtras = mqMut(this.#builderExtras)).push(apply);
         return this;
     }
+    /** `selectSub($query, $as)` — add a subquery as a selected column. */
+    selectSub(query, as) {
+        return this.#extra((q) => void q.selectSub(this.#sub(query), as));
+    }
+    /** `whereExists($query)` and its `or` / `not` variants. */
+    whereExists(query) {
+        return this.#extra((q) => void q.whereExists(this.#sub(query)));
+    }
+    orWhereExists(query) {
+        return this.#extra((q) => void q.orWhereExists(this.#sub(query)));
+    }
+    whereNotExists(query) {
+        return this.#extra((q) => void q.whereNotExists(this.#sub(query)));
+    }
+    orWhereNotExists(query) {
+        return this.#extra((q) => void q.orWhereNotExists(this.#sub(query)));
+    }
+    /** `union` / `unionAll` — the other query must select the same columns. */
+    union(query) {
+        return this.#extra((q) => void q.union(this.#sub(query)));
+    }
+    unionAll(query) {
+        return this.#extra((q) => void q.unionAll(this.#sub(query)));
+    }
+    /** `joinSub($query, $as, $first, $op, $second)`. */
+    joinSub(query, as, first, op, second) {
+        return this.#extra((q) => void q.joinSub(this.#sub(query), as, first, op, second));
+    }
+    leftJoinSub(query, as, first, op, second) {
+        return this.#extra((q) => void q.leftJoinSub(this.#sub(query), as, first, op, second));
+    }
+    rightJoinSub(query, as, first, op, second) {
+        return this.#extra((q) => void q.rightJoinSub(this.#sub(query), as, first, op, second));
+    }
+    /** `crossJoin($table)`. */
+    crossJoin(table) {
+        return this.#extra((q) => void q.crossJoin(table));
+    }
+    /** `groupByRaw($sql, $bindings)`. */
+    groupByRaw(sql, bindings = []) {
+        return this.#extra((q) => void q.groupByRaw(sql, bindings));
+    }
     /** `join` (hydrated models still from the base table). */
     join(table, first, op, second) {
         this.#simple = false;
@@ -1059,7 +1088,7 @@ export class ModelQuery {
         (this.#orders = mqMut(this.#orders)).push({ raw: sql });
         return this;
     }
-    /** Karobar / dialect alias for `orderByRaw`. */
+    /** Alias for `orderByRaw`. */
     orderBySql(sql) {
         return this.orderByRaw(sql);
     }
@@ -1102,6 +1131,21 @@ export class ModelQuery {
     take(value) {
         return this.limit(value);
     }
+    /**
+     * Remove and return this query's limit / offset. Eager loading calls it so a
+     * `with({ posts: (q) => q.limit(3) })` limit applies per parent, not to the
+     * whole batched query.
+     */
+    takePaging() {
+        const out = {};
+        if (this.#limitValue !== undefined)
+            out.limit = this.#limitValue;
+        if (this.#offsetValue !== undefined)
+            out.offset = this.#offsetValue;
+        this.#limitValue = undefined;
+        this.#offsetValue = undefined;
+        return out;
+    }
     offset(value) {
         this.#offsetValue = value;
         return this;
@@ -1132,7 +1176,7 @@ export class ModelQuery {
         return this;
     }
     /**
-     * OR `LIKE %term%` across columns (Karobar list `search`).
+     * OR `LIKE %term%` across columns (a list `search`).
      * Empty/whitespace term is a no-op.
      */
     search(columns, term) {
@@ -1344,7 +1388,7 @@ export class ModelQuery {
         const params = [];
         // Fingerprint (no values) — reuse quoted SQL for repeated list shapes.
         let key = this.#withTrashed ? "T" : this.#onlyTrashed ? "O" : "N";
-        key += `\u001e${this.model.table}\u001e${plan.columns}`;
+        key += `\u001e${conn.driver}\u001e${this.model.table}\u001e${plan.columns}`;
         for (const w of plan.scopeWheres) {
             key += `\u001eG\u001e${w.boolean}\u001e${w.column}\u001e${w.op}`;
             if (w.op !== "__null__" && w.op !== "__notnull__")
@@ -1538,8 +1582,9 @@ export class ModelQuery {
     #compileHasExistsSelect(conn = this.#queryConnection()) {
         const dialect = conn.dialect;
         const params = [];
+        // The compiled SQL is dialect specific (identifier quoting), so the driver is part of the key.
         let key = this.#withTrashed ? "T" : this.#onlyTrashed ? "O" : "N";
-        key += `\u001e${this.model.table}`;
+        key += `\u001e${conn.driver}\u001e${this.model.table}`;
         for (const w of this.#wheres) {
             key += `\u001e${w.boolean}\u001e${w.column}\u001e${w.op}`;
             if (w.op !== "__null__" && w.op !== "__notnull__")
@@ -1692,18 +1737,21 @@ export class ModelQuery {
                 alias: `${relation}_count`,
                 fn: "count",
                 column: undefined,
+                constraint: undefined,
             }));
         if (aggregates.length > 0) {
             q = q.select(`${this.model.table}.*`);
             for (const agg of aggregates) {
-                const meta = resolveRelation(this.model, agg.relation);
-                if (!meta)
-                    continue;
-                const expr = this.#aggregateSubquery(meta, agg.fn, agg.column);
-                if (!expr)
-                    continue;
+                const meta = resolveAggregateRelation(this.model, agg.relation);
+                if (!meta) {
+                    throw new Error(`Cannot aggregate unknown or unsupported relation [${agg.relation}] on ${this.model.name}.`);
+                }
                 const alias = wrapSqlName(this.model.getConnection().dialect, agg.alias);
-                q = q.selectRaw(`(${expr}) as ${alias}`);
+                const built = this.#constrainedAggregate(meta, agg);
+                if (!built) {
+                    throw new Error(`Relation [${agg.relation}] (${meta.kind}) does not support aggregates yet.`);
+                }
+                q = q.selectRaw(`(${built.sql}) as ${alias}`, built.bindings);
             }
         }
         if (this.#limitValue !== undefined)
@@ -1716,6 +1764,26 @@ export class ModelQuery {
             q = q.sharedLock();
         return q;
     }
+    /**
+     * Apply this model's global scopes onto a correlated subquery (`whereHas`, `withCount`, …),
+     * qualifying columns with `table` so joined pivot / parent columns never clash.
+     * Honors `withoutGlobalScopes()` called inside the user's constraint closure.
+     */
+    applyGlobalScopesToSubquery(q, table) {
+        if (this.#withoutGlobalScopes === true)
+            return q;
+        if (!hasGlobalScopes(this.model))
+            return q;
+        for (const [name, scope] of getGlobalScopes(this.model)) {
+            if (this.#withoutGlobalScopes?.has(name))
+                continue;
+            const temp = new ModelQuery(this.model, { withoutGlobalScopes: true });
+            scope(temp);
+            temp.qualifyColumns(table);
+            q = temp.applyConstraintsTo(q);
+        }
+        return q;
+    }
     #applyGlobalScopesTo(q) {
         if (this.#withoutGlobalScopes === true)
             return q;
@@ -1910,18 +1978,27 @@ export class ModelQuery {
             meta.kind === "morphToMany") {
             let applyRelated;
             let relatedQuery;
-            if (callback) {
-                const rq = meta.related.newQuery({
-                    withoutGlobalScopes: true,
-                });
-                callback(rq);
+            const scoped = hasGlobalScopes(meta.related);
+            const relatedRef = meta.kind === "has" && meta.related.table === this.model.table
+                ? `${meta.related.table}_has`
+                : meta.related.table;
+            if (callback || scoped) {
+                const rq = meta.related.newQuery();
+                callback?.(rq);
                 if (this.#relatedConstraintsAreMergeable(rq)) {
-                    applyRelated = this.#bindFlatRelatedApply(rq);
+                    const flat = this.#bindFlatRelatedApply(rq);
+                    applyRelated = scoped
+                        ? (sub) => {
+                            flat(sub);
+                            rq.applyGlobalScopesToSubquery(sub, relatedRef);
+                        }
+                        : flat;
                 }
                 else {
                     relatedQuery = rq;
                     applyRelated = (sub) => {
                         rq.applyConstraintsTo(sub);
+                        rq.applyGlobalScopesToSubquery(sub, relatedRef);
                     };
                 }
             }
@@ -1974,6 +2051,9 @@ export class ModelQuery {
                     sub.from(relatedTable);
                     sub.whereColumn(`${relatedTable}.${foreignKey}`, `${parentTable}.${localKey}`);
                 }
+                if (meta.typeColumn) {
+                    sub.where(`${selfAlias ?? relatedTable}.${meta.typeColumn}`, meta.morphType);
+                }
                 applyRelated?.(sub);
             };
         }
@@ -1999,6 +2079,8 @@ export class ModelQuery {
                     if (morphTypeColumn && morphTypes) {
                         sub.whereIn(`${pivotTable}.${morphTypeColumn}`, morphTypes);
                     }
+                    if (meta.kind === "belongsToMany")
+                        applyPivotWheres(sub, pivotTable, meta.pivotWheres);
                     applyRelated?.(sub);
                     sub.select(`${pivotTable}.${foreignPivotKey}`);
                 };
@@ -2012,6 +2094,8 @@ export class ModelQuery {
                         sub.whereIn(`${pivotTable}.${morphTypeColumn}`, morphTypes);
                         sub.whereColumn(`${pivotTable}.${pivotTenantKey}`, `${parentTable}.${parentTenantKey}`);
                     }
+                    if (meta.kind === "belongsToMany")
+                        applyPivotWheres(sub, pivotTable, meta.pivotWheres);
                     applyRelated?.(sub);
                 };
             }
@@ -2396,6 +2480,8 @@ export class ModelQuery {
                     sub.from(relatedTable);
                     sub.whereColumn(`${relatedTable}.${meta.foreignKey}`, `${parentTable}.${meta.localKey}`);
                 }
+                if (meta.typeColumn)
+                    sub.where(`${relatedTable}.${meta.typeColumn}`, meta.morphType);
             }
             else if (meta.kind === "belongsToMany" ||
                 meta.kind === "morphToMany") {
@@ -2522,45 +2608,78 @@ export class ModelQuery {
         }
         return constraint.not ? q.whereNotExists(wrap) : q.whereExists(wrap);
     }
-    #aggregateSubquery(meta, fn, column) {
-        const agg = fn === "exists"
-            ? "1"
-            : fn === "count"
-                ? "COUNT(*)"
-                : `${fn.toUpperCase()}(${column ?? "*"})`;
-        if (meta.kind === "has") {
-            const relatedTable = meta.related.table;
-            const parentTable = this.model.table;
-            if (relatedTable === parentTable) {
-                const alias = `${relatedTable}_has`;
-                const where = `${alias}.${meta.foreignKey} = ${parentTable}.${meta.localKey}`;
-                if (fn === "exists") {
-                    return `SELECT 1 FROM ${relatedTable} as ${alias} WHERE ${where} LIMIT 1`;
+    /** Correlated aggregate subquery for `withCount` / `withSum` / … (optional constraint closure). */
+    #constrainedAggregate(meta, agg) {
+        const parentTable = this.model.table;
+        const sub = this.#baseTable();
+        const related = meta.related;
+        const relatedTable = related.table;
+        // Column prefix for the related side (aliased when the relation is self-referencing).
+        let relatedRef = relatedTable;
+        switch (meta.kind) {
+            case "has": {
+                if (relatedTable === parentTable) {
+                    relatedRef = `${relatedTable}_has`;
+                    sub.from(`${relatedTable} as ${relatedRef}`);
                 }
-                return `SELECT ${agg} FROM ${relatedTable} as ${alias} WHERE ${where}`;
+                else {
+                    sub.from(relatedTable);
+                }
+                sub.whereColumn(`${relatedRef}.${meta.foreignKey}`, `${parentTable}.${meta.localKey}`);
+                if (meta.typeColumn)
+                    sub.where(`${relatedRef}.${meta.typeColumn}`, meta.morphType);
+                break;
             }
-            const where = `${relatedTable}.${meta.foreignKey} = ${parentTable}.${meta.localKey}`;
-            if (fn === "exists") {
-                return `SELECT 1 FROM ${relatedTable} WHERE ${where} LIMIT 1`;
+            case "belongsTo":
+                sub.from(relatedTable);
+                sub.whereColumn(`${relatedTable}.${meta.ownerKey}`, `${parentTable}.${meta.foreignKey}`);
+                break;
+            case "belongsToMany":
+            case "morphToMany":
+                sub.from(relatedTable);
+                sub.join(meta.pivotTable, `${meta.pivotTable}.${meta.relatedPivotKey}`, "=", `${relatedTable}.${related.primaryKey}`);
+                sub.whereColumn(`${meta.pivotTable}.${meta.foreignPivotKey}`, `${parentTable}.${meta.localKey}`);
+                if (meta.kind === "morphToMany") {
+                    sub.whereIn(`${meta.pivotTable}.${meta.morphTypeColumn}`, meta.morphTypes);
+                }
+                else {
+                    applyPivotWheres(sub, meta.pivotTable, meta.pivotWheres);
+                }
+                break;
+            case "hasManyThrough":
+            case "hasOneThrough": {
+                const through = meta.through.table;
+                sub.from(relatedTable);
+                sub.join(through, `${through}.${meta.secondLocalKey}`, "=", `${relatedTable}.${meta.secondKey}`);
+                sub.whereColumn(`${through}.${meta.firstKey}`, `${parentTable}.${meta.localKey}`);
+                if (usesSoftDeletes(meta.through)) {
+                    sub.whereNull(`${through}.${deletedAtColumn(meta.through)}`);
+                }
+                break;
             }
-            return `SELECT ${agg} FROM ${relatedTable} WHERE ${where}`;
+            default:
+                return null;
         }
-        if (meta.kind === "belongsTo") {
-            const where = `${meta.related.table}.${meta.ownerKey} = ${this.model.table}.${meta.foreignKey}`;
-            if (fn === "exists") {
-                return `SELECT 1 FROM ${meta.related.table} WHERE ${where} LIMIT 1`;
-            }
-            return `SELECT ${agg} FROM ${meta.related.table} WHERE ${where}`;
+        if (usesSoftDeletes(related)) {
+            sub.whereNull(`${relatedRef}.${deletedAtColumn(related)}`);
         }
-        if (meta.kind !== "belongsToMany" && meta.kind !== "morphToMany") {
-            return null;
+        if (agg.constraint || hasGlobalScopes(related)) {
+            const rq = related.newQuery();
+            agg.constraint?.(rq);
+            rq.applyConstraintsTo(sub);
+            rq.applyGlobalScopesToSubquery(sub, relatedRef);
         }
-        const join = `INNER JOIN ${meta.pivotTable} ON ${meta.pivotTable}.${meta.relatedPivotKey} = ${meta.related.table}.${meta.related.primaryKey}`;
-        const where = `${meta.pivotTable}.${meta.foreignPivotKey} = ${this.model.table}.${meta.localKey}`;
-        if (fn === "exists") {
-            return `SELECT 1 FROM ${meta.related.table} ${join} WHERE ${where} LIMIT 1`;
+        if (agg.fn === "exists") {
+            sub.select("1");
+            sub.limit(1);
         }
-        return `SELECT ${agg} FROM ${meta.related.table} ${join} WHERE ${where}`;
+        else {
+            const column = agg.column
+                ? agg.column.includes(".") ? agg.column : `${relatedRef}.${agg.column}`
+                : "*";
+            sub.selectRaw(agg.fn === "count" ? "COUNT(*)" : `${agg.fn.toUpperCase()}(${column})`);
+        }
+        return { sql: sub.toSql(), bindings: sub.getBindings() };
     }
     first() {
         const fast = this.#trySimpleFirst();
@@ -2922,8 +3041,45 @@ export class ModelQuery {
             page += 1;
         }
     }
+    /**
+     * `cursor($chunkSize)` — hydrate models one at a time from a single streamed
+     * query, so memory stays flat on large tables. `with()` relations are loaded
+     * per batch of `chunkSize` models rather than per row.
+     */
+    cursor(chunkSize = 1000) {
+        return new LazyCollection(() => this.#cursorModels(chunkSize));
+    }
+    async *#cursorModels(chunkSize) {
+        const size = Math.max(1, Math.floor(chunkSize));
+        const fireRetrieved = hasModelEventListeners(this.model, "retrieved");
+        const eager = this.#eagerLoad.length > 0;
+        let batch = [];
+        for await (const row of this.#buildQuery().cursor(size)) {
+            const model = this.#makeModel(row);
+            if (fireRetrieved) {
+                await fireModelEvent(model, "retrieved");
+            }
+            if (!eager) {
+                yield model;
+                continue;
+            }
+            batch.push(model);
+            if (batch.length >= size) {
+                await this.#loadEager(batch);
+                yield* batch;
+                batch = [];
+            }
+        }
+        if (batch.length > 0) {
+            await this.#loadEager(batch);
+            yield* batch;
+        }
+    }
     /** `lazy($chunkSize)`. */
-    async *lazy(chunkSize = 1000) {
+    lazy(chunkSize = 1000) {
+        return new LazyCollection(() => this.#lazyPages(chunkSize));
+    }
+    async *#lazyPages(chunkSize) {
         let page = 1;
         const fireRetrieved = hasModelEventListeners(this.model, "retrieved");
         for (;;) {
@@ -2976,11 +3132,11 @@ export class ModelQuery {
         }
     }
     /** `lazyById`. */
-    async *lazyById(chunkSize = 1000, column) {
-        yield* this.#lazyById(chunkSize, column ?? this.model.primaryKey, "asc");
+    lazyById(chunkSize = 1000, column) {
+        return new LazyCollection(() => this.#lazyById(chunkSize, column ?? this.model.primaryKey, "asc"));
     }
-    async *lazyByIdDesc(chunkSize = 1000, column) {
-        yield* this.#lazyById(chunkSize, column ?? this.model.primaryKey, "desc");
+    lazyByIdDesc(chunkSize = 1000, column) {
+        return new LazyCollection(() => this.#lazyById(chunkSize, column ?? this.model.primaryKey, "desc"));
     }
     async *#lazyById(chunkSize, column, direction) {
         const size = Math.max(1, Math.floor(chunkSize));