feat: add auto-detect persistence strategy for memory driver

Adds 'auto' mode to PersistenceTypeSchema that detects browser vs Node.js
environment at runtime and automatically selects the best persistence strategy:
- Browser → localStorage persistence
- Node.js → file-system persistence

Changes:
- spec: Add 'auto' to PersistenceTypeSchema enum
- spec: Add AutoPersistenceConfigSchema with optional overrides
- spec: Update MemoryPersistenceConfigSchema union to include auto
- driver: Add isBrowserEnvironment() detection method
- driver: Handle 'auto' in initPersistence() for both shorthand and object config
- tests: Add schema validation tests for auto persistence
- tests: Add driver integration tests for auto environment detection

Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>

Author: Copilot

packages/plugins/driver-memory/src/memory-driver.ts

@@ -35,12 +35,14 @@ export interface InMemoryDriverConfig {
    * Optional persistence configuration.
    * - `'file'` — File-system persistence with defaults (Node.js only)
    * - `'local'` — localStorage persistence with defaults (Browser only)
+   * - `'auto'` — Auto-detect environment (browser → localStorage, Node.js → file)
    * - `{ 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
    */
   persistence?: string | {
-    type?: 'file' | 'local';
+    type?: 'file' | 'local' | 'auto';
     path?: string;
     key?: string;
     autoSaveInterval?: number;
@@ -922,6 +924,13 @@ export class InMemoryDriver implements DriverInterface {
     }
   }
 
+  /**
+   * Detect whether the current runtime is a browser environment.
+   */
+  private isBrowserEnvironment(): boolean {
+    return typeof window !== 'undefined' && typeof window.localStorage !== 'undefined';
+  }
+
   /**
    * Initialize the persistence adapter based on configuration.
    */
@@ -930,19 +939,44 @@ export class InMemoryDriver implements DriverInterface {
     if (!persistence) return;
 
     if (typeof persistence === 'string') {
-      if (persistence === 'file') {
+      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' or 'local'.`);
+        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 === 'file') {
+      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,

packages/plugins/driver-memory/src/persistence/persistence.test.ts

@@ -155,6 +155,40 @@ describe('InMemoryDriver Persistence', () => {
     });
   });
 
+  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({

packages/spec/src/data/driver/memory.test.ts

@@ -8,6 +8,7 @@ import {
   LocalStoragePersistenceConfigSchema,
   CustomPersistenceConfigSchema,
   PersistenceAdapterSchema,
+  AutoPersistenceConfigSchema,
 } from './memory.zod';
 
 describe('MemoryConfigSchema', () => {
@@ -63,6 +64,14 @@ describe('MemoryConfigSchema', () => {
     expect(config.persistence).toBe('local');
   });
 
+  it('should accept persistence shorthand "auto"', () => {
+    const config = MemoryConfigSchema.parse({
+      persistence: 'auto',
+    });
+
+    expect(config.persistence).toBe('auto');
+  });
+
   it('should accept persistence with file object config', () => {
     const config = MemoryConfigSchema.parse({
       persistence: {
@@ -104,6 +113,34 @@ describe('MemoryConfigSchema', () => {
     expect(p.key).toBe('myapp:db');
   });
 
+  it('should accept persistence with auto object config', () => {
+    const config = MemoryConfigSchema.parse({
+      persistence: {
+        type: 'auto',
+        path: '/var/data/memory.json',
+        key: 'myapp:db',
+        autoSaveInterval: 5000,
+      },
+    });
+
+    const p = config.persistence as { type: 'auto'; path?: string; key?: string; autoSaveInterval?: number };
+    expect(p.type).toBe('auto');
+    expect(p.path).toBe('/var/data/memory.json');
+    expect(p.key).toBe('myapp:db');
+    expect(p.autoSaveInterval).toBe(5000);
+  });
+
+  it('should accept auto persistence without overrides', () => {
+    const config = MemoryConfigSchema.parse({
+      persistence: {
+        type: 'auto',
+      },
+    });
+
+    const p = config.persistence as { type: 'auto' };
+    expect(p.type).toBe('auto');
+  });
+
   it('should accept persistence with custom adapter', () => {
     const mockAdapter = {
       load: async () => null,
@@ -205,6 +242,10 @@ describe('PersistenceTypeSchema', () => {
     expect(PersistenceTypeSchema.parse('local')).toBe('local');
   });
 
+  it('should accept auto type', () => {
+    expect(PersistenceTypeSchema.parse('auto')).toBe('auto');
+  });
+
   it('should reject invalid type', () => {
     expect(() => PersistenceTypeSchema.parse('indexeddb')).toThrow();
   });
@@ -279,6 +320,40 @@ describe('CustomPersistenceConfigSchema', () => {
   });
 });
 
+describe('AutoPersistenceConfigSchema', () => {
+  it('should accept minimal auto config', () => {
+    const config = AutoPersistenceConfigSchema.parse({
+      type: 'auto',
+    });
+
+    expect(config.type).toBe('auto');
+    expect(config.path).toBeUndefined();
+    expect(config.key).toBeUndefined();
+    expect(config.autoSaveInterval).toBeUndefined();
+  });
+
+  it('should accept auto config with all overrides', () => {
+    const config = AutoPersistenceConfigSchema.parse({
+      type: 'auto',
+      path: '/data/store.json',
+      key: 'myapp:db',
+      autoSaveInterval: 5000,
+    });
+
+    expect(config.type).toBe('auto');
+    expect(config.path).toBe('/data/store.json');
+    expect(config.key).toBe('myapp:db');
+    expect(config.autoSaveInterval).toBe(5000);
+  });
+
+  it('should reject auto config with invalid autoSaveInterval', () => {
+    expect(() => AutoPersistenceConfigSchema.parse({
+      type: 'auto',
+      autoSaveInterval: 50, // Below minimum of 100
+    })).toThrow();
+  });
+});
+
 describe('MemoryPersistenceConfigSchema', () => {
   it('should accept shorthand "file"', () => {
     const config = MemoryPersistenceConfigSchema.parse('file');
@@ -290,6 +365,11 @@ describe('MemoryPersistenceConfigSchema', () => {
     expect(config).toBe('local');
   });
 
+  it('should accept shorthand "auto"', () => {
+    const config = MemoryPersistenceConfigSchema.parse('auto');
+    expect(config).toBe('auto');
+  });
+
   it('should accept file object config', () => {
     const config = MemoryPersistenceConfigSchema.parse({
       type: 'file',
@@ -306,6 +386,15 @@ describe('MemoryPersistenceConfigSchema', () => {
     expect(config).toEqual({ type: 'local', key: 'myapp:db' });
   });
 
+  it('should accept auto object config', () => {
+    const config = MemoryPersistenceConfigSchema.parse({
+      type: 'auto',
+      path: '/data/store.json',
+      key: 'myapp:db',
+    });
+    expect(config).toEqual({ type: 'auto', path: '/data/store.json', key: 'myapp:db' });
+  });
+
   it('should accept custom adapter', () => {
     const adapter = {
       load: async () => null,

packages/spec/src/data/driver/memory.zod.ts

@@ -42,8 +42,10 @@ export type PersistenceAdapter = z.infer<typeof PersistenceAdapterSchema>;
  * Persistence type enum.
  * - `file`: Persist to disk file (Node.js only).
  * - `local`: Persist to localStorage (Browser only).
+ * - `auto`: Auto-detect environment and choose the best strategy.
+ *   Uses `localStorage` in browser environments and `file` in Node.js.
  */
-export const PersistenceTypeSchema = z.enum(['file', 'local']).describe('Persistence backend type');
+export const PersistenceTypeSchema = z.enum(['file', 'local', 'auto']).describe('Persistence backend type');
 
 export type PersistenceType = z.infer<typeof PersistenceTypeSchema>;
 
@@ -83,23 +85,52 @@ export const CustomPersistenceConfigSchema = z.object({
 
 export type CustomPersistenceConfig = z.infer<typeof CustomPersistenceConfigSchema>;
 
+/**
+ * Auto-detect persistence configuration.
+ * Automatically selects the best persistence strategy based on the runtime environment:
+ * - Browser → localStorage persistence
+ * - Node.js → File-system persistence
+ *
+ * Optional overrides allow customizing the file path or localStorage key
+ * used by the auto-detected adapter.
+ */
+export const AutoPersistenceConfigSchema = z.object({
+  type: z.literal('auto'),
+  /** File path override when running in Node.js. */
+  path: z.string().optional().describe('File path override for Node.js environments'),
+  /** Auto-save interval override when running in Node.js. Default: 2000ms. */
+  autoSaveInterval: z.number().min(100).optional().describe('Auto-save interval override for Node.js environments'),
+  /** localStorage key override when running in a browser. */
+  key: z.string().optional().describe('localStorage key override for browser environments'),
+}).describe('Auto-detect persistence configuration');
+
+export type AutoPersistenceConfig = z.infer<typeof AutoPersistenceConfigSchema>;
+
 /**
  * Unified persistence configuration.
  *
  * Supports shorthand strings and detailed object configs:
  * - `'file'` — File-system persistence with defaults (Node.js)
  * - `'local'` — localStorage persistence with defaults (Browser)
+ * - `'auto'` — Auto-detect environment (browser → localStorage, Node.js → file)
  * - `{ type: 'file', path?: string }` — File-system with custom path
  * - `{ type: 'local', key?: string }` — localStorage with custom key
+ * - `{ type: 'auto', path?: string, key?: string }` — Auto-detect with overrides
  * - `{ adapter: PersistenceAdapter }` — Custom adapter
  *
  * @example
+ * // Auto-detect environment
+ * persistence: 'auto'
+ *
  * // Node.js with defaults
  * persistence: 'file'
  *
  * // Browser with defaults
  * persistence: 'local'
  *
+ * // Auto-detect with overrides
+ * persistence: { type: 'auto', path: '/var/data/memory.json', key: 'myapp:db' }
+ *
  * // Custom file path
  * persistence: { type: 'file', path: '/var/data/memory.json' }
  *
@@ -110,6 +141,7 @@ export const MemoryPersistenceConfigSchema = z.union([
   PersistenceTypeSchema,
   FilePersistenceConfigSchema,
   LocalStoragePersistenceConfigSchema,
+  AutoPersistenceConfigSchema,
   CustomPersistenceConfigSchema,
 ]).describe('Persistence configuration for the memory driver');
 
@@ -149,13 +181,17 @@ export const MemoryConfigSchema = z.object({
    * Optional persistence configuration.
    * When configured, the memory store automatically saves and restores data.
    *
+   * - `'auto'`: Auto-detect environment (browser → localStorage, Node.js → file)
    * - `'file'`: Persist to disk file (Node.js only, default path: `.objectstack/data/memory-driver.json`)
    * - `'local'`: Persist to localStorage (Browser only, default key: `objectstack:memory-db`)
+   * - `{ type: 'auto', path?: string, key?: string }`: Auto-detect with overrides
    * - `{ type: 'file', path?: string }`: File-system with custom path
    * - `{ type: 'local', key?: string }`: localStorage with custom key
    * - `{ adapter: PersistenceAdapter }`: Custom persistence adapter
    *
    * @example
+   * // Auto-detect environment
+   * new InMemoryDriver({ persistence: 'auto' })
    * // Node.js
    * new InMemoryDriver({ persistence: 'file' })
    * // Browser