@objectstack/driver-memory 3.0.10 → 3.1.0

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @objectstack/driver-memory@3.0.10 build /home/runner/work/spec/spec/packages/plugins/driver-memory
+> @objectstack/driver-memory@3.1.0 build /home/runner/work/spec/spec/packages/plugins/driver-memory
 > tsup --config ../../../tsup.config.ts
 
 CLI Building entry: src/index.ts
@@ -10,13 +10,13 @@
 CLI Cleaning output folder
 ESM Build start
 CJS Build start
-ESM dist/index.mjs     36.64 KB
-ESM dist/index.mjs.map 77.34 KB
-ESM ⚡️ Build success in 77ms
-CJS dist/index.js     37.79 KB
-CJS dist/index.js.map 77.38 KB
-CJS ⚡️ Build success in 94ms
+ESM dist/index.mjs     49.23 KB
+ESM dist/index.mjs.map 97.21 KB
+ESM ⚡️ Build success in 160ms
+CJS dist/index.js     50.91 KB
+CJS dist/index.js.map 97.27 KB
+CJS ⚡️ Build success in 163ms
 DTS Build start
-DTS ⚡️ Build success in 16782ms
-DTS dist/index.d.mts 8.39 KB
-DTS dist/index.d.ts  8.39 KB
+DTS ⚡️ Build success in 17419ms
+DTS dist/index.d.mts 13.73 KB
+DTS dist/index.d.ts  13.73 KB

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @objectstack/driver-memory
 
+## 3.1.0
+
+### Patch Changes
+
+- Updated dependencies [0088830]
+  - @objectstack/spec@3.1.0
+  - @objectstack/core@3.1.0
+
+## 3.0.11
+
+### Patch Changes
+
+- Updated dependencies [92d9d99]
+  - @objectstack/spec@3.0.11
+  - @objectstack/core@3.0.11
+
 ## 3.0.10
 
 ### Patch Changes

package/dist/index.d.mts

@@ -2,6 +2,19 @@ import { QueryInput, DriverOptions, Cube, AnalyticsQuery } from '@objectstack/sp
 import { DriverInterface, Logger } from '@objectstack/core';
 import { IAnalyticsService, AnalyticsResult, CubeMeta } from '@objectstack/spec/contracts';
 
+/**
+ * Persistence adapter interface.
+ * Matches the PersistenceAdapterSchema contract from @objectstack/spec.
+ */
+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.
@@ -13,6 +26,28 @@ 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;
+    };
 }
 /**
  * In-Memory Driver for ObjectStack
@@ -38,6 +73,7 @@ declare class InMemoryDriver implements DriverInterface {
     private logger;
     private idCounters;
     private transactions;
+    private persistenceAdapter;
     constructor(config?: InMemoryDriverConfig);
     install(ctx: any): void;
     supports: {
@@ -164,6 +200,120 @@ declare class InMemoryDriver implements DriverInterface {
     private projectFields;
     private getTable;
     private generateId;
+    /**
+     * Mark the database as dirty, triggering persistence save.
+     */
+    private markDirty;
+    /**
+     * Flush pending persistence writes to ensure data is safely stored.
+     */
+    flush(): Promise<void>;
+    /**
+     * Detect whether the current runtime is a browser environment.
+     */
+    private isBrowserEnvironment;
+    /**
+     * 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;
+    private static readonly SERVERLESS_PERSISTENCE_WARNING;
+    /**
+     * 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 initPersistence;
+}
+
+/**
+ * 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.
+ */
+declare class FileSystemPersistenceAdapter {
+    private readonly filePath;
+    private readonly autoSaveInterval;
+    private dirty;
+    private timer;
+    private currentDb;
+    constructor(options?: {
+        path?: string;
+        autoSaveInterval?: number;
+    });
+    /**
+     * Load persisted data from disk.
+     * Returns null if no file exists.
+     */
+    load(): Promise<Record<string, any[]> | null>;
+    /**
+     * Save data to disk using atomic write (temp file + rename).
+     */
+    save(db: Record<string, any[]>): Promise<void>;
+    /**
+     * Flush pending writes to disk immediately.
+     */
+    flush(): Promise<void>;
+    /**
+     * Start the auto-save timer.
+     */
+    startAutoSave(): void;
+    /**
+     * Stop the auto-save timer and flush pending writes.
+     */
+    stopAutoSave(): Promise<void>;
+    /**
+     * Atomic write: write to temp file, then rename.
+     */
+    private writeToDisk;
+}
+
+/**
+ * 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.
+ */
+declare class LocalStoragePersistenceAdapter {
+    private readonly storageKey;
+    private static readonly SIZE_WARNING_BYTES;
+    constructor(options?: {
+        key?: string;
+    });
+    /**
+     * Load persisted data from localStorage.
+     * Returns null if no data exists.
+     */
+    load(): Promise<Record<string, any[]> | null>;
+    /**
+     * Save data to localStorage.
+     * Warns if data size approaches the ~5MB localStorage limit.
+     */
+    save(db: Record<string, any[]>): Promise<void>;
+    /**
+     * Flush is a no-op for localStorage (writes are synchronous).
+     */
+    flush(): Promise<void>;
 }
 
 /**
@@ -237,4 +387,4 @@ declare const _default: {
     onEnable: (context: any) => Promise<void>;
 };
 
-export { InMemoryDriver, type InMemoryDriverConfig, type MemoryAnalyticsConfig, MemoryAnalyticsService, _default as default };
+export { FileSystemPersistenceAdapter, InMemoryDriver, type InMemoryDriverConfig, LocalStoragePersistenceAdapter, type MemoryAnalyticsConfig, MemoryAnalyticsService, type PersistenceAdapterInterface, _default as default };

package/dist/index.d.ts

@@ -2,6 +2,19 @@ import { QueryInput, DriverOptions, Cube, AnalyticsQuery } from '@objectstack/sp
 import { DriverInterface, Logger } from '@objectstack/core';
 import { IAnalyticsService, AnalyticsResult, CubeMeta } from '@objectstack/spec/contracts';
 
+/**
+ * Persistence adapter interface.
+ * Matches the PersistenceAdapterSchema contract from @objectstack/spec.
+ */
+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.
@@ -13,6 +26,28 @@ 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;
+    };
 }
 /**
  * In-Memory Driver for ObjectStack
@@ -38,6 +73,7 @@ declare class InMemoryDriver implements DriverInterface {
     private logger;
     private idCounters;
     private transactions;
+    private persistenceAdapter;
     constructor(config?: InMemoryDriverConfig);
     install(ctx: any): void;
     supports: {
@@ -164,6 +200,120 @@ declare class InMemoryDriver implements DriverInterface {
     private projectFields;
     private getTable;
     private generateId;
+    /**
+     * Mark the database as dirty, triggering persistence save.
+     */
+    private markDirty;
+    /**
+     * Flush pending persistence writes to ensure data is safely stored.
+     */
+    flush(): Promise<void>;
+    /**
+     * Detect whether the current runtime is a browser environment.
+     */
+    private isBrowserEnvironment;
+    /**
+     * 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;
+    private static readonly SERVERLESS_PERSISTENCE_WARNING;
+    /**
+     * 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 initPersistence;
+}
+
+/**
+ * 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.
+ */
+declare class FileSystemPersistenceAdapter {
+    private readonly filePath;
+    private readonly autoSaveInterval;
+    private dirty;
+    private timer;
+    private currentDb;
+    constructor(options?: {
+        path?: string;
+        autoSaveInterval?: number;
+    });
+    /**
+     * Load persisted data from disk.
+     * Returns null if no file exists.
+     */
+    load(): Promise<Record<string, any[]> | null>;
+    /**
+     * Save data to disk using atomic write (temp file + rename).
+     */
+    save(db: Record<string, any[]>): Promise<void>;
+    /**
+     * Flush pending writes to disk immediately.
+     */
+    flush(): Promise<void>;
+    /**
+     * Start the auto-save timer.
+     */
+    startAutoSave(): void;
+    /**
+     * Stop the auto-save timer and flush pending writes.
+     */
+    stopAutoSave(): Promise<void>;
+    /**
+     * Atomic write: write to temp file, then rename.
+     */
+    private writeToDisk;
+}
+
+/**
+ * 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.
+ */
+declare class LocalStoragePersistenceAdapter {
+    private readonly storageKey;
+    private static readonly SIZE_WARNING_BYTES;
+    constructor(options?: {
+        key?: string;
+    });
+    /**
+     * Load persisted data from localStorage.
+     * Returns null if no data exists.
+     */
+    load(): Promise<Record<string, any[]> | null>;
+    /**
+     * Save data to localStorage.
+     * Warns if data size approaches the ~5MB localStorage limit.
+     */
+    save(db: Record<string, any[]>): Promise<void>;
+    /**
+     * Flush is a no-op for localStorage (writes are synchronous).
+     */
+    flush(): Promise<void>;
 }
 
 /**
@@ -237,4 +387,4 @@ declare const _default: {
     onEnable: (context: any) => Promise<void>;
 };
 
-export { InMemoryDriver, type InMemoryDriverConfig, type MemoryAnalyticsConfig, MemoryAnalyticsService, _default as default };
+export { FileSystemPersistenceAdapter, InMemoryDriver, type InMemoryDriverConfig, LocalStoragePersistenceAdapter, type MemoryAnalyticsConfig, MemoryAnalyticsService, type PersistenceAdapterInterface, _default as default };