@dreamtree-org/korm-js 1.0.39 → 1.0.41

package/README.md

@@ -1,55 +1,58 @@
 # KORM-JS
 
-**Knowledge Object-Relational Mapping** - A powerful, modular ORM system for Node.js with dynamic database operations, complex queries, relationships, and nested requests.
+**Knowledge Object-Relational Mapping** - A powerful, modular ORM system for Node.js with dynamic database operations, complex queries, relationships, nested requests, and soft delete support.
 
-[![npm version](https://badge.fury.io/js/korm-js.svg)](https://badge.fury.io/js/korm-js)
+[![npm version](https://badge.fury.io/js/@dreamtree-org%2Fkorm-js.svg)](https://badge.fury.io/js/@dreamtree-org%2Fkorm-js)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
 ## Features
 
 - 🚀 **Multi-Database Support**: MySQL, PostgreSQL, SQLite
-- 🔧 **Dynamic Operations**: Create, Read, Update, Delete with ease
-- 🔍 **Advanced Querying**: Complex queries with relationships
+- 🔧 **Dynamic Operations**: Create, Read, Update, Delete, Replace, Upsert, Sync
+- 🔍 **Advanced Querying**: Complex queries with relationships, joins, and filtering
 - 🛡️ **Data Validation**: Built-in request validation with custom rules
 - 🔄 **Auto-Sync**: Automatic table schema synchronization
 - 📦 **Modular Design**: Use only what you need
 - 🎯 **Express.js Ready**: Perfect integration with Express applications
 - 🔄 **Schema Generation**: Auto-generate schemas from existing databases
+- 🗑️ **Soft Delete**: Built-in soft delete support with automatic filtering
+- 🎣 **Model Hooks**: Before, After, Validate, and Custom action hooks
 
 ## Installation
 
 ```bash
-npm install korm-js
+npm install @dreamtree-org/korm-js
 ```
 
-## Quick Start with Express.js and PostgreSQL
+## Quick Start with Express.js and MySQL
 
 ### 1. Basic Setup
 
 ```javascript
 require('dotenv').config();
 const express = require('express');
-const { initializeKORM, validate, helperUtility } = require('korm-js');
+const { initializeKORM, validate, helperUtility } = require('@dreamtree-org/korm-js');
 const knex = require('knex');
 
 const app = express();
 app.use(express.json());
 
-// Database configuration
+// MySQL database configuration
 const db = knex({
-  client: 'pg',
+  client: 'mysql2',
   connection: {
     host: process.env.DB_HOST || 'localhost',
-    user: process.env.DB_USER || 'your_user',
-    password: process.env.DB_PASS || 'your_pass',
-    database: process.env.DB_NAME || 'your_db'
+    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
   }
 });
 
-// Initialize KORM
+// Initialize KORM with MySQL
 const korm = initializeKORM({
   db: db,
-  dbClient: 'pg'
+  dbClient: 'mysql'
 });
 
 app.listen(3000, () => {
@@ -63,9 +66,11 @@ app.listen(3000, () => {
 async function initApp() {
   // Load existing schema if available
   let syncSchema = helperUtility.file.readJSON('schema/sync.json');
-  korm.setSchema(syncSchema);
+  if (syncSchema) {
+    korm.setSchema(syncSchema);
+  }
   
-  // Sync database with schema
+  // Sync database with schema (creates tables if they don't exist)
   await korm.syncDatabase().then(() => {
     console.log('✅ Database synced');
   });
@@ -103,7 +108,9 @@ app.get('/health', (req, res) => {
 });
 ```
 
-### 4. Example API Usage
+## Complete CRUD Operations Guide
+
+### 1. Create Operation
 
 ```javascript
 // Create a new record
@@ -114,11 +121,36 @@ POST /api/Users/crud
     "username": "john_doe",
     "email": "john@example.com",
     "first_name": "John",
-    "last_name": "Doe"
+    "last_name": "Doe",
+    "age": 30,
+    "is_active": true
   }
 }
 
-// Get all records
+// Response
+{
+  "message": "Record created successfully",
+  "data": [
+    {
+      "id": 1,
+      "username": "john_doe",
+      "email": "john@example.com",
+      "first_name": "John",
+      "last_name": "Doe",
+      "age": 30,
+      "is_active": true,
+      "created_at": "2024-01-01T00:00:00.000Z",
+      "updated_at": "2024-01-01T00:00:00.000Z"
+    }
+  ],
+  "success": true
+}
+```
+
+### 2. List Operation (Read Multiple Records)
+
+```javascript
+// Get all records with basic filtering
 POST /api/Users/crud
 {
   "action": "list",
@@ -128,103 +160,695 @@ POST /api/Users/crud
   "limit": 10
 }
 
-// Get single record
+// List with pagination
+POST /api/Users/crud
+{
+  "action": "list",
+  "select": ["id", "username", "email"],
+  "sort": [["created_at", "desc"]],
+  "limit": 10,
+  "offset": 20
+}
+
+// List with complex conditions
+POST /api/Users/crud
+{
+  "action": "list",
+  "where": {
+    "first_name": { "like": "%John%" },
+    "email": { "like": "%@example.com" },
+    "age": { ">=": 18, "<=": 65 },
+    "is_active": true
+  },
+  "select": ["id", "username", "email", "first_name", "last_name"],
+  "sort": [["created_at", "desc"], ["last_name", "asc"]],
+  "limit": 10
+}
+
+// Response
+{
+  "data": [
+    {
+      "id": 1,
+      "username": "john_doe",
+      "email": "john@example.com",
+      "first_name": "John",
+      "last_name": "Doe"
+    }
+  ],
+  "total": 1,
+  "page": 1,
+  "limit": 10
+}
+```
+
+### 3. Show Operation (Read Single Record)
+
+```javascript
+// Get single record by ID
 POST /api/Users/crud
 {
   "action": "show",
   "where": { "id": 1 }
 }
 
-// Update record
+// Get single record with multiple conditions
+POST /api/Users/crud
+{
+  "action": "show",
+  "where": {
+    "username": "john_doe",
+    "is_active": true
+  }
+}
+
+// Response
+{
+  "id": 1,
+  "username": "john_doe",
+  "email": "john@example.com",
+  "first_name": "John",
+  "last_name": "Doe",
+  "age": 30,
+  "is_active": true,
+  "created_at": "2024-01-01T00:00:00.000Z",
+  "updated_at": "2024-01-01T00:00:00.000Z"
+}
+```
+
+### 4. Update Operation
+
+```javascript
+// Update record by ID
 POST /api/Users/crud
 {
   "action": "update",
   "where": { "id": 1 },
   "data": {
     "first_name": "Jane",
-    "updated_at": "2024-01-01T00:00:00Z"
+    "last_name": "Smith",
+    "updated_at": new Date().toISOString()
+  }
+}
+
+// Update multiple records
+POST /api/Users/crud
+{
+  "action": "update",
+  "where": { "is_active": false },
+  "data": {
+    "is_active": true,
+    "updated_at": new Date().toISOString()
+  }
+}
+
+// Response
+{
+  "message": "Record updated successfully",
+  "data": [
+    {
+      "id": 1,
+      "first_name": "Jane",
+      "last_name": "Smith",
+      "updated_at": "2024-01-01T00:00:00.000Z"
+    }
+  ],
+  "success": true
+}
+```
+
+### 5. Delete Operation
+
+```javascript
+// Hard delete (permanent deletion)
+POST /api/Users/crud
+{
+  "action": "delete",
+  "where": { "id": 1 }
+}
+
+// Delete multiple records
+POST /api/Users/crud
+{
+  "action": "delete",
+  "where": { "is_active": false }
+}
+
+// Response
+{
+  "message": "Record deleted successfully",
+  "data": [/* deleted records */],
+  "success": true
+}
+```
+
+### 6. Count Operation
+
+```javascript
+// Count all records
+POST /api/Users/crud
+{
+  "action": "count"
+}
+
+// Count with conditions
+POST /api/Users/crud
+{
+  "action": "count",
+  "where": {
+    "is_active": true,
+    "created_at": { ">=": "2024-01-01" }
+  }
+}
+
+// Response
+42  // Number of matching records
+```
+
+### 7. Replace Operation
+
+```javascript
+// Replace record (MySQL specific - replaces entire row)
+POST /api/Users/crud
+{
+  "action": "replace",
+  "data": {
+    "id": 1,
+    "username": "john_doe_updated",
+    "email": "john.updated@example.com",
+    "first_name": "John",
+    "last_name": "Doe Updated"
+  }
+}
+
+// Response
+{
+  "message": "Record replaced successfully",
+  "data": [/* replaced record */],
+  "success": true
+}
+```
+
+### 8. Upsert Operation (Insert or Update)
+
+```javascript
+// Upsert record (insert if not exists, update if exists)
+POST /api/Users/crud
+{
+  "action": "upsert",
+  "data": {
+    "username": "john_doe",
+    "email": "john@example.com",
+    "first_name": "John",
+    "last_name": "Doe"
+  },
+  "conflict": ["username"]  // Conflict columns for MySQL
+}
+
+// Response
+{
+  "message": "Record upserted successfully",
+  "data": [/* upserted record */],
+  "success": true
+}
+```
+
+### 9. Sync Operation (Upsert + Delete)
+
+```javascript
+// Sync operation: upsert records and delete others matching where clause
+POST /api/Users/crud
+{
+  "action": "sync",
+  "data": {
+    "username": "john_doe",
+    "email": "john@example.com",
+    "first_name": "John",
+    "last_name": "Doe"
+  },
+  "conflict": ["username"],
+  "where": {
+    "created_at": { "<": "2024-01-01" }
+  }
+}
+
+// Response
+{
+  "message": "Record synced successfully",
+  "data": {
+    "insertOrUpdateQuery": [/* upserted records */],
+    "deleteQuery": [/* deleted records */]
+  },
+  "success": true
+}
+```
+
+## Advanced Querying
+
+### Complex Where Conditions
+
+```javascript
+// Multiple operators
+POST /api/Users/crud
+{
+  "action": "list",
+  "where": {
+    "age": { ">=": 18, "<=": 65 },
+    "email": { "like": "%@example.com" },
+    "first_name": { "in": ["John", "Jane", "Bob"] },
+    "is_active": true,
+    "created_at": { ">=": "2024-01-01", "<=": "2024-12-31" }
+  }
+}
+
+// OR conditions (using arrays)
+POST /api/Users/crud
+{
+  "action": "list",
+  "where": {
+    "or": [
+      { "first_name": "John" },
+      { "last_name": "Doe" }
+    ]
+  }
+}
+
+// NULL checks
+POST /api/Users/crud
+{
+  "action": "list",
+  "where": {
+    "deleted_at": null
+  }
+}
+```
+
+### Sorting
+
+```javascript
+// Single sort
+POST /api/Users/crud
+{
+  "action": "list",
+  "sort": [["created_at", "desc"]]
+}
+
+// Multiple sorts
+POST /api/Users/crud
+{
+  "action": "list",
+  "sort": [
+    ["is_active", "desc"],
+    ["created_at", "desc"],
+    ["last_name", "asc"]
+  ]
+}
+```
+
+### Joins
+
+```javascript
+// Inner join
+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"
+    }
+  ],
+  "where": { "users.is_active": true }
+}
+
+// Left join
+POST /api/Users/crud
+{
+  "action": "list",
+  "select": ["users.*", "profiles.bio"],
+  "join": [
+    {
+      "table": "user_profiles",
+      "as": "profiles",
+      "on": "users.id = profiles.user_id",
+      "type": "left"
+    }
+  ]
+}
+```
+
+## Relational Support with hasRelations
+
+### Understanding hasRelations Structure
+
+The `hasRelations` object in your schema defines relationships between models. Based on your actual schema file (`../borebell.in/schema/sync.json`), relationships use the following structure:
+
+#### One-to-One or Belongs-To Relationship (`type: "one"`)
+
+```json
+{
+  "UserDetail": {
+    "hasRelations": {
+      "User": {
+        "type": "one",
+        "table": "users",
+        "localKey": "user_id",
+        "foreignKey": "id"
+      }
+    }
+  }
+}
+```
+
+#### One-to-Many Relationship (`type: "many"`)
+
+```json
+{
+  "User": {
+    "hasRelations": {
+      "Post": {
+        "type": "many",
+        "table": "posts",
+        "localKey": "id",
+        "foreignKey": "user_id"
+      },
+      "Comment": {
+        "type": "many",
+        "table": "comments",
+        "localKey": "id",
+        "foreignKey": "user_id"
+      }
+    }
+  }
+}
+```
+
+#### Many-to-Many Relationship (using `through`)
+
+For many-to-many relationships, use the `through` key to specify the join/pivot table:
+
+```json
+{
+  "User": {
+    "hasRelations": {
+      "Role": {
+        "type": "many",
+        "table": "roles",
+        "localKey": "id",
+        "foreignKey": "id",
+        "through": "user_roles",
+        "throughLocalKey": "user_id",
+        "throughForeignKey": "role_id"
+      }
+    }
+  }
+}
+```
+
+**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"`)
+- `foreignKey`: The primary key in the related table (e.g., `"id"`)
+- `through`: **Required** - The join/pivot table name (e.g., `"user_roles"`)
+- `throughLocalKey`: The foreign key in the join table pointing to the current model (e.g., `"user_id"`)
+- `throughForeignKey`: The foreign key in the join table pointing to the related model (e.g., `"role_id"`)
+
+### Using Relationships in Queries
+
+#### Eager Loading with `with`
+
+```javascript
+// Load User with related Posts and Comments
+POST /api/User/crud
+{
+  "action": "list",
+  "where": { "id": 1 },
+  "with": ["Post", "Comment"]
+}
+
+// Nested relationships
+POST /api/User/crud
+{
+  "action": "list",
+  "where": { "id": 1 },
+  "with": ["Post.Comment", "Post.Like"]
+}
+
+// Multiple relationships
+POST /api/User/crud
+{
+  "action": "list",
+  "where": { "id": 1 },
+  "with": ["UserDetail", "Post", "Comment", "Like"]
+}
+```
+
+#### Filtering Related Data with Nested Where
+
+```javascript
+// Get users who have posts with specific hashtag
+POST /api/User/crud
+{
+  "action": "list",
+  "where": {
+    "Post.hashtag": "#OrganicFarming"
+  },
+  "with": ["Post"]
+}
+
+// Get posts with comments from specific user
+POST /api/Post/crud
+{
+  "action": "list",
+  "where": {
+    "Comment.user_id": 1
+  },
+  "with": ["Comment"]
+}
+```
+
+### Example: Complete Relationship Structure
+
+Based on your actual schema (`../borebell.in/schema/sync.json`):
+
+```json
+{
+  "User": {
+    "table": "users",
+    "hasRelations": {
+      "UserDetail": {
+        "type": "one",
+        "table": "user_details",
+        "localKey": "id",
+        "foreignKey": "user_id"
+      },
+      "Post": {
+        "type": "many",
+        "table": "posts",
+        "localKey": "id",
+        "foreignKey": "user_id"
+      },
+      "Comment": {
+        "type": "many",
+        "table": "comments",
+        "localKey": "id",
+        "foreignKey": "user_id"
+      },
+      "Like": {
+        "type": "many",
+        "table": "likes",
+        "localKey": "id",
+        "foreignKey": "user_id"
+      }
+    }
+  },
+  "Post": {
+    "table": "posts",
+    "hasRelations": {
+      "User": {
+        "type": "one",
+        "table": "users",
+        "localKey": "user_id",
+        "foreignKey": "id"
+      },
+      "Comment": {
+        "type": "many",
+        "table": "comments",
+        "localKey": "id",
+        "foreignKey": "post_id"
+      },
+      "Like": {
+        "type": "many",
+        "table": "likes",
+        "localKey": "id",
+        "foreignKey": "post_id"
+      }
+    }
+  }
+}
+```
+
+### Important Notes
+
+> **Always refer to your actual schema file** (`../borebell.in/schema/sync.json`) for the exact relationship definitions in your project. The structure shown above matches the format used in your schema.
+
+- `type: "one"` = One-to-One or Belongs-To relationship
+- `type: "many"` = One-to-Many relationship
+- `through` = Required for Many-to-Many relationships (specifies the join table)
+- `localKey` = The key in the current model
+- `foreignKey` = The key in the related table
+- `throughLocalKey` = The key in the join table pointing to current model (for many-to-many)
+- `throughForeignKey` = The key in the join table pointing to related model (for many-to-many)
+
+## Soft Delete Support
+
+### Enabling Soft Delete
+
+Create a model file at `models/Users.model.js`:
+
+```javascript
+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
+    console.log('User soft deleted:', data);
   }
 }
 
-// Delete record
+module.exports = Users;
+```
+
+### Using Soft Delete
+
+```javascript
+// When soft delete is enabled, delete action automatically sets deleted_at
 POST /api/Users/crud
 {
   "action": "delete",
   "where": { "id": 1 }
 }
 
-// Count records
+// List operation automatically filters out soft-deleted records
 POST /api/Users/crud
 {
-  "action": "count",
+  "action": "list",
   "where": { "is_active": true }
+  // Automatically adds: deleted_at IS NULL
 }
+
+// To see soft-deleted records, you need to query directly
+// (soft delete only affects list and delete operations)
 ```
 
-### 5. Advanced Querying Examples
+## Model Hooks
 
-```javascript
-// Complex search with multiple conditions
-POST /api/Users/crud
-{
-  "action": "list",
-  "where": {
-    "first_name": { "like": "%John%" },
-    "email": { "like": "%@example.com" },
-    "is_active": true
-  },
-  "select": ["id", "username", "email", "first_name", "last_name"],
-  "sort": [["created_at", "desc"]],
-  "limit": 10
-}
+### Creating Model Hooks
 
-// Pagination with offset
-POST /api/Users/crud
-{
-  "action": "list",
-  "select": ["id", "username", "email", "first_name", "last_name"],
-  "sort": [["created_at", "desc"]],
-  "limit": 10,
-  "offset": 20
-}
+Create a model file at `models/Users.model.js`:
 
-// Count with conditions
-POST /api/Users/crud
-{
-  "action": "count",
-  "where": {
-    "is_active": true,
-    "created_at": { ">=": "2024-01-01" }
+```javascript
+class Users {
+  // Validation hook - runs before any action
+  async validate({ model, action, request, context, db, utils, controller }) {
+    if (action === 'create' || action === 'update') {
+      if (!request.data.email) {
+        throw new Error('Email is required');
+      }
+      // Check if email already exists
+      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 hook - runs before the action executes
+  async beforeCreate({ model, action, request, context, db, utils, controller }) {
+    // Add timestamps
+    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
+    request.data.updated_at = new Date();
+    return request.data;
+  }
+  
+  // After hook - runs after the action executes
+  async afterCreate({ model, action, data, request, context, db, utils, controller }) {
+    // Log creation
+    console.log('User created:', data);
+    // Send welcome email, 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}`);
+  }
+  
+  // Soft delete support
+  hasSoftDelete = true;
 }
 
-// Join queries (if relationships are defined)
+module.exports = Users;
+```
+
+### Using Custom Actions
+
+```javascript
+// Call custom action
 POST /api/Users/crud
 {
-  "action": "list",
-  "select": ["id", "username", "email"],
-  "join": [
-    {
-      "table": "user_profiles",
-      "on": "users.id = user_profiles.user_id"
-    }
-  ],
-  "where": { "users.is_active": true }
+  "action": "activate",
+  "where": { "id": 1 }
 }
 ```
 
-### 6. Data Validation Example
+## Data Validation
+
+### Basic Validation
 
 ```javascript
-const { validate } = require('korm-js');
+const { validate } = require('@dreamtree-org/korm-js');
 
 // Define validation rules
 const userValidationRules = {
-  username: 'required|type:string|maxLen:50',
+  username: 'required|type:string|minLen:3|maxLen:50',
   email: 'required|type:string|maxLen:255',
   first_name: 'required|type:string|maxLen:100',
   last_name: 'required|type:string|maxLen:100',
-  age: 'type:number|min:0|max:150'
+  age: 'type:number|min:0|max:150',
+  is_active: 'type:boolean'
 };
 
 // Validate and create user
@@ -235,24 +859,20 @@ app.post('/api/users/validate', async (req, res) => {
     
     const result = await korm.processRequest({
       action: 'create',
-      data: {
-        ...validatedData,
-        created_at: new Date(),
-        updated_at: new Date()
-      }
+      data: validatedData
     }, 'Users');
     
     res.status(201).json({
       success: true,
       message: 'User created successfully',
-      data: result.data
+      data: result
     });
   } catch (error) {
     if (error.name === 'ValidationError') {
       return res.status(400).json({
         success: false,
         message: 'Validation failed',
-        errors: error.message.details
+        errors: error.message
       });
     }
     
@@ -265,28 +885,102 @@ app.post('/api/users/validate', async (req, res) => {
 });
 ```
 
-### 7. Schema Structure Example
+### Advanced Validation
+
+```javascript
+const { validate } = require('@dreamtree-org/korm-js');
+
+// Advanced validation rules
+const advancedRules = {
+  username: 'required|type:string|regex:username',
+  email: 'required|type:string|regex:email',
+  phone: 'regex:phone',
+  password: 'required|type:string|minLen:8',
+  confirm_password: 'required|type:string|match:password',
+  status: 'in:active,inactive,pending',
+  user_id: 'exists:users,id'
+};
+
+const customRegex = {
+  username: /^[a-zA-Z0-9_]+$/,
+  email: /^[^\s@]+@[^\s@]+\.[^\s@]+$/,
+  phone: /^\+?[\d\s-()]{10,15}$/
+};
+
+const validatedData = await validate(data, advancedRules, { customRegex });
+```
+
+## Nested Requests
+
+```javascript
+// Process multiple related requests in one call
+POST /api/Users/crud
+{
+  "action": "show",
+  "where": { "id": 1 },
+  "other_requests": {
+    "Posts": {
+      "action": "list",
+      "where": { "user_id": 1 },
+      "limit": 10
+    },
+    "Comments": {
+      "action": "list",
+      "where": { "user_id": 1 },
+      "limit": 5
+    }
+  }
+}
+
+// Response includes nested data
+{
+  "id": 1,
+  "username": "john_doe",
+  "email": "john@example.com",
+  "other_responses": {
+    "Posts": {
+      "data": [/* posts */],
+      "total": 10
+    },
+    "Comments": {
+      "data": [/* comments */],
+      "total": 5
+    }
+  }
+}
+```
+
+## Schema Structure
+
+### Example Schema (Auto-generated from MySQL)
 
 ```javascript
-// Example schema structure (auto-generated)
 {
   "Users": {
     "table": "users",
     "alias": "Users",
+    "modelName": "Users",
     "columns": {
-      "id": "bigint|size:8|default:nextval('users_id_seq'::regclass)",
-      "username": "character varying|size:255",
-      "email": "character varying|size:255",
-      "first_name": "character varying|size:255|nullable",
-      "last_name": "character varying|size:255|nullable",
-      "is_active": "boolean|default:true",
-      "created_at": "timestamp with time zone|default:now()",
-      "updated_at": "timestamp with time zone|default:now()"
+      "id": "bigint|size:8|unsigned|auto_increment",
+      "username": "varchar|size:255",
+      "email": "varchar|size:255",
+      "first_name": "varchar|size:255|nullable",
+      "last_name": "varchar|size:255|nullable",
+      "age": "int|size:4|nullable",
+      "is_active": "tinyint|size:1|default:1",
+      "created_at": "timestamp|default:CURRENT_TIMESTAMP",
+      "updated_at": "timestamp|default:CURRENT_TIMESTAMP|onUpdate:CURRENT_TIMESTAMP",
+      "deleted_at": "timestamp|nullable"
     },
-    "modelName": "Users",
     "seed": [],
     "hasRelations": {},
-    "indexes": []
+    "indexes": [
+      {
+        "name": "idx_users_email",
+        "columns": ["email"],
+        "unique": true
+      }
+    ]
   }
 }
 ```
@@ -298,12 +992,15 @@ app.post('/api/users/validate', async (req, res) => {
 ```javascript
 const korm = initializeKORM({
   db: db,
-  dbClient: 'pg'  // or 'mysql', 'sqlite'
+  dbClient: 'mysql'  // or 'pg', 'sqlite'
 });
 
 // Process any CRUD request
 const result = await korm.processRequest(requestBody, modelName);
 
+// Process request with nested requests
+const result = await korm.processRequestWithOthers(requestBody, modelName);
+
 // Set schema manually
 korm.setSchema(schemaObject);
 
@@ -314,139 +1011,100 @@ await korm.syncDatabase();
 const schema = await korm.generateSchema();
 ```
 
-### ProcessRequest Actions
-
-```javascript
-// List records
-{
-  "action": "list",
-  "where": { "is_active": true },
-  "select": ["id", "name", "email"],
-  "sort": [["created_at", "desc"]],
-  "limit": 10,
-  "offset": 0
-}
-
-// Show single record
-{
-  "action": "show",
-  "where": { "id": 1 }
-}
-
-// Create record
-{
-  "action": "create",
-  "data": { "name": "John", "email": "john@example.com" }
-}
-
-// Update record
-{
-  "action": "update",
-  "where": { "id": 1 },
-  "data": { "name": "Jane" }
-}
-
-// Delete record
-{
-  "action": "delete",
-  "where": { "id": 1 }
-}
-
-// Count records
-{
-  "action": "count",
-  "where": { "is_active": true }
-}
-```
-
-### Validation Rules
+### ControllerWrapper Static Methods
 
 ```javascript
-const { validate } = require('korm-js');
-
-// Basic validation rules
-const rules = {
-  username: 'required|type:string|minLen:3|maxLen:30',
-  email: 'required|type:string|maxLen:255',
-  age: 'type:number|min:0|max:150',
-  status: 'in:active,inactive,pending'
-};
+const { ControllerWrapper } = require('@dreamtree-org/korm-js');
 
-// Advanced validation with custom patterns
-const advancedRules = {
-  username: 'required|type:string|regex:username',
-  email: 'required|type:string|regex:email',
-  phone: 'regex:phone',
-  user_id: 'exists:users,id'
-};
+// Load model class
+const ModelClass = ControllerWrapper.loadModelClass('Users');
 
-const customRegex = {
-  username: /^[a-zA-Z0-9_]+$/,
-  email: /^[^\s@]+@[^\s@]+\.[^\s@]+$/,
-  phone: /^\+?[\d\s-()]{10,15}$/
-};
+// Get model instance
+const modelInstance = ControllerWrapper.getModelInstance(model);
 
-const validatedData = await validate(data, rules, { customRegex });
+// Generate schema
+const schema = await ControllerWrapper.generateSchema();
 ```
 
-### Helper Utilities
+### ProcessRequest Actions Summary
 
-```javascript
-const { helperUtility } = require('korm-js');
+| Action | Description | Required Fields |
+|--------|-------------|----------------|
+| `create` | Create new record | `data` |
+| `list` | Get multiple records | None (optional: `where`, `select`, `sort`, `limit`, `offset`) |
+| `show` | Get single record | `where` |
+| `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` |
 
-// File operations
-helperUtility.file.readJSON('path/to/file.json');
-helperUtility.file.writeJSON('path/to/file.json', data);
-helperUtility.file.createDirectory('path/to/directory');
+### Validation Rules
 
-// Other utilities available through helperUtility
-```
+| 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'` |
+| `match:field` | Must match another field | `confirm_password: 'match:password'` |
+| `exists:table,column` | Value must exist in table | `user_id: 'exists:users,id'` |
 
 ## Database Support
 
-### PostgreSQL (Recommended)
+### MySQL (Current Guide)
+
 ```javascript
 const knex = require('knex');
 
 const db = knex({
-  client: 'pg',
+  client: 'mysql2',
   connection: {
     host: process.env.DB_HOST || 'localhost',
-    user: process.env.DB_USER || 'username',
+    user: process.env.DB_USER || 'root',
     password: process.env.DB_PASS || 'password',
     database: process.env.DB_NAME || 'database_name',
-    port: process.env.DB_PORT || 5432
+    port: process.env.DB_PORT || 3306
   }
 });
 
 const korm = initializeKORM({
   db: db,
-  dbClient: 'pg'
+  dbClient: 'mysql'
 });
 ```
 
-### MySQL
+### PostgreSQL
+
 ```javascript
 const knex = require('knex');
 
 const db = knex({
-  client: 'mysql2',
+  client: 'pg',
   connection: {
     host: process.env.DB_HOST || 'localhost',
     user: process.env.DB_USER || 'username',
     password: process.env.DB_PASS || 'password',
     database: process.env.DB_NAME || 'database_name',
-    port: process.env.DB_PORT || 3306
+    port: process.env.DB_PORT || 5432
   }
 });
 
 const korm = initializeKORM({
   db: db,
-  dbClient: 'mysql'
+  dbClient: 'pg'
 });
 ```
 
 ### SQLite
+
 ```javascript
 const knex = require('knex');
 
@@ -466,15 +1124,123 @@ const korm = initializeKORM({
 ## Error Handling
 
 ```javascript
+// Global error handler
 app.use((error, req, res, next) => {
   console.error('KORM Error:', error);
   
-  res.status(500).json({
+  res.status(error.status || 500).json({
     success: false,
     message: 'Internal server error',
-    error: process.env.NODE_ENV === 'development' ? error.message : 'Something went wrong'
+    error: process.env.NODE_ENV === 'development' ? error.message : 'Something went wrong',
+    stack: process.env.NODE_ENV === 'development' ? error.stack : undefined
   });
 });
+
+// Route-specific error handling
+app.post('/api/:model/crud', async (req, res) => {
+  try {
+    const { model } = req.params;
+    const result = await korm.processRequest(req.body, model);
+    res.json(result);
+  } catch (error) {
+    // Handle validation errors
+    if (error.name === 'ValidationError') {
+      return res.status(400).json({
+        success: false,
+        message: 'Validation failed',
+        errors: error.message
+      });
+    }
+    
+    // Handle not found errors
+    if (error.message.includes('not found')) {
+      return res.status(404).json({
+        success: false,
+        message: error.message
+      });
+    }
+    
+    // Handle other errors
+    res.status(400).json({
+      success: false,
+      message: error.message
+    });
+  }
+});
+```
+
+## Complete Example Application
+
+```javascript
+require('dotenv').config();
+const express = require('express');
+const { initializeKORM, validate, helperUtility } = require('@dreamtree-org/korm-js');
+const knex = require('knex');
+
+const app = express();
+app.use(express.json());
+
+// MySQL configuration
+const db = knex({
+  client: 'mysql2',
+  connection: {
+    host: process.env.DB_HOST || 'localhost',
+    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
+  }
+});
+
+// Initialize KORM
+const korm = initializeKORM({
+  db: db,
+  dbClient: 'mysql'
+});
+
+// Initialize app
+async function initApp() {
+  try {
+    // Load or generate schema
+    let schema = helperUtility.file.readJSON('schema/schema.json');
+    if (schema) {
+      korm.setSchema(schema);
+    } else {
+      schema = await korm.generateSchema();
+      helperUtility.file.createDirectory('schema');
+      helperUtility.file.writeJSON('schema/schema.json', schema);
+    }
+    
+    // Sync database
+    await korm.syncDatabase();
+    console.log('✅ Database synced');
+  } catch (error) {
+    console.error('❌ Initialization error:', error);
+  }
+}
+
+// Generic CRUD endpoint
+app.post('/api/:model/crud', async (req, res) => {
+  try {
+    const { model } = req.params;
+    const result = await korm.processRequest(req.body, model);
+    res.json(result);
+  } catch (error) {
+    res.status(400).json({ error: error.message });
+  }
+});
+
+// Health check
+app.get('/health', (req, res) => {
+  res.send('OK');
+});
+
+// Start server
+const PORT = process.env.PORT || 3000;
+app.listen(PORT, async () => {
+  console.log(`🚀 Server running on http://localhost:${PORT}`);
+  await initApp();
+});
 ```
 
 ## Contributing
@@ -491,7 +1257,7 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
 
 ## Support
 
-If you have any questions or need help, please open an issue on GitHub or contact us at [partha.preetham.krishna@gmail.com](mailto:partha.preetham.krishna@gmail.com).
+If you have any questions or need help, please open an issue on GitHub or contact us at [partha.preetham.krishna@gmail.com](mailto:partha-preetham.krishna@gmail.com).
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dreamtree-org/korm-js",
-  "version": "1.0.39",
+  "version": "1.0.41",
   "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",