ilana-orm 1.0.17 → 1.0.19

package/README.md

@@ -24,6 +24,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)
@@ -447,6 +448,9 @@ module.exports = {
     extension: "ts",
   },
 
+  // SQL query logging — logs every query with bound values and execution time
+  logging: process.env.NODE_ENV === "development",
+
   // Debugging
   debug: process.env.NODE_ENV === "development",
 
@@ -790,47 +794,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
 
@@ -1518,11 +1508,11 @@ const users = await User.all();
 
 // Find by primary key
 const user = await User.find(1);
-const user = await User.findOrFail(1); // Throws if not found
+const user = await User.findOrFail(1); // Throws ModelNotFoundException if not found
 
 // First record
 const user = await User.first();
-const user = await User.firstOrFail(); // Throws if not found
+const user = await User.firstOrFail(); // Throws ModelNotFoundException if not found
 
 // Create or find
 const user = await User.firstOrCreate(
@@ -1545,11 +1535,11 @@ const users = await User.all();
 
 // Find by primary key
 const user = await User.find(1);
-const user = await User.findOrFail(1); // Throws if not found
+const user = await User.findOrFail(1); // Throws ModelNotFoundException if not found
 
 // First record
 const user = await User.first();
-const user = await User.firstOrFail(); // Throws if not found
+const user = await User.firstOrFail(); // Throws ModelNotFoundException if not found
 
 // Create or find
 const user = await User.firstOrCreate(
@@ -4022,6 +4012,222 @@ const users = await User.query().on("reporting_db").get();
 
 ````
 
+## Debugging
+
+### Query Logging
+
+Enable SQL query logging in `ilana.config.js`:
+
+```javascript
+// ilana.config.js
+module.exports = {
+  default: 'mysql',
+  logging: process.env.NODE_ENV === 'development', // logs all queries in dev
+  connections: { ... }
+};
+```
+
+Or toggle programmatically:
+
+```javascript
+import { Database } from 'ilana-orm';
+
+Database.enableLogging();  // turn on
+Database.disableLogging(); // turn off
+```
+
+Output:
+```
+[IlanaORM] select * from "users" where "role" = 'admin' order by "created_at" desc limit 10 — 3ms
+[IlanaORM] select * from "posts" where "user_id" in (1, 2, 3) — 1ms
+```
+
+Inspect a query without executing it:
+
+```javascript
+const sql = User.query().where('role', 'admin').toSql();
+console.log(sql); // select * from "users" where "role" = 'admin'
+```
+
+### ModelNotFoundException
+
+`findOrFail()`, `firstOrFail()`, and `sole()` throw a `ModelNotFoundException` — a named error class you can catch specifically:
+
+```javascript
+import { ModelNotFoundException } from 'ilana-orm';
+
+// In a route
+app.get('/users/:id', async (req, res) => {
+  const user = await User.findOrFail(req.params.id);
+  res.json(user);
+});
+
+// Global Express error handler
+app.use((err, req, res, next) => {
+  if (err instanceof ModelNotFoundException) {
+    return res.status(404).json({ message: err.message });
+    // "User with id 99 not found"
+  }
+  res.status(500).json({ message: 'Server error' });
+});
+```
+
+Properties: `err.message`, `err.model` (class name), `err.id` (the id passed to `findOrFail`).
+
+Call `err.toResponse()` to get a plain `{ status: 404, message }` object suitable for any HTTP framework:
+
+```javascript
+app.get('/users/:id', async (req, res) => {
+  try {
+    return res.json(await User.findOrFail(req.params.id));
+  } catch (err) {
+    if (err instanceof ModelNotFoundException) {
+      const { status, message } = err.toResponse();
+      return res.status(status).json({ message });
+    }
+    throw err;
+  }
+});
+```
+
+### Column Expressions with `F()`
+
+Reference a column's current value in an update — no raw SQL, no race conditions, no need to fetch first:
+
+```javascript
+import { F } from 'ilana-orm';
+
+await Post.query().where('id', postId).update({ views: F('views').plus(1) });
+await Product.query().where('id', id).update({ stock: F('stock').minus(quantity) });
+```
+
+Available: `.plus(n)`, `.minus(n)`, `.times(n)`, `.divide(n)`.
+
+### Bulk Restore
+
+Restore many soft-deleted records at once via the query builder:
+
+```javascript
+await User.query().onlyTrashed().where('role', 'admin').restore();
+// UPDATE users SET deleted_at = NULL WHERE role = 'admin' AND deleted_at IS NOT NULL
+```
+
+### Enum Helpers
+
+Define possible values for enum columns and get auto-generated `isX()` / `makeX()` helpers on every instance:
+
+```javascript
+class User extends Model {
+  static enums = {
+    role: ['user', 'moderator', 'admin'],
+    status: ['active', 'suspended'],
+  };
+}
+
+const user = await User.find(1);
+user.isAdmin();        // true / false
+await user.makeAdmin(); // sets role = 'admin' and saves
+user.isSuspended();    // true / false
+```
+
+### Strict Loading
+
+Throw an error when an unloaded relation is accessed — catches N+1 problems at development time:
+
+```javascript
+class Post extends Model {
+  static strictLoading = true;
+}
+
+const posts = await Post.all();           // no .with('comments')
+posts[0].relations.comments;             // throws: 'comments' was not eager loaded on Post
+```
+
+### Touch
+
+Automatically update a parent's `updated_at` whenever the child saves:
+
+```javascript
+class Comment extends Model {
+  static touches = ['post'];
+
+  post() { return this.belongsTo('Post', 'post_id'); }
+}
+
+await comment.save(); // also bumps posts SET updated_at = NOW() WHERE id = comment.post_id
+```
+
+### Plain Object Results with `values()`
+
+Return raw plain objects instead of model instances — faster for read-heavy endpoints where you don't need model methods:
+
+```javascript
+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
@@ -4074,6 +4280,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
@@ -4249,12 +4481,18 @@ User.updateOrCreate(search, update); // Update or create
 User.firstOrNew(search, create); // Find or new instance
 User.upsert(data, unique, update); // Upsert records
 
-// Deletion methods
-User.destroy(ids); // Delete by IDs
+// Deletion & seeding
+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
@@ -4262,6 +4500,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
@@ -4297,6 +4536,10 @@ user.update(attributes); // Update model
 user.delete(); // Delete model
 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)
@@ -4435,6 +4678,18 @@ query.findOrFail(id); // Find or throw
 query.pluck(column); // Get column values
 query.exists(); // Check existence
 query.doesntExist(); // Check non-existence
+query.sole(); // Get exactly one result — throws if zero or more than one
+query.tap(callback); // Run a callback for debugging without breaking the chain
+query.values(); // Return plain objects instead of model instances
+```
+
+#### Soft Deletes (QueryBuilder)
+
+```javascript
+query.withTrashed();   // include soft-deleted records
+query.onlyTrashed();   // only soft-deleted records
+query.withoutTrashed(); // exclude soft-deleted (default)
+query.restore();       // bulk-restore matched soft-deleted records
 ```
 
 #### Pagination
@@ -4469,9 +4724,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