@bunnykit/orm 0.1.26 → 0.1.27

package/README.md

@@ -972,6 +972,48 @@ class User extends Model {
 const post = await user.latestPost().getResults();
 ```
 
+### Eager Loading
+
+Use `with()` to eager load relations for query results:
+
+```ts
+const users = await User.with("posts", "profile").get();
+const posts = await Post.with("author").get();
+```
+
+Nested relations use dot notation:
+
+```ts
+const users = await User.with("posts.comments").get();
+```
+
+You can constrain an eager-loaded relation by passing an object whose key is the relation name and whose value is a query callback:
+
+```ts
+const users = await User.with({
+  posts: (query) => {
+    query.where("status", "published").orderBy("created_at", "desc");
+  },
+}).get();
+```
+
+Nested eager loads can be constrained too:
+
+```ts
+const users = await User.with(
+  { posts: (query) => query.where("status", "published") },
+  { "posts.comments": (query) => query.where("approved", true) },
+).get();
+```
+
+Constrained eager loading is also available when loading relations onto an existing model:
+
+```ts
+await user.load({
+  posts: (query) => query.where("status", "published"),
+});
+```
+
 ### Relation Queries and Aggregates
 
 Filter models by related records:

package/dist/src/index.d.ts

@@ -14,7 +14,7 @@ export { MySqlGrammar } from "./schema/grammars/MySqlGrammar.js";
 export { PostgresGrammar } from "./schema/grammars/PostgresGrammar.js";
 export { Builder } from "./query/Builder.js";
 export { Model, HasMany, BelongsTo, HasOne, HasManyThrough, HasOneThrough } from "./model/Model.js";
-export type { ModelAttributeInput, ModelAttributes, ModelColumn, ModelColumnValue, ModelConstructor, ModelRelationName, GlobalScope, CastDefinition, CastsAttributes, } from "./model/Model.js";
+export type { ModelAttributeInput, ModelAttributes, ModelColumn, ModelColumnValue, ModelConstructor, ModelRelationName, EagerLoadConstraint, EagerLoadDefinition, EagerLoadInput, GlobalScope, CastDefinition, CastsAttributes, } from "./model/Model.js";
 export { ModelNotFoundError } from "./model/ModelNotFoundError.js";
 export { ObserverRegistry, type ObserverContract } from "./model/Observer.js";
 export { MorphMap } from "./model/MorphMap.js";

package/dist/src/model/Model.d.ts

@@ -5,6 +5,12 @@ import { BelongsToMany } from "./BelongsToMany.js";
 export type ModelConstructor<T extends Model = Model> = (new (...args: any[]) => T) & Omit<typeof Model, "prototype">;
 export type GlobalScope = (builder: Builder<any>, model: ModelConstructor) => void;
 export type LiteralUnion<T extends string> = T | (string & {});
+export type EagerLoadConstraint = (query: Builder<any>) => void | Builder<any>;
+export interface EagerLoadDefinition {
+    name: string;
+    constraint?: EagerLoadConstraint;
+}
+export type EagerLoadInput = string | EagerLoadDefinition | Record<string, EagerLoadConstraint | undefined>;
 type BaseModelInstanceKey = "$attributes" | "$original" | "$exists" | "$relations" | "$casts" | "$castCache" | "$connection" | "fill" | "setConnection" | "getConnection" | "isFillable" | "getAttribute" | "setAttribute" | "castAttribute" | "serializeCastAttribute" | "mergeCasts" | "getDirty" | "isDirty" | "save" | "updateTimestamps" | "touch" | "increment" | "decrement" | "load" | "delete" | "restore" | "forceDelete" | "refresh" | "toJSON" | "toString" | "freshTimestamp" | "setRelation" | "getRelation" | "hasMany" | "belongsTo" | "hasOne" | "hasManyThrough" | "hasOneThrough" | "belongsToMany" | "morphTo" | "morphOne" | "morphMany" | "morphToMany" | "morphedByMany";
 export type ModelInstanceAttributeKeys<T> = Extract<Exclude<keyof T, BaseModelInstanceKey>, string>;
 export type ModelAttributes<T> = T extends {
@@ -168,7 +174,7 @@ export declare class Model<T extends Record<string, any> = Record<string, any>>
     static inRandomOrder<M extends ModelConstructor>(this: M): Builder<InstanceType<M>>;
     static lockForUpdate<M extends ModelConstructor>(this: M): Builder<InstanceType<M>>;
     static sharedLock<M extends ModelConstructor>(this: M): Builder<InstanceType<M>>;
-    static with<M extends ModelConstructor>(this: M, ...relations: ModelRelationName<InstanceType<M>>[]): Builder<InstanceType<M>>;
+    static with<M extends ModelConstructor>(this: M, ...relations: (ModelRelationName<InstanceType<M>> | EagerLoadInput | EagerLoadInput[])[]): Builder<InstanceType<M>>;
     static withTrashed<M extends ModelConstructor>(this: M): Builder<InstanceType<M>>;
     static onlyTrashed<M extends ModelConstructor>(this: M): Builder<InstanceType<M>>;
     static withoutGlobalScope<M extends ModelConstructor>(this: M, scope: string): Builder<InstanceType<M>>;
@@ -188,8 +194,9 @@ export declare class Model<T extends Record<string, any> = Record<string, any>>
     static each<M extends ModelConstructor>(this: M, count: number, callback: (item: InstanceType<M>) => void | Promise<void>): Promise<void>;
     static cursor<M extends ModelConstructor>(this: M): AsyncGenerator<InstanceType<M>>;
     static lazy<M extends ModelConstructor>(this: M, count?: number): AsyncGenerator<InstanceType<M>>;
-    static eagerLoadRelations(models: Model[], relations: string[]): Promise<void>;
-    static eagerLoadRelation(models: Model[], relationName: string): Promise<void>;
+    static normalizeEagerLoads(relations: (EagerLoadInput | EagerLoadInput[])[]): EagerLoadDefinition[];
+    static eagerLoadRelations(models: Model[], relations: (string | EagerLoadDefinition)[]): Promise<void>;
+    static eagerLoadRelation(models: Model[], relationName: string, constraint?: EagerLoadConstraint): Promise<void>;
     fill(attributes: Partial<T> | ModelAttributeInput<this>): this;
     setConnection(connection: Connection): this;
     getConnection(): Connection;
@@ -210,7 +217,7 @@ export declare class Model<T extends Record<string, any> = Record<string, any>>
     touch(): Promise<boolean>;
     increment<K extends ModelColumn<this>>(column: K, amount?: number, extra?: ModelAttributeInput<this>): Promise<this>;
     decrement<K extends ModelColumn<this>>(column: K, amount?: number, extra?: ModelAttributeInput<this>): Promise<this>;
-    load(...relations: string[]): Promise<this>;
+    load(...relations: (string | EagerLoadInput | EagerLoadInput[])[]): Promise<this>;
     delete(): Promise<boolean>;
     restore(): Promise<boolean>;
     forceDelete(): Promise<boolean>;

package/dist/src/model/Model.js

@@ -629,34 +629,65 @@ export class Model {
     static lazy(count) {
         return this.query().lazy(count);
     }
-    static async eagerLoadRelations(models, relations) {
-        for (const relationName of relations) {
-            if (relationName.includes(".")) {
-                const [first, ...rest] = relationName.split(".");
-                await this.eagerLoadRelation(models, first);
-                const nestedModels = [];
-                for (const model of models) {
-                    const related = model.getRelation(first);
-                    if (Array.isArray(related))
-                        nestedModels.push(...related);
-                    else if (related)
-                        nestedModels.push(related);
-                }
-                if (nestedModels.length > 0) {
-                    await this.eagerLoadRelations(nestedModels, [rest.join(".")]);
-                }
+    static normalizeEagerLoads(relations) {
+        const normalized = [];
+        for (const relation of relations.flat()) {
+            if (typeof relation === "string") {
+                normalized.push({ name: relation });
+            }
+            else if ("name" in relation && typeof relation.name === "string") {
+                normalized.push(relation);
             }
             else {
-                await this.eagerLoadRelation(models, relationName);
+                for (const [name, constraint] of Object.entries(relation)) {
+                    normalized.push({ name, constraint });
+                }
+            }
+        }
+        return normalized;
+    }
+    static async eagerLoadRelations(models, relations) {
+        const normalized = this.normalizeEagerLoads(relations);
+        const groups = new Map();
+        for (const definition of normalized) {
+            const [first] = definition.name.split(".");
+            const group = groups.get(first) || [];
+            group.push(definition);
+            groups.set(first, group);
+        }
+        for (const [relationName, definitions] of groups) {
+            const direct = definitions.find((definition) => definition.name === relationName);
+            await this.eagerLoadRelation(models, relationName, direct?.constraint);
+            const nestedDefinitions = definitions
+                .filter((definition) => definition.name.includes("."))
+                .map((definition) => ({
+                name: definition.name.split(".").slice(1).join("."),
+                constraint: definition.constraint,
+            }));
+            if (nestedDefinitions.length === 0)
+                continue;
+            const nestedModels = [];
+            for (const model of models) {
+                const related = model.getRelation(relationName);
+                if (Array.isArray(related))
+                    nestedModels.push(...related);
+                else if (related)
+                    nestedModels.push(related);
+            }
+            if (nestedModels.length > 0) {
+                await this.eagerLoadRelations(nestedModels, nestedDefinitions);
             }
         }
     }
-    static async eagerLoadRelation(models, relationName) {
+    static async eagerLoadRelation(models, relationName, constraint) {
         if (models.length === 0)
             return;
         const firstModel = models[0];
         const relation = firstModel[relationName]();
         relation.addEagerConstraints(models);
+        if (constraint) {
+            constraint(relation.getQuery());
+        }
         const results = await relation.getEager();
         relation.match(models, results, relationName);
     }

package/dist/src/query/Builder.d.ts

@@ -1,6 +1,6 @@
 import { Connection } from "../connection/Connection.js";
 import type { WhereClause, OrderClause, HavingClause, UnionClause } from "../types/index.js";
-import type { ModelAttributeInput, ModelColumn, ModelColumnValue, ModelConstructor, ModelRelationName } from "../model/Model.js";
+import type { EagerLoadDefinition, EagerLoadInput, ModelAttributeInput, ModelColumn, ModelColumnValue, ModelConstructor } from "../model/Model.js";
 type RelationConstraint = (query: Builder<any>) => void | Builder<any>;
 export interface Paginator<T> {
     data: T[];
@@ -24,7 +24,7 @@ export declare class Builder<T = Record<string, any>> {
     joins: string[];
     distinctFlag: boolean;
     model?: ModelConstructor;
-    eagerLoads: string[];
+    eagerLoads: EagerLoadDefinition[];
     randomOrderFlag: boolean;
     lockMode?: string;
     unions: UnionClause[];
@@ -36,6 +36,7 @@ export declare class Builder<T = Record<string, any>> {
     constructor(connection: Connection, table: string);
     private get grammar();
     private invalidateSqlCache;
+    private normalizeEagerLoads;
     setModel(model: ModelConstructor): this;
     table(table: string): this;
     select(...columns: ModelColumn<T>[]): this;
@@ -106,7 +107,7 @@ export declare class Builder<T = Record<string, any>> {
     crossJoin(table: string): this;
     union(query: Builder<T> | string, all?: boolean): this;
     unionAll(query: Builder<T> | string): this;
-    with(...relations: ModelRelationName<T>[]): this;
+    with(...relations: (EagerLoadInput | EagerLoadInput[])[]): this;
     withoutGlobalScope(scope: string): this;
     withoutGlobalScopes(): this;
     withTrashed(): this;

package/dist/src/query/Builder.js

@@ -32,6 +32,23 @@ export class Builder {
     invalidateSqlCache() {
         this.sqlCache = undefined;
     }
+    normalizeEagerLoads(relations) {
+        const normalized = [];
+        for (const relation of relations.flat()) {
+            if (typeof relation === "string") {
+                normalized.push({ name: relation });
+            }
+            else if ("name" in relation && typeof relation.name === "string") {
+                normalized.push(relation);
+            }
+            else {
+                for (const [name, constraint] of Object.entries(relation)) {
+                    normalized.push({ name, constraint });
+                }
+            }
+        }
+        return normalized;
+    }
     setModel(model) {
         this.model = model;
         return this;
@@ -332,7 +349,7 @@ export class Builder {
         return this.union(query, true);
     }
     with(...relations) {
-        this.eagerLoads.push(...relations);
+        this.eagerLoads.push(...this.normalizeEagerLoads(relations));
         return this;
     }
     withoutGlobalScope(scope) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bunnykit/orm",
-  "version": "0.1.26",
+  "version": "0.1.27",
   "description": "An Eloquent-inspired ORM for Bun's native SQL client supporting SQLite, MySQL, and PostgreSQL.",
   "license": "MIT",
   "packageManager": "bun@1.3.12",