outlet-orm 9.0.2 → 11.1.0

package/README.md

@@ -7,6 +7,72 @@ A JavaScript ORM inspired by Laravel Eloquent for Node.js with support for MySQL
 
 📚 **[Complete documentation available in `/docs`](./docs/INDEX.md)**
 
+## Table of Contents
+
+- [✅ Prerequisites and compatibility](#prerequisites-and-compatibility)
+- [🚀 Installation](#installation)
+  - [Install the database driver](#install-the-database-driver)
+- [📁 Recommended Project Structure](#recommended-project-structure)
+  - [🏗️ Architecture Flow](#architecture-flow)
+  - [📋 Role of each layer](#role-of-each-layer)
+  - [✅ Benefits of this architecture](#benefits-of-this-architecture)
+  - [📝 Example workflow](#example-workflow)
+- [✨ Key features](#key-features)
+- [⚡ Quick Start](#quick-start)
+  - [Project Initialisation](#project-initialisation)
+  - [🌱 Quick Seeding](#quick-seeding)
+- [📖 Usage](#usage)
+  - [Connection configuration](#connection-configuration)
+  - [Importation](#importation)
+  - [Define a model](#define-a-model)
+  - [CRUD operations](#crud-operations)
+  - [Query Builder](#query-builder)
+  - [Relationship filters](#relationship-filters)
+- [🔗 Relations](#relations)
+  - [One to One (hasOne)](#one-to-one-hasone)
+  - [One to Many (hasMany)](#one-to-many-hasmany)
+  - [Belongs To (belongsTo)](#belongs-to-belongsto)
+  - [Many to Many (belongsToMany)](#many-to-many-belongstomany)
+  - [Has Many Through (hasManyThrough)](#has-many-through-hasmanythrough)
+  - [Has One Through (hasOneThrough)](#has-one-through-hasonethrough)
+  - [Polymorphic relationships](#polymorphic-relationships)
+  - [Eager Loading](#eager-loading)
+- [🎭 Attributs](#attributs)
+  - [Casts](#casts)
+  - [Hidden attributes](#hidden-attributes)
+  - [Timestamps](#timestamps)
+- [🔄 Transactions](#transactions)
+- [🗑️ Soft Deletes](#soft-deletes)
+- [🔬 Scopes](#scopes)
+  - [Scopes Globaux](#scopes-globaux)
+- [📣 Events / Hooks](#events-hooks)
+- [✅ Validation](#validation)
+  - [Available rules](#available-rules)
+- [📊 Query Logging](#query-logging)
+- [📝 API Reference](#api-reference)
+  - [DatabaseConnection](#databaseconnection)
+  - [Model (static methods)](#model-static-methods)
+  - [Model (instance methods)](#model-instance-methods)
+  - [QueryBuilder](#querybuilder)
+- [🛠️ CLI tools](#cli-tools)
+  - [outlet-init](#outlet-init)
+  - [outlet-migrate](#outlet-migrate)
+  - [outlet-convert](#outlet-convert)
+- [🤖 AI Integration](#ai-integration)
+  - [AI — Multi-Provider LLM Abstraction](#ai-multi-provider-llm-abstraction)
+  - [AI Query Builder — Natural Language → SQL](#ai-query-builder-natural-language-sql)
+  - [AI Seeder — Realistic Data Generation](#ai-seeder-realistic-data-generation)
+  - [AI Query Optimizer](#ai-query-optimizer)
+  - [MCP Server — AI Agent Integration](#mcp-server-ai-agent-integration)
+- [📚 Documentation](#documentation)
+- [📘 TypeScript Support](#typescript-support)
+  - [Typed models](#typed-models)
+  - [Migrations typedes](#migrations-typedes)
+- [🤝 Contributions](#contributions)
+- [📄 Licence](#licence)
+
+---
+
 ## ✅ Prerequisites and compatibility
 
 - Node.js >= 18 (recommended/required)
@@ -197,7 +263,7 @@ async store(req, res) {
 - **Raw queries**: `executeRawQuery()` and `execute()` (native driver results)
 - **Complete Migrations** (create/alter/drop, index, foreign keys, batch tracking)
 - **Database Backup** (v6.0.0): full/partial/journal backups, recurring scheduler, AES-256-GCM encryption, TCP daemon + remote client, automatic restore
-- **🤖 AiBridge** (v8.0.0): Multi-provider LLM abstraction — chat, stream, embeddings, images, TTS, STT with 9+ providers
+- **🤖 AI** (v8.0.0): Multi-provider LLM abstraction — chat, stream, embeddings, images, TTS, STT with 9+ providers
 - **🤖 AI Query Builder** (v8.0.0): Natural language → SQL with schema introspection
 - **🤖 AI Seeder** (v8.0.0): LLM-powered realistic, domain-specific data generation
 - **🤖 AI Query Optimizer** (v8.0.0): SQL analysis, optimization, and index recommendations
@@ -208,6 +274,17 @@ async store(req, res) {
 - **`.env` configuration** (loaded automatically)
 - **Multi-database**: MySQL, PostgreSQL, and SQLite
 - **Complete TypeScript types** with Generic Model and typed Schema Builder (v4.0.0+)
+- **🆕 Property-style attribute access** (v11.0.0): `user.name` instead of `user.getAttribute('name')`
+- **🆕 Computed Appends** (v11.0.0): `static appends` for virtual attributes auto-included in `toJSON()`
+- **🆕 Model Utility Methods** (v11.0.0): `fresh()`, `refresh()`, `replicate()`, `is()` / `isNot()`, `only()` / `except()`
+- **🆕 Instance-Level Visibility** (v11.0.0): `makeVisible()` / `makeHidden()` per-instance control
+- **🆕 Change Tracking** (v11.0.0): `wasChanged()` / `getChanges()` after `save()`
+- **🆕 Batch Processing** (v11.0.0): `chunk(size, callback)` for memory-efficient iteration
+- **🆕 Conditional Queries** (v11.0.0): `when(condition, callback)` and `tap(callback)`
+- **🆕 Query Debugging** (v11.0.0): `dd()` dumps SQL + bindings to console and throws
+- **🆕 Fluent Local Scopes** (v11.0.0): `static scopeActive(query)` → `User.query().active()`
+- **🆕 Relation Defaults** (v11.0.0): `withDefault()` on HasOne/MorphOne/HasOneThrough
+- **🆕 Aggregates & Pluck** (v11.0.0): `sum()`, `avg()`, `min()`, `max()`, `value()`, keyed `pluck(col, key)`
 
 ## ⚡ Quick Start
 
@@ -1034,6 +1111,7 @@ if (db.isLogging()) {
 | `execute(sql, params?)` | Raw query (native driver results) |
 | `increment(table, column, query, amount?)` | Atomic increment |
 | `decrement(table, column, query, amount?)` | Atomic decrement |
+| `aggregate(table, fn, column, query)` | Execute aggregate function (SUM/AVG/MIN/MAX) |
 | `close()` / `disconnect()` | Closes the connection |
 | **Query Logging (static)** | |
 | `enableQueryLog()` | Enables query logging |
@@ -1100,6 +1178,17 @@ if (db.isLogging()) {
 | `getDirty()` | Modified attributes |
 | `isDirty()` | Has been modified? |
 | `toJSON()` | Convert to plain object |
+| `fresh()` | Reload from DB (new instance) |
+| `refresh()` | Reload in place |
+| `replicate()` | Clone without ID/timestamps |
+| `is(model)` | Same type and primary key? |
+| `isNot(model)` | Negation of `is()` |
+| `only(...keys)` | Subset of attributes |
+| `except(...keys)` | All attributes except listed |
+| `makeVisible(...attrs)` | Unhide attributes for this instance |
+| `makeHidden(...attrs)` | Hide attributes for this instance |
+| `wasChanged(attr?)` | Changed after last `save()`? |
+| `getChanges()` | Attributes changed by last `save()` |
 | **Soft Deletes** | |
 | `trashed()` | Is deleted? |
 | `restore()` | Restore the model |
@@ -1150,6 +1239,15 @@ if (db.isLogging()) {
 | `delete()` | Delete |
 | `increment(col, amount?)` | Atomic increment |
 | `decrement(col, amount?)` | Atomic decrement |
+| `pluck(col, keyCol?)` | Array of values or keyed object |
+| `value(col)` | Single scalar value |
+| `sum(col)` / `avg(col)` | Aggregate sum / average |
+| `min(col)` / `max(col)` | Aggregate min / max |
+| `chunk(size, callback)` | Process results in batches |
+| `when(cond, cb, fallback?)` | Conditional query building |
+| `tap(callback)` | Inspect builder without modifying |
+| `toSQL()` | Returns `{ sql, bindings }` |
+| `dd()` | Dumps SQL + bindings and throws |
 | `clone()` | Clones the query builder |
 
 ## 🛠️ CLI tools
@@ -1233,12 +1331,12 @@ Outlet ORM includes a complete AI subsystem with multi-provider LLM support and
 
 📚 **[Complete AI documentation available in `/docs`](./docs/AI_BRIDGE.md)**
 
-### AiBridge — Multi-Provider LLM Abstraction
+### AI — Multi-Provider LLM Abstraction
 
 ```javascript
-const { AiBridgeManager } = require('outlet-orm');
+const { AIManager } = require('outlet-orm');
 
-const ai = new AiBridgeManager({
+const ai = new AIManager({
   providers: {
     openai: { api_key: process.env.OPENAI_API_KEY, model: 'gpt-4o' },
     claude: { api_key: process.env.ANTHROPIC_API_KEY, model: 'claude-sonnet-4-20250514' },
@@ -1339,7 +1437,7 @@ Configure your AI editor:
 **13 MCP tools**: migrations, schema introspection, queries, seeds, backups, AI query, query optimization
 
 📖 Full documentation:
-- [AiBridge Manager](docs/AI_BRIDGE.md) — Multi-provider LLM abstraction
+- [AI Manager](docs/AI_BRIDGE.md) — Multi-provider LLM abstraction
 - [AI Query Builder](docs/AI_QUERY.md) — Natural language to SQL
 - [AI Seeder](docs/AI_SEEDER.md) — Realistic data generation
 - [AI Query Optimizer](docs/AI_OPTIMIZER.md) — SQL optimization

package/bin/reverse.js

@@ -82,7 +82,6 @@ function parseCreateTable(sql) {
   for (const line of splitDefinitions(body)) {
     const trimmed  = line.trim();
     if (!trimmed) continue;
-    const upperTrimmed = trimmed.toUpperCase();
 
     // ── Table-level FOREIGN KEY constraint ───────────────────────────────────
     if (/^FOREIGN\s+KEY/i.test(trimmed) || /^CONSTRAINT\s+\S+\s+FOREIGN\s+KEY/i.test(trimmed)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "outlet-orm",
-  "version": "9.0.2",
+  "version": "11.1.0",
   "description": "A Laravel Eloquent-inspired ORM for Node.js with support for MySQL, PostgreSQL, and SQLite",
   "main": "src/index.js",
   "types": "types/index.d.ts",

package/skills/outlet-orm/ADVANCED.md

@@ -157,6 +157,35 @@ Log.addGlobalScope('recent', (q) => q.where('created_at', '>', '2024-01-01'));
 Model.addGlobalScope('tenant', (q) => q.where('tenant_id', currentTenantId));
 ```
 
+### Local Scopes (v11.0.0)
+
+Define reusable query constraints as static `scopeXxx` methods. They become fluent methods on the QueryBuilder:
+
+```javascript
+class User extends Model {
+  static table = 'users';
+
+  static scopeActive(query) {
+    return query.where('status', 'active');
+  }
+
+  static scopeRole(query, role) {
+    return query.where('role', role);
+  }
+
+  static scopeRecent(query, days = 7) {
+    const date = new Date(Date.now() - days * 86400000).toISOString();
+    return query.where('created_at', '>', date);
+  }
+}
+
+// Fluent usage — scopes become methods on the query builder
+const users = await User.query().active().role('admin').recent(30).get();
+const count = await User.query().active().count();
+```
+
+> **Note**: The legacy `static scopes = {}` and `.scope('name')` syntax still works. Fluent local scopes are the recommended approach from v11.
+
 ---
 
 ## Events / Hooks

package/skills/outlet-orm/AI.md

@@ -1,6 +1,6 @@
 ---
 name: outlet-orm-ai-integration
-description: Guide for AI agents to use Outlet ORM's AiBridge multi-provider LLM, AI Query Builder, AI Seeder, AI Optimizer, AI Prompt Enhancer, MCP Server, and AI Safety Guardrails. Use this skill when an AI agent needs to interact with LLMs, databases, run migrations, generate data, optimize queries, or create projects safely.
+description: Guide for AI agents to use Outlet ORM's AI multi-provider LLM, AI Query Builder, AI Seeder, AI Optimizer, AI Prompt Enhancer, MCP Server, and AI Safety Guardrails. Use this skill when an AI agent needs to interact with LLMs, databases, run migrations, generate data, optimize queries, or create projects safely.
 license: MIT
 metadata:
   author: omgbwa-yasse
@@ -13,7 +13,7 @@ metadata:
 
 This skill covers Outlet ORM's complete AI feature set (v7.0.0 – v9.0.0):
 
-- **AiBridge** — Multi-provider LLM abstraction (9 providers, chat, stream, embeddings, images, TTS, STT, tool calling)
+- **AI** — Multi-provider LLM abstraction (9 providers, chat, stream, embeddings, images, TTS, STT, tool calling)
 - **AI Query Builder** — Natural language to SQL
 - **AI Seeder** — LLM-powered realistic data generation
 - **AI Query Optimizer** — SQL optimization and EXPLAIN analysis
@@ -23,16 +23,16 @@ This skill covers Outlet ORM's complete AI feature set (v7.0.0 – v9.0.0):
 
 ---
 
-## AiBridge — Multi-Provider LLM Abstraction
+## AI — Multi-Provider LLM Abstraction
 
 > Since v8.0.0
 
-AiBridge provides a unified API to interact with 9+ LLM providers. Zero production dependencies (Node 18+ native `fetch`).
+AI provides a unified API to interact with 9+ LLM providers. Zero production dependencies (Node 18+ native `fetch`).
 
 ### Configuration
 
 ```javascript
-// config/aibridge.js
+// config/ai.js
 module.exports = {
   default: process.env.AI_DEFAULT_PROVIDER || 'openai',
   providers: {
@@ -84,9 +84,9 @@ module.exports = {
 ### Chat
 
 ```javascript
-const { AiBridgeManager } = require('outlet-orm');
+const { AIManager } = require('outlet-orm');
 
-const ai = new AiBridgeManager(config);
+const ai = new AIManager(config);
 
 const response = await ai.chat('openai', [
   { role: 'system', content: 'You are a helpful assistant.' },
@@ -179,14 +179,14 @@ const response = await ai.chatWithTools('openai', [
 ]);
 ```
 
-### AiBridge Facade
+### AI Facade
 
 ```javascript
-const { AiBridge, AiBridgeManager } = require('outlet-orm');
+const { AI, AIManager } = require('outlet-orm');
 
-AiBridge.setManager(new AiBridgeManager(config));
+AI.setManager(new AIManager(config));
 
-const { text } = await AiBridge.text()
+const { text } = await AI.text()
   .using('openai', 'gpt-4o')
   .withPrompt('Hello!')
   .asText();
@@ -226,9 +226,9 @@ const { text } = await AiBridge.text()
 Convert natural language questions into SQL queries using any LLM.
 
 ```javascript
-const { AiBridgeManager, AIQueryBuilder, DatabaseConnection } = require('outlet-orm');
+const { AIManager, AIQueryBuilder, DatabaseConnection } = require('outlet-orm');
 
-const ai = new AiBridgeManager(config);
+const ai = new AIManager(config);
 const db = new DatabaseConnection();
 const qb = new AIQueryBuilder(ai, db);
 
@@ -267,9 +267,9 @@ const { sql } = await qb.toSql('Find duplicate emails');
 Generate realistic, domain-specific seed data using AI.
 
 ```javascript
-const { AiBridgeManager, AISeeder, DatabaseConnection } = require('outlet-orm');
+const { AIManager, AISeeder, DatabaseConnection } = require('outlet-orm');
 
-const seeder = new AISeeder(new AiBridgeManager(config), new DatabaseConnection());
+const seeder = new AISeeder(new AIManager(config), new DatabaseConnection());
 
 // Generate and insert
 const { records, inserted } = await seeder.seed('users', 10, {
@@ -309,9 +309,9 @@ const records = await seeder.generate('products', 20, {
 Analyze and optimize SQL queries using AI with index recommendations.
 
 ```javascript
-const { AiBridgeManager, AIQueryOptimizer, DatabaseConnection } = require('outlet-orm');
+const { AIManager, AIQueryOptimizer, DatabaseConnection } = require('outlet-orm');
 
-const optimizer = new AIQueryOptimizer(new AiBridgeManager(config), new DatabaseConnection());
+const optimizer = new AIQueryOptimizer(new AIManager(config), new DatabaseConnection());
 
 // Optimize
 const result = await optimizer.optimize(
@@ -352,9 +352,9 @@ const { plan, analysis } = await optimizer.explain('SELECT ...');
 Generate complete schemas, models, and migrations from natural language.
 
 ```javascript
-const { AiBridgeManager, AIPromptEnhancer } = require('outlet-orm');
+const { AIManager, AIPromptEnhancer } = require('outlet-orm');
 
-const enhancer = new AIPromptEnhancer(new AiBridgeManager(config));
+const enhancer = new AIPromptEnhancer(new AIManager(config));
 
 // Generate full schema
 const schema = await enhancer.generateSchema(
@@ -546,10 +546,10 @@ console.log(result.allowed); // true
 
 ```javascript
 const {
-  // AiBridge — Multi-Provider LLM
-  AiBridgeManager,       // Main manager (chat, stream, embeddings, images, TTS, STT, tools)
-  AiBridge,              // Static facade
-  // AiBridge Support
+  // AI — Multi-Provider LLM
+  AIManager,       // Main manager (chat, stream, embeddings, images, TTS, STT, tools)
+  AI,              // Static facade
+  // AI Support
   Message,               // Chat message value object
   Document,              // File/URL/base64 attachment
   StreamChunk,           // Streaming DTO

package/skills/outlet-orm/API.md

@@ -54,6 +54,7 @@ const db = new DatabaseConnection({
 |`update(table, data, query)`| Update records |
 |`delete(table, query)`| Delete records |
 |`count(table, query)`| Count records |
+|`aggregate(table, func, col, query)`| Run aggregate function (v11) |
 |`executeRawQuery(sql, params?)`| Raw query (normalised results) |
 |`execute(sql, params?)`| Raw query (native driver results) |
 |`increment(table, column, query, amount?)`| Atomic increment |
@@ -191,10 +192,27 @@ const db = new DatabaseConnection({
 |`fill(attrs)`| Fill attributes |
 |`setAttribute(key, val)`| Set single attribute |
 |`getAttribute(key)`| Get single attribute |
+|`user.key` (Proxy)| Property-style get/set (v11) |
 |`getDirty()`| Get modified attributes |
 |`isDirty()`| Check if modified |
+|`wasChanged(key?)`| Check if changed after save (v11) |
+|`getChanges()`| Get post-save changes (v11) |
+|`only(...keys)`| Subset of attributes (v11) |
+|`except(...keys)`| All attributes except keys (v11) |
+|`makeVisible(...keys)`| Show hidden attrs on instance (v11) |
+|`makeHidden(...keys)`| Hide attrs on instance (v11) |
 |`toJSON()`| Convert to plain object |
 
+### Model Utility (v11.0.0)
+
+| Method | Description |
+|--------|-------------|
+|`fresh()`| New reloaded instance from DB |
+|`refresh()`| Reload current instance in-place |
+|`replicate()`| Clone without primary key |
+|`is(model)`| Same table + same PK |
+|`isNot(model)`| Different identity |
+
 ### Persistence
 
 | Method | Description |
@@ -322,6 +340,13 @@ const db = new DatabaseConnection({
 |`paginate(page, perPage)`| Paginated results |
 |`count()`| Count results |
 |`exists()`| Check existence |
+|`sum(col)`| Sum of column (v11) |
+|`avg(col)`| Average of column (v11) |
+|`min(col)`| Minimum of column (v11) |
+|`max(col)`| Maximum of column (v11) |
+|`pluck(col)`| Array of column values (v11) |
+|`value(col)`| Single value from first row (v11) |
+|`chunk(size, callback)`| Batch processing (v11) |
 
 ### Mutations
 
@@ -339,6 +364,10 @@ const db = new DatabaseConnection({
 | Method | Description |
 |--------|-------------|
 |`clone()`| Clone QueryBuilder |
+|`when(condition, callback)`| Conditional clause (v11) |
+|`tap(callback)`| Debug callback (v11) |
+|`toSQL()`| Get SQL + bindings (v11) |
+|`dd()`| Dump & die debug (v11) |
 
 ---
 
@@ -464,6 +493,7 @@ const db = new DatabaseConnection({
 |`hidden`| array |`[]`| Hidden from JSON |
 |`casts`| object |`{}`| Type casting |
 |`rules`| object |`{}`| Validation rules |
+|`appends`| array |`[]`| Computed attrs in toJSON (v11) |
 |`connection`| object |`null`| Custom connection |
 
 ---
@@ -515,15 +545,15 @@ const db = new DatabaseConnection({
 
 ---
 
-## AiBridgeManager
+## AIManager
 
 > Since v8.0.0
 
 ### Constructor
 
 ```javascript
-const { AiBridgeManager } = require('outlet-orm');
-const ai = new AiBridgeManager(config); // From config/aibridge.js or inline
+const { AIManager } = require('outlet-orm');
+const ai = new AIManager(config); // From config/ai.js or inline
 ```
 
 ### Methods

package/skills/outlet-orm/MODELS.md

@@ -109,6 +109,7 @@ class User extends Model {
 |`hidden`| array |`[]`| Hidden from JSON |
 |`casts`| object |`{}`| Type casting definitions |
 |`rules`| object |`{}`| Validation rules |
+|`appends`| array |`[]`| Computed attributes included in toJSON (v11) |
 |`connection`| object |`null`| Custom DB connection |
 
 ---
@@ -256,7 +257,10 @@ await user.forceDelete();
 ```javascript
 const user = await User.find(1);
 
-// Get single attribute
+// Property access (v11+)
+const name = user.name;
+
+// Method access
 const name = user.getAttribute('name');
 
 // Get all attributes as object
@@ -272,7 +276,10 @@ const dirty = user.getDirty(); // Get modified attributes
 ```javascript
 const user = new User();
 
-// Set single attribute
+// Property access (v11+)
+user.name = 'John';
+
+// Method access
 user.setAttribute('name', 'John');
 
 // Fill multiple attributes
@@ -310,6 +317,141 @@ if (user && await bcrypt.compare(password, user.getAttribute('password'))) {
 }
 ```
 
+### Instance-Level Visibility (v11.0.0)
+
+```javascript
+const user = await User.find(1);
+
+// Temporarily show hidden attributes on this instance
+user.makeVisible('password', 'secret_token');
+console.log(user.toJSON()); // password & secret_token included
+
+// Temporarily hide additional attributes on this instance
+user.makeHidden('email', 'phone');
+console.log(user.toJSON()); // email & phone excluded
+```
+
+---
+
+## Property Access (v11.0.0)
+
+Access model attributes directly as properties via Proxy, in addition to `getAttribute()`/`setAttribute()`:
+
+```javascript
+const user = await User.find(1);
+
+// Before v11 - only method access
+const name = user.getAttribute('name');
+user.setAttribute('name', 'New Name');
+
+// v11+ - property-style access (equivalent)
+const name = user.name;
+user.name = 'New Name';
+await user.save();
+
+// Works with casts
+console.log(user.email_verified); // boolean (thanks to casts)
+console.log(user.metadata);       // object (JSON cast)
+
+// Check dirty state
+user.name = 'Changed';
+console.log(user.isDirty()); // true
+```
+
+> **Note**: Native Model methods and properties (`save`, `destroy`, `fill`, etc.) always take precedence over attribute names.
+
+---
+
+## Computed Appends (v11.0.0)
+
+Include computed attributes in `toJSON()` output:
+
+```javascript
+class User extends Model {
+  static table = 'users';
+  static appends = ['full_name', 'is_admin'];
+
+  // Accessor for computed attribute
+  getFullNameAttribute() {
+    return `${this.getAttribute('first_name')} ${this.getAttribute('last_name')}`;
+  }
+
+  getIsAdminAttribute() {
+    return this.getAttribute('role') === 'admin';
+  }
+}
+
+const user = await User.find(1);
+console.log(user.toJSON());
+// { id: 1, first_name: 'John', last_name: 'Doe', full_name: 'John Doe', is_admin: false, ... }
+```
+
+---
+
+## Model Utility Methods (v11.0.0)
+
+### fresh() / refresh()
+
+```javascript
+const user = await User.find(1);
+
+// fresh() returns a NEW instance reloaded from DB (original unchanged)
+const freshUser = await user.fresh();
+
+// refresh() reloads the CURRENT instance in-place
+user.name = 'temp';
+await user.refresh();
+console.log(user.name); // Back to DB value
+```
+
+### replicate()
+
+```javascript
+const user = await User.find(1);
+const clone = user.replicate();
+// clone has same attributes but NO primary key
+clone.name = 'Clone of ' + user.name;
+await clone.save(); // Inserts as new record
+```
+
+### is() / isNot()
+
+```javascript
+const user1 = await User.find(1);
+const user2 = await User.find(1);
+const user3 = await User.find(2);
+
+user1.is(user2);    // true  (same table + same PK)
+user1.isNot(user3); // true  (different PK)
+```
+
+### only() / except()
+
+```javascript
+const user = await User.find(1);
+
+// Get a subset of attributes
+const subset = user.only('name', 'email');
+// { name: 'John', email: 'john@example.com' }
+
+// Get all attributes except some
+const filtered = user.except('password', 'secret_token');
+// { id: 1, name: 'John', email: 'john@example.com', ... }
+```
+
+### wasChanged() / getChanges()
+
+```javascript
+const user = await User.find(1);
+user.name = 'Updated';
+await user.save();
+
+user.wasChanged();       // true
+user.wasChanged('name'); // true
+user.wasChanged('email'); // false
+user.getChanges();       // { name: 'Updated' }
+```
+
 ---
 
 ## Timestamps