json-database-st 1.0.6 → 1.0.8

package/JSONDatabase.js

@@ -1,485 +1,493 @@
-// 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}`);
-  }
-}
-
+// File: JSONDatabase.js
+// Final, Complete, and Secure Version (Patched)
+
+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);
+      // --- ENHANCEMENT: Make the instance unusable if init fails ---
+      // By re-throwing here, the _initPromise will be rejected, and all subsequent
+      // operations waiting on _ensureInitialized() will fail immediately.
+      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() {
+      // This promise will be rejected if _initialize() fails, stopping all operations.
+      return this._initPromise;
+  }
+
+  /** @private Performs an atomic write operation. */
+  async _atomicWrite(operationFn) {
+    await this._ensureInitialized();
+
+    // This promise chain ensures all writes happen one after another.
+    this.writeLock = this.writeLock.then(async () => {
+      // Use the live cache as the source of truth for the transaction.
+      const oldData = this.cache;
+      const dataToModify = _.cloneDeep(oldData);
+
+      try {
+        // --- CRITICAL FIX: Await the operation function in case it's async ---
+        const newData = await operationFn(dataToModify);
+
+        // --- ENHANCEMENT: Stricter check to prevent accidental data loss ---
+        if (newData === undefined) {
+          throw new TransactionError("Atomic operation function returned undefined. Aborting to prevent data loss. Did you forget to `return data`?");
+        }
+
+        if (this.config.schema) {
+          const validationResult = this.config.schema.safeParse(newData);
+          if (!validationResult.success) {
+            throw new ValidationError('Schema validation failed.', validationResult.error.issues);
+          }
+        }
+        
+        // --- ENHANCEMENT: Update indices *before* the write to catch violations early ---
+        // This will throw an IndexViolationError if there's a problem.
+        this._updateIndices(oldData, newData);
+
+        // Only write to disk if data has actually changed.
+        if (this.config.writeOnChange && _.isEqual(newData, oldData)) {
+          return oldData; // Return the unchanged data
+        }
+
+        const contentToWrite = this.config.encryptionKey
+          ? this._encrypt(newData)
+          : JSON.stringify(newData, null, this.config.prettyPrint ? 2 : 0);
+        
+        await fs.writeFile(this.filename, contentToWrite, 'utf8');
+
+        // Update cache only after a successful write.
+        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) {
+        // If any part of the transaction fails, emit the error and re-throw.
+        // The cache remains unchanged from before the operation.
+        this.emit('error', error);
+        console.error("[JSONDatabase] Atomic write failed. No changes were saved.", error);
+        throw error; // Propagate the error to the caller.
+      }
+    });
+
+    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, []);
+
+          // This logic works for both arrays of objects and objects of objects (maps)
+          const oldItems = _.values(oldCollection);
+          const newItems = _.values(newCollection);
+
+          const oldMap = new Map(oldItems.map(item => [item[field], item]));
+          const newMap = new Map(newItems.map(item => [item[field], item]));
+
+          // Find values that were removed or changed
+          for (const [oldValue, oldItem] of oldMap.entries()) {
+              if (oldValue !== undefined && !newMap.has(oldValue)) {
+                  indexMap.delete(oldValue);
+              }
+          }
+          
+          // Find values that were added or changed
+          for (const [newValue, newItem] of newMap.entries()) {
+               if (newValue !== undefined && !oldMap.has(newValue)) {
+                  if (indexDef.unique && indexMap.has(newValue)) {
+                      throw new IndexViolationError(`Unique index '${indexDef.name}' violated for value '${newValue}'.`);
+                  }
+                  // To find the key, we need to iterate, which isn't ideal but necessary here.
+                  const key = _.findKey(newCollection, {[field]: newValue});
+                  indexMap.set(newValue, key);
+               }
+          }
+      }
+  }
+
+
+  // --- Public API ---
+
+  async get(path, defaultValue) {
+    await this._ensureInitialized();
+    this.stats.cacheHits++;
+    // --- CRITICAL FIX: Handle undefined/null path to get the entire object ---
+    if (path === undefined || path === null) {
+      return this.cache;
+    }
+    return _.get(this.cache, path, defaultValue);
+  }
+
+  async has(path) {
+    await this._ensureInitialized();
+    this.stats.cacheHits++;
+    return _.has(this.cache, path);
+  }
+
+  async set(path, value) {
+    return 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;
+    return this._atomicWrite(data => {
+      const arr = _.get(data, path);
+      const targetArray = Array.isArray(arr) ? arr : [];
+      items.forEach(item => {
+        // Use deep comparison to ensure object uniqueness
+        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;
+    return 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;
+
+    return 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);
+      // Works for both objects and arrays
+      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);
+      // Construct the full path to the object
+      const fullPath = [..._.toPath(indexDef.path), objectKey];
+      return _.get(this.cache, fullPath);
+  }
+
+  async clear() {
+    console.warn(`[JSONDatabase] Clearing all data from ${this.filename}. This action is irreversible.`);
+    return this._atomicWrite(() => ({}));
+  }
+
+  getStats() {
+    return { ...this.stats };
+  }
+
+  async close() {
+    // Wait for the last pending write operation to finish
+    await this.writeLock;
+    
+    this.cache = null;
+    this._indices.clear();
+    this.removeAllListeners();
+    this._initPromise = null; // Allow for garbage collection
+
+    const finalStats = JSON.stringify(this.getStats());
+    console.log(`[JSONDatabase] Closed connection to ${this.filename}. Final Stats: ${finalStats}`);
+  }
+}
+
 module.exports = JSONDatabase;

package/LICENSE

@@ -18,4 +18,4 @@ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+SOFTWARE.

package/package.json

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