json-database-st 1.0.2 → 1.0.5

package/JSONDatabase.js

@@ -1,627 +1,485 @@
-// File: JSONDatabase.js
-
-const fs = require("fs").promises;
-const path = require("path");
-const _ = require("lodash"); // Ensure lodash is installed: npm install lodash
-
-const jsonRegex = /\.json$/;
-
-/**
- * @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
- */
-
-/**
- * A simple, promise-based JSON file database with atomic operations.
- * Uses lodash for object manipulation.
- *
- * @class JSONDatabase
- */
-class JSONDatabase {
-  /**
-   * Creates a database instance.
-   *
-   * @param {string} filename - Database file path (e.g., 'db.json' or './data/myDb'). '.json' extension is added if missing.
-   * @param {object} [options] - Configuration options.
-   * @param {boolean} [options.prettyPrint=false] - Pretty-print JSON file output (adds indentation). Defaults to false for smaller file size.
-   */
-  constructor(filename, options = {}) {
-    if (!jsonRegex.test(filename)) {
-      this.filename = path.resolve(`${filename}.json`);
-    } else {
-      this.filename = path.resolve(filename);
-    }
-    this.cache = null; // In-memory cache of the database content
-    this.writeLock = null; // Promise acting as a lock for atomic writes
-    this.config = {
-      prettyPrint: options.prettyPrint === true, // Explicit check
-    };
-    this.stats = { reads: 0, writes: 0, cacheHits: 0 };
-    this._initPromise = null; // Track initialization promise
-
-    // Initialize cache asynchronously, handle errors during init.
-    this._init().catch((err) => {
-      console.error(
-        `[JSONDatabase] FATAL: Initialization failed for ${this.filename}:`,
-        err
-      );
-      // Optionally, set a state indicating permanent failure
-    });
-  }
-
-  /** @private Initialize cache by reading the file */
-  async _init() {
-    // Prevent race conditions during initial load if multiple operations trigger it
-    if (this._initPromise) return this._initPromise;
-
-    // Create the promise and store it
-    this._initPromise = this._refreshCache();
-
-    try {
-      await this._initPromise;
-    } finally {
-      // Clear the promise variable once initialization is complete (success or failure)
-      // So subsequent calls to _init (if needed, e.g. after close/re-open) would trigger a new load
-      this._initPromise = null;
-    }
-    return this.cache; // Return cache state after init attempt
-  }
-
-  /** @private Reads the database file and populates the cache. Creates file if not exists. */
-  async _refreshCache() {
-    try {
-      const data = await fs.readFile(this.filename, "utf8");
-      // Handle case where file is empty or contains only whitespace
-      this.cache = data.trim() === "" ? {} : JSON.parse(data);
-      this.stats.reads++;
-      return this.cache;
-    } catch (err) {
-      if (err.code === "ENOENT") {
-        // File doesn't exist, create it with an empty object
-        console.warn(
-          `[JSONDatabase] File ${this.filename} not found. Creating.`
-        );
-        try {
-          await fs.writeFile(this.filename, "{}", "utf8");
-          this.cache = {};
-          this.stats.writes++; // Count file creation as a write
-          return this.cache;
-        } catch (writeErr) {
-          console.error(
-            `[JSONDatabase] Failed to create ${this.filename}:`,
-            writeErr
-          );
-          throw writeErr; // Re-throw creation error
-        }
-      } else if (err instanceof SyntaxError) {
-        // Handle corrupted JSON file
-        console.error(
-          `[JSONDatabase] Error parsing JSON from ${this.filename}. File might be corrupted. Returning empty object and logging error.`,
-          err
-        );
-        // Decide recovery strategy: Throw, reset to {}, load backup?
-        // For robustness, let's reset the cache to {} but throw the original error
-        this.cache = {}; // Prevent operations on potentially bad data
-        throw new Error(
-          `Failed to parse JSON file: ${this.filename}. ${err.message}`
-        );
-      }
-      // Log and re-throw other unexpected errors
-      console.error(
-        `[JSONDatabase] Error reading or parsing ${this.filename}:`,
-        err
-      );
-      throw err;
-    }
-  }
-
-  /**
-   * @private Ensures atomic write operations using a lock.
-   * Takes a function that receives the current data state and should return the modified state.
-   * @param {(data: object) => object | Promise<object>} operationFn - Function performing the modification.
-   * @returns {Promise<object>} The final data state after the write.
-   */
-  async _atomicWrite(operationFn) {
-    // Ensure initialization is complete before attempting writes
-    // If _initPromise exists, await it. If not, call _init() which handles the lock itself.
-    await (this._initPromise || this._init());
-
-    // Chain onto the existing lock promise if it exists
-    const performWrite = async () => {
-      let dataToModify;
-      try {
-        // Get the most recent data, MUST be from cache as it reflects the state after the previous write lock released.
-        // If cache is somehow null here (edge case after close?), refresh.
-        dataToModify = _.cloneDeep(this.cache ?? (await this._refreshCache()));
-
-        // Execute the user-provided operation function
-        const result = await operationFn(dataToModify);
-
-        // The operationFn *must* return the data object to be written.
-        const dataToWrite = result;
-        if (dataToWrite === undefined) {
-          // This indicates a potential programming error in the calling function (e.g., transaction, batch)
-          console.error(
-            "[JSONDatabase] FATAL: Atomic operation function returned undefined. This should not happen. Aborting write to prevent data loss."
-          );
-          throw new Error(
-            "Atomic operation function returned undefined, cannot proceed with write."
-          );
-        }
-
-        // Optimization: Only write if data actually changed. Deep compare can be costly for large objects.
-        // Let's keep it simple and write every time for guaranteed consistency, unless performance becomes an issue.
-        // if (_.isEqual(dataToWrite, this.cache)) {
-        //     return this.cache; // No change, return current cache state
-        // }
-
-        await fs.writeFile(
-          this.filename,
-          JSON.stringify(dataToWrite, null, this.config.prettyPrint ? 2 : 0),
-          "utf8"
-        );
-
-        this.cache = dataToWrite; // Update cache AFTER successful write
-        this.stats.writes++;
-        return this.cache; // Return the final state written to disk/cache
-      } catch (error) {
-        console.error(
-          "[JSONDatabase] Error during atomic write operation:",
-          error
-        );
-        // Don't update cache on error, state is uncertain relative to the disk.
-        // A subsequent read/write *should* re-sync if the error was temporary.
-        throw error; // Re-throw the error to the caller
-      }
-    };
-
-    // Assign the promise of the current write operation to the lock, ensuring sequential execution.
-    // The `then()` ensures we wait for the previous lock to finish before starting the new write.
-    this.writeLock = (this.writeLock || Promise.resolve()).then(
-      performWrite,
-      performWrite
-    );
-    // We return the promise assigned to this.writeLock so callers can await this specific operation's completion.
-    return this.writeLock;
-  }
-
-  /**
-   * Gets a value from the database using a lodash path.
-   * Returns undefined if the path does not exist, unless a defaultValue is provided.
-   *
-   * @param {string | string[]} path - The lodash path (e.g., 'users.john.age' or ['users', 'john', 'age']).
-   * @param {any} [defaultValue] - Value to return if path is not found.
-   * @returns {Promise<any>} The value found at the path or the default value.
-   */
-  async get(path, defaultValue) {
-    // Ensure cache is loaded. _init() handles the initialization promise logic.
-    await this._init();
-    const data = this.cache; // Read directly from cache after init ensures it's loaded
-    this.stats.cacheHits++;
-    return _.get(data, path, defaultValue);
-  }
-
-  /**
-   * Sets a value in the database at a specific lodash path.
-   *
-   * @param {string | string[]} path - The lodash path to set.
-   * @param {any} value - The value to set. Can be any JSON-serializable type.
-   * @returns {Promise<void>} Resolves when the write operation is complete.
-   */
-  async set(path, value) {
-    // The void return type means callers don't get the data back directly,
-    // but the promise resolution confirms the write completed.
-    await this._atomicWrite((data) => {
-      _.set(data, path, value);
-      return data; // Return the modified data object for the atomic write process
-    });
-  }
-
-  /**
-   * Pushes one or more items into an array at the specified path.
-   * If the path doesn't exist or isn't an array, it creates/replaces it with a new array containing the items.
-   * Ensures items are unique within the array using deep comparison (`lodash.isEqual`).
-   *
-   * @param {string | string[]} path - The lodash path to the array.
-   * @param {...any} items - The items to push into the array.
-   * @returns {Promise<void>} Resolves when the write operation is complete.
-   */
-  async push(path, ...items) {
-    if (items.length === 0) return; // No-op if no items provided
-    await this._atomicWrite((data) => {
-      let arr = _.get(data, path);
-      // Initialize as array if path doesn't exist or holds a non-array value
-      if (!Array.isArray(arr)) {
-        arr = [];
-        // Ensure the path is set to an empty array before proceeding
-        _.set(data, path, arr);
-      }
-
-      let changed = false;
-      items.forEach((item) => {
-        // Use lodash isEqual for deep comparison to check existence
-        const itemExists = arr.some((existingItem) =>
-          _.isEqual(existingItem, item)
-        );
-        if (!itemExists) {
-          arr.push(item);
-          changed = true;
-        }
-      });
-
-      // No need to _.set again if arr reference was modified in place and already set
-      // However, if arr was initialized (arr = []), _.set was needed above.
-      // The atomic write will handle writing 'data' regardless if 'changed' is true.
-      // Returning 'data' is sufficient.
-
-      return data; // Return the data object (potentially modified)
-    });
-  }
-
-  /**
-   * Removes specified items from an array at the given path.
-   * Uses deep comparison (`lodash.isEqual`) via `lodash.pullAllWith`.
-   * If the target path doesn't exist or is not an array, the operation is ignored silently.
-   *
-   * @param {string | string[]} path - Dot notation path to the array.
-   * @param {...any} itemsToRemove - Items to remove from the array.
-   * @returns {Promise<void>} Resolves when the write operation is complete.
-   */
-  async pull(path, ...itemsToRemove) {
-    if (itemsToRemove.length === 0) return; // No-op if no items provided
-    await this._atomicWrite((data) => {
-      let arr = _.get(data, path);
-
-      if (!Array.isArray(arr)) {
-        // Silently ignore if target is not an array
-        return data; // Return unmodified data
-      }
-
-      const initialLength = arr.length;
-      // Use pullAllWith and isEqual for robust object comparison during removal
-      _.pullAllWith(arr, itemsToRemove, _.isEqual);
-
-      // If the array length changed, the data object 'data' now contains the modified array.
-      // No explicit _.set is needed here as pullAllWith modifies the array in place,
-      // and 'arr' is a reference within 'data'.
-
-      // Only trigger a file write if something actually changed (handled by atomicWrite comparing result)
-      // if (arr.length !== initialLength) {
-      // _.set(data, path, arr); // No need to set again, arr is ref inside data
-      // }
-      return data; // Return the data object (potentially modified)
-    });
-  }
-
-  /**
-   * Deletes a value or property at the specified path.
-   *
-   * @param {string | string[]} path - The lodash path to delete.
-   * @returns {Promise<boolean>} True if the path existed and was deleted, false otherwise.
-   */
-  async delete(path) {
-    let deleted = false;
-    await this._atomicWrite((data) => {
-      // _.unset modifies 'data' in place and returns boolean
-      deleted = _.unset(data, path);
-      return data; // Return the modified data object
-    });
-    // Return the result captured from _.unset
-    return deleted;
-  }
-
-  /**
-   * Checks if a path exists in the database.
-   * Note: An existing path with a value of `undefined` will return `true`.
-   *
-   * @param {string | string[]} path - The lodash path to check.
-   * @returns {Promise<boolean>} True if the path exists, false otherwise.
-   */
-  async has(path) {
-    await this._init(); // Ensure cache is ready
-    const data = this.cache;
-    this.stats.cacheHits++;
-    return _.has(data, path);
-  }
-
-  /**
-   * Performs an atomic transaction.
-   * The provided asynchronous function receives the current database state (as a deep clone)
-   * and should return the modified state to be written.
-   * If the function throws an error, the transaction is aborted, and no changes are saved.
-   * If the function returns `undefined`, an error is thrown to prevent potential data loss.
-   *
-   * @param {(data: object) => Promise<object> | object} asyncFn - An async function that modifies the data. It MUST return the modified data object.
-   * @returns {Promise<object>} A promise that resolves with the final database state after the transaction (the value returned by `asyncFn`).
-   * @throws {Error} Throws if the transaction function `asyncFn` throws an error, or if `asyncFn` returns undefined.
-   * @example
-   * await db.transaction(async (data) => {
-   *   const user = _.get(data, 'users.john');
-   *   if (user) {
-   *     user.visits = (user.visits || 0) + 1;
-   *     _.set(data, 'users.john', user); // Optional if modifying user in place
-   *   }
-   *   return data; // MUST return the modified data
-   * });
-   */
-  async transaction(asyncFn) {
-    // _atomicWrite handles the locking, cloning, writing, and cache update.
-    // It expects a function that receives data and returns the modified data.
-    // asyncFn fits this signature. We just pass it through.
-    // _atomicWrite also handles the 'undefined' return check now.
-    return this._atomicWrite(asyncFn);
-  }
-
-  /**
-   * Executes multiple operations atomically within a single write lock.
-   * Supported operations: 'set', 'delete', 'push', 'pull'.
-   * Operations are executed sequentially in the provided order.
-   * If any operation definition is invalid (e.g., missing path/value, invalid type) or
-   * encounters an error during its execution (this is less likely for simple types but possible),
-   * an error is logged, and the batch processing *continues* with the next operation by default.
-   * The entire final state is written to disk once all operations are attempted.
-   *
-   * @param {BatchOperation[]} ops - An array of operation objects.
-   * @returns {Promise<void>} Resolves when the batch write is complete.
-   * @example
-   * await db.batch([
-   *   { type: 'set', path: 'users.jane', value: { age: 30 } },
-   *   { type: 'push', path: 'users.jane.hobbies', values: ['reading', 'hiking'] }, // deep compares items in 'values'
-   *   { type: 'pull', path: 'config.features', values: ['betaFeature'] }, // deep compares items in 'values'
-   *   { type: 'delete', path: 'users.oldUser' }
-   * ]);
-   */
-  async batch(ops) {
-    if (!Array.isArray(ops) || ops.length === 0) {
-      console.warn("[JSONDatabase] Batch called with no operations.");
-      return; // No operations to perform
-    }
-
-    await this._atomicWrite((data) => {
-      ops.forEach((op, index) => {
-        try {
-          // Validate base operation structure
-          if (!op || typeof op !== "object" || !op.type) {
-            throw new Error(
-              `Operation at index ${index} is invalid or missing 'type'.`
-            );
-          }
-
-          switch (op.type) {
-            case "set":
-              if (op.path === undefined || !op.hasOwnProperty("value"))
-                throw new Error(
-                  `Batch 'set' op index ${index} missing 'path' or 'value'.`
-                );
-              _.set(data, op.path, op.value);
-              break;
-            case "delete":
-              if (op.path === undefined)
-                throw new Error(
-                  `Batch 'delete' op index ${index} missing 'path'.`
-                );
-              _.unset(data, op.path);
-              break;
-            case "push": {
-              if (op.path === undefined || !Array.isArray(op.values))
-                throw new Error(
-                  `Batch 'push' op index ${index} missing 'path' or 'values' array.`
-                );
-              if (op.values.length === 0) break; // Skip if no values to push
-
-              let arr = _.get(data, op.path);
-              if (!Array.isArray(arr)) {
-                arr = []; // Initialize if not array
-                _.set(data, op.path, arr); // Set the path to the new array
-              }
-              op.values.forEach((item) => {
-                const itemExists = arr.some((existing) =>
-                  _.isEqual(existing, item)
-                );
-                if (!itemExists) {
-                  arr.push(item);
-                } // Push modifies arr in place
-              });
-              break;
-            }
-            case "pull": {
-              if (op.path === undefined || !Array.isArray(op.values))
-                throw new Error(
-                  `Batch 'pull' op index ${index} missing 'path' or 'values' array.`
-                );
-              if (op.values.length === 0) break; // Skip if no values to pull
-
-              let arr = _.get(data, op.path);
-              if (Array.isArray(arr)) {
-                _.pullAllWith(arr, op.values, _.isEqual); // pullAllWith modifies arr in place
-              } // else ignore pull from non-array silently
-              break;
-            }
-            default:
-              // Use Error for invalid type as it indicates a programming mistake
-              throw new Error(
-                `Invalid batch operation type: '${op.type}' at index ${index}.`
-              );
-          }
-        } catch (batchOpError) {
-          // Log the error but continue processing the rest of the batch
-          console.error(
-            `[JSONDatabase] Error during batch operation index ${index} (type: ${op?.type}, path: ${op?.path}):`,
-            batchOpError.message
-          );
-          // Optional: Could add an option to stop batch on first error if needed
-        }
-      });
-      // Return the final state after all batch operations attempted
-      return data;
-    });
-  }
-
-  /**
-   * Queries the database based on a predicate function.
-   * Iterates over the direct properties (key-value pairs) of an object specified by `options.basePath`,
-   * or the root object of the database if `basePath` is omitted.
-   * Returns an array of the **values** of the properties that satisfy the predicate.
-   *
-   * @param {(value: any, key: string) => boolean} predicate - A function returning true for items to include. Receives (value, key) of each property being iterated.
-   * @param {object} [options] - Query options.
-   * @param {string | string[]} [options.basePath] - A lodash path to the object whose properties should be queried.
-   * @param {number} [options.limit] - Maximum number of results to return.
-   * @returns {Promise<any[]>} An array of **values** that satisfy the predicate.
-   * @example
-   * // Find all users older than 30 within the 'users' object
-   * const oldUsers = await db.query(
-   *   (userValue, userKey) => typeof userValue === 'object' && userValue.age > 30,
-   *   { basePath: 'users' }
-   * );
-   * // -> [ { name: 'Alice', age: 35, ... }, { name: 'Charlie', age: 40, ... } ]
-   *
-   * // Find top-level properties whose key starts with 'config'
-   * const configValues = await db.query(
-   *   (value, key) => key.startsWith('config')
-   * );
-   * // -> [ { theme: 'dark', ... }, { region: 'us-east', ... } ] (assuming config objects exist at root)
-   */
-  async query(predicate, options = {}) {
-    await this._init(); // Ensure cache is ready
-    const data = this.cache;
-    this.stats.cacheHits++; // Count query as cache hit
-
-    const basePath = options.basePath;
-    // Use _.get to safely retrieve the base object/value
-    const baseData = basePath ? _.get(data, basePath) : data;
-
-    // Ensure baseData is an object we can iterate over
-    if (
-      typeof baseData !== "object" ||
-      baseData === null ||
-      Array.isArray(baseData)
-    ) {
-      if (basePath) {
-        console.warn(
-          `[JSONDatabase] Query basePath "${basePath}" does not point to an iterable object (must be a plain object). Returning empty array.`
-        );
-      } else {
-        console.warn(
-          `[JSONDatabase] Query attempted on non-object root data type (${typeof baseData}). Returning empty array.`
-        );
-      }
-      return [];
-    }
-
-    const results = [];
-    const limit = options.limit ?? Infinity;
-
-    // Iterate over the properties of the baseData object
-    for (const key in baseData) {
-      // Ensure we only iterate own properties
-      if (Object.prototype.hasOwnProperty.call(baseData, key)) {
-        if (results.length >= limit) {
-          break; // Stop iteration if limit is reached
-        }
-        const value = baseData[key];
-        try {
-          if (predicate(value, key)) {
-            results.push(value); // Return the value that matched
-          }
-        } catch (predicateError) {
-          console.error(
-            `[JSONDatabase] Error executing query predicate for key "${key}":`,
-            predicateError
-          );
-          // Skip this item or handle error as needed (currently skipping)
-        }
-      }
-    }
-
-    // Slice again in case limit was exactly reached (though break should handle it)
-    return results.slice(0, limit);
-  }
-
-  /**
-   * Clears the entire database content, replacing it with an empty object `{}`.
-   * This is an atomic write operation. Use with caution!
-   * @returns {Promise<void>} Resolves when the database has been cleared.
-   */
-  async clear() {
-    await this._atomicWrite(() => {
-      // Return an empty object to be written
-      return {};
-    });
-    console.warn(`[JSONDatabase] Cleared all data from ${this.filename}.`);
-  }
-
-  /**
-   * Returns the current operational statistics for this database instance.
-   * @returns {{reads: number, writes: number, cacheHits: number}}
-   */
-  getStats() {
-    // Return a copy to prevent external modification of the internal stats object
-    return { ...this.stats };
-  }
-
-  /**
-   * Waits for any pending write operations queued by this instance to complete,
-   * then clears the internal cache and releases the write lock.
-   * Does not delete the database file.
-   * Call this before your application exits to ensure data integrity.
-   *
-   * @returns {Promise<void>} Resolves when the database instance is closed and pending writes are finished.
-   */
-  async close() {
-    // Wait for the current write lock promise chain to complete, if any exists
-    try {
-      // If there's a lock, await it. If not, nothing to wait for.
-      if (this.writeLock) {
-        await this.writeLock;
-      }
-    } catch (err) {
-      // Log error during final write if it occurs, but proceed with closing
-      console.error(
-        "[JSONDatabase] Error during final write operation while closing:",
-        err
-      );
-    } finally {
-      // Clear the cache and the lock reference *after* waiting
-      this.cache = null;
-      this.writeLock = null;
-      this._initPromise = null; // Reset init promise tracking
-      const stats = this.getStats(); // Get stats before resetting
-      console.log(
-        `[JSONDatabase] Closed connection to ${
-          this.filename
-        }. Final Stats: ${JSON.stringify(stats)}`
-      );
-      // Optionally reset stats, or leave them for inspection after close
-      // this.stats = { reads: 0, writes: 0, cacheHits: 0 };
-    }
-  }
-}
-
-module.exports = JSONDatabase;
+// 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/package.json

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