@bunnykit/orm 0.1.27 → 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

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, EagerLoadConstraint, EagerLoadDefinition, EagerLoadInput, 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

@@ -19,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;
@@ -132,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>;
@@ -212,7 +230,7 @@ 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>;

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);
     }
@@ -836,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();
@@ -847,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;
@@ -889,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bunnykit/orm",
-  "version": "0.1.27",
+  "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",