Criterion	WebSocket	HTTP Sync	AutoConnectionProvider
Real-time updates	Pushed instantly	Polled (configurable interval)	WS when available, HTTP fallback
Serverless compatible	No (needs persistent connection)	Yes (stateless requests)	Yes (auto-detects)
Live query subscriptions	Yes	No (one-shot queries only)	Depends on active transport
Bandwidth efficiency	Merkle tree delta sync	Timestamp-based delta sync	Best available
Connection cost	Per-connection billing	Per-request billing	Adapts to environment
Recommended for	Real-time apps, VPS/container deployments	Serverless functions, edge functions	Unknown deployment target

Criterion

WebSocket

HTTP Sync

AutoConnectionProvider

Real-time updates

Pushed instantly

Polled (configurable interval)

WS when available, HTTP fallback

Serverless compatible

No (needs persistent connection)

Yes (stateless requests)

Yes (auto-detects)

Live query subscriptions

Yes

No (one-shot queries only)

Depends on active transport

Bandwidth efficiency

Merkle tree delta sync

Timestamp-based delta sync

Best available

Connection cost

Per-connection billing

Per-request billing

Adapts to environment

Recommended for

Real-time apps, VPS/container deployments

Serverless functions, edge functions

Unknown deployment target

Feature	LWW-Map	OR-Map
Primary Use Case	Key-Value properties (Profile, Config)	Collections, Sets, Lists (Todos, Comments)
Conflict Resolution	Last Write Wins (Overwrites)	Union of Adds (Merge), Observed Remove
Deletion	Tombstone (`value: null`)	Tag added to tombstone set
Hook (UI)	`useQuery / useMutation`	`useORMap`

Feature

LWW-Map

OR-Map

Primary Use Case

Key-Value properties (Profile, Config)

Collections, Sets, Lists (Todos, Comments)

Conflict Resolution

Last Write Wins (Overwrites)

Union of Adds (Merge), Observed Remove

Deletion

Tombstone (value: null)

Tag added to tombstone set

Hook (UI)

useQuery / useMutation

useORMap

Client API

`TopGunClient` is the imperative SDK entry point. It manages local CRDT maps, the sync engine, and the connection lifecycle. The class is generic over an optional schema type that narrows `getMap`, `getORMap`, and `query` to your application types. ```typescript interface AppSchema { todos: { text: string; done: boolean }; users: { name: string; email: string }; } const client = new TopGunClient({ storage: new IDBAdapter(), }); // Narrowed: LWWMap const todos = client.getMap('todos'); ``` The untyped fallback overloads remain for callers that pass explicit type parameters. ## Constructor ```typescript new TopGunClient(config: TopGunClientConfig) ``` `TopGunClientConfig` accepts: | Field | Type | Description | |---|---|---| | `storage` | `IStorageAdapter` | Required. Local persistence (typically `new IDBAdapter()`). | | `serverUrl` | `string` | Optional. WebSocket URL for single-server mode. Mutually exclusive with `cluster`. | | `cluster` | `TopGunClusterConfig` | Optional. Cluster configuration. Mutually exclusive with `serverUrl`. | | `nodeId` | `string` | Optional. Auto-generated UUID if omitted. | | `backoff` | `Partial` | Optional. Reconnect backoff tuning. | | `backpressure` | `Partial` | Optional. Backpressure thresholds and strategy. | | `auth` | `AuthProvider` | Optional. Pluggable auth provider (Clerk, Firebase, BetterAuth, Custom). | The constructor branches on three mutually exclusive modes: ### Local-only mode (default) When neither `serverUrl` nor `cluster` is supplied, the client uses `NullConnectionProvider`. Operations stay in memory and IndexedDB; no socket is opened. This is the default for offline demos, tests, and prototype apps. ```typescript const client = new TopGunClient({ storage: new IDBAdapter(), }); ``` ### Single-server mode Supply `serverUrl` to connect to one TopGun server over WebSocket. ```typescript const client = new TopGunClient({ serverUrl: 'ws://localhost:8080', storage: new IDBAdapter(), }); ``` ### Cluster mode Supply `cluster.seeds` (one or more seed URLs) for partition-aware routing across multiple nodes. ```typescript const client = new TopGunClient({ cluster: { seeds: [ 'ws://node1.example.com:8080', 'ws://node2.example.com:8080', 'ws://node3.example.com:8080', ], smartRouting: true, connectionsPerNode: 2, connectionTimeoutMs: 5000, }, storage: new IDBAdapter(), }); ``` `TopGunClusterConfig` fields: `seeds` (required), `connectionsPerNode` (default 1), `smartRouting` (default true), `partitionMapRefreshMs` (default 30000), `connectionTimeoutMs` (default 5000), `retryAttempts` (default 3). Supplying both `serverUrl` and `cluster` throws at construction. ### Advanced: HTTP-sync and auto-connection providers For environments without WebSockets (Cloudflare Workers, serverless, restrictive proxies), build a custom `SyncEngine` with `HttpSyncProvider` or `AutoConnectionProvider`. These are advanced and bypass the `TopGunClient` wrapper. ```typescript const hlc = new HLC('client-1'); const provider = new HttpSyncProvider({ url: 'https://your-api.example.com', clientId: 'client-1', hlc, authToken: 'your-jwt-token', syncMaps: ['todos'], pollIntervalMs: 5000, }); const engine = new SyncEngine({ nodeId: 'client-1', connectionProvider: provider, storageAdapter: new IDBAdapter(), }); ``` `AutoConnectionProvider` attempts WebSocket first, then falls back to HTTP polling. Same setup pattern. ## Core Methods ### `start()` ```typescript public async start(): Promise ``` Initializes the storage adapter (calls `storage.initialize('topgun_offline_db')`). For local-only mode this is optional — `IDBAdapter` initializes lazily on first read/write. Calling `start()` eagerly is useful when you want to surface storage errors before the UI renders. ### `getMap(name)` ```typescript getMap(name: K): LWWMap; getMap(name: string): LWWMap; ``` Returns an `LWWMap` (last-write-wins CRDT) for the given name. Creates the map on first call and restores its state from storage asynchronously. ```typescript const users = client.getMap('users'); users.set('u1', { name: 'Alice' }); const user = users.get('u1'); ``` ### `getORMap(name)` ```typescript getORMap(name: K): ORMap; getORMap(name: string): ORMap; ``` Returns an `ORMap` (observed-remove CRDT) for multi-value-per-key data. ```typescript const tags = client.getORMap('tags'); tags.add('post:123', 'javascript'); tags.add('post:123', 'typescript'); const postTags = tags.get('post:123'); // ['javascript', 'typescript'] ``` ### `query(mapName, filter)` ```typescript query(mapName: K, filter: QueryFilter): QueryHandle; query(mapName: string, filter: QueryFilter): QueryHandle; ``` Returns a live query subscription. The handle emits an initial result and delta updates. See [Search & live queries](/docs/guides/search-and-live-queries) for the canonical use-case-driven example. ```typescript const handle = client.query('todos', { where: { completed: false }, sort: { createdAt: 'desc' }, limit: 10, }); const unsubscribe = handle.subscribe((results) => { console.log('Results:', results); }); // Cursor pagination const { nextCursor, hasMore } = handle.getPaginationInfo(); if (hasMore && nextCursor) { const nextPage = client.query('todos', { where: { completed: false }, sort: { createdAt: 'desc' }, limit: 10, cursor: nextCursor, }); } ``` `QueryHandle` methods: `subscribe(cb)`, `onDelta(listener)`, `consumeChanges()`, `getLastChange()`, `getPendingChanges()`, `clearChanges()`, `resetChangeTracker()`, `getFilter()`, `getMapName()`, `getPaginationInfo()`, `onPaginationChange(listener)`, `updatePaginationInfo(info)`, `syncState` (getter), `onSyncStateChange(listener)`. ### `topic(name)` ```typescript public topic(name: string): TopicHandle ``` Returns a pub/sub topic for ephemeral fan-out messaging (not CRDT-persisted). See [Live notifications](/docs/guides/live-notifications) for the canonical hook-first pattern. ```typescript const chat = client.topic('chat-room'); chat.publish({ text: 'Hello!' }); const unsubscribe = chat.subscribe((msg) => { console.log(msg); }); ``` ### `getLock(name)` ```typescript public getLock(name: string): DistributedLock ``` Returns a distributed lock handle. See [Counters & locks](/docs/guides/counters-and-locks) for fencing-token semantics and single-node-vs-cluster caveats. ```typescript const lock = client.getLock('resource-A'); if (await lock.lock(10000)) { // Critical section await lock.unlock(); } ``` `DistributedLock` methods: `lock(ttl?: number)`, `unlock()`, `isLocked()`. ### `getPNCounter(name)` ```typescript public getPNCounter(name: string): PNCounterHandle ``` Returns a PN-Counter (positive-negative) for offline-capable increment/decrement. See [Counters & locks](/docs/guides/counters-and-locks) for a canonical example. ```typescript const likes = client.getPNCounter('likes:post-123'); likes.increment(); likes.decrement(); likes.addAndGet(10); likes.subscribe((value) => { console.log('Current likes:', value); }); ``` ### Entry processors — planned (v2.x) Server-side atomic read-modify-write via user-defined functions (`client.executeOnKey`, `client.executeOnKeys`, `BuiltInProcessors`) requires a WASM sandbox on the v2.x roadmap. The SDK surface throws an explanatory error pre-launch — see [/docs/roadmap](/docs/roadmap). ### `close()` ```typescript public async close(): Promise ``` Tears down the client. Awaits cluster reconnect-timer cleanup so the host process does not leak `setTimeout` handles. ## Search and SQL ### `search(mapName, query, options?)` ```typescript public async search( mapName: string, query: string, options?: { limit?: number; minScore?: number; boost?: Record } ): Promise> ``` One-shot BM25 full-text search. Requires FTS enabled for the map on the server. ```typescript const results = await client.search

('articles', 'machine learning', { limit: 20, minScore: 0.5, boost: { title: 2.0, body: 1.0 }, }); ``` ### `searchSubscribe(mapName, query, options?)` ```typescript public searchSubscribe( mapName: string, query: string, options?: SearchOptions ): SearchHandle ``` Live BM25 subscription. The handle receives ENTER/UPDATE/LEAVE deltas as documents change. ```typescript const handle = client.searchSubscribe

('articles', 'machine learning', { limit: 20, minScore: 0.5, }); const unsubscribe = handle.subscribe((results) => setResults(results)); handle.dispose(); ``` ### `sql(query)` ```typescript public async sql(query: string): Promise ``` Execute a SQL query server-side via DataFusion. Map names are table names. Requires the server's DataFusion feature and registered schemas. ```typescript const result = await client.sql('SELECT name, age FROM users WHERE age > 21 ORDER BY age'); // result.columns: ['name', 'age'] // result.rows: [[...], [...]] ``` ### `vectorSearch(mapName, queryVector, options?)` ```typescript public async vectorSearch( mapName: string, queryVector: Float32Array | number[], options?: VectorSearchClientOptions ): Promise ``` ANN search against the HNSW vector index. Query vector serializes as little-endian f32 bytes. ```typescript const results = await client.vectorSearch('notes', new Float32Array([0.1, 0.2, 0.3]), { k: 5 }); ``` ### `hybridSearch(mapName, queryText, options?)` ```typescript public async hybridSearch( mapName: string, queryText: string, options?: HybridSearchClientOptions ): Promise ``` Tri-hybrid search combining exact match, full-text, and semantic vector results via Reciprocal Rank Fusion. ### `hybridSearchSubscribe(mapName, queryText, options?)` ```typescript public hybridSearchSubscribe( mapName: string, queryText: string, options?: HybridSearchSubscribeOptions ): HybridSearchHandle ``` Live tri-hybrid search subscription. ### `hybridQuery(mapName, filter?)` ```typescript public hybridQuery(mapName: string, filter: HybridQueryFilter = {}): HybridQueryHandle ``` Combine FTS predicates with traditional filter predicates in a single query. Results include `_score` for FTS ranking. ```typescript const handle = client.hybridQuery

('articles', { predicate: Predicates.and( Predicates.match('body', 'machine learning'), Predicates.equal('category', 'tech') ), sort: { _score: 'desc' }, limit: 20, }); ``` ## Connection State ### `getConnectionState()` ```typescript public getConnectionState(): SyncState ``` Returns the current state from the connection state machine (e.g., `OFFLINE`, `CONNECTING`, `AUTHENTICATING`, `READY`). ### `onConnectionStateChange(listener)` ```typescript public onConnectionStateChange(listener: (event: StateChangeEvent) => void): () => void ``` Subscribe to state transitions. Returns an unsubscribe function. ```typescript const unsubscribe = client.onConnectionStateChange((event) => { console.log(`State: ${event.from} -> ${event.to}`); }); ``` ### `getStateHistory(limit?)` ```typescript public getStateHistory(limit?: number): StateChangeEvent[] ``` Returns the ring-buffered state-change history (useful for debugging reconnect storms). ### `resetConnection()` ```typescript public resetConnection(): void ``` Reset the connection and state machine. Use after fatal errors to start fresh. ## Backpressure ### `getPendingOpsCount()` ```typescript public getPendingOpsCount(): number ``` Number of unacknowledged operations waiting for server ack. ### `getBackpressureStatus()` ```typescript public getBackpressureStatus(): BackpressureStatus ``` Snapshot: `{ pending, maxPending, strategy, paused, droppedCount }`. ### `isBackpressurePaused()` ```typescript public isBackpressurePaused(): boolean ``` True when the writer is currently paused under the pause strategy. ### `onBackpressure(event, listener)` ```typescript public onBackpressure( event: 'backpressure:high' | 'backpressure:low' | 'backpressure:paused' | 'backpressure:resumed' | 'operation:dropped', listener: (data?: BackpressureThresholdEvent | OperationDroppedEvent) => void ): () => void ``` Subscribe to backpressure transitions. ```typescript client.onBackpressure('backpressure:high', ({ pending, max }) => { console.warn(`Warning: ${pending}/${max} pending ops`); }); client.onBackpressure('backpressure:paused', () => showLoadingSpinner()); client.onBackpressure('backpressure:resumed', () => hideLoadingSpinner()); ``` ## Event Journal ### `getEventJournal()` ```typescript public getEventJournal(): EventJournalReader ``` Returns the journal reader for subscribing to and replaying map-change events (audit trail, undo history, change-feed consumers). ```typescript const journal = client.getEventJournal(); const unsubscribe = journal.subscribe((event) => { console.log(`${event.type} on ${event.mapName}:${event.key}`); }); // Filtered subscription journal.subscribe( (event) => console.log('User changed:', event.key), { mapName: 'users' } ); // Historical replay const events = await journal.readFrom(0n, 100); ``` `EventJournalReader` methods: `readFrom(sequence, limit)`, `readMapEvents(...)`, `getLatestSequence()`, `subscribe(listener, options?)`. ## Conflict Resolvers ### `getConflictResolvers()` ```typescript public getConflictResolvers(): ConflictResolverClient ``` Observe merge rejections (the built-in CRDT merge logic rejected a remote change). The returned client's `register` / `unregister` / `list` methods throw — registering custom server-side resolvers requires a WASM sandbox on the v2.x roadmap, see [/docs/roadmap](/docs/roadmap). ```typescript const resolvers = client.getConflictResolvers(); resolvers.onRejection((rejection) => { console.log(`Merge rejected: ${rejection.reason}`); }); ``` ## Per-Record Sync State ### `getRecordSyncStateTracker()` ```typescript public getRecordSyncStateTracker(): RecordSyncStateTracker ``` The tracker projects op-log mutations, connection state, and merge rejections into a four-state tag per `(mapName, key)`. Used by React hooks (`useSyncState`, the `*WithSyncState` companions) and by advanced consumers reading sync state outside a query context. ## Cluster Mode API ### `isCluster()` ```typescript public isCluster(): boolean ``` True when the client was constructed with `cluster` config. ### `getConnectedNodes()` ```typescript public getConnectedNodes(): string[] ``` List of currently connected node IDs (cluster mode); empty array otherwise. ### `getPartitionMapVersion()` ```typescript public getPartitionMapVersion(): number ``` Current partition-map version; 0 in single-server mode. ### `isRoutingActive()` ```typescript public isRoutingActive(): boolean ``` True when direct routing to partition owners is active. ### `getClusterHealth()` ```typescript public getClusterHealth(): Map ``` Per-node health map. ### `refreshPartitionMap()` ```typescript public async refreshPartitionMap(): Promise ``` Force a partition-map refresh. Useful after detecting routing errors. ### `getClusterStats()` ```typescript public getClusterStats(): { mapVersion: number; partitionCount: number; nodeCount: number; lastRefresh: number; isStale: boolean } | null ``` Router statistics snapshot. ## Authentication ### `setAuthToken(token)` ```typescript public setAuthToken(token: string): void ``` Set a static JWT for the next sync handshake. ```typescript client.setAuthToken('jwt-token-here'); ``` ### `setAuthTokenProvider(provider)` ```typescript public setAuthTokenProvider(provider: () => Promise): void ``` Provider is called on each reconnection — refresh tokens land here. ```typescript client.setAuthTokenProvider(async () => { const token = await refreshToken(); return token; }); ``` For Clerk/Firebase/BetterAuth/Custom, prefer the `auth` constructor option with a pluggable `AuthProvider` instead of calling these methods directly. --- [← Reference Overview](/docs/reference) · [Core →](/docs/reference/core) --- # React > Reference for @topgunbuild/react — hooks for building reactive TopGun apps.

React

`@topgunbuild/react` ships hooks that wrap the imperative `TopGunClient` API. Every hook below resolves the client through `` — that provider is the one required ancestor. For the imperative surface these hooks call into, see the [Client Reference](/docs/reference/client). ## Setup ### `TopGunProvider` Required React context provider. Wrap your app once at the root. ```tsx const client = new TopGunClient({ storage: new IDBAdapter(), }); export function App() { return ( ); } ``` ### `useClient` Escape hatch returning the underlying `TopGunClient`. Use this for imperative operations (calling `client.getEventJournal`, `client.topic`, etc.) inside event handlers and effects. ```tsx function ResetButton() { const client = useClient(); return ; } ``` Throws if used outside ``. ## Reactive Data Hooks ### `useQuery` Live query subscription. Returns `data`, `loading`, `error`, change-tracking fields, pagination info, and per-record sync state. See [Search & live queries](/docs/guides/search-and-live-queries) for canonical examples. ```tsx interface Todo { text: string; done: boolean } function TodoList() { const { data, loading, error } = useQuery('todos', { where: { done: false }, sort: { createdAt: 'desc' }, limit: 10, }); if (loading) return

Loading…

; if (error) return

Error: {error.message}

; return (

{item.text}

); } ``` Signature: ```typescript function useQuery( mapName: string, query?: QueryFilter, options?: UseQueryOptions ): UseQueryResult ``` `UseQueryOptions` (all optional): | Field | Description | |---|---| | `onChange` | Called for any change event with the `ChangeEvent`. | | `onAdd` | Called when an item is added: `(key, value)`. | | `onUpdate` | Called when an item is updated: `(key, value, previous)`. | | `onRemove` | Called when an item is removed: `(key, previous)`. | | `maxChanges` | Cap on accumulated `changes[]`. Default 1000. | `UseQueryResult` fields: | Field | Description | |---|---| | `data` | `QueryResultItem[]` — current rows; each item carries `_key`. | | `loading` | True until first result arrives. | | `error` | `Error \| null`. | | `lastChange` | Most recent `ChangeEvent` (or `null`). | | `changes` | All `ChangeEvent` since the last `clearChanges()`. | | `clearChanges` | Resets `changes` and `lastChange`. | | `nextCursor` / `hasMore` / `cursorStatus` | Pagination state. | | `syncState` | `ReadonlyMap` keyed by `_key`. | Pagination example: ```tsx const [cursor, setCursor] = useState(); const { data, nextCursor, hasMore } = useQuery('todos', { sort: { createdAt: 'desc' }, limit: 20, cursor, }); // {hasMore && } ``` ### `useMutation` Imperative write helper. Returns `{ create, update, remove, map }`. ```tsx function AddTodo() { const { create } = useMutation('todos'); return ( ); } ``` Signature: ```typescript function useMutation(mapName: string): UseMutationResult ``` `UseMutationResult`: | Field | Type | Description | |---|---|---| | `create` | `(key: K, value: T) => void` | Write a new entry. | | `update` | `(key: K, value: T) => void` | Overwrite an entry. (Same semantics as `create` under LWW.) | | `remove` | `(key: K) => void` | Delete (tombstone) an entry. | | `map` | `LWWMap` | Underlying map instance for advanced consumers. | ### `useMap` Lower-level escape hatch returning the raw `LWWMap` instance for the named map. Useful when you need direct access to `merge`, `prune`, or `subscribe` — but for most UI code, `useQuery`/`useMutation` is the right choice. ```typescript function useMap(mapName: string): LWWMap ``` A companion `useMapWithSyncState` variant exposes per-record sync state alongside the map. ### `useORMap` Same shape as `useMap` but returns the `ORMap` for multi-value-per-key data. ```typescript function useORMap(mapName: string): ORMap ``` Companion: `useORMapWithSyncState`. ## Sync State ### `useSyncState` Returns the current `RecordSyncState` for a `(mapName, key)` pair. The state is one of `synced`, `pending`, `conflict`, or `offline`. Re-renders only when *that* key's state changes. See [Offline-first apps](/docs/guides/offline-first) for the canonical reconnect-and-merge pattern. ```tsx function SyncBadge({ id }: { id: string }) { const state = useSyncState('todos', id); return {state}; } ``` ```typescript function useSyncState(mapName: string, key: string): RecordSyncState ``` ## Pub/Sub ### `useTopic` Subscribe to (and publish on) an ephemeral pub/sub topic. See [Live notifications](/docs/guides/live-notifications) for canonical examples. ```tsx function ChatLog() { const [messages, setMessages] = useState([]); const topic = useTopic('chat-room', (msg) => { setMessages(prev => [...prev, msg as string]); }); return ( <>

); } ``` ```typescript function useTopic(topicName: string, callback?: TopicCallback): TopicHandle ``` ## Counters ### `usePNCounter` PN-Counter handle with reactive value. ```tsx function LikeButton() { const { value, increment } = usePNCounter('likes:post-123'); return ; } ``` ```typescript function usePNCounter(name: string): UsePNCounterResult ``` `UsePNCounterResult` exposes `value` plus `increment`, `decrement`, and `addAndGet` callbacks. ## Server-Side Logic ### `useEventJournal` Subscribe to the journal of map-change events. Useful for audit trails, activity feeds, undo stacks. ```typescript function useEventJournal( options?: { mapName?: string; types?: JournalEventType[]; limit?: number } ): { events: JournalEvent[]; loading: boolean; error: Error | null } ``` ## Conflict Resolvers ### `useMergeRejections` Surface merge rejections (the built-in CRDT merge logic rejected a remote change). Useful for telling the user "your edit conflicted". ```typescript function useMergeRejections( options?: { mapName?: string; key?: string } ): MergeRejection[] ``` > Custom user-defined resolvers (`useConflictResolver`, `client.executeOnKey`, server-side entry processors) require a WASM sandbox on the v2.x roadmap. See [/docs/roadmap](/docs/roadmap). The SDK surface for those features was removed pre-launch to avoid runtime errors. ## Search ### `useSearch` Live BM25 full-text search. Re-runs when `query` changes. ```tsx function ArticleSearch() { const [q, setQ] = useState(''); const { results, loading } = useSearch

('articles', q, { limit: 20, minScore: 0.5, }); return ( <> setQ(e.target.value)} /> {loading ?

…

: results.map(r => (

{r.value.title} ({r.score.toFixed(2)})

))} ); } ``` ```typescript function useSearch( mapName: string, query: string, options?: SearchOptions, ): { results: SearchResult[]; loading: boolean; error: Error | null } ``` ### `useHybridQuery` Combine FTS predicates with traditional filter predicates (`where`/`sort`/`limit`/`cursor`) in one query. Results include `_score` for FTS ranking. ```tsx const { data } = useHybridQuery

('articles', { predicate: Predicates.and( Predicates.match('body', 'machine learning'), Predicates.equal('category', 'tech') ), sort: { _score: 'desc' }, limit: 20, }); ``` ```typescript function useHybridQuery( mapName: string, filter?: HybridQueryFilter, ): { data: HybridResultItem[]; loading: boolean; error: Error | null; nextCursor?: string; hasMore: boolean } ``` ### `useVectorSearch` ANN vector search via the HNSW index. ```typescript function useVectorSearch( mapName: string, queryVector: Float32Array | number[] | null, options?: VectorSearchClientOptions, ): { results: VectorSearchClientResult[]; loading: boolean; error: Error | null } ``` Passing `null` as the vector pauses the search (useful while the user is still typing). ### `useHybridSearch` Tri-hybrid search (exact + full-text + semantic, fused via Reciprocal Rank Fusion). ```typescript function useHybridSearch( mapName: string, queryText: string, options?: HybridSearchClientOptions, ): { results: HybridSearchClientResult[]; loading: boolean; error: Error | null } ``` ### `useHybridSearchSubscribe` Live tri-hybrid search subscription with ENTER/UPDATE/LEAVE deltas. Pair with optimistic UI for animated results. ```typescript function useHybridSearchSubscribe( mapName: string, queryText: string, options?: HybridSearchSubscribeOptions, ): { results: HybridSearchHandleResult[]; loading: boolean; error: Error | null } ``` --- [← Core](/docs/reference/core) · [Adapters →](/docs/reference/adapters) --- # Core > Reference for @topgunbuild/core — LWWMap, ORMap, HLC, and MerkleTree.

Core

`@topgunbuild/core` ships the CRDT primitives, Hybrid Logical Clock, and Merkle tree that the client and server share. This page documents the public surface (the "what / how"). For background on why TopGun picks these primitives over alternatives, see [Concepts → Data Structures](/docs/concepts/data-structures). The two primary data structures are `LWWMap` (last-write-wins) and `ORMap` (observed-remove). Both are exposed on `TopGunClient` via `getMap()` and `getORMap()` — most application code never instantiates them directly. ## LWWMap ```typescript const hlc = new HLC('node-1'); const map = new LWWMap(hlc); ``` Last-write-wins semantics: each key holds exactly one value. Concurrent writes from different nodes are resolved by HLC timestamp (highest wins, ties broken by `nodeId`). ### Constructor ```typescript new LWWMap(hlc: HLC) ``` ### Methods **`set(key, value, ttlMs?)`** — `LWWRecord` Write a value. Stamps the record with `hlc.now()`. Optional `ttlMs` for time-bounded entries. ```typescript const record = map.set('u1', { name: 'Alice', email: 'alice@example.com' }); // { value: {...}, timestamp: { millis, counter, nodeId } } // With 1-hour TTL map.set('session-123', sessionData, 3600000); ``` **`get(key)`** — `V | undefined` Read a value. Returns `undefined` for deleted or expired keys. **`getRecord(key)`** — `LWWRecord | undefined` Read the full record (value, timestamp, optional TTL). **`remove(key)`** — `LWWRecord` Delete a key by writing a tombstone (`value: null`). Returns the tombstone record. **`merge(key, remoteRecord)`** — `boolean` Merge a remote record. Returns `true` if local state was updated (i.e., the remote record's timestamp dominated). ```typescript const remote: LWWRecord = { value: { name: 'Bob' }, timestamp: { millis: Date.now(), counter: 0, nodeId: 'node-2' }, }; const updated = map.merge('u1', remote); ``` **`subscribe(callback)`** — `() => void` Subscribe to map-change notifications. The callback receives `entries: Array<[K, V]>`. Returns an unsubscribe function. ```typescript const unsubscribe = map.subscribe((entries) => { console.log('Map changed,', entries.length, 'live entries'); }); ``` **`entries()`** — `IterableIterator<[K, V]>` Iterate non-tombstoned entries (drops deleted and expired). **`allKeys()`** — `IterableIterator` Iterate every key including tombstones. **`size`** (getter) — `number` Count of entries including tombstones. **`prune(olderThan)`** — `K[]` Drop tombstones older than the given `Timestamp`. Returns the removed keys. **`clear()`** — `void` Reset to empty state. **`getMerkleTree()`** — `MerkleTree` Access the underlying Merkle tree for delta-sync diffing. ### LWWRecord shape ```typescript interface LWWRecord { value: V | null; // null indicates tombstone timestamp: Timestamp; // HLC stamp ttlMs?: number; // optional TTL } ``` ## ORMap ```typescript const hlc = new HLC('node-1'); const map = new ORMap(hlc); ``` Observed-remove semantics: each key holds a *set* of values. Concurrent adds preserve every value (tagged with unique IDs). A remove operation tombstones only the tags it observed locally, so concurrent add-vs-remove resolves correctly (no spurious deletes). Use this for tag clouds, comment threads, multi-select fields, presence rosters — anywhere two clients can legitimately contribute different values to the same key. ### Constructor ```typescript new ORMap(hlc: HLC) ``` ### Methods **`add(key, value, ttlMs?)`** — `ORMapRecord` Add a value under a key. Generates a unique tag. Returns the record. ```typescript const tags = new ORMap(hlc); tags.add('post:123', 'javascript'); tags.add('post:123', 'typescript'); // post:123 -> ['javascript', 'typescript'] ``` **`remove(key, value)`** — `string[]` Remove a specific value under a key. Returns the tombstone tags created. **`get(key)`** — `V[]` Read all live values for a key. ```typescript const postTags = tags.get('post:123'); // ['javascript', 'typescript'] ``` **`getRecords(key)`** — `ORMapRecord[]` Read full records (value + tag + timestamp) for a key. **`getTombstones()`** — `string[]` Read all current tombstone tags. **`apply(key, record)`** — `boolean` Apply a remote `ORMapRecord` to local state. Returns `true` if state changed. **`applyTombstone(tag)`** — `void` Apply a remote tombstone tag. **`merge(other)`** — `void` Merge another `ORMap` of the same key/value types in bulk. **`subscribe(callback)`** — `() => void` Subscribe to change events. The callback receives `entries: Array<[K, V[]]>`. **`allKeys()`** — `K[]` All keys with at least one live or tombstoned value. **`size`** / **`totalRecords`** (getters) — `number` `size` counts distinct keys; `totalRecords` counts every tagged record (including duplicates per key). **`prune(olderThan)`** — `string[]` Drop tombstones older than the timestamp. Returns dropped tags. **`clear()`** — `void` Reset to empty. **`getMerkleTree()`** — `ORMapMerkleTree` Underlying Merkle tree (a different shape than LWWMap's tree because ORMap stores multi-value-per-key). **`getSnapshot()`** — `ORMapSnapshot` Serializable snapshot for persistence. **`isTombstoned(tag)`** — `boolean` Check whether a tag is in the tombstone set. ### ORMapRecord shape ```typescript interface ORMapRecord { value: V; tag: string; // unique add ID timestamp: Timestamp; // HLC stamp ttlMs?: number; } ``` ## HLC (Hybrid Logical Clock) ```typescript const hlc = new HLC('node-1'); const ts = hlc.now(); // { millis: 1748025600000, counter: 0, nodeId: 'node-1' } ``` The HLC combines physical wall-clock time (`millis`) with a logical counter (`counter`) so total ordering is preserved across nodes even when clocks drift. ### Constructor ```typescript new HLC(nodeId: string, options?: HLCOptions) ``` `HLCOptions` fields: | Field | Default | Description | |---|---|---| | `strictMode` | `false` | Throw on clock drift exceeding `maxDriftMs`. | | `maxDriftMs` | `60000` | Permitted drift threshold (ms). | | `clockSource` | wall clock | Custom `ClockSource` for deterministic tests. | ### Methods **`now()`** — `Timestamp` Issue a fresh timestamp. Monotonic per node. **`update(remote)`** — `void` Update the local clock against a received remote timestamp. Bumps `lastMillis`/`lastCounter` as needed to maintain causal ordering. **`getClockSource()`** — `ClockSource` Returns the configured clock source. **`getNodeId`** / **`getStrictMode`** / **`getMaxDriftMs`** (getters) Inspect configured fields. ### Static helpers **`HLC.compare(a, b)`** — `number` Total-order comparator. Returns negative if `a < b`, zero if equal, positive if `a > b`. Ordered by `millis`, then `counter`, then `nodeId`. **`HLC.toString(ts)`** — `string` Canonical string encoding for serialization or sort keys. **`HLC.parse(str)`** — `Timestamp` Inverse of `toString`. ### Timestamp shape ```typescript interface Timestamp { millis: number; counter: number; nodeId: string; } ``` ## MerkleTree ```typescript const tree = new MerkleTree(); ``` The Merkle tree powers delta sync: clients and servers compare hash trees and exchange only differing buckets instead of full state. `LWWMap` and `ORMap` maintain their own trees internally — use this directly only when implementing custom sync providers or diagnostics. ### Constructor ```typescript new MerkleTree(records?: Map>, depth = 3) ``` `depth` controls fan-out (default 3 levels deep). ### Methods **`update(key, record)`** — `void` Insert or replace the leaf for `key` and rehash the path to the root. **`remove(key)`** — `void` Drop the leaf and rehash. **`getRootHash()`** — `number` Top-level hash. Two trees with identical content produce the same root. **`getNode(path)`** — `MerkleNode | undefined` Return the node at a given path string (used during diff walks). **`getBuckets(path)`** — `Record` Per-bucket hashes for the children of the node at `path`. **`getKeysInBucket(path)`** — `string[]` Leaf keys grouped under the given path. ## Re-exports `@topgunbuild/core` also re-exports types and helpers consumed across the stack. Highlights: - **`Predicates`** — composable filter builders (`equal`, `gt`, `lt`, `contains`, `and`, `or`, `not`, `match`, `matchPhrase`, `matchPrefix`). Used by `client.query`, `client.hybridQuery`, and the React hooks. - **`SearchOptions`** — shared FTS options shape used by `client.search`/`searchSubscribe` and `useSearch`. - **`MergeRejection`** — event shape emitted when the built-in CRDT merge logic rejects a remote change. Observed via `useMergeRejections` (React) or `client.getConflictResolvers().onRejection()`. - **`WriteConcern`** / **`ConsistencyLevel`** — durability and consistency knobs for cluster writes. - **`IndexedLWWMap`** / **`IndexedORMap`** — indexed variants used by the server's query engine. - **Full-Text Search** — `Tokenizer`, `InvertedIndex`, `BM25Scorer`, `FullTextIndex` for embedding FTS directly. - **Deterministic Simulation Testing** — `VirtualClock`, `SeededRNG`, `VirtualNetwork`, `InvariantChecker`, `ScenarioRunner` for property-based distributed tests. The complete re-export list lives in `packages/core/src/index.ts`. --- [← Client](/docs/reference/client) · [React →](/docs/reference/react) --- # Comparison > How TopGun compares to other solutions in the ecosystem. Docs Get Started Comparison # Comparison How TopGun compares to other solutions in the ecosystem. {/* TopGun claims sourced from packages/core/src/, packages/client/src/, packages/server-rust/src/ — verified 2026-05-21 */} {/* Firebase claims sourced from https://firebase.google.com/docs/firestore — verified 2026-05-21 */} {/* Supabase Realtime claims sourced from https://supabase.com/docs/guides/realtime — verified 2026-05-21 */} {/* Yjs claims sourced from https://github.com/yjs/yjs — verified 2026-05-21 */} {/* RxDB claims sourced from https://rxdb.info/replication.html — verified 2026-05-21 */} {/* Replicache claims sourced from https://doc.replicache.dev/ — verified 2026-05-21 */} {/* InstantDB claims sourced from https://www.instantdb.com/docs and https://github.com/instantdb/instant — verified 2026-05-21 */}

Feature	TopGun	Firebase	Supabase Realtime	Yjs	RxDB	Replicache	InstantDB
Primary Model	Local-First CRDT grid	Cloud Doc DB	Postgres pub/sub	Collaborative CRDT framework	Local-First DB	Client-auth sync	Local-first graph DB
Offline Support	First-Class	Good	Limited	Excellent	Excellent	Good	First-Class
Latency	~0ms (in-memory)	Network-dependent	Network-dependent	~0ms (in-memory)	~5–10ms (IndexedDB)	~0ms local / server-validated	~0ms (in-memory)
Backend Control	Self-host (Apache-2.0)	Proprietary	Self-host or Supabase Cloud	BYO transport / provider	CouchDB / Custom	Self-host or Replicache Cloud	InstantDB Cloud (self-host community)
Consistency	HLC + CRDT	Server-authoritative LWW	Server Authority	CRDT (Y-types)	Revision Trees	Server Authority	Server-authoritative with optimistic UI
Distributed Locks	Fencing Tokens (single-node stable; cluster Raft: in progress)	Not Supported	Not Supported	Not Supported	Not Supported	Not Supported	Not Supported
License	Apache-2.0	Proprietary	Apache-2.0	MIT	Apache-2.0 / Proprietary (Premium)	Apache-2.0	MIT (client) + proprietary cloud

View Roadmap: distributed primitives maturity levels ## Why TopGun?

vs Firebase:
TopGun gives you ownership of your data. Run it on your own cloud, use your own backend, and never get locked into a proprietary platform.
vs Supabase Realtime:
Supabase Realtime is Postgres pub/sub — great for server-driven events, but not designed for offline-first local writes. TopGun persists data locally in IndexedDB and syncs seamlessly when the network returns.
vs Yjs:
Yjs is an excellent CRDT framework for collaborative text editing but requires you to bring your own transport, persistence, and server. TopGun ships with a full server, IndexedDB persistence, and a React SDK out of the box.
vs RxDB:
RxDB is a mature local-first database with good offline support, but its writes go through IndexedDB (5–10ms). TopGun operates entirely in-memory for zero-latency reads/writes, with async write-behind to the configured backend.
vs Replicache:
TopGun uses CRDTs for automatic conflict resolution — mutations apply locally first and merge deterministically. Replicache is server-authoritative: mutations queue and the server validates them. Related: Zero (also from Rocicorp) offers a similar server-authoritative model with a managed cloud option. Both Replicache and TopGun are Apache-2.0 open source.
vs InstantDB:
InstantDB is a local-first graph database with an excellent developer experience. It currently runs on InstantDB Cloud (community-led self-hosting available via the open-source repo). TopGun is fully self-hostable under Apache-2.0 with no cloud dependency.

Previous Introduction Next Section Installation --- # For Coding Agents > TopGun cheatsheet for LLM coding assistants — schema-typed minimal code, structured headings, optimized for context-window ingestion. ## What TopGun is Local-first reactive data layer; CRDT-merged writes; WebSocket sync to a Rust server (single-node stable). ## Install ```bash pnpm add @topgunbuild/client @topgunbuild/react @topgunbuild/adapters ``` ## Canonical app shape (React) ```tsx // main.tsx const client = new TopGunClient({ serverUrl: 'ws://localhost:8080', storage: new IDBAdapter(), }); client.start(); // non-await: lazy init, do NOT await function App() { return ( ); } ``` ## Canonical writes ```tsx // useMutation('mapName') returns { create, update, remove } // record._key is the unique identifier on every record const { create, update, remove } = useMutation('todos'); create(crypto.randomUUID(), { title: 'Buy milk', done: false }); update(existingKey, { done: true }); remove(existingKey); ``` ## Canonical queries ```tsx // useQuery('mapName') returns { data: T[] } const { data: todos } = useQuery('todos'); // With predicates: const { data: open } = useQuery('todos', { predicate: Predicates.equal('done', false), }); // Also: Predicates.isIn(), Predicates.greaterThan() ``` ## Local-only mode ```tsx // Omit serverUrl to run fully local — no server needed const client = new TopGunClient({ storage: new IDBAdapter(), }); ``` ## Add real-time sync ```bash pnpm start:server # embedded redb backend, zero-config ``` ```tsx const client = new TopGunClient({ serverUrl: 'ws://localhost:8080', storage: new IDBAdapter(), }); ``` ## Topic-based pub/sub ```tsx // useTopic returns a TopicHandle. Pass a callback to receive messages; // publish via the returned handle. const [messages, setMessages] = useState>([]); const topic = useTopic<{ text: string }>('chat', (msg) => setMessages((prev) => [...prev, msg]), ); topic.publish({ text: 'hello' }); ``` ## Auth ```tsx // client.setAuthToken(jwt) after sign-in // TopGun does NOT issue JWTs — use your own auth provider const jwt = await myAuthServer.signIn(email, password); client.setAuthToken(jwt); ``` ## Common pitfalls - Do NOT `await client.start()` — lazy init; calling `await` is incorrect - Use `record._key` (not `record.id`) to identify records in mutation callbacks - `useMutation` requires the generic param `` for type-safety: `useMutation('todos')` - IndexedDB only persists when `IDBAdapter` is wired in `new TopGunClient({ storage: new IDBAdapter() })` ## Cross-reference Full bundle: `/llms-full.txt`. Source: `https://github.com/TopGunBuild/topgun`.

Non-Blocking Initialization

Persistence

Optional: Encrypt Local Storage

Building with an AI Agent?

Package Manager

Core Initialization

Server Development

Data Flow

Why is this important?

Clock Drift Tolerance

Traditional REST/GraphQL

TopGun Sync

The Exchange Process

The HTTP Sync Exchange

1. Gateway Node

2. Partition Engine

3. Persistence Layer

4. Pub/Sub Bus

LWW-Map Tombstones

OR-Map Tombstones

Client API

React

Core