ilana-orm 1.0.17 → 1.0.18

package/README.md

@@ -447,6 +447,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",
 
@@ -1518,11 +1521,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 +1548,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 +4025,160 @@ 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' }, ...]
+```
+
 ## TypeScript Support
 
 ### Type-Safe Models
@@ -4249,8 +4406,10 @@ 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.withTrashed(); // Include soft deleted
 User.onlyTrashed(); // Only soft deleted
 User.withoutTrashed(); // Exclude soft deleted
@@ -4297,6 +4456,8 @@ 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
 
 // Attributes
 user.fill(attributes); // Mass assign (respects fillable/guarded)
@@ -4435,6 +4596,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

package/cli/ilana.js

@@ -127,7 +127,10 @@ import Database from 'ilana-orm/database/connection.js';
 const config = {
   default: process.env.DB_CONNECTION || 'mysql',
   timezone: process.env.DB_TIMEZONE || 'UTC',
-  
+
+  // Set to true (or use process.env.NODE_ENV === 'development') to log all SQL queries
+  logging: false,
+
   connections: {
     sqlite: {
       client: 'sqlite3',
@@ -136,7 +139,7 @@ const config = {
       },
       useNullAsDefault: true
     },
-    
+
     mysql: {
       client: 'mysql2',
       connection: {
@@ -148,7 +151,7 @@ const config = {
         timezone: process.env.DB_TIMEZONE || 'UTC'
       }
     },
-    
+
     postgres: {
       client: 'pg',
       connection: {
@@ -160,12 +163,12 @@ const config = {
       }
     }
   },
-  
+
   migrations: {
     directory: './${structure.databaseDir}/migrations',
     tableName: 'migrations'
   },
-  
+
   seeds: {
     directory: './${structure.databaseDir}/seeds'
   }
@@ -186,7 +189,10 @@ const Database = require('ilana-orm/database/connection');
 const config = {
   default: process.env.DB_CONNECTION || 'mysql',
   timezone: process.env.DB_TIMEZONE || 'UTC',
-  
+
+  // Set to true (or use process.env.NODE_ENV === 'development') to log all SQL queries
+  logging: false,
+
   connections: {
     sqlite: {
       client: 'sqlite3',
@@ -195,7 +201,7 @@ const config = {
       },
       useNullAsDefault: true
     },
-    
+
     mysql: {
       client: 'mysql2',
       connection: {
@@ -207,7 +213,7 @@ const config = {
         timezone: process.env.DB_TIMEZONE || 'UTC'
       }
     },
-    
+
     postgres: {
       client: 'pg',
       connection: {
@@ -219,12 +225,12 @@ const config = {
       }
     }
   },
-  
+
   migrations: {
     directory: './${structure.databaseDir}/migrations',
     tableName: 'migrations'
   },
-  
+
   seeds: {
     directory: './${structure.databaseDir}/seeds'
   }
@@ -823,13 +829,13 @@ function parseMigrationsForTable(tableName, migrationsDir) {
 
       // Match column definitions: table.string('col'), table.integer('col').nullable(), etc.
       const colRegex = new RegExp(
-        `${alias}\\.(\\w+)\\s*\\(\\s*['"]([^'"]+)['"](?:[^)]*)?\\)([^;\\n]*)`,
+        `${alias}\\.(\\w+)\\s*\\(\\s*['"]([^'"]+)['"]([^)]*)\\)([^;\\n]*)`,
         'g'
       );
 
       let colMatch;
       while ((colMatch = colRegex.exec(block)) !== null) {
-        const [, method, colName, rest] = colMatch;
+        const [, method, colName, args, rest] = colMatch;
         const knexDef = KNEX_COLUMN_MAP[method];
         if (!knexDef) continue;
 
@@ -837,7 +843,17 @@ function parseMigrationsForTable(tableName, migrationsDir) {
         const isNotNullable = /\.notNullable\(\)/.test(rest);
         const nullable = isNullable ? true : isNotNullable ? false : knexDef.nullable;
 
-        columns[colName] = { type: knexDef.type, nullable };
+        // For enum columns, extract the values array and build a union type
+        let tsType = knexDef.type;
+        if (method === 'enum') {
+          const valuesMatch = args.match(/\[([^\]]+)\]/);
+          if (valuesMatch) {
+            const values = [...valuesMatch[1].matchAll(/['"]([^'"]+)['"]/g)].map(m => `'${m[1]}'`);
+            if (values.length) tsType = values.join(' | ');
+          }
+        }
+
+        columns[colName] = { type: tsType, nullable };
       }
     }
   }

package/database/connection.d.ts

@@ -2,6 +2,7 @@ import { Knex } from 'knex';
 
 export interface DatabaseConfig {
   default: string;
+  logging?: boolean;
   connections: {
     [name: string]: Knex.Config;
   };
@@ -27,6 +28,8 @@ export default class Database {
   private static _currentTransaction: Knex.Transaction | null;
 
   static configure(config: DatabaseConfig): void;
+  static enableLogging(): void;
+  static disableLogging(): void;
   static connection(name?: string): Knex;
   static getDefaultConnection(): string;
   static hasConnection(name: string): boolean;

package/database/connection.js

@@ -3,11 +3,33 @@ const knex = require('knex');
 class Database {
   static connections = new Map();
   static _currentTransaction = null;
+  static _logging = false;
+
+  static enableLogging() {
+    this._logging = true;
+  }
+
+  static disableLogging() {
+    this._logging = false;
+  }
+
+  static _log(sql, bindings, ms) {
+    if (!this._logging) return;
+    const bound = sql.replace(/\?/g, () => {
+      const val = bindings?.shift();
+      if (val === null || val === undefined) return 'NULL';
+      if (typeof val === 'string') return `'${val}'`;
+      return val;
+    });
+    const time = ms !== undefined ? ` \x1b[90m— ${ms}ms\x1b[0m` : '';
+    console.log(`\x1b[36m[IlanaORM]\x1b[0m ${bound}${time}`);
+  }
 
   static configure(config) {
     this.config = config;
     this.defaultConnection = config.default;
-    
+    if (config.logging) this._logging = true;
+
     // Initialize all configured connections
     for (const [name, connConfig] of Object.entries(config.connections)) {
       try {
@@ -21,6 +43,23 @@ class Database {
             directory: './seeds'
           }
         });
+
+        // Attach query logger
+        connection.on('query', (query) => {
+          this._queryStart = Date.now();
+          this._pendingQuery = query.sql;
+          this._pendingBindings = [...(query.bindings || [])];
+        });
+        connection.on('query-response', (response, query) => {
+          const ms = Date.now() - (this._queryStart || Date.now());
+          this._log(query.sql, [...(query.bindings || [])], ms);
+        });
+        connection.on('query-error', (error, query) => {
+          if (this._logging) {
+            console.error(`\x1b[36m[IlanaORM]\x1b[0m \x1b[31mERROR\x1b[0m ${query.sql}`);
+          }
+        });
+
         this.connections.set(name, connection);
       } catch (error) {
         if (error.code === 'MODULE_NOT_FOUND' && error.message.includes(connConfig.client)) {

package/ilana.config.js

@@ -1,4 +1,4 @@
-const Database = require('ilana/database/connection').default;
+const Database = require('./database/connection');
 
 const config = {
   default: 'sqlite',

package/index.d.ts

@@ -5,5 +5,22 @@ export { default as Database } from './database/connection';
 export * from './orm/Relation';
 export * from './orm/CustomCasts';
 
+export declare class FExpression {
+  constructor(column: string);
+  plus(n: number): any;
+  minus(n: number): any;
+  times(n: number): any;
+  divide(n: number): any;
+}
+export declare function F(column: string): FExpression;
+
+export declare class ModelNotFoundException extends Error {
+  name: 'ModelNotFoundException';
+  model: string;
+  id?: any;
+  constructor(model: string, id?: any);
+  toResponse(): { status: 404; message: string };
+}
+
 // Default export
 export { default } from './orm/Model';

package/index.js

@@ -10,6 +10,8 @@ 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 { F } = require('./orm/F');
 
 module.exports = {
   Model,
@@ -22,11 +24,13 @@ module.exports = {
   Seeder,
   Factory: Factory.Factory,
   defineFactory: Factory.defineFactory,
-  
+  ModelNotFoundException,
+  F,
+
   // Relationships
   MorphOne: Relation.MorphOne,
   ...Relation,
-  
+
   // Custom Casts
   ...CustomCasts
 };

package/index.mjs

@@ -15,6 +15,8 @@ export const {
   Seeder,
   Factory,
   defineFactory,
+  ModelNotFoundException,
+  F,
   Relation,
   HasOne,
   HasMany,

package/jest.config.js

@@ -0,0 +1,4 @@
+module.exports = {
+  testEnvironment: 'node',
+  setupFiles: ['<rootDir>/tests/setup.js'],
+};

package/orm/Errors.js

@@ -0,0 +1,18 @@
+class ModelNotFoundException extends Error {
+  constructor(model, id) {
+    const message = id !== undefined
+      ? `${model} with id ${id} not found`
+      : `${model} not found`;
+    super(message);
+    this.name = 'ModelNotFoundException';
+    this.model = model;
+    this.id = id;
+    if (Error.captureStackTrace) Error.captureStackTrace(this, ModelNotFoundException);
+  }
+
+  toResponse() {
+    return { status: 404, message: this.message };
+  }
+}
+
+module.exports = { ModelNotFoundException };

package/orm/F.js

@@ -0,0 +1,22 @@
+const Database = require('../database/connection');
+
+class FExpression {
+  constructor(column) {
+    this.column = column;
+  }
+
+  _raw(op, n) {
+    return Database.raw(`?? ${op} ?`, [this.column, n]);
+  }
+
+  plus(n)   { return this._raw('+', n); }
+  minus(n)  { return this._raw('-', n); }
+  times(n)  { return this._raw('*', n); }
+  divide(n) { return this._raw('/', n); }
+}
+
+function F(column) {
+  return new FExpression(column);
+}
+
+module.exports = { F, FExpression };

package/orm/Factory.js

@@ -14,6 +14,9 @@ class Factory {
     this.count = 1;
     this.currentStates = [];
     this.relationships = new Map();
+    this._has = new Map();
+    this._for = new Map();
+    this._hasAttached = new Map();
     this._sequenceCount = 0;
     this.sequences = new Map();
   }
@@ -57,23 +60,30 @@ class Factory {
     return this;
   }
 
-  for(relation, factory) {
-    this.relationships.set(relation, factory);
+  for(relation, relFactory) {
+    this._for.set(relation, relFactory);
     return this;
   }
 
-  has(factory, relation) {
-    if (relation) {
-      this.relationships.set(relation, factory);
-    }
+  has(relFactory, relation) {
+    this._has.set(relation, relFactory);
     return this;
   }
 
-  hasAttached(factory, relation) {
-    this.relationships.set(relation, factory);
+  hasAttached(relFactory, relation) {
+    this._hasAttached.set(relation, relFactory);
     return this;
   }
 
+  _getRelation(relationName) {
+    try {
+      const dummy = new this.model({});
+      return typeof dummy[relationName] === 'function' ? dummy[relationName]() : null;
+    } catch (_) {
+      return null;
+    }
+  }
+
   sequence() {
     return ++this._sequenceCount;
   }
@@ -173,16 +183,40 @@ class Factory {
   }
 
   async createOne(attributes = {}) {
-    const model = await this.makeOne(attributes);
-    
-    // Run beforeCreating callbacks
+    // Handle 'for' (belongsTo) — create parent first, inject FK into this model
+    const parentAttrs = {};
+    for (const [relationName, relFactory] of this._for) {
+      const parent = await relFactory.createOne({});
+      const rel = this._getRelation(relationName);
+      if (rel && rel.foreignKey) parentAttrs[rel.foreignKey] = parent.getKey();
+    }
+
+    const model = await this.makeOne({ ...parentAttrs, ...attributes });
+
     for (const callback of this._beforeCreatingCallbacks) {
       await callback(model);
     }
 
     await model.save();
 
-    // Run afterCreating callbacks
+    // Handle 'has' (hasMany) — create children with FK pointing to this model
+    for (const [relationName, relFactory] of this._has) {
+      const rel = this._getRelation(relationName);
+      if (rel && rel.foreignKey) {
+        await relFactory.create({ [rel.foreignKey]: model.getKey() });
+      }
+    }
+
+    // Handle 'hasAttached' (belongsToMany) — create and attach via pivot
+    for (const [relationName, relFactory] of this._hasAttached) {
+      const related = await relFactory.create({});
+      const relatedArr = Array.isArray(related) ? related : [related];
+      const rel = this._getRelation(relationName);
+      if (rel && typeof rel.attach === 'function') {
+        for (const r of relatedArr) await rel.attach(r.getKey());
+      }
+    }
+
     for (const callback of this._afterCreatingCallbacks) {
       await callback(model);
     }
@@ -354,6 +388,9 @@ if (typeof Model !== 'undefined') {
       newFactory.states = new Map(existingFactory.states);
       newFactory._afterCreatingCallbacks = [...existingFactory._afterCreatingCallbacks];
       newFactory._beforeCreatingCallbacks = [...existingFactory._beforeCreatingCallbacks];
+      newFactory._has = new Map(existingFactory._has);
+      newFactory._for = new Map(existingFactory._for);
+      newFactory._hasAttached = new Map(existingFactory._hasAttached);
       return newFactory;
     }
     throw new Error(`No factory defined for model: ${this.name}`);

package/orm/Model.d.ts

@@ -50,6 +50,9 @@ export default class Model<TAttributes extends ModelAttributes = ModelAttributes
   protected static globalScopes: Map<string, (query: QueryBuilder) => void>;
   protected static appends: string[];
   protected static timezone: string;
+  static strictLoading: boolean;
+  static touches: string[];
+  static enums: { [column: string]: string[] };
 
   // Instance properties
   attributes: ModelAttributes;
@@ -90,6 +93,8 @@ export default class Model<TAttributes extends ModelAttributes = ModelAttributes
   static generateUuid(): string;
   static insert(data: ModelAttributes | ModelAttributes[]): Promise<any>;
   static destroy(ids: any | any[]): Promise<number>;
+  static truncate(): Promise<void>;
+  static seed(count?: number): Promise<any[]>;
   static firstOrCreate(attributes: ModelAttributes, values?: ModelAttributes): Promise<Model>;
   static firstOrNew(attributes: ModelAttributes, values?: ModelAttributes): Promise<Model>;
   static updateOrCreate(attributes: ModelAttributes, values?: ModelAttributes): Promise<Model>;
@@ -143,10 +148,14 @@ export default class Model<TAttributes extends ModelAttributes = ModelAttributes
   getDirty(): ModelAttributes;
   delete(): Promise<boolean>;
   restore(): Promise<boolean>;
+  increment(column: string, amount?: number): Promise<this>;
+  decrement(column: string, amount?: number): Promise<this>;
   trashed(): boolean;
   only(keys: string[]): ModelAttributes;
   except(keys: string[]): ModelAttributes;
   forceDelete(): Promise<boolean>;
+  fresh(): Promise<this | null>;
+  is(other: Model): boolean;
   toJSON(): any;
 
   // Relationships

package/orm/Model.js

@@ -35,6 +35,9 @@ class Model {
   static globalScopes = new Map();
   static appends = [];
   static timezone = 'UTC';
+  static strictLoading = false;
+  static touches = [];
+  static enums = {};
 
   // --- Instance props ---
   attributes = {};
@@ -62,6 +65,25 @@ class Model {
       ? this.appends
       : this.constructor.appends;
 
+    // Wrap relations in a Proxy for strict loading enforcement
+    const modelClass = this.constructor;
+    this.relations = new Proxy({}, {
+      get(target, key) {
+        if (typeof key !== 'string') return target[key];
+        if (modelClass.strictLoading && !(key in target)) {
+          throw new Error(
+            `Strict loading violation: '${key}' was not eager loaded on ${modelClass.name}. ` +
+            `Use .with('${key}') in your query.`
+          );
+        }
+        return target[key];
+      },
+      set(target, key, value) { target[key] = value; return true; },
+      has(target, key) { return key in target; },
+      ownKeys(target) { return Object.keys(target); },
+      getOwnPropertyDescriptor(target, key) { return Object.getOwnPropertyDescriptor(target, key); },
+    });
+
     // defer attribute setting
     if (attrs && Object.keys(attrs).length) this._deferred = attrs;
 
@@ -79,6 +101,7 @@ class Model {
     this._deferred = null;
     // Recreate getters after initialization
     this._createAttributeGetters();
+    this._generateEnumHelpers();
   }
 
   _createAttributeGetters() {
@@ -106,6 +129,26 @@ class Model {
     }
   }
 
+  _generateEnumHelpers() {
+    const enums = this.constructor.enums || {};
+    for (const [column, values] of Object.entries(enums)) {
+      for (const value of values) {
+        const pascal = value.charAt(0).toUpperCase() + value.slice(1);
+        const isMethod = `is${pascal}`;
+        const makeMethod = `make${pascal}`;
+        if (!this[isMethod]) {
+          this[isMethod] = () => this.getAttribute(column) === value;
+        }
+        if (!this[makeMethod]) {
+          this[makeMethod] = async () => {
+            this.setAttribute(column, value);
+            return this.save();
+          };
+        }
+      }
+    }
+  }
+
   _toPascalCase(key) {
     return key.replace(/(^|_)([a-z])/g, (_, __, c) => c.toUpperCase());
   }
@@ -210,6 +253,11 @@ class Model {
   }
 
   static async insert(data) { return this.query().insert(data); }
+  static async truncate() { return this.query().toKnex().truncate(); }
+  static async seed(count = 1) {
+    const { factory } = require('./Factory');
+    return factory(this).times(count).create();
+  }
   static async destroy(ids) {
     const idList = Array.isArray(ids) ? ids : [ids];
     if (this.softDeletes) {
@@ -525,9 +573,27 @@ class Model {
       this.syncOriginal();
     }
 
+    await this._touchRelations();
+
     return true;
   }
 
+  async _touchRelations() {
+    const touches = this.constructor.touches || [];
+    for (const relName of touches) {
+      if (typeof this[relName] !== 'function') continue;
+      const rel = this[relName]();
+      if (!rel || rel.constructor.name !== 'BelongsTo') continue;
+      const parentClass = rel.getRelatedClass();
+      const parentId = this.getAttribute(rel.foreignKey);
+      if (!parentId) continue;
+      const col = parentClass.updatedAt || 'updated_at';
+      await parentClass.query()
+        .where(parentClass.primaryKey || 'id', parentId)
+        .update({ [col]: new Date() });
+    }
+  }
+
   async update(attributes = {}) {
     this.fill(attributes);
     return await this.save();
@@ -604,6 +670,20 @@ class Model {
     return result;
   }
 
+  async increment(column, amount = 1) {
+    await this.constructor.query().where(this.constructor.primaryKey, this.getKey()).increment(column, amount);
+    this.setAttribute(column, (this.getAttribute(column) || 0) + amount);
+    this.syncOriginal();
+    return this;
+  }
+
+  async decrement(column, amount = 1) {
+    await this.constructor.query().where(this.constructor.primaryKey, this.getKey()).decrement(column, amount);
+    this.setAttribute(column, (this.getAttribute(column) || 0) - amount);
+    this.syncOriginal();
+    return this;
+  }
+
   async forceDelete() {
     if (!this.exists) return false;
 
@@ -614,6 +694,16 @@ class Model {
     return true;
   }
 
+  async fresh() {
+    if (!this.exists) return null;
+    return this.constructor.find(this.getKey());
+  }
+
+  is(other) {
+    if (!other || !(other instanceof this.constructor)) return false;
+    return this.getKey() === other.getKey();
+  }
+
   // JSON serialization
   toJSON() {
     this._initialize();

package/orm/QueryBuilder.d.ts

@@ -135,6 +135,8 @@ export default class QueryBuilder {
   pluck(column: string): Promise<any[]>;
   exists(): Promise<boolean>;
   doesntExist(): Promise<boolean>;
+  sole(): Promise<Model>;
+  tap(callback: (query: this) => void): this;
 
   // Pagination
   paginate(page?: number, perPage?: number): Promise<PaginationResult<Model>>;
@@ -150,6 +152,8 @@ export default class QueryBuilder {
   insert(data: any | any[]): Promise<any>;
   insertGetId(data: any): Promise<any>;
   update(data: any): Promise<number>;
+  increment(column: string, amount?: number): Promise<number>;
+  decrement(column: string, amount?: number): Promise<number>;
   delete(): Promise<number>;
   upsert(data: any[], uniqueBy: string[], update?: string[]): Promise<any>;
 
@@ -167,6 +171,10 @@ export default class QueryBuilder {
   withTrashed(): this;
   onlyTrashed(): this;
   withoutTrashed(): this;
+  restore(): Promise<number>;
+
+  // Plain object result (no model hydration)
+  values(): Promise<any[]>;
 
   // Debug
   toSql(): string;

package/orm/QueryBuilder.js

@@ -1,6 +1,7 @@
 const Database = require('../database/connection');
 const Collection = require('./Collection');
 const ModelRegistry = require('./ModelRegistry');
+const { ModelNotFoundException } = require('./Errors');
 
 class QueryBuilder {
   constructor(tableName, modelClass, connectionName) {
@@ -609,13 +610,13 @@ class QueryBuilder {
 
   async findOrFail(id) {
     const result = await this.find(id);
-    if (!result) throw new Error(`Model not found with id: ${id}`);
+    if (!result) throw new ModelNotFoundException(this.modelClass?.name || 'Model', id);
     return result;
   }
 
   async firstOrFail() {
     const result = await this.first();
-    if (!result) throw new Error('No records found.');
+    if (!result) throw new ModelNotFoundException(this.modelClass?.name || 'Model');
     return result;
   }
 
@@ -623,6 +624,18 @@ class QueryBuilder {
     return !(await this.exists());
   }
 
+  async sole() {
+    const results = await this._softQuery().limit(2);
+    if (results.length === 0) throw new ModelNotFoundException(this.modelClass?.name || 'Model');
+    if (results.length > 1) throw new Error(`${this.modelClass?.name || 'Model'}: sole() found more than one result.`);
+    return this.modelClass ? new this.modelClass(results[0]) : results[0];
+  }
+
+  tap(callback) {
+    callback(this);
+    return this;
+  }
+
   async pluck(column) {
     return await this._softQuery().pluck(column);
   }
@@ -758,6 +771,14 @@ class QueryBuilder {
     return this.query.update(data);
   }
 
+  async increment(column, amount = 1) {
+    return this.query.increment(column, amount);
+  }
+
+  async decrement(column, amount = 1) {
+    return this.query.decrement(column, amount);
+  }
+
   async delete() {
     return this.query.del();
   }
@@ -1033,6 +1054,18 @@ class QueryBuilder {
     return this;
   }
 
+  async restore() {
+    if (!this.modelClass || !this.modelClass.softDeletes) {
+      throw new Error(`restore() requires softDeletes to be enabled on ${this.modelClass?.name || 'the model'}`);
+    }
+    const col = this.modelClass.deletedAt || 'deleted_at';
+    return this._softQuery().update({ [col]: null });
+  }
+
+  async values() {
+    return this._softQuery();
+  }
+
   // Debug
   toSql() {
     return this.query.toSQL().sql;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ilana-orm",
-  "version": "1.0.17",
+  "version": "1.0.18",
   "description": "A fully-featured, Eloquent-style ORM for Node.js with TypeScript support",
   "main": "index.js",
   "types": "index.d.ts",