@edryslabs/genericprovider 1.0.1

package/dist/index.d.ts

@@ -0,0 +1,323 @@
+import * as Y from 'yjs';
+import * as awarenessProtocol from 'y-protocols/awareness';
+import { Observable } from 'lib0/observable';
+import type { Transport, ConnectionConfig, ConnectionStatus } from './transport';
+/**
+ * PubSub channel for real-time messaging alongside Yjs.
+ * Allows sending ephemeral messages that don't need CRDT properties.
+ */
+export declare class PubSubChannel extends Observable<string> {
+    private provider;
+    constructor(provider: GenericProvider);
+    /**
+     * Publish a message to a topic.
+     *
+     * @param topic - Topic name (e.g., 'notifications', 'rpc', 'events')
+     * @param message - Any JSON-serializable data
+     *
+     * @example
+     * ```typescript
+     * provider.pubsub.publish('chat', { user: 'Alice', text: 'Hello!' })
+     * provider.pubsub.publish('cursor', { x: 100, y: 200 })
+     * ```
+     */
+    publish(topic: string, message: any): void;
+    /**
+     * Publish a message to a single target instead of broadcasting.
+     *
+     * On transports with `sendTo`, `target` is the peer's ID and delivery is
+     * direct. On transports without it, the message is broadcast with the
+     * target embedded and dropped by every provider whose `localId` differs.
+     *
+     * @param target - Recipient id (transport peerId, or a `localId`)
+     * @param topic - Topic name
+     * @param message - Any JSON-serializable data
+     */
+    publishTo(target: string, topic: string, message: any): void;
+    /**
+     * Subscribe to messages on a topic.
+     *
+     * @param topic - Topic name to listen to (use '*' for all topics)
+     * @param callback - Function called when message received
+     * @returns Unsubscribe function
+     *
+     * @example
+     * ```typescript
+     * const unsub = provider.pubsub.subscribe('chat', (msg) => {
+     *   console.log('Chat:', msg)
+     * })
+     *
+     * // Later: unsub()
+     * ```
+     */
+    subscribe(topic: string, callback: (message: any, topic: string) => void): () => void;
+    /**
+     * Internal: Handle incoming pub/sub message
+     */
+    _handleMessage(topic: string, message: any): void;
+}
+/**
+ * Generic Yjs provider that works with any transport implementation.
+ *
+ * This provider handles all Yjs synchronization logic including:
+ * - Document updates (automatic sync)
+ * - Awareness protocol (presence, cursors, etc.)
+ * - State vector synchronization
+ * - Optional pub/sub channel for real-time messaging
+ *
+ * You only need to implement the Transport interface for your backend.
+ *
+ * @example
+ * ```typescript
+ * // Create your transport
+ * const transport = new MyCustomTransport()
+ *
+ * // Create provider with Yjs document
+ * const doc = new Y.Doc()
+ * const provider = new GenericProvider(doc, transport)
+ *
+ * // Connect
+ * await provider.connect({ room: 'my-room' })
+ *
+ * // Provider automatically syncs all changes
+ * const ytext = doc.getText('content')
+ * ytext.insert(0, 'Hello') // Automatically synced!
+ * ```
+ */
+export declare class GenericProvider extends Observable<string> {
+    readonly doc: Y.Doc;
+    readonly transport: Transport;
+    readonly awareness: awarenessProtocol.Awareness;
+    readonly pubsub: PubSubChannel;
+    private _status;
+    private _synced;
+    private _destroying;
+    private _syncInterval;
+    private _syncIntervalId?;
+    private _verifyUpdates;
+    private _disableBc;
+    private _bcChannel;
+    private _bcConnected;
+    private _bcSubscriber?;
+    private _hashMismatchCount;
+    private _lastHashMismatchTime;
+    private _syncRequestTimes;
+    private _maxSyncRequestsPerWindow;
+    private _syncRequestWindowMs;
+    private _localSeqNum;
+    private _remoteSeqNums;
+    private _corruptedMessageCount;
+    private _lastCorruptedMessageTime;
+    private _batchUpdates;
+    private _pendingUpdate;
+    private _batchTimeoutId?;
+    private _awarenessInterval;
+    private _pendingAwarenessClients;
+    private _awarenessTimeoutId?;
+    private _lastAwarenessTime;
+    private _excludeOrigins;
+    private _localId?;
+    private _syncMode;
+    private _updateHandler?;
+    private _awarenessUpdateHandler?;
+    private _unsubscribeTransport?;
+    private _beforeUnloadHandler?;
+    /**
+     * Create a new generic provider.
+     *
+     * @param doc - The Yjs document to sync
+     * @param transport - Transport implementation for your backend
+     * @param options - Optional configuration
+     */
+    constructor(doc: Y.Doc, transport: Transport, options?: {
+        awareness?: awarenessProtocol.Awareness;
+        /**
+         * Interval in milliseconds for periodic sync retries.
+         * Helps recover from packet loss. Set to 0 to disable.
+         * @default 5000
+         */
+        syncInterval?: number;
+        /**
+         * Send document hash with each update for immediate desync detection.
+         * When enabled, mismatch triggers instant re-sync instead of waiting.
+         * @default true
+         */
+        verifyUpdates?: boolean;
+        /**
+         * Batch (debounce) document updates to reduce network traffic.
+         * Updates are collected and sent after this delay in milliseconds.
+         * Set to 0 to send updates immediately (no batching).
+         * Recommended: 50-200ms for good balance between latency and efficiency.
+         * @default 0 (disabled - immediate transmission)
+         */
+        batchUpdates?: number;
+        /**
+         * Disable BroadcastChannel for cross-tab communication.
+         * When enabled (default), updates are shared instantly between tabs
+         * in the same browser without going through the network transport.
+         * Automatically disabled in non-browser environments (e.g., Node.js).
+         * @default false (BroadcastChannel enabled)
+         */
+        disableBc?: boolean;
+        /**
+         * Throttle awareness updates to reduce network traffic.
+         * Awareness updates (cursors, presence) are batched and sent at this interval.
+         * Set to 0 for immediate transmission (not recommended for high-frequency updates).
+         * This prevents awareness from flooding document sync on limited transports.
+         * @default 100 (100ms between awareness broadcasts)
+         */
+        awarenessInterval?: number;
+        /**
+         * Transaction origins whose updates should not be sent to peers.
+         * Updates from these origins stay local (never reach the transport).
+         * @default [] (no origins excluded)
+         */
+        excludeOrigins?: any[];
+        /**
+         * This provider's identity for targeted pubsub (publishTo).
+         * On transports without sendTo, targeted messages are broadcast and
+         * dropped unless their target matches this id.
+         */
+        localId?: string;
+        /**
+         * Connect-time sync strategy.
+         * - 'push-pull' (default): push full local state to peers, then request
+         *   remote state. Correct for P2P transports where there is no
+         *   authoritative peer to pull from (e.g. offline edits must be pushed).
+         * - 'pull': only request remote state on connect (SyncStep1), never push
+         *   full local state. Use with relay/server transports (e.g. y-websocket)
+         *   where the server holds authoritative state and a reconnecting client
+         *   should adopt it rather than push a competing local copy.
+         * @default 'push-pull'
+         */
+        syncMode?: 'push-pull' | 'pull';
+    });
+    /**
+     * Connect to the backend and start syncing.
+     *
+     * @param config - Connection configuration passed to transport
+     */
+    connect(config: ConnectionConfig): Promise<void>;
+    /**
+     * Disconnect from the backend.
+     * The provider can be reconnected later with connect().
+     */
+    disconnect(): void;
+    /**
+     * Destroy the provider permanently.
+     * Removes all event listeners and cleans up resources.
+     */
+    destroy(): void;
+    /**
+     * Current connection status
+     */
+    get status(): ConnectionStatus;
+    /**
+     * Whether the provider is connected to the backend
+     */
+    get connected(): boolean;
+    /**
+     * Whether BroadcastChannel is connected for cross-tab sync
+     */
+    get bcConnected(): boolean;
+    /**
+     * Whether the document is synced with remote peers
+     */
+    get synced(): boolean;
+    /**
+     * Force an immediate sync with remote peers.
+     * Useful after network interruptions or to manually trigger re-sync.
+     */
+    syncNow(): void;
+    /**
+     * Setup automatic document synchronization.
+     * Listens to document updates and sends them to the transport.
+     * If batchUpdates is enabled, updates are debounced/batched.
+     */
+    private _setupDocumentSync;
+    /**
+     * Batch/debounce updates to reduce network traffic.
+     * Merges multiple updates and sends after delay.
+     */
+    private _batchUpdate;
+    /**
+     * Setup automatic awareness synchronization.
+     * Listens to awareness changes and broadcasts them.
+     */
+    private _setupAwarenessSync;
+    /**
+     * Handle incoming messages from the transport.
+     * Verifies message integrity with CRC32 before processing.
+     * Corrupt messages are rejected immediately without attempting to decode.
+     */
+    private _handleIncomingMessage;
+    /**
+     * Send SyncStep1 message to request missing updates.
+     * This is sent when first connecting to sync with remote peers.
+     * Note: SyncStep1 is just a request and doesn't include hash verification.
+     * Rate limited to prevent spam.
+     */
+    private _sendSyncStep1;
+    /**
+     * Send a document update to the transport.
+     * If verifyUpdates is enabled, includes sequence number and document hash for ordering and desync detection.
+     */
+    private _sendUpdate;
+    /**
+     * Send awareness update to the transport.
+     */
+    private _sendAwarenessUpdate;
+    /**
+     * Send a pub/sub message.
+     * Internal method called by PubSubChannel.
+     */
+    _sendPubSub(topic: string, message: any): void;
+    /**
+     * Send a targeted pub/sub message.
+     * Uses transport.sendTo when available (direct delivery), otherwise
+     * broadcasts a targeted frame that non-target providers drop.
+     * Internal method called by PubSubChannel.
+     */
+    _sendPubSubTo(target: string, topic: string, message: any): void;
+    /**
+     * Broadcast awareness state for the specified clients.
+     * Throttled to prevent awareness updates from flooding document sync.
+     * Multiple rapid updates are batched together.
+     */
+    private _broadcastAwareness;
+    /**
+     * Send awareness update immediately without throttling.
+     */
+    private _sendAwarenessNow;
+    /**
+     * Setup BroadcastChannel for cross-tab communication.
+     * Automatically disabled in non-browser environments.
+     */
+    private _setupBroadcastChannel;
+    /**
+     * Disconnect from BroadcastChannel and mark local client as offline.
+     */
+    private _disconnectBroadcastChannel;
+    /**
+     * Send data through both BroadcastChannel (if connected) and transport.
+     * All messages are wrapped with CRC32 checksum for integrity verification.
+     * This ensures updates reach both local tabs and remote peers with corruption detection.
+     */
+    private _send;
+    /**
+     * Update connection status and emit event.
+     */
+    private _setStatus;
+    /**
+     * TEST HELPER: Set local sequence number to a specific value.
+     * Used for testing sequence number overflow scenarios.
+     * @internal
+     */
+    _testSetSequenceNumber(seqNum: number): void;
+    /**
+     * TEST HELPER: Get current local sequence number.
+     * @internal
+     */
+    _testGetSequenceNumber(): number;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAA;AACxB,OAAO,KAAK,iBAAiB,MAAM,uBAAuB,CAAA;AAI1D,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAG5C,OAAO,KAAK,EAAE,SAAS,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AA6GhF;;;GAGG;AACH,qBAAa,aAAc,SAAQ,UAAU,CAAC,MAAM,CAAC;IACnD,OAAO,CAAC,QAAQ,CAAiB;gBAErB,QAAQ,EAAE,eAAe;IAKrC;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,GAAG,IAAI;IAI1C;;;;;;;;;;OAUG;IACH,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,GAAG,IAAI;IAI5D;;;;;;;;;;;;;;;OAeG;IACH,SAAS,CACP,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,GAC9C,MAAM,IAAI;IAWb;;OAEG;IACH,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,GAAG,IAAI;CAGlD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,qBAAa,eAAgB,SAAQ,UAAU,CAAC,MAAM,CAAC;IACrD,SAAgB,GAAG,EAAE,CAAC,CAAC,GAAG,CAAA;IAC1B,SAAgB,SAAS,EAAE,SAAS,CAAA;IACpC,SAAgB,SAAS,EAAE,iBAAiB,CAAC,SAAS,CAAA;IACtD,SAAgB,MAAM,EAAE,aAAa,CAAA;IAErC,OAAO,CAAC,OAAO,CAA8C;IAC7D,OAAO,CAAC,OAAO,CAAiB;IAChC,OAAO,CAAC,WAAW,CAAiB;IACpC,OAAO,CAAC,aAAa,CAAQ;IAC7B,OAAO,CAAC,eAAe,CAAC,CAA+B;IACvD,OAAO,CAAC,cAAc,CAAS;IAC/B,OAAO,CAAC,UAAU,CAAS;IAG3B,OAAO,CAAC,UAAU,CAAa;IAC/B,OAAO,CAAC,YAAY,CAAiB;IACrC,OAAO,CAAC,aAAa,CAAC,CAA0C;IAGhE,OAAO,CAAC,kBAAkB,CAAY;IACtC,OAAO,CAAC,qBAAqB,CAAY;IAGzC,OAAO,CAAC,iBAAiB,CAAe;IACxC,OAAO,CAAC,yBAAyB,CAAa;IAC9C,OAAO,CAAC,oBAAoB,CAAgB;IAG5C,OAAO,CAAC,YAAY,CAAY;IAChC,OAAO,CAAC,cAAc,CAAiC;IAGvD,OAAO,CAAC,sBAAsB,CAAY;IAC1C,OAAO,CAAC,yBAAyB,CAAY;IAG7C,OAAO,CAAC,aAAa,CAAY;IACjC,OAAO,CAAC,cAAc,CAA0B;IAChD,OAAO,CAAC,eAAe,CAAC,CAA+B;IAGvD,OAAO,CAAC,kBAAkB,CAAc;IACxC,OAAO,CAAC,wBAAwB,CAAyB;IACzD,OAAO,CAAC,mBAAmB,CAAC,CAA+B;IAC3D,OAAO,CAAC,kBAAkB,CAAY;IAGtC,OAAO,CAAC,eAAe,CAAsB;IAG7C,OAAO,CAAC,QAAQ,CAAC,CAAQ;IAIzB,OAAO,CAAC,SAAS,CAAoC;IAErD,OAAO,CAAC,cAAc,CAAC,CAA2C;IAClE,OAAO,CAAC,uBAAuB,CAAC,CAAqC;IACrE,OAAO,CAAC,qBAAqB,CAAC,CAAY;IAC1C,OAAO,CAAC,oBAAoB,CAAC,CAAY;IAEzC;;;;;;OAMG;gBAED,GAAG,EAAE,CAAC,CAAC,GAAG,EACV,SAAS,EAAE,SAAS,EACpB,OAAO,GAAE;QACP,SAAS,CAAC,EAAE,iBAAiB,CAAC,SAAS,CAAA;QACvC;;;;WAIG;QACH,YAAY,CAAC,EAAE,MAAM,CAAA;QACrB;;;;WAIG;QACH,aAAa,CAAC,EAAE,OAAO,CAAA;QACvB;;;;;;WAMG;QACH,YAAY,CAAC,EAAE,MAAM,CAAA;QACrB;;;;;;WAMG;QACH,SAAS,CAAC,EAAE,OAAO,CAAA;QACnB;;;;;;WAMG;QACH,iBAAiB,CAAC,EAAE,MAAM,CAAA;QAC1B;;;;WAIG;QACH,cAAc,CAAC,EAAE,GAAG,EAAE,CAAA;QACtB;;;;WAIG;QACH,OAAO,CAAC,EAAE,MAAM,CAAA;QAChB;;;;;;;;;;WAUG;QACH,QAAQ,CAAC,EAAE,WAAW,GAAG,MAAM,CAAA;KAC3B;IAqBR;;;;OAIG;IACG,OAAO,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;IA4FtD;;;OAGG;IACH,UAAU,IAAI,IAAI;IA2DlB;;;OAGG;IACH,OAAO,IAAI,IAAI;IA6Cf;;OAEG;IACH,IAAI,MAAM,IAAI,gBAAgB,CAE7B;IAED;;OAEG;IACH,IAAI,SAAS,IAAI,OAAO,CAEvB;IAED;;OAEG;IACH,IAAI,WAAW,IAAI,OAAO,CAEzB;IAED;;OAEG;IACH,IAAI,MAAM,IAAI,OAAO,CAEpB;IAED;;;OAGG;IACH,OAAO,IAAI,IAAI;IAoBf;;;;OAIG;IACH,OAAO,CAAC,kBAAkB;IAoB1B;;;OAGG;IACH,OAAO,CAAC,YAAY;IAgCpB;;;OAGG;IACH,OAAO,CAAC,mBAAmB;IAmC3B;;;;OAIG;IACH,OAAO,CAAC,sBAAsB;IAoO9B;;;;;OAKG;IACH,OAAO,CAAC,cAAc;IA2BtB;;;OAGG;IACH,OAAO,CAAC,WAAW;IAyBnB;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAU5B;;;OAGG;IACH,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,GAAG,IAAI;IA6B9C;;;;;OAKG;IACH,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,GAAG,IAAI;IAmChE;;;;OAIG;IACH,OAAO,CAAC,mBAAmB;IAuC3B;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAUzB;;;OAGG;IACH,OAAO,CAAC,sBAAsB;IAqE9B;;OAEG;IACH,OAAO,CAAC,2BAA2B;IA4BnC;;;;OAIG;IACH,OAAO,CAAC,KAAK;IA2Bb;;OAEG;IACH,OAAO,CAAC,UAAU;IAKlB;;;;OAIG;IACH,sBAAsB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAO5C;;;OAGG;IACH,sBAAsB,IAAI,MAAM;CAGjC"}