@bunnykit/orm 0.1.26 → 0.1.28

package/README.md

@@ -644,10 +644,10 @@ User.where("name", "Alice").dd();     // logs SQL and throws
 | `each(n, fn)`                                              | Per-item iterate                    |
 | `cursor()`                                                 | Lazy async generator                |
 | `lazy(n?)`                                                 | Chunked lazy generator              |
-| `insert(data)`                                             | Insert row(s)                       |
-| `insertGetId(data, col?)`                                  | Insert and return ID                |
-| `insertOrIgnore(data)`                                     | Insert, ignore conflicts            |
-| `upsert(data, uniqueBy, updateCols?)`                      | Insert or update on conflict        |
+| `insert(data, options?)`                                        | Insert row(s) with optional chunking     |
+| `insertGetId(data, col?)`                                       | Insert and return ID                    |
+| `insertOrIgnore(data)`                                          | Insert, ignore conflicts                |
+| `upsert(data, uniqueBy, updateCols?, options?)`                 | Insert or update on conflict, optional chunking |
 | `update(data)`                                             | Update matched rows                 |
 | `updateFrom(tbl, a, op, b)`                                | Update with JOIN                    |
 | `delete()`                                                 | Delete matched rows                 |
@@ -739,10 +739,123 @@ const user = await User.firstOrCreate(
   { email: "alice@example.com" },
   { name: "Alice" },
 );
-const user = await User.updateOrCreate(
+const user = await User.updateOrInsert(
   { email: "alice@example.com" },
   { name: "Alice Smith" },
 );
+
+// Bulk insert / upsert (apply fillable, casts, timestamps, UUID keys)
+await User.insert([
+  { name: "Alice", email: "alice1@example.com" },
+  { name: "Bob", email: "alice2@example.com" },
+], { chunkSize: 100 });
+
+await User.upsert(
+  [{ email: "alice@example.com", name: "Alice Updated" }],
+  "email",
+  ["name"],
+  { chunkSize: 100 },
+);
+
+// Bulk create / save (fire model events by default)
+const users = await User.createMany([
+  { name: "Alice", email: "alice@example.com" },
+  { name: "Bob", email: "bob@example.com" },
+]);
+
+await User.saveMany(users);
+
+// Bypass observers with { events: false }
+await User.createMany(records, { events: false });
+await User.saveMany(models, { events: false });
+model.save({ events: false });
+```
+
+### Bulk Operations
+
+Bunny provides bulk methods for inserting, upserting, and creating multiple records efficiently. All bulk insert and upsert operations apply fillable rules, attribute casts, timestamps, and UUID key generation automatically.
+
+#### Model.insert(records, options?)
+
+Insert raw records with automatic processing. Respects `fillable` guard, applies casts and timestamps, and generates UUID keys for `primaryKey = "uuid"` models.
+
+```ts
+await User.insert([
+  { name: "Alice", email: "alice@example.com" },
+  { name: "Bob", email: "bob@example.com" },
+], { chunkSize: 500 });
+```
+
+`chunkSize` batches large inserts to avoid exceeding query size limits.
+
+#### Model.upsert(records, uniqueBy, updateColumns?, options?)
+
+Insert or update records based on a unique key. On insert: applies fillable, casts, timestamps, and UUID generation. On update: only the specified `updateColumns` are modified.
+
+```ts
+// Insert or update by email, updating only the name
+await User.upsert(
+  [{ email: "alice@example.com", name: "Alice Updated" }],
+  "email",
+  ["name"],
+  { chunkSize: 500 },
+);
+
+// Insert or update by email, updating all columns except the unique key
+await User.upsert(
+  [{ email: "alice@example.com", name: "Alice", active: true }],
+  "email",
+);
+```
+
+#### Model.updateOrInsert(attributes, values)
+
+Find a record by `attributes` and update with `values`, or create a new record if not found. Combines `firstOrCreate` logic with the ability to pass explicit create values.
+
+```ts
+const user = await User.updateOrInsert(
+  { email: "alice@example.com" },
+  { name: "Alice Smith", active: true },
+);
+```
+
+#### Model.createMany(records, options?)
+
+Create multiple model instances with full ORM support. Fires `creating` / `created` observers by default. Pass `{ events: false }` to bypass observers for better performance.
+
+```ts
+const users = await User.createMany([
+  { name: "Alice", email: "alice@example.com" },
+  { name: "Bob", email: "bob@example.com" },
+]);
+
+// Bypass observers for bulk create
+await User.createMany(records, { events: false });
+```
+
+#### Model.saveMany(models, options?)
+
+Persist an array of new or existing model instances. Existing models trigger update observers and update `updated_at`. New models trigger create observers. Auto-increment IDs are preserved when saving new models silently one-by-one where needed. Pass `{ events: false }` to bypass all observers.
+
+```ts
+const users = [
+  new User({ name: "Alice" }),
+  new User({ id: 5, name: "Bob" }), // existing record
+];
+
+await User.saveMany(users);
+
+// Bypass observers for bulk save
+await User.saveMany(models, { events: false });
+```
+
+#### model.save(options?)
+
+Save an existing model instance. Pass `{ events: false }` to bypass `updating` / `updated` observers.
+
+```ts
+user.name = "Charlie";
+await user.save({ events: false });
 ```
 
 ### Default Attributes
@@ -972,6 +1085,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, BulkModelOptions, SaveOptions, 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 {
@@ -13,6 +19,13 @@ export type ModelAttributes<T> = T extends {
 export type ModelColumn<T> = LiteralUnion<Extract<keyof ModelAttributes<T>, string>>;
 export type ModelColumnValue<T, K> = K extends keyof ModelAttributes<T> ? ModelAttributes<T>[K] : any;
 export type ModelAttributeInput<T> = Partial<ModelAttributes<T>> & Record<string, any>;
+export interface BulkModelOptions {
+    chunkSize?: number;
+    events?: boolean;
+}
+export interface SaveOptions {
+    events?: boolean;
+}
 export type ModelRelationValue = Relation<any> | MorphTo<any> | MorphOne<any> | MorphMany<any> | MorphToMany<any> | BelongsToMany<any>;
 export type ModelRelationName<T> = LiteralUnion<Extract<{
     [K in keyof T]-?: T[K] extends (...args: any[]) => ModelRelationValue ? K : never;
@@ -126,8 +139,19 @@ export declare class Model<T extends Record<string, any> = Record<string, any>>
     static applyGlobalScopes(builder: Builder<any>): void;
     static getQualifiedDeletedAtColumn(): string;
     static shouldAutoGeneratePrimaryKey(): Promise<boolean>;
+    static prepareBulkRecords<M extends ModelConstructor>(this: M, records: ModelAttributeInput<InstanceType<M>>[]): Promise<Record<string, any>[]>;
+    static prepareBulkRecord<M extends ModelConstructor>(this: M, record: ModelAttributeInput<InstanceType<M>>, options?: {
+        touchCreatedAt?: boolean;
+        touchUpdatedAt?: boolean;
+        generatePrimaryKey?: boolean;
+    }): Promise<Record<string, any>>;
     static hydrate<M extends ModelConstructor>(this: M, row: Record<string, any>, connection?: Connection): InstanceType<M>;
     static create<M extends ModelConstructor>(this: M, attributes: ModelAttributeInput<InstanceType<M>>): Promise<InstanceType<M>>;
+    static insert<M extends ModelConstructor>(this: M, records: ModelAttributeInput<InstanceType<M>> | ModelAttributeInput<InstanceType<M>>[], options?: Omit<BulkModelOptions, "events">): Promise<any>;
+    static upsert<M extends ModelConstructor>(this: M, records: ModelAttributeInput<InstanceType<M>> | ModelAttributeInput<InstanceType<M>>[], uniqueBy: ModelColumn<InstanceType<M>> | ModelColumn<InstanceType<M>>[], updateColumns?: ModelColumn<InstanceType<M>>[], options?: Omit<BulkModelOptions, "events">): Promise<any>;
+    static updateOrInsert<M extends ModelConstructor>(this: M, attributes: ModelAttributeInput<InstanceType<M>>, values?: ModelAttributeInput<InstanceType<M>>): Promise<boolean>;
+    static createMany<M extends ModelConstructor>(this: M, records: ModelAttributeInput<InstanceType<M>>[], options?: BulkModelOptions): Promise<InstanceType<M>[]>;
+    static saveMany<M extends ModelConstructor>(this: M, models: InstanceType<M>[], options?: BulkModelOptions): Promise<InstanceType<M>[]>;
     static find<M extends ModelConstructor>(this: M, id: any): Promise<InstanceType<M> | null>;
     static findOrFail<M extends ModelConstructor>(this: M, id: any): Promise<InstanceType<M>>;
     static first<M extends ModelConstructor>(this: M): Promise<InstanceType<M> | null>;
@@ -168,7 +192,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 +212,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;
@@ -205,12 +230,12 @@ export declare class Model<T extends Record<string, any> = Record<string, any>>
     protected resolveCustomCast(cast: CastDefinition): CastsAttributes | null;
     getDirty(): Partial<T>;
     isDirty(): boolean;
-    save(): Promise<this>;
+    save(options?: SaveOptions): Promise<this>;
     updateTimestamps(): void;
     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

@@ -433,6 +433,33 @@ export class Model {
         const numericTypes = new Set(["integer", "int", "bigint", "smallint", "tinyint", "real", "float", "double", "decimal", "numeric"]);
         return !numericTypes.has(type);
     }
+    static async prepareBulkRecords(records) {
+        const prepared = [];
+        for (const record of records) {
+            prepared.push(await this.prepareBulkRecord(record));
+        }
+        return prepared;
+    }
+    static async prepareBulkRecord(record, options = {}) {
+        const instance = new this();
+        instance.fill(record);
+        const attributes = { ...instance.$attributes };
+        if (this.timestamps) {
+            const now = instance.freshTimestamp();
+            if (options.touchCreatedAt !== false && attributes.created_at === undefined)
+                attributes.created_at = now;
+            if (options.touchUpdatedAt !== false && attributes.updated_at === undefined)
+                attributes.updated_at = now;
+        }
+        if (options.generatePrimaryKey !== false) {
+            const primaryKey = this.primaryKey;
+            const primaryKeyValue = attributes[primaryKey];
+            if ((primaryKeyValue === null || primaryKeyValue === undefined || primaryKeyValue === "") && await this.shouldAutoGeneratePrimaryKey()) {
+                attributes[primaryKey] = crypto.randomUUID();
+            }
+        }
+        return attributes;
+    }
     static hydrate(row, connection) {
         const instance = new this();
         instance.$attributes = { ...instance.$attributes, ...row };
@@ -450,6 +477,100 @@ export class Model {
         await instance.save();
         return instance;
     }
+    static async insert(records, options = {}) {
+        const prepared = await this.prepareBulkRecords(Array.isArray(records) ? records : [records]);
+        const chunkSize = options.chunkSize || prepared.length || 1;
+        let result;
+        for (let i = 0; i < prepared.length; i += chunkSize) {
+            result = await this.query().insert(prepared.slice(i, i + chunkSize));
+        }
+        return result;
+    }
+    static async upsert(records, uniqueBy, updateColumns, options = {}) {
+        const prepared = await this.prepareBulkRecords(Array.isArray(records) ? records : [records]);
+        const chunkSize = options.chunkSize || prepared.length || 1;
+        let columns = updateColumns;
+        if (!columns && this.timestamps) {
+            const uniqueColumns = new Set(Array.isArray(uniqueBy) ? uniqueBy : [uniqueBy]);
+            columns = Object.keys(prepared[0] || {}).filter((column) => column !== "created_at" && !uniqueColumns.has(column));
+        }
+        let result;
+        for (let i = 0; i < prepared.length; i += chunkSize) {
+            result = await this.query().upsert(prepared.slice(i, i + chunkSize), uniqueBy, columns);
+        }
+        return result;
+    }
+    static async updateOrInsert(attributes, values = {}) {
+        const existing = await this.where(attributes).first();
+        if (existing) {
+            const update = await this.prepareBulkRecord(values, { touchUpdatedAt: true, touchCreatedAt: false, generatePrimaryKey: false });
+            await this.where(attributes).update(update);
+            return true;
+        }
+        await this.insert({ ...attributes, ...values });
+        return true;
+    }
+    static async createMany(records, options = {}) {
+        const models = records.map((attributes) => new this(attributes));
+        await this.saveMany(models, options);
+        return models;
+    }
+    static async saveMany(models, options = {}) {
+        const chunkSize = options.chunkSize || models.length || 1;
+        const events = options.events !== false;
+        if (events) {
+            for (const model of models) {
+                await model.save();
+            }
+            return models;
+        }
+        for (let i = 0; i < models.length; i += chunkSize) {
+            const chunk = models.slice(i, i + chunkSize);
+            const newModels = chunk.filter((model) => !model.$exists);
+            const existingModels = chunk.filter((model) => model.$exists);
+            if (newModels.length > 0) {
+                const shouldGeneratePrimaryKey = await this.shouldAutoGeneratePrimaryKey();
+                const bulkModels = [];
+                for (const model of newModels) {
+                    const pk = model.getAttribute(this.primaryKey);
+                    if (!shouldGeneratePrimaryKey && (pk === null || pk === undefined || pk === "")) {
+                        const record = await this.prepareBulkRecord(model.$attributes);
+                        const id = await this.query().insertGetId(record);
+                        if (id)
+                            record[this.primaryKey] = id;
+                        model.$attributes = record;
+                        model.$original = { ...record };
+                        model.$exists = true;
+                    }
+                    else {
+                        bulkModels.push(model);
+                    }
+                }
+                if (bulkModels.length > 0) {
+                    const records = await this.prepareBulkRecords(bulkModels.map((model) => model.$attributes));
+                    await this.query().insert(records);
+                    for (let index = 0; index < bulkModels.length; index++) {
+                        bulkModels[index].$attributes = records[index];
+                        bulkModels[index].$original = { ...records[index] };
+                        bulkModels[index].$exists = true;
+                    }
+                }
+            }
+            for (const model of existingModels) {
+                let dirty = model.getDirty();
+                if (Object.keys(dirty).length > 0 && this.timestamps) {
+                    model.$attributes.updated_at = model.freshTimestamp();
+                    delete model.$castCache.updated_at;
+                    dirty = model.getDirty();
+                }
+                if (Object.keys(dirty).length === 0)
+                    continue;
+                await this.query().where(this.primaryKey, model.getAttribute(this.primaryKey)).update(dirty);
+                model.$original = { ...model.$attributes };
+            }
+        }
+        return models;
+    }
     static async find(id) {
         return this.query().find(id, this.primaryKey);
     }
@@ -629,34 +750,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 eagerLoadRelation(models, relationName) {
+    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, 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);
     }
@@ -805,10 +957,12 @@ export class Model {
     isDirty() {
         return Object.keys(this.getDirty()).length > 0;
     }
-    async save() {
+    async save(options = {}) {
         const constructor = this.constructor;
+        const events = options.events !== false;
         if (this.$exists) {
-            await ObserverRegistry.dispatch("saving", this);
+            if (events)
+                await ObserverRegistry.dispatch("saving", this);
             let dirty = this.getDirty();
             if (Object.keys(dirty).length > 0 && constructor.timestamps) {
                 this.$attributes["updated_at"] = this.freshTimestamp();
@@ -816,20 +970,25 @@ export class Model {
                 dirty = this.getDirty();
             }
             if (Object.keys(dirty).length > 0) {
-                await ObserverRegistry.dispatch("updating", this);
+                if (events)
+                    await ObserverRegistry.dispatch("updating", this);
                 const pk = this.getAttribute(constructor.primaryKey);
                 const connection = this.getConnection();
                 await new Builder(connection, connection.qualifyTable(constructor.getTable()))
                     .where(constructor.primaryKey, pk)
                     .update(dirty);
-                await ObserverRegistry.dispatch("updated", this);
+                if (events)
+                    await ObserverRegistry.dispatch("updated", this);
             }
             this.$original = { ...this.$attributes };
-            await ObserverRegistry.dispatch("saved", this);
+            if (events)
+                await ObserverRegistry.dispatch("saved", this);
         }
         else {
-            await ObserverRegistry.dispatch("creating", this);
-            await ObserverRegistry.dispatch("saving", this);
+            if (events)
+                await ObserverRegistry.dispatch("creating", this);
+            if (events)
+                await ObserverRegistry.dispatch("saving", this);
             if (constructor.timestamps) {
                 const now = this.freshTimestamp();
                 this.$attributes["created_at"] = now;
@@ -858,8 +1017,10 @@ export class Model {
             }
             this.$exists = true;
             this.$original = { ...this.$attributes };
-            await ObserverRegistry.dispatch("created", this);
-            await ObserverRegistry.dispatch("saved", this);
+            if (events)
+                await ObserverRegistry.dispatch("created", this);
+            if (events)
+                await ObserverRegistry.dispatch("saved", this);
         }
         const identityMap = IdentityMap.current();
         if (identityMap) {

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.28",
   "description": "An Eloquent-inspired ORM for Bun's native SQL client supporting SQLite, MySQL, and PostgreSQL.",
   "license": "MIT",
   "packageManager": "bun@1.3.12",