sehawq.db 2.4.2 → 3.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sehawq.db",
-  "version": "2.4.2",
+  "version": "3.0.0",
   "description": "Lightweight JSON-based key-value database with namespaces, array & math helpers.",
   "main": "src/index.js",
   "keywords": [
@@ -11,5 +11,10 @@
     "lightweight"
   ],
   "author": "Omer (sehawq)",
-  "license": "MIT"
+  "license": "MIT",
+  "dependencies": {
+    "cors": "^2.8.5",
+    "express": "^5.1.0",
+    "socket.io": "^4.8.1"
+  }
 }

package/readme.md

@@ -1,306 +1,241 @@
-# sehawq.db  
+# sehawq.db 🚀
 
 [![npm version](https://img.shields.io/npm/v/sehawq.db.svg)](https://www.npmjs.com/package/sehawq.db)  
 [![npm downloads](https://img.shields.io/npm/dt/sehawq.db.svg)](https://www.npmjs.com/package/sehawq.db)  
 [![license](https://img.shields.io/github/license/sehawq/sehawq.db.svg)](LICENSE)  
 
-**Lightweight JSON-based key-value database for Node.js**  
-Minimal, dependency-free, and easy-to-use. Perfect for small projects, bots, CLIs, and prototyping.  
+**The most powerful JSON-based database for Node.js**  
+Local database + REST API + Real-time Sync = **Firebase Alternative in One Package!**
+
+Perfect for: APIs, Real-time apps, Chat apps, Collaborative tools, Prototypes, and Production!
 
 ---
 
-## 🚀 Features  
-
-- **JSON-based lightweight storage** — No extra dependencies, works with pure Node.js.  
-- **Key-Value structure** — Simple `set`, `get`, `delete` logic.  
-- **Dot-notation namespace** — Access nested data with `user.123.balance`.  
-- **Sync & Async API** — Choose blocking or non-blocking file operations.  
-- **Auto-save** — Writes changes to disk at regular intervals.  
-- **🔥 NEW: Advanced Query System** — Filter, sort, and paginate your data.
-- **🔥 NEW: Aggregation Functions** — Calculate sum, average, min, max, and more.
-- **🔥 NEW: Method Chaining** — Chain operations for complex queries.
-
-### 🔍 Query System
-- `find(filter)` — Find all entries matching a filter function.
-- `findOne(filter)` — Find the first entry matching a filter.
-- `where(field, operator, value)` — Filter by field with operators (`>`, `<`, `>=`, `<=`, `=`, `!=`, `in`, `contains`, `startsWith`, `endsWith`).
-
-### 📊 Aggregation Functions
-- `count(filter)` — Count entries (with optional filter).
-- `sum(field)` — Sum numeric values by field.
-- `avg(field)` — Calculate average of numeric values.
-- `min(field)` / `max(field)` — Find minimum/maximum values.
-- `groupBy(field)` — Group entries by field value.
-
-### ⛓️ Method Chaining & Pagination
-- `sort(field, direction)` — Sort results by field (`'asc'` or `'desc'`).
-- `limit(count)` — Limit number of results.
-- `skip(count)` — Skip number of results for pagination.
-- `first()` / `last()` — Get first or last result.
-- `values()` / `keys()` — Extract values or keys only.
-
-### 🔧 Array Helpers  
-- `push(key, value)` — Add an element to an array.  
-- `pull(key, value)` — Remove an element from an array.  
-
-### ➗ Math Helpers  
-- `add(key, number)` — Increment a numeric value.  
-- `subtract(key, number)` — Decrement a numeric value.  
-
-### 💾 Backup & Restore  
-- `backup(filePath)` — Save a backup of the database.  
-- `restore(filePath)` — Restore database from a backup.  
-
-### 📡 Event Emitter  
-Hooks into database operations:  
-- `set` — Triggered when data is added or updated.  
-- `delete` — Triggered when a key is removed.  
-- `clear` — Triggered when all data is cleared.  
-- `push` / `pull` — Triggered on array modification.  
-- `add` — Triggered on numeric increment.  
-- `backup` / `restore` — Triggered on backup or restore.  
+## 🎯 Why SehawqDB?
+
+❌ **Firebase**: Expensive, vendor lock-in, complex pricing  
+❌ **MongoDB**: Heavy, requires separate server setup  
+❌ **Redis**: In-memory only, no persistence by default  
+
+✅ **SehawqDB**: Lightweight, local-first, REST API built-in, real-time sync, **ZERO configuration!**
 
 ---
 
-## 📦 Installation  
+## 🔥 Features
+
+### 💾 Core Database
+- **JSON-based storage** — Simple, readable, git-friendly
+- **Query System** — MongoDB-like queries with `find()`, `where()`, filtering
+- **Aggregations** — `sum()`, `avg()`, `min()`, `max()`, `groupBy()`
+- **Method Chaining** — Fluent API for complex queries
+- **Dot notation** — Access nested data easily
+
+### 🌐 Built-in REST API (NEW!)
+- **Zero configuration** — Call `.startServer()` and you're live!
+- **Full CRUD** — GET, POST, PUT, DELETE endpoints
+- **Query API** — Filter, sort, paginate via HTTP
+- **Authentication** — Optional API key protection
+
+### ⚡ Real-time Sync (NEW!)
+- **WebSocket integration** — Powered by Socket.io
+- **Live updates** — All clients sync instantly
+- **Event-driven** — Listen to data changes in real-time
+- **Cross-platform** — Works with React, Vue, Angular, mobile apps
+
+### 🔧 Developer Experience
+- **TypeScript ready** — Full type definitions
+- **Events** — Hook into all database operations
+- **Backup & Restore** — Easy data management
+- **Auto-save** — Configurable intervals
+- **Array & Math helpers** — Built-in utilities
+
+---
+
+## 📦 Installation
 
 ```bash
-npm install sehawq.db
+npm install sehawq.db express socket.io socket.io-client cors
 ```
 
 ---
 
-## ⚡ Quick Start (30 seconds)
+## ⚡ Quick Start (Local Database)
 
 ```javascript
-const db = require('sehawq.db')();
+const SehawqDB = require('sehawq.db');
+const db = new SehawqDB();
 
-// Store data
-db.set('user', 'John Doe');
-db.set('score', 100);
+// Basic operations
+db.set('user', { name: 'John', age: 25 });
+console.log(db.get('user')); // { name: 'John', age: 25 }
 
-// Get data
-console.log(db.get('user'));  // John Doe
-console.log(db.get('score')); // 100
+// Query system
+db.set('user1', { name: 'Alice', score: 95 });
+db.set('user2', { name: 'Bob', score: 87 });
 
-// That's it! 🎉
+const topUsers = db.find()
+  .sort('score', 'desc')
+  .limit(2)
+  .values();
 ```
 
 ---
 
-## 🔧 Detailed Usage
+## 🌐 REST API Server
 
-### Basic Operations
+### Start Server
 
 ```javascript
 const SehawqDB = require('sehawq.db');
+
 const db = new SehawqDB({
-  path: './mydata.json',
-  autoSaveInterval: 5000 // Auto-save every 5 seconds
+  path: './database.json',
+  enableServer: true,  // Enable REST API
+  serverPort: 3000,
+  enableRealtime: true, // Enable WebSocket
+  apiKey: 'your-secret-key' // Optional authentication
 });
 
-// Set and get data
-db.set('user.123.name', 'John Doe');
-db.set('user.123.balance', 1000);
-console.log(db.get('user.123')); // { name: 'John Doe', balance: 1000 }
-
-// Check if key exists
-if (db.has('user.123')) {
-  console.log('User exists!');
-}
+// Or start manually:
+// await db.startServer(3000);
 
-// Delete data
-db.delete('user.123.balance');
+// 🚀 Server is now running on http://localhost:3000
 ```
 
-### Array Operations
-
-```javascript
-// Initialize an array
-db.set('users', []);
-
-// Add items
-db.push('users', { id: 1, name: 'Alice' });
-db.push('users', { id: 2, name: 'Bob' });
-
-// Remove items
-db.pull('users', { id: 1, name: 'Alice' });
+### API Endpoints
 
-console.log(db.get('users')); // [{ id: 2, name: 'Bob' }]
+#### Health Check
+```bash
+GET /api/health
 ```
 
-### Math Operations
-
-```javascript
-db.set('score', 100);
-db.add('score', 50);      // score = 150
-db.subtract('score', 20); // score = 130
-console.log(db.get('score')); // 130
+#### Get All Data
+```bash
+GET /api/data
 ```
 
-### Advanced Queries
-
-```javascript
-// Sample data
-db.set('user1', { name: 'Alice', age: 25, active: true, score: 95 });
-db.set('user2', { name: 'Bob', age: 30, active: false, score: 87 });
-db.set('user3', { name: 'Charlie', age: 22, active: true, score: 92 });
-
-// Find all active users
-const activeUsers = db.find(user => user.active).values();
-console.log(activeUsers);
-
-// Find users older than 24
-const olderUsers = db.where('age', '>', 24).values();
-
-// Complex query with chaining
-const topActiveUsers = db
-  .find(user => user.active)
-  .sort('score', 'desc')
-  .limit(2)
-  .values();
-
-console.log(topActiveUsers); // Top 2 active users by score
+#### Get by Key
+```bash
+GET /api/data/:key
 ```
 
-### Aggregation
+#### Set Data
+```bash
+POST /api/data/:key
+Content-Type: application/json
 
-```javascript
-// Count total users
-const totalUsers = db.count();
+{
+  "value": { "name": "John", "age": 25 }
+}
+```
 
-// Count active users
-const activeCount = db.count(user => user.active);
+#### Update Data
+```bash
+PUT /api/data/:key
+Content-Type: application/json
 
-// Calculate average age
-const avgAge = db.avg('age');
+{
+  "value": { "name": "John", "age": 26 }
+}
+```
 
-// Find highest score
-const highestScore = db.max('score');
+#### Delete Data
+```bash
+DELETE /api/data/:key
+```
 
-// Group users by active status
-const grouped = db.groupBy('active');
-console.log(grouped);
-// {
-//   'true': [{ name: 'Alice', ... }, { name: 'Charlie', ... }],
-//   'false': [{ name: 'Bob', ... }]
-// }
+#### Query with Filters
+```bash
+POST /api/query
+Content-Type: application/json
+
+{
+  "filter": {},
+  "sort": { "field": "age", "direction": "desc" },
+  "limit": 10,
+  "skip": 0
+}
 ```
 
-### Pagination
+#### Aggregations
+```bash
+GET /api/aggregate/count
+GET /api/aggregate/sum?field=score
+GET /api/aggregate/avg?field=age
+GET /api/aggregate/min?field=price
+GET /api/aggregate/max?field=rating
+```
 
-```javascript
-// Get users with pagination (page 2, 10 items per page)
-const page2Users = db
-  .find()
-  .skip(10)
-  .limit(10)
-  .values();
+#### Array Operations
+```bash
+POST /api/array/:key/push
+POST /api/array/:key/pull
+```
 
-// Sort and paginate
-const sortedPage = db
-  .find()
-  .sort('name', 'asc')
-  .skip(20)
-  .limit(5)
-  .values();
+#### Math Operations
+```bash
+POST /api/math/:key/add
+POST /api/math/:key/subtract
 ```
 
-### Event Handling
+### API Authentication
 
 ```javascript
-// Listen for database events
-db.on('set', (data) => {
-  console.log(`Set: ${data.key} = ${data.value}`);
-});
-
-db.on('delete', (data) => {
-  console.log(`Deleted: ${data.key}`);
+// Server side
+const db = new SehawqDB({
+  apiKey: 'my-secret-key-123'
 });
 
-db.on('backup', (data) => {
-  console.log(`Backup created: ${data.backupPath}`);
+// Client side
+fetch('http://localhost:3000/api/data', {
+  headers: {
+    'X-API-Key': 'my-secret-key-123'
+  }
 });
 ```
 
-### Backup & Restore
-
-```javascript
-// Create backup
-await db.backup('./backup.json');
-
-// Restore from backup
-await db.restore('./backup.json');
-```
-
 ---
 
-## 📝 Changelog
-
-### Changes in 2.4.2 🔥
-
-- ✨ **Added Query System**
-  - `find(filter)` — Filter entries with custom functions
-  - `findOne(filter)` — Find first matching entry  
-  - `where(field, operator, value)` — Field-based filtering with operators
-  - **Operators**: `>`, `<`, `>=`, `<=`, `=`, `!=`, `in`, `contains`, `startsWith`, `endsWith`
-
-- ✨ **Added Aggregation Functions**
-  - `count(filter)` — Count entries with optional filtering
-  - `sum(field)` — Sum numeric values by field
-  - `avg(field)` — Calculate average of numeric values
-  - `min(field)` / `max(field)` — Find minimum/maximum values
-  - `groupBy(field)` — Group entries by field value
-
-- ✨ **Added Method Chaining Support**
-  - New `QueryResult` class enables chaining operations
-  - `sort(field, direction)` — Sort results ascending or descending
-  - `limit(count)` / `skip(count)` — Pagination support
-  - `first()` / `last()` — Get first or last result
-  - `values()` / `keys()` — Extract values or keys only
-  - `filter()` — Apply additional filtering
-  - `map()` — Transform results
-
-- 🔧 **Enhanced Dot Notation**
-  - Full support for nested queries and filtering
-  - Deep object traversal for all query operations
-
-- 📊 **Advanced Query Examples**
-  ```javascript
-  // Complex chained queries
-  db.find(user => user.active)
-    .sort('score', 'desc')
-    .limit(10)
-    .values();
-  
-  // Field-based filtering
-  db.where('age', '>=', 18)
-    .where('status', 'in', ['premium', 'gold'])
-    .count();
-  ```
-
-### Changes in 2.4.2x
-
-- ✨ Initial release with core features
-- 🔧 Basic CRUD operations (`set`, `get`, `delete`, `has`)
-- 🔧 Dot notation support for nested data
-- 🔧 Array helpers (`push`, `pull`)
-- 🔧 Math helpers (`add`, `subtract`)
-- 🔧 Auto-save functionality
-- 🔧 Event emitter system
-- 🔧 Backup & restore functionality
-- 🔧 Atomic file operations with temporary files
-
----
+## ⚡ Real-time Sync
 
-## 📄 License
+### Server Setup
 
-MIT License - see [LICENSE](https://github.com/sehawq/sehawq.db/blob/main/LICENSE) file for details.
+```javascript
+const db = new SehawqDB({
+  enableServer: true,
+  enableRealtime: true,
+  serverPort: 3000
+});
 
-## 🤝 Contributing
+// Listen to client events
+db.on('client:connected', ({ socketId }) => {
+  console.log('Client connected:', socketId);
+});
 
-Contributions are welcome! Please feel free to submit a Pull Request.
+db.on('client:disconnected', ({ socketId }) => {
+  console.log('Client disconnected:', socketId);
+});
+```
 
-## 🐛 Issues
+### Frontend (React Example)
 
-Found a bug? Please report it on [GitHub Issues](https://github.com/sehawq/sehawq.db/issues).
+```javascript
+import { io } from 'socket.io-client';
+import { useEffect, useState } from 'react';
+
+function App() {
+  const [data, setData] = useState({});
+  const socket = io('http://localhost:3000');
+
+  useEffect(() => {
+    // Receive initial data
+    socket.on('data:init', (initialData) => {
+      setData(initialData);
+    });
+
+    // Listen to real-time changes
+    socket.on('data:changed', ({ action, key, value }) => {
+      console.log(`Data ${action}:`, key, value);
+      
+      if (action === 'set') {
+        setData(prev => ({ ...prev, [key]:

package/src/index.js

@@ -1,6 +1,10 @@
 const fs = require("fs").promises;
 const path = require("path");
 const EventEmitter = require("events");
+const http = require("http");
+const express = require("express");
+const { Server } = require("socket.io");
+const cors = require("cors");
 
 class SehawqDB extends EventEmitter {
   /**
@@ -8,18 +12,38 @@ class SehawqDB extends EventEmitter {
    * @param {Object} options
    * @param {string} [options.path="sehawq.json"] File path for storage.
    * @param {number} [options.autoSaveInterval=0] Autosave interval in ms (0 disables autosave).
+   * @param {boolean} [options.enableServer=false] Enable REST API server
+   * @param {number} [options.serverPort=3000] Server port
+   * @param {boolean} [options.enableRealtime=true] Enable real-time sync via WebSocket
+   * @param {string} [options.apiKey] Optional API key for authentication
    */
   constructor(options = {}) {
     super();
     this.filePath = path.resolve(options.path || "sehawq.json");
     this.autoSaveInterval = options.autoSaveInterval || 0;
     this.data = {};
+    
+    // Server options
+    this.enableServer = options.enableServer || false;
+    this.serverPort = options.serverPort || 3000;
+    this.enableRealtime = options.enableRealtime !== false;
+    this.apiKey = options.apiKey || null;
+    
+    // Server instances
+    this.app = null;
+    this.server = null;
+    this.io = null;
+    this.isServerRunning = false;
 
     this._init();
 
     if (this.autoSaveInterval > 0) {
       this._interval = setInterval(() => this.save(), this.autoSaveInterval);
     }
+    
+    if (this.enableServer) {
+      this.startServer(this.serverPort);
+    }
   }
 
   async _init() {
@@ -41,6 +65,17 @@ class SehawqDB extends EventEmitter {
   set(key, value) {
     this._setByPath(key, value);
     this.emit("set", { key, value });
+    
+    // Real-time broadcast
+    if (this.io) {
+      this.io.emit("data:changed", { 
+        action: "set", 
+        key, 
+        value,
+        timestamp: Date.now()
+      });
+    }
+    
     this.save();
     return value;
   }
@@ -52,6 +87,16 @@ class SehawqDB extends EventEmitter {
   delete(key) {
     this._deleteByPath(key);
     this.emit("delete", { key });
+    
+    // Real-time broadcast
+    if (this.io) {
+      this.io.emit("data:changed", { 
+        action: "delete", 
+        key,
+        timestamp: Date.now()
+      });
+    }
+    
     this.save();
   }
 
@@ -66,6 +111,15 @@ class SehawqDB extends EventEmitter {
   clear() {
     this.data = {};
     this.emit("clear");
+    
+    // Real-time broadcast
+    if (this.io) {
+      this.io.emit("data:changed", { 
+        action: "clear",
+        timestamp: Date.now()
+      });
+    }
+    
     this.save();
   }
 
@@ -84,6 +138,17 @@ class SehawqDB extends EventEmitter {
     arr.push(value);
     this._setByPath(key, arr);
     this.emit("push", { key, value });
+    
+    // Real-time broadcast
+    if (this.io) {
+      this.io.emit("data:changed", { 
+        action: "push", 
+        key, 
+        value,
+        timestamp: Date.now()
+      });
+    }
+    
     this.save();
     return arr;
   }
@@ -94,6 +159,17 @@ class SehawqDB extends EventEmitter {
     arr = arr.filter(v => v !== value);
     this._setByPath(key, arr);
     this.emit("pull", { key, value });
+    
+    // Real-time broadcast
+    if (this.io) {
+      this.io.emit("data:changed", { 
+        action: "pull", 
+        key, 
+        value,
+        timestamp: Date.now()
+      });
+    }
+    
     this.save();
     return arr;
   }
@@ -105,6 +181,18 @@ class SehawqDB extends EventEmitter {
     val += number;
     this._setByPath(key, val);
     this.emit("add", { key, number });
+    
+    // Real-time broadcast
+    if (this.io) {
+      this.io.emit("data:changed", { 
+        action: "add", 
+        key, 
+        number,
+        newValue: val,
+        timestamp: Date.now()
+      });
+    }
+    
     this.save();
     return val;
   }
@@ -113,13 +201,8 @@ class SehawqDB extends EventEmitter {
     return this.add(key, -number);
   }
 
-  // ---------------- NEW: Query System ----------------
+  // ---------------- Query System ----------------
   
-  /**
-   * Find all entries that match the filter function
-   * @param {Function} filter - Filter function (item, key) => boolean
-   * @returns {QueryResult} Chainable query result
-   */
   find(filter) {
     const results = [];
     
@@ -130,7 +213,6 @@ class SehawqDB extends EventEmitter {
         }
       }
     } else {
-      // Eğer filter verilmezse tüm dataları döndür
       for (const [key, value] of Object.entries(this.data)) {
         results.push({ key, value });
       }
@@ -139,11 +221,6 @@ class SehawqDB extends EventEmitter {
     return new QueryResult(results);
   }
 
-  /**
-   * Find first entry that matches the filter
-   * @param {Function} filter - Filter function
-   * @returns {Object|undefined} First matching item
-   */
   findOne(filter) {
     if (typeof filter === 'function') {
       for (const [key, value] of Object.entries(this.data)) {
@@ -155,13 +232,6 @@ class SehawqDB extends EventEmitter {
     return undefined;
   }
 
-  /**
-   * Filter by field value with operators
-   * @param {string} field - Field name (supports dot notation)
-   * @param {string} operator - Comparison operator (=, !=, >, <, >=, <=, in, contains)
-   * @param {*} value - Value to compare
-   * @returns {QueryResult} Chainable query result
-   */
   where(field, operator, value) {
     return this.find((item, key) => {
       const fieldValue = this._getValueByPath(item, field);
@@ -194,13 +264,8 @@ class SehawqDB extends EventEmitter {
     });
   }
 
-  // ---------------- NEW: Aggregation System ----------------
+  // ---------------- Aggregation System ----------------
   
-  /**
-   * Count total entries
-   * @param {Function} [filter] - Optional filter function
-   * @returns {number} Count of entries
-   */
   count(filter) {
     if (filter) {
       return this.find(filter).count();
@@ -208,12 +273,6 @@ class SehawqDB extends EventEmitter {
     return Object.keys(this.data).length;
   }
 
-  /**
-   * Sum numeric values by field
-   * @param {string} field - Field name to sum
-   * @param {Function} [filter] - Optional filter function
-   * @returns {number} Sum of values
-   */
   sum(field, filter) {
     const items = filter ? this.find(filter).toArray() : this.find().toArray();
     return items.reduce((sum, item) => {
@@ -222,12 +281,6 @@ class SehawqDB extends EventEmitter {
     }, 0);
   }
 
-  /**
-   * Average of numeric values by field
-   * @param {string} field - Field name to average
-   * @param {Function} [filter] - Optional filter function
-   * @returns {number} Average of values
-   */
   avg(field, filter) {
     const items = filter ? this.find(filter).toArray() : this.find().toArray();
     if (items.length === 0) return 0;
@@ -240,12 +293,6 @@ class SehawqDB extends EventEmitter {
     return sum / items.length;
   }
 
-  /**
-   * Minimum value by field
-   * @param {string} field - Field name
-   * @param {Function} [filter] - Optional filter function
-   * @returns {*} Minimum value
-   */
   min(field, filter) {
     const items = filter ? this.find(filter).toArray() : this.find().toArray();
     if (items.length === 0) return undefined;
@@ -256,12 +303,6 @@ class SehawqDB extends EventEmitter {
     }).filter(val => val !== Infinity));
   }
 
-  /**
-   * Maximum value by field
-   * @param {string} field - Field name
-   * @param {Function} [filter] - Optional filter function
-   * @returns {*} Maximum value
-   */
   max(field, filter) {
     const items = filter ? this.find(filter).toArray() : this.find().toArray();
     if (items.length === 0) return undefined;
@@ -272,12 +313,6 @@ class SehawqDB extends EventEmitter {
     }).filter(val => val !== -Infinity));
   }
 
-  /**
-   * Group entries by field value
-   * @param {string} field - Field name to group by
-   * @param {Function} [filter] - Optional filter function
-   * @returns {Object} Grouped results
-   */
   groupBy(field, filter) {
     const items = filter ? this.find(filter).toArray() : this.find().toArray();
     const groups = {};
@@ -295,6 +330,286 @@ class SehawqDB extends EventEmitter {
     return groups;
   }
 
+  // ---------------- REST API Server ----------------
+  
+  /**
+   * Start REST API server with real-time sync
+   * @param {number} port - Server port
+   * @returns {Promise<void>}
+   */
+  async startServer(port = 3000) {
+    if (this.isServerRunning) {
+      console.log(`⚠️  Server is already running on port ${this.serverPort}`);
+      return;
+    }
+
+    this.app = express();
+    this.server = http.createServer(this.app);
+    
+    // Enable real-time if requested
+    if (this.enableRealtime) {
+      this.io = new Server(this.server, {
+        cors: {
+          origin: "*",
+          methods: ["GET", "POST", "PUT", "DELETE"]
+        }
+      });
+      
+      this._setupWebSocket();
+    }
+
+    // Middleware
+    this.app.use(cors());
+    this.app.use(express.json());
+    
+    // API Key middleware
+    if (this.apiKey) {
+      this.app.use((req, res, next) => {
+        const key = req.headers['x-api-key'];
+        if (key !== this.apiKey) {
+          return res.status(401).json({ error: 'Unauthorized' });
+        }
+        next();
+      });
+    }
+
+    this._setupRoutes();
+
+    return new Promise((resolve, reject) => {
+      this.server.listen(port, () => {
+        this.isServerRunning = true;
+        this.serverPort = port;
+        console.log(`🚀 SehawqDB Server running on http://localhost:${port}`);
+        console.log(`📡 Real-time sync: ${this.enableRealtime ? 'ENABLED' : 'DISABLED'}`);
+        console.log(`🔒 API Key: ${this.apiKey ? 'ENABLED' : 'DISABLED'}`);
+        this.emit('server:started', { port });
+        resolve();
+      }).on('error', reject);
+    });
+  }
+
+  /**
+   * Stop the REST API server
+   */
+  stopServer() {
+    if (!this.isServerRunning) return;
+    
+    if (this.io) this.io.close();
+    if (this.server) this.server.close();
+    
+    this.isServerRunning = false;
+    console.log('🛑 SehawqDB Server stopped');
+    this.emit('server:stopped');
+  }
+
+  _setupRoutes() {
+    const router = express.Router();
+
+    // Health check
+    router.get('/health', (req, res) => {
+      res.json({ 
+        status: 'ok', 
+        uptime: process.uptime(),
+        realtime: this.enableRealtime,
+        dataSize: Object.keys(this.data).length
+      });
+    });
+
+    // Get all data
+    router.get('/data', (req, res) => {
+      res.json({ success: true, data: this.data });
+    });
+
+    // Get by key
+    router.get('/data/:key', (req, res) => {
+      const { key } = req.params;
+      const value = this.get(key);
+      
+      if (value === undefined) {
+        return res.status(404).json({ success: false, error: 'Key not found' });
+      }
+      
+      res.json({ success: true, key, value });
+    });
+
+    // Set data
+    router.post('/data/:key', (req, res) => {
+      const { key } = req.params;
+      const { value } = req.body;
+      
+      if (value === undefined) {
+        return res.status(400).json({ success: false, error: 'Value is required' });
+      }
+      
+      const result = this.set(key, value);
+      res.json({ success: true, key, value: result });
+    });
+
+    // Update data (alias for set)
+    router.put('/data/:key', (req, res) => {
+      const { key } = req.params;
+      const { value } = req.body;
+      
+      if (value === undefined) {
+        return res.status(400).json({ success: false, error: 'Value is required' });
+      }
+      
+      const result = this.set(key, value);
+      res.json({ success: true, key, value: result });
+    });
+
+    // Delete data
+    router.delete('/data/:key', (req, res) => {
+      const { key } = req.params;
+      
+      if (!this.has(key)) {
+        return res.status(404).json({ success: false, error: 'Key not found' });
+      }
+      
+      this.delete(key);
+      res.json({ success: true, key });
+    });
+
+    // Query with find
+    router.post('/query', (req, res) => {
+      try {
+        const { filter, sort, limit, skip } = req.body;
+        
+        let query = this.find();
+        
+        // Apply sorting
+        if (sort && sort.field) {
+          query = query.sort(sort.field, sort.direction || 'asc');
+        }
+        
+        // Apply pagination
+        if (skip) query = query.skip(skip);
+        if (limit) query = query.limit(limit);
+        
+        const results = query.toArray();
+        
+        res.json({ 
+          success: true, 
+          results,
+          count: results.length
+        });
+      } catch (error) {
+        res.status(400).json({ success: false, error: error.message });
+      }
+    });
+
+    // Aggregation
+    router.get('/aggregate/:operation', (req, res) => {
+      try {
+        const { operation } = req.params;
+        const { field } = req.query;
+        
+        let result;
+        
+        switch (operation) {
+          case 'count':
+            result = this.count();
+            break;
+          case 'sum':
+            if (!field) return res.status(400).json({ error: 'Field is required' });
+            result = this.sum(field);
+            break;
+          case 'avg':
+            if (!field) return res.status(400).json({ error: 'Field is required' });
+            result = this.avg(field);
+            break;
+          case 'min':
+            if (!field) return res.status(400).json({ error: 'Field is required' });
+            result = this.min(field);
+            break;
+          case 'max':
+            if (!field) return res.status(400).json({ error: 'Field is required' });
+            result = this.max(field);
+            break;
+          default:
+            return res.status(400).json({ error: 'Invalid operation' });
+        }
+        
+        res.json({ success: true, operation, field, result });
+      } catch (error) {
+        res.status(400).json({ success: false, error: error.message });
+      }
+    });
+
+    // Array operations
+    router.post('/array/:key/push', (req, res) => {
+      const { key } = req.params;
+      const { value } = req.body;
+      
+      const result = this.push(key, value);
+      res.json({ success: true, key, value: result });
+    });
+
+    router.post('/array/:key/pull', (req, res) => {
+      const { key } = req.params;
+      const { value } = req.body;
+      
+      const result = this.pull(key, value);
+      res.json({ success: true, key, value: result });
+    });
+
+    // Math operations
+    router.post('/math/:key/add', (req, res) => {
+      const { key } = req.params;
+      const { number } = req.body;
+      
+      if (typeof number !== 'number') {
+        return res.status(400).json({ error: 'Number is required' });
+      }
+      
+      const result = this.add(key, number);
+      res.json({ success: true, key, value: result });
+    });
+
+    router.post('/math/:key/subtract', (req, res) => {
+      const { key } = req.params;
+      const { number } = req.body;
+      
+      if (typeof number !== 'number') {
+        return res.status(400).json({ error: 'Number is required' });
+      }
+      
+      const result = this.subtract(key, number);
+      res.json({ success: true, key, value: result });
+    });
+
+    this.app.use('/api', router);
+  }
+
+  _setupWebSocket() {
+    this.io.on('connection', (socket) => {
+      console.log(`✅ Client connected: ${socket.id}`);
+      this.emit('client:connected', { socketId: socket.id });
+
+      // Send current data on connection
+      socket.emit('data:init', this.data);
+
+      // Handle client operations
+      socket.on('data:set', ({ key, value }) => {
+        this.set(key, value);
+      });
+
+      socket.on('data:delete', ({ key }) => {
+        this.delete(key);
+      });
+
+      socket.on('data:get', ({ key }, callback) => {
+        const value = this.get(key);
+        callback({ success: true, value });
+      });
+
+      socket.on('disconnect', () => {
+        console.log(`❌ Client disconnected: ${socket.id}`);
+        this.emit('client:disconnected', { socketId: socket.id });
+      });
+    });
+  }
+
   // ---------------- Backup & Restore ----------------
   async backup(backupPath) {
     await fs.writeFile(backupPath, JSON.stringify(this.data, null, 2), "utf8");
@@ -365,18 +680,12 @@ class SehawqDB extends EventEmitter {
   }
 }
 
-// ---------------- QueryResult Class (for method chaining) ----------------
+// ---------------- QueryResult Class ----------------
 class QueryResult {
   constructor(results) {
     this.results = results || [];
   }
 
-  /**
-   * Sort results by field
-   * @param {string} field - Field name to sort by
-   * @param {string} direction - 'asc' or 'desc'
-   * @returns {QueryResult} Chainable
-   */
   sort(field, direction = 'asc') {
     this.results.sort((a, b) => {
       const aVal = this._getValueByPath(a.value, field);
@@ -391,89 +700,45 @@ class QueryResult {
     return this;
   }
 
-  /**
-   * Limit number of results
-   * @param {number} count - Maximum number of results
-   * @returns {QueryResult} Chainable
-   */
   limit(count) {
     this.results = this.results.slice(0, count);
     return this;
   }
 
-  /**
-   * Skip number of results
-   * @param {number} count - Number of results to skip
-   * @returns {QueryResult} Chainable
-   */
   skip(count) {
     this.results = this.results.slice(count);
     return this;
   }
 
-  /**
-   * Get count of results
-   * @returns {number} Count
-   */
   count() {
     return this.results.length;
   }
 
-  /**
-   * Get first result
-   * @returns {Object|undefined} First result
-   */
   first() {
     return this.results[0];
   }
 
-  /**
-   * Get last result
-   * @returns {Object|undefined} Last result
-   */
   last() {
     return this.results[this.results.length - 1];
   }
 
-  /**
-   * Convert to array
-   * @returns {Array} Results array
-   */
   toArray() {
     return this.results;
   }
 
-  /**
-   * Get only values (without keys)
-   * @returns {Array} Values array
-   */
   values() {
     return this.results.map(item => item.value);
   }
 
-  /**
-   * Get only keys
-   * @returns {Array} Keys array
-   */
   keys() {
     return this.results.map(item => item.key);
   }
 
-  /**
-   * Apply additional filter
-   * @param {Function} filter - Filter function
-   * @returns {QueryResult} Chainable
-   */
   filter(filter) {
     this.results = this.results.filter(item => filter(item.value, item.key));
     return this;
   }
 
-  /**
-   * Map over results
-   * @param {Function} mapper - Map function
-   * @returns {Array} Mapped results
-   */
   map(mapper) {
     return this.results.map(item => mapper(item.value, item.key));
   }