@topgunbuild/client 0.1.0

package/LICENSE

@@ -0,0 +1,97 @@
+Business Source License 1.1
+
+Parameters
+
+Licensor:             TopGun Contributors
+Licensed Work:        TopGun
+                      The Licensed Work is (c) 2024 TopGun Contributors.
+Additional Use Grant: You may make production use of the Licensed Work,
+                      provided Your use does not include offering the
+                      Licensed Work to third parties as a commercial
+                      managed database service, database-as-a-service,
+                      or similar hosted database offering that competes
+                      with TopGun products or services.
+
+                      For purposes of this license:
+                      - "Managed database service" means a service that
+                        allows third parties to create, manage, or operate
+                        databases using TopGun as the underlying technology.
+                      - Internal use within your organization is permitted.
+                      - Using TopGun as part of your application's backend
+                        (not exposed as a database service) is permitted.
+                      - Consulting and professional services around TopGun
+                        are permitted.
+
+Change Date:          Four years from the date of each version release
+Change License:       Apache License, Version 2.0
+
+For information about alternative licensing arrangements for the Licensed Work,
+please contact the Licensor.
+
+Notice
+
+Business Source License 1.1
+
+Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative
+works, redistribute, and make non-production use of the Licensed Work. The
+Licensor may make an Additional Use Grant, above, permitting limited production use.
+
+Effective on the Change Date, or the fourth anniversary of the first publicly
+available distribution of a specific version of the Licensed Work under this
+License, whichever comes first, the Licensor hereby grants you rights under
+the terms of the Change License, and the rights granted in the paragraph
+above terminate.
+
+If your use of the Licensed Work does not comply with the requirements
+currently in effect as described in this License, you must purchase a
+commercial license from the Licensor, its affiliated entities, or authorized
+resellers, or you must refrain from using the Licensed Work.
+
+All copies of the original and modified Licensed Work, and derivative works
+of the Licensed Work, are subject to this License. This License applies
+separately for each version of the Licensed Work and the Change Date may vary
+for each version of the Licensed Work released by Licensor.
+
+You must conspicuously display this License on each original or modified copy
+of the Licensed Work. If you receive the Licensed Work in original or
+modified form from a third party, the terms and conditions set forth in this
+License apply to your use of that work.
+
+Any use of the Licensed Work in violation of this License will automatically
+terminate your rights under this License for the current and all other
+versions of the Licensed Work.
+
+This License does not grant you any right in any trademark or logo of
+Licensor or its affiliates (provided that you may use a trademark or logo of
+Licensor as expressly required by this License).
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON
+AN "AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS,
+EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND
+TITLE.
+
+MariaDB hereby grants you permission to use this License's text to license
+your works, and to refer to it using the trademark "Business Source License",
+as long as you comply with the Covenants of Licensor below.
+
+Covenants of Licensor
+
+In consideration of the right to use this License's text and the "Business
+Source License" name and trademark, Licensor covenants to MariaDB, and to all
+other recipients of the licensed work to be provided by Licensor:
+
+1. To specify as the Change License the GPL Version 2.0 or any later version,
+   or a license that is compatible with GPL Version 2.0 or a later version,
+   where "compatible" means that software provided under the Change License can
+   be included in a program with software provided under GPL Version 2.0 or a
+   later version. Licensor may specify additional Change Licenses without
+   limitation.
+
+2. To either: (a) specify an Additional Use Grant (above) that does not impose
+   any additional restriction on the right granted in this License, as the
+   Additional Use Grant; or (b) insert the text "None" to specify a Change Date.
+
+3. Not to modify this License in any other way.

package/dist/index.d.mts

@@ -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 };