snowbase 5.0.0 → 6.0.0

package/src/SnowbaseAsync.js

@@ -0,0 +1,402 @@
+import { stat, mkdir, readdir, unlink, copyFile } from "node:fs/promises";
+import { encrypt, decrypt } from "./helpers/crypto.js";
+import { parsePath, log, getTargetFromData } from "./helpers/utilsAsync.js";
+import FileStorageAsync from "./storages/FileStorageAsync.js";
+import { resolve, join } from "path";
+import { EventEmitter } from "events";
+
+/**
+ * Snowbase database in JSON, with encription, logging and backup
+ * @class SnowbaseAsync
+ * @extends EventEmitter
+ *
+ * @example
+ * import Snowbase from "snowbase/async";
+ *
+ * const db = new Snowbase({
+ *  baseDir: "./database"// Default is './snowbase'
+ *  encryption: true,
+ *  secret: "password123",
+ *  logging: true,
+ *  backup: true
+ * });
+ *
+ * db.on("ready", () => {
+ *   console.log("Database is ready");
+ * });
+ *
+ * db.on("error", (err) => {
+ *   console.error(err);
+ * });
+ * await db.set("user/name", "Pedro");
+ * console.log(await db.get("user/name"))// Pedro
+ */
+export default class SnowbaseAsync extends EventEmitter {
+  /**
+   * @param {Object} [args]
+   * @param {string} [args.baseDir='./snowbase'] - The base directory for the database.
+   * @param {boolean} [args.encryption=false] - Enable encryption
+   * @param {string} [args.secret] - Encryption secret
+   * @param {boolean} [args.logging=false] - Enable logging
+   * @param {boolean} [args.backup=false] - Enable backup
+   */
+  constructor(args = {}) {
+    super();
+    this.baseDir = args.baseDir ? resolve(args.baseDir) : resolve("./snowbase");
+    if (args.encryption === true) {
+      if (!args.secret)
+        this._error(
+          "[INVALID_SECRET] Encryption secret is required when encryption is enabled",
+        );
+      this.secret = args.secret;
+      this.encryption = true;
+    } else {
+      this.encryption = false;
+    }
+    if (args.logging == true) {
+      this.logsDir = join(this.baseDir, "logs");
+      this.logging = true;
+    } else this.logging = false;
+
+    if (args.backup == true) {
+      this.backupDir = join(this.baseDir, "backups");
+      this.backup = true;
+    } else this.backup = false;
+
+    this.path = join(this.baseDir, "snowbase.json"); //Default path for the database file
+    if (this.logsDir) this.logsPath = join(this.logsDir, "snowbase.log");
+
+    this.storage = new FileStorageAsync({
+      baseDir: this.baseDir,
+      encryption: this.encryption,
+      secret: this.secret,
+      backup: this.backup,
+      logging: this.logging,
+      error: this._error.bind(this),
+      emit: this.emit.bind(this),
+      log: this._log.bind(this),
+    });
+  }
+
+  /**
+   * @param {any} data
+   * @param {string} [secret]
+   * @returns {Promise<string>}
+   */
+  async _encrypt(data, secret) {
+    return encrypt(data, secret ? secret : this.secret || "");
+  }
+
+  /**
+   * @param {string} raw
+   * @param {string} [secret]
+   * @returns {Promise<any>}
+   */
+  async _decrypt(raw, secret) {
+    return decrypt(raw, secret ? secret : this.secret || "");
+  }
+
+  /**
+   * @param {any} err
+   * @returns {Promise<never>}
+   */
+  async _error(err) {
+    const error = new Error(String(err));
+    if (this.listenerCount("error") > 0) this.emit("error", error);
+    throw error;
+  }
+
+  /**
+   * @param {string|Function|undefined} path - Path to parse
+   * @returns {Promise<string[]|any>} - Path parts or full data if path is undefined or function
+   */
+  async _parsePath(path) {
+    return await parsePath(path, this._error.bind(this));
+  }
+  /**
+   * @param {string|undefined|Function} path - Path to parse
+   * @returns {Promise<any>} - Target value
+   */
+  async _getTarget(path) {
+    const parts = await this._parsePath(path);
+    let current = await this.storage.readAsync();
+    for (const part of parts) {
+      if (
+        current == null ||
+        typeof current !== "object" ||
+        !Object.hasOwn(current, part)
+      ) {
+        return undefined;
+      }
+      current = current[part];
+    }
+    return current;
+  }
+
+  /**
+   * @param {Object} data - Data to get target from
+   * @param {string} path - Path to get target from
+   * @returns {Promise<*>} Target value
+   */
+  async _getTargetFromData(data, path) {
+    return await getTargetFromData(data, path, this._error.bind(this));
+  }
+
+  /**
+   * @param {string} operation - Operation to log
+   * @param {Object} [details] - Details of the operation
+   * @returns {Promise<string>}
+   */
+  async _log(operation, details) {
+    return await log(
+      operation,
+      details,
+      this.logsPath || "",
+      this.emit.bind(this),
+      this.logging,
+    );
+  }
+  /**
+   * @param {string} [path]
+   * @returns {Promise<any>}
+   * @example
+   * await db.get("user/name"); // returns "Pedro"
+   *
+   * await db.get(); // returns the entire database
+   */
+  async get(path) {
+    const data = await this.storage.readAsync();
+    if (path === undefined) {
+      this.emit("get", { path: undefined, data });
+      return data;
+    }
+    const value = await this._getTargetFromData(data, path);
+    this.emit("get", { path, value });
+    return value;
+  }
+
+  /**
+   * @param {string} [path]
+   * @returns {Promise<boolean>}
+   *
+   * @example
+   * await db.get("user")// { name: "Pedro" }
+   *
+   * await db.remove("user/name"); // returns true
+   *
+   * await db.remove("user/age"); // returns false
+   */
+  async remove(path) {
+    if (path === undefined)
+      this._error("[INVALID_PATH] Invalid path to remove");
+    const parts = await this._parsePath(path);
+    const data = await this.storage.readAsync();
+    let current = data;
+
+    for (let i = 0; i < parts.length - 1; i++) {
+      const key = parts[i];
+      if (
+        current == null ||
+        typeof current !== "object" ||
+        !Object.hasOwn(current, key)
+      ) {
+        await this._log("remove", {
+          path,
+          value: undefined,
+          removed: false,
+        });
+        return false; //returns false if the path does not exist
+      }
+      current = current[key];
+    }
+    const lastKey = parts[parts.length - 1];
+    if (!Object.hasOwn(current, lastKey)) {
+      this._log("remove", { path, value: undefined, removed: false });
+      return false;
+    }
+    this._log("remove", { path, value: current[lastKey], removed: true });
+    delete current[lastKey];
+    await this.storage.writeAsync(data);
+    return true;
+  }
+
+  /**
+   * Clears the entire database
+   * @returns {Promise<boolean>} Returns `true` if the database was cleared
+   *
+   * @example
+   * await db.clear(); // returns true
+   */
+  async clear() {
+    const data = await this.storage.readAsync();
+    await this.storage.writeAsync({});
+    await this._log("clear", { value: data });
+    return true;
+  }
+
+  /**
+   * @param {string} path
+   * @param {any} value
+   * @returns {Promise<void>}
+   * 
+   * @example
+   * await db.set("user/name", "Pedro"); // set the value of user/name to "Pedro"
+   */
+  async set(path, value) {
+    if (!path) this._error("[MISSING_KEY] Missing a key to set");
+    if (value === undefined)
+      this._error("[MISSING_VALUE] Missing value to set");
+    const parts = await this._parsePath(path);
+    const data = await this.storage.readAsync();
+    let current = data;
+    for (let i = 0; i < parts.length - 1; i++) {
+      const key = parts[i];
+      if (current[key] == null || typeof current[key] !== "object") {
+        current[key] = {};
+      }
+      current = current[key];
+    }
+    current[parts[parts.length - 1]] = value;
+    await this.storage.writeAsync(data);
+    this._log("set", { path, key: parts[parts.length - 1], value });
+  }
+
+  /**
+   * @param {string} path
+   * @param {any} value
+   * @returns {Promise<void>}
+   * 
+   * @example
+   * await db.set("user/name", "Pedro"); // set the value of user/name to "Pedro"
+   */
+  async save(path, value) {
+    await this.set(path, value);
+  }
+
+  /**
+   * Return all values from a specified path with a filter.
+   *
+   * If dont provide path, it will search in the entire database.
+   * It only search in the first level of the path (if you provide path='/users', it will only search in the users object, not in the nested objects).
+   *
+   * @param {string|((value: { key: string; value: any; }, index: number, array: { key: string; value: any; }[]) => any)} [path] - Path to get all values from or filter function if path is omitted
+   * @param {((value: { key: string; value: any; }, index: number, array: { key: string; value: any; }[]) => any)} [filter] - Filter to apply to the values
+   * @returns {Promise<{ key: string; value: any; }[]>} Array of key-value pairs
+   *
+   * @example
+   * await db.get("users")// { pedro: {name: "Pedro"}, laura: {name: "Laura"}, john: {name: "John"}}
+   * await db.get("animals")// {dog: {name: "Duke"}, cat: {name: "Princess"}}
+   *
+   * await db.all("users", (x) => x.key.includes("r")) // returns all values with key that includes "r" ( [ { key: "pedro", value: { ... } }, { key: "laura", value: { ... } } ] )
+   * await db.all((x) => x.key.includes("ani")) // returns all values with key that includes "ani" ( [ { key: "animals", value: { ... } } ] )
+   */
+  async all(path, filter) {
+    if (typeof path === "function") {
+      filter = path;
+      path = undefined;
+    }
+
+    if (filter !== undefined && typeof filter !== "function") {
+      this._error("[INVALID_FILTER] Filter must be a function");
+    }
+
+    let target =
+      path !== undefined
+        ? await this._getTarget(path)
+        : await this.storage.readAsync();
+    if (target == null || typeof target !== "object") return [];
+
+    const formatted = Object.entries(target).map(([key, value]) => ({
+      key,
+      value,
+    }));
+    return filter ? formatted.filter(filter) : formatted;
+  }
+
+  /**
+   * Checks if a path exists
+   * @param {string} path - Path to check
+   * @returns {Promise<boolean>} Returns `true` if the path exists, `false` otherwise
+   *
+   * @example
+   * await db.get("user")// { name: "Pedro" }
+   *
+   * await db.has("user/name"); // true
+   *
+   * await db.has("user/age"); // false
+   */
+  async has(path) {
+    if (!path) this._error("[INVALID_PATH] Invalid path to check");
+    return (await this._getTarget(path)) !== undefined;
+  }
+
+  /**
+   * Return the number of values at a specified path
+   *
+   * If dont provide path, it will search in the entire database.
+   * It only search in the first level of the path (if you provide path='/users', it will only search in the users object, not in the nested objects).
+   *
+   * @param {string|((value: { key: string; value: any; }, index: number, array: { key: string; value: any; }[]) => any)} [path] - Path to count values from or filter function if path is omitted
+   * @param {(value: { key: string; value: any; }, index: number, array: { key: string; value: any; }[]) => any} [filter] - Filter to apply to the values
+   * @returns {Promise<number>} Number of values at the specified path
+   *
+   * @example
+   * await db.get("users")// { pedro: {name: "Pedro"}, laura: {name: "Laura"}, john: {name: "John"}}
+   *
+   * await db.count("users"); // 3
+   *
+   * await db.count("users", (x) => x.key.includes("r")); // 2
+   */
+  async count(path, filter) {
+    if (path === undefined && filter === undefined)
+      return (await this.all()).length;
+    if (typeof path === "function") {
+      filter = path;
+      path = undefined;
+    }
+    //how many entries are in the database, with an optional filter function to count only specific entries
+    return (await this.all(path, filter)).length;
+  }
+
+  /**
+   * Return the first value that satisfies the predicate function
+   *
+   * If dont provide path, it will search in the entire database.
+   * It only search in the first level of the path (if you provide path='/users', it will only search in the users object, not in the nested objects).
+   *
+   * @param {string|((value: { key: string; value: any; }, index: number, array: { key: string; value: any; }[]) => any)} [path] - Path to find value in or predicate function if path is omitted
+   * @param {(value: { key: string; value: any; }, index: number, array: { key: string; value: any; }[]) => any} [predicate] - Predicate function to apply to the values
+   * @returns {Promise<{ key: string; value: any; }|null>} Value at the specified path
+   *
+   * @example
+   * await db.get("users")// { laura: {name: "Laura"}, john: {name: "John"}, pedro: {name: "Pedro"} }
+   *
+   * await db.find("users", (x) => x.key.includes("r")); // { key: "laura", value: { ... } }
+   *
+   * await db.find((x) => x.key.includes("u")); // { key: "user", value: { ... } }
+   *
+   * await db.find((x) => x.key.includes("z")) // null
+   */
+  async find(path, predicate) {
+    if (path === undefined && predicate === undefined) {
+      return null;
+    }
+    if (typeof path === "function") {
+      predicate = path;
+      path = undefined;
+    }
+    if (typeof predicate !== "function")
+      this._error("[INVALID_PREDICATE] Predicate must be a function");
+    const data =
+      path !== undefined
+        ? await this._getTarget(path)
+        : await this.storage.readAsync();
+    if (data === undefined || typeof data !== "object") return null;
+    const entries = Object.entries(data).map(([key, value]) => ({
+      key,
+      value,
+    }));
+
+    return (predicate && entries.find(predicate)) || null;
+  }
+}

package/src/helpers/crypto.js

@@ -0,0 +1,69 @@
+import {
+  randomBytes,
+  createCipheriv,
+  createDecipheriv,
+  scryptSync,
+} from "crypto";
+import { stableStringify } from "./utils.js";
+
+/**
+ * @param {string} password
+ * @param {Buffer} salt
+ * @returns {Buffer}
+ */
+export function getKey(password, salt) {
+  return scryptSync(password, salt, 32);
+}
+
+/**
+ * @param {any} data
+ * @param {string} secret
+ * @returns {string}
+ */
+export function encrypt(data, secret) {
+  const iv = randomBytes(12);
+  const salt = randomBytes(16);
+  const key = getKey(secret, salt);
+  const cipher = createCipheriv("aes-256-gcm", key, iv);
+
+  const encrypted = Buffer.concat([
+    cipher.update(stableStringify(data), "utf8"),
+    cipher.final(),
+  ]);
+
+  const tag = cipher.getAuthTag();
+
+  return JSON.stringify({
+    salt: salt.toString("base64"),
+    iv: iv.toString("base64"),
+    tag: tag.toString("base64"),
+    data: encrypted.toString("base64"),
+  });
+}
+
+/**
+ * @param {string} raw
+ * @param {string} secret
+ * @returns {any}
+ */
+export function decrypt(raw, secret) {
+  const payload = JSON.parse(raw);
+
+  const salt = Buffer.from(payload.salt, "base64");
+  const key = getKey(secret, salt);
+
+  const decipher = createDecipheriv(
+    "aes-256-gcm",
+    key,
+    Buffer.from(payload.iv, "base64"),
+  );
+
+  decipher.setAuthTag(Buffer.from(payload.tag, "base64"));
+
+  const decrypted = Buffer.concat([
+    decipher.update(Buffer.from(payload.data, "base64")),
+    decipher.final(),
+  ]);
+
+  return JSON.parse(decrypted.toString("utf8"));
+}

package/src/helpers/utils.js

@@ -0,0 +1,234 @@
+import { decrypt, encrypt } from "./crypto.js";
+import { createHash } from "crypto";
+import { readFileSync, writeFileSync, appendFileSync, copyFileSync } from "fs";
+import { join } from "path";
+
+/**
+ * @param {string} path
+ * @returns {string}
+ */
+export function hash(path) {
+  const fileBuffer = readFileSync(path);
+  return createHash("sha256").update(fileBuffer).digest("hex");
+}
+
+/**
+ * Converts a value to a stable JSON string
+ * @param {any} value - Value to convert
+ * @returns {string} - Stable JSON string
+ */
+export function stableStringify(value) {
+  if (value === null || typeof value !== "object") {
+    return JSON.stringify(value);
+  }
+
+  if (Array.isArray(value)) {
+    return `[${value.map((v) => stableStringify(v)).join(",")}]`;
+  }
+
+  const keys = Object.keys(value).sort();
+
+  return `{${keys
+    .map((k) => `${JSON.stringify(k)}:${stableStringify(value[k])}`)
+    .join(",")}}`;
+}
+/**
+ * Normalizes a chunk of data
+ * @param {string|Object} chunk - Chunk to normalize
+ * @returns {{raw: Object, stable: string}} - Normalized chunk
+ */
+export function normalize(chunk) {
+  const obj = typeof chunk === "string" ? JSON.parse(chunk) : chunk;
+
+  return {
+    raw: obj,
+    stable: stableStringify(obj),
+  };
+}
+/**
+ * Splits a path like "user/name/first" into ["user", "name", "first"] for nested access
+ * @param {string|undefined|Function} path - Path to parse
+ * @param {function} error - Error callback
+ * @returns {string[]} - Array of path parts
+ */
+export function parsePath(path, error) {
+  if (path == null || path === "") {
+    error("[INVALID_PATH] Invalid path");
+    return [];
+  }
+  if (typeof path !== "string") {
+    error("[INVALID_PATH] Path must be a string");
+    return [];
+  }
+  const parts = path.split("/").filter(Boolean);
+  const forbidden = new Set(["prototype", "__proto__", "constructor"]); //protecting against prototype pollution
+  if (parts.some((part) => forbidden.has(part)))
+    error("[FORBIDDEN_KEY] Path contains forbidden key");
+  if (parts.some((part) => part.includes(".")))
+    error("[INVALID_PATH] Path parts cannot contain dots");
+  if (parts.length === 0) error("[INVALID_PATH] Path is empty (just /)");
+  return parts;
+}
+
+/**
+ * Reads the database file
+ * @param {string} path - Database file path
+ * @param {function} error - Error callback
+ * @param {boolean} encryption - Is encryption enabled
+ * @param {string} [secret] - Encryption secret
+ * @returns {Record<string, any>} - Parsed database data
+ */
+export function read(path, error, encryption, secret) {
+  const raw = readFileSync(path, "utf8");
+  let data;
+  try {
+    data = encryption ? decrypt(raw, secret || "") : JSON.parse(raw);
+  } catch {
+    if (
+      !JSON.parse(raw).salt ||
+      !JSON.parse(raw).data ||
+      !JSON.parse(raw).tag ||
+      !JSON.parse(raw).iv
+    )
+      error(
+        "[INVALID_DATA] Database file is not encrypted or invalid JSON (data, salt, tag or iv not found)",
+      );
+    error(
+      "[INVALID_DATA] Database file contains invalid JSON or invalid encryption (perhaps invalid secret)",
+    );
+  }
+
+  if (data == null || typeof data !== "object" || Array.isArray(data)) {
+    error("[INVALID_DATA] Database root must be an object");
+  }
+
+  //validate dangerous keys
+  const forbidden = new Set(["prototype", "__proto__", "constructor"]);
+  /** @param {Record<string, any>} obj */
+  const hasForbiddenKey = (obj) => {
+    for (const key of Object.keys(obj)) {
+      if (forbidden.has(key)) {
+        error("[FORBIDDEN_KEY] Database contains forbidden key: " + key);
+      }
+      if (typeof obj[key] === "object" && obj[key] !== null) {
+        hasForbiddenKey(obj[key]);
+      }
+    }
+  };
+
+  hasForbiddenKey(data);
+  return data;
+}
+
+/**
+ * Logs an operation
+ * @param {string} operation - Operation to log
+ * @param {Record<string, any>|undefined} details - Details of the operation
+ * @param {string|undefined} logsPath - Path to log file
+ * @param {function} emit - Emit event
+ * @param {boolean} logging - Enable logging
+ * @returns {string} - Timestamp
+ */
+export function log(operation, details, logsPath, emit, logging) {
+  let timestamp = new Date().toISOString();
+  if (!logging) {
+    emit(operation, details ? details : undefined, timestamp);
+    return timestamp;
+  }
+  if (!logsPath) {
+    emit(operation, details ? details : undefined, timestamp);
+    return timestamp;
+  }
+  if (!details)
+    appendFileSync(logsPath, `[${timestamp}] ${operation}\n`, "utf8");
+  if (operation) {
+    switch (operation) {
+      case "get":
+        appendFileSync(
+          logsPath,
+          `[${timestamp}] ${operation} - Path: ${details?.path || "/"}\n`,
+          "utf8",
+        );
+        break;
+      case "remove":
+        appendFileSync(
+          logsPath,
+          `[${timestamp}] ${operation} - Path: ${details?.path || "/"}\n`,
+          "utf8",
+        );
+        break;
+      case "set":
+        appendFileSync(
+          logsPath,
+          `[${timestamp}] ${operation} - Path: ${details?.path || "/"}\n`,
+          "utf8",
+        );
+        break;
+      case "clear":
+        appendFileSync(
+          logsPath,
+          `[${timestamp}] ${operation} - Cleared all data\n`,
+          "utf8",
+        );
+        break;
+    }
+  }
+  emit(operation, details ? details : undefined, timestamp);
+  return timestamp;
+}
+
+/**
+ * Gets a target value from the data by path
+ * @param {Record<string, any>} data - Data to search in
+ * @param {string} path - Path to get target from
+ * @param {function} error - Error callback
+ * @returns {any} - Found value or undefined
+ */
+export function getTargetFromData(data, path, error) {
+  const parts = parsePath(path, error);
+  let current = data;
+
+  for (const part of parts) {
+    if (
+      current == null ||
+      typeof current !== "object" ||
+      !Object.hasOwn(current, part)
+    ) {
+      return undefined;
+    }
+    current = current[part];
+  }
+  return current;
+}
+
+/**
+ * Writes data to the database file
+ * @param {string} path - Database file path
+ * @param {Record<string, any>} data - Data to write
+ * @param {function} error - Error callback
+ * @param {function} emit - Emit event
+ * @param {boolean} encryption - Is encryption enabled
+ * @param {string|undefined} secret - Encryption secret
+ */
+export function write(path, data, error, emit, encryption, secret) {
+  let content = "";
+  try {
+    content = encryption ? encrypt(data, secret || "") : stableStringify(data);
+  } catch {
+    error("[INVALID_DATA] Data must be JSON serializable or encryptable");
+  }
+
+  writeFileSync(path, content, "utf8");
+  emit("_write", data, new Date().toISOString());
+}
+
+export function randomId5() {
+  const chars = "abcdefghijklmnopqrstuvwxyz0123456789";
+  let id = "";
+
+  for (let i = 0; i < 5; i++) {
+    id += chars[Math.floor(Math.random() * chars.length)];
+  }
+
+  return id;
+}