@objectstack/driver-memory

In-memory ObjectQL driver for ObjectStack — zero-config storage for development, unit tests, Storybook, and browser MSW mocks.

Overview

Implements the IDataEngine contract against in-memory Map-backed tables. Supports the full ObjectQL surface: MongoDB-style operators ($eq, $ne, $gt, $lt, $gte, $lte, $in, $nin, $and, $or, $not), sorting, pagination, aggregations, and joins. Optional persistence adapters serialize state to disk (Node) or localStorage (browser).

Installation

pnpm add @objectstack/driver-memory

Quick Start

import { ObjectKernel } from '@objectstack/core';
import memoryPlugin from '@objectstack/driver-memory';

const kernel = new ObjectKernel();
kernel.use(memoryPlugin);                 // default plugin
await kernel.bootstrap();

Direct instantiation

import { InMemoryDriver } from '@objectstack/driver-memory';

const driver = new InMemoryDriver();
await driver.connect();

With filesystem persistence (Node)

import { InMemoryDriver, FileSystemPersistenceAdapter } from '@objectstack/driver-memory';

const driver = new InMemoryDriver({
  persistence: new FileSystemPersistenceAdapter('./data/snapshot.json'),
});
await driver.connect();

With localStorage persistence (browser)

import { InMemoryDriver, LocalStoragePersistenceAdapter } from '@objectstack/driver-memory';

const driver = new InMemoryDriver({
  persistence: new LocalStoragePersistenceAdapter('objectstack:dev'),
});

Key Exports

| Export | Kind | Description | |:---|:---|:---| | default | kernel plugin | Drop-in plugin. | | InMemoryDriver | class | Driver instance for direct use. | | InMemoryStrategy | class | Query execution strategy used by ObjectQL. | | FileSystemPersistenceAdapter | class | Node-only persistence. | | LocalStoragePersistenceAdapter | class | Browser-only persistence. | | MemoryAnalyticsService | class | Adds analytics aggregations backed by memory store. | | InMemoryDriverConfig, PersistenceAdapterInterface, MemoryAnalyticsConfig | types | Configuration shapes. |

Configuration

| Option | Type | Default | Notes | |:---|:---|:---|:---| | persistence | PersistenceAdapterInterface? | undefined | Optional snapshot store. | | seed | Record<string, any[]>? | {} | Initial rows keyed by object name. | | idStrategy | 'uuid' \| 'auto' | 'uuid' | ID generation strategy. |

When to use

• ✅ Development, unit tests, CI, Storybook.
• ✅ Browser-only demos pairing with @objectstack/plugin-msw.

When not to use

• ❌ Production — data is lost on restart without a persistence adapter; durability/concurrency guarantees are minimal.
• ❌ Multi-process deployments.

Related Packages

• @objectstack/objectql — query engine.
• @objectstack/driver-sql, @objectstack/driver-turso — production drivers.
• @objectstack/plugin-msw — browser mock API.

Links

• 📖 Docs: https://objectstack.ai/docs
• 📚 API Reference: https://objectstack.ai/docs/references

License

Apache-2.0 © ObjectStack