@dreamtree-org/korm-js 1.0.44 → 1.0.46

package/README.md

@@ -156,7 +156,7 @@ POST /api/Users/crud
   "action": "list",
   "where": { "is_active": true },
   "select": ["id", "username", "email", "first_name", "last_name"],
-  "sort": [["created_at", "desc"]],
+  "orderBy": { "column": "created_at", "direction": "desc" },
   "limit": 10
 }
 
@@ -165,7 +165,7 @@ POST /api/Users/crud
 {
   "action": "list",
   "select": ["id", "username", "email"],
-  "sort": [["created_at", "desc"]],
+  "orderBy": { "column": "created_at", "direction": "desc" },
   "limit": 10,
   "offset": 20
 }
@@ -175,13 +175,16 @@ POST /api/Users/crud
 {
   "action": "list",
   "where": {
-    "first_name": { "like": "%John%" },
-    "email": { "like": "%@example.com" },
-    "age": { ">=": 18, "<=": 65 },
+    "first_name": "%John%",
+    "email": "%@example.com",
+    "age": "><18,65",
     "is_active": true
   },
   "select": ["id", "username", "email", "first_name", "last_name"],
-  "sort": [["created_at", "desc"], ["last_name", "asc"]],
+  "orderBy": [
+    { "column": "created_at", "direction": "desc" },
+    { "column": "last_name", "direction": "asc" }
+  ],
   "limit": 10
 }
 
@@ -315,7 +318,7 @@ POST /api/Users/crud
   "action": "count",
   "where": {
     "is_active": true,
-    "created_at": { ">=": "2024-01-01" }
+    "created_at": ">=2024-01-01"
   }
 }
 
@@ -386,7 +389,7 @@ POST /api/Users/crud
   },
   "conflict": ["username"],
   "where": {
-    "created_at": { "<": "2024-01-01" }
+    "created_at": "<2024-01-01"
   }
 }
 
@@ -411,11 +414,11 @@ POST /api/Users/crud
 {
   "action": "list",
   "where": {
-    "age": { ">=": 18, "<=": 65 },
-    "email": { "like": "%@example.com" },
-    "first_name": { "in": ["John", "Jane", "Bob"] },
+    "age": "><18,65",
+    "email": "%@example.com",
+    "first_name": "[]John,Jane,Bob",
     "is_active": true,
-    "created_at": { ">=": "2024-01-01", "<=": "2024-12-31" }
+    "created_at": "><2024-01-01,2024-12-31"
   }
 }
 
@@ -440,7 +443,7 @@ POST /api/Users/crud
   "action": "list",
   "where": {
     "status": "active",
-    "Or:name": "like:%john%"
+    "Or:name": "%john%"
   }
 }
 // Generated SQL: WHERE status = 'active' OR name LIKE '%john%'
@@ -463,7 +466,7 @@ POST /api/Users/crud
   "action": "list",
   "where": {
     "status": "active",
-    "age": { ">=": 18 },
+    "age": ">=18",
     "Or:role": "admin",
     "Or:role": "super_admin"
   }
@@ -476,8 +479,8 @@ POST /api/Users/crud
   "action": "list",
   "where": {
     "department": "sales",
-    "Or:email": { "like": "%@company.com" },
-    "Or:created_at": { ">=": "2024-01-01" }
+    "Or:email": "%@company.com",
+    "Or:created_at": ">=2024-01-01"
   }
 }
 // Generated SQL: WHERE department = 'sales' OR email LIKE '%@company.com' OR created_at >= '2024-01-01'
@@ -527,7 +530,7 @@ POST /api/Users/crud
 {
   "action": "list",
   "where": [
-    { "is_active": true, "age": { ">=": 18 } },
+    { "is_active": true, "age": ">=18" },
     { "Or:status": "verified" },
     { "Or:role": "admin" }
   ]
@@ -541,7 +544,7 @@ POST /api/Users/crud
   "where": [
     { "department": "engineering" },
     { "Or:department": "product" },
-    { "created_at": { ">=": "2024-01-01" } }
+    { "created_at": ">=2024-01-01" }
   ]
 }
 // Generated SQL: WHERE department = 'engineering' OR department = 'product' AND created_at >= '2024-01-01'
@@ -549,79 +552,133 @@ POST /api/Users/crud
 
 ### Where Operators Reference
 
-| Operator | Description | Example |
-|----------|-------------|---------|
-| `=` (default) | Equals | `"status": "active"` |
-| `>=` | Greater than or equal | `"age": { ">=": 18 }` |
-| `<=` | Less than or equal | `"age": { "<=": 65 }` |
-| `>` | Greater than | `"price": { ">": 100 }` |
-| `<` | Less than | `"price": { "<": 500 }` |
-| `!=` | Not equal | `"status": { "!=": "deleted" }` |
-| `like` | Pattern matching | `"name": { "like": "%john%" }` |
-| `in` | Value in list | `"status": ["active", "pending"]` |
-| `notIn` | Value not in list | `"role": { "notIn": ["banned", "suspended"] }` |
-| `between` | Range (inclusive) | `"age": { "between": [18, 65] }` |
-| `notBetween` | Outside range | `"score": { "notBetween": [0, 50] }` |
-| `null` | IS NULL check | `"deleted_at": null` |
-| `Or:column` | OR condition prefix | `"Or:name": "John"` |
-
-### Sorting
+| 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:**
+
+```javascript
+// Complex query with string-based operators
+POST /api/Users/crud
+{
+  "action": "list",
+  "where": {
+    "age": ">=18",
+    "status": "!deleted",
+    "name": "%john%",
+    "role": "[]admin,moderator,editor",
+    "score": "><50,100"
+  }
+}
+// SQL: WHERE age >= 18 AND status != 'deleted' AND name LIKE '%john%' 
+//      AND role IN ('admin', 'moderator', 'editor') AND score BETWEEN 50 AND 100
+```
+
+### Sorting (orderBy)
 
 ```javascript
-// Single sort
+// Single sort with object
+POST /api/Users/crud
+{
+  "action": "list",
+  "orderBy": { "column": "created_at", "direction": "desc" }
+}
+
+// Single sort with string (default: ascending)
 POST /api/Users/crud
 {
   "action": "list",
-  "sort": [["created_at", "desc"]]
+  "orderBy": "created_at"
 }
 
-// Multiple sorts
+// Multiple sorts with array of objects
 POST /api/Users/crud
 {
   "action": "list",
-  "sort": [
-    ["is_active", "desc"],
-    ["created_at", "desc"],
-    ["last_name", "asc"]
+  "orderBy": [
+    { "column": "is_active", "direction": "desc" },
+    { "column": "created_at", "direction": "desc" },
+    { "column": "last_name", "direction": "asc" }
   ]
 }
+
+// Multiple sorts with array of strings (all ascending)
+POST /api/Users/crud
+{
+  "action": "list",
+  "orderBy": ["is_active", "created_at", "last_name"]
+}
 ```
 
 ### Joins
 
 ```javascript
-// Inner join
+// Inner join (using innerJoin parameter)
 POST /api/Users/crud
 {
   "action": "list",
-  "select": ["users.id", "users.username", "profiles.bio"],
-  "join": [
-    {
-      "table": "user_profiles",
-      "as": "profiles",
-      "on": "users.id = profiles.user_id",
-      "type": "inner"
-    }
-  ],
+  "select": ["users.id", "users.username", "user_profiles.bio"],
+  "innerJoin": {
+    "table": "user_profiles",
+    "on": "users.id = user_profiles.user_id"
+  },
   "where": { "users.is_active": true }
 }
 
-// Left join
+// Left join (using leftJoin parameter)
 POST /api/Users/crud
 {
   "action": "list",
-  "select": ["users.*", "profiles.bio"],
-  "join": [
-    {
-      "table": "user_profiles",
-      "as": "profiles",
-      "on": "users.id = profiles.user_id",
-      "type": "left"
-    }
+  "select": ["users.*", "user_profiles.bio"],
+  "leftJoin": {
+    "table": "user_profiles",
+    "on": "users.id = user_profiles.user_id"
+  }
+}
+
+// Multiple joins (array format)
+POST /api/Users/crud
+{
+  "action": "list",
+  "select": ["users.*", "profiles.bio", "roles.name"],
+  "leftJoin": [
+    { "table": "user_profiles", "on": "users.id = user_profiles.user_id" },
+    { "table": "roles", "on": "users.role_id = roles.id" }
   ]
 }
+
+// Join with explicit columns
+POST /api/Users/crud
+{
+  "action": "list",
+  "innerJoin": {
+    "table": "orders",
+    "first": "users.id",
+    "operator": "=",
+    "second": "orders.user_id"
+  }
+}
 ```
 
+**Available join types:**
+- `join` - Regular join
+- `innerJoin` - Inner join
+- `leftJoin` - Left join
+- `rightJoin` - Right join
+
 ## Relational Support with hasRelations
 
 ### Understanding hasRelations Structure
@@ -881,6 +938,9 @@ Create a model file at `models/Users.model.js`:
 
 ```javascript
 class Users {
+  // Soft delete support (property, not method)
+  hasSoftDelete = true;
+
   // Validation hook - runs before any action
   async validate({ model, action, request, context, db, utils, controller }) {
     if (action === 'create' || action === 'update') {
@@ -897,61 +957,91 @@ class Users {
     }
   }
   
-  // Before hook - runs before the action executes
+  // 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 }) {
-    // Add timestamps
+    // Modify request data before insert
     request.data.created_at = new Date();
     request.data.updated_at = new Date();
     return request.data;
   }
   
   async beforeUpdate({ model, action, request, context, db, utils, controller }) {
-    // Update timestamp
+    // Modify request data before update
     request.data.updated_at = new Date();
     return request.data;
   }
   
-  // After hook - runs after the action executes
+  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 }) {
-    // Log creation
+    // data contains the result of the action
     console.log('User created:', data);
-    // Send welcome email, etc.
+    // Send welcome email, trigger notifications, etc.
     return data;
   }
   
   async afterUpdate({ model, action, data, request, context, db, utils, controller }) {
-    // Log update
     console.log('User updated:', data);
     return data;
   }
   
-  // Custom action hook
-  async onCustomAction({ model, action, request, context, db, utils, controller }) {
-    // Handle custom actions like 'activate', 'deactivate', etc.
-    if (action === 'activate') {
-      return await db('users')
-        .where(request.where)
-        .update({ is_active: true, updated_at: new Date() });
-    }
-    throw new Error(`Unknown custom action: ${action}`);
+  async afterList({ model, action, data, request, context, db, utils, controller }) {
+    // Modify list results before returning
+    return data;
   }
   
-  // Soft delete support
-  hasSoftDelete = true;
+  // Custom action hooks
+  // Method naming: on{Action}Action (e.g., onActivateAction, onDeactivateAction)
+  async onActivateAction({ model, action, request, context, db, utils, controller }) {
+    return await db('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)
+      .update({ is_active: false, updated_at: new Date() });
+  }
 }
 
 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 |
+
 ### Using Custom Actions
 
 ```javascript
-// Call custom action
+// Call custom action - triggers on{Action}Action hook
 POST /api/Users/crud
 {
   "action": "activate",
   "where": { "id": 1 }
 }
+
+POST /api/Users/crud
+{
+  "action": "deactivate", 
+  "where": { "id": 1 }
+}
 ```
 
 ## Data Validation
@@ -1109,49 +1199,67 @@ POST /api/Users/crud
 ### KORM Instance Methods
 
 ```javascript
+const { initializeKORM } = require('@dreamtree-org/korm-js');
+
 const korm = initializeKORM({
-  db: db,
-  dbClient: 'mysql'  // or 'pg', 'sqlite'
+  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())
 });
 
-// Process any CRUD request
-const result = await korm.processRequest(requestBody, modelName);
+// Process any CRUD request (automatically handles other_requests if present)
+const result = await korm.processRequest(requestBody, modelName, context);
 
-// Process request with nested requests
-const result = await korm.processRequestWithOthers(requestBody, modelName);
+// Process request with nested requests (legacy - now same as processRequest)
+const result = await korm.processRequestWithOthers(requestBody, modelName, context);
 
 // Set schema manually
 korm.setSchema(schemaObject);
 
-// Sync database with schema
+// Sync database with schema (creates/updates tables)
 await korm.syncDatabase();
 
 // Generate schema from existing database
 const schema = await korm.generateSchema();
-```
-
-### ControllerWrapper Static Methods
 
-```javascript
-const { ControllerWrapper } = require('@dreamtree-org/korm-js');
-
-// Load model class
-const ModelClass = ControllerWrapper.loadModelClass('Users');
+// Load model class from models/{ModelName}.model.js
+const ModelClass = korm.loadModelClass('Users');
 
 // Get model instance
-const modelInstance = ControllerWrapper.getModelInstance(model);
-
-// Generate schema
-const schema = await ControllerWrapper.generateSchema();
+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 |
+| `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 |
 |--------|-------------|----------------|
-| `create` | Create new record | `data` |
-| `list` | Get multiple records | None (optional: `where`, `select`, `sort`, `limit`, `offset`) |
+| `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`) |
@@ -1163,19 +1271,58 @@ const schema = await ControllerWrapper.generateSchema();
 
 | Rule | Description | Example |
 |------|-------------|---------|
-| `required` | Field is required | `username: 'required'` |
-| `type:string` | Field must be string | `name: 'type:string'` |
-| `type:number` | Field must be number | `age: 'type:number'` |
-| `type:boolean` | Field must be boolean | `is_active: 'type:boolean'` |
-| `minLen:n` | Minimum length | `username: 'minLen:3'` |
-| `maxLen:n` | Maximum length | `email: 'maxLen:255'` |
-| `min:n` | Minimum value | `age: 'min:0'` |
-| `max:n` | Maximum value | `age: 'max:150'` |
-| `in:val1,val2` | Value must be in list | `status: 'in:active,inactive'` |
-| `regex:name` | Custom regex pattern | `email: 'regex:email'` |
-| `call:name` | Custom callback function | `field: 'call:myValidator'` |
-| `exists:table,column` | Value must exist in table | `user_id: 'exists:users,id'` |
-| `default:value` | Default value if not provided | `status: 'default:active'` |
+| `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',
+  email: 'required|type:string|regex:email',
+  age: 'type:number|min:0|max:150',
+  status: 'in:active,inactive|default:active'
+}
+```
+
+### Library Exports
+
+```javascript
+const { 
+  initializeKORM,      // Initialize KORM with database connection
+  helperUtility,       // Utility functions (file operations, string manipulation)
+  emitter,             // Event emitter instance
+  validate,            // Validation function
+  lib,                 // Additional utilities
+  LibClasses           // Library classes (Emitter)
+} = require('@dreamtree-org/korm-js');
+
+// lib contains:
+// - createValidationMiddleware(rules, options) - Express middleware
+// - validateEmail(email) - Email validation
+// - validatePassword(password) - Password strength validation
+// - validatePhone(phone) - Phone number validation
+// - validatePAN(pan) - PAN validation (India)
+// - validateAadhaar(aadhaar) - Aadhaar validation (India)
+
+// helperUtility.file contains:
+// - readJSON(path) - Read JSON file
+// - writeJSON(path, data) - Write JSON file
+// - createDirectory(path) - Create directory
+```
 
 ## Database Support
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dreamtree-org/korm-js",
-  "version": "1.0.44",
+  "version": "1.0.46",
   "description": "Knowledge Object-Relational Mapping - A powerful, modular ORM system for Node.js with dynamic database operations, complex queries, relationships, and nested requests",
   "author": {
     "name": "Partha Preetham Krishna",