outlet-orm 10.0.0 → 11.1.0

package/README.md

@@ -274,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
 
@@ -1100,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 |
@@ -1166,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 |
@@ -1216,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

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": "10.0.0",
+  "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/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 |
 
 ---

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

package/skills/outlet-orm/QUERIES.md

@@ -211,6 +211,30 @@ if (hasAdmins) {
 }
 ```
 
+### Sum / Avg / Min / Max (v11.0.0)
+
+```javascript
+const totalBalance = await User.query().sum('balance');
+const averageAge = await User.query().avg('age');
+const youngest = await User.query().min('age');
+const oldest = await User.query().max('age');
+
+// With conditions
+const activeTotal = await User.where('status', 'active').sum('balance');
+```
+
+### Pluck / Value (v11.0.0)
+
+```javascript
+// pluck() — get an array of values from a single column
+const emails = await User.query().pluck('email');
+// ['john@example.com', 'jane@example.com', ...]
+
+// value() — get a single value from the first row
+const name = await User.where('id', 1).value('name');
+// 'John Doe'
+```
+
 ### Group By & Having
 
 ```javascript
@@ -280,6 +304,104 @@ await User.where('id', 1).decrement('credits', 50);
 
 ---
 
+## Batch Processing — chunk() (v11.0.0)
+
+Process large datasets in manageable batches:
+
+```javascript
+// Process 100 records at a time
+await User.query().chunk(100, async (users) => {
+  for (const user of users) {
+    await sendNewsletter(user);
+  }
+});
+
+// With conditions
+await User.where('status', 'active').chunk(50, async (batch) => {
+  console.log(`Processing ${batch.length} users`);
+});
+```
+
+---
+
+## Conditional Queries — when() / tap() (v11.0.0)
+
+### when()
+
+Conditionally apply query clauses:
+
+```javascript
+const status = req.query.status; // may be undefined
+
+const users = await User.query()
+  .when(status, (query, value) => query.where('status', value))
+  .when(req.query.role, (query, value) => query.where('role', value))
+  .get();
+```
+
+### tap()
+
+Execute a callback for debugging without modifying the query:
+
+```javascript
+const users = await User.query()
+  .where('status', 'active')
+  .tap((query) => console.log('Query so far:', query.toSQL()))
+  .orderBy('name')
+  .get();
+```
+
+---
+
+## Query Debugging — toSQL() / dd() (v11.0.0)
+
+```javascript
+// toSQL() — get the SQL string and bindings
+const { sql, bindings } = User.where('status', 'active').toSQL();
+console.log(sql);      // 'SELECT * FROM users WHERE status = ?'
+console.log(bindings); // ['active']
+
+// dd() — dump and die (logs to console and throws)
+User.where('status', 'active').dd();
+// Logs: { sql: '...', bindings: [...] } then throws
+```
+
+---
+
+## Fluent Local Scopes (v11.0.0)
+
+Define reusable query constraints as static methods on the model:
+
+```javascript
+class User extends Model {
+  static table = 'users';
+
+  // Define scope as static scopeXxx(query, ...params)
+  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);
+  }
+}
+
+// Use fluently on the query builder
+const users = await User.query().active().role('admin').recent(30).get();
+
+// Combine with other query methods
+const count = await User.query().active().count();
+```
+
+> See [ADVANCED.md](ADVANCED.md) for more details on global and local scopes.
+
+---
+
 ## Raw Queries
 
 ```javascript
@@ -394,6 +516,17 @@ See [AI.md](AI.md) for full details.
 |`paginate(page, perPage)`| Pagination |
 |`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) |
+|`when(condition, callback)`| Conditional clause (v11) |
+|`tap(callback)`| Debug callback (v11) |
+|`toSQL()`| Get SQL + bindings (v11) |
+|`dd()`| Dump & die debug (v11) |
 |`insert(data)`| Insert record(s) |
 |`update(attrs)`| Update records |
 |`delete()`| Delete records |

package/skills/outlet-orm/RELATIONS.md

@@ -546,6 +546,50 @@ class Category extends Model {
 |`attach(ids)`| Attach (many-to-many) |
 |`detach(ids?)`| Detach (many-to-many) |
 |`sync(ids)`| Sync (many-to-many) |
+|`withDefault(attrs?)`| Default for empty HasOne/MorphOne (v11) |
+
+---
+
+## Relation Defaults — withDefault() (v11.0.0)
+
+Return a default model instead of `null` when a `hasOne`, `morphOne` or `hasOneThrough` relationship is empty:
+
+```javascript
+class User extends Model {
+  static table = 'users';
+
+  profile() {
+    // Returns empty Profile instance instead of null
+    return this.hasOne(Profile, 'user_id').withDefault();
+  }
+
+  avatar() {
+    // Returns a Profile with default values
+    return this.morphOne(Image, 'imageable').withDefault({
+      url: '/images/default-avatar.png'
+    });
+  }
+
+  settings() {
+    // Dynamic defaults via callback
+    return this.hasOne(Settings, 'user_id').withDefault((model) => {
+      model.setAttribute('theme', 'light');
+      model.setAttribute('locale', 'en');
+    });
+  }
+}
+
+// Usage
+const user = await User.with('profile').find(1);
+console.log(user.relationships.profile); // Profile instance (never null)
+```
+
+**Signatures:**
+- `withDefault()` — empty model instance
+- `withDefault({ key: value, ... })` — model with attributes
+- `withDefault((model) => { ... })` — dynamic defaults via callback
+
+**Supported on:** `hasOne`, `morphOne`, `hasOneThrough`
 
 ---
 

package/skills/outlet-orm/SKILL.md

@@ -4,7 +4,7 @@ description: Outlet ORM is a Laravel Eloquent-inspired ORM for Node.js with MySQ
 license: MIT
 metadata:
 author: omgbwa-yasse
-version: "9.0.0"
+version: "11.0.0"
 source: https://github.com/omgbwa-yasse/outlet-orm
 npm: https://www.npmjs.com/package/outlet-orm
 ---
@@ -13,7 +13,9 @@ npm: https://www.npmjs.com/package/outlet-orm
 
 Comprehensive guide for using Outlet ORM - a Laravel Eloquent-inspired ORM for Node.js/TypeScript with support for MySQL, PostgreSQL, and SQLite.
 
-> 🆕 **v9.0.0**: Complete AI documentation — AI multi-provider LLM, AI Query Builder, AI Seeder, AI Optimizer, AI Prompt Enhancer, AI Safety Guardrails. See [AI.md](AI.md).
+> 🆕 **v11.0.0**: Proxy property access (`user.name`), Eloquent-style model methods (`fresh`, `refresh`, `replicate`, `is`, `isNot`, `only`, `except`, `makeVisible`, `makeHidden`, `wasChanged`, `getChanges`), computed `appends`, QueryBuilder enhancements (`value`, `chunk`, `when`, `tap`, `toSQL`, `dd`), fluent local scopes (`static scopeActive(query)` → `User.query().active()`), relation `withDefault()`. See [MODELS.md](MODELS.md), [QUERIES.md](QUERIES.md), [ADVANCED.md](ADVANCED.md), [RELATIONS.md](RELATIONS.md).
+>
+> 🔖 **v9.0.0**: Complete AI documentation — AI multi-provider LLM, AI Query Builder, AI Seeder, AI Optimizer, AI Prompt Enhancer, AI Safety Guardrails. See [AI.md](AI.md).
 >
 > 🔖 **v8.0.0**: AI multi-provider LLM abstraction (9 providers), AI Query Builder, AI Seeder, AI Query Optimizer, AI Prompt Enhancer.
 >

package/skills/outlet-orm/TYPESCRIPT.md

@@ -384,6 +384,104 @@ table.foreign('user_id')
 
 ---
 
+## v11.0.0 Type Additions
+
+### Property-Style Attribute Access
+
+Model instances are wrapped in a `Proxy`, so attributes can be read and written as direct properties:
+
+```typescript
+const user = await User.find(1);
+
+// Property access (via Proxy)
+console.log(user.name);       // equivalent to user.getAttribute('name')
+user.email = 'new@mail.com';  // equivalent to user.setAttribute('email', ...)
+
+// Both styles coexist
+user.getAttribute('name');     // still works
+```
+
+The index signature `[K: string]: any` on `Model` enables this in TypeScript.
+
+### Computed Appends
+
+```typescript
+class User extends Model<UserAttributes> {
+  static table = 'users';
+  static appends = ['full_name'] as const;
+
+  getFullNameAttribute(): string {
+    return `${this.attributes.first_name} ${this.attributes.last_name}`;
+  }
+}
+
+// full_name is included in toJSON() output
+```
+
+### New Model Instance Methods
+
+```typescript
+// Reload from DB
+const freshUser: User | null = await user.fresh('posts');
+await user.refresh(); // mutates in place
+
+// Clone without primary key
+const clone: User = user.replicate('id', 'created_at');
+
+// Identity comparison
+user.is(otherUser);    // same table + same PK
+user.isNot(otherUser);
+
+// Attribute subsets
+const partial: Partial<UserAttributes> = user.only('name', 'email');
+const rest: Partial<UserAttributes> = user.except('password');
+
+// Instance-level visibility
+user.makeVisible('password');
+user.makeHidden('email');
+
+// Change tracking (after save)
+user.wasChanged('name'); // boolean
+user.getChanges();       // { name: 'new value' }
+```
+
+### New QueryBuilder Methods
+
+```typescript
+// Single column value
+const email: any = await User.where('id', 1).value('email');
+
+// Batch processing
+await User.where('active', true).chunk(100, (users, page) => {
+  console.log(`Page ${page}:`, users.length);
+  // return false to stop
+});
+
+// Conditional query building
+User.query()
+  .when(role, (qb, val) => qb.where('role', val))
+  .tap(qb => console.log(qb.toSQL()))
+  .get();
+
+// Debug
+const sql = User.where('active', true).toSQL();
+User.where('active', true).dd(); // dumps SQL + throws
+```
+
+### withDefault on Relations
+
+```typescript
+class User extends Model<UserAttributes> {
+  profile(): HasOneRelation<Profile> {
+    return this.hasOne(Profile, 'user_id').withDefault();
+    // or .withDefault({ bio: 'N/A' })
+    // or .withDefault(() => new Profile({ bio: 'N/A' }))
+  }
+}
+```
+
+---
+
 ## Common Patterns
 
 ### Repository Pattern