fyre-db

An offline-first, reactive data framework for TypeScript/JavaScript. fyre-db handles entity storage, multi-device sync via cloud blob storage, HLC-based conflict resolution, multi-tenancy, encryption, and reactive UI bindings.

Install

npm install @fyre-db/core

Quick Start

import { FyreDb, MemoryStorageAdapter, defineEntity } from '@fyre-db/core';

// 1. Define your entities
type Task = { title: string; done: boolean };
const taskDef = defineEntity<Task>('task');

// 2. Create a FyreDb instance
const fyredb = new FyreDb({
  appId: 'my-app',
  entities: [taskDef],
  localAdapter: new MemoryStorageAdapter(),
  deviceId: 'device-1',
});

// 3. Create and open a tenant
const tenant = await fyredb.tenants.create({ name: 'My Workspace', meta: {} });
await fyredb.tenants.open(tenant.id);

// 4. Use the repository
const tasks = fyredb.repo(taskDef);
const id = tasks.save({ title: 'Hello FyreDb', done: false });
console.log(tasks.get(id));        // { title: 'Hello FyreDb', done: false, id: '...', ... }
console.log(tasks.query().length); // 1

// 5. Clean up
await fyredb.dispose();

Features

| Feature | Description | |---|---| | Offline-first | In-memory Map is the source of truth. All reads are synchronous. | | Multi-device sync | Three-tier sync: memory ↔ local ↔ cloud. Periodic flush + cloud sync via any blob storage. | | Conflict resolution | HLC-based (Hybrid Logical Clock) last-writer-wins with tombstone support. | | Reactive | RxJS Observables for entity changes, queries, sync events, and dirty state. | | Multi-tenancy | Isolated workspaces with metadata-based storage routing and tenant sharing. | | Encryption | Per-tenant credential-based encryption (KEK/DEK model) with automatic detection. | | Migrations | Lazy blob migrations that transform stored data to new formats on read. | | Pluggable storage | One StorageAdapter interface (3 methods) — implement for IndexedDB, filesystem, S3, or any backend. |

Configuration

const fyredb = new FyreDb({
  appId: 'my-app',                    // unique app identifier
  entities: [taskDef, noteDef],       // entity definitions
  localAdapter: myStorageAdapter,     // StorageAdapter implementation
  cloudAdapter: myCloudAdapter,       // optional — enables cloud sync
  deviceId: 'device-1',              // unique per device
  encryptionService: myEncryption,    // optional — enables per-tenant encryption
  migrations: [...],                  // optional — blob migrations
  options: {
    localFlushDebounceMs: 500,        // memory → local, after edits settle (default: 500ms)
    localFlushMaxWaitMs: 3000,        // local flush ceiling during sustained edits (default: 3s)
    cloudSyncDebounceMs: 10000,       // cloud sync, after edits settle (default: 10s)
    cloudSyncMaxWaitMs: 60000,        // cloud sync ceiling (default: 60s)
    cloudPullIntervalMs: 300000,      // periodic pull backstop (default: 5m)
    tombstoneRetentionMs: 604800000,  // tombstone TTL (default: 7 days)
  },
});

Lifecycle

new FyreDb(config) → tenants.open(id) → use repos → dispose()

1. new FyreDb(config) — creates instance, validates entity definitions, initializes HLC and EventBus
2. fyredb.tenants.open(tenantId) — loads tenant, hydrates data from local/cloud, starts sync scheduler
3. Use repos — fyredb.repo(entityDef) for CRUD, queries, and reactive observations
4. fyredb.dispose() — closes tenant, flushes to local, stops sync, cleans up

Guides

| Guide | Description | |---|---| | Getting Started | Installation, first entity, lifecycle diagram | | Entities & Repositories | Key strategies, queries, CRUD, batch operations | | Reactive Observations | Observe entity changes and sync events with RxJS | | Storage Adapters | Implement custom persistence backends | | Sync & Offline | Cloud sync, conflict resolution, tombstones | | Encryption | Per-tenant encryption with PBKDF2 + AES-GCM | | Multi-Tenancy | Tenant management, sharing, and probing | | Migrations | Data schema evolution with lazy blob migrations |

License

MIT