@syncular/react 0.15.4 → 0.15.5

package/README.md

@@ -67,8 +67,9 @@ A ready client can be passed directly:
 ```
 
 For async engines, create one resource outside React render. It owns one
-initialization attempt across StrictMode remounts and closes the client exactly
-once when explicitly disposed:
+initialization attempt across StrictMode remounts, can retry a failed startup
+without replacing the provider, and closes the client exactly once when
+explicitly disposed:
 
 ```tsx
 import { createSyncClientResource, SyncProvider } from '@syncular/react';
@@ -78,7 +79,12 @@ const clientResource = createSyncClientResource(() => createClient());
 <SyncProvider
   client={clientResource}
   fallback={<p>Starting local database…</p>}
-  renderError={(error) => <p>{error.message}</p>}
+  renderError={(error, retry) => (
+    <div>
+      <p>{error.message}</p>
+      <button onClick={() => void retry()}>Try again</button>
+    </div>
+  )}
 >
   <App />
 </SyncProvider>
@@ -87,6 +93,12 @@ const clientResource = createSyncClientResource(() => createClient());
 Call `await clientResource.dispose()` from the application's real lifecycle
 owner, not from a StrictMode-sensitive child effect.
 
+The resource is stable across React remounts, not JavaScript module replacement.
+During development, preserve it in the bundler's hot-module data or dispose the
+old resource before creating another one. Otherwise the old worker and the new
+worker can briefly compete for the same persistent OPFS directory. Never wipe
+or rename the database in response to a retryable startup error.
+
 ## `useMutation`
 
 `useMutation()` retains the raw batch API. `useMutation(generatedTable)` adds

package/dist/provider.d.ts

@@ -16,6 +16,6 @@ export interface SyncProviderProps {
     readonly client: SyncClientLike | SyncClientResource;
     readonly children?: ReactNode;
     readonly fallback?: ReactNode;
-    readonly renderError?: (error: Error) => ReactNode;
+    readonly renderError?: (error: Error, retry: () => Promise<void>) => ReactNode;
 }
 export declare function SyncProvider(props: SyncProviderProps): ReactNode;

package/dist/provider.js

@@ -56,8 +56,8 @@ export function SyncProvider(props) {
     if (snapshot.phase === 'pending')
         return props.fallback ?? null;
     if (snapshot.phase === 'error') {
-        if (props.renderError !== undefined)
-            return props.renderError(snapshot.error);
+        if (props.renderError !== undefined && resource !== undefined)
+            return props.renderError(snapshot.error, resource.retry);
         throw snapshot.error;
     }
     return createElement(ReadySyncProvider, { client: snapshot.client }, props.children);

package/dist/resource.d.ts

@@ -12,6 +12,8 @@ export interface SyncClientResource {
     readonly kind: 'syncular-client-resource';
     subscribe(listener: () => void): () => void;
     getSnapshot(): SyncClientResourceSnapshot;
+    /** Re-run a failed initialization attempt. Pending/ready calls are no-ops. */
+    retry(): Promise<void>;
     dispose(): Promise<void>;
 }
 export declare function createSyncClientResource(factory: () => SyncClientLike | Promise<SyncClientLike>): SyncClientResource;

package/dist/resource.js

@@ -3,31 +3,43 @@ export function createSyncClientResource(factory) {
     let snapshot = { phase: 'pending' };
     let disposed = false;
     let closed = false;
-    const initialized = Promise.resolve()
-        .then(factory)
-        .then(async (client) => {
-        if (disposed) {
-            const close = client
-                .close;
-            if (close !== undefined && !closed) {
-                closed = true;
-                await close.call(client);
-            }
-            return;
-        }
-        snapshot = { phase: 'ready', client };
-        for (const listener of listeners)
-            listener();
-    }, (error) => {
-        if (disposed)
-            return;
-        snapshot = {
-            phase: 'error',
-            error: error instanceof Error ? error : new Error(String(error)),
-        };
+    let initialized;
+    const notify = () => {
         for (const listener of listeners)
             listener();
-    });
+    };
+    const closeClient = async (client) => {
+        const close = client.close;
+        if (close !== undefined && !closed) {
+            closed = true;
+            await close.call(client);
+        }
+    };
+    const initialize = (publishPending) => {
+        if (publishPending) {
+            snapshot = { phase: 'pending' };
+            notify();
+        }
+        return Promise.resolve()
+            .then(factory)
+            .then(async (client) => {
+            if (disposed) {
+                await closeClient(client);
+                return;
+            }
+            snapshot = { phase: 'ready', client };
+            notify();
+        }, (error) => {
+            if (disposed)
+                return;
+            snapshot = {
+                phase: 'error',
+                error: error instanceof Error ? error : new Error(String(error)),
+            };
+            notify();
+        });
+    };
+    initialized = initialize(false);
     return {
         kind: 'syncular-client-resource',
         subscribe(listener) {
@@ -35,17 +47,19 @@ export function createSyncClientResource(factory) {
             return () => listeners.delete(listener);
         },
         getSnapshot: () => snapshot,
+        retry() {
+            if (disposed || snapshot.phase !== 'error')
+                return initialized;
+            initialized = initialize(true);
+            return initialized;
+        },
         async dispose() {
             if (disposed)
                 return;
             disposed = true;
             await initialized;
             if (snapshot.phase === 'ready' && !closed) {
-                const close = snapshot.client.close;
-                if (close !== undefined) {
-                    closed = true;
-                    await close.call(snapshot.client);
-                }
+                await closeClient(snapshot.client);
             }
             listeners.clear();
         },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/react",
-  "version": "0.15.4",
+  "version": "0.15.5",
   "description": "React hooks for Syncular offline-first sync",
   "license": "Apache-2.0",
   "author": "Benjamin Kniffler",
@@ -48,15 +48,15 @@
     "test": "bun test --preload ./test/setup.ts"
   },
   "dependencies": {
-    "@syncular/client": "0.15.4"
+    "@syncular/client": "0.15.5"
   },
   "peerDependencies": {
     "react": ">=18.0.0"
   },
   "devDependencies": {
     "@happy-dom/global-registrator": "^15.11.0",
-    "@syncular/core": "0.15.4",
-    "@syncular/server": "0.15.4",
+    "@syncular/core": "0.15.5",
+    "@syncular/server": "0.15.5",
     "@testing-library/react": "^16.1.0",
     "@types/react": "^18.3.0",
     "react": "^18.3.1",

package/src/provider.ts

@@ -33,7 +33,10 @@ export interface SyncProviderProps {
   readonly client: SyncClientLike | SyncClientResource;
   readonly children?: ReactNode;
   readonly fallback?: ReactNode;
-  readonly renderError?: (error: Error) => ReactNode;
+  readonly renderError?: (
+    error: Error,
+    retry: () => Promise<void>,
+  ) => ReactNode;
 }
 
 interface ClientRecord {
@@ -106,8 +109,8 @@ export function SyncProvider(props: SyncProviderProps): ReactNode {
   );
   if (snapshot.phase === 'pending') return props.fallback ?? null;
   if (snapshot.phase === 'error') {
-    if (props.renderError !== undefined)
-      return props.renderError(snapshot.error);
+    if (props.renderError !== undefined && resource !== undefined)
+      return props.renderError(snapshot.error, resource.retry);
     throw snapshot.error;
   }
   return createElement(

package/src/resource.ts

@@ -9,6 +9,8 @@ export interface SyncClientResource {
   readonly kind: 'syncular-client-resource';
   subscribe(listener: () => void): () => void;
   getSnapshot(): SyncClientResourceSnapshot;
+  /** Re-run a failed initialization attempt. Pending/ready calls are no-ops. */
+  retry(): Promise<void>;
   dispose(): Promise<void>;
 }
 
@@ -19,31 +21,48 @@ export function createSyncClientResource(
   let snapshot: SyncClientResourceSnapshot = { phase: 'pending' };
   let disposed = false;
   let closed = false;
-  const initialized = Promise.resolve()
-    .then(factory)
-    .then(
-      async (client) => {
-        if (disposed) {
-          const close = (client as { close?: () => void | Promise<void> })
-            .close;
-          if (close !== undefined && !closed) {
-            closed = true;
-            await close.call(client);
+  let initialized: Promise<void>;
+
+  const notify = (): void => {
+    for (const listener of listeners) listener();
+  };
+
+  const closeClient = async (client: SyncClientLike): Promise<void> => {
+    const close = (client as { close?: () => void | Promise<void> }).close;
+    if (close !== undefined && !closed) {
+      closed = true;
+      await close.call(client);
+    }
+  };
+
+  const initialize = (publishPending: boolean): Promise<void> => {
+    if (publishPending) {
+      snapshot = { phase: 'pending' };
+      notify();
+    }
+    return Promise.resolve()
+      .then(factory)
+      .then(
+        async (client) => {
+          if (disposed) {
+            await closeClient(client);
+            return;
           }
-          return;
-        }
-        snapshot = { phase: 'ready', client };
-        for (const listener of listeners) listener();
-      },
-      (error: unknown) => {
-        if (disposed) return;
-        snapshot = {
-          phase: 'error',
-          error: error instanceof Error ? error : new Error(String(error)),
-        };
-        for (const listener of listeners) listener();
-      },
-    );
+          snapshot = { phase: 'ready', client };
+          notify();
+        },
+        (error: unknown) => {
+          if (disposed) return;
+          snapshot = {
+            phase: 'error',
+            error: error instanceof Error ? error : new Error(String(error)),
+          };
+          notify();
+        },
+      );
+  };
+
+  initialized = initialize(false);
 
   return {
     kind: 'syncular-client-resource',
@@ -52,18 +71,17 @@ export function createSyncClientResource(
       return () => listeners.delete(listener);
     },
     getSnapshot: () => snapshot,
+    retry() {
+      if (disposed || snapshot.phase !== 'error') return initialized;
+      initialized = initialize(true);
+      return initialized;
+    },
     async dispose() {
       if (disposed) return;
       disposed = true;
       await initialized;
       if (snapshot.phase === 'ready' && !closed) {
-        const close = (
-          snapshot.client as { close?: () => void | Promise<void> }
-        ).close;
-        if (close !== undefined) {
-          closed = true;
-          await close.call(snapshot.client);
-        }
+        await closeClient(snapshot.client);
       }
       listeners.clear();
     },