@groundstate/store

Offline-first storage layer with pluggable adapters, encryption, migrations, and query support.

Installation

# npm
npm install @groundstate/store

# yarn
yarn add @groundstate/store

# pnpm
pnpm add @groundstate/store

Quick Start

import { PersistenceEngine, IndexedDBAdapter, EncryptionManager } from '@groundstate/store';
import { Doc, Field } from '@groundstate/crdt';

const doc = Doc({ title: Field(''), body: Field('') });

// Persist to IndexedDB with encryption
const engine = new PersistenceEngine(doc, {
  adapter: new IndexedDBAdapter('my-app'),
  encryption: new EncryptionManager({ key: userKey }),
  autoSave: true,
});

await engine.load();
doc.title = 'Hello, local-first!';
await engine.save();

API Highlights

Storage Adapters

• IndexedDBAdapter -- Browser-based storage using IndexedDB
• SQLiteAdapter -- SQLite storage for Node.js, Electron, or mobile
• MemoryAdapter -- In-memory adapter for testing
• FSAdapter -- File-system adapter for Node.js environments
• StorageAdapter -- Interface for building custom adapters

Persistence

• PersistenceEngine -- Manages loading, saving, and auto-persistence lifecycle

Encryption

• EncryptionManager -- At-rest encryption for stored documents

Compaction & Maintenance

• CompactionEngine -- Compact operation history to reduce storage size

Migrations

• MigrationEngine -- Run versioned schema migrations on stored data
• MigrationTester -- Test migrations against snapshots before deploying

Query

• QueryEngine -- Query documents by field values with filtering and sorting

Backup

• createBackup / restoreBackup -- Export and import full database snapshots

Documentation

See the full documentation for complete API reference.

License

MIT