@syncular/client-react 0.0.4-26 → 0.0.6-46

package/dist/async-init-registry.d.ts

@@ -0,0 +1,25 @@
+/**
+ * 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 declare function createAsyncInitRegistry<TKey, TValue>(): AsyncInitRegistry<TKey, TValue>;
+//# sourceMappingURL=async-init-registry.d.ts.map

package/dist/async-init-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"async-init-registry.d.ts","sourceRoot":"","sources":["../src/async-init-registry.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,WAAW,iBAAiB,CAAC,IAAI,EAAE,MAAM;IAC7C;;;;;OAKG;IACH,GAAG,CAAC,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,GAAG,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAEtE;;OAEG;IACH,UAAU,CAAC,GAAG,EAAE,IAAI,GAAG,IAAI,CAAC;IAE5B;;OAEG;IACH,KAAK,IAAI,IAAI,CAAC;CACf;AAED,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,KAAK,iBAAiB,CACxE,IAAI,EACJ,MAAM,CACP,CA6BA"}

package/dist/async-init-registry.js

@@ -0,0 +1,32 @@
+/**
+ * Shared async initialization registry.
+ *
+ * Deduplicates concurrent (and subsequent) initialization calls by key.
+ * Failed initializations are evicted automatically so retries can run.
+ */
+export function createAsyncInitRegistry() {
+    const cache = new Map();
+    function run(key, init) {
+        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) {
+            cache.delete(key);
+        },
+        clear() {
+            cache.clear();
+        },
+    };
+}
+//# sourceMappingURL=async-init-registry.js.map

package/dist/async-init-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"async-init-registry.js","sourceRoot":"","sources":["../src/async-init-registry.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAsBH,MAAM,UAAU,uBAAuB,GAGrC;IACA,MAAM,KAAK,GAAG,IAAI,GAAG,EAAyB,CAAC;IAE/C,SAAS,GAAG,CACV,GAAS,EACT,IAAoC,EACnB;QACjB,MAAM,MAAM,GAAG,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAC9B,IAAI,MAAM;YAAE,OAAO,MAAM,CAAC;QAE1B,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC1C,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;QACrB,KAAK,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC;YACpB,IAAI,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,IAAI,EAAE,CAAC;gBAC5B,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACpB,CAAC;QAAA,CACF,CAAC,CAAC;QACH,OAAO,IAAI,CAAC;IAAA,CACb;IAED,OAAO;QACL,GAAG;QACH,UAAU,CAAC,GAAS,EAAE;YACpB,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAAA,CACnB;QACD,KAAK,GAAG;YACN,KAAK,CAAC,KAAK,EAAE,CAAC;QAAA,CACf;KACF,CAAC;AAAA,CACH"}

package/dist/index.d.ts

@@ -4,8 +4,12 @@
  * Use `createSyncularReact<DB>()` to create a SyncProvider + hooks that are
  * typed to your application's DB schema.
  */
+export type { AsyncInitRegistry } from './async-init-registry';
+export { createAsyncInitRegistry } from './async-init-registry';
 export type { ConflictResolution, FluentMutation, MutationInput, MutationResult, MutationsHook, OutboxCommit, SyncContextValue, SyncProviderProps, SyncStatus, UseConflictsResult, UseMutationOptions, UseMutationResult, UseMutationsOptions, UseOutboxResult, UsePresenceResult, UsePresenceWithJoinOptions, UsePresenceWithJoinResult, UseQueryOptions, UseQueryResult, UseResolveConflictOptions, UseResolveConflictResult, UseSyncConnectionResult, UseSyncEngineResult, UseSyncInspectorOptions, UseSyncInspectorResult, UseSyncProgressOptions, UseSyncProgressResult, UseSyncQueryOptions, UseSyncQueryResult, UseSyncStatusOptions, UseSyncSubscriptionResult, UseSyncSubscriptionsOptions, UseSyncSubscriptionsResult, UseTransportHealthResult, } from './createSyncularReact';
 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, SyncGroupStatus, UseSyncGroupResult, } from './useSyncGroup';
 export { useSyncGroup } from './useSyncGroup';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,YAAY,EACV,kBAAkB,EAClB,cAAc,EACd,aAAa,EACb,cAAc,EACd,aAAa,EACb,YAAY,EACZ,gBAAgB,EAChB,iBAAiB,EACjB,UAAU,EACV,kBAAkB,EAClB,kBAAkB,EAClB,iBAAiB,EACjB,mBAAmB,EACnB,eAAe,EACf,iBAAiB,EACjB,0BAA0B,EAC1B,yBAAyB,EACzB,eAAe,EACf,cAAc,EACd,yBAAyB,EACzB,wBAAwB,EACxB,uBAAuB,EACvB,mBAAmB,EACnB,uBAAuB,EACvB,sBAAsB,EACtB,sBAAsB,EACtB,qBAAqB,EACrB,mBAAmB,EACnB,kBAAkB,EAClB,oBAAoB,EACpB,yBAAyB,EACzB,2BAA2B,EAC3B,0BAA0B,EAC1B,wBAAwB,GACzB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAC5D,YAAY,EACV,gBAAgB,EAChB,wBAAwB,EACxB,eAAe,EACf,kBAAkB,GACnB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,YAAY,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC/D,OAAO,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AAChE,YAAY,EACV,kBAAkB,EAClB,cAAc,EACd,aAAa,EACb,cAAc,EACd,aAAa,EACb,YAAY,EACZ,gBAAgB,EAChB,iBAAiB,EACjB,UAAU,EACV,kBAAkB,EAClB,kBAAkB,EAClB,iBAAiB,EACjB,mBAAmB,EACnB,eAAe,EACf,iBAAiB,EACjB,0BAA0B,EAC1B,yBAAyB,EACzB,eAAe,EACf,cAAc,EACd,yBAAyB,EACzB,wBAAwB,EACxB,uBAAuB,EACvB,mBAAmB,EACnB,uBAAuB,EACvB,sBAAsB,EACtB,sBAAsB,EACtB,qBAAqB,EACrB,mBAAmB,EACnB,kBAAkB,EAClB,oBAAoB,EACpB,yBAAyB,EACzB,2BAA2B,EAC3B,0BAA0B,EAC1B,wBAAwB,GACzB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAC5D,YAAY,EAAE,0BAA0B,EAAE,MAAM,0BAA0B,CAAC;AAC3E,OAAO,EACL,sBAAsB,EACtB,0BAA0B,EAC1B,mBAAmB,GACpB,MAAM,0BAA0B,CAAC;AAClC,YAAY,EACV,gBAAgB,EAChB,wBAAwB,EACxB,eAAe,EACf,kBAAkB,GACnB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/index.js

@@ -4,7 +4,9 @@
  * Use `createSyncularReact<DB>()` to create a SyncProvider + hooks that are
  * typed to your application's DB schema.
  */
+export { createAsyncInitRegistry } from './async-init-registry.js';
 // Re-export core client types for convenience.
 export { createSyncularReact } from './createSyncularReact.js';
+export { clearCachedAsyncValues, invalidateCachedAsyncValue, useCachedAsyncValue, } from './use-cached-async-value.js';
 export { useSyncGroup } from './useSyncGroup.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAsCH,+CAA+C;AAC/C,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAO5D,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AAqChE,+CAA+C;AAC/C,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAE5D,OAAO,EACL,sBAAsB,EACtB,0BAA0B,EAC1B,mBAAmB,GACpB,MAAM,0BAA0B,CAAC;AAOlC,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/use-cached-async-value.d.ts

@@ -0,0 +1,19 @@
+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 declare function useCachedAsyncValue<TValue>(run: () => Promise<TValue> | TValue, options?: UseCachedAsyncValueOptions): readonly [TValue | null, Error | null];
+export declare function invalidateCachedAsyncValue(key: unknown): void;
+export declare function clearCachedAsyncValues(): void;
+//# sourceMappingURL=use-cached-async-value.d.ts.map

package/dist/use-cached-async-value.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-cached-async-value.d.ts","sourceRoot":"","sources":["../src/use-cached-async-value.ts"],"names":[],"mappings":"AAOA,MAAM,WAAW,0BAA0B,CAAC,IAAI,GAAG,OAAO;IACxD;;;OAGG;IACH,GAAG,CAAC,EAAE,IAAI,CAAC;IACX;;OAEG;IACH,IAAI,CAAC,EAAE,SAAS,OAAO,EAAE,CAAC;CAC3B;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EACxC,GAAG,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,GAAG,MAAM,EACnC,OAAO,CAAC,EAAE,0BAA0B,GACnC,SAAS,CAAC,MAAM,GAAG,IAAI,EAAE,KAAK,GAAG,IAAI,CAAC,CAgCxC;AAED,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI,CAE7D;AAED,wBAAgB,sBAAsB,IAAI,IAAI,CAE7C"}

package/dist/use-cached-async-value.js

@@ -0,0 +1,44 @@
+import { useEffect, useRef, useState } from 'react';
+import { createAsyncInitRegistry } from './async-init-registry.js';
+const cachedAsyncValueRegistry = createAsyncInitRegistry();
+const EMPTY_DEPS = Object.freeze([]);
+/**
+ * Resolve an async value with a process-wide cache outside component state.
+ * Returns the resolved value and error tuple: [value, error].
+ */
+export function useCachedAsyncValue(run, options) {
+    const [value, setValue] = useState(null);
+    const [error, setError] = useState(null);
+    const runRef = useRef(run);
+    runRef.current = run;
+    const key = options?.key ?? run;
+    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);
+        })
+            .catch((cause) => {
+            if (cancelled)
+                return;
+            setError(cause instanceof Error ? cause : new Error(String(cause)));
+        });
+        return () => {
+            cancelled = true;
+        };
+    }, [key, ...deps]);
+    return [value, error];
+}
+export function invalidateCachedAsyncValue(key) {
+    cachedAsyncValueRegistry.invalidate(key);
+}
+export function clearCachedAsyncValues() {
+    cachedAsyncValueRegistry.clear();
+}
+//# sourceMappingURL=use-cached-async-value.js.map

package/dist/use-cached-async-value.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-cached-async-value.js","sourceRoot":"","sources":["../src/use-cached-async-value.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AACpD,OAAO,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AAEhE,MAAM,wBAAwB,GAAG,uBAAuB,EAAoB,CAAC;AAE7E,MAAM,UAAU,GAAuB,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;AAczD;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CACjC,GAAmC,EACnC,OAAoC,EACI;IACxC,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,GAAG,QAAQ,CAAgB,IAAI,CAAC,CAAC;IACxD,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,GAAG,QAAQ,CAAe,IAAI,CAAC,CAAC;IAEvD,MAAM,MAAM,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;IAC3B,MAAM,CAAC,OAAO,GAAG,GAAG,CAAC;IAErB,MAAM,GAAG,GAAG,OAAO,EAAE,GAAG,IAAI,GAAG,CAAC;IAChC,MAAM,IAAI,GAAG,OAAO,EAAE,IAAI,IAAI,UAAU,CAAC;IAEzC,SAAS,CAAC,GAAG,EAAE,CAAC;QACd,IAAI,SAAS,GAAG,KAAK,CAAC;QACtB,QAAQ,CAAC,IAAI,CAAC,CAAC;QACf,QAAQ,CAAC,IAAI,CAAC,CAAC;QAEf,KAAK,wBAAwB;aAC1B,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;aAChC,IAAI,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC;YAClB,IAAI,SAAS;gBAAE,OAAO;YACtB,QAAQ,CAAC,QAAkB,CAAC,CAAC;QAAA,CAC9B,CAAC;aACD,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE,CAAC;YACzB,IAAI,SAAS;gBAAE,OAAO;YACtB,QAAQ,CAAC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;QAAA,CACrE,CAAC,CAAC;QAEL,OAAO,GAAG,EAAE,CAAC;YACX,SAAS,GAAG,IAAI,CAAC;QAAA,CAClB,CAAC;IAAA,CACH,EAAE,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC,CAAC;IAEnB,OAAO,CAAC,KAAK,EAAE,KAAK,CAAU,CAAC;AAAA,CAChC;AAED,MAAM,UAAU,0BAA0B,CAAC,GAAY,EAAQ;IAC7D,wBAAwB,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;AAAA,CAC1C;AAED,MAAM,UAAU,sBAAsB,GAAS;IAC7C,wBAAwB,CAAC,KAAK,EAAE,CAAC;AAAA,CAClC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/client-react",
-  "version": "0.0.4-26",
+  "version": "0.0.6-46",
   "description": "React hooks and bindings for the Syncular client",
   "license": "MIT",
   "author": "Benjamin Kniffler",
@@ -44,20 +44,20 @@
     "release": "bunx syncular-publish"
   },
   "dependencies": {
-    "@syncular/client": "0.0.4-26"
+    "@syncular/client": "0.0.6-46"
   },
   "peerDependencies": {
     "kysely": "^0.28.0",
     "react": "^18.0.0 || ^19.0.0"
   },
   "devDependencies": {
-    "@happy-dom/global-registrator": "^20.6.1",
+    "@happy-dom/global-registrator": "^20.6.3",
     "@syncular/config": "0.0.0",
-    "@syncular/dialect-bun-sqlite": "0.0.4-26",
-    "@syncular/testkit": "0.0.4-26",
+    "@syncular/dialect-bun-sqlite": "0.0.6-46",
+    "@syncular/testkit": "0.0.6-46",
     "@testing-library/react": "^16.3.2",
     "@types/react": "^19.2.14",
-    "happy-dom": "^20.6.1",
+    "happy-dom": "^20.6.3",
     "kysely": "*",
     "kysely-bun-sqlite": "^0.4.0",
     "react": "^19.2.4",

package/src/__tests__/async-init-registry.test.ts

@@ -0,0 +1,64 @@
+import { describe, expect, it } from 'bun:test';
+import { createAsyncInitRegistry } from '../async-init-registry';
+
+describe('createAsyncInitRegistry', () => {
+  it('runs initializer once per key and shares the same result', async () => {
+    const registry = createAsyncInitRegistry<string, string>();
+    let runs = 0;
+
+    const first = registry.run('client-a', async () => {
+      runs += 1;
+      return 'ok';
+    });
+    const second = registry.run('client-a', async () => {
+      runs += 1;
+      return 'unexpected';
+    });
+
+    await expect(first).resolves.toBe('ok');
+    await expect(second).resolves.toBe('ok');
+    expect(runs).toBe(1);
+  });
+
+  it('evicts failed initializers so retry can succeed', async () => {
+    const registry = createAsyncInitRegistry<string, string>();
+    let runs = 0;
+
+    await expect(
+      registry.run('client-a', async () => {
+        runs += 1;
+        throw new Error('boom');
+      })
+    ).rejects.toThrow('boom');
+
+    await expect(
+      registry.run('client-a', async () => {
+        runs += 1;
+        return 'recovered';
+      })
+    ).resolves.toBe('recovered');
+
+    expect(runs).toBe(2);
+  });
+
+  it('supports explicit invalidation', async () => {
+    const registry = createAsyncInitRegistry<string, number>();
+    let seed = 0;
+
+    await expect(
+      registry.run('client-a', async () => {
+        seed += 1;
+        return seed;
+      })
+    ).resolves.toBe(1);
+
+    registry.invalidate('client-a');
+
+    await expect(
+      registry.run('client-a', async () => {
+        seed += 1;
+        return seed;
+      })
+    ).resolves.toBe(2);
+  });
+});

package/src/__tests__/use-cached-async-value.test.tsx

@@ -0,0 +1,111 @@
+import { describe, expect, it } from 'bun:test';
+import { renderHook, waitFor } from '@testing-library/react';
+import type { ReactNode } from 'react';
+import { StrictMode } from 'react';
+import {
+  clearCachedAsyncValues,
+  useCachedAsyncValue,
+} from '../use-cached-async-value';
+
+function strictModeWrapper(props: { children: ReactNode }) {
+  return <StrictMode>{props.children}</StrictMode>;
+}
+
+describe('useCachedAsyncValue', () => {
+  it('deduplicates StrictMode initialization by key', async () => {
+    clearCachedAsyncValues();
+    let runs = 0;
+
+    const { result } = renderHook(
+      () =>
+        useCachedAsyncValue(
+          async () => {
+            runs += 1;
+            return 'ready';
+          },
+          { key: 'strictmode-init' }
+        ),
+      { wrapper: strictModeWrapper }
+    );
+
+    await waitFor(() => {
+      expect(result.current[0]).toBe('ready');
+    });
+    expect(result.current[1]).toBeNull();
+    expect(runs).toBe(1);
+  });
+
+  it('retries after a failure when dependencies trigger rerun', async () => {
+    clearCachedAsyncValues();
+    let runs = 0;
+
+    const { result, rerender } = renderHook(
+      ({ attempt }: { attempt: number }) =>
+        useCachedAsyncValue(
+          async () => {
+            runs += 1;
+            if (attempt === 0) {
+              throw new Error('boom');
+            }
+            return 'recovered';
+          },
+          {
+            key: 'retryable-init',
+            deps: [attempt],
+          }
+        ),
+      {
+        initialProps: { attempt: 0 },
+      }
+    );
+
+    await waitFor(() => {
+      expect(result.current[1]?.message).toBe('boom');
+    });
+
+    rerender({ attempt: 1 });
+
+    await waitFor(() => {
+      expect(result.current[0]).toBe('recovered');
+    });
+    expect(result.current[1]).toBeNull();
+    expect(runs).toBe(2);
+  });
+
+  it('reuses cached values across component remounts', async () => {
+    clearCachedAsyncValues();
+    let runs = 0;
+
+    const first = renderHook(() =>
+      useCachedAsyncValue(
+        async () => {
+          runs += 1;
+          return 7;
+        },
+        { key: 'shared-init' }
+      )
+    );
+
+    await waitFor(() => {
+      expect(first.result.current[0]).toBe(7);
+    });
+    first.unmount();
+
+    const second = renderHook(() =>
+      useCachedAsyncValue(
+        async () => {
+          runs += 1;
+          return 9;
+        },
+        { key: 'shared-init' }
+      )
+    );
+
+    await waitFor(() => {
+      expect(second.result.current[0]).toBe(7);
+    });
+    expect(second.result.current[1]).toBeNull();
+    expect(runs).toBe(1);
+    second.unmount();
+  });
+});

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/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,67 @@
+import { useEffect, useRef, useState } from 'react';
+import { createAsyncInitRegistry } from './async-init-registry';
+
+const cachedAsyncValueRegistry = createAsyncInitRegistry<unknown, unknown>();
+
+const EMPTY_DEPS: readonly unknown[] = Object.freeze([]);
+
+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 ?? run;
+  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();
+}