VANTAGE
Documentation

Local Storage Adapters (@xtnd/vantage-storage-local)

Package: @xtnd/vantage-storage-local
Source Directory: xtnd-vantage/packages/storage-local/

1. Overview

@xtnd/vantage-storage-local provides the physical storage implementations for the Vantage local-first queuing architecture. It isolates telemetry writes from network failures and client disconnects.

2. Storage Adapters

2.1 MemoryStorageAdapter

High-speed, zero-dependency in-memory array adapter.

  • Primary Environments: Cloudflare Workers, Node.js background services, and automated test runners.
  • Capacity Guardrail: Defaults to maxCapacity = 5,000 events. When capacity is exceeded, it strategically evicts already-synced events before dropping the oldest unsynced event.
  • Pruning: Automatically cleans up synced records older than 24 hours via prune().

2.2 IndexedDBStorageAdapter

Persistent browser database adapter utilizing the browser's native IndexedDB API.

  • Primary Environments: Web browsers (LaoGPT, EvergreenAI, X360, XTransfer web apps).
  • Store Schema: Object store events keyed by UUID id, indexed by synced (boolean), timestamp (number), and priority (string).
  • Offline Durability: Telemetry events recorded while a user is offline (e.g. on mobile or during tunnel transit) remain persisted in IndexedDB and automatically flush when connectivity is re-established.
  • Seamless SSR / Fallback: If initialized in server-side rendering (SSR), Node.js, or private browsing modes where IndexedDB is inaccessible, it transparently falls back to MemoryStorageAdapter without throwing errors.

3. Storage Interface Implementation Comparison

Method MemoryStorageAdapter IndexedDBStorageAdapter
write(event) Pushes to internal array Puts object into IndexedDB transaction
readUnsynced(limit) Filters array where !event.synced Queries synced index with IDBKeyRange.only(false)
markSynced(ids) Sets event.synced = true for matching IDs Reads and updates records in readwrite transaction
prune(cutoff) Filters out synced events older than cutoff Iterates cursor over timestamp index and deletes synced records
count() Returns this.events.length Queries store.count()
clear() Resets array to [] Calls store.clear()

4. Usage Example

import { IndexedDBStorageAdapter } from '@xtnd/vantage-storage-local';

const storage = new IndexedDBStorageAdapter({
  dbName: 'xtnd_vantage_store',
  storeName: 'events'
});

// Writing an event
await storage.write({
  id: 'evt_123456',
  type: 'user:prompt_submit',
  source: 'laogpt.com',
  priority: 'P2_NORMAL',
  timestamp: Date.now(),
  payload: { promptLength: 120 },
  synced: false
});

// Reading pending events for batch sync
const pending = await storage.readUnsynced(50);
console.log(`Found ${pending.length} unsynced events`);

// Marking as confirmed
await storage.markSynced(['evt_123456']);