json-database-st 1.0.13 → 2.0.0

package/README.md

@@ -4,141 +4,73 @@
 [![NPM Downloads](https://img.shields.io/npm/dm/json-database-st.svg)](https://www.npmjs.com/package/json-database-st)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-A secure, performant, and feature-rich JSON file database for Node.js. Designed for projects that need simple, persistent data storage without the overhead of a traditional database server, but with modern features like **encryption, indexing, and schema validation**.
+The high-performance, secure, JSON-based database engine powering **Project Ares** and the **ST Conglomerate**.
 
-Ideal for small to medium-sized projects, configuration management, user session data, or any application where data safety and integrity are critical.
+Designed for Node.js applications that need data persistence without the complexity of SQL servers.
 
-## Features
+## 🚀 Key Features
 
-*   **🔒 Security First:**
-    *   **Encryption at Rest:** Built-in AES-256-GCM encryption protects your data on disk.
-    *   **Path Traversal Protection:** Prevents malicious file path inputs.
-    *   **Secure by Default:** Fails safely if data is tampered with or the key is wrong.
+- **🔒 AES-256-GCM Encryption:** Military-grade security for your data at rest.
+- **⚡ O(1) Indexing:** Instant lookups, no matter how big the database gets.
+- **🛡️ Atomic Writes:** Zero corruption risk. Uses lockfiles and temp-write-swap strategy.
+- **🔢 Math Helpers:** Atomic `add` and `subtract` for financial/gaming logic.
+- **📄 Pagination:** Built-in support for handling large lists efficiently.
+- **📸 Snapshots:** One-line command to backup your entire database.
 
-*   **⚡ High-Performance Indexing:**
-    *   Create indexes on your data fields (e.g., `users.email`).
-    *   Enjoy near-instantaneous `O(1)` lookups with `findByIndex()`, avoiding slow full-database scans.
-
-*   **🤝 Atomic & Reliable:**
-    *   **Atomic Writes:** All write operations (`set`, `transaction`, `batch`, etc.) are queued and executed atomically, preventing data corruption.
-    *   **Transactions:** Execute complex multi-step operations as a single, indivisible unit.
-    *   **Batching:** Perform multiple simple operations in a single, efficient disk write.
-
-*   **✅ Data Integrity:**
-    *   **Schema Validation:** Integrate with libraries like Zod or Joi to enforce data structures on every write, preventing bad data from ever being saved.
-    *   **Deep Uniqueness:** The `push()` method automatically prevents duplicate entries in arrays using deep object comparison.
-
-*   **📢 Modern & DX-Focused API:**
-    *   **Promise-based:** Fully asynchronous `async/await` friendly API.
-    *   **Event-Driven:** Emits `write`, `change`, and `error` events for reactive programming, auditing, or real-time updates.
-    *   **Intuitive & Powerful:** A clean API (`get`, `set`, `find`) powered by `lodash` for flexible path notation.
-
-## Installation
+## 📦 Installation
 
 ```bash
-# This package requires lodash as a peer dependency
-npm install json-database-st lodash
+npm install json-database-st lodash proper-lockfile
 ```
 
-## Quick Start: Secure & Indexed Database
-
-This example demonstrates setting up a secure, encrypted database with a high-speed index on user emails.
+## ⚡ Quick Start
 
 ```javascript
 const JSONDatabase = require('json-database-st');
-const path = require('path');
-const crypto = require('crypto');
-
-// 1. Generate a secure key (run once and store it in environment variables)
-// const encryptionKey = crypto.randomBytes(32).toString('hex');
-// console.log('Your secure encryption key:', encryptionKey);
-const ENCRYPTION_KEY = 'd0a7e8c1b2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9'; // Example key
-
-// 2. Initialize the database with encryption and an index
-const db = new JSONDatabase(path.join(__dirname, 'secure-data.json'), {
-  encryptionKey: ENCRYPTION_KEY,
-  indices: [
-    { name: 'user-email', path: 'users', field: 'email', unique: true }
-  ]
-});
+
+const db = new JSONDatabase('data.json');
 
 async function run() {
-  try {
-    // 3. Set data. The index will be updated automatically.
-    await db.set('users.alice', { email: 'alice@example.com', name: 'Alice' });
-    await db.set('users.bob', { email: 'bob@example.com', name: 'Bob' });
+    // 1. Set Data
+    await db.set('user.name', 'Sethun');
+    
+    // 2. Atomic Math (New!)
+    await db.set('user.balance', 1000);
+    await db.add('user.balance', 500); // Balance is now 1500
     
-    // This would throw an IndexViolationError because the email is not unique
-    // await db.set('users.impostor', { email: 'alice@example.com', name: 'Impostor' });
-
-    // 4. Use the high-speed index for an instant lookup
-    console.log('--- Finding user with index ---');
-    const alice = await db.findByIndex('user-email', 'alice@example.com');
-    console.log('Found user:', alice); // -> { email: 'alice@example.com', name: 'Alice' }
-
-    // 5. Perform a transaction
-    await db.transaction(data => {
-      data.users.bob.lastLogin = Date.now();
-      return data; // Must return the modified data
-    });
-
-    console.log('\n--- Bob after transaction ---');
-    console.log(await db.get('users.bob'));
-
-  } catch (err) {
-    console.error('Database operation failed:', err);
-  } finally {
-    // 6. IMPORTANT: Always close the DB for a graceful shutdown
-    await db.close();
-  }
+    // 3. Arrays with Uniqueness
+    await db.push('inventory', { id: 1, item: 'Laptop' });
+    
+    console.log(await db.get('user'));
 }
 
 run();
 ```
 
-## Documentation
-
-**Full API details and advanced usage examples are available on the hosted documentation site:**
-
-**[View Full Documentation Website](https://sethunthunder111.github.io/json-database-st/)**
-
-## Performance
-
-The library is designed for high performance, especially for read-heavy workloads. Indexed lookups are nearly instantaneous (`O(1)`), and the `multiProcess: false` option provides a significant boost for write speeds in single-process applications.
-
-For a detailed analysis, see the comprehensive benchmark report.
+## 📖 Documentation
 
-- **[View the detailed Benchmark Analysis (BENCHMARKS.md)](BENCHMARKS.md)**
-- **[View the interactive HTML Report](https://sethunthunder111.github.io/json-database-st/benchmarks.html)**
+Full documentation is available in the `website/docs.html` file included in this repository.
 
-## API Summary
+## 🏗️ Project Ares Integration
 
-*   `new JSONDatabase(filename, [options])`
-*   `async get(path, [defaultValue])`
-*   `async set(path, value)`
-*   `async has(path)`
-*   `async delete(path)`
-*   `async push(path, ...items)`
-*   `async pull(path, ...itemsToRemove)`
-*   `async transaction(asyncFn)`
-*   `async batch(operations, [options])`
-*   `async find(collectionPath, predicate)`
-*   `async findByIndex(indexName, value)`
-*   `async clear()`
-*   `getStats()`
-*   `async close()`
-*   Events: `.on('write', handler)`, `.on('change', handler)`, `.on('error', handler)`
+This database is optimized for the **ST Financial Engine**.
 
-## Limitations
+- Use `encryptionKey` for all financial records.
+- Use `paginate()` for transaction history lists.
+- Use `createSnapshot('daily')` for automated backups.
 
-*   **In-Memory Operation:** The entire database file is loaded into memory on initialization. This makes it extremely fast for reads but limits the practical file size to what can comfortably fit in your available RAM.
-*   **Single-Process Focus:** While writes are atomic, this library is designed for use by a single Node.js process. Using it with multiple processes writing to the same file (e.g., in a cluster) is not recommended and can lead to race conditions.
-*   **Not a Replacement for SQL/NoSQL Servers:** For very large datasets, high write concurrency, complex queries, or multi-process/multi-server needs, a dedicated database system like PostgreSQL, MongoDB, or SQLite is the appropriate choice.
+## 🤝 Contributing
 
-## Contributing
+Built by **SethunThunder** for the ST Empire.
+Laybon Gold 1.5 Assisted.
 
-Contributions, issues, and feature requests are welcome! Please feel free to open an issue to discuss any significant changes.
+## 🚀 Performance (v2.0)
 
-## License
+| Operation | 10k Records | 1M Records |
+| :--- | :--- | :--- |
+| **Indexed Read** | 0.15 ms | 0.07 ms |
+| **Write (Ingest)** | 42,450 ops/sec | 57,845 ops/sec |
+| **Single Update** | 100 ms | 6.3 s |
 
-[MIT](LICENSE)
+> **Fastest in Class:** Indexed reads are O(1). Updates are 1.5x faster than v1.0.
+> [View Full Benchmarks](./BENCHMARKS.md)

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "json-database-st",
-  "version": "1.0.13",
+  "version": "2.0.0",
   "description": "A simple, promise-based JSON file database for Node.js with atomic operations and lodash integration.",
   "main": "JSONDatabase.js",
   "types": "JSONDatabase.d.ts",
   "scripts": {
-    "test": "jest"
+    "test": "jest",
+    "benchmark": "node benchmark.js"
   },
   "repository": {
     "type": "git",