@syncular/client-react 0.0.4-25 → 0.0.6-100

package/src/async-init-registry.ts

@@ -0,0 +1,60 @@
+/**
+ * Shared async initialization registry.
+ *
+ * Deduplicates concurrent (and subsequent) initialization calls by key.
+ * Failed initializations are evicted automatically so retries can run.
+ */
+
+export interface AsyncInitRegistry<TKey, TValue> {
+  /**
+   * Run (or join) the initializer associated with a key.
+   * - First caller executes `init`.
+   * - Concurrent/future callers receive the same promise.
+   * - If `init` rejects, the key is evicted.
+   */
+  run(key: TKey, init: () => Promise<TValue> | TValue): Promise<TValue>;
+
+  /**
+   * Forget a single key so a subsequent `run` executes again.
+   */
+  invalidate(key: TKey): void;
+
+  /**
+   * Forget all cached entries.
+   */
+  clear(): void;
+}
+
+export function createAsyncInitRegistry<TKey, TValue>(): AsyncInitRegistry<
+  TKey,
+  TValue
+> {
+  const cache = new Map<TKey, Promise<TValue>>();
+
+  function run(
+    key: TKey,
+    init: () => Promise<TValue> | TValue
+  ): Promise<TValue> {
+    const cached = cache.get(key);
+    if (cached) return cached;
+
+    const next = Promise.resolve().then(init);
+    cache.set(key, next);
+    void next.catch(() => {
+      if (cache.get(key) === next) {
+        cache.delete(key);
+      }
+    });
+    return next;
+  }
+
+  return {
+    run,
+    invalidate(key: TKey) {
+      cache.delete(key);
+    },
+    clear() {
+      cache.clear();
+    },
+  };
+}

package/src/createSyncularReact.tsx

@@ -9,7 +9,7 @@
  */
 
 import type {
-  ClientTableRegistry,
+  ClientSyncConfig,
   MutationReceipt,
   MutationsApi,
   MutationsCommitFn,
@@ -28,7 +28,6 @@ import type {
   SyncRepairOptions,
   SyncResetOptions,
   SyncResetResult,
-  SyncSubscriptionRequest,
   SyncTransport,
   TransportHealth,
 } from '@syncular/client';
@@ -99,16 +98,18 @@ export interface SyncContextValue<DB extends SyncClientDb> {
   engine: SyncEngine<DB>;
   db: Kysely<DB>;
   transport: SyncTransport;
-  handlers: ClientTableRegistry<DB>;
+  handlers: ClientSyncConfig<DB, { actorId: string }>['handlers'];
 }
 
-export interface SyncProviderProps<DB extends SyncClientDb> {
+export interface SyncProviderProps<
+  DB extends SyncClientDb,
+  Identity extends { actorId: string },
+> {
   db: Kysely<DB>;
   transport: SyncTransport;
-  handlers: ClientTableRegistry<DB>;
-  actorId?: string | null;
+  sync: ClientSyncConfig<DB, Identity>;
+  identity: Identity;
   clientId?: string | null;
-  subscriptions?: Array<Omit<SyncSubscriptionRequest, 'cursor'>>;
   limitCommits?: number;
   limitSnapshotRows?: number;
   maxSnapshotPages?: number;
@@ -418,16 +419,18 @@ export interface UsePresenceWithJoinResult<TMetadata = Record<string, unknown>>
   isJoined: boolean;
 }
 
-export function createSyncularReact<DB extends SyncClientDb>() {
+export function createSyncularReact<
+  DB extends SyncClientDb,
+  Identity extends { actorId: string } = { actorId: string },
+>() {
   const SyncContext = createContext<SyncContextValue<DB> | null>(null);
 
   function SyncProvider({
     db,
     transport,
-    handlers,
-    actorId,
+    sync,
+    identity,
     clientId,
-    subscriptions = [],
     limitCommits,
     limitSnapshotRows,
     maxSnapshotPages,
@@ -446,15 +449,20 @@ export function createSyncularReact<DB extends SyncClientDb>() {
     autoStart = true,
     renderWhileStarting = true,
     children,
-  }: SyncProviderProps<DB>): ReactNode {
+  }: SyncProviderProps<DB, Identity>): ReactNode {
+    const resolvedSubscriptions = useMemo(
+      () => sync.subscriptions(identity),
+      [sync, identity]
+    );
+
     const config = useMemo<SyncEngineConfig<DB>>(
       () => ({
         db,
         transport,
-        handlers,
-        actorId,
+        handlers: sync.handlers,
+        actorId: identity.actorId,
         clientId,
-        subscriptions,
+        subscriptions: resolvedSubscriptions,
         limitCommits,
         limitSnapshotRows,
         maxSnapshotPages,
@@ -474,10 +482,10 @@ export function createSyncularReact<DB extends SyncClientDb>() {
       [
         db,
         transport,
-        handlers,
-        actorId,
+        sync,
+        identity,
         clientId,
-        subscriptions,
+        resolvedSubscriptions,
         limitCommits,
         limitSnapshotRows,
         maxSnapshotPages,
@@ -499,27 +507,28 @@ export function createSyncularReact<DB extends SyncClientDb>() {
     const [engine] = useState(() => new SyncEngine(config));
 
     const [initialProps] = useState(() => ({
-      actorId,
+      actorId: identity.actorId,
       clientId,
       db,
       transport,
-      handlers,
+      sync,
     }));
 
     useEffect(() => {
       const changedProps: string[] = [];
-      if (actorId !== initialProps.actorId) changedProps.push('actorId');
+      if (identity.actorId !== initialProps.actorId)
+        changedProps.push('actorId');
       if (clientId !== initialProps.clientId) changedProps.push('clientId');
       if (db !== initialProps.db) changedProps.push('db');
       if (transport !== initialProps.transport) changedProps.push('transport');
-      if (handlers !== initialProps.handlers) changedProps.push('handlers');
+      if (sync !== initialProps.sync) changedProps.push('sync');
 
       if (changedProps.length > 0) {
         const message =
           `[SyncProvider] Critical props changed after mount: ${changedProps.join(', ')}. ` +
           'This is not supported and may cause undefined behavior. ' +
           'Use a React key prop to force remount, e.g., ' +
-          `<SyncProvider key={userId} ...> or <SyncProvider key={actorId + ':' + clientId} ...>`;
+          `<SyncProvider key={userId} ...> or <SyncProvider key={identity.actorId + ':' + clientId} ...>`;
 
         console.error(message);
         if (process.env.NODE_ENV === 'development') {
@@ -529,7 +538,7 @@ export function createSyncularReact<DB extends SyncClientDb>() {
           );
         }
       }
-    }, [actorId, clientId, db, transport, handlers, initialProps]);
+    }, [identity, clientId, db, transport, sync, initialProps]);
 
     const [isReady, setIsReady] = useState(false);
 
@@ -561,19 +570,19 @@ export function createSyncularReact<DB extends SyncClientDb>() {
     }, [engine, autoStart]);
 
     useEffect(() => {
-      if (isReady && subscriptions.length > 0) {
-        engine.updateSubscriptions(subscriptions);
+      if (isReady && resolvedSubscriptions.length > 0) {
+        engine.updateSubscriptions(resolvedSubscriptions);
       }
-    }, [engine, isReady, subscriptions]);
+    }, [engine, isReady, resolvedSubscriptions]);
 
     const value = useMemo<SyncContextValue<DB>>(
       () => ({
         engine,
         db,
         transport,
-        handlers,
+        handlers: sync.handlers,
       }),
-      [engine, db, transport, handlers]
+      [engine, db, transport, sync]
     );
 
     if (!isReady && renderWhileStarting === false) {

package/src/index.ts

@@ -5,6 +5,8 @@
  * typed to your application's DB schema.
  */
 
+export type { AsyncInitRegistry } from './async-init-registry';
+export { createAsyncInitRegistry } from './async-init-registry';
 export type {
   ConflictResolution,
   FluentMutation,
@@ -43,6 +45,12 @@ export type {
 } from './createSyncularReact';
 // Re-export core client types for convenience.
 export { createSyncularReact } from './createSyncularReact';
+export type { UseCachedAsyncValueOptions } from './use-cached-async-value';
+export {
+  clearCachedAsyncValues,
+  invalidateCachedAsyncValue,
+  useCachedAsyncValue,
+} from './use-cached-async-value';
 export type {
   SyncGroupChannel,
   SyncGroupChannelSnapshot,

package/src/use-cached-async-value.ts

@@ -0,0 +1,68 @@
+import { useEffect, useRef, useState } from 'react';
+import { createAsyncInitRegistry } from './async-init-registry';
+
+const cachedAsyncValueRegistry = createAsyncInitRegistry<unknown, unknown>();
+
+const EMPTY_DEPS: readonly unknown[] = Object.freeze([]);
+const DEFAULT_KEY = 'default';
+
+export interface UseCachedAsyncValueOptions<TKey = unknown> {
+  /**
+   * Stable cache key shared across component instances.
+   * Defaults to the callback function identity.
+   */
+  key?: TKey;
+  /**
+   * Additional dependencies that should re-run the callback.
+   */
+  deps?: readonly unknown[];
+}
+
+/**
+ * Resolve an async value with a process-wide cache outside component state.
+ * Returns the resolved value and error tuple: [value, error].
+ */
+export function useCachedAsyncValue<TValue>(
+  run: () => Promise<TValue> | TValue,
+  options?: UseCachedAsyncValueOptions
+): readonly [TValue | null, Error | null] {
+  const [value, setValue] = useState<TValue | null>(null);
+  const [error, setError] = useState<Error | null>(null);
+
+  const runRef = useRef(run);
+  runRef.current = run;
+
+  const key = options?.key ?? DEFAULT_KEY;
+  const deps = options?.deps ?? EMPTY_DEPS;
+
+  useEffect(() => {
+    let cancelled = false;
+    setValue(null);
+    setError(null);
+
+    void cachedAsyncValueRegistry
+      .run(key, () => runRef.current())
+      .then((resolved) => {
+        if (cancelled) return;
+        setValue(resolved as TValue);
+      })
+      .catch((cause: unknown) => {
+        if (cancelled) return;
+        setError(cause instanceof Error ? cause : new Error(String(cause)));
+      });
+
+    return () => {
+      cancelled = true;
+    };
+  }, [key, ...deps]);
+
+  return [value, error] as const;
+}
+
+export function invalidateCachedAsyncValue(key: unknown): void {
+  cachedAsyncValueRegistry.invalidate(key);
+}
+
+export function clearCachedAsyncValues(): void {
+  cachedAsyncValueRegistry.clear();
+}