@korajs/react 0.3.2 → 0.5.0

package/dist/index.js

@@ -8,12 +8,8 @@ function KoraProvider({
   fallback,
   children
 }) {
-  const [resolvedStore, setResolvedStore] = useState(
-    store ?? null
-  );
-  const [resolvedSync, setResolvedSync] = useState(
-    syncEngine ?? null
-  );
+  const [resolvedStore, setResolvedStore] = useState(store ?? null);
+  const [resolvedSync, setResolvedSync] = useState(syncEngine ?? null);
   const [ready, setReady] = useState(!app);
   const [initError, setInitError] = useState(null);
   useEffect(() => {
@@ -52,7 +48,10 @@ function KoraProvider({
   }
   const value = {
     store: resolvedStore,
-    syncEngine: resolvedSync
+    syncEngine: resolvedSync,
+    app: app ?? null,
+    events: app?.events ?? null,
+    subscribeSyncStatus: app?.sync?.subscribeStatus ?? null
   };
   return createElement(KoraContext.Provider, { value }, children);
 }
@@ -66,6 +65,17 @@ function useKoraContext() {
   return context;
 }
 
+// src/hooks/use-app.ts
+function useApp() {
+  const { app } = useKoraContext();
+  if (!app) {
+    throw new Error(
+      'useApp() requires KoraProvider to be initialized with an "app" prop. Pass your createApp() result to <KoraProvider app={app}>.'
+    );
+  }
+  return app;
+}
+
 // src/hooks/use-query.ts
 import { useMemo, useRef, useSyncExternalStore } from "react";
 
@@ -141,6 +151,18 @@ var QueryStore = class {
 };
 
 // src/hooks/use-query.ts
+var APP_NOT_READY_CODE = "APP_NOT_READY";
+function assertQueryReady(query) {
+  const descriptor = query.getDescriptor();
+  if (descriptor.collection === "__pending__") {
+    const err = new Error(
+      "Cannot use useQuery() before app.ready. Await app.ready or wrap your UI in <KoraProvider app={app}>."
+    );
+    err.name = "AppNotReadyError";
+    Object.assign(err, { code: APP_NOT_READY_CODE });
+    throw err;
+  }
+}
 var EMPTY_ARRAY2 = Object.freeze([]);
 var noopSubscribe = (_onStoreChange) => {
   return () => {
@@ -148,6 +170,9 @@ var noopSubscribe = (_onStoreChange) => {
 };
 function useQuery(query, options) {
   const enabled = options?.enabled !== false;
+  if (enabled) {
+    assertQueryReady(query);
+  }
   const descriptorKey = JSON.stringify(query.getDescriptor());
   const queryStoreRef = useRef(null);
   const prevKeyRef = useRef(null);
@@ -180,7 +205,7 @@ function useQuery(query, options) {
 
 // src/hooks/use-mutation.ts
 import { useCallback, useEffect as useEffect2, useRef as useRef2, useState as useState2 } from "react";
-function useMutation(mutationFn) {
+function useMutation(mutationFn, options) {
   const [state, setState] = useState2({
     isLoading: false,
     error: null
@@ -194,21 +219,35 @@ function useMutation(mutationFn) {
   }, []);
   const fnRef = useRef2(mutationFn);
   fnRef.current = mutationFn;
+  const optionsRef = useRef2(options);
+  optionsRef.current = options;
   const mutateAsync = useCallback(async (...args) => {
+    const opts = optionsRef.current;
+    let context;
     if (mountedRef.current) {
       setState({ isLoading: true, error: null });
     }
     try {
+      if (opts?.onMutate) {
+        context = await opts.onMutate(...args);
+      }
       const result = await fnRef.current(...args);
       if (mountedRef.current) {
         setState({ isLoading: false, error: null });
       }
+      opts?.onSuccess?.(result, ...args);
+      opts?.onSettled?.(result, null, ...args);
       return result;
     } catch (err) {
       const error = err instanceof Error ? err : new Error(String(err));
+      if (context !== void 0 && opts?.onRollback) {
+        await opts.onRollback(context, ...args);
+      }
       if (mountedRef.current) {
         setState({ isLoading: false, error });
       }
+      opts?.onError?.(error, ...args);
+      opts?.onSettled?.(void 0, error, ...args);
       throw error;
     }
   }, []);
@@ -234,22 +273,45 @@ function useMutation(mutationFn) {
 }
 
 // src/hooks/use-sync-status.ts
-import { useCallback as useCallback2, useEffect as useEffect3, useRef as useRef3, useSyncExternalStore as useSyncExternalStore2 } from "react";
-var POLL_INTERVAL_MS = 500;
+import { useCallback as useCallback2, useRef as useRef3, useSyncExternalStore as useSyncExternalStore2 } from "react";
 var OFFLINE_STATUS = Object.freeze({
   status: "offline",
   pendingOperations: 0,
-  lastSyncedAt: null
+  lastSyncedAt: null,
+  lastSuccessfulPush: null,
+  lastSuccessfulPull: null,
+  conflicts: 0
 });
+var SYNC_STATUS_EVENT_TYPES = [
+  "sync:connected",
+  "sync:disconnected",
+  "sync:schema-mismatch",
+  "sync:auth-failed",
+  "sync:sent",
+  "sync:received",
+  "sync:acknowledged",
+  "sync:apply-failed",
+  "sync:diagnostics",
+  "sync:initial-sync-progress"
+];
 function useSyncStatus() {
-  const { syncEngine } = useKoraContext();
+  const { syncEngine, subscribeSyncStatus, events } = useKoraContext();
   const snapshotRef = useRef3(OFFLINE_STATUS);
   const serializedRef = useRef3(JSON.stringify(OFFLINE_STATUS));
   const subscribe = useCallback2(
     (onStoreChange) => {
-      if (!syncEngine) return () => {
-      };
-      const intervalId = setInterval(() => {
+      if (subscribeSyncStatus) {
+        return subscribeSyncStatus((status) => {
+          snapshotRef.current = status;
+          serializedRef.current = JSON.stringify(status);
+          onStoreChange();
+        });
+      }
+      if (!syncEngine) {
+        return () => {
+        };
+      }
+      const refresh = () => {
         const newStatus = syncEngine.getStatus();
         const newSerialized = JSON.stringify(newStatus);
         if (newSerialized !== serializedRef.current) {
@@ -257,29 +319,28 @@ function useSyncStatus() {
           serializedRef.current = newSerialized;
           onStoreChange();
         }
-      }, POLL_INTERVAL_MS);
-      const initialStatus = syncEngine.getStatus();
-      const initialSerialized = JSON.stringify(initialStatus);
-      if (initialSerialized !== serializedRef.current) {
-        snapshotRef.current = initialStatus;
-        serializedRef.current = initialSerialized;
-        onStoreChange();
+      };
+      if (events) {
+        const unsubs = SYNC_STATUS_EVENT_TYPES.map((type) => events.on(type, refresh));
+        refresh();
+        return () => {
+          for (const unsub of unsubs) {
+            unsub();
+          }
+        };
       }
+      refresh();
       return () => {
-        clearInterval(intervalId);
       };
     },
-    [syncEngine]
+    [syncEngine, subscribeSyncStatus, events]
   );
   const getSnapshot = useCallback2(() => {
-    return snapshotRef.current;
-  }, []);
-  useEffect3(() => {
-    if (!syncEngine) {
-      snapshotRef.current = OFFLINE_STATUS;
-      serializedRef.current = JSON.stringify(OFFLINE_STATUS);
+    if (subscribeSyncStatus) {
+      return snapshotRef.current;
     }
-  }, [syncEngine]);
+    return syncEngine ? syncEngine.getStatus() : OFFLINE_STATUS;
+  }, [syncEngine, subscribeSyncStatus]);
   return useSyncExternalStore2(subscribe, getSnapshot);
 }
 
@@ -293,21 +354,35 @@ function useCollection(name) {
 }
 
 // src/hooks/use-rich-text.ts
-import { useCallback as useCallback3, useEffect as useEffect4, useMemo as useMemo3, useRef as useRef4, useState as useState3 } from "react";
+import { encodeRichtext } from "@korajs/store";
+import { useCallback as useCallback3, useEffect as useEffect3, useMemo as useMemo3, useRef as useRef4, useState as useState3 } from "react";
 import * as Y from "yjs";
 var LOAD_ORIGIN = "kora-load";
+var REMOTE_ORIGIN = "kora-remote";
+var DOC_CHANNEL_ORIGIN = "kora-doc-channel";
 var TEXT_KEY = "content";
 var COMPACT_AFTER_DELTAS = 20;
-function useRichText(collectionName, recordId, fieldName) {
-  const { store } = useKoraContext();
-  const collection = useMemo3(() => store.collection(collectionName), [store, collectionName]);
+var PERSIST_DEBOUNCE_MS = 400;
+function useRichText(collectionName, recordId, fieldName, options) {
+  const { store, syncEngine } = useKoraContext();
+  const collection = useMemo3(
+    () => store.collection(collectionName),
+    [store, collectionName]
+  );
   const [doc] = useState3(() => new Y.Doc());
   const [ready, setReady] = useState3(false);
   const [error, setError] = useState3(null);
   const [canUndo, setCanUndo] = useState3(false);
   const [canRedo, setCanRedo] = useState3(false);
+  const [cursors, setCursors] = useState3([]);
   const baseUpdateRef = useRef4(null);
   const pendingDeltasRef = useRef4([]);
+  const docChannelActiveRef = useRef4(false);
+  const persistTimerRef = useRef4(null);
+  const userRef = useRef4(options?.user);
+  useEffect3(() => {
+    userRef.current = options?.user;
+  }, [options?.user]);
   const text = useMemo3(() => doc.getText(TEXT_KEY), [doc]);
   const undoManager = useMemo3(() => new Y.UndoManager(text), [text]);
   const syncHistoryState = useCallback3(() => {
@@ -322,7 +397,73 @@ function useRichText(collectionName, recordId, fieldName) {
     undoManager.redo();
     syncHistoryState();
   }, [syncHistoryState, undoManager]);
-  useEffect4(() => {
+  const resolveAwarenessUser = useCallback3(() => {
+    if (userRef.current) {
+      return userRef.current;
+    }
+    if (syncEngine) {
+      const existing = syncEngine.getAwarenessManager().getLocalState()?.user;
+      if (existing) {
+        return existing;
+      }
+    }
+    return {
+      name: "Anonymous",
+      color: "#6366f1"
+    };
+  }, [syncEngine]);
+  const setCursor = useCallback3(
+    (anchor, head) => {
+      if (!syncEngine) {
+        return;
+      }
+      const awareness = syncEngine.getAwarenessManager();
+      const state = {
+        user: resolveAwarenessUser(),
+        cursor: {
+          collection: collectionName,
+          recordId,
+          field: fieldName,
+          anchor,
+          head
+        }
+      };
+      awareness.setLocalState(state);
+    },
+    [collectionName, fieldName, recordId, resolveAwarenessUser, syncEngine]
+  );
+  const clearCursor = useCallback3(() => {
+    if (!syncEngine) {
+      return;
+    }
+    const awareness = syncEngine.getAwarenessManager();
+    const current = awareness.getLocalState();
+    if (!current?.cursor) {
+      return;
+    }
+    if (current.cursor.collection !== collectionName || current.cursor.recordId !== recordId || current.cursor.field !== fieldName) {
+      return;
+    }
+    awareness.setLocalState({ user: current.user });
+  }, [collectionName, fieldName, recordId, syncEngine]);
+  const applyRemoteSnapshot = useCallback3(
+    (value) => {
+      const encoded = encodeRichtextInput(value);
+      if (!encoded) {
+        return;
+      }
+      const currentSnapshot = Y.encodeStateAsUpdate(doc);
+      if (updatesEqual(currentSnapshot, encoded)) {
+        return;
+      }
+      Y.applyUpdate(doc, encoded, REMOTE_ORIGIN);
+      baseUpdateRef.current = encoded;
+      pendingDeltasRef.current = [];
+      syncHistoryState();
+    },
+    [doc, syncHistoryState]
+  );
+  useEffect3(() => {
     let disposed = false;
     const initialize = async () => {
       setReady(false);
@@ -340,18 +481,15 @@ function useRichText(collectionName, recordId, fieldName) {
         if (encoded) {
           Y.applyUpdate(doc, encoded, LOAD_ORIGIN);
         }
+        const channel = syncEngine?.getRichtextDocChannel?.();
+        docChannelActiveRef.current = channel?.shouldUseChannel(encoded?.length ?? 0, options?.useDocChannel) ?? false;
         setReady(true);
       } catch (cause) {
         if (disposed) return;
         setError(cause instanceof Error ? cause : new Error(String(cause)));
       }
     };
-    const persist = async (_update, origin) => {
-      syncHistoryState();
-      if (origin === LOAD_ORIGIN) {
-        return;
-      }
-      pendingDeltasRef.current.push(_update);
+    const flushPersist = async () => {
       const snapshot = composeRichtextSnapshot(baseUpdateRef.current, pendingDeltasRef.current);
       if (pendingDeltasRef.current.length >= COMPACT_AFTER_DELTAS) {
         baseUpdateRef.current = snapshot;
@@ -367,54 +505,150 @@ function useRichText(collectionName, recordId, fieldName) {
         }
       }
     };
+    const schedulePersist = () => {
+      if (persistTimerRef.current) {
+        clearTimeout(persistTimerRef.current);
+      }
+      persistTimerRef.current = setTimeout(() => {
+        persistTimerRef.current = null;
+        void flushPersist();
+      }, PERSIST_DEBOUNCE_MS);
+    };
+    const persist = (_update, origin) => {
+      syncHistoryState();
+      if (origin === LOAD_ORIGIN || origin === REMOTE_ORIGIN || origin === DOC_CHANNEL_ORIGIN) {
+        return;
+      }
+      pendingDeltasRef.current.push(_update);
+      if (docChannelActiveRef.current && syncEngine) {
+        syncEngine.getRichtextDocChannel().send(collectionName, recordId, fieldName, _update);
+        schedulePersist();
+        return;
+      }
+      void flushPersist();
+    };
     doc.on("update", persist);
     void initialize();
     syncHistoryState();
     return () => {
       disposed = true;
+      if (persistTimerRef.current) {
+        clearTimeout(persistTimerRef.current);
+        persistTimerRef.current = null;
+      }
       doc.off("update", persist);
       undoManager.destroy();
       baseUpdateRef.current = null;
       pendingDeltasRef.current = [];
+      docChannelActiveRef.current = false;
+    };
+  }, [
+    collection,
+    collectionName,
+    doc,
+    fieldName,
+    options?.useDocChannel,
+    recordId,
+    syncEngine,
+    syncHistoryState,
+    undoManager
+  ]);
+  useEffect3(() => {
+    if (!ready || !syncEngine || !docChannelActiveRef.current) {
+      return;
+    }
+    const channel = syncEngine.getRichtextDocChannel();
+    return channel.subscribe(collectionName, recordId, fieldName, (update) => {
+      Y.applyUpdate(doc, update, DOC_CHANNEL_ORIGIN);
+      syncHistoryState();
+    });
+  }, [collectionName, doc, fieldName, ready, recordId, syncEngine, syncHistoryState]);
+  useEffect3(() => {
+    if (!ready) {
+      return;
+    }
+    const unsubscribe = store.collection(collectionName).where({ id: recordId }).subscribe((results) => {
+      const record = results[0];
+      if (!record) {
+        return;
+      }
+      applyRemoteSnapshot(record[fieldName]);
+    });
+    return unsubscribe;
+  }, [applyRemoteSnapshot, collectionName, fieldName, ready, recordId, store]);
+  useEffect3(() => {
+    if (!syncEngine) return;
+    const awareness = syncEngine.getAwarenessManager();
+    const localClientId = awareness.clientId;
+    const updateCursors = () => {
+      const states = awareness.getStates();
+      const fieldCursors = [];
+      for (const [clientId, state] of states) {
+        if (clientId === localClientId) continue;
+        if (!state.cursor) continue;
+        if (state.cursor.collection !== collectionName || state.cursor.recordId !== recordId || state.cursor.field !== fieldName) {
+          continue;
+        }
+        fieldCursors.push({
+          clientId,
+          userName: state.user.name,
+          color: state.user.color,
+          anchor: state.cursor.anchor,
+          head: state.cursor.head
+        });
+      }
+      setCursors(fieldCursors);
+    };
+    const unsubscribe = awareness.on("change", () => {
+      updateCursors();
+    });
+    updateCursors();
+    return () => {
+      unsubscribe();
+      clearCursor();
     };
-  }, [collection, doc, fieldName, recordId, syncHistoryState, undoManager]);
-  return { doc, text, undo, redo, canUndo, canRedo, ready, error };
+  }, [clearCursor, collectionName, fieldName, recordId, syncEngine]);
+  return { doc, text, undo, redo, canUndo, canRedo, ready, error, cursors, setCursor, clearCursor };
 }
 function encodeRichtextInput(value) {
   if (value === null || value === void 0) {
     return null;
   }
-  if (typeof value === "string") {
-    const doc = new Y.Doc();
-    doc.getText(TEXT_KEY).insert(0, value);
-    return Y.encodeStateAsUpdate(doc);
-  }
-  if (value instanceof Uint8Array) {
-    return value;
-  }
-  if (value instanceof ArrayBuffer) {
-    return new Uint8Array(value);
-  }
-  if (typeof globalThis !== "undefined" && "Buffer" in globalThis) {
-    const BufferCtor = globalThis.Buffer;
-    if (BufferCtor.isBuffer(value)) {
-      return new Uint8Array(value.buffer, value.byteOffset, value.byteLength);
+  try {
+    return encodeRichtext(value);
+  } catch {
+    if (typeof value === "string") {
+      const fallbackDoc = new Y.Doc();
+      fallbackDoc.getText(TEXT_KEY).insert(0, value);
+      return Y.encodeStateAsUpdate(fallbackDoc);
     }
+    throw new Error("Richtext record value must be a string, Uint8Array, ArrayBuffer, or null.");
   }
-  throw new Error("Richtext record value must be a string, Uint8Array, ArrayBuffer, or null.");
 }
 function composeRichtextSnapshot(base, deltas) {
-  const doc = new Y.Doc();
+  const mergedDoc = new Y.Doc();
   if (base) {
-    Y.applyUpdate(doc, base);
+    Y.applyUpdate(mergedDoc, base);
   }
   for (const delta of deltas) {
-    Y.applyUpdate(doc, delta);
+    Y.applyUpdate(mergedDoc, delta);
+  }
+  return Y.encodeStateAsUpdate(mergedDoc);
+}
+function updatesEqual(left, right) {
+  if (left.length !== right.length) {
+    return false;
+  }
+  for (let index = 0; index < left.length; index++) {
+    if (left[index] !== right[index]) {
+      return false;
+    }
   }
-  return Y.encodeStateAsUpdate(doc);
+  return true;
 }
 export {
   KoraProvider,
+  useApp,
   useCollection,
   useMutation,
   useQuery,