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

package/README.md

@@ -2,10 +2,10 @@
 
 Active-record models on top of [`@bunyad/database`](https://www.npmjs.com/package/@bunyad/database): relations, casts, scopes, events, soft deletes and factories. The same model code runs on Node and Bun.
 
-> **Alpha.** APIs may change between `0.x` releases.
+> **Beta.** Public APIs change only in minor releases, with a changelog entry and migration note. See the [stability policy](https://github.com/bunyadjs/framework/blob/main/docs/STABILITY.md).
 
 ```bash
-npm install @bunyad/orm@alpha @bunyad/database@alpha better-sqlite3
+npm install @bunyad/orm@beta @bunyad/database@beta better-sqlite3
 ```
 
 ## Quick start
@@ -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.
@@ -63,7 +85,7 @@ Pick one and install it next to `@bunyad/database`: `better-sqlite3`, `pg` or `m
 
 ## Status
 
-Alpha. SQLite is the most tested driver; PostgreSQL and MySQL tests need a live database and are skipped by default. Aggregate helpers such as `sumCase`/`countCase` are not implemented yet.
+Beta scope: SQLite, PostgreSQL and MySQL are tested on Bun and Node 20+ (the PostgreSQL and MySQL suites run when `BUNYAD_TEST_POSTGRES_URL` / `BUNYAD_TEST_MYSQL_URL` are set). SQL Server is experimental and needs `mssql` installed. Conditional aggregate helpers (`sumCase`, `countCase`) are not available yet.
 
 ## License
 

package/dist/concerns.d.ts

@@ -18,8 +18,8 @@ export declare function HasUuids(): ClassDecorator;
  * ULID primary keys (`incrementing = false`).
  */
 export declare function HasUlids(): ClassDecorator;
-type FactoryClass = new () => Factory;
-type FactoryResolver = FactoryClass | (() => Factory);
+type FactoryClass = new () => Factory<any>;
+type FactoryResolver = FactoryClass | (() => Factory<any>);
 /**
  * Bind a factory class and expose `Model.factory()`.
  *

package/dist/factory.d.ts

@@ -49,15 +49,15 @@ export declare abstract class Factory<T extends Model = Model> {
     /**
      * Create related models after the parent (`has(PostFactory.new().count(3))`).
      */
-    has(factory: Factory, relationship?: string): this;
+    has(factory: Factory<any>, relationship?: string): this;
     /**
      * Associate a parent model / factory (`for(TeamFactory.new())`).
      */
-    for(parent: Model | Factory, relationship?: string): this;
+    for(parent: Model | Factory<any>, relationship?: string): this;
     /**
      * Attach related models on a belongs-to-many after create.
      */
-    hasAttached(related: Factory | Model | Model[], pivot?: FactoryAttributes, relationship?: string): this;
+    hasAttached(related: Factory<any> | Model | Model[], pivot?: FactoryAttributes, relationship?: string): this;
     /** `Factory::new()`. */
     static new<T extends Factory>(this: new () => T): T;
     /** Build an in-memory model instance (not persisted). */

package/dist/model-events.d.ts

@@ -1,5 +1,5 @@
 import type { Model } from "./model.js";
-/** Eloquent model lifecycle event names. */
+/** Model lifecycle event names. */
 export type ModelEventName = "retrieved" | "creating" | "created" | "updating" | "updated" | "saving" | "saved" | "deleting" | "deleted" | "trashed" | "forceDeleting" | "forceDeleted" | "restoring" | "restored" | "replicating";
 export declare const MODEL_EVENT_NAMES: readonly ModelEventName[];
 /**
@@ -36,7 +36,7 @@ export declare function hasModelEventListeners(ctor: ModelCtor, event: ModelEven
 export declare function hasAnyModelEventListeners(ctor: ModelCtor): boolean;
 /** Run `callback` with model events disabled for `ctor`. */
 export declare function withoutModelEvents<T>(ctor: ModelCtor, callback: () => T | Promise<T>): T | Promise<T>;
-/** Register an observer instance or class (Laravel `Model::observe`). */
+/** Register an observer instance or class (`Model::observe`). */
 export declare function observeModel<T extends Model>(ctor: abstract new (...args: never[]) => T, observer: ModelObserver<T> | (new () => ModelObserver<T>) | Array<ModelObserver<T> | (new () => ModelObserver<T>)>): void;
 /** Test helper — clear boot state and listeners for a model class. */
 export declare function resetModelEventsForTests(ctor: ModelCtor): void;

package/dist/model-events.js

@@ -115,7 +115,7 @@ export function withoutModelEvents(ctor, callback) {
         throw error;
     }
 }
-/** Register an observer instance or class (Laravel `Model::observe`). */
+/** Register an observer instance or class (`Model::observe`). */
 export function observeModel(ctor, observer) {
     const list = Array.isArray(observer) ? observer : [observer];
     for (const item of list) {

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";
@@ -20,68 +20,68 @@ export declare class ModelQuery<T extends Model = Model, TResult extends "model"
     constructor(model: ModelClass, options?: ModelQueryOptions);
     /** `get()` returns plain row objects. Models are not built. */
     rows(): ModelQuery<T, "row">;
-    /** Laravel `withoutGlobalScopes`. */
+    /** `withoutGlobalScopes`. */
     withoutGlobalScopes(names?: string[]): this;
-    /** Laravel `withoutGlobalScope`. */
+    /** `withoutGlobalScope`. */
     withoutGlobalScope(name: string): this;
-    /** Laravel `withTrashed()`. */
+    /** `withTrashed()`. */
     withTrashed(): this;
-    /** Laravel `onlyTrashed()`. */
+    /** `onlyTrashed()`. */
     onlyTrashed(): this;
-    /** Laravel `withoutTrashed()`. */
+    /** `withoutTrashed()`. */
     withoutTrashed(): this;
     /**
-     * Laravel `Builder::withAttributes` — pending attrs for `create()`, and
+     * `Builder::withAttributes` — pending attrs for `create()`, and
      * matching `where` conditions when `asConditions` is true (default).
      */
     withAttributes(attributes: Record<string, unknown> | string, valueOrAsConditions?: unknown, asConditions?: boolean): this;
-    /** Laravel `withCasts` — merge query-time casts for hydration. */
+    /** `withCasts` — merge query-time casts for hydration. */
     withCasts(casts: Record<string, CastDefinition>): this;
-    /** Laravel `has`. */
+    /** `has`. */
     has(relation: string): this;
-    /** Laravel `doesntHave`. */
+    /** `doesntHave`. */
     doesntHave(relation: string): this;
-    /** Laravel `whereHas`. */
+    /** `whereHas`. */
     whereHas(relation: string, callback?: (query: ModelQuery) => void): this;
-    /** Laravel `orWhereHas`. */
+    /** `orWhereHas`. */
     orWhereHas(relation: string, callback?: (query: ModelQuery) => void): this;
-    /** Laravel `whereDoesntHave`. */
+    /** `whereDoesntHave`. */
     whereDoesntHave(relation: string, callback?: (query: ModelQuery) => void): this;
-    /** Laravel `orWhereDoesntHave`. */
+    /** `orWhereDoesntHave`. */
     orWhereDoesntHave(relation: string, callback?: (query: ModelQuery) => void): this;
     /**
-     * Laravel `whereRelation($relation, $column, $operator = null, $value = null)`.
+     * `whereRelation($relation, $column, $operator = null, $value = null)`.
      * Convenience wrapper around `whereHas` with a column constraint.
      */
     whereRelation(relation: string, column: string, opOrValue: unknown, value?: unknown): this;
-    /** Laravel `orWhereRelation`. */
+    /** `orWhereRelation`. */
     orWhereRelation(relation: string, column: string, opOrValue: unknown, value?: unknown): this;
-    /** Laravel `orHas`. */
+    /** `orHas`. */
     orHas(relation: string): this;
-    /** Laravel `orDoesntHave`. */
+    /** `orDoesntHave`. */
     orDoesntHave(relation: string): this;
     /**
-     * Laravel `whereBelongsTo($model, $relationshipName = null)`.
+     * `whereBelongsTo($model, $relationshipName = null)`.
      * Constrains by the foreign key of a belongsTo relation.
      */
     whereBelongsTo(related: Model, relationName?: string): this;
-    /** Laravel `orWhereBelongsTo`. */
+    /** `orWhereBelongsTo`. */
     orWhereBelongsTo(related: Model, relationName?: string): this;
     /**
-     * Laravel `whereMorphedTo($relation, $model)`.
+     * `whereMorphedTo($relation, $model)`.
      */
     whereMorphedTo(relation: string, model: Model): this;
     orWhereMorphedTo(relation: string, model: Model): this;
     whereNotMorphedTo(relation: string, model: Model): this;
     orWhereNotMorphedTo(relation: string, model: Model): this;
     /**
-     * Laravel `whereMorphRelation($relation, $types, $column, …)` — simplified:
+     * `whereMorphRelation($relation, $types, $column, …)` — simplified:
      * `whereMorphRelation('commentable', TypeModel, column, op?, value?)`.
      */
     whereMorphRelation(relation: string, type: ModelClass, column: string, opOrValue: unknown, value?: unknown): this;
     orWhereMorphRelation(relation: string, type: ModelClass, column: string, opOrValue: unknown, value?: unknown): this;
     /**
-     * Laravel `whereHasMorph($relation, $types, $callback?)`.
+     * `whereHasMorph($relation, $types, $callback?)`.
      * `$types` may be a single model class or an array.
      */
     whereHasMorph(relation: string, types: ModelClass | ModelClass[], callback?: (query: ModelQuery) => void): this;
@@ -91,60 +91,60 @@ export declare class ModelQuery<T extends Model = Model, TResult extends "model"
     hasMorph(relation: string, types: ModelClass | ModelClass[]): this;
     doesntHaveMorph(relation: string, types: ModelClass | ModelClass[]): this;
     /**
-     * Laravel `withWhereHas($relation, $callback?)` — whereHas + eager with same constraint.
+     * `withWhereHas($relation, $callback?)` — whereHas + eager with same constraint.
      */
     withWhereHas(relation: string, callback?: (query: ModelQuery) => void): this;
-    /** Laravel `whereAny` (forwarded to query builder). */
+    /** `whereAny` (forwarded to query builder). */
     whereAny(columns: string[], opOrValue: unknown, value?: unknown): this;
     orWhereAny(columns: string[], opOrValue: unknown, value?: unknown): this;
     whereAll(columns: string[], opOrValue: unknown, value?: unknown): this;
     orWhereAll(columns: string[], opOrValue: unknown, value?: unknown): this;
     whereNone(columns: string[], opOrValue: unknown, value?: unknown): this;
     orWhereNone(columns: string[], opOrValue: unknown, value?: unknown): this;
-    /** Laravel `whereKey($id)` / `whereKey([$ids])`. */
+    /** `whereKey($id)` / `whereKey([$ids])`. */
     whereKey(id: string | number | Array<string | number>): this;
-    /** Laravel `whereKeyNot`. */
+    /** `whereKeyNot`. */
     whereKeyNot(id: string | number | Array<string | number>): this;
-    /** Laravel `whereUuid($column, $uuid)`. */
+    /** `whereUuid($column, $uuid)`. */
     whereUuid(column: string, value: string): this;
-    /** Laravel `whereUlid($column, $ulid)`. */
+    /** `whereUlid($column, $ulid)`. */
     whereUlid(column: string, value: string): this;
-    /** Laravel `whereNot(closure)` nested group. */
+    /** `whereNot(closure)` nested group. */
     whereNot(callback: (query: ModelQuery<T>) => void): this;
     orWhereNot(callback: (query: ModelQuery<T>) => void): this;
-    /** Laravel `firstWhere`. */
+    /** `firstWhere`. */
     firstWhere(column: string, value: unknown): T | null | Promise<T | null>;
     firstWhere(column: string, op: string, value: unknown): T | null | Promise<T | null>;
-    /** Laravel `findMany`. */
+    /** `findMany`. */
     findMany(ids: Array<string | number>): OrmCollection<T> | Promise<OrmCollection<T>>;
-    /** Laravel `findOr($id, $callback)`. */
+    /** `findOr($id, $callback)`. */
     findOr(id: string | number, callback: () => T | Promise<T>): Promise<T>;
-    /** Laravel `findOrNew`. */
+    /** `findOrNew`. */
     findOrNew(id: string | number): Promise<T>;
-    /** Laravel `firstOr($callback)`. */
+    /** `firstOr($callback)`. */
     firstOr(callback: () => T | Promise<T>): Promise<T>;
-    /** Laravel `valueOrFail`. */
+    /** `valueOrFail`. */
     valueOrFail(column: string): Promise<unknown>;
-    /** Laravel `soleValue`. */
+    /** `soleValue`. */
     soleValue(column: string): Promise<unknown>;
     /** `withCount` — `'posts'`, `'posts as post_total'`, a string list, or `{ products: { as: 'productsCount' } }`. */
     withCount(...relations: Array<string | string[] | Record<string, true | string | ((query: ModelQuery) => void) | {
         as?: string;
     }>>): this;
-    /** Laravel `withSum($relation, $column)`. */
+    /** `withSum($relation, $column)`. */
     withSum(relation: string, column: string): this;
     withAvg(relation: string, column: string): this;
     withMin(relation: string, column: string): this;
     withMax(relation: string, column: string): this;
-    /** Laravel `withExists($relation)`. */
+    /** `withExists($relation)`. */
     withExists(...relations: string[]): this;
-    /** Laravel `withAggregate($relation, $column, $function)`. */
+    /** `withAggregate($relation, $column, $function)`. */
     withAggregate(relation: string, column: string, fn: "count" | "sum" | "avg" | "min" | "max"): this;
-    /** Laravel Eloquent `join` (hydrated models still from the base table). */
+    /** `join` (hydrated models still from the base table). */
     join(table: string, first: string, op: string, second: string): this;
-    /** Laravel `leftJoin`. */
+    /** `leftJoin`. */
     leftJoin(table: string, first: string, op: string, second: string): this;
-    /** Laravel `rightJoin`. */
+    /** `rightJoin`. */
     rightJoin(table: string, first: string, op: string, second: string): this;
     where(callback: (query: ModelQuery<T>) => void): this;
     where(column: string, value: unknown): this;
@@ -174,7 +174,7 @@ export declare class ModelQuery<T extends Model = Model, TResult extends "model"
     orWhereLike(column: string, value: string, caseSensitive?: boolean): this;
     whereNotLike(column: string, value: string, caseSensitive?: boolean): this;
     orWhereNotLike(column: string, value: string, caseSensitive?: boolean): this;
-    /** Laravel `whereDate` — same on SQLite / Postgres / MySQL. */
+    /** `whereDate` — same on SQLite / Postgres / MySQL. */
     whereDate(column: string, value: DateInput): this;
     whereDate(column: string, op: string, value: DateInput): this;
     whereYear(column: string, value: number): this;
@@ -229,7 +229,7 @@ export declare class ModelQuery<T extends Model = Model, TResult extends "model"
     /** Apply this query's wheres onto a QueryBuilder (exists subqueries). */
     applyConstraintsTo(q: QueryBuilder): QueryBuilder;
     first(): T | null | Promise<T | null>;
-    /** Laravel `firstOrFail`. */
+    /** `firstOrFail`. */
     firstOrFail(): Promise<T>;
     /**
      * Fetch matching models as an {@link OrmCollection}.
@@ -246,7 +246,7 @@ export declare class ModelQuery<T extends Model = Model, TResult extends "model"
     firstSync(): T | null;
     /** SQLite-only synchronous `find($id)`. */
     findSync(id: string | number): T | null;
-    /** Laravel `Builder::create` — insert on this query's connection. */
+    /** `Builder::create` — insert on this query's connection. */
     create(attributes: Record<string, unknown>): Promise<T>;
     paginate(perPage?: number, page?: number, options?: {
         path?: string;
@@ -257,24 +257,30 @@ export declare class ModelQuery<T extends Model = Model, TResult extends "model"
         path?: string;
         pageName?: string;
     }): Promise<Paginator<T>>;
-    /** Laravel `chunk($count, $callback)`. */
+    /** `chunk($count, $callback)`. */
     chunk(count: number, callback: (models: OrmCollection<T>) => void | Promise<void>): Promise<void>;
-    /** Laravel `lazy($chunkSize)`. */
-    lazy(chunkSize?: number): AsyncGenerator<T, void, unknown>;
-    /** Laravel `chunkById`. */
+    /**
+     * `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): 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>;
-    /** Laravel `lazyById`. */
-    lazyById(chunkSize?: number, column?: string): AsyncGenerator<T, void, unknown>;
-    lazyByIdDesc(chunkSize?: number, column?: string): AsyncGenerator<T, void, unknown>;
+    /** `lazyById`. */
+    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>;
-    /** Laravel `cursorPaginate`. */
+    /** `cursorPaginate`. */
     cursorPaginate(perPage?: number, cursor?: string | null, options?: {
         path?: string;
         cursorName?: string;
     }): Promise<CursorPaginator<T>>;
-    /** Laravel `Builder::count($columns = '*')` — honors `distinct()` for non-`*`. */
+    /** `Builder::count($columns = '*')` — honors `distinct()` for non-`*`. */
     count(column?: string): Promise<number>;
     exists(): Promise<boolean>;
     doesntExist(): Promise<boolean>;
@@ -285,9 +291,9 @@ export declare class ModelQuery<T extends Model = Model, TResult extends "model"
     sole(): Promise<T>;
     value(column: string): Promise<unknown>;
     /**
-     * Laravel `Builder::pluck($column, $key = null)`.
+     * `Builder::pluck($column, $key = null)`.
      * One column → list {@link Collection}. With `key`, selects both columns and
-     * returns a keyed plain object via {@link Collection.pluck} (Laravel assoc map).
+     * returns a keyed plain object via {@link Collection.pluck}.
      */
     pluck(column: string): Promise<Collection<unknown>>;
     pluck(column: string, key: string): Promise<Record<string, unknown>>;
@@ -301,8 +307,8 @@ export declare class ModelQuery<T extends Model = Model, TResult extends "model"
      */
     insert(values: Record<string, unknown> | Record<string, unknown>[]): Promise<boolean>;
     /**
-     * Laravel `Builder::upsert` — insert or update on unique conflict.
-     * When the model uses timestamps, stamps `created_at`/`updated_at` like Eloquent
+     * `Builder::upsert` — insert or update on unique conflict.
+     * When the model uses timestamps, stamps `created_at`/`updated_at`
      * (row values win; `updated_at` is always included in the update column list).
      */
     upsert(values: Record<string, unknown> | Record<string, unknown>[], uniqueBy: string | string[], update?: string[] | null): Promise<number>;