@korajs/react 1.0.0-beta.11 → 1.0.0-beta.13

package/README.md

@@ -1,70 +1,78 @@
 # @korajs/react
 
-React hooks and bindings for Kora.js. Reactive queries that update automatically, optimistic mutations, sync status tracking, and rich text editing support.
+React bindings for Kora.js: a provider, reactive queries, mutations, sync status, rich text and
+presence. Hooks use `useSyncExternalStore`, so they are safe in concurrent rendering, StrictMode and
+server rendering.
 
 ## Install
 
 ```bash
-pnpm add korajs @korajs/react
+pnpm add korajs@beta @korajs/react@beta
 ```
 
 ## Usage
 
-### Provider
+<!-- docs-check-prelude
+import { createApp, defineSchema, t } from 'korajs'
+const schema = defineSchema({
+  version: 1,
+  collections: { todos: { fields: { title: t.string(), completed: t.boolean().default(false), createdAt: t.timestamp().auto() } } },
+})
+const app = createApp({ schema })
+-->
 
 ```tsx
-import { KoraProvider } from '@korajs/react'
+import { createKoraHooks, KoraProvider } from '@korajs/react'
 
-function App() {
+// Hooks typed by your schema
+const { useCollection, useMutation, useQuery, useSyncStatus } = createKoraHooks<typeof app>()
+
+export function Root() {
   return (
-    <KoraProvider app={app}>
+    <KoraProvider app={app} fallback={<p>Loading...</p>}>
       <TodoList />
     </KoraProvider>
   )
 }
-```
-
-### Reactive Queries
-
-```tsx
-import { useQuery } from '@korajs/react'
 
 function TodoList() {
-  const todos = useQuery(app.todos.where({ completed: false }).orderBy('createdAt'))
-  // Always up to date. No loading state needed for local data.
-
-  return todos.map((todo) => <TodoItem key={todo.id} todo={todo} />)
-}
-```
-
-### Mutations
-
-```tsx
-import { useMutation } from '@korajs/react'
-
-function AddTodo() {
-  const addTodo = useMutation(app.todos.insert)
+  const todos = useCollection('todos')
+  const open = useQuery(todos.where({ completed: false }).orderBy('createdAt'))
+  const addTodo = useMutation(todos.insert)
+  const status = useSyncStatus()
 
-  return <button onClick={() => addTodo({ title: 'New todo' })}>Add</button>
+  return (
+    <>
+      <button onClick={() => addTodo.mutate({ title: 'New todo' })}>Add</button>
+      {addTodo.error && <p role="alert">{addTodo.error.message}</p>}
+      <ul>
+        {open.map((todo) => (
+          <li key={todo.id}>{todo.title}</li>
+        ))}
+      </ul>
+      <small>
+        {status.status}, {status.pendingOperations} pending
+      </small>
+    </>
+  )
 }
 ```
 
-### Sync Status
-
-```tsx
-import { useSyncStatus } from '@korajs/react'
+- `KoraProvider` renders `fallback` until the local database is open.
+- `useQuery` renders `[]` first and the rows right after mount, then re-renders only when the
+  result changes. `useQueryState` returns `{ data, error, ready }`.
+- `useMutation` returns `{ mutate, mutateAsync, isLoading, error, reset }`; writes land locally at
+  once and upload in the background.
+- `useSyncStatus()` returns the full status (`status`, `pendingOperations`, `lastSyncedAt`, ...)
+  and re-renders only when it changes.
+- `useRichText`, `usePresence`, `useCollaborators` and `AuthBoundKoraProvider` cover collaborative
+  editing and per-user databases.
 
-function SyncIndicator() {
-  const status = useSyncStatus()
-  // 'connected' | 'syncing' | 'synced' | 'offline' | 'error'
-  return <span>{status}</span>
-}
-```
+## Documentation
 
-All hooks use `useSyncExternalStore` for React 18+ concurrent mode safety.
+[React Hooks guide](https://korajs.dev/guide/react-hooks) and the
+[React API reference](https://korajs.dev/api/react).
 
 ## License
 
 MIT
-
-See the [full documentation](https://github.com/ehoneahobed/kora) for guides, API reference, and examples.

package/dist/index.cjs

@@ -22,12 +22,15 @@ var index_exports = {};
 __export(index_exports, {
   AuthBoundKoraProvider: () => AuthBoundKoraProvider,
   KoraProvider: () => KoraProvider,
+  classifyKoraInitializationError: () => classifyKoraInitializationError,
+  createKoraHooks: () => createKoraHooks,
   useApp: () => useApp,
   useCollaborators: () => useCollaborators,
   useCollection: () => useCollection,
   useMutation: () => useMutation,
   usePresence: () => usePresence,
   useQuery: () => useQuery,
+  useQueryState: () => useQueryState,
   useRichText: () => useRichText,
   useSyncStatus: () => useSyncStatus
 });
@@ -123,11 +126,36 @@ function useKoraContext() {
 
 // src/context/auth-bound-kora-provider.ts
 var import_react2 = require("react");
+var SENSITIVE_METADATA_KEY = /token|secret|password|authorization|cookie/i;
+function classifyKoraInitializationError(error) {
+  const candidate = error;
+  const message = typeof candidate?.message === "string" ? candidate.message : String(error);
+  const name = typeof candidate?.name === "string" ? candidate.name : "Error";
+  const cause = new Error(message);
+  cause.name = name;
+  if (typeof candidate?.stack === "string") cause.stack = candidate.stack;
+  let code = typeof candidate?.code === "string" ? candidate.code : "INITIALIZATION_FAILED";
+  if (code === "INITIALIZATION_FAILED" && cause.name === "QuotaExceededError") {
+    code = "STORAGE_QUOTA_EXCEEDED";
+  }
+  const metadata = {};
+  if (candidate?.context && typeof candidate.context === "object") {
+    for (const [key, value] of Object.entries(candidate.context)) {
+      if (SENSITIVE_METADATA_KEY.test(key)) continue;
+      if (typeof value === "string" || typeof value === "number" || typeof value === "boolean" || value === null) {
+        metadata[key] = value;
+      }
+    }
+  }
+  return { code, name: cause.name, message: cause.message, metadata, cause };
+}
 function AuthBoundKoraProvider({
   authClient,
   createApp,
   signedOut = null,
+  locked,
   fallback = null,
+  error: renderError,
   children
 }) {
   const [app, setApp] = (0, import_react2.useState)(null);
@@ -139,6 +167,8 @@ function AuthBoundKoraProvider({
   const activeUserId = (0, import_react2.useRef)(null);
   const generation = (0, import_react2.useRef)(0);
   const transition = (0, import_react2.useRef)(Promise.resolve());
+  const reconcileRef = (0, import_react2.useRef)(() => {
+  });
   (0, import_react2.useEffect)(() => {
     let disposed = false;
     const reconcile = () => {
@@ -176,10 +206,18 @@ function AuthBoundKoraProvider({
         setApp(created);
       }).catch((error) => {
         if (!disposed && currentGeneration === generation.current) {
-          setInitError(error instanceof Error ? error : new Error(String(error)));
+          void authClient.resolveSyncState?.().then((failedSession) => {
+            if (!disposed && currentGeneration === generation.current && failedSession?.state === "authenticated") {
+              setInitError({
+                error: classifyKoraInitializationError(error),
+                session: { userId: failedSession.userId }
+              });
+            }
+          });
         }
       });
     };
+    reconcileRef.current = reconcile;
     reconcile();
     const unsubscribe = authClient.subscribe?.(reconcile) ?? (() => {
     });
@@ -194,14 +232,22 @@ function AuthBoundKoraProvider({
     };
   }, [authClient]);
   if (initError) {
+    if (renderError) {
+      return renderError({
+        error: initError.error,
+        session: initError.session,
+        retry: () => reconcileRef.current()
+      });
+    }
     return (0, import_react2.createElement)(
       "div",
       { style: { color: "red", padding: "1rem", fontFamily: "monospace" } },
       (0, import_react2.createElement)("strong", null, "Kora initialization error: "),
-      initError.message
+      initError.error.message
     );
   }
   if (state.state === "signed-out" || state.state === "anonymous") return signedOut;
+  if (state.state === "authenticated" && state.locked) return locked ?? signedOut;
   if (!app) return fallback;
   return (0, import_react2.createElement)(KoraProvider, { app, fallback }, children);
 }
@@ -225,10 +271,17 @@ var noopSubscribe = (_onStoreChange) => {
   return () => {
   };
 };
-function useQuery(query, options) {
+var getServerSnapshot = () => EMPTY_ARRAY;
+var getNoError = () => null;
+function readQueryError(queryStore) {
+  if (!queryStore) return null;
+  const channel = queryStore;
+  return typeof channel.getError === "function" ? channel.getError() : null;
+}
+function useQuerySubscription(query, options) {
   const { queryStoreCache } = useKoraContext();
   const enabled = options?.enabled !== false;
-  const descriptorKey = JSON.stringify(query.getDescriptor());
+  const descriptorKey = (0, import_store2.queryKey)(query.getDescriptor());
   const queryRef = (0, import_react3.useRef)(query);
   queryRef.current = query;
   const lastSnapshotRef = (0, import_react3.useRef)(EMPTY_ARRAY);
@@ -246,122 +299,204 @@ function useQuery(query, options) {
       queryStoreCache.release(currentQuery);
     };
   }, [descriptorKey, enabled, queryStoreCache]);
+  const subscribe = enabled && queryStore ? queryStore.subscribe : noopSubscribe;
   const getSnapshot = (0, import_react3.useCallback)(() => {
     if (!enabled) {
       lastSnapshotRef.current = EMPTY_ARRAY;
       return lastSnapshotRef.current;
     }
-    if (!queryStore) {
-      return lastSnapshotRef.current;
-    }
-    if (!queryStore.hasSnapshot()) {
+    if (!queryStore || !queryStore.hasSnapshot()) {
       return lastSnapshotRef.current;
     }
     const snapshot = queryStore.getSnapshot();
     lastSnapshotRef.current = snapshot;
     return snapshot;
   }, [enabled, queryStore]);
-  return (0, import_react3.useSyncExternalStore)(queryStore ? queryStore.subscribe : noopSubscribe, getSnapshot);
+  const getError = (0, import_react3.useCallback)(
+    () => enabled ? readQueryError(queryStore) : null,
+    [enabled, queryStore]
+  );
+  const data = (0, import_react3.useSyncExternalStore)(subscribe, getSnapshot, getServerSnapshot);
+  const error = (0, import_react3.useSyncExternalStore)(subscribe, getError, getNoError);
+  const ready = enabled && queryStore !== null && queryStore.hasSnapshot();
+  return { data, error, ready };
+}
+function useQuery(query, options) {
+  const { data, error } = useQuerySubscription(query, options);
+  if (error && options?.throwOnError !== false) {
+    throw error;
+  }
+  return data;
+}
+function useQueryState(query, options) {
+  const { data, error, ready } = useQuerySubscription(query, options);
+  return (0, import_react3.useMemo)(() => ({ data, error, ready }), [data, error, ready]);
 }
 
+// src/hooks/create-kora-hooks.ts
+var import_react7 = require("react");
+
 // src/hooks/use-mutation.ts
 var import_bindings = require("@korajs/core/bindings");
 var import_react5 = require("react");
 
 // src/hooks/use-controller.ts
 var import_react4 = require("react");
+var ORPHAN_REAP_MS = 1e3;
 function useController(create, destroy, deps) {
-  const controllerRef = (0, import_react4.useRef)(null);
+  const entryRef = (0, import_react4.useRef)(null);
   const createRef = (0, import_react4.useRef)(create);
   createRef.current = create;
-  const [, forceRender] = (0, import_react4.useReducer)((count) => count + 1, 0);
-  const getController = (0, import_react4.useRef)(() => {
-    if (controllerRef.current === null) {
-      controllerRef.current = createRef.current();
+  const destroyRef = (0, import_react4.useRef)(destroy);
+  destroyRef.current = destroy;
+  const [version, bumpVersion] = (0, import_react4.useReducer)((count) => count + 1, 0);
+  const handle = (0, import_react4.useRef)({
+    get: () => {
+      const current = entryRef.current;
+      if (current !== null && !current.reaped) {
+        return current.controller;
+      }
+      const entry = {
+        controller: createRef.current(),
+        claimed: false,
+        reaped: false
+      };
+      entryRef.current = entry;
+      setTimeout(() => {
+        if (!entry.claimed && !entry.reaped) {
+          entry.reaped = true;
+          destroyRef.current(entry.controller);
+        }
+      }, ORPHAN_REAP_MS);
+      return entry.controller;
+    },
+    peek: () => {
+      const current = entryRef.current;
+      return current?.claimed && !current.reaped ? current.controller : null;
     }
-    return controllerRef.current;
   }).current;
   (0, import_react4.useEffect)(() => {
-    if (controllerRef.current === null) {
-      controllerRef.current = createRef.current();
-      forceRender();
+    const current = entryRef.current;
+    if (current !== null && !current.reaped && !current.claimed) {
+      current.claimed = true;
+    } else if (current === null || current.reaped) {
+      entryRef.current = { controller: createRef.current(), claimed: true, reaped: false };
+      bumpVersion();
     }
     return () => {
-      const controller = controllerRef.current;
-      controllerRef.current = null;
-      if (controller !== null) {
-        destroy(controller);
+      const entry = entryRef.current;
+      entryRef.current = null;
+      if (entry !== null && !entry.reaped) {
+        entry.reaped = true;
+        destroyRef.current(entry.controller);
       }
     };
   }, deps);
-  return getController;
+  return { get: handle.get, peek: handle.peek, version };
 }
 
 // src/hooks/use-mutation.ts
+var IDLE = Object.freeze({ isLoading: false, error: null });
+var getServerSnapshot2 = () => IDLE;
 function useMutation(mutationFn, options) {
   const fnRef = (0, import_react5.useRef)(mutationFn);
   fnRef.current = mutationFn;
   const optionsRef = (0, import_react5.useRef)(options);
   optionsRef.current = options;
-  const getController = useController(
+  const controller = useController(
     () => (0, import_bindings.createMutationController)({
       mutationFn: (...args) => fnRef.current(...args),
       resolveOptions: () => optionsRef.current
     }),
-    (controller) => controller.destroy(),
+    (instance) => instance.destroy(),
     []
   );
-  const state = (0, import_react5.useSyncExternalStore)(
+  const getController = controller.get;
+  const subscribe = (0, import_react5.useCallback)(
     (onStoreChange) => getController().subscribe(onStoreChange),
-    () => getController().getSnapshot(),
-    () => getController().getSnapshot()
+    [getController, controller.version]
+  );
+  const getSnapshot = (0, import_react5.useCallback)(() => getController().getSnapshot(), [getController]);
+  const state = (0, import_react5.useSyncExternalStore)(subscribe, getSnapshot, getServerSnapshot2);
+  const mutate = (0, import_react5.useCallback)((...args) => getController().mutate(...args), [getController]);
+  const mutateAsync = (0, import_react5.useCallback)(
+    (...args) => getController().mutateAsync(...args),
+    [getController]
+  );
+  const reset = (0, import_react5.useCallback)(() => getController().reset(), [getController]);
+  return (0, import_react5.useMemo)(
+    () => ({ mutate, mutateAsync, isLoading: state.isLoading, error: state.error, reset }),
+    [mutate, mutateAsync, reset, state.isLoading, state.error]
   );
-  return {
-    mutate: (...args) => getController().mutate(...args),
-    mutateAsync: (...args) => getController().mutateAsync(...args),
-    isLoading: state.isLoading,
-    error: state.error,
-    reset: () => getController().reset()
-  };
 }
 
 // src/hooks/use-sync-status.ts
 var import_sync = require("@korajs/sync");
 var import_react6 = require("react");
+var getServerSnapshot3 = () => import_sync.OFFLINE_SYNC_STATUS;
 function useSyncStatus() {
   const { syncEngine, subscribeSyncStatus, events } = useKoraContext();
-  const getController = useController(
+  const controller = useController(
     () => (0, import_sync.createSyncStatusController)({
       syncEngine,
       subscribeSyncStatus,
       events: subscribeSyncStatus ? null : events
     }),
-    (controller) => controller.destroy(),
+    (instance) => instance.destroy(),
     [syncEngine, subscribeSyncStatus, events]
   );
-  return (0, import_react6.useSyncExternalStore)(
+  const getController = controller.get;
+  const subscribe = (0, import_react6.useCallback)(
     (onStoreChange) => getController().subscribe(onStoreChange),
-    () => getController().getSnapshot(),
-    () => getController().getSnapshot()
+    [getController, controller.version]
   );
+  const peek = controller.peek;
+  const getSnapshot = (0, import_react6.useCallback)(
+    () => peek()?.getSnapshot() ?? import_sync.OFFLINE_SYNC_STATUS,
+    [peek]
+  );
+  return (0, import_react6.useSyncExternalStore)(subscribe, getSnapshot, getServerSnapshot3);
+}
+
+// src/hooks/create-kora-hooks.ts
+function createKoraHooks() {
+  function useTypedApp() {
+    return useApp();
+  }
+  function useTypedCollection(name) {
+    const { app, store } = useKoraContext();
+    return (0, import_react7.useMemo)(() => {
+      const collections = app?.collections;
+      const accessor = collections && name in collections ? collections[name] : store.collection(name);
+      return accessor;
+    }, [app, store, name]);
+  }
+  return {
+    useApp: useTypedApp,
+    useCollection: useTypedCollection,
+    useQuery,
+    useQueryState,
+    useMutation,
+    useSyncStatus
+  };
 }
 
 // src/hooks/use-collection.ts
-var import_react7 = require("react");
+var import_react8 = require("react");
 function useCollection(name) {
   const { store } = useKoraContext();
-  return (0, import_react7.useMemo)(() => {
+  return (0, import_react8.useMemo)(() => {
     return store.collection(name);
   }, [store, name]);
 }
 
 // src/hooks/use-rich-text.ts
 var import_store3 = require("@korajs/store");
-var import_react8 = require("react");
+var import_react9 = require("react");
 function useRichText(collectionName, recordId, fieldName, options) {
   const { store, syncEngine } = useKoraContext();
-  const collection = (0, import_react8.useMemo)(() => store.collection(collectionName), [store, collectionName]);
-  const getController = useController(
+  const collection = (0, import_react9.useMemo)(() => store.collection(collectionName), [store, collectionName]);
+  const controller = useController(
     () => (0, import_store3.createRichTextController)({
       collection,
       collectionName,
@@ -372,29 +507,35 @@ function useRichText(collectionName, recordId, fieldName, options) {
       useDocChannel: options?.useDocChannel,
       user: options?.user
     }),
-    (controller) => controller.destroy(),
+    (instance) => instance.destroy(),
     [collection, collectionName, fieldName, options?.useDocChannel, recordId, store, syncEngine]
   );
-  (0, import_react8.useEffect)(() => {
+  const getController = controller.get;
+  (0, import_react9.useEffect)(() => {
     getController().setUser(options?.user);
-  }, [getController, options?.user]);
-  const snapshot = (0, import_react8.useSyncExternalStore)(
+  }, [getController, options?.user, controller.version]);
+  const subscribe = (0, import_react9.useCallback)(
     (onStoreChange) => getController().subscribe(onStoreChange),
-    () => getController().getSnapshot(),
-    () => getController().getSnapshot()
+    [getController, controller.version]
   );
-  const undo = (0, import_react8.useCallback)(() => {
+  const getSnapshot = (0, import_react9.useCallback)(() => getController().getSnapshot(), [getController]);
+  const snapshot = (0, import_react9.useSyncExternalStore)(subscribe, getSnapshot, getSnapshot);
+  const undo = (0, import_react9.useCallback)(() => {
     getController().undo();
   }, [getController]);
-  const redo = (0, import_react8.useCallback)(() => {
+  const redo = (0, import_react9.useCallback)(() => {
     getController().redo();
   }, [getController]);
-  const setCursor = (0, import_react8.useCallback)(
+  const setCursor = (0, import_react9.useCallback)(
     (anchor, head) => getController().setCursor(anchor, head),
     [getController]
   );
-  const clearCursor = (0, import_react8.useCallback)(() => getController().clearCursor(), [getController]);
-  return buildResult(getController(), snapshot, undo, redo, setCursor, clearCursor);
+  const clearCursor = (0, import_react9.useCallback)(() => getController().clearCursor(), [getController]);
+  const live = getController();
+  return (0, import_react9.useMemo)(
+    () => buildResult(live, snapshot, undo, redo, setCursor, clearCursor),
+    [live, snapshot, undo, redo, setCursor, clearCursor, controller.version]
+  );
 }
 function buildResult(controller, snapshot, undo, redo, setCursor, clearCursor) {
   return {
@@ -413,13 +554,13 @@ function buildResult(controller, snapshot, undo, redo, setCursor, clearCursor) {
 }
 
 // src/hooks/use-presence.ts
-var import_react9 = require("react");
+var import_react10 = require("react");
 function usePresence(user) {
   const { syncEngine } = useKoraContext();
   const name = user?.name ?? null;
   const color = user?.color ?? null;
   const avatar = user?.avatar ?? null;
-  (0, import_react9.useEffect)(() => {
+  (0, import_react10.useEffect)(() => {
     if (!syncEngine || !name || !color) return;
     const awareness = syncEngine.getAwarenessManager();
     awareness.setLocalState({
@@ -433,12 +574,13 @@ function usePresence(user) {
 
 // src/hooks/use-collaborators.ts
 var import_sync2 = require("@korajs/sync");
-var import_react10 = require("react");
+var import_react11 = require("react");
 var EMPTY_ARRAY2 = [];
+var getServerSnapshot4 = () => EMPTY_ARRAY2;
 function useCollaborators() {
   const { syncEngine } = useKoraContext();
-  const snapshotRef = (0, import_react10.useRef)(EMPTY_ARRAY2);
-  const subscribe = (0, import_react10.useCallback)(
+  const snapshotRef = (0, import_react11.useRef)(EMPTY_ARRAY2);
+  const subscribe = (0, import_react11.useCallback)(
     (onStoreChange) => {
       if (!syncEngine) {
         snapshotRef.current = EMPTY_ARRAY2;
@@ -446,6 +588,7 @@ function useCollaborators() {
         };
       }
       const awareness = syncEngine.getAwarenessManager();
+      snapshotRef.current = EMPTY_ARRAY2;
       return (0, import_sync2.subscribeRemoteAwarenessStates)(awareness, (states) => {
         snapshotRef.current = states;
         onStoreChange();
@@ -453,24 +596,27 @@ function useCollaborators() {
     },
     [syncEngine]
   );
-  const getSnapshot = (0, import_react10.useCallback)(() => snapshotRef.current, []);
-  (0, import_react10.useEffect)(() => {
+  const getSnapshot = (0, import_react11.useCallback)(() => snapshotRef.current, []);
+  (0, import_react11.useEffect)(() => {
     if (!syncEngine) {
       snapshotRef.current = EMPTY_ARRAY2;
     }
   }, [syncEngine]);
-  return (0, import_react10.useSyncExternalStore)(subscribe, getSnapshot);
+  return (0, import_react11.useSyncExternalStore)(subscribe, getSnapshot, getServerSnapshot4);
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AuthBoundKoraProvider,
   KoraProvider,
+  classifyKoraInitializationError,
+  createKoraHooks,
   useApp,
   useCollaborators,
   useCollection,
   useMutation,
   usePresence,
   useQuery,
+  useQueryState,
   useRichText,
   useSyncStatus
 });