@prabhask5/stellar-engine 1.1.18 → 1.2.1

package/dist/crdt/persistence.js

@@ -0,0 +1,171 @@
+/**
+ * @fileoverview CRDT Supabase Persistence
+ *
+ * Handles durable persistence of Yjs document state to the Supabase
+ * `crdt_documents` table. This is the long-term storage layer — the
+ * "source of truth" that survives device loss, browser data clearing,
+ * and cross-device sync.
+ *
+ * Key behaviors:
+ *   - {@link persistDocument} — Upserts full Yjs state to Supabase
+ *   - {@link persistAllDirty} — Persists all active dirty documents
+ *   - {@link fetchRemoteState} — Fetches latest state for initial load / sync
+ *   - Binary state is base64-encoded for Supabase REST transport
+ *   - Skips unchanged documents (compares state vectors)
+ *   - Updates `lastPersistedAt` in IndexedDB on success
+ *   - Clears pending updates after successful persist
+ *
+ * Timing:
+ *   - Periodic persist: every `persistIntervalMs` (default 30s)
+ *   - On document close (if dirty and online)
+ *   - On offline → online reconnection (immediate)
+ *
+ * @see {@link ./provider.ts} for the timer that triggers periodic persists
+ * @see {@link ./store.ts} for IndexedDB operations
+ * @see {@link ./config.ts} for timing configuration
+ */
+import * as Y from 'yjs';
+import { supabase } from '../supabase/client';
+import { getDeviceId } from '../deviceId';
+import { debugLog, debugWarn } from '../debug';
+import { getCRDTConfig } from './config';
+import { clearPendingUpdates, saveDocumentState, loadDocumentState } from './store';
+import { getActiveProvider } from './provider';
+// =============================================================================
+//  Binary ↔ Base64 Encoding
+// =============================================================================
+/**
+ * Encode a `Uint8Array` to a base64 string for Supabase REST transport.
+ */
+function uint8ToBase64(bytes) {
+    let binary = '';
+    for (let i = 0; i < bytes.length; i++) {
+        binary += String.fromCharCode(bytes[i]);
+    }
+    return btoa(binary);
+}
+/**
+ * Decode a base64 string back to a `Uint8Array`.
+ */
+function base64ToUint8(base64) {
+    const binary = atob(base64);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) {
+        bytes[i] = binary.charCodeAt(i);
+    }
+    return bytes;
+}
+// =============================================================================
+//  Supabase Persistence
+// =============================================================================
+/**
+ * Persist a Yjs document's full state to Supabase.
+ *
+ * Performs an upsert: if a row for this `page_id` already exists, it is
+ * updated; otherwise a new row is created. The upsert key is `page_id`
+ * (unique per user via RLS).
+ *
+ * On success:
+ *   - Clears `crdtPendingUpdates` for this document in IndexedDB
+ *   - Updates `lastPersistedAt` in the local `crdtDocuments` record
+ *
+ * @param documentId - The document identifier (for logging and IndexedDB updates).
+ * @param doc - The Yjs document to persist.
+ *
+ * @throws {Error} If the Supabase upsert fails.
+ */
+export async function persistDocument(documentId, doc) {
+    const config = getCRDTConfig();
+    const state = Y.encodeStateAsUpdate(doc);
+    const stateVector = Y.encodeStateVector(doc);
+    const deviceId = getDeviceId();
+    /* Find the pageId from the active provider. */
+    const provider = getActiveProvider(documentId);
+    if (!provider) {
+        debugWarn(`[CRDT] Document ${documentId}: cannot persist — no active provider`);
+        return;
+    }
+    debugLog(`[CRDT] Document ${documentId}: persisting to Supabase (${state.byteLength} bytes)`);
+    const { error } = await supabase.from(config.supabaseTable).upsert({
+        page_id: provider.pageId,
+        state: uint8ToBase64(state),
+        state_vector: uint8ToBase64(stateVector),
+        state_size: state.byteLength,
+        device_id: deviceId
+    }, { onConflict: 'page_id' });
+    if (error) {
+        debugWarn(`[CRDT] Document ${documentId}: Supabase persist failed: ${error.message}`);
+        throw error;
+    }
+    /* Clear pending updates from IndexedDB (now captured in Supabase). */
+    const cleared = await clearPendingUpdates(documentId);
+    debugLog(`[CRDT] Document ${documentId}: Supabase persist success (cleared ${cleared} pending updates)`);
+    /* Update lastPersistedAt in IndexedDB. */
+    const localRecord = await loadDocumentState(documentId);
+    if (localRecord) {
+        localRecord.lastPersistedAt = new Date().toISOString();
+        await saveDocumentState(localRecord);
+    }
+}
+/**
+ * Persist all active dirty documents to Supabase.
+ *
+ * Iterates all active providers, checks if they are dirty, and persists
+ * each one. Errors are caught per-document to avoid one failure blocking others.
+ *
+ * Useful as a manual "save all" action or for pre-close cleanup.
+ */
+export async function persistAllDirty() {
+    /*
+     * Dynamic import to avoid circular dependency at module load time.
+     * The provider module imports from persistence (this file), so we cannot
+     * statically import the provider registry here. Dynamic import breaks the cycle.
+     */
+    const { getActiveProviderEntries } = await import('./provider');
+    const entries = getActiveProviderEntries();
+    let persisted = 0;
+    for (const [documentId, provider] of entries) {
+        if (!provider.isDirty)
+            continue;
+        try {
+            await persistDocument(documentId, provider.doc);
+            persisted++;
+        }
+        catch (e) {
+            debugWarn(`[CRDT] persistAllDirty: failed for document ${documentId}:`, e);
+        }
+    }
+    debugLog(`[CRDT] persistAllDirty: persisted ${persisted} documents`);
+}
+// =============================================================================
+//  Supabase Fetch
+// =============================================================================
+/**
+ * Fetch the latest CRDT document state from Supabase by page ID.
+ *
+ * Used during `openDocument` when no local state exists and the device is
+ * online. Returns the raw Yjs binary state ready to be applied via
+ * `Y.applyUpdate(doc, state)`.
+ *
+ * @param pageId - The page/entity ID to fetch the document for.
+ * @returns The Yjs state as a `Uint8Array`, or `null` if no document exists.
+ */
+export async function fetchRemoteState(pageId) {
+    const config = getCRDTConfig();
+    const { data, error } = await supabase
+        .from(config.supabaseTable)
+        .select('state')
+        .eq('page_id', pageId)
+        .maybeSingle();
+    if (error) {
+        debugWarn(`[CRDT] Failed to fetch remote state for page ${pageId}: ${error.message}`);
+        return null;
+    }
+    if (!data?.state) {
+        return null;
+    }
+    const state = base64ToUint8(data.state);
+    debugLog(`[CRDT] Fetched remote state for page ${pageId} (${state.byteLength} bytes)`);
+    return state;
+}
+//# sourceMappingURL=persistence.js.map

package/dist/crdt/persistence.js.map

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

package/dist/crdt/provider.d.ts

@@ -0,0 +1,109 @@
+/**
+ * @fileoverview CRDT Document Provider — Per-Document Lifecycle Manager
+ *
+ * The `CRDTProvider` is the central orchestrator for a single collaborative
+ * document. It manages:
+ *   - Yjs `Y.Doc` creation and state loading (from IndexedDB or Supabase)
+ *   - Wiring `doc.on('update')` to persistence, broadcast, and crash recovery
+ *   - Supabase Broadcast channel for real-time update distribution
+ *   - Periodic Supabase persistence timer
+ *   - Local IndexedDB full-state saves (debounced)
+ *   - Document lifecycle (open → edit → close → destroy)
+ *
+ * Module-level `Map<string, CRDTProvider>` tracks all active providers.
+ * Factory functions {@link openDocument} / {@link closeDocument} manage the lifecycle.
+ *
+ * @see {@link ./channel.ts} for Broadcast channel management
+ * @see {@link ./store.ts} for IndexedDB persistence
+ * @see {@link ./persistence.ts} for Supabase persistence
+ * @see {@link ./awareness.ts} for cursor/presence management
+ *
+ * @example
+ * import { openDocument, closeDocument } from '@prabhask5/stellar-engine/crdt';
+ *
+ * const provider = await openDocument('doc-1', 'page-1', { offlineEnabled: true });
+ * // provider.doc is a Y.Doc — use with your editor
+ * // ...
+ * await closeDocument('doc-1');
+ */
+import * as Y from 'yjs';
+import type { CRDTConnectionState, OpenDocumentOptions } from './types';
+/**
+ * Public interface for a CRDT document provider.
+ *
+ * Consumers receive this from {@link openDocument}. All mutable state
+ * (timers, channels, pending updates) is hidden in the implementation.
+ */
+export interface CRDTProvider {
+    /** The Yjs document instance — use with your editor. */
+    readonly doc: Y.Doc;
+    /** Unique document identifier. */
+    readonly documentId: string;
+    /** The page/entity this document belongs to. */
+    readonly pageId: string;
+    /** Current Broadcast channel connection state. */
+    readonly connectionState: CRDTConnectionState;
+    /** Whether the document has unsaved changes. */
+    readonly isDirty: boolean;
+    /** Destroy this provider and release all resources. */
+    destroy(): Promise<void>;
+}
+/**
+ * Open a collaborative CRDT document.
+ *
+ * Creates a new `CRDTProvider` for the document, loads its initial state
+ * (from IndexedDB or Supabase), wires update handlers, joins the Broadcast
+ * channel, and starts the periodic persist timer.
+ *
+ * **Idempotent:** If the document is already open, returns the existing provider.
+ *
+ * @param documentId - Unique identifier for the document.
+ * @param pageId - The page/entity this document belongs to.
+ * @param options - Optional configuration (offline mode, initial presence).
+ * @returns The active `CRDTProvider` for this document.
+ *
+ * @throws {Error} If CRDT is not configured in `initEngine()`.
+ *
+ * @example
+ * const provider = await openDocument('doc-1', 'page-1', {
+ *   offlineEnabled: true,
+ *   initialPresence: { name: 'Alice' },
+ * });
+ * const text = provider.doc.getText('content');
+ */
+export declare function openDocument(documentId: string, pageId: string, options?: OpenDocumentOptions): Promise<CRDTProvider>;
+/**
+ * Close a specific CRDT document.
+ *
+ * Saves final state, persists to Supabase if dirty, leaves the Broadcast
+ * channel, and destroys the Y.Doc.
+ *
+ * @param documentId - The document to close.
+ */
+export declare function closeDocument(documentId: string): Promise<void>;
+/**
+ * Close all active CRDT documents.
+ *
+ * Called during sign-out to ensure all documents are properly saved and
+ * all channels are cleaned up. Each document is closed in parallel.
+ */
+export declare function closeAllDocuments(): Promise<void>;
+/**
+ * Get the active provider for a document, if open.
+ *
+ * @param documentId - The document to look up.
+ * @returns The active provider, or `undefined` if not open.
+ * @internal
+ */
+export declare function getActiveProvider(documentId: string): CRDTProvider | undefined;
+/**
+ * Get all active provider entries for iteration.
+ *
+ * Used by {@link persistence.ts#persistAllDirty} to iterate and persist
+ * all dirty documents. Returns `[documentId, provider]` pairs.
+ *
+ * @returns Iterator of `[documentId, CRDTProvider]` entries.
+ * @internal
+ */
+export declare function getActiveProviderEntries(): IterableIterator<[string, CRDTProvider]>;
+//# sourceMappingURL=provider.d.ts.map

package/dist/crdt/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../../src/crdt/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AAczB,OAAO,KAAK,EAAE,mBAAmB,EAAsB,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAoB5F;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,wDAAwD;IACxD,QAAQ,CAAC,GAAG,EAAE,CAAC,CAAC,GAAG,CAAC;IACpB,kCAAkC;IAClC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,gDAAgD;IAChD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,kDAAkD;IAClD,QAAQ,CAAC,eAAe,EAAE,mBAAmB,CAAC;IAC9C,gDAAgD;IAChD,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,uDAAuD;IACvD,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AA8eD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,YAAY,CAChC,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,mBAAwB,GAChC,OAAO,CAAC,YAAY,CAAC,CAuBvB;AAED;;;;;;;GAOG;AACH,wBAAsB,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAIrE;AAED;;;;;GAKG;AACH,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC,CAQvD;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS,CAE9E;AAED;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,IAAI,gBAAgB,CAAC,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC,CAEnF"}