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

package/dist/factory.js

@@ -83,6 +83,11 @@ export class Factory {
     #has = [];
     #for = [];
     #hasAttached = [];
+    #configured = false;
+    /** Models reused instead of creating new parents (`recycle`). */
+    #recycled = [];
+    /** Parents created from `for(Factory)` — one per batch, shared by every model in it. */
+    #forParents = new Map();
     /** Public model class accessor for relationship factories. */
     modelClass() {
         return this.model();
@@ -90,6 +95,10 @@ export class Factory {
     definition() {
         return {};
     }
+    /** Runs once, before the first `make` / `create` (`afterMaking`, default states, …). */
+    configure() {
+        return this;
+    }
     /** Number of models to make/create. */
     count(amount) {
         this.#count = amount;
@@ -140,6 +149,26 @@ export class Factory {
         this.#hasAttached.push({ related, pivot, relationship });
         return 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) {
+        const list = Array.isArray(models)
+            ? models
+            : "all" in models && typeof models.all === "function"
+                ? models.all()
+                : [models];
+        this.#recycled.push(...list);
+        return this;
+    }
+    /** A recycled model of `Ctor`, chosen at random. */
+    #recycledFor(Ctor) {
+        const matches = this.#recycled.filter((m) => m.constructor === Ctor);
+        if (matches.length === 0)
+            return undefined;
+        return matches[Math.floor(Math.random() * matches.length)];
+    }
     /** `Factory::new()`. */
     static new() {
         return new this();
@@ -157,52 +186,89 @@ export class Factory {
             attrs = { ...attrs, ...patch };
         }
         for (const spec of this.#for) {
-            const parentModel = spec.parent instanceof Factory
-                ? (await spec.parent.create())
-                : spec.parent;
+            let parentModel;
+            if (spec.parent instanceof Factory) {
+                let created = this.#forParents.get(spec);
+                if (!created) {
+                    created = this.#recycledFor(spec.parent.modelClass());
+                }
+                if (!created) {
+                    if (this.#recycled.length > 0)
+                        spec.parent.recycle(this.#recycled);
+                    created = (await spec.parent.create());
+                }
+                this.#forParents.set(spec, created);
+                parentModel = created;
+            }
+            else {
+                parentModel = spec.parent;
+            }
             const ParentCtor = parentModel.constructor;
             const fkName = spec.relationship?.endsWith("_id")
                 ? spec.relationship
-                : spec.relationship
-                    ? `${spec.relationship}_id`
-                    : `${singularTable(ParentCtor.table)}_id`;
+                : this.#belongsToKey(ParentCtor, spec.relationship);
             attrs[fkName] = parentModel[ParentCtor.primaryKey];
         }
         return { ...attrs, ...attributes };
     }
+    /**
+     * Foreign key for `for(parent)`: the child's `belongsTo` relation named after
+     * the parent class (a `Team` parent looks for `team()`), else `team_id`.
+     */
+    #belongsToKey(Parent, relationship) {
+        const camel = relationship ?? Parent.name.charAt(0).toLowerCase() + Parent.name.slice(1);
+        try {
+            const rel = new (this.model())().related(camel);
+            if (typeof rel.getForeignKeyName === "function")
+                return rel.getForeignKeyName();
+        }
+        catch {
+            // no such relation on the child model
+        }
+        const snake = camel.replace(/[A-Z]/g, (c) => `_${c.toLowerCase()}`);
+        return `${snake}_id`;
+    }
     async #createRelated(parent) {
         const ParentCtor = parent.constructor;
         const parentId = parent[ParentCtor.primaryKey];
+        const idsOf = (list) => list.map((m) => m[m.constructor.primaryKey]);
         for (const spec of this.#has) {
+            if (this.#recycled.length > 0)
+                spec.factory.recycle(this.#recycled);
             const RelatedCtor = spec.factory.modelClass();
             const relName = spec.relationship ?? guessRelationName(ParentCtor, RelatedCtor);
             let fk = `${singularTable(ParentCtor.table)}_id`;
-            let useAttach = false;
+            let fixed = null;
+            let rel = null;
             try {
-                const rel = parent.related(relName);
-                if (typeof rel.attach === "function") {
-                    useAttach = true;
-                }
-                else if (typeof rel.getForeignKeyName === "function") {
-                    fk = rel.getForeignKeyName();
-                }
+                rel = parent.related(relName);
             }
             catch {
-                // use default fk
+                // fall back to the conventional foreign key
             }
-            if (useAttach) {
-                const related = await spec.factory.create();
-                const list = Array.isArray(related) ? related : [related];
-                const rel = parent.related(relName);
-                const ids = list.map((m) => m[m.constructor.primaryKey]);
-                await rel.attach(ids);
+            if (rel && typeof rel.attach === "function") {
+                const created = await spec.factory.create();
+                const list = (Array.isArray(created) ? created : [created]);
+                await rel.attach(idsOf(list));
                 continue;
             }
-            await spec.factory.state({ [fk]: parentId }).create();
+            if (rel && typeof rel.getTypeColumn === "function") {
+                // morphOne / morphMany: set both the id and the type column.
+                fixed = {
+                    [rel.getIdColumn()]: parentId,
+                    [rel.getTypeColumn()]: rel.getMorphType(),
+                };
+            }
+            else if (rel && typeof rel.getForeignKeyName === "function") {
+                fk = rel.getForeignKeyName();
+            }
+            await spec.factory.state(fixed ?? { [fk]: parentId }).create();
         }
         for (const spec of this.#hasAttached) {
             let models;
             if (spec.related instanceof Factory) {
+                if (this.#recycled.length > 0)
+                    spec.related.recycle(this.#recycled);
                 const created = await spec.related.create();
                 models = Array.isArray(created) ? created : [created];
             }
@@ -217,17 +283,33 @@ export class Factory {
             const RelatedCtor = models[0].constructor;
             const relName = spec.relationship ?? guessRelationName(ParentCtor, RelatedCtor);
             const rel = parent.related(relName);
-            const ids = models.map((m) => m[m.constructor.primaryKey]);
-            await rel.attach(ids);
-            void spec.pivot;
+            const pivot = spec.pivot;
+            if (typeof pivot === "function") {
+                // Per-model pivot attributes.
+                const map = {};
+                for (const m of models)
+                    map[String(idsOf([m])[0])] = pivot(m);
+                await rel.attach(map);
+            }
+            else {
+                await rel.attach(idsOf(models), pivot ?? {});
+            }
         }
     }
-    /** Build an in-memory model instance (not persisted). */
-    async make(attributes = {}) {
-        const n = this.#count;
-        const many = this.#many;
+    #begin() {
+        if (!this.#configured) {
+            this.#configured = true;
+            this.configure();
+        }
+        const out = { n: this.#count, many: this.#many };
         this.#count = 1;
         this.#many = false;
+        this.#forParents.clear();
+        return out;
+    }
+    /** Build an in-memory model instance (not persisted). */
+    async make(attributes = {}) {
+        const { n, many } = this.#begin();
         const ModelClass = this.model();
         const items = [];
         for (let i = 0; i < n; i++) {
@@ -242,18 +324,16 @@ export class Factory {
     }
     /** Persist model(s) via `Model.forceCreate` (factories set guarded columns too). */
     async create(attributes = {}) {
-        const n = this.#count;
-        const many = this.#many;
-        this.#count = 1;
-        this.#many = false;
+        const { n, many } = this.#begin();
         const ModelClass = this.model();
         const items = [];
         for (let i = 0; i < n; i++) {
             const base = await this.#resolveAttributes(attributes);
-            const model = (await ModelClass.forceCreate(base));
-            for (const cb of this.#afterMaking) {
-                await cb(model);
-            }
+            // `afterMaking` runs on the unsaved model, then it is persisted.
+            const model = (await ModelClass.forceCreate(base, async (unsaved) => {
+                for (const cb of this.#afterMaking)
+                    await cb(unsaved);
+            }));
             for (const cb of this.#afterCreating) {
                 await cb(model);
             }
@@ -262,4 +342,30 @@ export class Factory {
         }
         return (many ? items : items[0]);
     }
+    /** `makeOne`. */
+    async makeOne(attributes = {}) {
+        return (await this.make(attributes));
+    }
+    /** `createOne`. */
+    async createOne(attributes = {}) {
+        return (await this.create(attributes));
+    }
+    /** `createMany(3)` or `createMany([{ name: "a" }, { name: "b" }])`. */
+    async createMany(records) {
+        if (typeof records === "number") {
+            return (await this.count(records).create());
+        }
+        const out = [];
+        for (const attrs of records)
+            out.push((await this.createOne(attrs)));
+        return out;
+    }
+    /** `createQuietly` — no model events. */
+    async createQuietly(attributes = {}) {
+        return this.model().withoutEvents(() => this.create(attributes));
+    }
+    /** `createManyQuietly`. */
+    async createManyQuietly(records) {
+        return this.model().withoutEvents(() => this.createMany(records));
+    }
 }

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { Model, ModelQuery, HasMany, HasManyThrough, HasOne, HasOneThrough, BelongsTo, BelongsToMany, MorphToMany, MorphMany, MorphOne, MorphTo, morphMap, clearMorphMap, eagerLoadModels, eagerLoadAggregates, ModelNotFoundException, LazyLoadingViolationException, MassAssignmentException, MissingAttributeException, resetModelStrictnessForTests, isModelCtor, Attribute, AsCollection, AsFluent, AsEnumCollection, resetModelEventsForTests, type ModelClass, type RelationFactory, type RelationsMap, type CastType, type CastDefinition, type EnumCast, type ModelEventName, type ModelEventListener, type ModelObserver, type ModelQueryOptions, type EagerAggregateSpec, type MorphToManyOptions, resolveConnection, } from "./model.js";
+export { Model, ModelQuery, HasMany, HasManyThrough, HasOne, HasOneThrough, BelongsTo, BelongsToMany, MorphToMany, MorphedByMany, MorphMany, MorphOne, MorphTo, morphMap, enforceMorphMap, requireMorphMap, getMorphedModel, clearMorphMap, eagerLoadModels, eagerLoadAggregates, ModelNotFoundException, LazyLoadingViolationException, MassAssignmentException, MissingAttributeException, resetModelStrictnessForTests, isModelCtor, Attribute, AsCollection, AsFluent, AsEnumCollection, resetModelEventsForTests, type ModelClass, type RelationFactory, type RelationsMap, type CastType, type CastDefinition, type EnumCast, type ModelEventName, type ModelEventListener, type ModelObserver, type ModelQueryOptions, type EagerAggregateSpec, type MorphToManyOptions, resolveConnection, } from "./model.js";
 export type { GlobalScopeCallback } from "./scopes.js";
 export { clearGlobalScopes } from "./scopes.js";
 export { UseBuilder, resolveModelBuilder, type ModelBuilderConstructor, } from "./decorators.js";
@@ -8,3 +8,23 @@ export { Factory, fake, type FactoryAttributes, type FactoryState, type FactoryS
 export { Pivot } from "./pivot.js";
 export { LengthAwarePaginator } from "@bunyad/database";
 export { Collection, collect } from "@bunyad/common";
+export type { AggregateRelations } from "./model-query.js";
+/**
+ * Type-level switch for the whole ORM, declared here (the package entry) so an app can augment it.
+ *
+ * Relation and column names are checked at compile time by default: `User.with("psots")` and
+ * `User.where("emial", x)` are errors. To accept any string again, add this to a `.d.ts` file in your app:
+ *
+ * ```ts
+ * declare module "@bunyad/orm" {
+ *   interface OrmTypeOptions {
+ *     strictNames: false;
+ *   }
+ * }
+ * ```
+ */
+export interface OrmTypeOptions {
+}
+export type { ColumnHint, ColumnNames, RelationHint, RelationNames, } from "./typed-names.js";
+export { unsafeName } from "./typed-names.js";
+export { checkModelSchema, generateModelTypes, modelColumnsInterface, tsTypeForColumn, type SchemaIssue } from "./schema-types.js";

package/dist/index.js

@@ -1,4 +1,4 @@
-export { Model, ModelQuery, HasMany, HasManyThrough, HasOne, HasOneThrough, BelongsTo, BelongsToMany, MorphToMany, MorphMany, MorphOne, MorphTo, morphMap, clearMorphMap, eagerLoadModels, eagerLoadAggregates, ModelNotFoundException, LazyLoadingViolationException, MassAssignmentException, MissingAttributeException, resetModelStrictnessForTests, isModelCtor, Attribute, AsCollection, AsFluent, AsEnumCollection, resetModelEventsForTests, resolveConnection, } from "./model.js";
+export { Model, ModelQuery, HasMany, HasManyThrough, HasOne, HasOneThrough, BelongsTo, BelongsToMany, MorphToMany, MorphedByMany, MorphMany, MorphOne, MorphTo, morphMap, enforceMorphMap, requireMorphMap, getMorphedModel, clearMorphMap, eagerLoadModels, eagerLoadAggregates, ModelNotFoundException, LazyLoadingViolationException, MassAssignmentException, MissingAttributeException, resetModelStrictnessForTests, isModelCtor, Attribute, AsCollection, AsFluent, AsEnumCollection, resetModelEventsForTests, resolveConnection, } from "./model.js";
 export { clearGlobalScopes } from "./scopes.js";
 export { UseBuilder, resolveModelBuilder, } from "./decorators.js";
 export { HasUuids, HasUlids, HasFactory, SoftDeletes, Prunable, MassPrunable, prune, pruneAll, prunableModelClasses, massPrunableModelClasses, clearPrunableRegistries, uuid7, ulid, } from "./concerns.js";
@@ -7,3 +7,5 @@ export { Factory, fake, } from "./factory.js";
 export { Pivot } from "./pivot.js";
 export { LengthAwarePaginator } from "@bunyad/database";
 export { Collection, collect } from "@bunyad/common";
+export { unsafeName } from "./typed-names.js";
+export { checkModelSchema, generateModelTypes, modelColumnsInterface, tsTypeForColumn } from "./schema-types.js";

package/dist/model-events.d.ts

@@ -10,6 +10,9 @@ export type ModelEventListener<T extends Model = Model> = (model: T) => void | b
 /** Observer object with optional methods named after events. */
 export type ModelObserver<T extends Model = Model> = {
     [K in ModelEventName]?: (model: T) => void | boolean | Promise<void | boolean>;
+} & {
+    /** Dispatch the after-events (`created`, `saved`, …) once the transaction commits. */
+    afterCommit?: boolean;
 };
 type ModelCtor = abstract new (...args: never[]) => Model;
 /** Whether events are currently suppressed for this model class. */
@@ -34,8 +37,11 @@ export declare function fireModelEvent(model: Model, event: ModelEventName): boo
 /** True when at least one listener is registered for this event. */
 export declare function hasModelEventListeners(ctor: ModelCtor, event: ModelEventName): boolean;
 export declare function hasAnyModelEventListeners(ctor: ModelCtor): boolean;
-/** Run `callback` with model events disabled for `ctor`. */
-export declare function withoutModelEvents<T>(ctor: ModelCtor, callback: () => T | Promise<T>): T | Promise<T>;
+/**
+ * Run `callback` with model events disabled for `ctor`, or for every model
+ * when `all` is true (`Model.withoutEvents(...)` on the base class).
+ */
+export declare function withoutModelEvents<T>(ctor: ModelCtor, callback: () => T | Promise<T>, all?: boolean): T | Promise<T>;
 /** Register an observer instance or class (`Model::observe`). */
 export declare function observeModel<T extends Model>(ctor: abstract new (...args: never[]) => T, observer: ModelObserver<T> | (new () => ModelObserver<T>) | Array<ModelObserver<T> | (new () => ModelObserver<T>)>): void;
 /** Test helper — clear boot state and listeners for a model class. */

package/dist/model-events.js

@@ -18,6 +18,8 @@ export const MODEL_EVENT_NAMES = [
 const booted = new WeakSet();
 const listeners = new WeakMap();
 const eventsDisabled = new WeakMap();
+/** `Model.withoutEvents()` called on the base class: every model is muted (seeders, imports). */
+let globalEventsDisabled = 0;
 function listenerMap(ctor) {
     let map = listeners.get(ctor);
     if (!map) {
@@ -28,7 +30,7 @@ function listenerMap(ctor) {
 }
 /** Whether events are currently suppressed for this model class. */
 export function modelEventsDisabled(ctor) {
-    return (eventsDisabled.get(ctor) ?? 0) > 0;
+    return globalEventsDisabled > 0 || (eventsDisabled.get(ctor) ?? 0) > 0;
 }
 /**
  * Ensure `boot` / `booted` have run once for this model class.
@@ -92,10 +94,20 @@ export function hasAnyModelEventListeners(ctor) {
     }
     return false;
 }
-/** Run `callback` with model events disabled for `ctor`. */
-export function withoutModelEvents(ctor, callback) {
-    eventsDisabled.set(ctor, (eventsDisabled.get(ctor) ?? 0) + 1);
+/**
+ * Run `callback` with model events disabled for `ctor`, or for every model
+ * when `all` is true (`Model.withoutEvents(...)` on the base class).
+ */
+export function withoutModelEvents(ctor, callback, all = false) {
+    if (all)
+        globalEventsDisabled++;
+    else
+        eventsDisabled.set(ctor, (eventsDisabled.get(ctor) ?? 0) + 1);
     const finish = () => {
+        if (all) {
+            globalEventsDisabled = Math.max(0, globalEventsDisabled - 1);
+            return;
+        }
         const depth = (eventsDisabled.get(ctor) ?? 1) - 1;
         if (depth <= 0)
             eventsDisabled.delete(ctor);
@@ -125,6 +137,17 @@ export function observeModel(ctor, observer) {
         for (const event of MODEL_EVENT_NAMES) {
             const method = instance[event];
             if (typeof method === "function") {
+                const isBefore = event.endsWith("ing") && event !== "replicating";
+                if (instance.afterCommit === true && !isBefore) {
+                    // Run once the outermost
+                    // transaction commits (immediately when there is none); dropped on rollback.
+                    registerModelEvent(ctor, event, (model) => {
+                        model.getConnection().afterCommit(async () => {
+                            await method.call(instance, model);
+                        });
+                    });
+                    continue;
+                }
                 registerModelEvent(ctor, event, (model) => method.call(instance, model));
             }
         }

package/dist/model-query.d.ts

@@ -3,8 +3,9 @@
  */
 import type { DateInput, QueryBuilder } from "@bunyad/database";
 import { CursorPaginator, LengthAwarePaginator, Paginator } from "@bunyad/database";
-import { Collection } from "@bunyad/common";
+import { Collection, LazyCollection } from "@bunyad/common";
 import { OrmCollection } from "./orm-collection.js";
+import type { ColumnHint, RelationHint, WithMap } from "./typed-names.js";
 import { type CastDefinition } from "./casts.js";
 import { Model, type ModelClass, type ModelQueryOptions } from "./model.js";
 /**
@@ -14,6 +15,13 @@ import { Model, type ModelClass, type ModelQueryOptions } from "./model.js";
 export declare const MODEL_QUERY_TARGET: unique symbol;
 /** Unwrap a local-scope Proxy to the underlying `ModelQuery` instance. */
 export declare function unwrapModelQuery<Q extends ModelQuery>(query: Q): Q;
+/** Shared empty array — copy-on-write before mutate (ModelQuery ctor hot path). */
+/** Relations accepted by `withCount` / `withSum` / …: names, lists, or constraint maps. */
+export type AggregateRelations = string | AggregateRelations[] | Record<string, true | string | {
+    as?: string;
+} | ((query: ModelQuery) => void)>;
+/** A subquery: a query builder, a model query, or a closure that configures a builder. */
+export type SubQuery = QueryBuilder | ModelQuery<any, any> | ((q: QueryBuilder) => void);
 export declare class ModelQuery<T extends Model = Model, TResult extends "model" | "row" = "model"> {
     #private;
     private model;
@@ -38,15 +46,15 @@ export declare class ModelQuery<T extends Model = Model, TResult extends "model"
     /** `withCasts` — merge query-time casts for hydration. */
     withCasts(casts: Record<string, CastDefinition>): this;
     /** `has`. */
-    has(relation: string): this;
+    has(relation: RelationHint<T>): this;
     /** `doesntHave`. */
-    doesntHave(relation: string): this;
+    doesntHave(relation: RelationHint<T>): this;
     /** `whereHas`. */
-    whereHas(relation: string, callback?: (query: ModelQuery) => void): this;
+    whereHas(relation: RelationHint<T>, callback?: (query: ModelQuery) => void): this;
     /** `orWhereHas`. */
-    orWhereHas(relation: string, callback?: (query: ModelQuery) => void): this;
+    orWhereHas(relation: RelationHint<T>, callback?: (query: ModelQuery) => void): this;
     /** `whereDoesntHave`. */
-    whereDoesntHave(relation: string, callback?: (query: ModelQuery) => void): this;
+    whereDoesntHave(relation: RelationHint<T>, callback?: (query: ModelQuery) => void): this;
     /** `orWhereDoesntHave`. */
     orWhereDoesntHave(relation: string, callback?: (query: ModelQuery) => void): this;
     /**
@@ -93,7 +101,7 @@ export declare class ModelQuery<T extends Model = Model, TResult extends "model"
     /**
      * `withWhereHas($relation, $callback?)` — whereHas + eager with same constraint.
      */
-    withWhereHas(relation: string, callback?: (query: ModelQuery) => void): this;
+    withWhereHas(relation: RelationHint<T>, callback?: (query: ModelQuery) => void): this;
     /** `whereAny` (forwarded to query builder). */
     whereAny(columns: string[], opOrValue: unknown, value?: unknown): this;
     orWhereAny(columns: string[], opOrValue: unknown, value?: unknown): this;
@@ -111,7 +119,11 @@ export declare class ModelQuery<T extends Model = Model, TResult extends "model"
     whereUlid(column: string, value: string): this;
     /** `whereNot(closure)` nested group. */
     whereNot(callback: (query: ModelQuery<T>) => void): this;
+    whereNot(column: ColumnHint<T>, value: unknown): this;
+    whereNot(column: ColumnHint<T>, op: string, value: unknown): this;
     orWhereNot(callback: (query: ModelQuery<T>) => void): this;
+    orWhereNot(column: ColumnHint<T>, value: unknown): this;
+    orWhereNot(column: ColumnHint<T>, op: string, value: unknown): this;
     /** `firstWhere`. */
     firstWhere(column: string, value: unknown): T | null | Promise<T | null>;
     firstWhere(column: string, op: string, value: unknown): T | null | Promise<T | null>;
@@ -127,19 +139,38 @@ export declare class ModelQuery<T extends Model = Model, TResult extends "model"
     valueOrFail(column: string): Promise<unknown>;
     /** `soleValue`. */
     soleValue(column: string): Promise<unknown>;
-    /** `withCount` — `'posts'`, `'posts as post_total'`, a string list, or `{ products: { as: 'productsCount' } }`. */
-    withCount(...relations: Array<string | string[] | Record<string, true | string | ((query: ModelQuery) => void) | {
-        as?: string;
-    }>>): this;
-    /** `withSum($relation, $column)`. */
-    withSum(relation: string, column: string): this;
-    withAvg(relation: string, column: string): this;
-    withMin(relation: string, column: string): this;
-    withMax(relation: string, column: string): this;
+    /**
+     * `withCount` — `'posts'`, `'posts as post_total'`, a list, or a map such as
+     * `{ "payments as paid": (q) => q.where("status", "paid") }`.
+     */
+    withCount(...relations: AggregateRelations[]): this;
+    /** `withSum($relation, $column)` — relation may be a constrained map. */
+    withSum(relation: AggregateRelations, column: string): this;
+    withAvg(relation: AggregateRelations, column: string): this;
+    withMin(relation: AggregateRelations, column: string): this;
+    withMax(relation: AggregateRelations, column: string): this;
     /** `withExists($relation)`. */
-    withExists(...relations: string[]): this;
+    withExists(...relations: AggregateRelations[]): this;
     /** `withAggregate($relation, $column, $function)`. */
-    withAggregate(relation: string, column: string, fn: "count" | "sum" | "avg" | "min" | "max"): this;
+    withAggregate(relation: AggregateRelations, column: string, fn: "count" | "sum" | "avg" | "min" | "max"): this;
+    /** `selectSub($query, $as)` — add a subquery as a selected column. */
+    selectSub(query: SubQuery, as: string): this;
+    /** `whereExists($query)` and its `or` / `not` variants. */
+    whereExists(query: SubQuery): this;
+    orWhereExists(query: SubQuery): this;
+    whereNotExists(query: SubQuery): this;
+    orWhereNotExists(query: SubQuery): this;
+    /** `union` / `unionAll` — the other query must select the same columns. */
+    union(query: SubQuery): this;
+    unionAll(query: SubQuery): this;
+    /** `joinSub($query, $as, $first, $op, $second)`. */
+    joinSub(query: SubQuery, as: string, first: string, op: string, second: string): this;
+    leftJoinSub(query: SubQuery, as: string, first: string, op: string, second: string): this;
+    rightJoinSub(query: SubQuery, as: string, first: string, op: string, second: string): this;
+    /** `crossJoin($table)`. */
+    crossJoin(table: string): this;
+    /** `groupByRaw($sql, $bindings)`. */
+    groupByRaw(sql: string, bindings?: unknown[]): this;
     /** `join` (hydrated models still from the base table). */
     join(table: string, first: string, op: string, second: string): this;
     /** `leftJoin`. */
@@ -147,18 +178,18 @@ export declare class ModelQuery<T extends Model = Model, TResult extends "model"
     /** `rightJoin`. */
     rightJoin(table: string, first: string, op: string, second: string): this;
     where(callback: (query: ModelQuery<T>) => void): this;
-    where(column: string, value: unknown): this;
-    where(column: string, op: string, value: unknown): this;
+    where(column: ColumnHint<T>, value: unknown): this;
+    where(column: ColumnHint<T>, op: string, value: unknown): this;
     orWhere(callback: (query: ModelQuery<T>) => void): this;
-    orWhere(column: string, value: unknown): this;
-    orWhere(column: string, op: string, value: unknown): this;
-    whereIn(column: string, values: unknown[]): this;
+    orWhere(column: ColumnHint<T>, value: unknown): this;
+    orWhere(column: ColumnHint<T>, op: string, value: unknown): this;
+    whereIn(column: ColumnHint<T>, values: unknown[]): this;
     orWhereIn(column: string, values: unknown[]): this;
     whereNotIn(column: string, values: unknown[]): this;
     orWhereNotIn(column: string, values: unknown[]): this;
-    whereNull(column: string): this;
+    whereNull(column: ColumnHint<T>): this;
     orWhereNull(column: string): this;
-    whereNotNull(column: string): this;
+    whereNotNull(column: ColumnHint<T>): this;
     orWhereNotNull(column: string): this;
     whereBetween(column: string, values: [unknown, unknown]): this;
     orWhereBetween(column: string, values: [unknown, unknown]): this;
@@ -184,10 +215,10 @@ export declare class ModelQuery<T extends Model = Model, TResult extends "model"
     addSelect(...columns: string[]): this;
     selectRaw(expression: string, bindings?: unknown[]): this;
     distinct(value?: boolean): this;
-    orderBy(column: string, direction?: "asc" | "desc"): this;
-    orderByDesc(column: string): this;
+    orderBy(column: ColumnHint<T>, direction?: "asc" | "desc"): this;
+    orderByDesc(column: ColumnHint<T>): this;
     orderByRaw(sql: string): this;
-    /** Karobar / dialect alias for `orderByRaw`. */
+    /** Alias for `orderByRaw`. */
     orderBySql(sql: string): this;
     reorder(column?: string, direction?: "asc" | "desc"): this;
     inRandomOrder(): this;
@@ -198,6 +229,15 @@ export declare class ModelQuery<T extends Model = Model, TResult extends "model"
     havingRaw(sql: string, bindings?: unknown[]): this;
     limit(value: number): this;
     take(value: number): this;
+    /**
+     * 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(): {
+        limit?: number;
+        offset?: number;
+    };
     offset(value: number): this;
     skip(value: number): this;
     forPage(page: number, perPage?: number): this;
@@ -205,14 +245,14 @@ export declare class ModelQuery<T extends Model = Model, TResult extends "model"
     sharedLock(): this;
     when(condition: unknown, callback: (query: this) => void, defaultCallback?: (query: this) => void): 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: string[], term: string): this;
     unless(condition: unknown, callback: (query: this) => void, defaultCallback?: (query: this) => void): this;
     tap(callback: (query: this) => void): this;
     clone(): ModelQuery<T, TResult>;
-    with(...relations: Array<string | string[] | Record<string, unknown>>): this;
+    with(...relations: Array<RelationHint<T> | RelationHint<T>[] | WithMap<T>>): this;
     /** Underlying query builder (fresh compile each call). */
     toBase(): QueryBuilder;
     /** Compiled SQL (bindings via `getBindings()`). */
@@ -222,6 +262,12 @@ export declare class ModelQuery<T extends Model = Model, TResult extends "model"
     getBindings(): unknown[];
     dump(): this;
     dd(): never;
+    /**
+     * 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: QueryBuilder, table: string): QueryBuilder;
     /**
      * Prefix unqualified columns with `table.` (BelongsTo whereHas → JOIN path).
      */
@@ -259,14 +305,20 @@ export declare class ModelQuery<T extends Model = Model, TResult extends "model"
     }): Promise<Paginator<T>>;
     /** `chunk($count, $callback)`. */
     chunk(count: number, callback: (models: OrmCollection<T>) => void | Promise<void>): Promise<void>;
+    /**
+     * `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?: number): LazyCollection<T>;
     /** `lazy($chunkSize)`. */
-    lazy(chunkSize?: number): AsyncGenerator<T, void, unknown>;
+    lazy(chunkSize?: number): LazyCollection<T>;
     /** `chunkById`. */
     chunkById(count: number, callback: (models: OrmCollection<T>) => void | boolean | Promise<void | boolean>, column?: string): Promise<boolean>;
     chunkByIdDesc(count: number, callback: (models: OrmCollection<T>) => void | boolean | Promise<void | boolean>, column?: string): Promise<boolean>;
     /** `lazyById`. */
-    lazyById(chunkSize?: number, column?: string): AsyncGenerator<T, void, unknown>;
-    lazyByIdDesc(chunkSize?: number, column?: string): AsyncGenerator<T, void, unknown>;
+    lazyById(chunkSize?: number, column?: string): LazyCollection<T>;
+    lazyByIdDesc(chunkSize?: number, column?: string): LazyCollection<T>;
     increment(column: string, amount?: number): Promise<void>;
     decrement(column: string, amount?: number): Promise<void>;
     /** `cursorPaginate`. */