sehawq.db 2.3.0 → 2.4.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sehawq.db",
-  "version": "2.3.0",
+  "version": "2.4.2",
   "description": "Lightweight JSON-based key-value database with namespaces, array & math helpers.",
   "main": "src/index.js",
   "keywords": [

package/readme.md

@@ -16,6 +16,28 @@ Minimal, dependency-free, and easy-to-use. Perfect for small projects, bots, CLI
 - **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.  
@@ -44,3 +66,241 @@ Hooks into database operations:
 
 ```bash
 npm install sehawq.db
+```
+
+---
+
+## ⚡ Quick Start (30 seconds)
+
+```javascript
+const db = require('sehawq.db')();
+
+// Store data
+db.set('user', 'John Doe');
+db.set('score', 100);
+
+// Get data
+console.log(db.get('user'));  // John Doe
+console.log(db.get('score')); // 100
+
+// That's it! 🎉
+```
+
+---
+
+## 🔧 Detailed Usage
+
+### Basic Operations
+
+```javascript
+const SehawqDB = require('sehawq.db');
+const db = new SehawqDB({
+  path: './mydata.json',
+  autoSaveInterval: 5000 // Auto-save every 5 seconds
+});
+
+// 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!');
+}
+
+// Delete data
+db.delete('user.123.balance');
+```
+
+### 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' });
+
+console.log(db.get('users')); // [{ id: 2, name: 'Bob' }]
+```
+
+### 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
+```
+
+### 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
+```
+
+### Aggregation
+
+```javascript
+// Count total users
+const totalUsers = db.count();
+
+// Count active users
+const activeCount = db.count(user => user.active);
+
+// Calculate average age
+const avgAge = db.avg('age');
+
+// Find highest score
+const highestScore = db.max('score');
+
+// Group users by active status
+const grouped = db.groupBy('active');
+console.log(grouped);
+// {
+//   'true': [{ name: 'Alice', ... }, { name: 'Charlie', ... }],
+//   'false': [{ name: 'Bob', ... }]
+// }
+```
+
+### Pagination
+
+```javascript
+// Get users with pagination (page 2, 10 items per page)
+const page2Users = db
+  .find()
+  .skip(10)
+  .limit(10)
+  .values();
+
+// Sort and paginate
+const sortedPage = db
+  .find()
+  .sort('name', 'asc')
+  .skip(20)
+  .limit(5)
+  .values();
+```
+
+### Event Handling
+
+```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}`);
+});
+
+db.on('backup', (data) => {
+  console.log(`Backup created: ${data.backupPath}`);
+});
+```
+
+### 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
+
+---
+
+## 📄 License
+
+MIT License - see [LICENSE](https://github.com/sehawq/sehawq.db/blob/main/LICENSE) file for details.
+
+## 🤝 Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## 🐛 Issues
+
+Found a bug? Please report it on [GitHub Issues](https://github.com/sehawq/sehawq.db/issues).

package/src/index.js

@@ -113,6 +113,188 @@ class SehawqDB extends EventEmitter {
     return this.add(key, -number);
   }
 
+  // ---------------- NEW: 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 = [];
+    
+    if (typeof filter === 'function') {
+      for (const [key, value] of Object.entries(this.data)) {
+        if (filter(value, key)) {
+          results.push({ key, value });
+        }
+      }
+    } else {
+      // Eğer filter verilmezse tüm dataları döndür
+      for (const [key, value] of Object.entries(this.data)) {
+        results.push({ key, value });
+      }
+    }
+    
+    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)) {
+        if (filter(value, key)) {
+          return { key, value };
+        }
+      }
+    }
+    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);
+      
+      switch (operator) {
+        case '=':
+        case '==':
+          return fieldValue === value;
+        case '!=':
+          return fieldValue !== value;
+        case '>':
+          return fieldValue > value;
+        case '<':
+          return fieldValue < value;
+        case '>=':
+          return fieldValue >= value;
+        case '<=':
+          return fieldValue <= value;
+        case 'in':
+          return Array.isArray(value) && value.includes(fieldValue);
+        case 'contains':
+          return typeof fieldValue === 'string' && fieldValue.includes(value);
+        case 'startsWith':
+          return typeof fieldValue === 'string' && fieldValue.startsWith(value);
+        case 'endsWith':
+          return typeof fieldValue === 'string' && fieldValue.endsWith(value);
+        default:
+          return false;
+      }
+    });
+  }
+
+  // ---------------- NEW: 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();
+    }
+    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) => {
+      const val = this._getValueByPath(item.value, field);
+      return sum + (typeof val === 'number' ? val : 0);
+    }, 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;
+    
+    const sum = items.reduce((total, item) => {
+      const val = this._getValueByPath(item.value, field);
+      return total + (typeof val === 'number' ? val : 0);
+    }, 0);
+    
+    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;
+    
+    return Math.min(...items.map(item => {
+      const val = this._getValueByPath(item.value, field);
+      return typeof val === 'number' ? val : Infinity;
+    }).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;
+    
+    return Math.max(...items.map(item => {
+      const val = this._getValueByPath(item.value, field);
+      return typeof val === 'number' ? val : -Infinity;
+    }).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 = {};
+    
+    items.forEach(item => {
+      const groupKey = this._getValueByPath(item.value, field);
+      const key = groupKey !== undefined ? String(groupKey) : 'undefined';
+      
+      if (!groups[key]) {
+        groups[key] = [];
+      }
+      groups[key].push(item);
+    });
+    
+    return groups;
+  }
+
   // ---------------- Backup & Restore ----------------
   async backup(backupPath) {
     await fs.writeFile(backupPath, JSON.stringify(this.data, null, 2), "utf8");
@@ -168,6 +350,146 @@ class SehawqDB extends EventEmitter {
     }
     delete obj[keys[0]];
   }
+
+  _getValueByPath(obj, pathStr) {
+    const keys = pathStr.split(".");
+    let result = obj;
+    for (const key of keys) {
+      if (result && Object.prototype.hasOwnProperty.call(result, key)) {
+        result = result[key];
+      } else {
+        return undefined;
+      }
+    }
+    return result;
+  }
+}
+
+// ---------------- QueryResult Class (for method chaining) ----------------
+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);
+      const bVal = this._getValueByPath(b.value, field);
+      
+      if (aVal === bVal) return 0;
+      
+      const comparison = aVal > bVal ? 1 : -1;
+      return direction === 'desc' ? -comparison : comparison;
+    });
+    
+    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));
+  }
+
+  _getValueByPath(obj, pathStr) {
+    const keys = pathStr.split(".");
+    let result = obj;
+    for (const key of keys) {
+      if (result && Object.prototype.hasOwnProperty.call(result, key)) {
+        result = result[key];
+      } else {
+        return undefined;
+      }
+    }
+    return result;
+  }
 }
 
-module.exports = SehawqDB;
+module.exports = SehawqDB;