@topgunbuild/client 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,367 @@
+import { LWWRecord, ORMapRecord, PredicateNode, LWWMap, ORMap, Timestamp, HLC } from '@topgunbuild/core';
+export { LWWMap, LWWRecord, PredicateNode, Predicates } from '@topgunbuild/core';
+import pino from 'pino';
+
+interface OpLogEntry {
+    id?: number;
+    key: string;
+    op: 'PUT' | 'REMOVE' | 'OR_ADD' | 'OR_REMOVE';
+    value?: any;
+    record?: LWWRecord<any>;
+    orRecord?: ORMapRecord<any>;
+    orTag?: string;
+    hlc?: string;
+    timestamp?: any;
+    synced: number;
+    mapName: string;
+}
+interface IStorageAdapter {
+    initialize(dbName: string): Promise<void>;
+    close(): Promise<void>;
+    /**
+     * Waits for the storage adapter to be fully initialized.
+     * Optional - adapters that initialize synchronously may return immediately.
+     */
+    waitForReady?(): Promise<void>;
+    get<V>(key: string): Promise<LWWRecord<V> | ORMapRecord<V>[] | any | undefined>;
+    put(key: string, value: any): Promise<void>;
+    remove(key: string): Promise<void>;
+    getMeta(key: string): Promise<any>;
+    setMeta(key: string, value: any): Promise<void>;
+    batchPut(entries: Map<string, any>): Promise<void>;
+    appendOpLog(entry: Omit<OpLogEntry, 'id'>): Promise<number>;
+    getPendingOps(): Promise<OpLogEntry[]>;
+    markOpsSynced(lastId: number): Promise<void>;
+    getAllKeys(): Promise<string[]>;
+}
+
+interface QueryFilter {
+    where?: Record<string, any>;
+    predicate?: PredicateNode;
+    sort?: Record<string, 'asc' | 'desc'>;
+    limit?: number;
+    offset?: number;
+}
+/** Source of query results for proper handling of race conditions */
+type QueryResultSource = 'local' | 'server';
+/** Result item with _key field for client-side lookups */
+type QueryResultItem<T> = T & {
+    _key: string;
+};
+declare class QueryHandle<T> {
+    readonly id: string;
+    private syncEngine;
+    private mapName;
+    private filter;
+    private listeners;
+    private currentResults;
+    constructor(syncEngine: SyncEngine, mapName: string, filter?: QueryFilter);
+    subscribe(callback: (results: QueryResultItem<T>[]) => void): () => void;
+    private loadInitialLocalData;
+    private hasReceivedServerData;
+    /**
+     * Called by SyncEngine when server sends initial results or by local storage load.
+     * Uses merge strategy instead of clear to prevent UI flickering.
+     *
+     * @param items - Array of key-value pairs
+     * @param source - 'local' for IndexedDB data, 'server' for QUERY_RESP from server
+     *
+     * Race condition protection:
+     * - Empty server responses are ignored until we receive non-empty server data
+     * - This prevents clearing local data when server hasn't loaded from storage yet
+     * - Works with any async storage adapter (PostgreSQL, SQLite, Redis, etc.)
+     */
+    onResult(items: {
+        key: string;
+        value: T;
+    }[], source?: QueryResultSource): void;
+    /**
+     * Called by SyncEngine when server sends a live update
+     */
+    onUpdate(key: string, value: T | null): void;
+    private notify;
+    private getSortedResults;
+    getFilter(): QueryFilter;
+    getMapName(): string;
+}
+
+type TopicCallback = (data: any, context: {
+    timestamp: number;
+    publisherId?: string;
+}) => void;
+declare class TopicHandle {
+    private engine;
+    private topic;
+    private listeners;
+    constructor(engine: SyncEngine, topic: string);
+    get id(): string;
+    /**
+     * Publish a message to the topic
+     */
+    publish(data: any): void;
+    /**
+     * Subscribe to the topic
+     */
+    subscribe(callback: TopicCallback): () => void;
+    private unsubscribe;
+    /**
+     * Called by SyncEngine when a message is received
+     */
+    onMessage(data: any, context: {
+        timestamp: number;
+        publisherId?: string;
+    }): void;
+}
+
+interface SyncEngineConfig {
+    nodeId: string;
+    serverUrl: string;
+    storageAdapter: IStorageAdapter;
+    reconnectInterval?: number;
+}
+declare class SyncEngine {
+    private readonly nodeId;
+    private readonly serverUrl;
+    private readonly storageAdapter;
+    private readonly reconnectInterval;
+    private readonly hlc;
+    private websocket;
+    private isOnline;
+    private isAuthenticated;
+    private opLog;
+    private maps;
+    private queries;
+    private topics;
+    private pendingLockRequests;
+    private lastSyncTimestamp;
+    private reconnectTimer;
+    private authToken;
+    private tokenProvider;
+    constructor(config: SyncEngineConfig);
+    private initConnection;
+    private scheduleReconnect;
+    private loadOpLog;
+    private saveOpLog;
+    registerMap(mapName: string, map: LWWMap<any, any> | ORMap<any, any>): void;
+    recordOperation(mapName: string, opType: 'PUT' | 'REMOVE' | 'OR_ADD' | 'OR_REMOVE', key: string, data: {
+        record?: LWWRecord<any>;
+        orRecord?: ORMapRecord<any>;
+        orTag?: string;
+        timestamp: Timestamp;
+    }): Promise<void>;
+    private syncPendingOperations;
+    private startMerkleSync;
+    setAuthToken(token: string): void;
+    setTokenProvider(provider: () => Promise<string | null>): void;
+    private sendAuth;
+    subscribeToQuery(query: QueryHandle<any>): void;
+    subscribeToTopic(topic: string, handle: TopicHandle): void;
+    unsubscribeFromTopic(topic: string): void;
+    publishTopic(topic: string, data: any): void;
+    private sendTopicSubscription;
+    /**
+     * Executes a query against local storage immediately
+     */
+    runLocalQuery(mapName: string, filter: QueryFilter): Promise<{
+        key: string;
+        value: any;
+    }[]>;
+    unsubscribeFromQuery(queryId: string): void;
+    private sendQuerySubscription;
+    requestLock(name: string, requestId: string, ttl: number): Promise<{
+        fencingToken: number;
+    }>;
+    releaseLock(name: string, requestId: string, fencingToken: number): Promise<boolean>;
+    private handleServerMessage;
+    getHLC(): HLC;
+    /**
+     * Closes the WebSocket connection and cleans up resources.
+     */
+    close(): void;
+    private resetMap;
+}
+
+interface ILock {
+    lock(ttl?: number): Promise<boolean>;
+    unlock(): Promise<void>;
+    isLocked(): boolean;
+}
+declare class DistributedLock implements ILock {
+    private syncEngine;
+    private name;
+    private fencingToken;
+    private _isLocked;
+    constructor(syncEngine: SyncEngine, name: string);
+    lock(ttl?: number): Promise<boolean>;
+    unlock(): Promise<void>;
+    isLocked(): boolean;
+}
+
+declare class TopGunClient {
+    private readonly nodeId;
+    private readonly syncEngine;
+    private readonly maps;
+    private readonly storageAdapter;
+    private readonly topicHandles;
+    constructor(config: {
+        nodeId?: string;
+        serverUrl: string;
+        storage: IStorageAdapter;
+    });
+    start(): Promise<void>;
+    setAuthToken(token: string): void;
+    setAuthTokenProvider(provider: () => Promise<string | null>): void;
+    /**
+     * Creates a live query subscription for a map.
+     */
+    query<T>(mapName: string, filter: QueryFilter): QueryHandle<T>;
+    /**
+     * Retrieves a distributed lock instance.
+     * @param name The name of the lock.
+     */
+    getLock(name: string): DistributedLock;
+    /**
+     * Retrieves a topic handle for Pub/Sub messaging.
+     * @param name The name of the topic.
+     */
+    topic(name: string): TopicHandle;
+    /**
+     * Retrieves an LWWMap instance. If the map doesn't exist locally, it's created.
+     * @param name The name of the map.
+     * @returns An LWWMap instance.
+     */
+    getMap<K, V>(name: string): LWWMap<K, V>;
+    /**
+     * Retrieves an ORMap instance. If the map doesn't exist locally, it's created.
+     * @param name The name of the map.
+     * @returns An ORMap instance.
+     */
+    getORMap<K, V>(name: string): ORMap<K, V>;
+    private restoreORMap;
+    private persistORMapKey;
+    private persistORMapTombstones;
+    /**
+     * Closes the client, disconnecting from the server and cleaning up resources.
+     */
+    close(): void;
+}
+
+interface TopGunConfig {
+    sync: string;
+    persist: 'indexeddb' | IStorageAdapter;
+    nodeId?: string;
+}
+type TopGunSchema = Record<string, any>;
+declare class TopGun<T extends TopGunSchema = any> {
+    private client;
+    private initPromise;
+    [key: string]: any;
+    constructor(config: TopGunConfig);
+    /**
+     * Waits for the storage adapter to be fully initialized.
+     * This is optional - you can start using the database immediately.
+     * Operations are queued in memory and persisted once IndexedDB is ready.
+     */
+    waitForReady(): Promise<void>;
+    collection<K extends keyof T & string>(name: K): CollectionWrapper<T[K]>;
+}
+declare class CollectionWrapper<ItemType = any> {
+    private map;
+    constructor(map: LWWMap<string, ItemType>);
+    /**
+     * Sets an item in the collection.
+     * The item MUST have an 'id' or '_id' field.
+     */
+    set(value: ItemType): Promise<ItemType>;
+    /**
+     * Retrieves an item by ID.
+     * Returns the value directly (unwrapped from CRDT record).
+     */
+    get(key: string): ItemType | undefined;
+    /**
+     * Get the raw LWWRecord (including metadata like timestamp).
+     */
+    getRecord(key: string): LWWRecord<ItemType> | undefined;
+    get raw(): LWWMap<string, ItemType>;
+}
+
+/**
+ * Non-blocking IndexedDB adapter that allows immediate use before initialization completes.
+ *
+ * Operations are queued in memory and replayed once IndexedDB is ready.
+ * This enables true "memory-first" behavior where the UI can render immediately
+ * without waiting for IndexedDB to initialize (which can take 50-500ms).
+ */
+declare class IDBAdapter implements IStorageAdapter {
+    private dbPromise?;
+    private db?;
+    private isReady;
+    private operationQueue;
+    private initPromise?;
+    /**
+     * Initializes IndexedDB in the background.
+     * Returns immediately - does NOT block on IndexedDB being ready.
+     * Use waitForReady() if you need to ensure initialization is complete.
+     */
+    initialize(dbName: string): Promise<void>;
+    /**
+     * Internal initialization that actually opens IndexedDB.
+     */
+    private initializeInternal;
+    /**
+     * Waits for IndexedDB to be fully initialized.
+     * Call this if you need guaranteed persistence before proceeding.
+     */
+    waitForReady(): Promise<void>;
+    /**
+     * Flushes all queued operations once IndexedDB is ready.
+     */
+    private flushQueue;
+    /**
+     * Queues an operation if not ready, or executes immediately if ready.
+     */
+    private queueOrExecute;
+    close(): Promise<void>;
+    get<V>(key: string): Promise<LWWRecord<V> | ORMapRecord<V>[] | any | undefined>;
+    getMeta(key: string): Promise<any>;
+    getPendingOps(): Promise<OpLogEntry[]>;
+    getAllKeys(): Promise<string[]>;
+    put(key: string, value: any): Promise<void>;
+    private putInternal;
+    remove(key: string): Promise<void>;
+    private removeInternal;
+    setMeta(key: string, value: any): Promise<void>;
+    private setMetaInternal;
+    batchPut(entries: Map<string, any>): Promise<void>;
+    private batchPutInternal;
+    appendOpLog(entry: any): Promise<number>;
+    private appendOpLogInternal;
+    markOpsSynced(lastId: number): Promise<void>;
+    private markOpsSyncedInternal;
+}
+
+/**
+ * Wraps an underlying storage adapter and encrypts data at rest using AES-GCM.
+ */
+declare class EncryptedStorageAdapter implements IStorageAdapter {
+    private wrapped;
+    private key;
+    constructor(wrapped: IStorageAdapter, key: CryptoKey);
+    initialize(dbName: string): Promise<void>;
+    close(): Promise<void>;
+    get<V>(key: string): Promise<V | any | undefined>;
+    put(key: string, value: any): Promise<void>;
+    remove(key: string): Promise<void>;
+    getMeta(key: string): Promise<any>;
+    setMeta(key: string, value: any): Promise<void>;
+    batchPut(entries: Map<string, any>): Promise<void>;
+    appendOpLog(entry: Omit<OpLogEntry, 'id'>): Promise<number>;
+    getPendingOps(): Promise<OpLogEntry[]>;
+    markOpsSynced(lastId: number): Promise<void>;
+    getAllKeys(): Promise<string[]>;
+    private isEncryptedRecord;
+}
+
+declare const logger: pino.Logger<never, boolean>;
+
+export { EncryptedStorageAdapter, IDBAdapter, type IStorageAdapter, type OpLogEntry, type QueryFilter, QueryHandle, type QueryResultItem, type QueryResultSource, SyncEngine, TopGun, TopGunClient, type TopicCallback, TopicHandle, logger };