@syncular/react 0.59.0 → 0.60.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -250,10 +250,8 @@ not need a custom retention effect.
250
250
 
251
251
  ## Other hooks
252
252
 
253
- - `useDiagnostics({ expectedSubscriptions })` observes the versioned,
254
- privacy-safe support snapshot. Native/Worker events trigger a fresh request,
255
- preserving expected-but-unregistered intent on every host. Subscription ids
256
- must be stable and PHI-free; scopes are not accepted.
253
+ - `useDiagnostics()` observes the versioned, privacy-safe support snapshot.
254
+ Native/Worker events trigger a fresh read on every host.
257
255
  - `useSyncStatus()` observes the status domain without a follow-up read after
258
256
  every row change. It includes `availability` and `currentSchemaVersion`;
259
257
  `outbox` is local push work, while `syncNeeded` specifically means an inbound
@@ -292,23 +290,16 @@ a stable error code, an optional SQLite result code, and the first failure
292
290
  time. It never contains SQL, parameters, rows, or SQLite error prose. Raw SQL
293
291
  uses the diagnostic id `raw` unless `useRawSql` receives an explicit `id`.
294
292
 
295
- Use application-owned, stable, PHI-free subscription ids to make missing
296
- registration distinguishable from a completed zero-row bootstrap. The hook
297
- refreshes after diagnostics events on direct, Worker, Tauri, and React Native
298
- hosts while preserving that expected intent:
293
+ The snapshot counts units by state (`units.bootstrapping`, `units.complete`,
294
+ `units.reset`, `units.revoked`, `units.failed`) and carries `activeUnits` and
295
+ the replica cursor, without scope values. The hook refreshes after diagnostics
296
+ events on direct, Worker, Tauri, and React Native hosts:
299
297
 
300
298
  ```tsx
301
299
  import { useDiagnostics } from '@syncular/react';
302
300
 
303
- const expectedSubscriptions = [
304
- { id: 'membership-security', table: 'facility_memberships' },
305
- { id: 'scheduler-window', table: 'surgeries' },
306
- ] as const;
307
-
308
301
  function SyncSupportPanel() {
309
- const { snapshot, isLoading, error, refresh } = useDiagnostics({
310
- expectedSubscriptions,
311
- });
302
+ const { snapshot, isLoading, error, refresh } = useDiagnostics();
312
303
 
313
304
  if (isLoading) return <p>Collecting local sync evidence…</p>;
314
305
  if (error) return <p>Diagnostics unavailable: {error.message}</p>;
package/dist/index.d.ts CHANGED
@@ -14,7 +14,7 @@ export { SYNCULAR_REACT_RUNTIME_VERSION } from './runtime-version.js';
14
14
  export { useReactiveStore, useSyncClient } from './use-client.js';
15
15
  export { type UseCommitOutcomesResult, useCommitOutcomes, } from './use-commit-outcomes.js';
16
16
  export { type UseConflictsResult, useConflicts } from './use-conflicts.js';
17
- export { type UseDiagnosticsOptions, type UseDiagnosticsResult, useDiagnostics, } from './use-diagnostics.js';
17
+ export { type UseDiagnosticsResult, useDiagnostics } from './use-diagnostics.js';
18
18
  export { type SyncTableDescriptor, type UseMutationOptions, type UseMutationResult, type UseTableMutationResult, useMutation, } from './use-mutation.js';
19
19
  export { usePresence } from './use-presence.js';
20
20
  export { type NamedQueryDescriptor, useQuery } from './use-query.js';
package/dist/index.js CHANGED
@@ -4,7 +4,7 @@ export { SYNCULAR_REACT_RUNTIME_VERSION } from './runtime-version.js';
4
4
  export { useReactiveStore, useSyncClient } from './use-client.js';
5
5
  export { useCommitOutcomes, } from './use-commit-outcomes.js';
6
6
  export { useConflicts } from './use-conflicts.js';
7
- export { useDiagnostics, } from './use-diagnostics.js';
7
+ export { useDiagnostics } from './use-diagnostics.js';
8
8
  export { useMutation, } from './use-mutation.js';
9
9
  export { usePresence } from './use-presence.js';
10
10
  export { useQuery } from './use-query.js';
@@ -3,4 +3,4 @@
3
3
  * Vite HMR uses it to replace a worker owner after a Syncular package upgrade
4
4
  * even when the application's generated schema version did not change.
5
5
  */
6
- export declare const SYNCULAR_REACT_RUNTIME_VERSION = "0.59.0";
6
+ export declare const SYNCULAR_REACT_RUNTIME_VERSION = "0.60.1";
@@ -3,4 +3,4 @@
3
3
  * Vite HMR uses it to replace a worker owner after a Syncular package upgrade
4
4
  * even when the application's generated schema version did not change.
5
5
  */
6
- export const SYNCULAR_REACT_RUNTIME_VERSION = '0.59.0';
6
+ export const SYNCULAR_REACT_RUNTIME_VERSION = '0.60.1';
@@ -1,11 +1,4 @@
1
- import type { ClientDiagnosticsSnapshot, ExpectedDiagnosticSubscription } from '@syncular/client';
2
- export interface UseDiagnosticsOptions {
3
- /**
4
- * Application-owned subscription intent. IDs must be stable and PHI-free;
5
- * no scope values are accepted by the diagnostics contract.
6
- */
7
- readonly expectedSubscriptions?: readonly ExpectedDiagnosticSubscription[];
8
- }
1
+ import type { ClientDiagnosticsSnapshot } from '@syncular/client';
9
2
  export interface UseDiagnosticsResult {
10
3
  readonly snapshot: ClientDiagnosticsSnapshot | undefined;
11
4
  readonly isLoading: boolean;
@@ -14,7 +7,6 @@ export interface UseDiagnosticsResult {
14
7
  }
15
8
  /**
16
9
  * Observe the versioned, privacy-safe diagnostics snapshot. Native/Worker
17
- * events are treated as invalidation signals and followed by a fresh request,
18
- * so expected-but-unregistered subscriptions remain visible on every host.
10
+ * events are treated as invalidation signals and followed by a fresh read.
19
11
  */
20
- export declare function useDiagnostics(options?: UseDiagnosticsOptions): UseDiagnosticsResult;
12
+ export declare function useDiagnostics(): UseDiagnosticsResult;
@@ -1,21 +1,14 @@
1
- import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
1
+ import { useCallback, useEffect, useRef, useState } from 'react';
2
2
  import { useSyncClient } from './use-client.js';
3
3
  /**
4
4
  * Observe the versioned, privacy-safe diagnostics snapshot. Native/Worker
5
- * events are treated as invalidation signals and followed by a fresh request,
6
- * so expected-but-unregistered subscriptions remain visible on every host.
5
+ * events are treated as invalidation signals and followed by a fresh read.
7
6
  */
8
- export function useDiagnostics(options = {}) {
7
+ export function useDiagnostics() {
9
8
  const client = useSyncClient();
10
- const requestKey = JSON.stringify(options.expectedSubscriptions ?? []);
11
- const request = useMemo(() => {
12
- const expectedSubscriptions = JSON.parse(requestKey);
13
- return expectedSubscriptions.length === 0 ? {} : { expectedSubscriptions };
14
- }, [requestKey]);
15
9
  const generation = useRef(0);
16
10
  const [state, setState] = useState({
17
11
  client,
18
- requestKey,
19
12
  snapshot: undefined,
20
13
  error: undefined,
21
14
  settled: false,
@@ -24,13 +17,12 @@ export function useDiagnostics(options = {}) {
24
17
  const current = ++generation.current;
25
18
  setState((prev) => (prev.settled ? { ...prev, settled: false } : prev));
26
19
  void Promise.resolve()
27
- .then(() => client.diagnosticsSnapshot(request))
20
+ .then(() => client.diagnosticsSnapshot())
28
21
  .then((next) => {
29
22
  if (generation.current !== current)
30
23
  return;
31
24
  setState({
32
25
  client,
33
- requestKey,
34
26
  snapshot: next,
35
27
  error: undefined,
36
28
  settled: true,
@@ -40,15 +32,12 @@ export function useDiagnostics(options = {}) {
40
32
  return;
41
33
  setState((prev) => ({
42
34
  client,
43
- requestKey,
44
- snapshot: prev.client === client && prev.requestKey === requestKey
45
- ? prev.snapshot
46
- : undefined,
35
+ snapshot: prev.client === client ? prev.snapshot : undefined,
47
36
  error: reason instanceof Error ? reason : new Error(String(reason)),
48
37
  settled: true,
49
38
  }));
50
39
  });
51
- }, [client, request, requestKey]);
40
+ }, [client]);
52
41
  useEffect(() => {
53
42
  const unsubscribe = client.onDiagnostics(refresh);
54
43
  refresh();
@@ -57,7 +46,7 @@ export function useDiagnostics(options = {}) {
57
46
  unsubscribe();
58
47
  };
59
48
  }, [client, refresh]);
60
- const current = state.client === client && state.requestKey === requestKey;
49
+ const current = state.client === client;
61
50
  return {
62
51
  snapshot: current ? state.snapshot : undefined,
63
52
  isLoading: !current || !state.settled,
@@ -1,5 +1,5 @@
1
1
  import type { SyncProgress, SyncProgressListener } from '@syncular/client';
2
- /** Live work snapshots; completion refers to one round (SPEC §7.6). */
2
+ /** Live work snapshots; completion refers to one round (SPEC §7.7). */
3
3
  export declare function useSyncProgress(client: {
4
4
  onProgress(listener: SyncProgressListener): () => void;
5
5
  progressSnapshot(): SyncProgress | undefined;
@@ -1,5 +1,5 @@
1
1
  import { useCallback, useSyncExternalStore } from 'react';
2
- /** Live work snapshots; completion refers to one round (SPEC §7.6). */
2
+ /** Live work snapshots; completion refers to one round (SPEC §7.7). */
3
3
  export function useSyncProgress(client) {
4
4
  const subscribe = useCallback((notify) => client.onProgress(notify), [client]);
5
5
  const snapshot = useCallback(() => client.progressSnapshot(), [client]);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@syncular/react",
3
- "version": "0.59.0",
3
+ "version": "0.60.1",
4
4
  "description": "React hooks for Syncular offline-first sync",
5
5
  "license": "Apache-2.0",
6
6
  "author": "Benjamin Kniffler",
@@ -55,15 +55,15 @@
55
55
  "test": "bun test --preload ./test/setup.ts"
56
56
  },
57
57
  "dependencies": {
58
- "@syncular/client": "0.59.0"
58
+ "@syncular/client": "0.60.1"
59
59
  },
60
60
  "peerDependencies": {
61
61
  "react": ">=18.0.0"
62
62
  },
63
63
  "devDependencies": {
64
64
  "@happy-dom/global-registrator": "^20.0.0",
65
- "@syncular/core": "0.59.0",
66
- "@syncular/server": "0.59.0",
65
+ "@syncular/core": "0.60.1",
66
+ "@syncular/server": "0.60.1",
67
67
  "@testing-library/react": "^16.1.0",
68
68
  "@types/react": "^18.3.0",
69
69
  "@types/react-dom": "^18.3.0",
package/src/index.ts CHANGED
@@ -29,11 +29,7 @@ export {
29
29
  useCommitOutcomes,
30
30
  } from './use-commit-outcomes';
31
31
  export { type UseConflictsResult, useConflicts } from './use-conflicts';
32
- export {
33
- type UseDiagnosticsOptions,
34
- type UseDiagnosticsResult,
35
- useDiagnostics,
36
- } from './use-diagnostics';
32
+ export { type UseDiagnosticsResult, useDiagnostics } from './use-diagnostics';
37
33
  export {
38
34
  type SyncTableDescriptor,
39
35
  type UseMutationOptions,
@@ -3,4 +3,4 @@
3
3
  * Vite HMR uses it to replace a worker owner after a Syncular package upgrade
4
4
  * even when the application's generated schema version did not change.
5
5
  */
6
- export const SYNCULAR_REACT_RUNTIME_VERSION = '0.59.0';
6
+ export const SYNCULAR_REACT_RUNTIME_VERSION = '0.60.1';
@@ -1,19 +1,7 @@
1
- import type {
2
- ClientDiagnosticsRequest,
3
- ClientDiagnosticsSnapshot,
4
- ExpectedDiagnosticSubscription,
5
- } from '@syncular/client';
6
- import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
1
+ import type { ClientDiagnosticsSnapshot } from '@syncular/client';
2
+ import { useCallback, useEffect, useRef, useState } from 'react';
7
3
  import { useSyncClient } from './use-client';
8
4
 
9
- export interface UseDiagnosticsOptions {
10
- /**
11
- * Application-owned subscription intent. IDs must be stable and PHI-free;
12
- * no scope values are accepted by the diagnostics contract.
13
- */
14
- readonly expectedSubscriptions?: readonly ExpectedDiagnosticSubscription[];
15
- }
16
-
17
5
  export interface UseDiagnosticsResult {
18
6
  readonly snapshot: ClientDiagnosticsSnapshot | undefined;
19
7
  readonly isLoading: boolean;
@@ -23,30 +11,18 @@ export interface UseDiagnosticsResult {
23
11
 
24
12
  /**
25
13
  * Observe the versioned, privacy-safe diagnostics snapshot. Native/Worker
26
- * events are treated as invalidation signals and followed by a fresh request,
27
- * so expected-but-unregistered subscriptions remain visible on every host.
14
+ * events are treated as invalidation signals and followed by a fresh read.
28
15
  */
29
- export function useDiagnostics(
30
- options: UseDiagnosticsOptions = {},
31
- ): UseDiagnosticsResult {
16
+ export function useDiagnostics(): UseDiagnosticsResult {
32
17
  const client = useSyncClient();
33
- const requestKey = JSON.stringify(options.expectedSubscriptions ?? []);
34
- const request = useMemo<ClientDiagnosticsRequest>(() => {
35
- const expectedSubscriptions = JSON.parse(
36
- requestKey,
37
- ) as ExpectedDiagnosticSubscription[];
38
- return expectedSubscriptions.length === 0 ? {} : { expectedSubscriptions };
39
- }, [requestKey]);
40
18
  const generation = useRef(0);
41
19
  const [state, setState] = useState<{
42
20
  readonly client: typeof client;
43
- readonly requestKey: string;
44
21
  readonly snapshot: ClientDiagnosticsSnapshot | undefined;
45
22
  readonly error: Error | undefined;
46
23
  readonly settled: boolean;
47
24
  }>({
48
25
  client,
49
- requestKey,
50
26
  snapshot: undefined,
51
27
  error: undefined,
52
28
  settled: false,
@@ -56,13 +32,12 @@ export function useDiagnostics(
56
32
  const current = ++generation.current;
57
33
  setState((prev) => (prev.settled ? { ...prev, settled: false } : prev));
58
34
  void Promise.resolve()
59
- .then(() => client.diagnosticsSnapshot(request))
35
+ .then(() => client.diagnosticsSnapshot())
60
36
  .then(
61
37
  (next) => {
62
38
  if (generation.current !== current) return;
63
39
  setState({
64
40
  client,
65
- requestKey,
66
41
  snapshot: next,
67
42
  error: undefined,
68
43
  settled: true,
@@ -72,17 +47,13 @@ export function useDiagnostics(
72
47
  if (generation.current !== current) return;
73
48
  setState((prev) => ({
74
49
  client,
75
- requestKey,
76
- snapshot:
77
- prev.client === client && prev.requestKey === requestKey
78
- ? prev.snapshot
79
- : undefined,
50
+ snapshot: prev.client === client ? prev.snapshot : undefined,
80
51
  error: reason instanceof Error ? reason : new Error(String(reason)),
81
52
  settled: true,
82
53
  }));
83
54
  },
84
55
  );
85
- }, [client, request, requestKey]);
56
+ }, [client]);
86
57
 
87
58
  useEffect(() => {
88
59
  const unsubscribe = client.onDiagnostics(refresh);
@@ -93,7 +64,7 @@ export function useDiagnostics(
93
64
  };
94
65
  }, [client, refresh]);
95
66
 
96
- const current = state.client === client && state.requestKey === requestKey;
67
+ const current = state.client === client;
97
68
  return {
98
69
  snapshot: current ? state.snapshot : undefined,
99
70
  isLoading: !current || !state.settled,
@@ -1,7 +1,7 @@
1
1
  import type { SyncProgress, SyncProgressListener } from '@syncular/client';
2
2
  import { useCallback, useSyncExternalStore } from 'react';
3
3
 
4
- /** Live work snapshots; completion refers to one round (SPEC §7.6). */
4
+ /** Live work snapshots; completion refers to one round (SPEC §7.7). */
5
5
  export function useSyncProgress(client: {
6
6
  onProgress(listener: SyncProgressListener): () => void;
7
7
  progressSnapshot(): SyncProgress | undefined;