@edryslabs/genericprovider 1.0.1

package/dist/providers/dummy/index.js

@@ -0,0 +1,326 @@
+/**
+ * Dummy Transport for Testing
+ *
+ * A simple in-memory transport that simulates network behavior without
+ * any external dependencies. Perfect for:
+ * - Unit testing
+ * - Learning how transports work
+ * - Local development without a server
+ * - Reference implementation for custom transports
+ *
+ * Features:
+ * - Simulated network latency
+ * - Simulated packet loss
+ * - Connect multiple clients in-memory
+ * - No external dependencies
+ * - Auto-managed hubs (just works!)
+ *
+ * @example
+ * ```typescript
+ * import { GenericProvider } from 'y-generic'
+ * import { DummyTransport } from 'y-generic/providers/dummy'
+ *
+ * // Simple usage - hub is auto-managed
+ * const doc1 = new Y.Doc()
+ * const provider1 = new GenericProvider(doc1, new DummyTransport())
+ * await provider1.connect({ room: 'test-room' })
+ *
+ * const doc2 = new Y.Doc()
+ * const provider2 = new GenericProvider(doc2, new DummyTransport())
+ * await provider2.connect({ room: 'test-room' })
+ *
+ * // Changes sync automatically!
+ * doc1.getText('test').insert(0, 'Hello')
+ * // doc2 receives the update
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Advanced: Explicit hub for fine control
+ * import { DummyHub } from 'y-generic/providers/dummy'
+ *
+ * const hub = new DummyHub()
+ * const transport1 = new DummyTransport({ hub })
+ * const transport2 = new DummyTransport({ hub })
+ * ```
+ */
+/**
+ * Central hub that routes messages between DummyTransport instances.
+ * Simulates a server or message broker.
+ */
+export class DummyHub {
+    constructor() {
+        this.rooms = new Map();
+    }
+    /**
+     * Register a transport in a room.
+     */
+    join(room, transport, callback) {
+        if (!this.rooms.has(room)) {
+            this.rooms.set(room, new Set());
+        }
+        this.rooms.get(room).add({ transport, callback });
+    }
+    /**
+     * Unregister a transport from a room.
+     */
+    leave(room, transport) {
+        const clients = this.rooms.get(room);
+        if (clients) {
+            for (const client of clients) {
+                if (client.transport === transport) {
+                    clients.delete(client);
+                    break;
+                }
+            }
+            if (clients.size === 0) {
+                this.rooms.delete(room);
+            }
+        }
+    }
+    /**
+     * Broadcast a message to all clients in a room except the sender.
+     */
+    broadcast(room, data, sender, options) {
+        const clients = this.rooms.get(room);
+        if (!clients)
+            return;
+        const latency = options?.latency ?? 0;
+        const dropRate = options?.dropRate ?? 0;
+        const jitter = options?.jitter ?? 0;
+        for (const client of clients) {
+            // Don't send back to sender
+            if (client.transport === sender)
+                continue;
+            // Simulate packet loss
+            if (dropRate > 0 && Math.random() < dropRate) {
+                continue;
+            }
+            // Calculate actual delay with jitter
+            let actualDelay = latency;
+            if (latency > 0 && jitter > 0) {
+                // Random delay between latency*(1-jitter) and latency*(1+jitter)
+                const minDelay = latency * (1 - jitter);
+                const maxDelay = latency * (1 + jitter);
+                actualDelay = minDelay + Math.random() * (maxDelay - minDelay);
+            }
+            // Simulate network latency
+            if (actualDelay > 0) {
+                setTimeout(() => {
+                    try {
+                        client.callback(data);
+                    }
+                    catch (error) {
+                        console.error('Error delivering message:', error);
+                    }
+                }, actualDelay);
+            }
+            else {
+                try {
+                    client.callback(data);
+                }
+                catch (error) {
+                    console.error('Error delivering message:', error);
+                }
+            }
+        }
+    }
+    /**
+     * Get the number of clients connected to a room.
+     */
+    getRoomSize(room) {
+        return this.rooms.get(room)?.size ?? 0;
+    }
+    /**
+     * Get all active room names.
+     */
+    getRooms() {
+        return Array.from(this.rooms.keys());
+    }
+    /**
+     * Disconnect all clients and clear all rooms.
+     */
+    clear() {
+        this.rooms.clear();
+    }
+}
+/**
+ * Global hub registry for auto-managed hubs (one per room).
+ * Used when no explicit hub is provided.
+ */
+const globalHubs = new Map();
+/**
+ * Get or create a hub for a room.
+ */
+function getOrCreateHub(room) {
+    if (!globalHubs.has(room)) {
+        globalHubs.set(room, new DummyHub());
+    }
+    return globalHubs.get(room);
+}
+/**
+ * Dummy transport implementation for testing and development.
+ * Routes messages through a DummyHub instance.
+ */
+export class DummyTransport {
+    /**
+     * Create a new DummyTransport.
+     *
+     * @param options - Optional behavior simulation settings
+     *
+     * @example
+     * ```typescript
+     * // Simple case - hub is auto-managed
+     * const transport = new DummyTransport()
+     *
+     * // With network simulation
+     * const transport = new DummyTransport({ latency: 100, dropRate: 0.1 })
+     *
+     * // With out-of-order delivery (useful for testing CRDT)
+     * const transport = new DummyTransport({ latency: 100, jitter: 0.5 })
+     * // Messages arrive between 50ms and 150ms (may arrive out of order)
+     *
+     * // Advanced - explicit shared hub
+     * const hub = new DummyHub()
+     * const transport1 = new DummyTransport({ hub })
+     * const transport2 = new DummyTransport({ hub })
+     * ```
+     */
+    constructor(options = {}) {
+        this._connected = false;
+        this._room = '';
+        this.hub = options.hub;
+        this.explicitHub = !!options.hub;
+        this.options = {
+            latency: options.latency ?? 0,
+            dropRate: options.dropRate ?? 0,
+            jitter: options.jitter ?? 0,
+            autoConnect: options.autoConnect ?? false,
+        };
+    }
+    /**
+     * Connect to a room on the hub.
+     */
+    async connect(config) {
+        if (this._connected) {
+            throw new Error('Already connected');
+        }
+        this._room = config.room;
+        // Get or create hub for this room if not explicitly provided
+        if (!this.hub) {
+            this.hub = getOrCreateHub(this._room);
+        }
+        // Simulate async connection
+        await new Promise((resolve) => setTimeout(resolve, this.options.latency));
+        // If callback is registered, join immediately
+        if (this._callback) {
+            this.hub.join(this._room, this, this._callback);
+        }
+        // Otherwise, will join when onMessage() is called
+        this._connected = true;
+    }
+    /**
+     * Disconnect from the hub.
+     */
+    disconnect() {
+        if (!this._connected)
+            return;
+        if (this.hub) {
+            this.hub.leave(this._room, this);
+        }
+        this._connected = false;
+    }
+    /**
+     * Send data to all other clients in the room.
+     */
+    send(data) {
+        if (!this._connected || !this.hub) {
+            if (this.options.autoConnect && this._room) {
+                // Auto-reconnect was requested
+                console.warn('DummyTransport: Not connected, dropping message');
+            }
+            return;
+        }
+        // Broadcast through hub
+        this.hub.broadcast(this._room, data, this, {
+            latency: this.options.latency,
+            dropRate: this.options.dropRate,
+            jitter: this.options.jitter,
+        });
+    }
+    /**
+     * Register callback for incoming messages.
+     */
+    onMessage(callback) {
+        this._callback = callback;
+        // If already connected, register with hub now
+        if (this._connected && this._room && this.hub) {
+            this.hub.join(this._room, this, callback);
+        }
+        // Return unsubscribe function
+        return () => {
+            this._callback = undefined;
+        };
+    }
+    /**
+     * Check if connected.
+     */
+    get isConnected() {
+        return this._connected;
+    }
+    /**
+     * Get current room name (for debugging).
+     */
+    get room() {
+        return this._room;
+    }
+    /**
+     * Get the hub instance being used (for debugging).
+     */
+    getHub() {
+        return this.hub;
+    }
+}
+/**
+ * Utility functions for debugging and testing.
+ */
+/**
+ * Get statistics about all auto-managed hubs.
+ * Useful for debugging and verifying test cleanup.
+ *
+ * @example
+ * ```typescript
+ * const stats = getGlobalHubStats()
+ * console.log(`Active rooms: ${stats.totalRooms}`)
+ * console.log(`Total clients: ${stats.totalClients}`)
+ * ```
+ */
+export function getGlobalHubStats() {
+    const rooms = Array.from(globalHubs.entries()).map(([room, hub]) => ({
+        room,
+        clients: hub.getRoomSize(room),
+    }));
+    return {
+        totalRooms: globalHubs.size,
+        totalClients: rooms.reduce((sum, r) => sum + r.clients, 0),
+        rooms,
+    };
+}
+/**
+ * Clear all auto-managed hubs.
+ * Useful for cleaning up between tests.
+ *
+ * @example
+ * ```typescript
+ * afterEach(() => {
+ *   clearGlobalHubs()
+ * })
+ * ```
+ */
+export function clearGlobalHubs() {
+    for (const hub of globalHubs.values()) {
+        hub.clear();
+    }
+    globalHubs.clear();
+}
+//# sourceMappingURL=index.js.map

package/dist/providers/dummy/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/providers/dummy/index.ts"],"names":[],"mappings":"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"}

package/dist/providers/gun/index.d.ts

@@ -0,0 +1,269 @@
+/**
+ * GunDB Transport Provider
+ *
+ * Decentralized peer-to-peer transport using GunDB graph database.
+ * GunDB provides automatic conflict resolution and offline-first sync.
+ *
+ * Features:
+ * - Decentralized P2P architecture
+ * - Automatic conflict resolution (CRDT)
+ * - Offline-first with auto-sync
+ * - Real-time updates via .on()
+ * - Optional relay servers
+ * - Graph-based data structure
+ * - Password-protected rooms with AES encryption (via SEA)
+ *
+ * @example
+ * ```typescript
+ * import { GenericProvider } from 'y-generic'
+ * import { GunTransport } from 'y-generic/providers/gun'
+ * import Gun from 'gun'
+ *
+ * const doc = new Y.Doc()
+ * const transport = new GunTransport({
+ *   gun: Gun, // Pass the Gun constructor
+ *   peers: ['https://gun-relay.herokuapp.com/gun']
+ * })
+ * const provider = new GenericProvider(doc, transport)
+ * await provider.connect({ room: 'my-room' })
+ * ```
+ *
+ * @example Password-protected room
+ * ```typescript
+ * import Gun from 'gun'
+ * import 'gun/sea'  // Required for encryption
+ *
+ * const transport = new GunTransport({
+ *   gun: Gun,
+ *   sea: Gun.SEA,  // Provide SEA module
+ *   password: 'my-secret-room-password',
+ *   peers: ['https://gun-relay.herokuapp.com/gun']
+ * })
+ * ```
+ */
+import * as Y from 'yjs';
+import type { Transport, ConnectionConfig } from '../../transport';
+/**
+ * Gun constructor type (from gun library).
+ */
+export type GunConstructor = any;
+/**
+ * Configuration options for Gun transport.
+ */
+export interface GunTransportOptions {
+    /**
+     * The Gun library constructor.
+     * Users must provide this to avoid bundling the library.
+     * @example
+     * ```typescript
+     * import Gun from 'gun'
+     * const transport = new GunTransport({ gun: Gun })
+     * ```
+     */
+    gun: GunConstructor;
+    /**
+     * Array of peer relay servers to connect to.
+     * Gun will attempt to sync with these peers and any peers they know about.
+     * @default [] (local only)
+     * @example ['https://gun-relay.herokuapp.com/gun']
+     */
+    peers?: string[];
+    /**
+     * Gun configuration options.
+     * @see https://gun.eco/docs/API
+     */
+    gunOptions?: {
+        localStorage?: boolean;
+        radisk?: boolean;
+        axe?: boolean;
+        [key: string]: any;
+    };
+    /**
+     * Enable debug logging.
+     * @default false
+     */
+    debug?: boolean;
+    /**
+     * Update batch interval in milliseconds.
+     * Uses debouncing - timer resets on each update.
+     * Only sends after this period of inactivity.
+     * @default 100
+     */
+    batchInterval?: number;
+    /**
+     * Password for room encryption.
+     * When set, all data is encrypted with AES using Gun's SEA module.
+     * All peers in the room must use the same password.
+     * Requires the SEA module to be provided.
+     * @default undefined (no encryption)
+     * @example 'my-secret-password'
+     */
+    password?: string;
+    /**
+     * Gun SEA (Security, Encryption, Authorization) module.
+     * Required when using password encryption.
+     * @example
+     * ```typescript
+     * import Gun from 'gun'
+     * import 'gun/sea'
+     * const SEA = Gun.SEA
+     * const transport = new GunTransport({ gun: Gun, sea: SEA, password: 'secret' })
+     * ```
+     */
+    sea?: any;
+}
+/**
+ * Extended connection config with optional persistence settings.
+ */
+export interface GunConnectionConfig extends ConnectionConfig {
+    /**
+     * When true, a full Y.Doc snapshot is saved to Gun on every debounced
+     * update and loaded back when peers reconnect after all going offline.
+     * When false (default), any previously stored snapshot is cleared on
+     * connect so new sessions start from a blank state.
+     * @default false
+     */
+    persistent?: boolean;
+    /**
+     * The Y.Doc to snapshot. Required when persistent is true.
+     */
+    doc?: Y.Doc;
+    /**
+     * Debounce delay in ms before writing the snapshot to Gun.
+     * @default 2000
+     */
+    persistDebounceMs?: number;
+}
+/**
+ * GunDB transport implementation.
+ * Creates decentralized P2P connections using Gun graph database.
+ */
+export declare class GunTransport implements Transport {
+    private options;
+    private _connected;
+    private _room;
+    private _callback?;
+    private gun;
+    private roomNode;
+    private updateListener;
+    private lastUpdateTime;
+    private updateBatch;
+    private batchTimeout?;
+    private processedUpdates;
+    private connectionTime;
+    private throttleTimeout?;
+    private pendingUpdates;
+    private updateSlot;
+    private readonly BUFFER_SIZE;
+    private awarenessListener;
+    private lastAwarenessId;
+    private encryptionEnabled;
+    private persistentMode;
+    private persistDoc;
+    private persistDebounceMs;
+    private persistTimer?;
+    private isWritingToGun;
+    private savePending;
+    /** Data loaded from Gun snapshot before onMessage callback is registered */
+    private pendingLoad;
+    /**
+     * Create a new Gun transport.
+     *
+     * @param options - Configuration options (must include gun constructor)
+     */
+    constructor(options: GunTransportOptions);
+    /**
+     * Connect to the room and start syncing.
+     */
+    connect(config: GunConnectionConfig): Promise<void>;
+    /**
+     * Setup listener for Gun updates.
+     */
+    private setupUpdateListener;
+    /**
+     * Process all pending updates at once.
+     */
+    private processPendingUpdates;
+    /**
+     * Disconnect from Gun and cleanup.
+     */
+    disconnect(): void;
+    /**
+     * Send data to all peers via Gun.
+     * Routes awareness to a separate volatile node, doc sync to circular buffer.
+     * Uses debouncing for doc sync - each new update resets the timer.
+     */
+    send(data: Uint8Array): void;
+    /**
+     * Peek at the message type from CRC32-wrapped data.
+     * Format: [CRC32 (4 bytes)][message type (varint)]...
+     * Returns -1 if cannot determine type.
+     */
+    private peekMessageType;
+    /**
+     * Send awareness update to a separate volatile node.
+     * Awareness is ephemeral - only the latest state matters.
+     * Each client writes to its own awareness slot to avoid overwrites.
+     */
+    private sendAwareness;
+    /**
+     * Setup listener for awareness updates (separate from doc sync).
+     */
+    private setupAwarenessListener;
+    /**
+     * Flush batched updates to Gun.
+     * Called after debounce period (no new updates for batchInterval ms).
+     */
+    private flushBatch;
+    /**
+     * Register callback for incoming messages.
+     */
+    onMessage(callback: (data: Uint8Array) => void): () => void;
+    /**
+     * Check if connected.
+     */
+    get isConnected(): boolean;
+    /**
+     * Generate a circular buffer slot ID.
+     * Uses only BUFFER_SIZE slots to prevent infinite accumulation.
+     */
+    private generateUpdateId;
+    /**
+     * Schedule a debounced snapshot write. Called on every doc update.
+     * Always saves the latest full state, never an individual delta.
+     */
+    private queuePersist;
+    /**
+     * Encode the full Y.Doc state as a proper y-protocols SYNC_STEP_2 message
+     * and write it to the Gun `snapshot` node.
+     * Using SYNC_STEP_2 format ensures GenericProvider interprets it correctly.
+     */
+    private saveSnapshot;
+    /**
+     * Load the snapshot from Gun and deliver it to the message callback.
+     * Uses a pendingLoad buffer in case the callback isn't registered yet.
+     */
+    private loadSnapshot;
+    /**
+     * Convert Uint8Array to base64 string.
+     */
+    private uint8ArrayToBase64;
+    /**
+     * Convert base64 string to Uint8Array.
+     */
+    private base64ToUint8Array;
+    /**
+     * Encrypt data using SEA with the configured password.
+     */
+    private encrypt;
+    /**
+     * Decrypt data using SEA with the configured password.
+     * Returns null if decryption fails (wrong password).
+     */
+    private decrypt;
+    /**
+     * Log debug messages if enabled.
+     */
+    private log;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/providers/gun/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/providers/gun/index.ts"],"names":[],"mappings":"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"}