@bunnykit/orm 0.1.3 → 0.1.5

package/README.md

@@ -18,11 +18,12 @@ An **Eloquent-inspired ORM** built specifically for [Bun](https://bun.sh)'s nati
 - 📦 **Multi-database** — SQLite, MySQL, and PostgreSQL support
 - 🔷 **Fully Typed** — Written in TypeScript with generics everywhere
 - 🏗️ **Schema Builder** — Programmatic table creation, indexes, foreign keys
-- 🔍 **Query Builder** — Chainable `where`, `join`, `orderBy`, `groupBy`, etc.
-- 🧬 **Eloquent-style Models** — Property attributes, defaults, casts, dirty tracking, soft deletes, scopes
+- 🔍 **Query Builder** — Chainable `where`, `join`, `orderBy`, `groupBy`, date filters, conditional building, etc.
+- 🧬 **Eloquent-style Models** — Property attributes, defaults, casts, dirty tracking, soft deletes, scopes, find-or-fail, first-or-create
 - 🔗 **Relations** — Standard, many-to-many, polymorphic, through, one-of-many, and relation queries
 - 👁️ **Observers** — Lifecycle hooks (`creating`, `created`, `updating`, `updated`, etc.)
 - 🚀 **Migrations & CLI** — Create, run, and rollback migrations from the command line
+- ⚡ **Streaming** — `chunk`, `cursor`, `each`, and `lazy` for memory-efficient large dataset processing
 
 ---
 
@@ -261,6 +262,14 @@ User.where({ role: "admin", active: true });
 User.whereIn("id", [1, 2, 3]);
 User.whereNull("deleted_at");
 User.whereNotNull("email");
+User.whereNot("status", "banned");
+
+// Date filtering (cross-database)
+Event.whereDate("happened_at", "2024-01-01");
+Event.whereYear("created_at", ">=", 2023);
+Event.whereMonth("birthday", 12);
+Event.whereDay("anniversary", 14);
+Event.whereTime("opened_at", "09:00:00");
 
 // Chaining
 const results = await User
@@ -271,6 +280,16 @@ const results = await User
   .offset(0)
   .get();
 
+// Conditional building
+User.when(filters.name, (q) => q.where("name", filters.name))
+    .when(filters.age,  (q) => q.where("age", ">=", filters.age))
+    .unless(showAll,    (q) => q.where("active", true))
+    .tap((q) => console.log(q.toSql()));
+
+// Ordering convenience
+Post.latest().first();        // orderBy created_at desc
+Post.oldest("published_at");  // orderBy published_at asc
+
 // Aggregates
 const count = await User.where("active", true).count();
 const exists = await User.where("email", "test@example.com").exists();
@@ -288,6 +307,16 @@ const emails = await User.pluck("email");
 // First / Find
 const user = await User.where("email", "alice@example.com").first();
 const byId = await User.find(1);
+
+// Find-or-Fail (throws if not found)
+const user = await User.findOrFail(1);
+const first = await User.firstOrFail();
+
+// Streaming large datasets
+await User.chunk(100, (users) => { ... });
+await User.each(100, (user) => { ... });
+for await (const user of User.cursor()) { ... }
+for await (const user of User.lazy(500)) { ... }
 ```
 
 ---
@@ -345,7 +374,18 @@ user.getDirty();          // { name: "Charlie" }
 await user.save();
 await user.delete();
 await user.refresh();
+await user.touch();       // update only timestamps
+await user.load("posts"); // lazy eager loading
 user.toJSON();            // plain object
+
+// Increment / Decrement
+await user.increment("login_count");
+await user.increment("login_count", 5, { last_login_at: new Date() });
+await user.decrement("stock", 10);
+
+// First-or-Create / Update-or-Create
+const user = await User.firstOrCreate({ email: "alice@example.com" }, { name: "Alice" });
+const user = await User.updateOrCreate({ email: "alice@example.com" }, { name: "Alice Smith" });
 ```
 
 ### Default Attributes
@@ -932,7 +972,7 @@ Bunny includes a full test suite built with `bun:test`.
 bun test
 ```
 
-92 tests covering connection management, schema grammars, query builder, model CRUD, casts, scopes, soft deletes, relations, observers, migrations, and type generation.
+139 tests covering connection management, schema grammars, query builder, model CRUD, casts, scopes, soft deletes, relations, observers, migrations, type generation, lazy eager loading, find-or-fail, first-or-create, increment/decrement, touch, chunk/cursor/lazy streaming, date where clauses, conditional query building, whereNot, and latest/oldest.
 
 ---
 

package/dist/src/index.d.ts

@@ -9,6 +9,7 @@ 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 { ModelConstructor, 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";
 export { MorphTo, MorphOne, MorphMany, MorphToMany } from "./model/MorphRelations.js";

package/dist/src/index.js

@@ -7,6 +7,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 { ModelNotFoundError } from "./model/ModelNotFoundError.js";
 export { ObserverRegistry } from "./model/Observer.js";
 export { MorphMap } from "./model/MorphMap.js";
 export { MorphTo, MorphOne, MorphMany, MorphToMany } from "./model/MorphRelations.js";

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

@@ -109,12 +109,39 @@ export declare class Model<T extends Record<string, any> = Record<string, any>>
     static shouldAutoGeneratePrimaryKey(): Promise<boolean>;
     static create<M extends typeof Model>(this: M, attributes: Partial<InstanceType<M> extends Model<infer U> ? U : Record<string, any>>): Promise<InstanceType<M>>;
     static find<M extends typeof Model>(this: M, id: any): Promise<InstanceType<M> | null>;
+    static findOrFail<M extends typeof Model>(this: M, id: any): Promise<InstanceType<M>>;
     static first<M extends typeof Model>(this: M): Promise<InstanceType<M> | null>;
+    static firstOrFail<M extends typeof Model>(this: M): Promise<InstanceType<M>>;
+    static firstOrCreate<M extends typeof Model>(this: M, attributes?: Record<string, any>, values?: Record<string, any>): Promise<InstanceType<M>>;
+    static updateOrCreate<M extends typeof Model>(this: M, attributes: Record<string, any>, values?: Record<string, any>): Promise<InstanceType<M>>;
     static where<M extends typeof Model>(this: M, column: string | Record<string, any>, operator?: string | any, value?: any): Builder<InstanceType<M>>;
+    static orderBy<M extends typeof Model>(this: M, column: string, direction?: "asc" | "desc"): Builder<InstanceType<M>>;
     static whereIn<M extends typeof Model>(this: M, column: string, values: any[]): Builder<InstanceType<M>>;
     static whereNull<M extends typeof Model>(this: M, column: string): Builder<InstanceType<M>>;
     static whereNotNull<M extends typeof Model>(this: M, column: string): Builder<InstanceType<M>>;
     static orWhere<M extends typeof Model>(this: M, column: string | Record<string, any>, operator?: string | any, value?: any): Builder<InstanceType<M>>;
+    static whereNot<M extends typeof Model>(this: M, column: string | Record<string, any>, value?: any): Builder<InstanceType<M>>;
+    static orWhereNot<M extends typeof Model>(this: M, column: string | Record<string, any>, value?: any): Builder<InstanceType<M>>;
+    static whereDate<M extends typeof Model>(this: M, column: string, operator?: string | any, value?: any): Builder<InstanceType<M>>;
+    static orWhereDate<M extends typeof Model>(this: M, column: string, operator?: string | any, value?: any): Builder<InstanceType<M>>;
+    static whereDay<M extends typeof Model>(this: M, column: string, operator?: string | any, value?: any): Builder<InstanceType<M>>;
+    static orWhereDay<M extends typeof Model>(this: M, column: string, operator?: string | any, value?: any): Builder<InstanceType<M>>;
+    static whereMonth<M extends typeof Model>(this: M, column: string, operator?: string | any, value?: any): Builder<InstanceType<M>>;
+    static orWhereMonth<M extends typeof Model>(this: M, column: string, operator?: string | any, value?: any): Builder<InstanceType<M>>;
+    static whereYear<M extends typeof Model>(this: M, column: string, operator?: string | any, value?: any): Builder<InstanceType<M>>;
+    static orWhereYear<M extends typeof Model>(this: M, column: string, operator?: string | any, value?: any): Builder<InstanceType<M>>;
+    static whereTime<M extends typeof Model>(this: M, column: string, operator?: string | any, value?: any): Builder<InstanceType<M>>;
+    static orWhereTime<M extends typeof Model>(this: M, column: string, operator?: string | any, value?: any): Builder<InstanceType<M>>;
+    static latest<M extends typeof Model>(this: M, column?: string): Builder<InstanceType<M>>;
+    static oldest<M extends typeof Model>(this: M, column?: string): Builder<InstanceType<M>>;
+    static when<M extends typeof Model>(this: M, condition: any, callback: (query: Builder<any>) => void | Builder<any>, defaultCallback?: (query: Builder<any>) => void | Builder<any>): Builder<InstanceType<M>>;
+    static unless<M extends typeof Model>(this: M, condition: any, callback: (query: Builder<any>) => void | Builder<any>, defaultCallback?: (query: Builder<any>) => void | Builder<any>): Builder<InstanceType<M>>;
+    static tap<M extends typeof Model>(this: M, callback: (query: Builder<any>) => void | Builder<any>): Builder<InstanceType<M>>;
+    static take<M extends typeof Model>(this: M, count: number): Builder<InstanceType<M>>;
+    static skip<M extends typeof Model>(this: M, count: number): Builder<InstanceType<M>>;
+    static inRandomOrder<M extends typeof Model>(this: M): Builder<InstanceType<M>>;
+    static lockForUpdate<M extends typeof Model>(this: M): Builder<InstanceType<M>>;
+    static sharedLock<M extends typeof Model>(this: M): Builder<InstanceType<M>>;
     static with<M extends typeof Model>(this: M, ...relations: string[]): Builder<InstanceType<M>>;
     static withTrashed<M extends typeof Model>(this: M): Builder<InstanceType<M>>;
     static onlyTrashed<M extends typeof Model>(this: M): Builder<InstanceType<M>>;
@@ -131,6 +158,10 @@ export declare class Model<T extends Record<string, any> = Record<string, any>>
     static withMax<M extends typeof Model>(this: M, relationName: string, column: string, alias?: string): Builder<InstanceType<M>>;
     static all<M extends typeof Model>(this: M): Promise<InstanceType<M>[]>;
     static paginate<M extends typeof Model>(this: M, perPage?: number, page?: number): Promise<import("../query/Builder.js").Paginator<InstanceType<M>>>;
+    static chunk<M extends typeof Model>(this: M, count: number, callback: (items: InstanceType<M>[]) => void | Promise<void>): Promise<void>;
+    static each<M extends typeof Model>(this: M, count: number, callback: (item: InstanceType<M>) => void | Promise<void>): Promise<void>;
+    static cursor<M extends typeof Model>(this: M): AsyncGenerator<InstanceType<M>>;
+    static lazy<M extends typeof Model>(this: M, count?: number): AsyncGenerator<InstanceType<M>>;
     static eagerLoadRelations(models: Model[], relations: string[]): Promise<void>;
     static eagerLoadRelation(models: Model[], relationName: string): Promise<void>;
     fill(attributes: Partial<T>): this;
@@ -147,6 +178,11 @@ export declare class Model<T extends Record<string, any> = Record<string, any>>
     getDirty(): Partial<T>;
     isDirty(): boolean;
     save(): Promise<this>;
+    updateTimestamps(): void;
+    touch(): Promise<boolean>;
+    increment(column: string, amount?: number, extra?: Record<string, any>): Promise<this>;
+    decrement(column: string, amount?: number, extra?: Record<string, any>): Promise<this>;
+    load(...relations: string[]): Promise<this>;
     delete(): Promise<boolean>;
     restore(): Promise<boolean>;
     forceDelete(): Promise<boolean>;

package/dist/src/model/Model.js

@@ -4,6 +4,7 @@ import { ObserverRegistry } from "./Observer.js";
 import { MorphTo, MorphOne, MorphMany, MorphToMany } from "./MorphRelations.js";
 import { BelongsToMany } from "./BelongsToMany.js";
 import { Schema } from "../schema/Schema.js";
+import { ModelNotFoundError } from "./ModelNotFoundError.js";
 const globalScopes = new WeakMap();
 function getGlobalScopes(model) {
     const scopes = new Map();
@@ -397,12 +398,44 @@ export class Model {
     static async find(id) {
         return this.query().find(id, this.primaryKey);
     }
+    static async findOrFail(id) {
+        const result = await this.find(id);
+        if (!result) {
+            throw new ModelNotFoundError(this.name, id);
+        }
+        return result;
+    }
     static async first() {
         return this.query().first();
     }
+    static async firstOrFail() {
+        const result = await this.first();
+        if (!result) {
+            throw new ModelNotFoundError(this.name);
+        }
+        return result;
+    }
+    static async firstOrCreate(attributes = {}, values = {}) {
+        const found = await this.where(attributes).first();
+        if (found)
+            return found;
+        return this.create({ ...attributes, ...values });
+    }
+    static async updateOrCreate(attributes, values = {}) {
+        const found = await this.where(attributes).first();
+        if (found) {
+            found.fill(values);
+            await found.save();
+            return found;
+        }
+        return this.create({ ...attributes, ...values });
+    }
     static where(column, operator, value) {
         return this.query().where(column, operator, value);
     }
+    static orderBy(column, direction) {
+        return this.query().orderBy(column, direction);
+    }
     static whereIn(column, values) {
         return this.query().whereIn(column, values);
     }
@@ -415,6 +448,72 @@ export class Model {
     static orWhere(column, operator, value) {
         return this.query().orWhere(column, operator, value);
     }
+    static whereNot(column, value) {
+        return this.query().whereNot(column, value);
+    }
+    static orWhereNot(column, value) {
+        return this.query().orWhereNot(column, value);
+    }
+    static whereDate(column, operator, value) {
+        return this.query().whereDate(column, operator, value);
+    }
+    static orWhereDate(column, operator, value) {
+        return this.query().orWhereDate(column, operator, value);
+    }
+    static whereDay(column, operator, value) {
+        return this.query().whereDay(column, operator, value);
+    }
+    static orWhereDay(column, operator, value) {
+        return this.query().orWhereDay(column, operator, value);
+    }
+    static whereMonth(column, operator, value) {
+        return this.query().whereMonth(column, operator, value);
+    }
+    static orWhereMonth(column, operator, value) {
+        return this.query().orWhereMonth(column, operator, value);
+    }
+    static whereYear(column, operator, value) {
+        return this.query().whereYear(column, operator, value);
+    }
+    static orWhereYear(column, operator, value) {
+        return this.query().orWhereYear(column, operator, value);
+    }
+    static whereTime(column, operator, value) {
+        return this.query().whereTime(column, operator, value);
+    }
+    static orWhereTime(column, operator, value) {
+        return this.query().orWhereTime(column, operator, value);
+    }
+    static latest(column) {
+        return this.query().latest(column);
+    }
+    static oldest(column) {
+        return this.query().oldest(column);
+    }
+    static when(condition, callback, defaultCallback) {
+        return this.query().when(condition, callback, defaultCallback);
+    }
+    static unless(condition, callback, defaultCallback) {
+        return this.query().unless(condition, callback, defaultCallback);
+    }
+    static tap(callback) {
+        return this.query().tap(callback);
+    }
+    static take(count) {
+        return this.query().take(count);
+    }
+    static skip(count) {
+        return this.query().skip(count);
+    }
+    static inRandomOrder() {
+        return this.query().inRandomOrder();
+    }
+    static lockForUpdate() {
+        return this.query().lockForUpdate();
+    }
+    static sharedLock() {
+        return this.query().sharedLock();
+    }
     static with(...relations) {
         return this.query().with(...relations);
     }
@@ -463,6 +562,18 @@ export class Model {
     static async paginate(perPage, page) {
         return this.query().paginate(perPage, page);
     }
+    static async chunk(count, callback) {
+        return this.query().chunk(count, callback);
+    }
+    static async each(count, callback) {
+        return this.query().each(count, callback);
+    }
+    static cursor() {
+        return this.query().cursor();
+    }
+    static lazy(count) {
+        return this.query().lazy(count);
+    }
     static async eagerLoadRelations(models, relations) {
         for (const relationName of relations) {
             if (relationName.includes(".")) {
@@ -673,6 +784,57 @@ export class Model {
         }
         return this;
     }
+    updateTimestamps() {
+        const constructor = this.constructor;
+        if (!constructor.timestamps)
+            return;
+        const now = this.freshTimestamp();
+        this.$attributes["updated_at"] = now;
+        if (!this.$exists) {
+            this.$attributes["created_at"] = now;
+        }
+    }
+    async touch() {
+        if (!this.$exists)
+            return false;
+        const constructor = this.constructor;
+        if (!constructor.timestamps)
+            return false;
+        const now = this.freshTimestamp();
+        const pk = this.getAttribute(constructor.primaryKey);
+        await new Builder(constructor.getConnection(), constructor.getTable())
+            .where(constructor.primaryKey, pk)
+            .update({ updated_at: now });
+        this.$attributes["updated_at"] = now;
+        this.$original = { ...this.$attributes };
+        return true;
+    }
+    async increment(column, amount = 1, extra = {}) {
+        const constructor = this.constructor;
+        const pk = this.getAttribute(constructor.primaryKey);
+        if (!pk)
+            return this;
+        const builder = new Builder(constructor.getConnection(), constructor.getTable())
+            .where(constructor.primaryKey, pk);
+        if (constructor.timestamps) {
+            extra = { ...extra, updated_at: this.freshTimestamp() };
+        }
+        await builder.increment(column, amount, extra);
+        this.$attributes[column] = (this.$attributes[column] || 0) + amount;
+        for (const [key, value] of Object.entries(extra)) {
+            this.$attributes[key] = value;
+        }
+        this.$original = { ...this.$attributes };
+        return this;
+    }
+    async decrement(column, amount = 1, extra = {}) {
+        return this.increment(column, -amount, extra);
+    }
+    async load(...relations) {
+        const constructor = this.constructor;
+        await constructor.eagerLoadRelations([this], relations);
+        return this;
+    }
     async delete() {
         const constructor = this.constructor;
         await ObserverRegistry.dispatch("deleting", this);

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

@@ -0,0 +1,5 @@
+export declare class ModelNotFoundError extends Error {
+    modelName: string;
+    identifiers?: any;
+    constructor(modelName: string, identifiers?: any);
+}

package/dist/src/model/ModelNotFoundError.js

@@ -0,0 +1,13 @@
+export class ModelNotFoundError extends Error {
+    modelName;
+    identifiers;
+    constructor(modelName, identifiers) {
+        const msg = identifiers !== undefined
+            ? `No query results for model [${modelName}] ${JSON.stringify(identifiers)}`
+            : `No query results for model [${modelName}]`;
+        super(msg);
+        this.name = "ModelNotFoundError";
+        this.modelName = modelName;
+        this.identifiers = identifiers;
+    }
+}

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

@@ -25,23 +25,41 @@ export declare class Builder<T = Record<string, any>> {
     distinctFlag: boolean;
     model?: typeof Model;
     eagerLoads: string[];
+    randomOrderFlag: boolean;
+    lockMode?: string;
     constructor(connection: Connection, table: string);
     setModel(model: typeof Model): this;
     table(table: string): this;
     select(...columns: string[]): this;
     distinct(): this;
-    where(column: string | Record<string, any>, operator?: string | any, value?: any, boolean?: "and" | "or", scope?: string): this;
-    orWhere(column: string | Record<string, any>, operator?: string | any, value?: any): this;
+    where(column: string | Record<string, any> | ((query: Builder<T>) => void), operator?: string | any, value?: any, boolean?: "and" | "or", scope?: string): this;
+    private whereNested;
+    orWhere(column: string | Record<string, any> | ((query: Builder<T>) => void), operator?: string | any, value?: any): this;
+    whereNot(column: string | Record<string, any>, value?: any, boolean?: "and" | "or"): this;
+    orWhereNot(column: string | Record<string, any>, value?: any): this;
     whereIn(column: string, values: any[], boolean?: "and" | "or", scope?: string): this;
     whereNotIn(column: string, values: any[], boolean?: "and" | "or", scope?: string): this;
     whereNull(column: string, boolean?: "and" | "or", scope?: string): this;
     whereNotNull(column: string, boolean?: "and" | "or", scope?: string): this;
     whereBetween(column: string, values: [any, any], boolean?: "and" | "or", scope?: string): this;
     whereNotBetween(column: string, values: [any, any], boolean?: "and" | "or", scope?: string): this;
+    whereDate(column: string, operator?: string | any, value?: any, boolean?: "and" | "or"): this;
+    orWhereDate(column: string, operator?: string | any, value?: any): this;
+    whereDay(column: string, operator?: string | any, value?: any, boolean?: "and" | "or"): this;
+    orWhereDay(column: string, operator?: string | any, value?: any): this;
+    whereMonth(column: string, operator?: string | any, value?: any, boolean?: "and" | "or"): this;
+    orWhereMonth(column: string, operator?: string | any, value?: any): this;
+    whereYear(column: string, operator?: string | any, value?: any, boolean?: "and" | "or"): this;
+    orWhereYear(column: string, operator?: string | any, value?: any): this;
+    whereTime(column: string, operator?: string | any, value?: any, boolean?: "and" | "or"): this;
+    orWhereTime(column: string, operator?: string | any, value?: any): this;
     whereRaw(sql: string, boolean?: "and" | "or", scope?: string): this;
     whereColumn(first: string, operator: string, second: string, boolean?: "and" | "or"): this;
     whereExists(sql: string, boolean?: "and" | "or", not?: boolean): this;
     orderBy(column: string, direction?: "asc" | "desc"): this;
+    latest(column?: string): this;
+    oldest(column?: string): this;
+    inRandomOrder(): this;
     groupBy(...columns: string[]): this;
     having(column: string, operator: string, value: any): this;
     limit(count: number): this;
@@ -56,6 +74,9 @@ export declare class Builder<T = Record<string, any>> {
     withTrashed(): this;
     onlyTrashed(): this;
     scope(name: string, ...args: any[]): this;
+    when(condition: any, callback: (query: this) => void | this, defaultCallback?: (query: this) => void | this): this;
+    unless(condition: any, callback: (query: this) => void | this, defaultCallback?: (query: this) => void | this): this;
+    tap(callback: (query: this) => void | this): this;
     has(relationName: string, operator?: string | RelationConstraint, count?: number, callback?: RelationConstraint): this;
     orHas(relationName: string, operator?: string | RelationConstraint, count?: number, callback?: RelationConstraint): this;
     whereHas(relationName: string, callback?: RelationConstraint, operator?: string, count?: number): this;
@@ -74,7 +95,9 @@ export declare class Builder<T = Record<string, any>> {
     private wrap;
     private wrapValue;
     private escape;
+    private compileWhereClause;
     private compileWheres;
+    private compileNestedWheres;
     private compileOrders;
     private compileGroups;
     private compileHavings;
@@ -86,6 +109,10 @@ export declare class Builder<T = Record<string, any>> {
     get(): Promise<T[]>;
     first(): Promise<T | null>;
     find(id: any, column?: string): Promise<T | null>;
+    findOrFail(id: any, column?: string): Promise<T>;
+    firstOrFail(): Promise<T>;
+    firstOrCreate(attributes?: Partial<T>, values?: Partial<T>): Promise<T>;
+    updateOrCreate(attributes: Partial<T>, values?: Partial<T>): Promise<T>;
     pluck(column: string): Promise<any[]>;
     private aggregate;
     count(column?: string): Promise<number>;
@@ -94,12 +121,24 @@ export declare class Builder<T = Record<string, any>> {
     min(column: string): Promise<any>;
     max(column: string): Promise<any>;
     paginate(perPage?: number, page?: number): Promise<Paginator<T>>;
+    chunk(count: number, callback: (items: T[]) => void | Promise<void>): Promise<void>;
+    each(count: number, callback: (item: T) => void | Promise<void>): Promise<void>;
+    cursor(): AsyncGenerator<T>;
+    lazy(count?: number): AsyncGenerator<T>;
     insert(data: Partial<T> | Partial<T>[]): Promise<any>;
     insertGetId(data: Partial<T>, idColumn?: string): Promise<any>;
     update(data: Partial<T>): Promise<any>;
     delete(): Promise<any>;
+    increment(column: string, amount?: number, extra?: Record<string, any>): Promise<any>;
+    decrement(column: string, amount?: number, extra?: Record<string, any>): Promise<any>;
     restore(): Promise<any>;
     exists(): Promise<boolean>;
+    doesntExist(): Promise<boolean>;
+    take(count: number): this;
+    skip(count: number): this;
+    lockForUpdate(): this;
+    sharedLock(): this;
+    private addDateWhere;
     private getModelRelation;
     private withAggregate;
 }

package/dist/src/query/Builder.js

@@ -1,3 +1,4 @@
+import { ModelNotFoundError } from "../model/ModelNotFoundError.js";
 export class Builder {
     connection;
     tableName;
@@ -12,6 +13,8 @@ export class Builder {
     distinctFlag = false;
     model;
     eagerLoads = [];
+    randomOrderFlag = false;
+    lockMode;
     constructor(connection, table) {
         this.connection = connection;
         this.tableName = table;
@@ -33,6 +36,9 @@ export class Builder {
         return this;
     }
     where(column, operator, value, boolean = "and", scope) {
+        if (typeof column === "function") {
+            return this.whereNested(column, boolean);
+        }
         if (typeof column === "object" && column !== null) {
             for (const [key, val] of Object.entries(column)) {
                 this.where(key, "=", val, boolean, scope);
@@ -46,9 +52,30 @@ export class Builder {
         this.wheres.push({ type: "basic", column, operator, value, boolean, scope });
         return this;
     }
+    whereNested(callback, boolean = "and") {
+        const nested = new Builder(this.connection, this.tableName);
+        callback(nested);
+        if (nested.wheres.length > 0) {
+            const sql = this.compileNestedWheres(nested);
+            this.wheres.push({ type: "raw", column: `(${sql})`, boolean, scope: undefined });
+        }
+        return this;
+    }
     orWhere(column, operator, value) {
         return this.where(column, operator, value, "or");
     }
+    whereNot(column, value, boolean = "and") {
+        if (typeof column === "object" && column !== null) {
+            for (const [key, val] of Object.entries(column)) {
+                this.whereNot(key, val, boolean);
+            }
+            return this;
+        }
+        return this.where(column, "!=", value, boolean);
+    }
+    orWhereNot(column, value) {
+        return this.whereNot(column, value, "or");
+    }
     whereIn(column, values, boolean = "and", scope) {
         this.wheres.push({ type: "in", column, value: values, boolean, scope });
         return this;
@@ -73,6 +100,36 @@ export class Builder {
         this.wheres.push({ type: "between", column, value: values, boolean, operator: "NOT BETWEEN", scope });
         return this;
     }
+    whereDate(column, operator, value, boolean = "and") {
+        return this.addDateWhere("date", column, operator, value, boolean);
+    }
+    orWhereDate(column, operator, value) {
+        return this.whereDate(column, operator, value, "or");
+    }
+    whereDay(column, operator, value, boolean = "and") {
+        return this.addDateWhere("day", column, operator, value, boolean);
+    }
+    orWhereDay(column, operator, value) {
+        return this.whereDay(column, operator, value, "or");
+    }
+    whereMonth(column, operator, value, boolean = "and") {
+        return this.addDateWhere("month", column, operator, value, boolean);
+    }
+    orWhereMonth(column, operator, value) {
+        return this.whereMonth(column, operator, value, "or");
+    }
+    whereYear(column, operator, value, boolean = "and") {
+        return this.addDateWhere("year", column, operator, value, boolean);
+    }
+    orWhereYear(column, operator, value) {
+        return this.whereYear(column, operator, value, "or");
+    }
+    whereTime(column, operator, value, boolean = "and") {
+        return this.addDateWhere("time", column, operator, value, boolean);
+    }
+    orWhereTime(column, operator, value) {
+        return this.whereTime(column, operator, value, "or");
+    }
     whereRaw(sql, boolean = "and", scope) {
         this.wheres.push({ type: "raw", column: sql, boolean, scope });
         return this;
@@ -89,6 +146,16 @@ export class Builder {
         this.orders.push({ column, direction });
         return this;
     }
+    latest(column = "created_at") {
+        return this.orderBy(column, "desc");
+    }
+    oldest(column = "created_at") {
+        return this.orderBy(column, "asc");
+    }
+    inRandomOrder() {
+        this.randomOrderFlag = true;
+        return this;
+    }
     groupBy(...columns) {
         this.groups.push(...columns);
         return this;
@@ -154,6 +221,24 @@ export class Builder {
         const result = scope.call(this.model, this, ...args);
         return (result || this);
     }
+    when(condition, callback, defaultCallback) {
+        if (condition) {
+            const result = callback(this);
+            return (result || this);
+        }
+        else if (defaultCallback) {
+            const result = defaultCallback(this);
+            return (result || this);
+        }
+        return this;
+    }
+    unless(condition, callback, defaultCallback) {
+        return this.when(!condition, callback, defaultCallback);
+    }
+    tap(callback) {
+        const result = callback(this);
+        return (result || this);
+    }
     has(relationName, operator = ">=", count = 1, callback) {
         if (typeof operator === "function") {
             callback = operator;
@@ -233,6 +318,8 @@ export class Builder {
         cloned.distinctFlag = this.distinctFlag;
         cloned.model = this.model;
         cloned.eagerLoads = [...this.eagerLoads];
+        cloned.randomOrderFlag = this.randomOrderFlag;
+        cloned.lockMode = this.lockMode;
         return cloned;
     }
     wrapColumn(value) {
@@ -269,40 +356,57 @@ export class Builder {
             return value;
         return `'${String(value).replace(/'/g, "''")}'`;
     }
+    compileWhereClause(where, prefix) {
+        if (where.type === "basic") {
+            return `${prefix} ${this.wrap(where.column)} ${where.operator} ${this.escape(where.value)}`;
+        }
+        else if (where.type === "in") {
+            const op = where.operator === "NOT IN" ? "NOT IN" : "IN";
+            return `${prefix} ${this.wrap(where.column)} ${op} (${where.value.map((v) => this.escape(v)).join(", ")})`;
+        }
+        else if (where.type === "null") {
+            const op = where.operator === "NOT NULL" ? "IS NOT NULL" : "IS NULL";
+            return `${prefix} ${this.wrap(where.column)} ${op}`;
+        }
+        else if (where.type === "between") {
+            const op = where.operator === "NOT BETWEEN" ? "NOT BETWEEN" : "BETWEEN";
+            return `${prefix} ${this.wrap(where.column)} ${op} ${this.escape(where.value[0])} AND ${this.escape(where.value[1])}`;
+        }
+        else if (where.type === "raw") {
+            return `${prefix} ${where.column}`;
+        }
+        else if (where.type === "column") {
+            return `${prefix} ${this.wrap(where.column)} ${where.operator} ${this.wrap(where.value)}`;
+        }
+        else if (where.type === "exists") {
+            return `${prefix} ${where.operator} (${where.column})`;
+        }
+        return "";
+    }
     compileWheres() {
         if (this.wheres.length === 0)
             return "";
         const clauses = this.wheres.map((where, index) => {
             const prefix = index === 0 ? "WHERE" : where.boolean.toUpperCase();
-            if (where.type === "basic") {
-                return `${prefix} ${this.wrap(where.column)} ${where.operator} ${this.escape(where.value)}`;
-            }
-            else if (where.type === "in") {
-                const op = where.operator === "NOT IN" ? "NOT IN" : "IN";
-                return `${prefix} ${this.wrap(where.column)} ${op} (${where.value.map((v) => this.escape(v)).join(", ")})`;
-            }
-            else if (where.type === "null") {
-                const op = where.operator === "NOT NULL" ? "IS NOT NULL" : "IS NULL";
-                return `${prefix} ${this.wrap(where.column)} ${op}`;
-            }
-            else if (where.type === "between") {
-                const op = where.operator === "NOT BETWEEN" ? "NOT BETWEEN" : "BETWEEN";
-                return `${prefix} ${this.wrap(where.column)} ${op} ${this.escape(where.value[0])} AND ${this.escape(where.value[1])}`;
-            }
-            else if (where.type === "raw") {
-                return `${prefix} ${where.column}`;
-            }
-            else if (where.type === "column") {
-                return `${prefix} ${this.wrap(where.column)} ${where.operator} ${this.wrap(where.value)}`;
-            }
-            else if (where.type === "exists") {
-                return `${prefix} ${where.operator} (${where.column})`;
-            }
-            return "";
+            return this.compileWhereClause(where, prefix);
         });
         return clauses.join(" ");
     }
+    compileNestedWheres(builder) {
+        if (builder.wheres.length === 0)
+            return "";
+        const clauses = builder.wheres.map((where, index) => {
+            const prefix = index === 0 ? "" : where.boolean.toUpperCase();
+            return this.compileWhereClause(where, prefix);
+        });
+        return clauses.join(" ").trim();
+    }
     compileOrders() {
+        if (this.randomOrderFlag) {
+            const driver = this.connection.getDriverName();
+            const fn = driver === "mysql" ? "RAND()" : "RANDOM()";
+            return `ORDER BY ${fn}`;
+        }
         if (this.orders.length === 0)
             return "";
         return `ORDER BY ${this.orders.map((o) => `${this.wrap(o.column)} ${o.direction.toUpperCase()}`).join(", ")}`;
@@ -325,7 +429,10 @@ export class Builder {
     compileOffset() {
         if (this.offsetValue === undefined)
             return "";
-        return `OFFSET ${this.offsetValue}`;
+        const limitSql = this.limitValue === undefined && this.connection.getDriverName() === "sqlite"
+            ? "LIMIT -1 "
+            : "";
+        return `${limitSql}OFFSET ${this.offsetValue}`;
     }
     compileColumns() {
         return this.columns.map((c) => (this.isRawColumn(c) ? c : this.wrap(c))).join(", ");
@@ -344,6 +451,8 @@ export class Builder {
         sql += " " + this.compileOrders();
         sql += " " + this.compileLimit();
         sql += " " + this.compileOffset();
+        if (this.lockMode)
+            sql += " " + this.lockMode;
         return sql.replace(/\s+/g, " ").trim();
     }
     async get() {
@@ -370,6 +479,44 @@ export class Builder {
     async find(id, column = "id") {
         return this.where(column, id).first();
     }
+    async findOrFail(id, column = "id") {
+        const result = await this.find(id, column);
+        if (!result) {
+            throw new ModelNotFoundError(this.model?.name || "Model", id);
+        }
+        return result;
+    }
+    async firstOrFail() {
+        const result = await this.first();
+        if (!result) {
+            throw new ModelNotFoundError(this.model?.name || "Model");
+        }
+        return result;
+    }
+    async firstOrCreate(attributes = {}, values = {}) {
+        const found = await this.clone().where(attributes).first();
+        if (found)
+            return found;
+        if (!this.model) {
+            throw new Error("firstOrCreate requires a model to be set on the builder");
+        }
+        return this.model.create({ ...attributes, ...values });
+    }
+    async updateOrCreate(attributes, values = {}) {
+        const found = await this.clone().where(attributes).first();
+        if (found) {
+            const model = found;
+            if (typeof model.fill === "function") {
+                model.fill(values);
+                await model.save();
+            }
+            return found;
+        }
+        if (!this.model) {
+            throw new Error("updateOrCreate requires a model to be set on the builder");
+        }
+        return this.model.create({ ...attributes, ...values });
+    }
     async pluck(column) {
         const results = await this.select(column).get();
         return results.map((row) => row[column]);
@@ -409,6 +556,49 @@ export class Builder {
             to: total === 0 ? 0 : Math.min(page * perPage, total),
         };
     }
+    async chunk(count, callback) {
+        let page = 1;
+        while (true) {
+            const items = await this.clone().forPage(page, count).get();
+            if (items.length === 0)
+                break;
+            await callback(items);
+            if (items.length < count)
+                break;
+            page++;
+        }
+    }
+    async each(count, callback) {
+        await this.chunk(count, async (items) => {
+            for (const item of items) {
+                await callback(item);
+            }
+        });
+    }
+    async *cursor() {
+        let offset = 0;
+        while (true) {
+            const items = await this.clone().offset(offset).limit(1).get();
+            if (items.length === 0)
+                break;
+            yield items[0];
+            offset++;
+        }
+    }
+    async *lazy(count = 1000) {
+        let page = 1;
+        while (true) {
+            const items = await this.clone().forPage(page, count).get();
+            if (items.length === 0)
+                break;
+            for (const item of items) {
+                yield item;
+            }
+            if (items.length < count)
+                break;
+            page++;
+        }
+    }
     async insert(data) {
         const records = Array.isArray(data) ? data : [data];
         if (records.length === 0)
@@ -435,6 +625,17 @@ export class Builder {
         const sql = `DELETE FROM ${this.wrap(this.tableName)} ${this.compileWheres()}`;
         return await this.connection.run(sql.trim());
     }
+    async increment(column, amount = 1, extra = {}) {
+        const sets = [`${this.wrap(column)} = ${this.wrap(column)} + ${amount}`];
+        for (const [key, value] of Object.entries(extra)) {
+            sets.push(`${this.wrap(key)} = ${this.escape(value)}`);
+        }
+        const sql = `UPDATE ${this.wrap(this.tableName)} SET ${sets.join(", ")} ${this.compileWheres()}`;
+        return await this.connection.run(sql.trim());
+    }
+    async decrement(column, amount = 1, extra = {}) {
+        return this.increment(column, -amount, extra);
+    }
     async restore() {
         const model = this.model;
         if (!model?.softDeletes) {
@@ -446,6 +647,87 @@ export class Builder {
         const result = await this.select("1 as exists_check").limit(1).get();
         return result.length > 0;
     }
+    async doesntExist() {
+        return !(await this.exists());
+    }
+    take(count) {
+        return this.limit(count);
+    }
+    skip(count) {
+        return this.offset(count);
+    }
+    lockForUpdate() {
+        const driver = this.connection.getDriverName();
+        if (driver !== "sqlite") {
+            this.lockMode = driver === "mysql" ? "FOR UPDATE" : "FOR UPDATE";
+        }
+        return this;
+    }
+    sharedLock() {
+        const driver = this.connection.getDriverName();
+        if (driver === "mysql") {
+            this.lockMode = "LOCK IN SHARE MODE";
+        }
+        else if (driver === "postgres") {
+            this.lockMode = "FOR SHARE";
+        }
+        return this;
+    }
+    addDateWhere(type, column, operator, value, boolean = "and") {
+        if (value === undefined) {
+            value = operator;
+            operator = "=";
+        }
+        const driver = this.connection.getDriverName();
+        const wrapped = this.wrap(column);
+        let sql;
+        switch (type) {
+            case "date":
+                if (driver === "sqlite")
+                    sql = `date(${wrapped}) ${operator} ${this.escape(value)}`;
+                else if (driver === "mysql")
+                    sql = `DATE(${wrapped}) ${operator} ${this.escape(value)}`;
+                else
+                    sql = `(${wrapped})::date ${operator} ${this.escape(value)}`;
+                break;
+            case "day":
+                if (driver === "sqlite")
+                    sql = `CAST(strftime('%d', ${wrapped}) AS INTEGER) ${operator} ${this.escape(value)}`;
+                else if (driver === "mysql")
+                    sql = `DAY(${wrapped}) ${operator} ${this.escape(value)}`;
+                else
+                    sql = `EXTRACT(DAY FROM ${wrapped}) ${operator} ${this.escape(value)}`;
+                break;
+            case "month":
+                if (driver === "sqlite")
+                    sql = `CAST(strftime('%m', ${wrapped}) AS INTEGER) ${operator} ${this.escape(value)}`;
+                else if (driver === "mysql")
+                    sql = `MONTH(${wrapped}) ${operator} ${this.escape(value)}`;
+                else
+                    sql = `EXTRACT(MONTH FROM ${wrapped}) ${operator} ${this.escape(value)}`;
+                break;
+            case "year":
+                if (driver === "sqlite")
+                    sql = `CAST(strftime('%Y', ${wrapped}) AS INTEGER) ${operator} ${this.escape(value)}`;
+                else if (driver === "mysql")
+                    sql = `YEAR(${wrapped}) ${operator} ${this.escape(value)}`;
+                else
+                    sql = `EXTRACT(YEAR FROM ${wrapped}) ${operator} ${this.escape(value)}`;
+                break;
+            case "time":
+                if (driver === "sqlite")
+                    sql = `time(${wrapped}) ${operator} ${this.escape(value)}`;
+                else if (driver === "mysql")
+                    sql = `TIME(${wrapped}) ${operator} ${this.escape(value)}`;
+                else
+                    sql = `(${wrapped})::time ${operator} ${this.escape(value)}`;
+                break;
+            default:
+                sql = `${wrapped} ${operator} ${this.escape(value)}`;
+        }
+        this.wheres.push({ type: "raw", column: sql, boolean, scope: undefined });
+        return this;
+    }
     getModelRelation(relationName) {
         if (!this.model) {
             throw new Error(`Cannot query relation "${relationName}" without a model`);

package/package.json

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