@syncular/react 0.19.0 → 0.20.0

package/README.md

@@ -343,3 +343,12 @@ come from that snapshot. Direct `conflicts`, `rejections`, and
 `securityLifecycle` reads are now method calls. `normalizeClient` has been
 removed; custom adapters must implement the canonical snapshot methods.
 See the [client migration](https://syncular.dev/platform-web/#snapshot-api-migration).
+
+## Live sync progress
+
+`useSyncProgress(client)` subscribes to a direct, worker, Tauri, or React Native
+client's live progress stream and returns `SyncProgress | undefined`. The hook
+releases its subscription on unmount or when `client` changes. Download counters
+use bytes; import counters use processed rows and can include uncommitted work.
+See [browser progress](https://syncular.dev/platform-web/#live-sync-progress) for
+the attempt, phase, failure, and completion contract.

package/dist/client.d.ts

@@ -1,7 +1,9 @@
 /** The provider uses the supplied client identity and canonical snapshot methods. */
-import type { ClientSnapshotReader, ClientChangeListener, ClientDiagnosticsListener, InvalidationListener, LeadershipState, LocalDataPurgeInput, LocalDataPurgeResult, LocalDataRebootstrapInput, LocalDataRebootstrapResult, MutationInput, PresencePeer, QueryReadSpec, QuerySnapshot, SecurityLifecycle, SqlRow, SqlValue, WindowBase, WindowState } from '@syncular/client';
+import type { ClientSnapshotReader, SyncProgress, SyncProgressListener, ClientChangeListener, ClientDiagnosticsListener, InvalidationListener, LeadershipState, LocalDataPurgeInput, LocalDataPurgeResult, LocalDataRebootstrapInput, LocalDataRebootstrapResult, MutationInput, PresencePeer, QueryReadSpec, QuerySnapshot, SecurityLifecycle, SqlRow, SqlValue, WindowBase, WindowState } from '@syncular/client';
 export interface SyncClientLike extends ClientSnapshotReader {
     readonly currentSchemaVersion?: number;
+    onProgress(listener: SyncProgressListener): () => void;
+    progressSnapshot(): SyncProgress | undefined;
     onChange(listener: ClientChangeListener): () => void;
     onDiagnostics(listener: ClientDiagnosticsListener): () => void;
     onInvalidate(listener: InvalidationListener): () => void;

package/dist/index.d.ts

@@ -23,3 +23,4 @@ export { type UseRawSqlOptions, type UseRawSqlResult, useRawSql, } from './use-r
 export { type SyncStatus, useSyncStatus } from './use-sync-status.js';
 export { type UseRetainedWindowResult, type UseWindowResult, useRetainedWindow, useWindow, } from './use-window.js';
 export { createViteSyncClientResource, type RetainedSyncularResource, retainViteSyncClientResource, type ViteSyncClientResourceBootstrap, type ViteSyncClientResourceResult, } from './vite-hmr.js';
+export { useSyncProgress } from './use-sync-progress.js';

package/dist/index.js

@@ -13,3 +13,4 @@ export { useRawSql, } from './use-raw-sql.js';
 export { useSyncStatus } from './use-sync-status.js';
 export { useRetainedWindow, useWindow, } from './use-window.js';
 export { createViteSyncClientResource, retainViteSyncClientResource, } from './vite-hmr.js';
+export { useSyncProgress } from './use-sync-progress.js';

package/dist/runtime-version.d.ts

@@ -3,4 +3,4 @@
  * Vite HMR uses it to replace a worker owner after a Syncular package upgrade
  * even when the application's generated schema version did not change.
  */
-export declare const SYNCULAR_REACT_RUNTIME_VERSION = "0.19.0";
+export declare const SYNCULAR_REACT_RUNTIME_VERSION = "0.20.0";

package/dist/runtime-version.js

@@ -3,4 +3,4 @@
  * Vite HMR uses it to replace a worker owner after a Syncular package upgrade
  * even when the application's generated schema version did not change.
  */
-export const SYNCULAR_REACT_RUNTIME_VERSION = '0.19.0';
+export const SYNCULAR_REACT_RUNTIME_VERSION = '0.20.0';

package/dist/use-sync-progress.d.ts

@@ -0,0 +1,6 @@
+import type { SyncProgress, SyncProgressListener } from '@syncular/client';
+/** Live work snapshots; completion refers to one round (SPEC §7.6). */
+export declare function useSyncProgress(client: {
+    onProgress(listener: SyncProgressListener): () => void;
+    progressSnapshot(): SyncProgress | undefined;
+}): SyncProgress | undefined;

package/dist/use-sync-progress.js

@@ -0,0 +1,7 @@
+import { useCallback, useSyncExternalStore } from 'react';
+/** Live work snapshots; completion refers to one round (SPEC §7.6). */
+export function useSyncProgress(client) {
+    const subscribe = useCallback((notify) => client.onProgress(notify), [client]);
+    const snapshot = useCallback(() => client.progressSnapshot(), [client]);
+    return useSyncExternalStore(subscribe, snapshot, snapshot);
+}

package/package.json

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

package/src/client.ts

@@ -1,6 +1,8 @@
 /** The provider uses the supplied client identity and canonical snapshot methods. */
 import type {
   ClientSnapshotReader,
+  SyncProgress,
+  SyncProgressListener,
   ClientChangeListener,
   ClientDiagnosticsListener,
   InvalidationListener,
@@ -22,6 +24,8 @@ import type {
 
 export interface SyncClientLike extends ClientSnapshotReader {
   readonly currentSchemaVersion?: number;
+  onProgress(listener: SyncProgressListener): () => void;
+  progressSnapshot(): SyncProgress | undefined;
   onChange(listener: ClientChangeListener): () => void;
   onDiagnostics(listener: ClientDiagnosticsListener): () => void;
   onInvalidate(listener: InvalidationListener): () => void;

package/src/index.ts

@@ -63,3 +63,5 @@ export {
   type ViteSyncClientResourceBootstrap,
   type ViteSyncClientResourceResult,
 } from './vite-hmr';
+
+export { useSyncProgress } from './use-sync-progress';

package/src/runtime-version.ts

@@ -3,4 +3,4 @@
  * Vite HMR uses it to replace a worker owner after a Syncular package upgrade
  * even when the application's generated schema version did not change.
  */
-export const SYNCULAR_REACT_RUNTIME_VERSION = '0.19.0';
+export const SYNCULAR_REACT_RUNTIME_VERSION = '0.20.0';

package/src/use-sync-progress.ts

@@ -0,0 +1,15 @@
+import type { SyncProgress, SyncProgressListener } from '@syncular/client';
+import { useCallback, useSyncExternalStore } from 'react';
+
+/** Live work snapshots; completion refers to one round (SPEC §7.6). */
+export function useSyncProgress(client: {
+  onProgress(listener: SyncProgressListener): () => void;
+  progressSnapshot(): SyncProgress | undefined;
+}): SyncProgress | undefined {
+  const subscribe = useCallback(
+    (notify: () => void) => client.onProgress(notify),
+    [client],
+  );
+  const snapshot = useCallback(() => client.progressSnapshot(), [client]);
+  return useSyncExternalStore(subscribe, snapshot, snapshot);
+}