json-database-st 1.0.4 → 1.0.6

package/JSONDatabase.js

@@ -0,0 +1,485 @@
+// File: JSONDatabase.js
+// Final, Complete, and Secure Version
+
+const fs = require('fs').promises;
+const path = require('path');
+const crypto = require('crypto');
+const _ = require('lodash');
+const EventEmitter = require('events');
+
+// --- Custom Error Classes for Better Error Handling ---
+
+/** Base error for all database-specific issues. */
+class DBError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = this.constructor.name;
+  }
+}
+/** Error during database file initialization or parsing. */
+class DBInitializationError extends DBError {}
+/** Error within a user-provided transaction function. */
+class TransactionError extends DBError {}
+/** Error when data fails schema validation. */
+class ValidationError extends DBError {
+  constructor(message, validationIssues) {
+    super(message);
+    this.issues = validationIssues; // e.g., from Zod/Joi
+  }
+}
+/** Error related to index integrity (e.g., unique constraint violation). */
+class IndexViolationError extends DBError {}
+/** Error for security-related issues like path traversal or bad keys. */
+class SecurityError extends DBError {}
+
+
+// --- Type Definitions for Clarity ---
+
+/**
+ * @typedef {object} BatchOperationSet
+ * @property {'set'} type
+ * @property {string | string[]} path
+ * @property {any} value
+ */
+
+/**
+ * @typedef {object} BatchOperationDelete
+ * @property {'delete'} type
+ * @property {string | string[]} path
+ */
+
+/**
+ * @typedef {object} BatchOperationPush
+ * @property {'push'} type
+ * @property {string | string[]} path
+ * @property {any[]} values - Items to push uniquely using deep comparison.
+ */
+
+/**
+ * @typedef {object} BatchOperationPull
+ * @property {'pull'} type
+ * @property {string | string[]} path
+ * @property {any[]} values - Items to remove using deep comparison.
+ */
+
+/**
+ * @typedef {BatchOperationSet | BatchOperationDelete | BatchOperationPush | BatchOperationPull} BatchOperation
+ */
+
+/**
+ * @typedef {object} IndexDefinition
+ * @property {string} name - The unique name for the index.
+ * @property {string | string[]} path - The lodash path to the collection object (e.g., 'users').
+ * @property {string} field - The property field within each collection item to index (e.g., 'email').
+ * @property {boolean} [unique=false] - If true, enforces that the indexed field must be unique across the collection.
+ */
+
+
+// --- Cryptography Constants ---
+const ALGORITHM = 'aes-256-gcm';
+const IV_LENGTH = 16;
+const AUTH_TAG_LENGTH = 16;
+
+
+/**
+ * A robust, secure, promise-based JSON file database with atomic operations, indexing, schema validation, and events.
+ * Includes encryption-at-rest and path traversal protection.
+ *
+ * @class JSONDatabase
+ * @extends {EventEmitter}
+ */
+class JSONDatabase extends EventEmitter {
+  /**
+   * Creates a database instance.
+   *
+   * @param {string} filename - Database file path.
+   * @param {object} [options] - Configuration options.
+   * @param {string} [options.encryptionKey=null] - A 32-byte (64-character hex) secret key for encryption. If provided, enables encryption-at-rest. **MANAGE THIS KEY SECURELY.**
+   * @param {boolean} [options.prettyPrint=false] - Pretty-print JSON output (only if not encrypted).
+   * @param {boolean} [options.writeOnChange=true] - Only write to disk if data has changed.
+   * @param {object} [options.schema=null] - A validation schema (e.g., from Zod) with a `safeParse` method.
+   * @param {IndexDefinition[]} [options.indices=[]] - An array of index definitions for fast lookups.
+   * @throws {SecurityError} If the filename is invalid or attempts path traversal.
+   * @throws {SecurityError} If an encryption key is provided but is not the correct length.
+   */
+  constructor(filename, options = {}) {
+    super();
+
+    // --- Security Check: Path Traversal ---
+    const resolvedPath = path.resolve(filename);
+    const workingDir = process.cwd();
+    if (!resolvedPath.startsWith(workingDir)) {
+      throw new SecurityError(`Path traversal detected. Database path must be within the project directory: ${workingDir}`);
+    }
+    this.filename = /\.json$/.test(resolvedPath) ? resolvedPath : `${resolvedPath}.json`;
+
+    // --- Security Check: Encryption Key ---
+    if (options.encryptionKey && (!options.encryptionKey || Buffer.from(options.encryptionKey, 'hex').length !== 32)) {
+      throw new SecurityError('Encryption key must be a 32-byte (64-character hex) string.');
+    }
+
+    this.config = {
+      prettyPrint: options.prettyPrint === true,
+      writeOnChange: options.writeOnChange !== false,
+      schema: options.schema || null,
+      indices: options.indices || [],
+      encryptionKey: options.encryptionKey ? Buffer.from(options.encryptionKey, 'hex') : null,
+    };
+
+    this.cache = null;
+    this.writeLock = Promise.resolve();
+    this.stats = { reads: 0, writes: 0, cacheHits: 0 };
+    this._indices = new Map();
+
+    // Asynchronously initialize. Operations will queue behind this promise.
+    this._initPromise = this._initialize();
+  }
+
+  // --- Encryption & Decryption ---
+  _encrypt(data) {
+    const iv = crypto.randomBytes(IV_LENGTH);
+    const cipher = crypto.createCipheriv(ALGORITHM, this.config.encryptionKey, iv);
+    const jsonString = JSON.stringify(data);
+    const encrypted = Buffer.concat([cipher.update(jsonString, 'utf8'), cipher.final()]);
+    const authTag = cipher.getAuthTag();
+    return JSON.stringify({
+      iv: iv.toString('hex'),
+      tag: authTag.toString('hex'),
+      content: encrypted.toString('hex'),
+    });
+  }
+
+  _decrypt(encryptedPayload) {
+    try {
+      const payload = JSON.parse(encryptedPayload);
+      const iv = Buffer.from(payload.iv, 'hex');
+      const authTag = Buffer.from(payload.tag, 'hex');
+      const encryptedContent = Buffer.from(payload.content, 'hex');
+      const decipher = crypto.createDecipheriv(ALGORITHM, this.config.encryptionKey, iv);
+      decipher.setAuthTag(authTag);
+      const decrypted = decipher.update(encryptedContent, 'hex', 'utf8') + decipher.final('utf8');
+      return JSON.parse(decrypted);
+    } catch (e) {
+      throw new SecurityError('Decryption failed. The file may be corrupted, tampered with, or the encryption key is incorrect.');
+    }
+  }
+
+  // --- Private Core Methods ---
+
+  /** @private Kicks off the initialization process. */
+  async _initialize() {
+    try {
+      await this._refreshCache();
+      this._rebuildAllIndices();
+    } catch (err) {
+      const initError = new DBInitializationError(`Failed to initialize database: ${err.message}`);
+      this.emit('error', initError);
+      console.error(`[JSONDatabase] FATAL: Initialization failed for ${this.filename}. The database is in an unusable state.`, err);
+      throw initError;
+    }
+  }
+
+  /** @private Reads file, decrypts if necessary, and populates cache. */
+  async _refreshCache() {
+    try {
+      const fileContent = await fs.readFile(this.filename, 'utf8');
+      if (this.config.encryptionKey) {
+        this.cache = fileContent.trim() === '' ? {} : this._decrypt(fileContent);
+      } else {
+        this.cache = fileContent.trim() === '' ? {} : JSON.parse(fileContent);
+      }
+      this.stats.reads++;
+    } catch (err) {
+      if (err.code === 'ENOENT') {
+        console.warn(`[JSONDatabase] File ${this.filename} not found. Creating.`);
+        this.cache = {};
+        const initialContent = this.config.encryptionKey ? this._encrypt({}) : '{}';
+        await fs.writeFile(this.filename, initialContent, 'utf8');
+        this.stats.writes++;
+      } else if (err instanceof SyntaxError && !this.config.encryptionKey) {
+        throw new DBInitializationError(`Failed to parse JSON from ${this.filename}. File is corrupted.`);
+      } else {
+        throw err; // Re-throw security, crypto, and other errors
+      }
+    }
+  }
+
+  /** @private Ensures all operations wait for initialization to complete. */
+  async _ensureInitialized() {
+      return this._initPromise;
+  }
+
+  /** @private Performs an atomic write operation. */
+  async _atomicWrite(operationFn) {
+    await this._ensureInitialized();
+
+    this.writeLock = this.writeLock.then(async () => {
+      const oldData = this.cache;
+      const dataToModify = _.cloneDeep(oldData);
+
+      try {
+        const newData = operationFn(dataToModify);
+        if (newData === undefined) {
+          throw new TransactionError("Atomic operation function returned undefined. Aborting to prevent data loss.");
+        }
+
+        if (this.config.schema) {
+          const validationResult = this.config.schema.safeParse(newData);
+          if (!validationResult.success) {
+            throw new ValidationError('Schema validation failed.', validationResult.error.issues);
+          }
+        }
+
+        if (this.config.writeOnChange && _.isEqual(newData, oldData)) {
+          return oldData;
+        }
+        
+        this._updateIndices(oldData, newData);
+
+        const contentToWrite = this.config.encryptionKey
+          ? this._encrypt(newData)
+          : JSON.stringify(newData, null, this.config.prettyPrint ? 2 : 0);
+        
+        await fs.writeFile(this.filename, contentToWrite, 'utf8');
+
+        this.cache = newData;
+        this.stats.writes++;
+        
+        this.emit('write', { filename: this.filename, timestamp: Date.now() });
+        this.emit('change', { oldValue: oldData, newValue: newData });
+
+        return newData;
+
+      } catch (error) {
+        this.emit('error', error);
+        console.error("[JSONDatabase] Atomic write failed. No changes were saved.", error);
+        throw error;
+      }
+    });
+
+    return this.writeLock;
+  }
+  
+  // --- Indexing ---
+
+  /** @private Clears and rebuilds all defined indices from the current cache. */
+  _rebuildAllIndices() {
+      this._indices.clear();
+      for (const indexDef of this.config.indices) {
+          this._indices.set(indexDef.name, new Map());
+      }
+      if (this.config.indices.length > 0 && !_.isEmpty(this.cache)) {
+          this._updateIndices({}, this.cache); // Treat it as a full "add" operation
+      }
+      console.log(`[JSONDatabase] Rebuilt ${this.config.indices.length} indices for ${this.filename}.`);
+  }
+
+  /** @private Compares old and new data to update indices efficiently. */
+  _updateIndices(oldData, newData) {
+      for (const indexDef of this.config.indices) {
+          const collectionPath = indexDef.path;
+          const field = indexDef.field;
+          const indexMap = this._indices.get(indexDef.name);
+
+          const oldCollection = _.get(oldData, collectionPath, {});
+          const newCollection = _.get(newData, collectionPath, {});
+
+          const oldKeys = Object.keys(oldCollection);
+          const newKeys = Object.keys(newCollection);
+          
+          const addedKeys = _.difference(newKeys, oldKeys);
+          const removedKeys = _.difference(oldKeys, newKeys);
+          const potentiallyModifiedKeys = _.intersection(oldKeys, newKeys);
+          
+          for (const key of removedKeys) {
+              const oldItem = oldCollection[key];
+              if (oldItem && oldItem[field] !== undefined) {
+                  indexMap.delete(oldItem[field]);
+              }
+          }
+
+          for (const key of addedKeys) {
+              const newItem = newCollection[key];
+              const indexValue = newItem?.[field];
+              if (indexValue !== undefined) {
+                  if (indexDef.unique && indexMap.has(indexValue)) {
+                      throw new IndexViolationError(`Unique index '${indexDef.name}' violated for value '${indexValue}'.`);
+                  }
+                  indexMap.set(indexValue, key);
+              }
+          }
+
+          for (const key of potentiallyModifiedKeys) {
+              const oldItem = oldCollection[key];
+              const newItem = newCollection[key];
+              const oldIndexValue = oldItem?.[field];
+              const newIndexValue = newItem?.[field];
+              
+              if (!_.isEqual(oldItem, newItem) && oldIndexValue !== newIndexValue) {
+                  if (oldIndexValue !== undefined) indexMap.delete(oldIndexValue);
+                  if (newIndexValue !== undefined) {
+                      if (indexDef.unique && indexMap.has(newIndexValue)) {
+                          throw new IndexViolationError(`Unique index '${indexDef.name}' violated for value '${newIndexValue}'.`);
+                      }
+                      indexMap.set(newIndexValue, key);
+                  }
+              }
+          }
+      }
+  }
+
+
+  // --- Public API ---
+
+  async get(path, defaultValue) {
+    await this._ensureInitialized();
+    this.stats.cacheHits++;
+    return _.get(this.cache, path, defaultValue);
+  }
+
+  async has(path) {
+    await this._ensureInitialized();
+    this.stats.cacheHits++;
+    return _.has(this.cache, path);
+  }
+
+  async set(path, value) {
+    await this._atomicWrite(data => {
+      _.set(data, path, value);
+      return data;
+    });
+  }
+
+  async delete(path) {
+    let deleted = false;
+    await this._atomicWrite(data => {
+      deleted = _.unset(data, path);
+      return data;
+    });
+    return deleted;
+  }
+
+  async push(path, ...items) {
+    if (items.length === 0) return;
+    await this._atomicWrite(data => {
+      const arr = _.get(data, path);
+      const targetArray = Array.isArray(arr) ? arr : [];
+      items.forEach(item => {
+        if (!targetArray.some(existing => _.isEqual(existing, item))) {
+          targetArray.push(item);
+        }
+      });
+      _.set(data, path, targetArray);
+      return data;
+    });
+  }
+
+  async pull(path, ...itemsToRemove) {
+    if (itemsToRemove.length === 0) return;
+    await this._atomicWrite(data => {
+      const arr = _.get(data, path);
+      if (Array.isArray(arr)) {
+        _.pullAllWith(arr, itemsToRemove, _.isEqual);
+      }
+      return data;
+    });
+  }
+
+  async transaction(transactionFn) {
+    return this._atomicWrite(transactionFn);
+  }
+
+  async batch(ops, options = { stopOnError: false }) {
+    if (!Array.isArray(ops) || ops.length === 0) return;
+
+    await this._atomicWrite(data => {
+      for (const [index, op] of ops.entries()) {
+        try {
+          if (!op || !op.type || op.path === undefined) throw new Error("Invalid operation format: missing type or path.");
+          
+          switch (op.type) {
+            case 'set':
+              if (!op.hasOwnProperty('value')) throw new Error("Set operation missing 'value'.");
+              _.set(data, op.path, op.value);
+              break;
+            case 'delete':
+              _.unset(data, op.path);
+              break;
+            case 'push':
+              if (!Array.isArray(op.values)) throw new Error("Push operation 'values' must be an array.");
+              const arr = _.get(data, op.path);
+              const targetArray = Array.isArray(arr) ? arr : [];
+              op.values.forEach(item => {
+                  if (!targetArray.some(existing => _.isEqual(existing, item))) targetArray.push(item);
+              });
+              _.set(data, op.path, targetArray);
+              break;
+            case 'pull':
+              if (!Array.isArray(op.values)) throw new Error("Pull operation 'values' must be an array.");
+              const pullArr = _.get(data, op.path);
+              if (Array.isArray(pullArr)) _.pullAllWith(pullArr, op.values, _.isEqual);
+              break;
+            default:
+              throw new Error(`Unsupported operation type: '${op.type}'.`);
+          }
+        } catch (err) {
+            const errorMessage = `[JSONDatabase] Batch failed at operation index ${index} (type: ${op?.type}): ${err.message}`;
+            if (options.stopOnError) {
+                throw new Error(errorMessage);
+            } else {
+                console.error(errorMessage);
+            }
+        }
+      }
+      return data;
+    });
+  }
+
+  async find(collectionPath, predicate) {
+      await this._ensureInitialized();
+      const collection = _.get(this.cache, collectionPath);
+      if (typeof collection !== 'object' || collection === null) return undefined;
+      
+      this.stats.cacheHits++;
+      return _.find(collection, predicate);
+  }
+  
+  async findByIndex(indexName, value) {
+      await this._ensureInitialized();
+      if (!this._indices.has(indexName)) {
+          throw new Error(`Index with name '${indexName}' does not exist.`);
+      }
+
+      this.stats.cacheHits++;
+      const indexMap = this._indices.get(indexName);
+      const objectKey = indexMap.get(value);
+
+      if (objectKey === undefined) return undefined;
+
+      const indexDef = this.config.indices.find(i => i.name === indexName);
+      return _.get(this.cache, [..._.toPath(indexDef.path), objectKey]);
+  }
+
+  async clear() {
+    console.warn(`[JSONDatabase] Clearing all data from ${this.filename}.`);
+    await this._atomicWrite(() => ({}));
+  }
+
+  getStats() {
+    return { ...this.stats };
+  }
+
+  async close() {
+    await this.writeLock;
+    
+    this.cache = null;
+    this._indices.clear();
+    this.removeAllListeners();
+    this._initPromise = null;
+
+    const finalStats = JSON.stringify(this.getStats());
+    console.log(`[JSONDatabase] Closed connection to ${this.filename}. Final Stats: ${finalStats}`);
+  }
+}
+
+module.exports = JSONDatabase;

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.4",
+  "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": {