ilana-orm 1.0.18 → 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
 
@@ -24,6 +36,7 @@ A fully-featured, Eloquent-style ORM for Node.js with automatic TypeScript suppo
 - [Schema Builder](#schema-builder)
 - [Transactions](#transactions)
 - [Advanced Features](#advanced-features)
+- [Supabase](#supabase)
 - [Complete API Reference](#complete-api-reference)
 - [TypeScript Support](#typescript-support)
 - [Performance & Best Practices](#performance--best-practices)
@@ -717,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"];
 
@@ -793,47 +811,33 @@ export default class User extends Model {
 
 ### UUID Primary Keys
 
-**JavaScript:**
 ```javascript
 class User extends Model {
   static table = 'users';
-  static keyType = 'string';
+  static keyType = 'uuid';
   static incrementing = false;
 }
 
-module.exports = User;
-
-// Usage
-const user = await User.create({
-  name: 'John Doe',
-  email: 'john@example.com',
-});
-// user.id will be a generated UUID
-````
+const user = await User.create({ name: 'John Doe', email: 'john@example.com' });
+// user.id → "550e8400-e29b-41d4-a716-446655440000"
+```
 
-**TypeScript:**
+### ULID Primary Keys
 
-```typescript
-export default class User extends Model {
-  protected static table = "users";
-  protected static keyType = "string" as const;
-  protected static incrementing = false;
+ULIDs are 26-character sortable identifiers — URL-safe, lexicographically ordered by creation time:
 
-  // Attributes
-  id!: string; // UUID primary key
-  name!: string;
-  email!: string;
+```javascript
+class Order extends Model {
+  static table = 'orders';
+  static keyType = 'ulid';
+  static incrementing = false;
 }
 
-// Usage
-const user = await User.create({
-  name: "John Doe",
-  email: "john@example.com",
-});
-// user.id will be a generated UUID
+const order = await Order.create({ total: 49.99 });
+// order.id → "01J3X7KQZB8YTPNMCHW4RSVFGE"
 ```
 
-````
+Use `char(26)` for the column type in migrations.
 
 ### Attribute Casting
 
@@ -4179,6 +4183,68 @@ const users = await User.query().select('id', 'name', 'email').values();
 // [{ id: 1, name: 'John', email: 'john@example.com' }, ...]
 ```
 
+### Vector / Semantic Search (pgvector)
+
+Semantic search matches by **meaning**, not exact keywords. It works by converting text into a list of numbers called an **embedding** using an AI embedding model, storing those numbers in the database, and finding records whose embeddings are mathematically closest to a search query.
+
+**Requires:** PostgreSQL + pgvector extension. An external embedding model (OpenAI, Cohere, Ollama, etc.) is also required — IlanaORM does not include one. Does **not** work with MySQL or SQLite.
+
+```javascript
+// 1. Enable the extension in a migration
+await schema.enableVectorExtension();
+
+// 2. Add a vector column
+await schema.table('posts', table => {
+  table.specificType('embedding', 'vector(1536)'); // dimensions must match your model
+});
+
+// 3. Configure the model
+class Post extends Model {
+  static embeddingColumn = 'embedding';
+  static embeddingProvider = async (text) => {
+    // Must return Promise<number[]> — plug in any embedding API
+    const res = await openai.embeddings.create({ model: 'text-embedding-ada-002', input: text });
+    return res.data[0].embedding;
+  };
+}
+
+// 4. Store embeddings when creating records
+await Post.create({
+  title: 'JavaScript tips',
+  body: '...',
+  embedding: JSON.stringify(await Post.embeddingProvider('JavaScript tips ...')),
+});
+
+// 5. Search — converts text to vector, queries by similarity
+const posts = await Post.search('javascript performance tips', { limit: 5 });
+
+// Or search by a raw vector you already have
+const posts = await Post.nearestTo(myVector, { distance: 'cosine', limit: 10 });
+
+// Each result has a .distance attribute (lower = more similar)
+posts.forEach(p => console.log(p.title, p.distance));
+```
+
+Distance options: `'cosine'` (default, `<=>`), `'l2'` (`<->`), `'inner'` (`<#>`).
+
+### Edge Runtime
+
+Import from `ilana-orm/edge` to skip the Node.js `fs`/`path` auto-loader. Required for Cloudflare Workers, Deno, Bun, and Next.js edge routes:
+
+```javascript
+import { Model, Database } from 'ilana-orm/edge';
+
+// Must configure explicitly — no auto-loading of ilana.config.js
+Database.configure({
+  default: 'pg',
+  connections: {
+    pg: { client: 'pg', connection: { connectionString: process.env.DATABASE_URL } },
+  },
+});
+
+const users = await User.all();
+```
+
 ## TypeScript Support
 
 ### Type-Safe Models
@@ -4231,6 +4297,32 @@ const user = await User.factory().create({
 });
 ```
 
+## Supabase
+
+Supabase is a hosted PostgreSQL platform. IlanaORM works with it out of the box using the `pg` driver — no special setup required.
+
+```javascript
+// ilana.config.js
+const { Database } = require('ilana-orm');
+
+Database.configure({
+  default: 'pg',
+  connections: {
+    pg: {
+      client: 'pg',
+      connection: {
+        connectionString: process.env.DATABASE_URL, // from Supabase dashboard
+        ssl: { rejectUnauthorized: false },         // required for Supabase
+      },
+    },
+  },
+});
+```
+
+All features work including migrations, relations, soft deletes, and vector search (Supabase has pgvector built in).
+
+For serverless or edge deployments with Supabase, use the [connection pooler URL](https://supabase.com/docs/guides/database/connecting-to-postgres) (port `6543`) and the `ilana-orm/edge` entry point for Cloudflare Workers or Next.js edge routes.
+
 ## Performance & Best Practices
 
 ### Query Optimization
@@ -4410,10 +4502,14 @@ User.upsert(data, unique, update); // Upsert records
 User.destroy(ids); // Delete by IDs (soft-delete aware)
 User.truncate(); // Delete all rows in the table
 User.seed(n); // Create n records using the registered factory
+User.prune(); // Delete all records matching static prunable()
 User.withTrashed(); // Include soft deleted
 User.onlyTrashed(); // Only soft deleted
 User.withoutTrashed(); // Exclude soft deleted
 
+// Events
+User.withoutEvents(async () => { ... }); // Run without firing events
+
 // Configuration
 User.getTableName(); // Get table name
 User.getPrimaryKey(); // Get primary key
@@ -4421,6 +4517,7 @@ User.getKeyType(); // Get key type
 User.getIncrementing(); // Get incrementing flag
 User.getConnectionName(); // Get connection name
 User.generateUuid(); // Generate UUID
+User.generateUlid(); // Generate ULID
 
 // Events
 User.creating(callback); // Before creating
@@ -4458,9 +4555,12 @@ user.forceDelete(); // Force delete (ignores softDeletes)
 user.restore(); // Restore soft deleted
 user.fresh(); // Re-fetch from DB and return new instance
 user.is(other); // Check if two instances are the same record
+user.isNot(other); // Inverse of is()
+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
@@ -4642,9 +4742,10 @@ query.upsert(data, uniqueBy, update);
 query.with(...relations);
 query.withConstraints(relation, callback);
 query.withCount(...relations);    // adds relation_count subquery column per model
-query.whereHas(relation, callback); // WHERE EXISTS subquery
-query.doesntHave(relation);                    // WHERE NOT EXISTS subquery
-query.whereDoesntHave(relation, callback);     // WHERE NOT EXISTS with constraint
+query.has(relation, operator?, count?); // WHERE EXISTS, or count-based (e.g. has('posts', '>', 5))
+query.whereHas(relation, callback);    // WHERE EXISTS with constraint subquery
+query.doesntHave(relation);            // WHERE NOT EXISTS subquery
+query.whereDoesntHave(relation, callback); // WHERE NOT EXISTS with constraint
 ```
 
 #### Locking

package/cli/ilana.js

@@ -283,90 +283,20 @@ function getModelTemplate(className, tableName) {
 
   if (isTypeScriptProject()) {
     return `import Model from 'ilana-orm/orm/Model';
-// import { MoneyCast, EncryptedCast } from 'ilana-orm/orm/CustomCasts';
 
 export default class ${className} extends Model {
   protected static table = '${tableName}';
-  protected static timestamps = true;
-  protected static softDeletes = false;
-  
-  // For UUID primary keys, uncomment:
-  // protected static keyType = 'string' as const;
-  // protected static incrementing = false;
-
-  protected fillable: string[] = [];
-  protected hidden: string[] = [];
-  protected appends: string[] = [];
-  protected casts = {
-    // Basic casts
-    // is_active: 'boolean' as const,
-    // metadata: 'json' as const,
-    // tags: 'array' as const,
-    
-    // Custom casts
-    // price: new MoneyCast(),
-    // secret: new EncryptedCast('your-key'),
-  };
-
-  // Define relationships here
-  // example() {
-  //   return this.hasMany(RelatedModel, 'foreign_key');
-  // }
-
-  // Define scopes here
-  // static scopeActive(query: any) {
-  //   query.where('is_active', true);
-  // }
-  
-  // Register for polymorphic relationships
-  // static {
-  //   this.register();
-  // }
+  protected static fillable: string[] = [];
 }
 `;
   }
 
   if (isESModule) {
     return `import Model from 'ilana-orm/orm/Model';
-// import { MoneyCast, EncryptedCast } from 'ilana-orm/orm/CustomCasts';
 
 class ${className} extends Model {
   static table = '${tableName}';
-  static timestamps = true;
-  static softDeletes = false;
-  
-  // For UUID primary keys, uncomment:
-  // static keyType = 'string';
-  // static incrementing = false;
-
-  fillable = [];
-  hidden = [];
-  appends = [];
-  casts = {
-    // Basic casts
-    // is_active: 'boolean',
-    // metadata: 'json',
-    // tags: 'array',
-    
-    // Custom casts
-    // price: new MoneyCast(),
-    // secret: new EncryptedCast('your-key'),
-  };
-
-  // Define relationships here
-  // example() {
-  //   return this.hasMany(RelatedModel, 'foreign_key');
-  // }
-
-  // Define scopes here
-  // static scopeActive(query) {
-  //   query.where('is_active', true);
-  // }
-  
-  // Register for polymorphic relationships
-  // static {
-  //   this.register();
-  // }
+  static fillable = [];
 }
 
 export default ${className};
@@ -374,45 +304,10 @@ export default ${className};
   }
 
   return `const Model = require('ilana-orm/orm/Model');
-// const { MoneyCast, EncryptedCast } = require('ilana-orm/orm/CustomCasts');
 
 class ${className} extends Model {
   static table = '${tableName}';
-  static timestamps = true;
-  static softDeletes = false;
-  
-  // For UUID primary keys, uncomment:
-  // static keyType = 'string';
-  // static incrementing = false;
-
-  fillable = [];
-  hidden = [];
-  appends = [];
-  casts = {
-    // Basic casts
-    // is_active: 'boolean',
-    // metadata: 'json',
-    // tags: 'array',
-    
-    // Custom casts
-    // price: new MoneyCast(),
-    // secret: new EncryptedCast('your-key'),
-  };
-
-  // Define relationships here
-  // example() {
-  //   return this.hasMany(RelatedModel, 'foreign_key');
-  // }
-
-  // Define scopes here
-  // static scopeActive(query) {
-  //   query.where('is_active', true);
-  // }
-  
-  // Register for polymorphic relationships
-  // static {
-  //   this.register();
-  // }
+  static fillable = [];
 }
 
 module.exports = ${className};
@@ -427,11 +322,7 @@ function getPivotModelTemplate(className, tableName) {
 
 export default class ${className} extends Model {
   protected static table = '${tableName}';
-  protected static timestamps = true;
-  
-  protected fillable: string[] = [];
-
-  // Define pivot relationships here
+  protected static fillable: string[] = [];
 }
 `;
   }
@@ -441,11 +332,7 @@ export default class ${className} extends Model {
 
 class ${className} extends Model {
   static table = '${tableName}';
-  static timestamps = true;
-  
-  fillable = [];
-
-  // Define pivot relationships here
+  static fillable = [];
 }
 
 export default ${className};
@@ -456,11 +343,7 @@ export default ${className};
 
 class ${className} extends Model {
   static table = '${tableName}';
-  static timestamps = true;
-  
-  fillable = [];
-
-  // Define pivot relationships here
+  static fillable = [];
 }
 
 module.exports = ${className};
@@ -477,29 +360,27 @@ function generateFactory(className) {
   }
 
   const modelPath = structure.hasSrc ? `../models/${className}.js` : `../../models/${className}.js`;
+  const isESModule = isESModuleProject();
   const template = isTypeScriptProject() ?
     `import { defineFactory } from 'ilana-orm/orm/Factory.js';
 import ${className} from '${modelPath}';
 
 export default defineFactory(${className}, (faker) => ({
-  // Define your factory attributes here
   // name: faker.person.fullName(),
-  // email: faker.internet.email(),
-}))
-.state('example', (faker) => ({
-  // Define state modifications here
+}));
+` : isESModule ?
+    `import { defineFactory } from 'ilana-orm/orm/Factory';
+import ${className} from '${modelPath}';
+
+export default defineFactory(${className}, (faker) => ({
+  // name: faker.person.fullName(),
 }));
 ` :
     `const { defineFactory } = require('ilana-orm/orm/Factory');
 const ${className} = require('${modelPath.replace('.js', '')}');
 
 module.exports = defineFactory(${className}, (faker) => ({
-  // Define your factory attributes here
   // name: faker.person.fullName(),
-  // email: faker.internet.email(),
-}))
-.state('example', (faker) => ({
-  // Define state modifications here
 }));
 `;
 
@@ -517,34 +398,38 @@ function generateSeeder(className) {
   }
 
   const modelPath = structure.hasSrc ? `../models/${className}.js` : `../../models/${className}.js`;
+  const isESModule = isESModuleProject();
   const template = isTypeScriptProject() ?
     `import Seeder from 'ilana-orm/orm/Seeder.js';
+import { factory } from 'ilana-orm/orm/Factory.js';
 import ${className} from '${modelPath}';
 import '../factories/${className}Factory.js';
 
 export default class ${className}Seeder extends Seeder {
   async run(): Promise<void> {
-    console.log('Seeding ${className.toLowerCase()}s...');
-
-    // Create sample data
-    await ${className}.factory().times(10).create();
+    await factory(${className}).times(10).create();
+  }
+}
+` : isESModule ?
+    `import Seeder from 'ilana-orm/orm/Seeder';
+import { factory } from 'ilana-orm/orm/Factory';
+import ${className} from '${modelPath}';
+import '../factories/${className}Factory.js';
 
-    console.log('${className}s seeded successfully');
+export default class ${className}Seeder extends Seeder {
+  async run() {
+    await factory(${className}).times(10).create();
   }
 }
 ` :
     `const Seeder = require('ilana-orm/orm/Seeder');
+const { factory } = require('ilana-orm/orm/Factory');
 const ${className} = require('${modelPath.replace('.js', '')}');
 require('../factories/${className}Factory');
 
 class ${className}Seeder extends Seeder {
   async run() {
-    console.log('Seeding ${className.toLowerCase()}s...');
-
-    // Create sample data
-    await ${className}.factory().times(10).create();
-
-    console.log('${className}s seeded successfully');
+    await factory(${className}).times(10).create();
   }
 }
 
@@ -1590,4 +1475,5 @@ if (require.main === module) {
   main();
 }
 
-module.exports = commands;
+module.exports = commands;
+module.exports._templates = { getModelTemplate, getPivotModelTemplate };

package/database/schema-builder.js

@@ -207,6 +207,10 @@ class SchemaBuilder {
     return Promise.resolve();
   }
 
+  enableVectorExtension() {
+    return this.knex.raw('CREATE EXTENSION IF NOT EXISTS vector');
+  }
+
   createEnum(name, values) {
     if (this.knex.client.config.client === 'pg') {
       return this.knex.raw(`CREATE TYPE ${name} AS ENUM (${values.map(v => `'${v}'`).join(', ')})`);

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.js

@@ -0,0 +1,10 @@
+// Edge runtime entry point — no auto-loading of ilana.config.js.
+// Use this when running in Cloudflare Workers, Deno, Bun, or Next.js edge routes.
+// You must call Database.configure(config) explicitly before using any models.
+//
+// import { Model, Database } from 'ilana-orm/edge';
+// Database.configure({ default: 'pg', connections: { pg: { ... } } });
+
+'use strict';
+global.__ILANA_EDGE__ = true;
+module.exports = require('./index.js');

package/index.edge.mjs

@@ -0,0 +1,38 @@
+// Edge runtime entry point — ESM wrapper.
+// Sets __ILANA_EDGE__ before any model is loaded so the auto-loader is skipped.
+import { createRequire } from 'module';
+const require = createRequire(import.meta.url);
+
+globalThis.__ILANA_EDGE__ = true;
+const exports = require('./index.js');
+
+export const {
+  Model,
+  QueryBuilder,
+  Collection,
+  Database,
+  DB,
+  SchemaBuilder,
+  MigrationRunner,
+  Seeder,
+  Factory,
+  defineFactory,
+  ModelNotFoundException,
+  MassAssignmentException,
+  F,
+  HasOne,
+  HasMany,
+  BelongsTo,
+  BelongsToMany,
+  HasManyThrough,
+  MorphTo,
+  MorphOne,
+  MorphMany,
+  MoneyCast,
+  EncryptedCast,
+  JsonCast,
+  ArrayCast,
+  DateCast,
+} = exports;
+
+export default exports.Model;

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);
       }