@topgunbuild/adapters

Storage adapters for TopGun. Today: IndexedDB.

Install

npm install @topgunbuild/adapters @topgunbuild/client

Usage

import { TopGunClient } from '@topgunbuild/client';
import { IDBAdapter } from '@topgunbuild/adapters';

const client = new TopGunClient({
  storage: new IDBAdapter('my-app'),   // database name
  // serverUrl: 'ws://localhost:8080', // optional
});
client.start();

IDBAdapter

Non-blocking IndexedDB adapter. Operations queue in memory and replay once the database is ready, so the UI can render immediately without waiting for IDB to open (typically 50–500ms on first visit).

new IDBAdapter(databaseName: string)

The adapter creates three object stores:

• kv_store — key/value records for LWWMap / ORMap
• op_log — append-only operation log (auto-incrementing id)
• meta_store — metadata (sync cursors, schema versions, etc.)

Waiting for initialization (rare)

By default, the adapter is fire-and-forget. If you specifically need to ensure persistence is online (e.g., before importing a backup), use:

const adapter = new IDBAdapter('my-app');
const client = new TopGunClient({ storage: adapter });
client.start();
await adapter.waitForReady();   // optional — blocks until openDB resolves

Browser support

IndexedDB is supported in every modern browser (Chrome, Firefox, Safari, Edge). For Node.js or non-browser environments, a community adapter is on the roadmap.

Documentation

• Full docs: topgun.build/docs
• Client API: @topgunbuild/client
• GitHub: TopGunBuild/topgun

License

Apache-2.0