snowbase 5.1.0 → 6.0.0

package/src/helpers/utilsAsync.js

@@ -0,0 +1,229 @@
+import { decrypt, encrypt } from "./crypto.js";
+import { createHash } from "crypto";
+import { readFile, writeFile, appendFile, copyFile } from "node:fs/promises";
+import { join } from "path";
+
+/**
+ * @param {string} path
+ * @returns {Promise<string>}
+ */
+export async function hash(path) {
+  const fileBuffer = await readFile(path);
+  return createHash("sha256").update(fileBuffer).digest("hex");
+}
+
+/**
+ * Converts a value to a stable JSON string
+ * @param {any} value - Value to convert
+ * @returns {Promise<string>} - Stable JSON string
+ */
+export async function stableStringify(value) {
+  if (value === null || typeof value !== "object") {
+    return JSON.stringify(value);
+  }
+
+  if (Array.isArray(value)) {
+    return `[${(await Promise.all(value.map((v) => stableStringify(v)))).join(",")}]`;
+  }
+
+  const keys = Object.keys(value).sort();
+
+  return `{${Promise.all(
+    keys
+      .map((k) => `${JSON.stringify(k)}:${stableStringify(value[k])}`)
+      .join(","),
+  )}}`;
+}
+/**
+ * Normalizes a chunk of data
+ * @param {string|Object} chunk - Chunk to normalize
+ * @returns {Promise<{raw: Object, stable: string}>} - Normalized chunk
+ */
+export async function normalize(chunk) {
+  const obj = typeof chunk === "string" ? JSON.parse(chunk) : chunk;
+
+  return {
+    raw: obj,
+    stable: await 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 {Promise<string[]>} - Array of path parts
+ */
+export async 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 {Promise<Record<string, any>>} - Parsed database data
+ */
+export async function read(path, error, encryption, secret) {
+  const raw = await readFile(path, "utf8");
+  let data;
+  try {
+    data = encryption ? decrypt(raw, secret || "") : JSON.parse(raw);
+  } catch {
+    error(
+      "[INVALID_DATA] Database file contains invalid JSON or invalid encryption",
+    );
+  }
+
+  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 {Promise<string>} - Timestamp
+ */
+export async function log(operation, details, logsPath, emit, logging) {
+  let timestamp = new Date().toISOString();
+  if (!logging) {
+    await emit(operation, details ? details : undefined, timestamp);
+    return timestamp;
+  }
+  if (!logsPath) {
+    await emit(operation, details ? details : undefined, timestamp);
+    return timestamp;
+  }
+  if (!details)
+    await appendFile(logsPath, `[${timestamp}] ${operation}\n`, "utf8");
+  if (operation) {
+    switch (operation) {
+      case "get":
+        await appendFile(
+          logsPath,
+          `[${timestamp}] ${operation} - Path: ${details?.path || "/"}\n`,
+          "utf8",
+        );
+        break;
+      case "remove":
+        await appendFile(
+          logsPath,
+          `[${timestamp}] ${operation} - Path: ${details?.path || "/"}\n`,
+          "utf8",
+        );
+        break;
+      case "set":
+        await appendFile(
+          logsPath,
+          `[${timestamp}] ${operation} - Path: ${details?.path || "/"}\n`,
+          "utf8",
+        );
+        break;
+      case "clear":
+        await appendFile(
+          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 {Promise<any>} - Found value or undefined
+ */
+export async function getTargetFromData(data, path, error) {
+  const parts = await 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 async function write(path, data, error, emit, encryption, secret) {
+  let content = "";
+  try {
+    content = encryption
+      ? encrypt(data, secret || "")
+      : await stableStringify(data);
+  } catch {
+    await error("[INVALID_DATA] Data must be JSON serializable or encryptable");
+  }
+
+  await writeFile(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;
+}

package/src/storages/FileStorage.js

@@ -0,0 +1,170 @@
+import {
+  writeFileSync,
+  existsSync,
+  mkdirSync,
+  copyFileSync,
+  statSync,
+  readdirSync,
+  unlinkSync,
+} from "fs";
+import { read, write, randomId5 } from "../helpers/utils.js";
+import { encrypt, decrypt } from "../helpers/crypto.js";
+import { resolve, join } from "path";
+
+/**
+ * @fileoverview FileStorage is a storage class that stores data in a file.
+ * @class FileStorage
+ */
+export default class FileStorage {
+  /**
+   * @description Creates a new instance of FileStorage.
+   * @param {Object} options - Options for the FileStorage.
+   * @param {string} options.baseDir - The base directory for the database.
+   * @param {boolean} [options.encryption] - Whether to encrypt the data.
+   * @param {string} [options.secret] - The secret key for encryption.
+   * @param {boolean} [options.backup] - Whether to backup the data.
+   * @param {boolean} [options.logging] - Whether to log the data.
+   * @param {function(any): never} options.error - Function to handle errors.
+   * @param {function(...any): void} options.emit - Function to emit events.
+   * @param {function(string, any): void} options.log - Function to log the data.
+   * @memberof FileStorage
+   * @constructor
+   */
+  constructor({
+    baseDir,
+    encryption = false,
+    secret = "",
+    backup = false,
+    logging = false,
+    error,
+    emit,
+    log,
+  }) {
+    this.baseDir = resolve(baseDir) || resolve("./snowbase");
+    this.encryption = encryption;
+    this.secret = secret;
+    this.backup = backup;
+    this.logging = logging;
+    this._error = error;
+    this.emit = emit;
+    this._log = log;
+    this.path = join(this.baseDir, "snowbase.json");
+
+    if (this.logging) {
+      this.logsDir = join(this.baseDir, "logs");
+    }
+    if (this.backup) {
+      this.backupDir = join(this.baseDir, "backups");
+    }
+    this.path = join(this.baseDir, "snowbase.json");
+    if (this.logsDir) this.logsPath = join(this.logsDir, "snowbase.log");
+
+    //Creating directories if they don't exist
+    mkdirSync(this.baseDir, { recursive: true });
+    if (this.backup && this.backupDir)
+      mkdirSync(this.backupDir, { recursive: true }); //only if the user wants backup
+    if (this.logging && this.logsDir)
+      mkdirSync(this.logsDir, { recursive: true }); //only if the user wants logging
+
+    //Creating the database file if it doesn't exist
+    if (!existsSync(this.path)) {
+      const initialData = this.encryption
+        ? encrypt({}, this.secret)
+        : JSON.stringify({});
+      writeFileSync(this.path, initialData, "utf8");
+      /** @type {Record<string, any>|null} */
+      this._cache = {};
+      /** @type {import("node:fs").Stats} */
+      const stat = statSync(this.path);
+      /** @type {number} Last known modification time of the database file */
+      this._cacheMtime = stat.mtimeMs;
+      /** @type {number} Last known size of the database file */
+      this._cacheSize = stat.size;
+    } else {
+      /** @type {Record<string, any>|null} */
+      this._cache = null;
+      /** @type {number} */
+      this._cacheMtime = 0;
+    }
+    if (this.logging && this.logsPath && !existsSync(this.logsPath))
+      writeFileSync(this.logsPath, "", "utf8");
+  }
+  /**
+   * @returns {Record<string, any>} The data from the database
+   */
+  read() {
+    // Validate cache freshness by comparing file mtime
+    const stat = statSync(this.path);
+    const currentMtime = stat.mtimeMs;
+    if (
+      this._cache !== null &&
+      currentMtime === this._cacheMtime &&
+      stat.size === this._cacheSize
+    ) {
+      return this._cache;
+    }
+    const data = read(
+      this.path,
+      this._error.bind(this),
+      this.encryption,
+      this.secret || "",
+    );
+    if (data === null || Array.isArray(data) || typeof data !== "object") {
+      this._error("[INVALID_DATABASE] The database root must be an object.");
+    }
+    this._cache = data;
+    this._cacheMtime = currentMtime;
+    this._cacheSize = stat.size;
+    return data;
+  }
+
+  /**
+   * @param {Object} data - Data to write
+   * @returns {void}
+   */
+  write(data) {
+    write(
+      this.path,
+      data,
+      this._error.bind(this),
+      this.emit.bind(this),
+      this.encryption,
+      this.secret,
+    );
+    this.createBackup();
+    this._cache = data;
+    this._cacheMtime = statSync(this.path).mtimeMs;
+  }
+
+  createBackup() {
+    if (!this.backup || !this.backupDir) return false;
+    let maxBackups = 20;
+    const backupDir = this.backupDir || join(this.baseDir, "backups");
+    mkdirSync(backupDir, { recursive: true });
+    //Getting all backup files
+    const files = readdirSync(backupDir)
+      .filter((f) => f.startsWith("backup_"))
+      .map((file) => {
+        const fullPath = join(backupDir, file);
+        const stats = statSync(fullPath);
+
+        return {
+          path: fullPath,
+          time: stats.mtimeMs,
+        };
+      })
+      .sort((a, b) => a.time - b.time);
+
+    if (files.length - maxBackups > 0) {
+      for (let i = 0; i < files.length - maxBackups; i++) {
+        unlinkSync(files[i].path);
+      }
+    }
+    //Creates a new backup
+    const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+    const backupFile = join(backupDir, `backup_${stamp}-${randomId5()}.json`);
+    copyFileSync(this.path, backupFile);
+    this._log("create backup", { backupFile });
+    return backupFile;
+  }
+}

package/src/storages/FileStorageAsync.js

@@ -0,0 +1,167 @@
+import { writeFileSync, existsSync, mkdirSync, statSync } from "fs";
+import { stat, mkdir, readdir, unlink, copyFile } from "node:fs/promises";
+import { read, write, randomId5 } from "../helpers/utilsAsync.js";
+import { encrypt, decrypt } from "../helpers/crypto.js";
+import { resolve, join } from "path";
+
+/**
+ * @fileoverview FileStorage is a storage class that stores data in a file.
+ * @class FileStorage
+ */
+export default class FileStorageAsync {
+  /**
+   * @description Creates a new instance of FileStorage.
+   * @param {Object} options - Options for the FileStorage.
+   * @param {string} options.baseDir - The base directory for the database.
+   * @param {boolean} [options.encryption] - Whether to encrypt the data.
+   * @param {string} [options.secret] - The secret key for encryption.
+   * @param {boolean} [options.backup] - Whether to backup the data.
+   * @param {boolean} [options.logging] - Whether to log the data.
+   * @param {*} options.error - Function to handle errors.
+   * @param {function(...any): void} options.emit - Function to emit events.
+   * @param {function(string, any): void} options.log - Function to log the data.
+   * @memberof FileStorage
+   * @constructor
+   */
+  constructor({
+    baseDir,
+    encryption = false,
+    secret = "",
+    backup = false,
+    logging = false,
+    error,
+    emit,
+    log,
+  }) {
+    this.baseDir = resolve(baseDir) || resolve("./snowbase");
+    this.encryption = encryption;
+    this.secret = secret;
+    this.backup = backup;
+    this.logging = logging;
+    this._error = error;
+    this.emit = emit;
+    this._log = log;
+    this.path = join(this.baseDir, "snowbase.json");
+
+    if (this.logging) {
+      this.logsDir = join(this.baseDir, "logs");
+    }
+    if (this.backup) {
+      this.backupDir = join(this.baseDir, "backups");
+    }
+    this.path = join(this.baseDir, "snowbase.json");
+    if (this.logsDir) this.logsPath = join(this.logsDir, "snowbase.log");
+
+    //Creating directories if they don't exist
+    mkdirSync(this.baseDir, { recursive: true });
+    if (this.backup && this.backupDir)
+      mkdirSync(this.backupDir, { recursive: true }); //only if the user wants backup
+    if (this.logging && this.logsDir)
+      mkdirSync(this.logsDir, { recursive: true }); //only if the user wants logging
+
+    //Creating the database file if it doesn't exist
+    if (!existsSync(this.path)) {
+      const initialData = this.encryption
+        ? encrypt({}, this.secret)
+        : JSON.stringify({});
+      writeFileSync(this.path, initialData, "utf8");
+      /** @type {Record<string, any>|null} */
+      this._cache = {};
+      /** @type {import("node:fs").Stats} */
+      const stat = statSync(this.path);
+      /** @type {number} Last known modification time of the database file */
+      this._cacheMtime = stat.mtimeMs;
+      /** @type {number} Last known size of the database file */
+      this._cacheSize = stat.size;
+    } else {
+      /** @type {Record<string, any>|null} */
+      this._cache = null;
+      /** @type {number} */
+      this._cacheMtime = 0;
+    }
+    if (this.logging && this.logsPath && !existsSync(this.logsPath))
+      writeFileSync(this.logsPath, "", "utf8");
+  }
+  /**
+   * @returns {Promise<Record<string, any>>} The data from the database
+   */
+  async readAsync() {
+    // Validate cache freshness by comparing file mtime
+    const fileStat = await stat(this.path);
+    const currentMtime = fileStat.mtimeMs;
+    if (
+      this._cache !== null &&
+      currentMtime === this._cacheMtime &&
+      fileStat.size === this._cacheSize
+    ) {
+      return this._cache;
+    }
+    const data = await read(
+      this.path,
+      this._error.bind(this),
+      this.encryption,
+      this.secret || "",
+    );
+    if (data === null || Array.isArray(data) || typeof data !== "object") {
+      this._error("[INVALID_DATABASE] The database root must be an object.");
+    }
+    this._cache = data;
+    this._cacheMtime = currentMtime;
+    this._cacheSize = fileStat.size;
+    return data;
+  }
+
+  /**
+   * @param {Object} data - Data to write
+   * @returns {Promise<void>}
+   */
+  async writeAsync(data) {
+    await write(
+      this.path,
+      data,
+      this._error.bind(this),
+      this.emit.bind(this),
+      this.encryption,
+      this.secret,
+    );
+    await this.createBackupAsync();
+    this._cache = data;
+    this._cacheMtime = (await stat(this.path)).mtimeMs;
+  }
+
+  async createBackupAsync() {
+    if (!this.backup || !this.backupDir) return;
+    const maxBackups = 20;
+    const backupDir = this.backupDir || join(this.baseDir, "backups");
+    await mkdir(backupDir, { recursive: true });
+    //Getting all backup files
+    const files = (
+      await Promise.all(
+        (await readdir(backupDir))
+          .filter((f) => f.startsWith("backup_"))
+          .map(async (file) => {
+            const fullPath = join(backupDir, file);
+            const stats = await stat(fullPath);
+
+            return {
+              path: fullPath,
+              time: stats.mtimeMs,
+            };
+          }),
+      )
+    ).sort((a, b) => a.time - b.time);
+
+    if (files.length - maxBackups > 0) {
+      for (let i = 0; i < files.length - maxBackups; i++) {
+        await unlink(files[i].path);
+      }
+    }
+    //Creates a new backup
+    const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+    const backupFile = join(backupDir, `backup_${stamp}-${randomId5()}.json`);
+
+    await copyFile(this.path, backupFile);
+    this._log("create backup", { backupFile });
+    return backupFile;
+  }
+}

package/.upm/store.json

@@ -1 +0,0 @@
-{"version":2,"languages":{"nodejs-npm":{"specfileHash":"5d5decf1c69e3a2b4980b0627502cc86","lockfileHash":"603978d5629b271eba01c863d286f4e7","guessedImports":["node-fetch"],"guessedImportsHash":"56c1dadb55ef9ad867462f97e0673488"}}}

package/index.js

@@ -1,5 +0,0 @@
-/*module.exports*/const data = require('./src/index.js');
-let db = new data.Server({
-  login: 'frozen_test',
-  password: 'PHSBP3012'
-});

package/src/Local.js

@@ -1,45 +0,0 @@
-const {readFileSync, writeFileSync} = require('fs')
-
-module.exports = class LocalDatabase {
-  constructor(path) {
-    if (!path) throw new Error('Invalid path')
-    this.path = path;
-  };
-  get(key) {
-    if (!key) throw new Error('Invalid key to get');
-    let to;
-    const fileToRead = readFileSync(this.path, 'utf8');
-    let data = JSON.parse(fileToRead);
-    return data[key];
-  };
-  remove(key) {
-    if (!key) throw new Error('Invalid key to delete');
-    const fileToRead = readFileSync(this.path, 'utf8');
-    let data = JSON.parse(fileToRead);
-    delete data[key];
-    data = JSON.stringify(data);
-    writeFileSync(this.path, data);
-  };
-
-  save(key, value) {
-    if (!value) throw new Error('Missing Params');
-    const fileToRead = readFileSync(this.path, 'utf8');
-    let data = JSON.parse(fileToRead);
-    data[key] = value;
-    data = JSON.stringify(data);
-    writeFileSync(this.path, data)
-  };
-
-  all(filter) {
-    const fileToRead = readFileSync(this.path, 'utf8');
-    let data = JSON.parse(fileToRead);
-    data = Object.entries(data).map(d => {
-      return {
-        key: d[0],
-        value: d[1]
-      }
-    });
-    if (filter) return data.filter(filter);
-    return data;
-  }
-}