ilana-orm 1.0.19 → 1.0.20

package/README.md

@@ -5,7 +5,19 @@
 
 **Ìlànà** (pronounced "ee-LAH-nah") - A Yoruba word meaning "pattern," "system," or "protocol."
 
-A fully-featured, Eloquent-style ORM for Node.js with automatic TypeScript support. IlanaORM provides complete feature parity with Laravel's Eloquent ORM, following established patterns and protocols for database interaction, modeling, querying, relationships, events, casting, migrations, and more.
+A fully-featured, Laravel Eloquent-style ORM for Node.js & TypeScript. If you know Eloquent, you already know IlanaORM — same API, same patterns, same conventions. MySQL, PostgreSQL, SQLite, Supabase, edge runtimes, and pgvector AI search out of the box.
+
+| Feature | IlanaORM | Prisma | Drizzle | TypeORM |
+|---|:---:|:---:|:---:|:---:|
+| Eloquent-identical API | ✅ | ❌ | ❌ | ❌ |
+| pgvector / AI search built-in | ✅ | ❌ | ❌ | ❌ |
+| Edge runtime (Cloudflare, Next.js) | ✅ | ⚠️ | ✅ | ❌ |
+| Supabase compatible | ✅ | ✅ | ✅ | ⚠️ |
+| ULID primary keys | ✅ | ⚠️ | ⚠️ | ⚠️ |
+| Factories & seeders built-in | ✅ | ❌ | ❌ | ❌ |
+| Model events | ✅ | ⚠️ | ❌ | ✅ |
+| Soft deletes | ✅ | ❌ | ❌ | ✅ |
+| No code generation step | ✅ | ❌ | ✅ | ✅ |
 
 ## Table of Contents
 
@@ -718,6 +730,11 @@ class User extends Model {
   fillable = ["name", "email", "password"];
   guarded = ["id", "created_at", "updated_at"];
 
+  // By default, fill()/update() silently drops any key not covered by
+  // fillable/guarded — e.g. update({ typo_column: x }) resolves successfully
+  // and writes nothing. Opt in to catch that instead of silently swallowing it:
+  static preventsSilentlyDiscardingAttributes = true; // throws MassAssignmentException on any discarded key
+
   // Hidden attributes (won't appear in JSON)
   hidden = ["password", "remember_token"];
 
@@ -4543,6 +4560,7 @@ user.replicate(except?); // Clone as unsaved record (excludes PK + timestamps)
 
 // Attributes
 user.fill(attributes); // Mass assign (respects fillable/guarded)
+user.forceFill(attributes); // Mass assign, bypassing fillable/guarded entirely
 user.getAttribute(key); // Get attribute (calls accessor if defined)
 user.setAttribute(key, value); // Set attribute (calls mutator if defined)
 user.getKey(); // Get primary key value

package/index.d.ts

@@ -22,5 +22,13 @@ export declare class ModelNotFoundException extends Error {
   toResponse(): { status: 404; message: string };
 }
 
+export declare class MassAssignmentException extends Error {
+  name: 'MassAssignmentException';
+  model: string;
+  discardedKeys: string[];
+  constructor(model: string, discardedKeys: string[]);
+  toResponse(): { status: 422; message: string };
+}
+
 // Default export
 export { default } from './orm/Model';

package/index.edge.mjs

@@ -18,6 +18,7 @@ export const {
   Factory,
   defineFactory,
   ModelNotFoundException,
+  MassAssignmentException,
   F,
   HasOne,
   HasMany,

package/index.js

@@ -10,7 +10,7 @@ const Seeder = require('./orm/Seeder');
 const Factory = require('./orm/Factory');
 const Relation = require('./orm/Relation');
 const CustomCasts = require('./orm/CustomCasts');
-const { ModelNotFoundException } = require('./orm/Errors');
+const { ModelNotFoundException, MassAssignmentException } = require('./orm/Errors');
 const { F } = require('./orm/F');
 
 module.exports = {
@@ -25,6 +25,7 @@ module.exports = {
   Factory: Factory.Factory,
   defineFactory: Factory.defineFactory,
   ModelNotFoundException,
+  MassAssignmentException,
   F,
 
   // Relationships

package/index.mjs

@@ -16,6 +16,7 @@ export const {
   Factory,
   defineFactory,
   ModelNotFoundException,
+  MassAssignmentException,
   F,
   Relation,
   HasOne,

package/orm/Errors.js

@@ -15,4 +15,23 @@ class ModelNotFoundException extends Error {
   }
 }
 
-module.exports = { ModelNotFoundException };
+class MassAssignmentException extends Error {
+  constructor(model, discardedKeys) {
+    const keys = discardedKeys.join(', ');
+    super(
+      `Mass assignment blocked on ${model}: [${keys}] are not fillable, so ${model}.preventsSilentlyDiscardingAttributes ` +
+      `stopped the call instead of dropping them silently. Add the intended column(s) to ${model}.fillable, adjust ` +
+      `${model}.guarded, or set the attribute(s) directly (e.g. instance.column = value) instead of going through fill()/update().`
+    );
+    this.name = 'MassAssignmentException';
+    this.model = model;
+    this.discardedKeys = discardedKeys;
+    if (Error.captureStackTrace) Error.captureStackTrace(this, MassAssignmentException);
+  }
+
+  toResponse() {
+    return { status: 422, message: this.message };
+  }
+}
+
+module.exports = { ModelNotFoundException, MassAssignmentException };

package/orm/Factory.js

@@ -172,7 +172,7 @@ class Factory {
     const modelAttributes = this.makeRaw(attributes);
 
     const model = new this.model();
-    model.fill(modelAttributes);
+    model.forceFill(modelAttributes);
 
     // Run afterMaking callbacks
     for (const callback of this._afterMakingCallbacks) {
@@ -364,7 +364,7 @@ class BulkFactory {
       
       for (let k = 0; k < batchData.length; k++) {
         const model = new this.model();
-        model.fill({ ...batchData[k], id: insertedIds[k] });
+        model.forceFill({ ...batchData[k], id: insertedIds[k] });
         model.exists = true;
         results.push(model);
       }

package/orm/Model.d.ts

@@ -1,4 +1,5 @@
-import QueryBuilder from './QueryBuilder';
+import QueryBuilder, { PaginationResult, SimplePaginationResult, CursorPaginationResult } from './QueryBuilder';
+import Collection from './Collection';
 import { HasOne, HasMany, BelongsTo, BelongsToMany, HasManyThrough, MorphTo, MorphOne, MorphMany } from './Relation';
 
 export interface ModelAttributes {
@@ -51,6 +52,7 @@ export default class Model<TAttributes extends ModelAttributes = ModelAttributes
   protected static appends: string[];
   protected static timezone: string;
   static strictLoading: boolean;
+  static preventsSilentlyDiscardingAttributes: boolean;
   static touches: string[];
   static enums: { [column: string]: string[] };
   static embeddingColumn: string;
@@ -75,6 +77,7 @@ export default class Model<TAttributes extends ModelAttributes = ModelAttributes
 
   // Static methods
   static register(): void;
+  static _autoRegister(): void;
   static resolveRelatedModel(related: string | typeof Model): typeof Model;
   static query(): QueryBuilder;
   static with(...relations: string[]): QueryBuilder;
@@ -112,6 +115,113 @@ export default class Model<TAttributes extends ModelAttributes = ModelAttributes
   static firstOrNew(attributes: ModelAttributes, values?: ModelAttributes): Promise<Model>;
   static updateOrCreate(attributes: ModelAttributes, values?: ModelAttributes): Promise<Model>;
 
+  // QueryBuilder methods forwarded from Model.query() — at runtime, any
+  // QueryBuilder method not already declared above is proxied automatically
+  // from Model.<method>() to Model.query().<method>() (see Model.js), so this
+  // list exists purely to give TypeScript users type information for it.
+  static where(column: string, value: any): QueryBuilder;
+  static where(column: string, operator: string, value: any): QueryBuilder;
+  static orWhere(column: string, value: any): QueryBuilder;
+  static orWhere(column: string, operator: string, value: any): QueryBuilder;
+  static whereIn(column: string, values: any[]): QueryBuilder;
+  static whereNotIn(column: string, values: any[]): QueryBuilder;
+  static whereNull(column: string): QueryBuilder;
+  static whereNotNull(column: string): QueryBuilder;
+  static whereBetween(column: string, range: [any, any]): QueryBuilder;
+  static whereNotBetween(column: string, range: [any, any]): QueryBuilder;
+  static whereJsonContains(column: string, value: any): QueryBuilder;
+  static whereJsonLength(column: string, operator: string, value: number): QueryBuilder;
+  static whereDate(column: string, value: string): QueryBuilder;
+  static whereDate(column: string, operator: string, value: string): QueryBuilder;
+  static whereMonth(column: string, month: number): QueryBuilder;
+  static whereYear(column: string, year: number): QueryBuilder;
+  static whereDay(column: string, operatorOrValue: any, value?: any): QueryBuilder;
+  static whereTime(column: string, operatorOrValue: any, value?: any): QueryBuilder;
+  static whereRaw(sql: string, bindings?: any[]): QueryBuilder;
+  static orWhereNull(column: string): QueryBuilder;
+  static orWhereNotNull(column: string): QueryBuilder;
+  static orWhereIn(column: string, values: any[]): QueryBuilder;
+  static orWhereNotIn(column: string, values: any[]): QueryBuilder;
+  static orWhereRaw(sql: string, bindings?: any[]): QueryBuilder;
+  static whereExists(callback: (query: QueryBuilder) => void): QueryBuilder;
+  static whereNotExists(callback: (query: QueryBuilder) => void): QueryBuilder;
+  static when<T>(condition: T, callback: (query: QueryBuilder, condition: T) => void, otherwise?: (query: QueryBuilder) => void): QueryBuilder;
+  static unless<T>(condition: T, callback: (query: QueryBuilder) => void, otherwise?: (query: QueryBuilder, condition: T) => void): QueryBuilder;
+
+  static join(table: string, first: string, operator: string, second: string): QueryBuilder;
+  static leftJoin(table: string, first: string, operator: string, second: string): QueryBuilder;
+  static rightJoin(table: string, first: string, operator: string, second: string): QueryBuilder;
+  static innerJoin(table: string, first: string, operator: string, second: string): QueryBuilder;
+  static crossJoin(table: string): QueryBuilder;
+
+  static orderBy(column: string, direction?: 'asc' | 'desc'): QueryBuilder;
+  static orderByRaw(sql: string): QueryBuilder;
+  static orderBySubquery(callback: (query: QueryBuilder) => void, direction?: 'asc' | 'desc'): QueryBuilder;
+  static inRandomOrder(): QueryBuilder;
+  static limit(count: number): QueryBuilder;
+  static offset(count: number): QueryBuilder;
+  static take(count: number): QueryBuilder;
+  static skip(count: number): QueryBuilder;
+  static from(table: string): QueryBuilder;
+  static forPage(page: number, perPage?: number): QueryBuilder;
+
+  static groupBy(...columns: string[]): QueryBuilder;
+  static having(column: string, operator: string, value: any): QueryBuilder;
+  static having(rawSql: string): QueryBuilder;
+  static havingRaw(sql: string, bindings?: any[]): QueryBuilder;
+
+  static lockForUpdate(): QueryBuilder;
+  static sharedLock(): QueryBuilder;
+  static skipLocked(): QueryBuilder;
+  static noWait(): QueryBuilder;
+
+  static select(...columns: any[]): QueryBuilder;
+  static addSelect(...columns: any[]): QueryBuilder;
+  static addSelect(subqueries: { [alias: string]: (query: QueryBuilder) => void }): QueryBuilder;
+  static distinct(): QueryBuilder;
+  static selectRaw(sql: string, bindings?: any[]): QueryBuilder;
+
+  static withPendingAttributes(attributes: { [key: string]: any }): QueryBuilder;
+  static withConstraints(relation: string, callback: (query: QueryBuilder) => void): QueryBuilder;
+  static withConstraints(relations: { [key: string]: (query: QueryBuilder) => void }): QueryBuilder;
+  static whereHas(relation: string, callback?: (query: QueryBuilder) => void): QueryBuilder;
+  static doesntHave(relation: string): QueryBuilder;
+  static whereDoesntHave(relation: string, callback?: (query: QueryBuilder) => void): QueryBuilder;
+  static has(relation: string, operator?: '=' | '!=' | '<' | '<=' | '>' | '>=', count?: number): QueryBuilder;
+
+  static count(column?: string): Promise<number>;
+  static sum(column: string): Promise<number>;
+  static avg(column: string): Promise<number>;
+  static min(column: string): Promise<any>;
+  static max(column: string): Promise<any>;
+
+  static pluck(column: string): Promise<any[]>;
+  static exists(): Promise<boolean>;
+  static doesntExist(): Promise<boolean>;
+  static sole(): Promise<Model>;
+  static tap(callback: (query: QueryBuilder) => void): QueryBuilder;
+  static get(): Promise<Collection<Model>>;
+
+  static paginate(page?: number, perPage?: number): Promise<PaginationResult<Model>>;
+  static simplePaginate(page?: number, perPage?: number): Promise<SimplePaginationResult<Model>>;
+  static cursorPaginate(perPage?: number, cursor?: string, column?: string, direction?: 'asc' | 'desc'): Promise<CursorPaginationResult<Model>>;
+
+  static chunk(size: number, callback: (models: Collection<Model>) => Promise<void>): Promise<void>;
+  static cursor(chunkSize?: number): AsyncGenerator<Model, void, unknown>;
+  static lazy(chunkSize?: number): AsyncGenerator<Model, void, unknown>;
+
+  static update(data: any): Promise<number>;
+  static increment(column: string, amount?: number): Promise<number>;
+  static decrement(column: string, amount?: number): Promise<number>;
+  static delete(): Promise<number>;
+  static restore(): Promise<number>;
+
+  static clone(): QueryBuilder;
+  static toKnex(): any;
+  static toSql(): string;
+  static values(): Promise<any[]>;
+  static new(attributes?: { [key: string]: any }): Promise<Model>;
+
   // Scopes
   static addGlobalScope(name: string, scope: (query: QueryBuilder) => void): void;
   static removeGlobalScope(name: string): void;
@@ -142,6 +252,7 @@ export default class Model<TAttributes extends ModelAttributes = ModelAttributes
   // Instance methods
   getKey(): any;
   fill(attributes: ModelAttributes): this;
+  forceFill(attributes: ModelAttributes): this;
   load(...relations: string[]): Promise<this>;
   loadMissing(...relations: string[]): Promise<this>;
   getRelation(key: string): any;

package/orm/Model.js

@@ -3,6 +3,7 @@ const QueryBuilder = require('./QueryBuilder');
 const { HasOne, HasMany, BelongsTo, BelongsToMany, HasManyThrough, MorphTo, MorphMany, MorphOne } = require('./Relation');
 const ModelRegistry = require('./ModelRegistry');
 const Database = require('../database/connection');
+const { MassAssignmentException } = require('./Errors');
 
 // Auto-load configuration on first import (skipped in edge runtime)
 if (typeof process !== 'undefined' && process.versions && process.versions.node && !global.__ILANA_EDGE__) {
@@ -38,6 +39,7 @@ class Model {
   static appends = [];
   static timezone = 'UTC';
   static strictLoading = false;
+  static preventsSilentlyDiscardingAttributes = false;
   static touches = [];
   static enums = {};
   static embeddingColumn = 'embedding';
@@ -57,6 +59,8 @@ class Model {
   _deferred;
 
   constructor(attrs = {}) {
+    this.constructor._autoRegister();
+
     // instance-level fillable/guarded/casts
     this.fillable = Array.isArray(this.fillable) && this.fillable.length
       ? this.fillable
@@ -168,10 +172,21 @@ class Model {
     ModelRegistry.register(this.name, this);
   }
 
+  // Registers this class the first time it's actually used (constructed or
+  // queried), so string-based relations (this.hasMany('Post')) resolve
+  // without requiring an explicit Post.register() call, as long as Post gets
+  // used somewhere before the relation is loaded. Cheap to call repeatedly:
+  // skips the registry write once this class is already registered as itself.
+  static _autoRegister() {
+    if (ModelRegistry.get(this.name) !== this) {
+      ModelRegistry.register(this.name, this);
+    }
+  }
+
   static resolveRelatedModel(related) {
     if (typeof related === 'string') {
       const cls = ModelRegistry.get(related);
-      if (!cls) throw new Error(`Model '${related}' not found. Make sure to call ${related}.register().`);
+      if (!cls) throw new Error(`Model '${related}' not found. It gets registered automatically the first time it's queried or constructed, so require/use ${related} somewhere before this point, or call ${related}.register() explicitly.`);
       return cls;
     }
 
@@ -193,6 +208,7 @@ class Model {
 
   // --- Query builder ---
   static query() {
+    this._autoRegister();
 
     const qb = new QueryBuilder(this.getTableName(), this, this.getConnectionName());
 
@@ -447,8 +463,29 @@ class Model {
   getKey() { return this.attributes[this.constructor.primaryKey]; }
 
   fill(attrs) {
+    const discarded = [];
+    for (const [k, v] of Object.entries(attrs)) {
+      if (!this.isFillable(k)) { discarded.push(k); continue; }
+      this.setAttribute(k, v);
+    }
+    // Off by default, matching every prior release: a key rejected by
+    // fillable/guarded is silently dropped, same as always. Opt in per-model
+    // with `static preventsSilentlyDiscardingAttributes = true` to instead
+    // throw on any discarded key — useful for catching a forgotten
+    // `fillable` declaration or a typo'd column name in update() calls,
+    // without changing behavior for anyone who hasn't asked for it.
+    if (discarded.length > 0 && this.constructor.preventsSilentlyDiscardingAttributes) {
+      throw new MassAssignmentException(this.constructor.name, discarded);
+    }
+    return this;
+  }
+
+  // Sets attributes bypassing fillable/guarded entirely, for trusted,
+  // programmatic data (factories, seeders, internal code) rather than
+  // user-supplied mass assignment — mirrors fill()'s counterpart in
+  // Eloquent-style ORMs.
+  forceFill(attrs) {
     for (const [k, v] of Object.entries(attrs)) {
-      if (!this.isFillable(k)) continue;
       this.setAttribute(k, v);
     }
     return this;
@@ -909,4 +946,21 @@ class Model {
   }
 }
 
-module.exports = Model;
+// Any QueryBuilder instance method not already forwarded above (e.g. where(),
+// orderBy(), whereIn(), paginate()...) is auto-forwarded from Model.<method>()
+// to Model.query().<method>(), so new QueryBuilder methods don't need a
+// matching static added here to be callable directly on a Model subclass.
+const ModelStaticHandler = {
+  get(target, prop, receiver) {
+    if (typeof prop === 'symbol' || prop in target) {
+      return Reflect.get(target, prop, receiver);
+    }
+    const qbMethod = QueryBuilder.prototype[prop];
+    if (typeof prop === 'string' && prop[0] !== '_' && typeof qbMethod === 'function') {
+      return (...args) => receiver.query()[prop](...args);
+    }
+    return Reflect.get(target, prop, receiver);
+  }
+};
+
+module.exports = new Proxy(Model, ModelStaticHandler);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ilana-orm",
-  "version": "1.0.19",
-  "description": "A fully-featured, Eloquent-style ORM for Node.js with TypeScript support",
+  "version": "1.0.20",
+  "description": "A fully-featured, Laravel Eloquent-style ORM for Node.js & TypeScript. MySQL, PostgreSQL, SQLite, Supabase, edge runtimes, pgvector AI search.",
   "main": "index.js",
   "types": "index.d.ts",
   "exports": {
@@ -80,18 +80,30 @@
   },
   "keywords": [
     "orm",
+    "eloquent",
+    "laravel",
+    "active-record",
     "nodejs",
     "javascript",
-    "typescript-orm",
     "typescript",
+    "typescript-orm",
     "database",
-    "eloquent",
+    "query-builder",
+    "migrations",
+    "relationships",
     "mysql",
     "postgresql",
     "sqlite",
-    "query-builder",
-    "migrations",
-    "relationships"
+    "supabase",
+    "pgvector",
+    "vector-search",
+    "edge-runtime",
+    "cloudflare-workers",
+    "nextjs",
+    "ulid",
+    "knex",
+    "factory",
+    "seeder"
   ],
   "author": "Raphael Abayomi <raphyabak@gmail.com>",
   "license": "MIT",