@dreamtree-org/korm-js 1.0.52 → 1.0.54

package/README.md

@@ -29,6 +29,35 @@
 npm install @dreamtree-org/korm-js
 ```
 
+## AI assistant skills (`init --ai`)
+
+KORM-JS ships a canonical reference doc designed for AI coding assistants. After installing the package (or via `npx` without installing), drop the skill into the location your assistant picks up:
+
+```bash
+npx @dreamtree-org/korm-js init --ai claude
+```
+
+Supported providers:
+
+| `--ai` value                        | Target file                                                 |
+| ----------------------------------- | ----------------------------------------------------------- |
+| `claude`                            | `CLAUDE.md` (idempotent block insert)                       |
+| `openai` (alias: `codex`)           | `AGENTS.md` (idempotent block insert)                       |
+| `gemini`                            | `GEMINI.md` (idempotent block insert)                       |
+| `copilot` (alias: `github-copilot`) | `.github/copilot-instructions.md` (idempotent block insert) |
+| `kiro`                              | `.kiro/steering/korm-js.md`                                 |
+| `windsurf`                          | `.windsurf/rules/korm-js.md`                                |
+| `cursor`                            | `.cursor/rules/korm-js.mdc` (with MDC frontmatter)          |
+| `all`                               | Installs every provider above                               |
+
+Flags:
+
+- `--cwd <dir>` — install into a directory other than the current working directory.
+- `--force` — overwrite dedicated-file targets (Cursor / Windsurf / Kiro) that already exist.
+- `--dry-run` — print what would change without writing.
+
+Block-insert targets (`CLAUDE.md`, `AGENTS.md`, `GEMINI.md`, `.github/copilot-instructions.md`) wrap the skill in `<!-- BEGIN korm-js skill --> ... <!-- END korm-js skill -->` markers. Re-running the command after a library upgrade updates the block in place without touching the rest of the file.
+
 ## Quick Start with Express.js and MySQL
 
 ### 1. Basic Setup
@@ -50,15 +79,15 @@ const db = knex({
     user: process.env.DB_USER || 'root',
     password: process.env.DB_PASS || 'password',
     database: process.env.DB_NAME || 'my_database',
-    port: process.env.DB_PORT || 3306
-  }
+    port: process.env.DB_PORT || 3306,
+  },
 });
 
 // Initialize KORM with MySQL
 const korm = initializeKORM({
   db: db,
   dbClient: 'mysql',
-  debug: false  // Set to true for SQL debugging
+  debug: false, // Set to true for SQL debugging
 });
 
 app.listen(3000, () => {
@@ -75,14 +104,14 @@ async function initApp() {
   if (syncSchema) {
     korm.setSchema(syncSchema);
   }
-  
+
   // Sync database with schema (creates tables if they don't exist)
   await korm.syncDatabase().then(() => {
     console.log('✅ Database synced');
   });
-  
+
   // Generate schema from existing database
-  await korm.generateSchema().then(schema => {
+  await korm.generateSchema().then((schema) => {
     korm.setSchema(schema); // Set the schema to the korm instance
     helperUtility.file.createDirectory('schema');
     helperUtility.file.writeJSON('schema/schema.json', schema);
@@ -332,7 +361,49 @@ POST /api/Users/crud
 42  // Number of matching records
 ```
 
-### 7. Replace Operation
+### 7. Sum Operation
+
+Use either `data.sumColumn` (single column) or `data.sumFormula` (expression with `{columnName}` placeholders). Optional `where` filters the rows before summing.
+
+```javascript
+// Sum a single column
+POST /api/Employee/crud
+{
+  "action": "sum",
+  "data": {
+    "sumColumn": "salary"
+  },
+  "where": {
+    "is_active": true,
+    "created_at": ">=2024-01-01"
+  }
+}
+
+// Sum an expression (e.g. salary + bonus)
+POST /api/Employee/crud
+{
+  "action": "sum",
+  "data": {
+    "sumFormula": "{salary}+{bonus}"
+  },
+  "where": {
+    "is_active": true
+  }
+}
+
+// Response
+125000  // Sum value (number)
+```
+
+**Notes:**
+
+- Use **either** `sumColumn` or `sumFormula`, not both. If both are provided, `sumColumn` is used.
+- In `sumFormula`, column names are written as `{columnName}` and are safely quoted; only letters, numbers, and underscore are allowed in names.
+- **Expression guards:** `sumFormula` allows only BODMAS-safe content: numbers (including decimals), operators `+` `-` `*` `/`, parentheses `(` `)`, and `{columnName}` placeholders. Any other character (e.g. commas, quotes, SQL) is rejected. Parentheses must be balanced and correctly ordered.
+- Examples: `{salary}+{bonus}`, `({salary}+{bonus})*0.9`, `{amount}*1.1`, `{a}/{b}*100`.
+- `where` supports the same operators as list/count (e.g. `>=`, `><`, `%...%`, etc.).
+
+### 8. Replace Operation
 
 ```javascript
 // Replace record (MySQL specific - replaces entire row)
@@ -356,7 +427,7 @@ POST /api/Users/crud
 }
 ```
 
-### 8. Upsert Operation (Insert or Update)
+### 9. Upsert Operation (Insert or Update)
 
 ```javascript
 // Upsert record (insert if not exists, update if exists)
@@ -380,7 +451,7 @@ POST /api/Users/crud
 }
 ```
 
-### 9. Sync Operation (Upsert + Delete)
+### 10. Sync Operation (Upsert + Delete)
 
 ```javascript
 // Sync operation: upsert records and delete others matching where clause
@@ -558,21 +629,21 @@ POST /api/Users/crud
 
 ### Where Operators Reference
 
-| Operator | Description | Syntax | Example |
-|----------|-------------|--------|---------|
-| `=` (default) | Equals | `value` | `"status": "active"` |
-| `>=` | Greater than or equal | `>=value` | `"age": ">=18"` |
-| `<=` | Less than or equal | `<=value` | `"age": "<=65"` |
-| `>` | Greater than | `>value` | `"price": ">100"` |
-| `<` | Less than | `<value` | `"price": "<500"` |
-| `!=` | Not equal | `!value` | `"status": "!deleted"` |
-| `like` | Pattern matching (auto) | `%value%` | `"name": "%john%"` |
-| `in` | Value in list | `[]val1,val2` | `"status": "[]active,pending"` |
-| `notIn` | Value not in list | `![]val1,val2` | `"role": "![]banned,suspended"` |
-| `between` | Range (inclusive) | `><min,max` | `"age": "><18,65"` |
-| `notBetween` | Outside range | `<>min,max` | `"score": "<>0,50"` |
-| `null` | IS NULL check | `null` | `"deleted_at": null` |
-| `Or:column` | OR condition prefix | `Or:column` | `"Or:name": "John"` |
+| Operator      | Description             | Syntax         | Example                         |
+| ------------- | ----------------------- | -------------- | ------------------------------- |
+| `=` (default) | Equals                  | `value`        | `"status": "active"`            |
+| `>=`          | Greater than or equal   | `>=value`      | `"age": ">=18"`                 |
+| `<=`          | Less than or equal      | `<=value`      | `"age": "<=65"`                 |
+| `>`           | Greater than            | `>value`       | `"price": ">100"`               |
+| `<`           | Less than               | `<value`       | `"price": "<500"`               |
+| `!=`          | Not equal               | `!value`       | `"status": "!deleted"`          |
+| `like`        | Pattern matching (auto) | `%value%`      | `"name": "%john%"`              |
+| `in`          | Value in list           | `[]val1,val2`  | `"status": "[]active,pending"`  |
+| `notIn`       | Value not in list       | `![]val1,val2` | `"role": "![]banned,suspended"` |
+| `between`     | Range (inclusive)       | `><min,max`    | `"age": "><18,65"`              |
+| `notBetween`  | Outside range           | `<>min,max`    | `"score": "<>0,50"`             |
+| `null`        | IS NULL check           | `null`         | `"deleted_at": null`            |
+| `Or:column`   | OR condition prefix     | `Or:column`    | `"Or:name": "John"`             |
 
 **Examples:**
 
@@ -589,7 +660,7 @@ POST /api/Users/crud
     "score": "><50,100"
   }
 }
-// SQL: WHERE age >= 18 AND status != 'deleted' AND name LIKE '%john%' 
+// SQL: WHERE age >= 18 AND status != 'deleted' AND name LIKE '%john%'
 //      AND role IN ('admin', 'moderator', 'editor') AND score BETWEEN 50 AND 100
 ```
 
@@ -680,6 +751,7 @@ POST /api/Users/crud
 ```
 
 **Available join types:**
+
 - `join` - Regular join
 - `innerJoin` - Inner join
 - `leftJoin` - Left join
@@ -754,6 +826,7 @@ For many-to-many relationships, use the `through` key to specify the join/pivot
 ```
 
 **Many-to-Many Structure:**
+
 - `type`: `"many"` (always use "many" for many-to-many)
 - `table`: The related table name (e.g., `"roles"`)
 - `localKey`: The primary key in the current model (e.g., `"id"`)
@@ -824,7 +897,7 @@ POST /api/Post/crud
   },
   "with": ["User", "User.UserRole", "User.UserRole.Role"]
 }
-// SQL: WHERE EXISTS (SELECT * FROM users WHERE users.id = posts.user_id 
+// SQL: WHERE EXISTS (SELECT * FROM users WHERE users.id = posts.user_id
 //        AND EXISTS (SELECT * FROM user_roles WHERE user_roles.user_id = users.id
 //          AND EXISTS (SELECT * FROM roles WHERE roles.id = user_roles.role_id AND name = 'admin')))
 ```
@@ -843,7 +916,7 @@ POST /api/Post/crud
   },
   "with": ["User"]
 }
-// SQL: WHERE EXISTS (SELECT * FROM users WHERE users.id = posts.user_id 
+// SQL: WHERE EXISTS (SELECT * FROM users WHERE users.id = posts.user_id
 //        AND NOT EXISTS (SELECT * FROM user_roles WHERE user_roles.user_id = users.id))
 
 // Get users with no posts
@@ -871,12 +944,13 @@ POST /api/Post/crud
 
 **NOT EXISTS Syntax Summary:**
 
-| Pattern | Meaning | Use Case |
-|---------|---------|----------|
-| `"!RelName": true` | NOT EXISTS on direct relation | Users with no posts |
-| `"Parent.!Child": true` | NOT EXISTS on nested relation | Posts where user has no roles |
-| `"Parent.!Child.column": value` | NOT EXISTS with condition | Posts where user has no admin role |
-```
+| Pattern                         | Meaning                       | Use Case                           |
+| ------------------------------- | ----------------------------- | ---------------------------------- |
+| `"!RelName": true`              | NOT EXISTS on direct relation | Users with no posts                |
+| `"Parent.!Child": true`         | NOT EXISTS on nested relation | Posts where user has no roles      |
+| `"Parent.!Child.column": value` | NOT EXISTS with condition     | Posts where user has no admin role |
+
+````
 
 #### Filtering Eager Loaded Relations with `withWhere`
 
@@ -938,15 +1012,15 @@ POST /api/User/crud
     "Or:Post.is_featured": true
   }
 }
-```
+````
 
 **Key differences between `where` and `withWhere`:**
 
-| Feature | `where` (Nested) | `withWhere` |
-|---------|-----------------|-------------|
-| Affects parent query | Yes (filters parent rows) | No (only filters related rows) |
-| Purpose | Filter parents that have matching relations | Filter which related rows are loaded |
-| SQL generated | `WHERE EXISTS (subquery)` | Additional `WHERE` on relation query |
+| Feature              | `where` (Nested)                            | `withWhere`                          |
+| -------------------- | ------------------------------------------- | ------------------------------------ |
+| Affects parent query | Yes (filters parent rows)                   | No (only filters related rows)       |
+| Purpose              | Filter parents that have matching relations | Filter which related rows are loaded |
+| SQL generated        | `WHERE EXISTS (subquery)`                   | Additional `WHERE` on relation query |
 
 **Example showing the difference:**
 
@@ -971,6 +1045,7 @@ POST /api/User/crud
 ```
 
 **withWhere supports all operators:**
+
 - Comparison: `">=18"`, `"<=100"`, `">50"`, `"<10"`, `"!deleted"`
 - LIKE: `"%pattern%"`
 - IN: `"[]val1,val2,val3"`
@@ -1044,6 +1119,7 @@ Example complete relationship structure:
 ### Custom Relation Hooks
 
 For complex relationships that can't be defined in the schema, you can create custom relation hooks in your model class. This is useful for:
+
 - Virtual/computed relations
 - Cross-database relations
 - Complex aggregations
@@ -1059,35 +1135,33 @@ class Users {
     // rows = parent rows to attach relation data to
     // db = Knex database instance
     // qb = QueryBuilder instance
-    
+
     for (const row of rows) {
       // Fetch custom data for each row
-      const stats = await db('user_statistics')
-        .where('user_id', row.id)
-        .first();
-      
+      const stats = await db('user_statistics').where('user_id', row.id).first();
+
       // Attach to row
       row.Statistics = stats || { posts: 0, comments: 0, likes: 0 };
     }
   }
-  
+
   // Custom relation with aggregation
   async getPostCountRelation({ rows, db }) {
-    const userIds = rows.map(r => r.id);
-    
+    const userIds = rows.map((r) => r.id);
+
     const counts = await db('posts')
       .select('user_id')
       .count('* as count')
       .whereIn('user_id', userIds)
       .groupBy('user_id');
-    
-    const countMap = new Map(counts.map(c => [c.user_id, c.count]));
-    
+
+    const countMap = new Map(counts.map((c) => [c.user_id, c.count]));
+
     for (const row of rows) {
       row.PostCount = countMap.get(row.id) || 0;
     }
   }
-  
+
   // Custom relation from external API or different database
   async getExternalProfileRelation({ rows }) {
     for (const row of rows) {
@@ -1114,16 +1188,16 @@ POST /api/Users/crud
 
 **Custom Relation Hook Arguments:**
 
-| Argument | Description |
-|----------|-------------|
-| `rows` | Parent rows to attach relation data to (modify in place) |
-| `relName` | The relation name being fetched |
-| `model` | Model definition object |
-| `withTree` | Nested relations tree for further loading |
-| `controller` | ControllerWrapper instance |
-| `relation` | Relation definition from schema (may be undefined for custom relations) |
-| `qb` | QueryBuilder instance for building queries |
-| `db` | Knex database instance for direct queries |
+| Argument     | Description                                                             |
+| ------------ | ----------------------------------------------------------------------- |
+| `rows`       | Parent rows to attach relation data to (modify in place)                |
+| `relName`    | The relation name being fetched                                         |
+| `model`      | Model definition object                                                 |
+| `withTree`   | Nested relations tree for further loading                               |
+| `controller` | ControllerWrapper instance                                              |
+| `relation`   | Relation definition from schema (may be undefined for custom relations) |
+| `qb`         | QueryBuilder instance for building queries                              |
+| `db`         | Knex database instance for direct queries                               |
 
 ### Important Notes
 
@@ -1146,13 +1220,13 @@ Create a model file at `models/Users.model.js`:
 class Users {
   // Enable soft delete for this model
   hasSoftDelete = true;
-  
+
   // Optional: Custom soft delete hook
   beforeDelete({ model, action, request, context, db, utils, controller }) {
     // Custom logic before soft delete
     console.log('Soft deleting user:', request.where);
   }
-  
+
   // Optional: Custom hook after soft delete
   afterDelete({ model, action, data, request, context, db, utils, controller }) {
     // Custom logic after soft delete
@@ -1203,15 +1277,13 @@ class Users {
         throw new Error('Email is required');
       }
       // Check if email already exists
-      const existing = await db('users')
-        .where('email', request.data.email)
-        .first();
+      const existing = await db('users').where('email', request.data.email).first();
       if (existing && existing.id !== request.where?.id) {
         throw new Error('Email already exists');
       }
     }
   }
-  
+
   // Before hooks - run before the action executes
   // Method naming: before{Action} (e.g., beforeCreate, beforeUpdate, beforeList, beforeDelete)
   async beforeCreate({ model, action, request, context, db, utils, controller }) {
@@ -1220,18 +1292,18 @@ class Users {
     request.data.updated_at = new Date();
     return request.data;
   }
-  
+
   async beforeUpdate({ model, action, request, context, db, utils, controller }) {
     // Modify request data before update
     request.data.updated_at = new Date();
     return request.data;
   }
-  
+
   async beforeDelete({ model, action, request, context, db, utils, controller }) {
     // Logic before delete (works with both hard and soft delete)
     console.log('Deleting user:', request.where);
   }
-  
+
   // After hooks - run after the action executes
   // Method naming: after{Action} (e.g., afterCreate, afterUpdate, afterList, afterDelete)
   async afterCreate({ model, action, data, request, context, db, utils, controller }) {
@@ -1240,17 +1312,17 @@ class Users {
     // Send welcome email, trigger notifications, etc.
     return data;
   }
-  
+
   async afterUpdate({ model, action, data, request, context, db, utils, controller }) {
     console.log('User updated:', data);
     return data;
   }
-  
+
   async afterList({ model, action, data, request, context, db, utils, controller }) {
     // Modify list results before returning
     return data;
   }
-  
+
   // Custom action hooks
   // Method naming: on{Action}Action (e.g., onActivateAction, onDeactivateAction)
   async onActivateAction({ model, action, request, context, db, utils, controller }) {
@@ -1258,7 +1330,7 @@ class Users {
       .where(request.where)
       .update({ is_active: true, updated_at: new Date() });
   }
-  
+
   async onDeactivateAction({ model, action, request, context, db, utils, controller }) {
     return await db('users')
       .where(request.where)
@@ -1271,29 +1343,30 @@ module.exports = Users;
 
 ### Hook Arguments Reference
 
-| Argument | Description |
-|----------|-------------|
-| `model` | Model definition object with table, columns, relations |
-| `action` | Current action being performed (create, update, delete, etc.) |
-| `request` | The request object containing where, data, etc. |
-| `context` | Custom context passed from the controller |
-| `db` | Knex database instance for direct queries |
-| `utils` | Utility functions |
-| `controller` | ControllerWrapper instance |
-| `data` | (After hooks only) Result of the action |
+| Argument     | Description                                                   |
+| ------------ | ------------------------------------------------------------- |
+| `model`      | Model definition object with table, columns, relations        |
+| `action`     | Current action being performed (create, update, delete, etc.) |
+| `request`    | The request object containing where, data, etc.               |
+| `context`    | Custom context passed from the controller                     |
+| `db`         | Knex database instance for direct queries                     |
+| `utils`      | Utility functions                                             |
+| `controller` | ControllerWrapper instance                                    |
+| `data`       | (After hooks only) Result of the action                       |
 
 ### Complete Hook Types Reference
 
-| Hook Type | Method Naming | When Called | Use Case |
-|-----------|---------------|-------------|----------|
-| Validate | `validate` | Before any action | Input validation, authorization |
-| Before | `before{Action}` | Before action executes | Modify request data, add timestamps |
-| After | `after{Action}` | After action executes | Transform results, trigger side effects |
-| Custom Action | `on{Action}Action` | For custom actions | Implement business logic |
-| Soft Delete | `hasSoftDelete = true` | During delete/list | Enable soft delete |
-| Custom Relation | `get{RelName}Relation` | During eager loading | Custom data fetching |
+| Hook Type       | Method Naming          | When Called            | Use Case                                |
+| --------------- | ---------------------- | ---------------------- | --------------------------------------- |
+| Validate        | `validate`             | Before any action      | Input validation, authorization         |
+| Before          | `before{Action}`       | Before action executes | Modify request data, add timestamps     |
+| After           | `after{Action}`        | After action executes  | Transform results, trigger side effects |
+| Custom Action   | `on{Action}Action`     | For custom actions     | Implement business logic                |
+| Soft Delete     | `hasSoftDelete = true` | During delete/list     | Enable soft delete                      |
+| Custom Relation | `get{RelName}Relation` | During eager loading   | Custom data fetching                    |
 
 **Available Before/After hooks:**
+
 - `beforeCreate` / `afterCreate`
 - `beforeUpdate` / `afterUpdate`
 - `beforeDelete` / `afterDelete`
@@ -1316,7 +1389,7 @@ POST /api/Users/crud
 
 POST /api/Users/crud
 {
-  "action": "deactivate", 
+  "action": "deactivate",
   "where": { "id": 1 }
 }
 
@@ -1343,7 +1416,7 @@ const userValidationRules = {
   first_name: 'required|type:string|maxLen:100',
   last_name: 'required|type:string|maxLen:100',
   age: 'type:number|min:0|max:150',
-  is_active: 'type:boolean'
+  is_active: 'type:boolean',
 };
 
 // Validate and create user
@@ -1351,30 +1424,33 @@ app.post('/api/users/validate', async (req, res) => {
   try {
     // Validate request data
     const validatedData = await validate(req.body, userValidationRules);
-    
-    const result = await korm.processRequest({
-      action: 'create',
-      data: validatedData
-    }, 'Users');
-    
+
+    const result = await korm.processRequest(
+      {
+        action: 'create',
+        data: validatedData,
+      },
+      'Users'
+    );
+
     res.status(201).json({
       success: true,
       message: 'User created successfully',
-      data: result
+      data: result,
     });
   } catch (error) {
     if (error.name === 'ValidationError') {
       return res.status(400).json({
         success: false,
         message: 'Validation failed',
-        errors: error.message
+        errors: error.message,
       });
     }
-    
+
     res.status(500).json({
       success: false,
       message: 'Error creating user',
-      error: error.message
+      error: error.message,
     });
   }
 });
@@ -1392,13 +1468,13 @@ const advancedRules = {
   phone: 'regex:phone',
   password: 'required|type:string|minLen:8',
   status: 'in:active,inactive,pending',
-  user_id: 'exists:users,id'
+  user_id: 'exists:users,id',
 };
 
 const customRegex = {
   username: /^[a-zA-Z0-9_]+$/,
   email: /^[^\s@]+@[^\s@]+\.[^\s@]+$/,
-  phone: /^\+?[\d\s-()]{10,15}$/
+  phone: /^\+?[\d\s-()]{10,15}$/,
 };
 
 const validatedData = await validate(data, advancedRules, { customRegex });
@@ -1489,20 +1565,21 @@ type|modifier1|modifier2|...
 
 **Column Modifiers:**
 
-| Modifier | Description | Example |
-|----------|-------------|---------|
-| `size:n` | Column size | `varchar|size:255` |
-| `unsigned` | Unsigned integer | `int|unsigned` |
-| `primaryKey` | Primary key column | `bigint|primaryKey` |
-| `autoIncrement` | Auto increment | `bigint|primaryKey|autoIncrement` |
-| `notNull` | Not nullable | `varchar|size:255|notNull` |
-| `unique` | Unique constraint | `varchar|unique` |
-| `default:value` | Default value | `tinyint|default:1` |
-| `onUpdate:value` | On update value | `timestamp|onUpdate:CURRENT_TIMESTAMP` |
-| `comment:text` | Column comment | `varchar|comment:User email address` |
-| `foreignKey:table:column` | Foreign key | `int|foreignKey:users:id` |
+| Modifier                  | Description        | Example    |
+| ------------------------- | ------------------ | ---------- | --------------------------- | -------------- |
+| `size:n`                  | Column size        | `varchar   | size:255`                   |
+| `unsigned`                | Unsigned integer   | `int       | unsigned`                   |
+| `primaryKey`              | Primary key column | `bigint    | primaryKey`                 |
+| `autoIncrement`           | Auto increment     | `bigint    | primaryKey                  | autoIncrement` |
+| `notNull`                 | Not nullable       | `varchar   | size:255                    | notNull`       |
+| `unique`                  | Unique constraint  | `varchar   | unique`                     |
+| `default:value`           | Default value      | `tinyint   | default:1`                  |
+| `onUpdate:value`          | On update value    | `timestamp | onUpdate:CURRENT_TIMESTAMP` |
+| `comment:text`            | Column comment     | `varchar   | comment:User email address` |
+| `foreignKey:table:column` | Foreign key        | `int       | foreignKey:users:id`        |
 
 **Special Default Values:**
+
 - `now` or `now()` → `CURRENT_TIMESTAMP`
 
 **Example Column Definitions:**
@@ -1550,11 +1627,11 @@ Seed data is automatically inserted when `syncDatabase()` is called and the tabl
 const { initializeKORM } = require('@dreamtree-org/korm-js');
 
 const korm = initializeKORM({
-  db: db,               // Knex database instance
-  dbClient: 'mysql',    // 'mysql', 'mysql2', 'pg', 'postgresql', 'sqlite', 'sqlite3'
-  schema: null,         // Optional: initial schema object
-  resolverPath: null,   // Optional: path to models directory (default: process.cwd())
-  debug: false          // Optional: enable SQL debugging (default: false)
+  db: db, // Knex database instance
+  dbClient: 'mysql', // 'mysql', 'mysql2', 'pg', 'postgresql', 'sqlite', 'sqlite3'
+  schema: null, // Optional: initial schema object
+  resolverPath: null, // Optional: path to models directory (default: process.cwd())
+  debug: false, // Optional: enable SQL debugging (default: false)
 });
 
 // Process any CRUD request (automatically handles other_requests if present)
@@ -1581,64 +1658,66 @@ const modelInstance = korm.getModelInstance(modelDef);
 
 ### ProcessRequest Options
 
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `action` | string | Action to perform (list, show, create, update, delete, count, replace, upsert, sync) |
-| `where` | object/array | Filter conditions |
-| `data` | object/array | Data for create/update operations |
-| `select` | array/string | Columns to select |
-| `orderBy` | object/array/string | Sorting configuration |
-| `limit` | number | Maximum records to return |
-| `offset` | number | Records to skip |
-| `page` | number | Page number (alternative to offset) |
-| `with` | array | Related models to eager load |
-| `withWhere` | object | Filter conditions for eager loaded relations |
-| `groupBy` | array/string | Group by columns |
-| `having` | object | Having conditions |
-| `distinct` | boolean/array/string | Distinct results |
-| `join` | object/array | Join configuration |
-| `leftJoin` | object/array | Left join configuration |
-| `rightJoin` | object/array | Right join configuration |
-| `innerJoin` | object/array | Inner join configuration |
-| `conflict` | array | Conflict columns for upsert |
-| `other_requests` | object | Nested requests for related models |
+| Parameter        | Type                 | Description                                                                          |
+| ---------------- | -------------------- | ------------------------------------------------------------------------------------ |
+| `action`         | string               | Action to perform (list, show, create, update, delete, count, replace, upsert, sync) |
+| `where`          | object/array         | Filter conditions                                                                    |
+| `data`           | object/array         | Data for create/update operations                                                    |
+| `select`         | array/string         | Columns to select                                                                    |
+| `orderBy`        | object/array/string  | Sorting configuration                                                                |
+| `limit`          | number               | Maximum records to return                                                            |
+| `offset`         | number               | Records to skip                                                                      |
+| `page`           | number               | Page number (alternative to offset)                                                  |
+| `with`           | array                | Related models to eager load                                                         |
+| `withWhere`      | object               | Filter conditions for eager loaded relations                                         |
+| `groupBy`        | array/string         | Group by columns                                                                     |
+| `having`         | object               | Having conditions                                                                    |
+| `distinct`       | boolean/array/string | Distinct results                                                                     |
+| `join`           | object/array         | Join configuration                                                                   |
+| `leftJoin`       | object/array         | Left join configuration                                                              |
+| `rightJoin`      | object/array         | Right join configuration                                                             |
+| `innerJoin`      | object/array         | Inner join configuration                                                             |
+| `conflict`       | array                | Conflict columns for upsert                                                          |
+| `other_requests` | object               | Nested requests for related models                                                   |
 
 ### ProcessRequest Actions Summary
 
-| Action | Description | Required Fields |
-|--------|-------------|----------------|
-| `list` | Get multiple records | None (optional: `where`, `select`, `orderBy`, `limit`, `offset`) |
-| `show` | Get single record | `where` |
-| `create` | Create new record | `data` |
-| `update` | Update record(s) | `where`, `data` |
-| `delete` | Delete record(s) | `where` |
-| `count` | Count records | None (optional: `where`) |
-| `replace` | Replace record (MySQL) | `data` |
-| `upsert` | Insert or update | `data`, `conflict` |
-| `sync` | Upsert + delete | `data`, `conflict`, `where` |
+| Action    | Description              | Required Fields                                                  |
+| --------- | ------------------------ | ---------------------------------------------------------------- |
+| `list`    | Get multiple records     | None (optional: `where`, `select`, `orderBy`, `limit`, `offset`) |
+| `show`    | Get single record        | `where`                                                          |
+| `create`  | Create new record        | `data`                                                           |
+| `update`  | Update record(s)         | `where`, `data`                                                  |
+| `delete`  | Delete record(s)         | `where`                                                          |
+| `count`   | Count records            | None (optional: `where`)                                         |
+| `sum`     | Sum column or expression | `data.sumColumn` or `data.sumFormula` (optional: `where`)        |
+| `replace` | Replace record (MySQL)   | `data`                                                           |
+| `upsert`  | Insert or update         | `data`, `conflict`                                               |
+| `sync`    | Upsert + delete          | `data`, `conflict`, `where`                                      |
 
 ### Validation Rules
 
-| Rule | Description | Example |
-|------|-------------|---------|
-| `required` | Field is required | `'required'` |
-| `type:string` | Field must be string | `'type:string'` |
-| `type:number` | Field must be number | `'type:number'` |
-| `type:boolean` | Field must be boolean | `'type:boolean'` |
-| `type:array` | Field must be array | `'type:array'` |
-| `type:object` | Field must be object | `'type:object'` |
-| `type:longText` | Field must be string > 255 chars | `'type:longText'` |
-| `minLen:n` | Minimum string/array length | `'minLen:3'` |
-| `maxLen:n` | Maximum string/array length | `'maxLen:255'` |
-| `min:n` | Minimum numeric value | `'min:0'` |
-| `max:n` | Maximum numeric value | `'max:150'` |
-| `in:val1,val2` | Value must be in list | `'in:active,inactive,pending'` |
-| `regex:name` | Custom regex pattern (define in options) | `'regex:email'` |
-| `call:name` | Custom callback function (define in options) | `'call:myValidator'` |
-| `exists:table,column` | Value must exist in database table | `'exists:users,id'` |
-| `default:value` | Default value if not provided | `'default:active'` |
+| Rule                  | Description                                  | Example                        |
+| --------------------- | -------------------------------------------- | ------------------------------ |
+| `required`            | Field is required                            | `'required'`                   |
+| `type:string`         | Field must be string                         | `'type:string'`                |
+| `type:number`         | Field must be number                         | `'type:number'`                |
+| `type:boolean`        | Field must be boolean                        | `'type:boolean'`               |
+| `type:array`          | Field must be array                          | `'type:array'`                 |
+| `type:object`         | Field must be object                         | `'type:object'`                |
+| `type:longText`       | Field must be string > 255 chars             | `'type:longText'`              |
+| `minLen:n`            | Minimum string/array length                  | `'minLen:3'`                   |
+| `maxLen:n`            | Maximum string/array length                  | `'maxLen:255'`                 |
+| `min:n`               | Minimum numeric value                        | `'min:0'`                      |
+| `max:n`               | Maximum numeric value                        | `'max:150'`                    |
+| `in:val1,val2`        | Value must be in list                        | `'in:active,inactive,pending'` |
+| `regex:name`          | Custom regex pattern (define in options)     | `'regex:email'`                |
+| `call:name`           | Custom callback function (define in options) | `'call:myValidator'`           |
+| `exists:table,column` | Value must exist in database table           | `'exists:users,id'`            |
+| `default:value`       | Default value if not provided                | `'default:active'`             |
 
 **Rule Chaining:** Combine multiple rules with `|` pipe character:
+
 ```javascript
 {
   username: 'required|type:string|minLen:3|maxLen:50',
@@ -1651,14 +1730,14 @@ const modelInstance = korm.getModelInstance(modelDef);
 ### Library Exports
 
 ```javascript
-const { 
-  initializeKORM,      // Initialize KORM with database connection
-  helperUtility,       // Utility functions (file operations, string manipulation)
-  emitter,             // Event emitter instance
-  validate,            // Validation function
-  logger,              // Logger utility instance
-  lib,                 // Additional utilities
-  LibClasses           // Library classes (Emitter)
+const {
+  initializeKORM, // Initialize KORM with database connection
+  helperUtility, // Utility functions (file operations, string manipulation)
+  emitter, // Event emitter instance
+  validate, // Validation function
+  logger, // Logger utility instance
+  lib, // Additional utilities
+  LibClasses, // Library classes (Emitter)
 } = require('@dreamtree-org/korm-js');
 
 // lib contains:
@@ -1694,14 +1773,14 @@ logger.error('Error message');
 
 ### Log Levels
 
-| Level | Value | Description |
-|-------|-------|-------------|
-| `NONE` | 0 | Disable all logging |
-| `ERROR` | 1 | Only errors |
-| `WARN` | 2 | Warnings and errors (default) |
-| `INFO` | 3 | Info, warnings, and errors |
-| `LOG` | 4 | General logs and above |
-| `DEBUG` | 5 | All messages (most verbose) |
+| Level   | Value | Description                   |
+| ------- | ----- | ----------------------------- |
+| `NONE`  | 0     | Disable all logging           |
+| `ERROR` | 1     | Only errors                   |
+| `WARN`  | 2     | Warnings and errors (default) |
+| `INFO`  | 3     | Info, warnings, and errors    |
+| `LOG`   | 4     | General logs and above        |
+| `DEBUG` | 5     | All messages (most verbose)   |
 
 ### Configuration
 
@@ -1709,14 +1788,14 @@ logger.error('Error message');
 const { logger } = require('@dreamtree-org/korm-js');
 
 // Set log level programmatically
-logger.setLevel('debug');  // Show all logs
-logger.setLevel('warn');   // Only warnings and errors (default)
-logger.setLevel('error');  // Only errors
-logger.setLevel('none');   // Disable all logging
+logger.setLevel('debug'); // Show all logs
+logger.setLevel('warn'); // Only warnings and errors (default)
+logger.setLevel('error'); // Only errors
+logger.setLevel('none'); // Disable all logging
 
 // Enable/disable logging
-logger.disable();  // Temporarily disable all logging
-logger.enable();   // Re-enable logging
+logger.disable(); // Temporarily disable all logging
+logger.enable(); // Re-enable logging
 ```
 
 ### Environment Variable
@@ -1745,10 +1824,10 @@ const { logger } = require('@dreamtree-org/korm-js');
 
 // Create a child logger for a specific module
 const authLogger = logger.child('[Auth]');
-authLogger.info('User logged in');  // Output: [KORM][Auth] [INFO] User logged in
+authLogger.info('User logged in'); // Output: [KORM][Auth] [INFO] User logged in
 
 const dbLogger = logger.child('[DB]');
-dbLogger.debug('Query executed');   // Output: [KORM][DB] [DEBUG] Query executed
+dbLogger.debug('Query executed'); // Output: [KORM][DB] [DEBUG] Query executed
 ```
 
 ### Logger Options
@@ -1758,10 +1837,10 @@ const { Logger } = require('@dreamtree-org/korm-js').logger;
 
 // Create a custom logger instance
 const customLogger = new Logger({
-  prefix: '[MyApp]',      // Custom prefix (default: '[KORM]')
-  enabled: true,          // Enable/disable logging (default: true)
-  level: 'debug',         // Log level (default: 'warn' or KORM_LOG_LEVEL)
-  timestamps: true        // Include timestamps (default: false)
+  prefix: '[MyApp]', // Custom prefix (default: '[KORM]')
+  enabled: true, // Enable/disable logging (default: true)
+  level: 'debug', // Log level (default: 'warn' or KORM_LOG_LEVEL)
+  timestamps: true, // Include timestamps (default: false)
 });
 
 customLogger.info('Application started');
@@ -1799,7 +1878,7 @@ const { initializeKORM } = require('@dreamtree-org/korm-js');
 const korm = initializeKORM({
   db: db,
   dbClient: 'mysql',
-  debug: true  // Enable SQL debugging
+  debug: true, // Enable SQL debugging
 });
 ```
 
@@ -1841,10 +1920,10 @@ POST /api/Post/crud
 
 ### What's Included in sqlDebug
 
-| Index | Query Type | Description |
-|-------|------------|-------------|
-| 0 | Main Query | The primary SELECT query with all WHERE, ORDER BY, LIMIT clauses |
-| 1 | Count Query | The COUNT query used for pagination (only when limit > 0) |
+| Index | Query Type  | Description                                                      |
+| ----- | ----------- | ---------------------------------------------------------------- |
+| 0     | Main Query  | The primary SELECT query with all WHERE, ORDER BY, LIMIT clauses |
+| 1     | Count Query | The COUNT query used for pagination (only when limit > 0)        |
 
 ### Debug Mode Best Practices
 
@@ -1853,14 +1932,14 @@ POST /api/Post/crud
 const korm = initializeKORM({
   db: db,
   dbClient: 'mysql',
-  debug: process.env.NODE_ENV === 'development'
+  debug: process.env.NODE_ENV === 'development',
 });
 
 // Or use environment variable
 const korm = initializeKORM({
   db: db,
   dbClient: 'mysql',
-  debug: process.env.KORM_DEBUG === 'true'
+  debug: process.env.KORM_DEBUG === 'true',
 });
 ```
 
@@ -1880,14 +1959,14 @@ const db = knex({
     user: process.env.DB_USER || 'root',
     password: process.env.DB_PASS || 'password',
     database: process.env.DB_NAME || 'database_name',
-    port: process.env.DB_PORT || 3306
-  }
+    port: process.env.DB_PORT || 3306,
+  },
 });
 
 const korm = initializeKORM({
   db: db,
   dbClient: 'mysql',
-  debug: process.env.NODE_ENV === 'development'  // Enable SQL debugging in development
+  debug: process.env.NODE_ENV === 'development', // Enable SQL debugging in development
 });
 ```
 
@@ -1903,14 +1982,14 @@ const db = knex({
     user: process.env.DB_USER || 'username',
     password: process.env.DB_PASS || 'password',
     database: process.env.DB_NAME || 'database_name',
-    port: process.env.DB_PORT || 5432
-  }
+    port: process.env.DB_PORT || 5432,
+  },
 });
 
 const korm = initializeKORM({
   db: db,
   dbClient: 'pg',
-  debug: process.env.NODE_ENV === 'development'
+  debug: process.env.NODE_ENV === 'development',
 });
 ```
 
@@ -1922,14 +2001,14 @@ const knex = require('knex');
 const db = knex({
   client: 'sqlite3',
   connection: {
-    filename: process.env.DB_FILE || './database.sqlite'
-  }
+    filename: process.env.DB_FILE || './database.sqlite',
+  },
 });
 
 const korm = initializeKORM({
   db: db,
   dbClient: 'sqlite',
-  debug: process.env.NODE_ENV === 'development'
+  debug: process.env.NODE_ENV === 'development',
 });
 ```
 
@@ -1939,12 +2018,12 @@ const korm = initializeKORM({
 // Global error handler
 app.use((error, req, res, next) => {
   console.error('KORM Error:', error);
-  
+
   res.status(error.status || 500).json({
     success: false,
     message: 'Internal server error',
     error: process.env.NODE_ENV === 'development' ? error.message : 'Something went wrong',
-    stack: process.env.NODE_ENV === 'development' ? error.stack : undefined
+    stack: process.env.NODE_ENV === 'development' ? error.stack : undefined,
   });
 });
 
@@ -1960,22 +2039,22 @@ app.post('/api/:model/crud', async (req, res) => {
       return res.status(400).json({
         success: false,
         message: 'Validation failed',
-        errors: error.message
+        errors: error.message,
       });
     }
-    
+
     // Handle not found errors
     if (error.message.includes('not found')) {
       return res.status(404).json({
         success: false,
-        message: error.message
+        message: error.message,
       });
     }
-    
+
     // Handle other errors
     res.status(400).json({
       success: false,
-      message: error.message
+      message: error.message,
     });
   }
 });
@@ -2000,15 +2079,15 @@ const db = knex({
     user: process.env.DB_USER || 'root',
     password: process.env.DB_PASS || 'password',
     database: process.env.DB_NAME || 'my_database',
-    port: process.env.DB_PORT || 3306
-  }
+    port: process.env.DB_PORT || 3306,
+  },
 });
 
 // Initialize KORM
 const korm = initializeKORM({
   db: db,
   dbClient: 'mysql',
-  debug: process.env.NODE_ENV === 'development'  // SQL debugging in dev mode
+  debug: process.env.NODE_ENV === 'development', // SQL debugging in dev mode
 });
 
 // Initialize app
@@ -2023,7 +2102,7 @@ async function initApp() {
       helperUtility.file.createDirectory('schema');
       helperUtility.file.writeJSON('schema/schema.json', schema);
     }
-    
+
     // Sync database
     await korm.syncDatabase();
     console.log('✅ Database synced');