@objectstack/driver-memory 3.0.10 → 3.1.0

package/dist/index.js

@@ -1,8 +1,13 @@
 "use strict";
+var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
 var __export = (target, all) => {
   for (var name in all)
     __defProp(target, name, { get: all[name], enumerable: true });
@@ -15,12 +20,169 @@ var __copyProps = (to, from, except, desc) => {
   }
   return to;
 };
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
+// src/persistence/local-storage-adapter.ts
+var local_storage_adapter_exports = {};
+__export(local_storage_adapter_exports, {
+  LocalStoragePersistenceAdapter: () => LocalStoragePersistenceAdapter
+});
+var _LocalStoragePersistenceAdapter, LocalStoragePersistenceAdapter;
+var init_local_storage_adapter = __esm({
+  "src/persistence/local-storage-adapter.ts"() {
+    "use strict";
+    _LocalStoragePersistenceAdapter = class _LocalStoragePersistenceAdapter {
+      // 4.5MB warning threshold
+      constructor(options) {
+        this.storageKey = options?.key || "objectstack:memory-db";
+      }
+      /**
+       * Load persisted data from localStorage.
+       * Returns null if no data exists.
+       */
+      async load() {
+        try {
+          const raw = localStorage.getItem(this.storageKey);
+          if (!raw) return null;
+          return JSON.parse(raw);
+        } catch {
+          return null;
+        }
+      }
+      /**
+       * Save data to localStorage.
+       * Warns if data size approaches the ~5MB localStorage limit.
+       */
+      async save(db) {
+        const json = JSON.stringify(db);
+        if (json.length > _LocalStoragePersistenceAdapter.SIZE_WARNING_BYTES) {
+          console.warn(
+            `[ObjectStack] localStorage persistence data size (${(json.length / 1024 / 1024).toFixed(2)}MB) is approaching the ~5MB limit. Consider using a different persistence strategy.`
+          );
+        }
+        try {
+          localStorage.setItem(this.storageKey, json);
+        } catch (e) {
+          console.error("[ObjectStack] Failed to persist data to localStorage:", e?.message || e);
+        }
+      }
+      /**
+       * Flush is a no-op for localStorage (writes are synchronous).
+       */
+      async flush() {
+      }
+    };
+    _LocalStoragePersistenceAdapter.SIZE_WARNING_BYTES = 4.5 * 1024 * 1024;
+    LocalStoragePersistenceAdapter = _LocalStoragePersistenceAdapter;
+  }
+});
+
+// src/persistence/file-adapter.ts
+var file_adapter_exports = {};
+__export(file_adapter_exports, {
+  FileSystemPersistenceAdapter: () => FileSystemPersistenceAdapter
+});
+var fs, path, FileSystemPersistenceAdapter;
+var init_file_adapter = __esm({
+  "src/persistence/file-adapter.ts"() {
+    "use strict";
+    fs = __toESM(require("fs"));
+    path = __toESM(require("path"));
+    FileSystemPersistenceAdapter = class {
+      constructor(options) {
+        this.dirty = false;
+        this.timer = null;
+        this.currentDb = null;
+        this.filePath = options?.path || path.join(".objectstack", "data", "memory-driver.json");
+        this.autoSaveInterval = options?.autoSaveInterval ?? 2e3;
+      }
+      /**
+       * Load persisted data from disk.
+       * Returns null if no file exists.
+       */
+      async load() {
+        try {
+          if (!fs.existsSync(this.filePath)) {
+            return null;
+          }
+          const raw = fs.readFileSync(this.filePath, "utf-8");
+          const data = JSON.parse(raw);
+          return data;
+        } catch {
+          return null;
+        }
+      }
+      /**
+       * Save data to disk using atomic write (temp file + rename).
+       */
+      async save(db) {
+        this.currentDb = db;
+        this.dirty = true;
+      }
+      /**
+       * Flush pending writes to disk immediately.
+       */
+      async flush() {
+        if (!this.dirty || !this.currentDb) return;
+        await this.writeToDisk(this.currentDb);
+        this.dirty = false;
+      }
+      /**
+       * Start the auto-save timer.
+       */
+      startAutoSave() {
+        if (this.timer) return;
+        this.timer = setInterval(async () => {
+          if (this.dirty && this.currentDb) {
+            await this.writeToDisk(this.currentDb);
+            this.dirty = false;
+          }
+        }, this.autoSaveInterval);
+        if (this.timer) {
+          this.timer.unref();
+        }
+      }
+      /**
+       * Stop the auto-save timer and flush pending writes.
+       */
+      async stopAutoSave() {
+        if (this.timer) {
+          clearInterval(this.timer);
+          this.timer = null;
+        }
+        await this.flush();
+      }
+      /**
+       * Atomic write: write to temp file, then rename.
+       */
+      async writeToDisk(db) {
+        const dir = path.dirname(this.filePath);
+        if (!fs.existsSync(dir)) {
+          fs.mkdirSync(dir, { recursive: true });
+        }
+        const tmpPath = this.filePath + ".tmp";
+        const json = JSON.stringify(db, null, 2);
+        fs.writeFileSync(tmpPath, json, "utf-8");
+        fs.renameSync(tmpPath, this.filePath);
+      }
+    };
+  }
+});
+
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  FileSystemPersistenceAdapter: () => FileSystemPersistenceAdapter,
   InMemoryDriver: () => InMemoryDriver,
+  LocalStoragePersistenceAdapter: () => LocalStoragePersistenceAdapter,
   MemoryAnalyticsService: () => MemoryAnalyticsService,
   default: () => index_default
 });
@@ -31,22 +193,23 @@ var import_core = require("@objectstack/core");
 var import_mingo = require("mingo");
 
 // src/memory-matcher.ts
-function getValueByPath(obj, path) {
-  if (path === "_id" && obj._id === void 0 && obj.id !== void 0) {
+function getValueByPath(obj, path2) {
+  if (path2 === "_id" && obj._id === void 0 && obj.id !== void 0) {
     return obj.id;
   }
-  if (!path.includes(".")) return obj[path];
-  return path.split(".").reduce((o, i) => o ? o[i] : void 0, obj);
+  if (!path2.includes(".")) return obj[path2];
+  return path2.split(".").reduce((o, i) => o ? o[i] : void 0, obj);
 }
 
 // src/memory-driver.ts
-var InMemoryDriver = class {
+var _InMemoryDriver = class _InMemoryDriver {
   constructor(config) {
     this.name = "com.objectstack.driver.memory";
     this.type = "driver";
     this.version = "1.0.0";
     this.idCounters = /* @__PURE__ */ new Map();
     this.transactions = /* @__PURE__ */ new Map();
+    this.persistenceAdapter = null;
     this.supports = {
       // Transaction & Connection Management
       transactions: true,
@@ -100,6 +263,31 @@ var InMemoryDriver = class {
   // Lifecycle
   // ===================================
   async connect() {
+    await this.initPersistence();
+    if (this.persistenceAdapter) {
+      const persisted = await this.persistenceAdapter.load();
+      if (persisted) {
+        for (const [objectName, records] of Object.entries(persisted)) {
+          this.db[objectName] = records;
+          for (const record of records) {
+            if (record.id && typeof record.id === "string") {
+              const parts = record.id.split("-");
+              const lastPart = parts[parts.length - 1];
+              const counter = parseInt(lastPart, 10);
+              if (!isNaN(counter)) {
+                const current = this.idCounters.get(objectName) || 0;
+                if (counter > current) {
+                  this.idCounters.set(objectName, counter);
+                }
+              }
+            }
+          }
+        }
+        this.logger.info("InMemory Database restored from persistence", {
+          tables: Object.keys(persisted).length
+        });
+      }
+    }
     if (this.config.initialData) {
       for (const [objectName, records] of Object.entries(this.config.initialData)) {
         const table = this.getTable(objectName);
@@ -114,8 +302,17 @@ var InMemoryDriver = class {
     } else {
       this.logger.info("InMemory Database Connected (Virtual)");
     }
+    if (this.persistenceAdapter?.startAutoSave) {
+      this.persistenceAdapter.startAutoSave();
+    }
   }
   async disconnect() {
+    if (this.persistenceAdapter) {
+      if (this.persistenceAdapter.stopAutoSave) {
+        await this.persistenceAdapter.stopAutoSave();
+      }
+      await this.persistenceAdapter.flush();
+    }
     const tableCount = Object.keys(this.db).length;
     const recordCount = Object.values(this.db).reduce((sum, table) => sum + table.length, 0);
     this.db = {};
@@ -195,6 +392,7 @@ var InMemoryDriver = class {
       updated_at: data.updated_at || (/* @__PURE__ */ new Date()).toISOString()
     };
     table.push(newRecord);
+    this.markDirty();
     this.logger.debug("Record created", { object, id: newRecord.id, tableSize: table.length });
     return { ...newRecord };
   }
@@ -219,6 +417,7 @@ var InMemoryDriver = class {
       updated_at: (/* @__PURE__ */ new Date()).toISOString()
     };
     table[index] = updatedRecord;
+    this.markDirty();
     this.logger.debug("Record updated", { object, id });
     return { ...updatedRecord };
   }
@@ -251,6 +450,7 @@ var InMemoryDriver = class {
       return false;
     }
     table.splice(index, 1);
+    this.markDirty();
     this.logger.debug("Record deleted", { object, id, tableSize: table.length });
     return true;
   }
@@ -299,6 +499,7 @@ var InMemoryDriver = class {
         table[index] = updated;
       }
     }
+    if (count > 0) this.markDirty();
     this.logger.debug("UpdateMany completed", { object, count });
     return { count };
   }
@@ -320,6 +521,7 @@ var InMemoryDriver = class {
       this.db[object] = [];
     }
     const count = initialLength - this.db[object].length;
+    if (count > 0) this.markDirty();
     this.logger.debug("DeleteMany completed", { object, count });
     return { count };
   }
@@ -367,6 +569,7 @@ var InMemoryDriver = class {
     const tx = this.transactions.get(txId);
     this.db = tx.snapshot;
     this.transactions.delete(txId);
+    this.markDirty();
     this.logger.debug("Transaction rolled back", { txId });
   }
   // ===================================
@@ -378,6 +581,7 @@ var InMemoryDriver = class {
   async clear() {
     this.db = {};
     this.idCounters.clear();
+    this.markDirty();
     this.logger.debug("All data cleared");
   }
   /**
@@ -614,8 +818,8 @@ var InMemoryDriver = class {
         return null;
     }
   }
-  setValueByPath(obj, path, value) {
-    const parts = path.split(".");
+  setValueByPath(obj, path2, value) {
+    const parts = path2.split(".");
     let current = obj;
     for (let i = 0; i < parts.length - 1; i++) {
       const part = parts[i];
@@ -702,7 +906,131 @@ var InMemoryDriver = class {
     const timestamp = Date.now();
     return `${key}-${timestamp}-${counter}`;
   }
+  // ===================================
+  // Persistence
+  // ===================================
+  /**
+   * Mark the database as dirty, triggering persistence save.
+   */
+  markDirty() {
+    if (this.persistenceAdapter) {
+      this.persistenceAdapter.save(this.db);
+    }
+  }
+  /**
+   * Flush pending persistence writes to ensure data is safely stored.
+   */
+  async flush() {
+    if (this.persistenceAdapter) {
+      await this.persistenceAdapter.flush();
+    }
+  }
+  /**
+   * Detect whether the current runtime is a browser environment.
+   */
+  isBrowserEnvironment() {
+    return typeof globalThis.localStorage !== "undefined";
+  }
+  /**
+   * Detect whether the current runtime is a serverless/edge environment.
+   *
+   * Checks well-known environment variables set by serverless platforms:
+   * - `VERCEL` / `VERCEL_ENV` — Vercel Functions / Edge
+   * - `AWS_LAMBDA_FUNCTION_NAME` — AWS Lambda
+   * - `NETLIFY` — Netlify Functions
+   * - `FUNCTIONS_WORKER_RUNTIME` — Azure Functions
+   * - `K_SERVICE` — Google Cloud Run / Cloud Functions
+   * - `FUNCTION_TARGET` — Google Cloud Functions (Node.js)
+   * - `DENO_DEPLOYMENT_ID` — Deno Deploy
+   *
+   * Returns `false` when `process` or `process.env` is unavailable
+   * (e.g. browser or edge runtimes without a Node.js process object).
+   */
+  isServerlessEnvironment() {
+    if (typeof globalThis.process === "undefined" || !globalThis.process.env) {
+      return false;
+    }
+    const env = globalThis.process.env;
+    return !!(env.VERCEL || env.VERCEL_ENV || env.AWS_LAMBDA_FUNCTION_NAME || env.NETLIFY || env.FUNCTIONS_WORKER_RUNTIME || env.K_SERVICE || env.FUNCTION_TARGET || env.DENO_DEPLOYMENT_ID);
+  }
+  /**
+   * Initialize the persistence adapter based on configuration.
+   * Defaults to 'auto' when persistence is not specified.
+   * Use `persistence: false` to explicitly disable persistence.
+   *
+   * In serverless environments (Vercel, AWS Lambda, etc.), auto mode disables
+   * file-system persistence and emits a warning. Use `persistence: false` or
+   * supply a custom adapter for serverless-safe operation.
+   */
+  async initPersistence() {
+    const persistence = this.config.persistence === void 0 ? "auto" : this.config.persistence;
+    if (persistence === false) return;
+    if (typeof persistence === "string") {
+      if (persistence === "auto") {
+        if (this.isBrowserEnvironment()) {
+          const { LocalStoragePersistenceAdapter: LocalStoragePersistenceAdapter2 } = await Promise.resolve().then(() => (init_local_storage_adapter(), local_storage_adapter_exports));
+          this.persistenceAdapter = new LocalStoragePersistenceAdapter2();
+          this.logger.debug("Auto-detected browser environment, using localStorage persistence");
+        } else if (this.isServerlessEnvironment()) {
+          this.logger.warn(_InMemoryDriver.SERVERLESS_PERSISTENCE_WARNING);
+        } else {
+          const { FileSystemPersistenceAdapter: FileSystemPersistenceAdapter2 } = await Promise.resolve().then(() => (init_file_adapter(), file_adapter_exports));
+          this.persistenceAdapter = new FileSystemPersistenceAdapter2();
+          this.logger.debug("Auto-detected Node.js environment, using file persistence");
+        }
+      } else if (persistence === "file") {
+        const { FileSystemPersistenceAdapter: FileSystemPersistenceAdapter2 } = await Promise.resolve().then(() => (init_file_adapter(), file_adapter_exports));
+        this.persistenceAdapter = new FileSystemPersistenceAdapter2();
+      } else if (persistence === "local") {
+        const { LocalStoragePersistenceAdapter: LocalStoragePersistenceAdapter2 } = await Promise.resolve().then(() => (init_local_storage_adapter(), local_storage_adapter_exports));
+        this.persistenceAdapter = new LocalStoragePersistenceAdapter2();
+      } else {
+        throw new Error(`Unknown persistence type: "${persistence}". Use 'file', 'local', or 'auto'.`);
+      }
+    } else if ("adapter" in persistence && persistence.adapter) {
+      this.persistenceAdapter = persistence.adapter;
+    } else if ("type" in persistence) {
+      if (persistence.type === "auto") {
+        if (this.isBrowserEnvironment()) {
+          const { LocalStoragePersistenceAdapter: LocalStoragePersistenceAdapter2 } = await Promise.resolve().then(() => (init_local_storage_adapter(), local_storage_adapter_exports));
+          this.persistenceAdapter = new LocalStoragePersistenceAdapter2({
+            key: persistence.key
+          });
+          this.logger.debug("Auto-detected browser environment, using localStorage persistence");
+        } else if (this.isServerlessEnvironment()) {
+          this.logger.warn(_InMemoryDriver.SERVERLESS_PERSISTENCE_WARNING);
+        } else {
+          const { FileSystemPersistenceAdapter: FileSystemPersistenceAdapter2 } = await Promise.resolve().then(() => (init_file_adapter(), file_adapter_exports));
+          this.persistenceAdapter = new FileSystemPersistenceAdapter2({
+            path: persistence.path,
+            autoSaveInterval: persistence.autoSaveInterval
+          });
+          this.logger.debug("Auto-detected Node.js environment, using file persistence");
+        }
+      } else if (persistence.type === "file") {
+        const { FileSystemPersistenceAdapter: FileSystemPersistenceAdapter2 } = await Promise.resolve().then(() => (init_file_adapter(), file_adapter_exports));
+        this.persistenceAdapter = new FileSystemPersistenceAdapter2({
+          path: persistence.path,
+          autoSaveInterval: persistence.autoSaveInterval
+        });
+      } else if (persistence.type === "local") {
+        const { LocalStoragePersistenceAdapter: LocalStoragePersistenceAdapter2 } = await Promise.resolve().then(() => (init_local_storage_adapter(), local_storage_adapter_exports));
+        this.persistenceAdapter = new LocalStoragePersistenceAdapter2({
+          key: persistence.key
+        });
+      }
+    }
+    if (this.persistenceAdapter) {
+      this.logger.debug("Persistence adapter initialized");
+    }
+  }
 };
+_InMemoryDriver.SERVERLESS_PERSISTENCE_WARNING = "Serverless environment detected \u2014 file-system persistence is disabled in auto mode. Data will NOT be persisted across function invocations. Set persistence: false to silence this warning, or provide a custom adapter (e.g. Upstash Redis, Vercel KV) via persistence: { adapter: yourAdapter }.";
+var InMemoryDriver = _InMemoryDriver;
+
+// src/index.ts
+init_file_adapter();
+init_local_storage_adapter();
 
 // src/memory-analytics.ts
 var import_core2 = require("@objectstack/core");
@@ -1115,7 +1443,9 @@ var index_default = {
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  FileSystemPersistenceAdapter,
   InMemoryDriver,
+  LocalStoragePersistenceAdapter,
   MemoryAnalyticsService
 });
 //# sourceMappingURL=index.js.map