json-database-st 1.0.5 → 1.0.6

package/README.md

@@ -1,73 +1,95 @@
-# JSON Database By ST
+# JSON Database ST
 
-[![npm version](https://badge.fury.io/js/json-database-st.svg)](https://badge.fury.io/js/json-database-st) 
+[![NPM Version](https://badge.fury.io/js/json-database-st.svg)](https://badge.fury.io/js/json-database-st)
+[![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 simple, promise-based JSON file database for Node.js applications. Features atomic file operations, lodash integration for easy data access, transactions, batching, and basic querying.
+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**.
 
-Ideal for small projects, prototypes, configuration management, or simple data persistence needs where a full database server is overkill.
+Ideal for small to medium-sized projects, configuration management, user session data, or any application where data safety and integrity are critical.
 
 ## Features
 
-*   **Promise-based API:** Fully asynchronous methods.
-*   **Atomic Writes:** Prevents data corruption from concurrent writes using an internal lock.
-*   **Simple API:** `get`, `set`, `has`, `delete`, `push` (deep unique), `pull` (deep removal), `clear`.
-*   **Lodash Integration:** Use dot/bracket notation paths (e.g., `'users.john.age'`) via `lodash`.
-*   **Transactions:** Execute multiple reads/writes as a single atomic unit (`transaction`).
-*   **Batch Operations:** Efficiently perform multiple `set`, `delete`, `push`, or `pull` operations in one atomic write (`batch`).
-*   **Basic Querying:** Filter object properties based on a predicate function (`query`).
-*   **File Auto-Creation:** Creates the JSON file (with `{}`) if it doesn't exist.
-*   **Pretty Print Option:** Optionally format the JSON file for readability.
-*   **Dependencies:** Only requires `lodash`. Uses built-in `fs.promises`.
+*   **🔒 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.
+
+*   **⚡ 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
 
 ```bash
-# Make sure you have lodash installed as well
+# This package requires lodash as a peer dependency
 npm install json-database-st lodash
 ```
 
+## Quick Start: Secure & Indexed Database
 
-## Quick Start
+This example demonstrates setting up a secure, encrypted database with a high-speed index on user emails.
 
 ```javascript
-const JSONDatabase = require('json-database-st'); // Use your package name
+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
 
-// Initialize (creates 'mydata.json' if needed)
-const db = new JSONDatabase(path.join(__dirname, 'mydata'), { prettyPrint: true });
+// 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 }
+  ]
+});
 
 async function run() {
   try {
-    // Set data
-    await db.set('user.name', 'Bob');
-    await db.set('user.settings.theme', 'dark');
-
-    // Get data
-    const theme = await db.get('user.settings.theme', 'light'); // Default value
-    console.log(`Theme: ${theme}`); // -> Theme: dark
-
-    // Push unique items (uses deep compare)
-    await db.push('user.tags', 'vip', { type: 'beta' });
-    await db.push('user.tags', { type: 'beta' }); // Won't be added again
-    console.log('Tags:', await db.get('user.tags')); // -> ['vip', { type: 'beta' }]
-
-    // Check existence
-    console.log('Has user age?', await db.has('user.age')); // -> false
-
-    // Delete
-    await db.delete('user.settings');
-    console.log('User object:', await db.get('user')); // -> { name: 'Bob', tags: [...] }
-
-    // Get Stats
-    console.log('DB Stats:', db.getStats());
+    // 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' });
+    
+    // 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 {
-    // IMPORTANT: Always close the DB when done
+    // 6. IMPORTANT: Always close the DB for a graceful shutdown
     await db.close();
-    console.log('Database closed.');
   }
 }
 
@@ -76,9 +98,9 @@ run();
 
 ## Documentation
 
-**Full API details and advanced usage examples are available in the hosted documentation:**
+**Full API details and advanced usage examples are available on the hosted documentation site:**
 
-**[View Documentation](https://sethunthunder111.github.io/json-database-st/)**
+**[View Full Documentation Website](https://sethunthunder111.github.io/json-database-st/)**
 
 ## API Summary
 
@@ -90,27 +112,24 @@ run();
 *   `async push(path, ...items)`
 *   `async pull(path, ...itemsToRemove)`
 *   `async transaction(asyncFn)`
-*   `async batch(operations)`
-*   `async query(predicateFn, [options])`
+*   `async batch(operations, [options])`
+*   `async find(collectionPath, predicate)`
+*   `async findByIndex(indexName, value)`
 *   `async clear()`
 *   `getStats()`
 *   `async close()`
-*   Properties: `filename`, `config`
-
-## Concurrency and Atomicity
-
-Writes are queued and executed one after another for a given instance, ensuring file integrity. Reads use an in-memory cache for speed. See Core Concepts in the full documentation for details.
+*   Events: `.on('write', handler)`, `.on('change', handler)`, `.on('error', handler)`
 
 ## Limitations
 
-*   Best suited for small to medium-sized JSON files. Performance degrades with very large files.
-*   Loads the entire database into memory.
-*   Designed for single-process access to a given file. Not suitable for distributed systems.
+*   **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
 
-Contributions (issues, PRs) are welcome! Please open an issue to discuss significant changes.
+Contributions, issues, and feature requests are welcome! Please feel free to open an issue to discuss any significant changes.
 
 ## License
 
-[MIT](LICENSE)
+[MIT](LICENSE)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "json-database-st",
-  "version": "1.0.5",
+  "version": "1.0.6",
   "description": "A simple, promise-based JSON file database for Node.js with atomic operations and lodash integration.",
   "main": "JSONDatabase.js",
   "scripts": {