@objectstack/driver-memory 3.0.10 → 3.1.0

package/src/memory-driver.ts

@@ -6,6 +6,20 @@ import { Logger, createLogger } from '@objectstack/core';
 import { Query, Aggregator } from 'mingo';
 import { getValueByPath } from './memory-matcher.js';
 
+/**
+ * Persistence adapter interface.
+ * Matches the PersistenceAdapterSchema contract from @objectstack/spec.
+ */
+export interface PersistenceAdapterInterface {
+  load(): Promise<Record<string, any[]> | null>;
+  save(db: Record<string, any[]>): Promise<void>;
+  flush(): Promise<void>;
+  /** Optional: Start periodic auto-save (used by FileSystemPersistenceAdapter). */
+  startAutoSave?(): void;
+  /** Optional: Stop auto-save timer and flush pending writes. */
+  stopAutoSave?(): Promise<void>;
+}
+
 /**
  * Configuration options for the InMemory driver.
  * Aligned with @objectstack/spec MemoryConfigSchema.
@@ -17,6 +31,28 @@ export interface InMemoryDriverConfig {
   strictMode?: boolean;
   /** Optional: Logger instance */
   logger?: Logger;
+  /**
+   * Persistence configuration. Defaults to `'auto'`.
+   * - `'auto'` (default) — Auto-detect environment (browser → localStorage, Node.js → file, serverless → disabled)
+   * - `'file'` — File-system persistence with defaults (Node.js only)
+   * - `'local'` — localStorage persistence with defaults (Browser only)
+   * - `{ type: 'file', path?: string, autoSaveInterval?: number }` — File-system with options
+   * - `{ type: 'local', key?: string }` — localStorage with options
+   * - `{ type: 'auto', path?: string, key?: string, autoSaveInterval?: number }` — Auto-detect with options
+   * - `{ adapter: PersistenceAdapterInterface }` — Custom adapter
+   * - `false` — Disable persistence (pure in-memory)
+   *
+   * ⚠️ In serverless environments (Vercel, AWS Lambda, Netlify, etc.),
+   * auto mode disables file persistence to prevent silent data loss.
+   * Use `persistence: false` or supply a custom adapter for serverless deployments.
+   */
+  persistence?: string | false | {
+    type?: 'file' | 'local' | 'auto';
+    path?: string;
+    key?: string;
+    autoSaveInterval?: number;
+    adapter?: PersistenceAdapterInterface;
+  };
 }
 
 /**
@@ -51,6 +87,7 @@ export class InMemoryDriver implements DriverInterface {
   private logger: Logger;
   private idCounters: Map<string, number> = new Map();
   private transactions: Map<string, MemoryTransaction> = new Map();
+  private persistenceAdapter: PersistenceAdapterInterface | null = null;
 
   constructor(config?: InMemoryDriverConfig) {
     this.config = config || {};
@@ -100,6 +137,37 @@ export class InMemoryDriver implements DriverInterface {
   // ===================================
 
   async connect() {
+    // Initialize persistence adapter if configured
+    await this.initPersistence();
+
+    // Load persisted data if available
+    if (this.persistenceAdapter) {
+      const persisted = await this.persistenceAdapter.load();
+      if (persisted) {
+        for (const [objectName, records] of Object.entries(persisted)) {
+          this.db[objectName] = records;
+          // Update ID counters based on persisted data
+          for (const record of records) {
+            if (record.id && typeof record.id === 'string') {
+              // ID format: {objectName}-{timestamp}-{counter}
+              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,
+        });
+      }
+    }
+
     // Load initial data if provided
     if (this.config.initialData) {
       for (const [objectName, records] of Object.entries(this.config.initialData)) {
@@ -115,9 +183,22 @@ export class InMemoryDriver implements DriverInterface {
     } else {
       this.logger.info('InMemory Database Connected (Virtual)');
     }
+
+    // Start auto-save if using file adapter
+    if (this.persistenceAdapter?.startAutoSave) {
+      this.persistenceAdapter.startAutoSave();
+    }
   }
 
   async disconnect() {
+    // Stop auto-save and flush pending writes
+    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);
     
@@ -226,6 +307,7 @@ export class InMemoryDriver implements DriverInterface {
     };
 
     table.push(newRecord);
+    this.markDirty();
     this.logger.debug('Record created', { object, id: newRecord.id, tableSize: table.length });
     return { ...newRecord };
   }
@@ -253,6 +335,7 @@ export class InMemoryDriver implements DriverInterface {
     };
     
     table[index] = updatedRecord;
+    this.markDirty();
     this.logger.debug('Record updated', { object, id });
     return { ...updatedRecord };
   }
@@ -293,6 +376,7 @@ export class InMemoryDriver implements DriverInterface {
     }
 
     table.splice(index, 1);
+    this.markDirty();
     this.logger.debug('Record deleted', { object, id, tableSize: table.length });
     return true;
   }
@@ -350,6 +434,7 @@ export class InMemoryDriver implements DriverInterface {
           }
       }
       
+      if (count > 0) this.markDirty();
       this.logger.debug('UpdateMany completed', { object, count });
       return { count };
   }
@@ -377,6 +462,7 @@ export class InMemoryDriver implements DriverInterface {
       }
       
       const count = initialLength - this.db[object].length;
+      if (count > 0) this.markDirty();
       this.logger.debug('DeleteMany completed', { object, count });
       return { count };
   }
@@ -435,6 +521,7 @@ export class InMemoryDriver implements DriverInterface {
     // Restore the snapshot
     this.db = tx.snapshot;
     this.transactions.delete(txId);
+    this.markDirty();
     this.logger.debug('Transaction rolled back', { txId });
   }
 
@@ -448,6 +535,7 @@ export class InMemoryDriver implements DriverInterface {
   async clear() {
     this.db = {};
     this.idCounters.clear();
+    this.markDirty();
     this.logger.debug('All data cleared');
   }
 
@@ -818,4 +906,145 @@ export class InMemoryDriver implements DriverInterface {
     const timestamp = Date.now();
     return `${key}-${timestamp}-${counter}`;
   }
+
+  // ===================================
+  // Persistence
+  // ===================================
+
+  /**
+   * Mark the database as dirty, triggering persistence save.
+   */
+  private markDirty(): void {
+    if (this.persistenceAdapter) {
+      this.persistenceAdapter.save(this.db);
+    }
+  }
+
+  /**
+   * Flush pending persistence writes to ensure data is safely stored.
+   */
+  async flush(): Promise<void> {
+    if (this.persistenceAdapter) {
+      await this.persistenceAdapter.flush();
+    }
+  }
+
+  /**
+   * Detect whether the current runtime is a browser environment.
+   */
+  private isBrowserEnvironment(): boolean {
+    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).
+   */
+  private isServerlessEnvironment(): boolean {
+    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
+    );
+  }
+
+  private static readonly SERVERLESS_PERSISTENCE_WARNING =
+    'Serverless environment detected — 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 }.';
+
+  /**
+   * 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.
+   */
+  private async initPersistence(): Promise<void> {
+    const persistence = this.config.persistence === undefined ? 'auto' : this.config.persistence;
+    if (persistence === false) return;
+
+    if (typeof persistence === 'string') {
+      if (persistence === 'auto') {
+        if (this.isBrowserEnvironment()) {
+          const { LocalStoragePersistenceAdapter } = await import('./persistence/local-storage-adapter.js');
+          this.persistenceAdapter = new LocalStoragePersistenceAdapter();
+          this.logger.debug('Auto-detected browser environment, using localStorage persistence');
+        } else if (this.isServerlessEnvironment()) {
+          this.logger.warn(InMemoryDriver.SERVERLESS_PERSISTENCE_WARNING);
+        } else {
+          const { FileSystemPersistenceAdapter } = await import('./persistence/file-adapter.js');
+          this.persistenceAdapter = new FileSystemPersistenceAdapter();
+          this.logger.debug('Auto-detected Node.js environment, using file persistence');
+        }
+      } else if (persistence === 'file') {
+        const { FileSystemPersistenceAdapter } = await import('./persistence/file-adapter.js');
+        this.persistenceAdapter = new FileSystemPersistenceAdapter();
+      } else if (persistence === 'local') {
+        const { LocalStoragePersistenceAdapter } = await import('./persistence/local-storage-adapter.js');
+        this.persistenceAdapter = new LocalStoragePersistenceAdapter();
+      } 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 } = await import('./persistence/local-storage-adapter.js');
+          this.persistenceAdapter = new LocalStoragePersistenceAdapter({
+            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 } = await import('./persistence/file-adapter.js');
+          this.persistenceAdapter = new FileSystemPersistenceAdapter({
+            path: persistence.path,
+            autoSaveInterval: persistence.autoSaveInterval,
+          });
+          this.logger.debug('Auto-detected Node.js environment, using file persistence');
+        }
+      } else if (persistence.type === 'file') {
+        const { FileSystemPersistenceAdapter } = await import('./persistence/file-adapter.js');
+        this.persistenceAdapter = new FileSystemPersistenceAdapter({
+          path: persistence.path,
+          autoSaveInterval: persistence.autoSaveInterval,
+        });
+      } else if (persistence.type === 'local') {
+        const { LocalStoragePersistenceAdapter } = await import('./persistence/local-storage-adapter.js');
+        this.persistenceAdapter = new LocalStoragePersistenceAdapter({
+          key: persistence.key,
+        });
+      }
+    }
+
+    if (this.persistenceAdapter) {
+      this.logger.debug('Persistence adapter initialized');
+    }
+  }
 }

package/src/persistence/file-adapter.ts

@@ -0,0 +1,103 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+/**
+ * FileSystemPersistenceAdapter
+ *
+ * Persists the in-memory database to a JSON file on disk.
+ * Supports atomic writes (write to temp file then rename) and auto-save with dirty tracking.
+ *
+ * Node.js only — will throw if used in non-Node.js environments.
+ */
+export class FileSystemPersistenceAdapter {
+  private readonly filePath: string;
+  private readonly autoSaveInterval: number;
+  private dirty = false;
+  private timer: ReturnType<typeof setInterval> | null = null;
+  private currentDb: Record<string, any[]> | null = null;
+
+  constructor(options?: { path?: string; autoSaveInterval?: number }) {
+    this.filePath = options?.path || path.join('.objectstack', 'data', 'memory-driver.json');
+    this.autoSaveInterval = options?.autoSaveInterval ?? 2000;
+  }
+
+  /**
+   * Load persisted data from disk.
+   * Returns null if no file exists.
+   */
+  async load(): Promise<Record<string, any[]> | null> {
+    try {
+      if (!fs.existsSync(this.filePath)) {
+        return null;
+      }
+      const raw = fs.readFileSync(this.filePath, 'utf-8');
+      const data = JSON.parse(raw);
+      return data as Record<string, any[]>;
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Save data to disk using atomic write (temp file + rename).
+   */
+  async save(db: Record<string, any[]>): Promise<void> {
+    this.currentDb = db;
+    this.dirty = true;
+  }
+
+  /**
+   * Flush pending writes to disk immediately.
+   */
+  async flush(): Promise<void> {
+    if (!this.dirty || !this.currentDb) return;
+    await this.writeToDisk(this.currentDb);
+    this.dirty = false;
+  }
+
+  /**
+   * Start the auto-save timer.
+   */
+  startAutoSave(): void {
+    if (this.timer) return;
+    this.timer = setInterval(async () => {
+      if (this.dirty && this.currentDb) {
+        await this.writeToDisk(this.currentDb);
+        this.dirty = false;
+      }
+    }, this.autoSaveInterval);
+
+    // Allow process to exit even if timer is running
+    if (this.timer) {
+      this.timer.unref();
+    }
+  }
+
+  /**
+   * Stop the auto-save timer and flush pending writes.
+   */
+  async stopAutoSave(): Promise<void> {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+    await this.flush();
+  }
+
+  /**
+   * Atomic write: write to temp file, then rename.
+   */
+  private async writeToDisk(db: Record<string, any[]>): Promise<void> {
+    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);
+  }
+}

package/src/persistence/index.ts

@@ -0,0 +1,4 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+export { FileSystemPersistenceAdapter } from './file-adapter.js';
+export { LocalStoragePersistenceAdapter } from './local-storage-adapter.js';

package/src/persistence/local-storage-adapter.ts

@@ -0,0 +1,60 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * LocalStoragePersistenceAdapter
+ *
+ * Persists the in-memory database to browser localStorage.
+ * Synchronous storage with a ~5MB size limit warning.
+ *
+ * Browser only — will throw if used in non-browser environments.
+ */
+export class LocalStoragePersistenceAdapter {
+  private readonly storageKey: string;
+  private static readonly SIZE_WARNING_BYTES = 4.5 * 1024 * 1024; // 4.5MB warning threshold
+
+  constructor(options?: { key?: string }) {
+    this.storageKey = options?.key || 'objectstack:memory-db';
+  }
+
+  /**
+   * Load persisted data from localStorage.
+   * Returns null if no data exists.
+   */
+  async load(): Promise<Record<string, any[]> | null> {
+    try {
+      const raw = localStorage.getItem(this.storageKey);
+      if (!raw) return null;
+      return JSON.parse(raw) as Record<string, any[]>;
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Save data to localStorage.
+   * Warns if data size approaches the ~5MB localStorage limit.
+   */
+  async save(db: Record<string, any[]>): Promise<void> {
+    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: any) {
+      console.error('[ObjectStack] Failed to persist data to localStorage:', e?.message || e);
+    }
+  }
+
+  /**
+   * Flush is a no-op for localStorage (writes are synchronous).
+   */
+  async flush(): Promise<void> {
+    // localStorage writes are synchronous, no flushing needed
+  }
+}