@rudderjs/orm 0.0.6

package/boost/guidelines.md

@@ -0,0 +1,234 @@
+# @rudderjs/orm
+
+## Overview
+
+Eloquent-inspired ORM for RudderJS. Provides a `Model` base class with static query methods, attribute casting, accessors/mutators, soft deletes, observers, scopes, API resources (`JsonResource`), model collections, and factories. The ORM is adapter-based -- the actual database driver (e.g. Prisma) is registered via `ModelRegistry.set(adapter)` in a service provider.
+
+## Key Patterns
+
+### Defining Models
+
+```ts
+import { Model, Attribute } from '@rudderjs/orm'
+
+export class Post extends Model {
+  static table = 'posts'
+  static fillable = ['title', 'body', 'userId']
+  static hidden = ['deletedAt']
+  static softDeletes = true
+
+  static casts = {
+    isPublished: 'boolean',
+    metadata:    'json',
+    createdAt:   'datetime',
+  } as const satisfies Record<string, CastDefinition>
+
+  id!:          number
+  title!:       string
+  body!:        string
+  userId!:      number
+  isPublished!: boolean
+  metadata!:    Record<string, unknown>
+  createdAt!:   Date
+  updatedAt!:   Date
+  deletedAt!:   Date | null
+}
+```
+
+Table name defaults to lowercase class name + `s` if `static table` is omitted.
+
+### Relationships
+
+Relationships are loaded via the query builder's `with()` method. The adapter resolves relation names to the underlying DB joins/includes.
+
+```ts
+const user = await User.with('posts', 'profile').find(1)
+const posts = await Post.with('author', 'comments').where('isPublished', true).get()
+```
+
+### Querying
+
+All query methods are static on the Model class and return a chainable `QueryBuilder`:
+
+```ts
+const user  = await User.find(1)                       // by primary key
+const users = await User.all()                          // all records
+const admin = await User.where('role', 'admin').first() // first match
+
+// Chained queries
+const recent = await Post
+  .where('isPublished', true)
+  .orderBy('createdAt', 'DESC')
+  .limit(10)
+  .get()
+
+// Pagination
+const page = await User.query().paginate(1, 15)
+// => { data: [...], total, page, perPage, lastPage }
+
+// Operators
+const expensive = await Product.where('price', '>', 100).get()
+
+// Soft deletes (when static softDeletes = true)
+const withDeleted = await Post.query().withTrashed().get()
+const onlyDeleted = await Post.query().onlyTrashed().get()
+await Post.restore(id)
+await Post.forceDelete(id)
+```
+
+### Scopes
+
+```ts
+class Post extends Model {
+  static scopes = {
+    published: (query) => query.where('isPublished', true),
+    byAuthor:  (query, userId: number) => query.where('userId', userId),
+  }
+  static globalScopes = {
+    active: (query) => query.where('deletedAt', null),
+  }
+}
+
+// Usage
+const posts = await Post.query().scope('published').scope('byAuthor', 42).get()
+const all   = await Post.query().withoutGlobalScope('active').get()
+```
+
+### Accessors & Casts
+
+Built-in casts: `string`, `integer`, `float`, `boolean`, `date`, `datetime`, `json`, `array`, `encrypted`.
+
+```ts
+import { Attribute } from '@rudderjs/orm'
+
+class User extends Model {
+  static casts = { isAdmin: 'boolean', settings: 'json' }
+
+  static attributes = {
+    firstName: Attribute.make({
+      get: (v) => String(v).charAt(0).toUpperCase() + String(v).slice(1),
+    }),
+    fullName: Attribute.make({
+      get: (_, attrs) => `${attrs['firstName']} ${attrs['lastName']}`,
+    }),
+    password: Attribute.make({
+      set: async (v) => await bcrypt.hash(String(v), 10),
+    }),
+  }
+
+  static appends = ['fullName']
+}
+```
+
+Decorators are also available: `@Hidden`, `@Visible`, `@Appends`, `@Cast('boolean')`.
+
+### API Resources
+
+```ts
+import { JsonResource } from '@rudderjs/orm'
+
+class UserResource extends JsonResource<User> {
+  toArray() {
+    return {
+      id:    this.resource.id,
+      name:  this.resource.name,
+      email: this.resource.email,
+      admin: this.when(this.resource.role === 'admin', true),
+      posts: this.whenLoaded('posts'),
+      ...this.mergeWhen(this.resource.role === 'admin', {
+        permissions: this.resource.permissions,
+      }),
+    }
+  }
+}
+
+// Single resource
+res.json(new UserResource(user).toArray())
+
+// Collection with pagination meta
+res.json(await UserResource.collection(users, { total: 100, page: 1 }).toResponse())
+```
+
+### Factories
+
+```ts
+import { ModelFactory, sequence } from '@rudderjs/orm'
+
+class UserFactory extends ModelFactory<{ name: string; email: string; role: string }> {
+  protected modelClass = User
+
+  definition() {
+    return {
+      name:  'Alice',
+      email: sequence(i => `user${i}@example.com`)(),
+      role:  'user',
+    }
+  }
+
+  protected states() {
+    return {
+      admin: () => ({ role: 'admin' }),
+    }
+  }
+}
+
+const user  = await UserFactory.new().create()
+const admin = await UserFactory.new().state('admin').create()
+const users = await UserFactory.new().create(5)
+const dto   = await UserFactory.new().make()  // no DB write
+```
+
+### Observers
+
+```ts
+class UserObserver {
+  creating(data: Record<string, unknown>) {
+    data['slug'] = slugify(data['name'] as string)
+    return data
+  }
+  created(record: Record<string, unknown>) {
+    console.log('User created:', record['id'])
+  }
+}
+
+User.observe(UserObserver)
+
+// Or inline event listeners
+User.on('updating', (id, data) => { data['updatedAt'] = new Date() ; return data })
+```
+
+## Common Pitfalls
+
+- **No adapter registered**: You must call `ModelRegistry.set(adapter)` in a service provider before using any Model. The `DatabaseServiceProvider` must come before providers that query models.
+- **Forgotten `static table`**: Without it, table name is auto-derived as `lowercase(ClassName) + 's'` (e.g. `User` -> `users`). Set it explicitly if your table name differs.
+- **Casts not applied on write**: Casts transform values in both directions. If you bypass `Model.create()`/`Model.update()` and write directly via the adapter, casts and mutators are skipped.
+- **Appends without accessor**: Adding a field to `static appends` has no effect unless it also has a `get` function in `static attributes`.
+- **`encrypted` casts need `@rudderjs/crypt`**: The `encrypted`, `encrypted:array`, and `encrypted:object` casts require `@rudderjs/crypt` as a peer dependency.
+
+## Key Imports
+
+```ts
+import {
+  Model,
+  Attribute,
+  JsonResource,
+  ResourceCollection,
+  ModelCollection,
+  ModelFactory,
+  sequence,
+  ModelRegistry,
+  Hidden,
+  Visible,
+  Appends,
+  Cast,
+} from '@rudderjs/orm'
+
+import type {
+  QueryBuilder,
+  PaginatedResult,
+  CastDefinition,
+  CastUsing,
+  ModelEvent,
+  ModelObserver,
+} from '@rudderjs/orm'
+```

package/dist/attribute.d.ts

@@ -0,0 +1,36 @@
+export interface AttributeConfig<TGet = unknown, TSet = unknown> {
+    /** Transform the raw stored value when reading (accessor). */
+    get?: (value: unknown, attributes: Record<string, unknown>) => TGet;
+    /** Transform the value before writing to the database (mutator). */
+    set?: (value: TSet, attributes: Record<string, unknown>) => unknown;
+}
+/**
+ * Defines a model accessor and/or mutator for a property.
+ *
+ * @example
+ * class User extends Model {
+ *   static attributes = {
+ *     // Accessor only — capitalises first name on read
+ *     firstName: Attribute.make({
+ *       get: (v) => String(v).charAt(0).toUpperCase() + String(v).slice(1),
+ *     }),
+ *
+ *     // Mutator only — hash password on write
+ *     password: Attribute.make({
+ *       set: async (v) => await bcrypt.hash(String(v), 10),
+ *     }),
+ *
+ *     // Computed property from multiple columns (accessor only)
+ *     fullName: Attribute.make({
+ *       get: (_, attrs) => `${attrs['firstName']} ${attrs['lastName']}`,
+ *     }),
+ *   }
+ * }
+ */
+export declare class Attribute<TGet = unknown, TSet = unknown> {
+    readonly getter: ((value: unknown, attributes: Record<string, unknown>) => TGet) | undefined;
+    readonly setter: ((value: TSet, attributes: Record<string, unknown>) => unknown) | undefined;
+    private constructor();
+    static make<TGet = unknown, TSet = unknown>(config: AttributeConfig<TGet, TSet>): Attribute<TGet, TSet>;
+}
+//# sourceMappingURL=attribute.d.ts.map

package/dist/attribute.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attribute.d.ts","sourceRoot":"","sources":["../src/attribute.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,eAAe,CAAC,IAAI,GAAG,OAAO,EAAE,IAAI,GAAG,OAAO;IAC7D,8DAA8D;IAC9D,GAAG,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAA;IACnE,oEAAoE;IACpE,GAAG,CAAC,EAAE,CAAC,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAA;CACpE;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,SAAS,CAAC,IAAI,GAAG,OAAO,EAAE,IAAI,GAAG,OAAO;IAEjD,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC,GAAG,SAAS;IAC5F,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,GAAG,SAAS;IAF9F,OAAO;IAKP,MAAM,CAAC,IAAI,CAAC,IAAI,GAAG,OAAO,EAAE,IAAI,GAAG,OAAO,EACxC,MAAM,EAAE,eAAe,CAAC,IAAI,EAAE,IAAI,CAAC,GAClC,SAAS,CAAC,IAAI,EAAE,IAAI,CAAC;CAGzB"}

package/dist/attribute.js

@@ -0,0 +1,36 @@
+// ─── Attribute (Accessor / Mutator) ────────────────────────
+/**
+ * Defines a model accessor and/or mutator for a property.
+ *
+ * @example
+ * class User extends Model {
+ *   static attributes = {
+ *     // Accessor only — capitalises first name on read
+ *     firstName: Attribute.make({
+ *       get: (v) => String(v).charAt(0).toUpperCase() + String(v).slice(1),
+ *     }),
+ *
+ *     // Mutator only — hash password on write
+ *     password: Attribute.make({
+ *       set: async (v) => await bcrypt.hash(String(v), 10),
+ *     }),
+ *
+ *     // Computed property from multiple columns (accessor only)
+ *     fullName: Attribute.make({
+ *       get: (_, attrs) => `${attrs['firstName']} ${attrs['lastName']}`,
+ *     }),
+ *   }
+ * }
+ */
+export class Attribute {
+    getter;
+    setter;
+    constructor(getter, setter) {
+        this.getter = getter;
+        this.setter = setter;
+    }
+    static make(config) {
+        return new Attribute(config.get, config.set);
+    }
+}
+//# sourceMappingURL=attribute.js.map

package/dist/attribute.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"attribute.js","sourceRoot":"","sources":["../src/attribute.ts"],"names":[],"mappings":"AAAA,8DAA8D;AAS9D;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,OAAO,SAAS;IAET;IACA;IAFX,YACW,MAAmF,EACnF,MAAmF;QADnF,WAAM,GAAN,MAAM,CAA6E;QACnF,WAAM,GAAN,MAAM,CAA6E;IAC3F,CAAC;IAEJ,MAAM,CAAC,IAAI,CACT,MAAmC;QAEnC,OAAO,IAAI,SAAS,CAAC,MAAM,CAAC,GAAG,EAAE,MAAM,CAAC,GAAG,CAAC,CAAA;IAC9C,CAAC;CACF"}

package/dist/cast.d.ts

@@ -0,0 +1,14 @@
+export type BuiltInCast = 'string' | 'integer' | 'float' | 'boolean' | 'date' | 'datetime' | 'json' | 'array' | 'collection' | 'encrypted' | 'encrypted:array' | 'encrypted:object';
+/** Interface for a custom cast class. */
+export interface CastUsing {
+    /** Transform a raw DB value to the application type (on read). */
+    get(key: string, value: unknown, attributes: Record<string, unknown>): unknown;
+    /** Transform an application value to a DB-storable type (on write). */
+    set(key: string, value: unknown, attributes: Record<string, unknown>): unknown;
+}
+export type CastDefinition = BuiltInCast | (new () => CastUsing);
+/** Apply a cast when reading from DB (get side). */
+export declare function castGet(type: string, key: string, value: unknown, attributes: Record<string, unknown>): unknown;
+/** Apply a cast when writing to DB (set side). */
+export declare function castSet(type: string, key: string, value: unknown, attributes: Record<string, unknown>): unknown;
+//# sourceMappingURL=cast.d.ts.map

package/dist/cast.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cast.d.ts","sourceRoot":"","sources":["../src/cast.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,WAAW,GACnB,QAAQ,GACR,SAAS,GACT,OAAO,GACP,SAAS,GACT,MAAM,GACN,UAAU,GACV,MAAM,GACN,OAAO,GACP,YAAY,GACZ,WAAW,GACX,iBAAiB,GACjB,kBAAkB,CAAA;AAEtB,yCAAyC;AACzC,MAAM,WAAW,SAAS;IACxB,kEAAkE;IAClE,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAA;IAC9E,uEAAuE;IACvE,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAA;CAC/E;AAED,MAAM,MAAM,cAAc,GAAG,WAAW,GAAG,CAAC,UAAU,SAAS,CAAC,CAAA;AAIhE,oDAAoD;AACpD,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CA2B/G;AAED,kDAAkD;AAClD,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAyB/G"}

package/dist/cast.js

@@ -0,0 +1,85 @@
+// ─── Cast Types ────────────────────────────────────────────
+// ─── Built-in cast helpers ──────────────────────────────────
+/** Apply a cast when reading from DB (get side). */
+export function castGet(type, key, value, attributes) {
+    if (value === null || value === undefined)
+        return value;
+    if (typeof type !== 'string') {
+        // custom cast class — type is a constructor
+        const instance = new type();
+        return instance.get(key, value, attributes);
+    }
+    switch (type) {
+        case 'string': return String(value);
+        case 'integer': return parseInt(String(value), 10);
+        case 'float': return parseFloat(String(value));
+        case 'boolean': return value === 1 || value === '1' || value === true || value === 'true';
+        case 'date': return new Date(String(value));
+        case 'datetime': return new Date(String(value));
+        case 'json':
+        case 'array': return typeof value === 'string' ? JSON.parse(value) : value;
+        case 'collection':
+            // Returns plain array — ModelCollection wrapping done by caller if needed
+            return typeof value === 'string' ? JSON.parse(value) : value;
+        case 'encrypted':
+        case 'encrypted:array':
+        case 'encrypted:object':
+            return _decrypt(type, value);
+        default: return value;
+    }
+}
+/** Apply a cast when writing to DB (set side). */
+export function castSet(type, key, value, attributes) {
+    if (value === null || value === undefined)
+        return value;
+    if (typeof type !== 'string') {
+        const instance = new type();
+        return instance.set(key, value, attributes);
+    }
+    switch (type) {
+        case 'string': return String(value);
+        case 'integer': return parseInt(String(value), 10);
+        case 'float': return parseFloat(String(value));
+        case 'boolean': return value === true || value === 'true' || value === 1 || value === '1' ? 1 : 0;
+        case 'date': return value instanceof Date ? value.toISOString().slice(0, 10) : String(value);
+        case 'datetime': return value instanceof Date ? value.toISOString() : String(value);
+        case 'json':
+        case 'array':
+        case 'collection':
+            return typeof value === 'object' ? JSON.stringify(value) : value;
+        case 'encrypted':
+        case 'encrypted:array':
+        case 'encrypted:object':
+            return _encrypt(type, value);
+        default: return value;
+    }
+}
+// ─── Encryption stubs ───────────────────────────────────────
+// Uses @rudderjs/crypt if available, otherwise throws clearly.
+function _getCrypt() {
+    try {
+        // Dynamic require — only works if @rudderjs/crypt is installed
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        return require('@rudderjs/crypt');
+    }
+    catch {
+        return null;
+    }
+}
+function _encrypt(castType, value) {
+    const crypt = _getCrypt();
+    if (!crypt) {
+        throw new Error(`[RudderJS ORM] Cast type "${castType}" requires @rudderjs/crypt. Run: pnpm add @rudderjs/crypt`);
+    }
+    const serialized = castType === 'encrypted' ? String(value) : JSON.stringify(value);
+    return crypt.encrypt(serialized);
+}
+function _decrypt(castType, value) {
+    const crypt = _getCrypt();
+    if (!crypt) {
+        throw new Error(`[RudderJS ORM] Cast type "${castType}" requires @rudderjs/crypt. Run: pnpm add @rudderjs/crypt`);
+    }
+    const decrypted = crypt.decrypt(String(value));
+    return castType === 'encrypted' ? decrypted : JSON.parse(decrypted);
+}
+//# sourceMappingURL=cast.js.map

package/dist/cast.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cast.js","sourceRoot":"","sources":["../src/cast.ts"],"names":[],"mappings":"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"}

package/dist/collection.d.ts

@@ -0,0 +1,73 @@
+import type { Model } from './index.js';
+import type { QueryBuilder } from '@rudderjs/contracts';
+/**
+ * A typed array wrapper for Eloquent-style model collection operations.
+ * Returned by ORM queries when using `ModelCollection.wrap()`.
+ *
+ * @example
+ * const users = ModelCollection.wrap(await User.all())
+ *
+ * users.modelKeys()          // [1, 2, 3]
+ * users.find(2)              // { id: 2, ... }
+ * users.contains(2)          // true
+ * users.except([1, 3])       // [{ id: 2, ... }]
+ * users.only([1, 2])         // [{ id: 1, ... }, { id: 2, ... }]
+ * users.unique('email')      // deduplicated by email
+ * users.makeHidden(['email']) // each item's email hidden from JSON
+ */
+export declare class ModelCollection<T extends Record<string, unknown>> {
+    private readonly _items;
+    private readonly _primaryKey;
+    private constructor();
+    static wrap<T extends Record<string, unknown>>(items: T[], primaryKey?: string): ModelCollection<T>;
+    all(): T[];
+    count(): number;
+    isEmpty(): boolean;
+    isNotEmpty(): boolean;
+    toArray(): T[];
+    /** Returns an array of primary key values. */
+    modelKeys(): Array<string | number>;
+    /** Find item by primary key, or `undefined` if not found. */
+    find(id: string | number): T | undefined;
+    /**
+     * Returns true if any item matches. Accepts a primary key value or a predicate.
+     */
+    contains(idOrFn: string | number | ((item: T) => boolean)): boolean;
+    /** Items whose primary key is NOT in `ids`. */
+    except(ids: Array<string | number>): ModelCollection<T>;
+    /** Items whose primary key IS in `ids`. */
+    only(ids: Array<string | number>): ModelCollection<T>;
+    /** Items not present in `other` (diff by primary key). */
+    diff(other: ModelCollection<T> | T[]): ModelCollection<T>;
+    /**
+     * Items unique by the given key (or primary key if omitted).
+     * First occurrence wins.
+     */
+    unique(key?: string): ModelCollection<T>;
+    /** Call `makeVisible(keys)` on each model instance and return a new collection. */
+    makeVisible(keys: string[]): ModelCollection<T>;
+    /** Call `makeHidden(keys)` on each model instance and return a new collection. */
+    makeHidden(keys: string[]): ModelCollection<T>;
+    /**
+     * Reload each item from the database. Returns a new collection with fresh data.
+     * Items are loaded via `Model.find(id)` so they must have their primary key set.
+     */
+    fresh(modelClass: typeof Model): Promise<ModelCollection<Record<string, unknown>>>;
+    /**
+     * Eager-load relations for all items.
+     * Returns a new collection with relations loaded.
+     */
+    load(modelClass: typeof Model, ...relations: string[]): Promise<ModelCollection<Record<string, unknown>>>;
+    /**
+     * Eager-load relations that are not already present on the items.
+     * Only loads relations where `item[relation]` is undefined.
+     */
+    loadMissing(modelClass: typeof Model, ...relations: string[]): Promise<ModelCollection<Record<string, unknown>>>;
+    /**
+     * Return a query builder scoped to this collection's primary keys.
+     * Useful for building additional queries on the same set of records.
+     */
+    toQuery(modelClass: typeof Model): QueryBuilder<T>;
+    toJSON(): T[];
+}
+//# sourceMappingURL=collection.d.ts.map

package/dist/collection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"collection.d.ts","sourceRoot":"","sources":["../src/collection.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AACvC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AAIvD;;;;;;;;;;;;;;GAcG;AACH,qBAAa,eAAe,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAE1D,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,WAAW;IAF9B,OAAO;IAKP,MAAM,CAAC,IAAI,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC3C,KAAK,EAAE,CAAC,EAAE,EACV,UAAU,SAAO,GAChB,eAAe,CAAC,CAAC,CAAC;IAMrB,GAAG,IAAI,CAAC,EAAE;IACV,KAAK,IAAI,MAAM;IACf,OAAO,IAAI,OAAO;IAClB,UAAU,IAAI,OAAO;IACrB,OAAO,IAAI,CAAC,EAAE;IAEd,8CAA8C;IAC9C,SAAS,IAAI,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC;IAMnC,6DAA6D;IAC7D,IAAI,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,CAAC,GAAG,SAAS;IAIxC;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,KAAK,OAAO,CAAC,GAAG,OAAO;IAOnE,+CAA+C;IAC/C,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC,GAAG,eAAe,CAAC,CAAC,CAAC;IAQvD,2CAA2C;IAC3C,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC,GAAG,eAAe,CAAC,CAAC,CAAC;IAQrD,0DAA0D;IAC1D,IAAI,CAAC,KAAK,EAAE,eAAe,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,GAAG,eAAe,CAAC,CAAC,CAAC;IASzD;;;OAGG;IACH,MAAM,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,eAAe,CAAC,CAAC,CAAC;IAgBxC,mFAAmF;IACnF,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,eAAe,CAAC,CAAC,CAAC;IAa/C,kFAAkF;IAClF,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,eAAe,CAAC,CAAC,CAAC;IAe9C;;;OAGG;IACG,KAAK,CAAC,UAAU,EAAE,OAAO,KAAK,GAAG,OAAO,CAAC,eAAe,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAUxF;;;OAGG;IACG,IAAI,CACR,UAAU,EAAE,OAAO,KAAK,EACxB,GAAG,SAAS,EAAE,MAAM,EAAE,GACrB,OAAO,CAAC,eAAe,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAOpD;;;OAGG;IACG,WAAW,CACf,UAAU,EAAE,OAAO,KAAK,EACxB,GAAG,SAAS,EAAE,MAAM,EAAE,GACrB,OAAO,CAAC,eAAe,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAWpD;;;OAGG;IACH,OAAO,CAAC,UAAU,EAAE,OAAO,KAAK,GAAG,YAAY,CAAC,CAAC,CAAC;IAMlD,MAAM,IAAI,CAAC,EAAE;CAGd"}

package/dist/collection.js

@@ -0,0 +1,152 @@
+// ─── ModelCollection ────────────────────────────────────────
+/**
+ * A typed array wrapper for Eloquent-style model collection operations.
+ * Returned by ORM queries when using `ModelCollection.wrap()`.
+ *
+ * @example
+ * const users = ModelCollection.wrap(await User.all())
+ *
+ * users.modelKeys()          // [1, 2, 3]
+ * users.find(2)              // { id: 2, ... }
+ * users.contains(2)          // true
+ * users.except([1, 3])       // [{ id: 2, ... }]
+ * users.only([1, 2])         // [{ id: 1, ... }, { id: 2, ... }]
+ * users.unique('email')      // deduplicated by email
+ * users.makeHidden(['email']) // each item's email hidden from JSON
+ */
+export class ModelCollection {
+    _items;
+    _primaryKey;
+    constructor(_items, _primaryKey = 'id') {
+        this._items = _items;
+        this._primaryKey = _primaryKey;
+    }
+    static wrap(items, primaryKey = 'id') {
+        return new ModelCollection(items, primaryKey);
+    }
+    // ── Core ──────────────────────────────────────────────
+    all() { return this._items; }
+    count() { return this._items.length; }
+    isEmpty() { return this._items.length === 0; }
+    isNotEmpty() { return this._items.length > 0; }
+    toArray() { return [...this._items]; }
+    /** Returns an array of primary key values. */
+    modelKeys() {
+        return this._items.map(item => item[this._primaryKey]);
+    }
+    // ── Search ────────────────────────────────────────────
+    /** Find item by primary key, or `undefined` if not found. */
+    find(id) {
+        return this._items.find(item => item[this._primaryKey] === id);
+    }
+    /**
+     * Returns true if any item matches. Accepts a primary key value or a predicate.
+     */
+    contains(idOrFn) {
+        if (typeof idOrFn === 'function')
+            return this._items.some(idOrFn);
+        return this._items.some(item => item[this._primaryKey] === idOrFn);
+    }
+    // ── Filtering ─────────────────────────────────────────
+    /** Items whose primary key is NOT in `ids`. */
+    except(ids) {
+        const set = new Set(ids);
+        return ModelCollection.wrap(this._items.filter(item => !set.has(item[this._primaryKey])), this._primaryKey);
+    }
+    /** Items whose primary key IS in `ids`. */
+    only(ids) {
+        const set = new Set(ids);
+        return ModelCollection.wrap(this._items.filter(item => set.has(item[this._primaryKey])), this._primaryKey);
+    }
+    /** Items not present in `other` (diff by primary key). */
+    diff(other) {
+        const otherItems = other instanceof ModelCollection ? other.all() : other;
+        const otherKeys = new Set(otherItems.map(i => i[this._primaryKey]));
+        return ModelCollection.wrap(this._items.filter(item => !otherKeys.has(item[this._primaryKey])), this._primaryKey);
+    }
+    /**
+     * Items unique by the given key (or primary key if omitted).
+     * First occurrence wins.
+     */
+    unique(key) {
+        const k = key ?? this._primaryKey;
+        const seen = new Set();
+        return ModelCollection.wrap(this._items.filter(item => {
+            const val = item[k];
+            if (seen.has(val))
+                return false;
+            seen.add(val);
+            return true;
+        }), this._primaryKey);
+    }
+    // ── Serialization controls ────────────────────────────
+    /** Call `makeVisible(keys)` on each model instance and return a new collection. */
+    makeVisible(keys) {
+        return ModelCollection.wrap(this._items.map(item => {
+            const m = item;
+            if (typeof m['makeVisible'] === 'function') {
+                return m['makeVisible'](keys);
+            }
+            return item;
+        }), this._primaryKey);
+    }
+    /** Call `makeHidden(keys)` on each model instance and return a new collection. */
+    makeHidden(keys) {
+        return ModelCollection.wrap(this._items.map(item => {
+            const m = item;
+            if (typeof m['makeHidden'] === 'function') {
+                return m['makeHidden'](keys);
+            }
+            return item;
+        }), this._primaryKey);
+    }
+    // ── Async ORM operations ──────────────────────────────
+    /**
+     * Reload each item from the database. Returns a new collection with fresh data.
+     * Items are loaded via `Model.find(id)` so they must have their primary key set.
+     */
+    async fresh(modelClass) {
+        const ids = this.modelKeys();
+        const results = await Promise.all(ids.map(id => modelClass.find(id)));
+        return ModelCollection.wrap(
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        results.filter((r) => r !== null), this._primaryKey);
+    }
+    /**
+     * Eager-load relations for all items.
+     * Returns a new collection with relations loaded.
+     */
+    async load(modelClass, ...relations) {
+        const ids = this.modelKeys();
+        const items = await modelClass.with(...relations).where(this._primaryKey, ids).get();
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        return ModelCollection.wrap(items, this._primaryKey);
+    }
+    /**
+     * Eager-load relations that are not already present on the items.
+     * Only loads relations where `item[relation]` is undefined.
+     */
+    async loadMissing(modelClass, ...relations) {
+        const first = this._items[0];
+        if (!first)
+            return ModelCollection.wrap([], this._primaryKey);
+        const missing = relations.filter(rel => !(rel in first) || first[rel] === undefined);
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        if (missing.length === 0)
+            return ModelCollection.wrap(this._items, this._primaryKey);
+        return this.load(modelClass, ...missing);
+    }
+    /**
+     * Return a query builder scoped to this collection's primary keys.
+     * Useful for building additional queries on the same set of records.
+     */
+    toQuery(modelClass) {
+        const ids = this.modelKeys();
+        // Use where with array to produce a WHERE IN equivalent
+        return modelClass.where(this._primaryKey, ids);
+    }
+    toJSON() {
+        return this.toArray();
+    }
+}
+//# sourceMappingURL=collection.js.map