@objectstack/driver-memory 3.0.10 → 3.0.11

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,24 @@ 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)
+   * - `'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)
+   */
+  persistence?: string | false | {
+    type?: 'file' | 'local' | 'auto';
+    path?: string;
+    key?: string;
+    autoSaveInterval?: number;
+    adapter?: PersistenceAdapterInterface;
+  };
 }
 
 /**
@@ -51,6 +83,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 +133,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 +179,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 +303,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 +331,7 @@ export class InMemoryDriver implements DriverInterface {
     };
     
     table[index] = updatedRecord;
+    this.markDirty();
     this.logger.debug('Record updated', { object, id });
     return { ...updatedRecord };
   }
@@ -293,6 +372,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 +430,7 @@ export class InMemoryDriver implements DriverInterface {
           }
       }
       
+      if (count > 0) this.markDirty();
       this.logger.debug('UpdateMany completed', { object, count });
       return { count };
   }
@@ -377,6 +458,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 +517,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 +531,7 @@ export class InMemoryDriver implements DriverInterface {
   async clear() {
     this.db = {};
     this.idCounters.clear();
+    this.markDirty();
     this.logger.debug('All data cleared');
   }
 
@@ -818,4 +902,99 @@ 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';
+  }
+
+  /**
+   * Initialize the persistence adapter based on configuration.
+   * Defaults to 'auto' when persistence is not specified.
+   * Use `persistence: false` to explicitly disable persistence.
+   */
+  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 {
+          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 {
+          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
+  }
+}

package/src/persistence/persistence.test.ts

@@ -0,0 +1,215 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { InMemoryDriver } from '../memory-driver.js';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+const TEST_DATA_DIR = path.join('/tmp', 'objectstack-test-persistence');
+const TEST_FILE_PATH = path.join(TEST_DATA_DIR, 'test-db.json');
+
+describe('InMemoryDriver Persistence', () => {
+  beforeEach(() => {
+    // Clean up test directory
+    if (fs.existsSync(TEST_DATA_DIR)) {
+      fs.rmSync(TEST_DATA_DIR, { recursive: true });
+    }
+  });
+
+  afterEach(() => {
+    if (fs.existsSync(TEST_DATA_DIR)) {
+      fs.rmSync(TEST_DATA_DIR, { recursive: true });
+    }
+  });
+
+  describe('File Persistence', () => {
+    it('should persist and restore data via file adapter', async () => {
+      // Create and populate driver with file persistence
+      const driver1 = new InMemoryDriver({
+        persistence: { type: 'file', path: TEST_FILE_PATH, autoSaveInterval: 100 },
+      });
+      await driver1.connect();
+      await driver1.create('users', { id: '1', name: 'Alice' });
+      await driver1.create('users', { id: '2', name: 'Bob' });
+
+      // Flush and disconnect
+      await driver1.flush();
+      await driver1.disconnect();
+
+      // Verify file was created
+      expect(fs.existsSync(TEST_FILE_PATH)).toBe(true);
+
+      // Create a new driver and verify data is restored
+      const driver2 = new InMemoryDriver({
+        persistence: { type: 'file', path: TEST_FILE_PATH, autoSaveInterval: 100 },
+      });
+      await driver2.connect();
+
+      const users = await driver2.find('users', { object: 'users' });
+      expect(users).toHaveLength(2);
+      expect(users[0].name).toBe('Alice');
+      expect(users[1].name).toBe('Bob');
+
+      await driver2.disconnect();
+    });
+
+    it('should support shorthand "file" persistence string', async () => {
+      // Use shorthand — just verifies no error is thrown with 'file'
+      const driver = new InMemoryDriver({ persistence: 'file' });
+      await driver.connect();
+      await driver.create('items', { id: '1', name: 'Widget' });
+      await driver.disconnect();
+    });
+
+    it('should persist updates and deletes', async () => {
+      const driver1 = new InMemoryDriver({
+        persistence: { type: 'file', path: TEST_FILE_PATH, autoSaveInterval: 100 },
+      });
+      await driver1.connect();
+
+      // Create, update, and delete
+      await driver1.create('tasks', { id: '1', title: 'Task A', done: false });
+      await driver1.create('tasks', { id: '2', title: 'Task B', done: false });
+      await driver1.update('tasks', '1', { done: true });
+      await driver1.delete('tasks', '2');
+
+      await driver1.flush();
+      await driver1.disconnect();
+
+      // Restore
+      const driver2 = new InMemoryDriver({
+        persistence: { type: 'file', path: TEST_FILE_PATH, autoSaveInterval: 100 },
+      });
+      await driver2.connect();
+
+      const tasks = await driver2.find('tasks', { object: 'tasks' });
+      expect(tasks).toHaveLength(1);
+      expect(tasks[0].id).toBe('1');
+      expect(tasks[0].done).toBe(true);
+
+      await driver2.disconnect();
+    });
+
+    it('should handle missing persistence file gracefully', async () => {
+      const driver = new InMemoryDriver({
+        persistence: { type: 'file', path: '/tmp/nonexistent/path/db.json' },
+      });
+      await driver.connect();
+
+      const users = await driver.find('users', { object: 'users' });
+      expect(users).toHaveLength(0);
+
+      await driver.disconnect();
+    });
+  });
+
+  describe('Custom Adapter Persistence', () => {
+    it('should use a custom adapter for persistence', async () => {
+      const stored: Record<string, any[]> = {};
+      const customAdapter = {
+        load: async () => Object.keys(stored).length > 0 ? { ...stored } : null,
+        save: async (db: Record<string, any[]>) => {
+          for (const [k, v] of Object.entries(db)) {
+            stored[k] = [...v];
+          }
+        },
+        flush: async () => {},
+      };
+
+      const driver1 = new InMemoryDriver({
+        persistence: { adapter: customAdapter },
+      });
+      await driver1.connect();
+      await driver1.create('projects', { id: '1', name: 'Alpha' });
+      await driver1.disconnect();
+
+      // Verify data was saved via custom adapter
+      expect(stored.projects).toBeDefined();
+      expect(stored.projects).toHaveLength(1);
+
+      // Restore from custom adapter
+      const driver2 = new InMemoryDriver({
+        persistence: { adapter: customAdapter },
+      });
+      await driver2.connect();
+      const projects = await driver2.find('projects', { object: 'projects' });
+      expect(projects).toHaveLength(1);
+      expect(projects[0].name).toBe('Alpha');
+
+      await driver2.disconnect();
+    });
+  });
+
+  describe('Pure Memory (No Persistence)', () => {
+    it('should work without persistence when explicitly disabled', async () => {
+      const driver = new InMemoryDriver({ persistence: false });
+      await driver.connect();
+
+      await driver.create('items', { id: '1', name: 'Widget' });
+      const items = await driver.find('items', { object: 'items' });
+      expect(items).toHaveLength(1);
+
+      await driver.disconnect();
+
+      // After disconnect, data is gone
+      const itemsAfter = await driver.find('items', { object: 'items' });
+      expect(itemsAfter).toHaveLength(0);
+    });
+  });
+
+  describe('Auto Persistence', () => {
+    it('should auto-detect Node.js environment and use file persistence with shorthand', async () => {
+      // In Node.js, 'auto' should select file persistence
+      const driver = new InMemoryDriver({ persistence: 'auto' });
+      await driver.connect();
+      await driver.create('items', { id: '1', name: 'Widget' });
+      await driver.disconnect();
+    });
+
+    it('should auto-detect Node.js environment and use file persistence with object config', async () => {
+      const filePath = path.join(TEST_DATA_DIR, 'auto-test-db.json');
+      const driver1 = new InMemoryDriver({
+        persistence: { type: 'auto', path: filePath, autoSaveInterval: 100 },
+      });
+      await driver1.connect();
+      await driver1.create('users', { id: '1', name: 'Alice' });
+      await driver1.flush();
+      await driver1.disconnect();
+
+      // Verify file was created (Node.js env selects file adapter)
+      expect(fs.existsSync(filePath)).toBe(true);
+
+      // Restore from file
+      const driver2 = new InMemoryDriver({
+        persistence: { type: 'auto', path: filePath, autoSaveInterval: 100 },
+      });
+      await driver2.connect();
+      const users = await driver2.find('users', { object: 'users' });
+      expect(users).toHaveLength(1);
+      expect(users[0].name).toBe('Alice');
+      await driver2.disconnect();
+    });
+  });
+
+  describe('Bulk Operations with Persistence', () => {
+    it('should persist bulk creates', async () => {
+      const driver1 = new InMemoryDriver({
+        persistence: { type: 'file', path: TEST_FILE_PATH, autoSaveInterval: 100 },
+      });
+      await driver1.connect();
+      await driver1.bulkCreate('items', [
+        { id: '1', name: 'A' },
+        { id: '2', name: 'B' },
+        { id: '3', name: 'C' },
+      ]);
+      await driver1.flush();
+      await driver1.disconnect();
+
+      const driver2 = new InMemoryDriver({
+        persistence: { type: 'file', path: TEST_FILE_PATH, autoSaveInterval: 100 },
+      });
+      await driver2.connect();
+      const items = await driver2.find('items', { object: 'items' });
+      expect(items).toHaveLength(3);
+      await driver2.disconnect();
+    });
+  });
+});