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

package/README.md

@@ -51,6 +51,28 @@ await User.query().count();
 
 Relations load lazily (`await user.posts().get()`) or eagerly (`User.with("posts")`).
 
+## Large tables
+
+```ts
+for await (const user of User.where("active", true).cursor()) {
+  // hydrated one model at a time from a single streamed query
+}
+
+for await (const user of User.cursor()) {} // whole table
+```
+
+`User.cursor()`, `User.lazy()`, `User.lazyById()` and `User.lazyByIdDesc()` are also available as statics. They return a `LazyCollection`, so you can chain without loading the table:
+
+```ts
+const emails = await User.cursor()
+  .filter((user) => user.active)
+  .map((user) => user.email)
+  .take(100)
+  .toArray();
+```
+
+`cursor()` keeps memory flat and fires `retrieved` events. `with()` relations are loaded per batch of `chunkSize` models (default 1000), not per row. Use `lazyById()` when the loop updates the rows it reads. See `@bunyad/database` for per-driver behavior.
+
 ## Drivers
 
 Pick one and install it next to `@bunyad/database`: `better-sqlite3`, `pg` or `mysql2`. Bun uses its built-in drivers.

package/dist/model-query.d.ts

@@ -3,7 +3,7 @@
  */
 import type { DateInput, QueryBuilder } from "@bunyad/database";
 import { CursorPaginator, LengthAwarePaginator, Paginator } from "@bunyad/database";
-import { Collection } from "@bunyad/common";
+import { Collection, LazyCollection } from "@bunyad/common";
 import { OrmCollection } from "./orm-collection.js";
 import { type CastDefinition } from "./casts.js";
 import { Model, type ModelClass, type ModelQueryOptions } from "./model.js";
@@ -259,14 +259,20 @@ export declare class ModelQuery<T extends Model = Model, TResult extends "model"
     }): Promise<Paginator<T>>;
     /** `chunk($count, $callback)`. */
     chunk(count: number, callback: (models: OrmCollection<T>) => void | Promise<void>): Promise<void>;
+    /**
+     * `cursor($chunkSize)` — hydrate models one at a time from a single streamed
+     * query, so memory stays flat on large tables. `with()` relations are loaded
+     * per batch of `chunkSize` models rather than per row.
+     */
+    cursor(chunkSize?: number): LazyCollection<T>;
     /** `lazy($chunkSize)`. */
-    lazy(chunkSize?: number): AsyncGenerator<T, void, unknown>;
+    lazy(chunkSize?: number): LazyCollection<T>;
     /** `chunkById`. */
     chunkById(count: number, callback: (models: OrmCollection<T>) => void | boolean | Promise<void | boolean>, column?: string): Promise<boolean>;
     chunkByIdDesc(count: number, callback: (models: OrmCollection<T>) => void | boolean | Promise<void | boolean>, column?: string): Promise<boolean>;
     /** `lazyById`. */
-    lazyById(chunkSize?: number, column?: string): AsyncGenerator<T, void, unknown>;
-    lazyByIdDesc(chunkSize?: number, column?: string): AsyncGenerator<T, void, unknown>;
+    lazyById(chunkSize?: number, column?: string): LazyCollection<T>;
+    lazyByIdDesc(chunkSize?: number, column?: string): LazyCollection<T>;
     increment(column: string, amount?: number): Promise<void>;
     decrement(column: string, amount?: number): Promise<void>;
     /** `cursorPaginate`. */

package/dist/model-query.js

@@ -1,5 +1,5 @@
 import { DatabaseManager as Db, CursorPaginator, LengthAwarePaginator, Paginator, dateTimeForStorage, hasQueryListeners, resolvePaginatorPage, wrapSqlName, } from "@bunyad/database";
-import { Collection } from "@bunyad/common";
+import { Collection, LazyCollection } from "@bunyad/common";
 import { OrmCollection } from "./orm-collection.js";
 import { bootIfNotBooted, fireModelEvent, hasModelEventListeners, } from "./model-events.js";
 import { getGlobalScopes, hasGlobalScopes, } from "./scopes.js";
@@ -2922,8 +2922,45 @@ export class ModelQuery {
             page += 1;
         }
     }
+    /**
+     * `cursor($chunkSize)` — hydrate models one at a time from a single streamed
+     * query, so memory stays flat on large tables. `with()` relations are loaded
+     * per batch of `chunkSize` models rather than per row.
+     */
+    cursor(chunkSize = 1000) {
+        return new LazyCollection(() => this.#cursorModels(chunkSize));
+    }
+    async *#cursorModels(chunkSize) {
+        const size = Math.max(1, Math.floor(chunkSize));
+        const fireRetrieved = hasModelEventListeners(this.model, "retrieved");
+        const eager = this.#eagerLoad.length > 0;
+        let batch = [];
+        for await (const row of this.#buildQuery().cursor(size)) {
+            const model = this.#makeModel(row);
+            if (fireRetrieved) {
+                await fireModelEvent(model, "retrieved");
+            }
+            if (!eager) {
+                yield model;
+                continue;
+            }
+            batch.push(model);
+            if (batch.length >= size) {
+                await this.#loadEager(batch);
+                yield* batch;
+                batch = [];
+            }
+        }
+        if (batch.length > 0) {
+            await this.#loadEager(batch);
+            yield* batch;
+        }
+    }
     /** `lazy($chunkSize)`. */
-    async *lazy(chunkSize = 1000) {
+    lazy(chunkSize = 1000) {
+        return new LazyCollection(() => this.#lazyPages(chunkSize));
+    }
+    async *#lazyPages(chunkSize) {
         let page = 1;
         const fireRetrieved = hasModelEventListeners(this.model, "retrieved");
         for (;;) {
@@ -2976,11 +3013,11 @@ export class ModelQuery {
         }
     }
     /** `lazyById`. */
-    async *lazyById(chunkSize = 1000, column) {
-        yield* this.#lazyById(chunkSize, column ?? this.model.primaryKey, "asc");
+    lazyById(chunkSize = 1000, column) {
+        return new LazyCollection(() => this.#lazyById(chunkSize, column ?? this.model.primaryKey, "asc"));
     }
-    async *lazyByIdDesc(chunkSize = 1000, column) {
-        yield* this.#lazyById(chunkSize, column ?? this.model.primaryKey, "desc");
+    lazyByIdDesc(chunkSize = 1000, column) {
+        return new LazyCollection(() => this.#lazyById(chunkSize, column ?? this.model.primaryKey, "desc"));
     }
     async *#lazyById(chunkSize, column, direction) {
         const size = Math.max(1, Math.floor(chunkSize));

package/dist/model.d.ts

@@ -1,6 +1,6 @@
 import type { Connection, DatabaseManager, DateInput } from "@bunyad/database";
 import { LengthAwarePaginator, CursorPaginator } from "@bunyad/database";
-import { Collection } from "@bunyad/common";
+import { Collection, LazyCollection } from "@bunyad/common";
 import { OrmCollection } from "./orm-collection.js";
 import { type CastDefinition } from "./casts.js";
 import { type ModelEventListener, type ModelEventName, type ModelObserver } from "./model-events.js";
@@ -353,6 +353,14 @@ export declare class Model {
         path?: string;
         cursorName?: string;
     }): Promise<CursorPaginator<InstanceType<T>>>;
+    /** `Model::cursor()`: stream models from a single query. */
+    static cursor<T extends typeof Model>(this: T, chunkSize?: number): LazyCollection<InstanceType<T>>;
+    /** `Model::lazy()`: chunked iteration, one query per chunk. */
+    static lazy<T extends typeof Model>(this: T, chunkSize?: number): LazyCollection<InstanceType<T>>;
+    /** `Model::lazyById()`: chunked iteration by primary key (safe while updating). */
+    static lazyById<T extends typeof Model>(this: T, chunkSize?: number, column?: string): LazyCollection<InstanceType<T>>;
+    /** `Model::lazyByIdDesc()`. */
+    static lazyByIdDesc<T extends typeof Model>(this: T, chunkSize?: number, column?: string): LazyCollection<InstanceType<T>>;
     /** `Model::create` (respects `$fillable` / `$guarded`). */
     static create<T extends typeof Model>(this: T, attributes: Record<string, unknown>): InstanceType<T> | Promise<InstanceType<T>>;
     /** `Model::forceCreate` — insert every given attribute, ignoring `$fillable`. */

package/dist/model.js

@@ -1,5 +1,5 @@
 import { DatabaseManager as Db, setDefaultConnection, connections, LengthAwarePaginator, CursorPaginator, Paginator, dateTimeForStorage, withoutQueryWriteHook, wrapSqlName, } from "@bunyad/database";
-import { Collection } from "@bunyad/common";
+import { Collection, LazyCollection } from "@bunyad/common";
 import { OrmCollection } from "./orm-collection.js";
 import { Attribute, castFromStorage, castToStorage, hashCastValue, isAlreadyHashed, enumFromStorage, enumToStorage, isAttribute, isCastType, isEnumCast, } from "./casts.js";
 import { bootIfNotBooted, fireModelEvent, hasAnyModelEventListeners, hasModelEventListeners, observeModel, registerModelEvent, withoutModelEvents, } from "./model-events.js";
@@ -1138,6 +1138,22 @@ export class Model {
     static async cursorPaginate(perPage = 15, cursor = null, options = {}) {
         return this.newQuery().cursorPaginate(perPage, cursor, options);
     }
+    /** `Model::cursor()`: stream models from a single query. */
+    static cursor(chunkSize) {
+        return this.newQuery().cursor(chunkSize);
+    }
+    /** `Model::lazy()`: chunked iteration, one query per chunk. */
+    static lazy(chunkSize) {
+        return this.newQuery().lazy(chunkSize);
+    }
+    /** `Model::lazyById()`: chunked iteration by primary key (safe while updating). */
+    static lazyById(chunkSize, column) {
+        return this.newQuery().lazyById(chunkSize, column);
+    }
+    /** `Model::lazyByIdDesc()`. */
+    static lazyByIdDesc(chunkSize, column) {
+        return this.newQuery().lazyByIdDesc(chunkSize, column);
+    }
     /** `Model::create` (respects `$fillable` / `$guarded`). */
     static create(attributes) {
         this.bootIfNotBooted();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bunyad/orm",
-  "version": "0.2.0-beta.0",
+  "version": "0.2.0-beta.1",
   "description": "Active-record ORM for Bunyad: models, relations, casts, scopes, events, factories.",
   "license": "MIT",
   "author": "Shah Khalid",
@@ -36,8 +36,8 @@
     }
   },
   "dependencies": {
-    "@bunyad/common": "^0.2.0-beta.0",
-    "@bunyad/database": "^0.2.0-beta.0"
+    "@bunyad/common": "^0.2.0-beta.1",
+    "@bunyad/database": "^0.2.0-beta.1"
   },
   "publishConfig": {
     "access": "public"