@syncular/react 0.58.0 → 0.60.0

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
@@ -27,7 +27,7 @@ function Tasks({ projectId }: { projectId: string }) {
27
27
  const mutation = useMutation(tasksTable);
28
28
 
29
29
  if (tasks.phase === 'loading') return <p>Loading…</p>;
30
- if (tasks.phase === 'blocked') {
30
+ if (tasks.phase === 'blocked' && tasks.availability.state === 'blocked') {
31
31
  return <p>Sync unavailable: {tasks.availability.reason}</p>;
32
32
  }
33
33
  if (tasks.phase === 'error') return <p>{tasks.error?.message}</p>;
@@ -62,12 +62,16 @@ availability, refresh }`. `availability` is the typed `ready`, `migrating`, or
62
62
  - `partial`: rows exist, but some required window coverage is incomplete;
63
63
  - `ready`: the atomic snapshot says the answer is complete, including an
64
64
  honestly empty result;
65
- - `blocked`: sync cannot safely serve a fresh result because the generated
66
- schema is incompatible or the browser leader is unreachable. `isLoading`
67
- is `false`; previously read rows remain available for deliberate read-only
68
- UI, and `availability.reason` identifies the boundary;
65
+ - `blocked`: the tab cannot read through the browser leader, and
66
+ `availability.reason` is `leader-unreachable`, `leader-incompatible`, or
67
+ `leadership-taken`. `isLoading` is `false`; previously read rows remain
68
+ available for deliberate read-only UI. A schema block stops network transfer
69
+ and leaves local reads running, so it appears in `availability` and leaves
70
+ `phase` unchanged;
69
71
  - `error`: the latest read failed. A refresh error keeps the rows and revision
70
72
  from the last successful read while setting `isRefreshing` to `false`.
73
+ - `disabled`: the hook was given `enabled: false` and reads nothing; `rows`
74
+ is empty and `isLoading` is `false`.
71
75
 
72
76
  ## Provider and async initialization
73
77
 
@@ -219,9 +223,11 @@ Options:
219
223
  | `id` | Stable cache identity for a raw query. |
220
224
  | `tables`, `scopeKeys` | Compatibility shorthand; prefer `dependencies`. |
221
225
 
222
- Without explicit dependencies, raw SQL uses a conservative `FROM`/`JOIN`
223
- scan. Generated queries are preferred whenever the statement is known at
224
- build time because typegen can prove more.
226
+ `useRawSql` reads no table names from the SQL text. Pass `dependencies` or
227
+ `tables` naming every table the statement reads; without either, the hook
228
+ throws a `ClientSyncError` with code `client.raw_sql_dependencies_required`
229
+ when it mounts. Generated queries are preferred whenever the statement is
230
+ known at build time because typegen derives the dependencies from the schema.
225
231
 
226
232
  ## Exact changes and windows
227
233
 
@@ -244,10 +250,8 @@ not need a custom retention effect.
244
250
 
245
251
  ## Other hooks
246
252
 
247
- - `useDiagnostics({ expectedSubscriptions })` observes the versioned,
248
- privacy-safe support snapshot. Native/Worker events trigger a fresh request,
249
- preserving expected-but-unregistered intent on every host. Subscription ids
250
- 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.
251
255
  - `useSyncStatus()` observes the status domain without a follow-up read after
252
256
  every row change. It includes `availability` and `currentSchemaVersion`;
253
257
  `outbox` is local push work, while `syncNeeded` specifically means an inbound
@@ -286,23 +290,16 @@ a stable error code, an optional SQLite result code, and the first failure
286
290
  time. It never contains SQL, parameters, rows, or SQLite error prose. Raw SQL
287
291
  uses the diagnostic id `raw` unless `useRawSql` receives an explicit `id`.
288
292
 
289
- Use application-owned, stable, PHI-free subscription ids to make missing
290
- registration distinguishable from a completed zero-row bootstrap. The hook
291
- refreshes after diagnostics events on direct, Worker, Tauri, and React Native
292
- 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:
293
297
 
294
298
  ```tsx
295
299
  import { useDiagnostics } from '@syncular/react';
296
300
 
297
- const expectedSubscriptions = [
298
- { id: 'membership-security', table: 'facility_memberships' },
299
- { id: 'scheduler-window', table: 'surgeries' },
300
- ] as const;
301
-
302
301
  function SyncSupportPanel() {
303
- const { snapshot, isLoading, error, refresh } = useDiagnostics({
304
- expectedSubscriptions,
305
- });
302
+ const { snapshot, isLoading, error, refresh } = useDiagnostics();
306
303
 
307
304
  if (isLoading) return <p>Collecting local sync evidence…</p>;
308
305
  if (error) return <p>Diagnostics unavailable: {error.message}</p>;
package/dist/index.d.ts CHANGED
@@ -8,14 +8,13 @@
8
8
  * option.
9
9
  */
10
10
  export type { SyncClientLike } from './client.js';
11
- export { inferTables } from './infer-tables.js';
12
11
  export { type SyncBoundaryActions, type SyncBoundaryState, SyncContext, SyncProvider, type SyncProviderProps, SyncStoreContext, } from './provider.js';
13
12
  export { createSyncClientResource, isSyncClientResource, type SyncClientResource, type SyncClientResourceSnapshot, } from './resource.js';
14
13
  export { SYNCULAR_REACT_RUNTIME_VERSION } from './runtime-version.js';
15
14
  export { useReactiveStore, useSyncClient } from './use-client.js';
16
15
  export { type UseCommitOutcomesResult, useCommitOutcomes, } from './use-commit-outcomes.js';
17
16
  export { type UseConflictsResult, useConflicts } from './use-conflicts.js';
18
- export { type UseDiagnosticsOptions, type UseDiagnosticsResult, useDiagnostics, } from './use-diagnostics.js';
17
+ export { type UseDiagnosticsResult, useDiagnostics } from './use-diagnostics.js';
19
18
  export { type SyncTableDescriptor, type UseMutationOptions, type UseMutationResult, type UseTableMutationResult, useMutation, } from './use-mutation.js';
20
19
  export { usePresence } from './use-presence.js';
21
20
  export { type NamedQueryDescriptor, useQuery } from './use-query.js';
package/dist/index.js CHANGED
@@ -1,11 +1,10 @@
1
- export { inferTables } from './infer-tables.js';
2
1
  export { SyncContext, SyncProvider, SyncStoreContext, } from './provider.js';
3
2
  export { createSyncClientResource, isSyncClientResource, } from './resource.js';
4
3
  export { SYNCULAR_REACT_RUNTIME_VERSION } from './runtime-version.js';
5
4
  export { useReactiveStore, useSyncClient } from './use-client.js';
6
5
  export { useCommitOutcomes, } from './use-commit-outcomes.js';
7
6
  export { useConflicts } from './use-conflicts.js';
8
- export { useDiagnostics, } from './use-diagnostics.js';
7
+ export { useDiagnostics } from './use-diagnostics.js';
9
8
  export { useMutation, } from './use-mutation.js';
10
9
  export { usePresence } from './use-presence.js';
11
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.58.0";
6
+ export declare const SYNCULAR_REACT_RUNTIME_VERSION = "0.60.0";
@@ -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.58.0';
6
+ export const SYNCULAR_REACT_RUNTIME_VERSION = '0.60.0';
@@ -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,4 +1,4 @@
1
- import { useCallback, useRef, useState } from 'react';
1
+ import { useCallback, useMemo, useRef, useState } from 'react';
2
2
  import { useSyncClient } from './use-client.js';
3
3
  export function useMutation(tableOrOptions, maybeOptions) {
4
4
  const client = useSyncClient();
@@ -39,36 +39,26 @@ export function useMutation(tableOrOptions, maybeOptions) {
39
39
  error,
40
40
  resetError,
41
41
  };
42
- const upsert = useCallback((values, baseVersion) => {
43
- if (table === undefined)
44
- throw new Error('table mutation descriptor missing');
45
- return mutate([
46
- {
47
- table: table.name,
48
- op: 'upsert',
49
- values: values,
50
- ...(baseVersion !== undefined ? { baseVersion } : {}),
51
- },
52
- ]);
53
- }, [mutate, table]);
54
- const patch = useCallback((id, partial, baseVersion) => {
55
- if (table === undefined)
56
- throw new Error('table mutation descriptor missing');
57
- return run(() => client.patch(table.name, String(id), partial, baseVersion !== undefined ? { baseVersion } : undefined));
58
- }, [client, run, table]);
59
- const remove = useCallback((id, baseVersion) => {
60
- if (table === undefined)
61
- throw new Error('table mutation descriptor missing');
62
- return mutate([
63
- {
64
- table: table.name,
65
- op: 'delete',
66
- rowId: String(id),
67
- ...(baseVersion !== undefined ? { baseVersion } : {}),
68
- },
69
- ]);
70
- }, [mutate, table]);
71
- if (table === undefined)
72
- return base;
73
- return { ...base, upsert, patch, remove };
42
+ const helpers = useMemo(() => table === undefined
43
+ ? undefined
44
+ : {
45
+ upsert: (values, baseVersion) => mutate([
46
+ {
47
+ table: table.name,
48
+ op: 'upsert',
49
+ values: values,
50
+ ...(baseVersion !== undefined ? { baseVersion } : {}),
51
+ },
52
+ ]),
53
+ patch: (id, partial, baseVersion) => run(() => client.patch(table.name, String(id), partial, baseVersion !== undefined ? { baseVersion } : undefined)),
54
+ remove: (id, baseVersion) => mutate([
55
+ {
56
+ table: table.name,
57
+ op: 'delete',
58
+ rowId: String(id),
59
+ ...(baseVersion !== undefined ? { baseVersion } : {}),
60
+ },
61
+ ]),
62
+ }, [client, mutate, run, table]);
63
+ return helpers === undefined ? base : { ...base, ...helpers };
74
64
  }
@@ -21,7 +21,8 @@ export interface UseRawSqlOptions<Row = SqlRow> {
21
21
  }
22
22
  export interface UseRawSqlResult<Row> {
23
23
  readonly rows: readonly Row[];
24
- readonly phase: LiveQueryPhase;
24
+ /** `disabled` while `enabled` is `false`: the hook reads nothing. */
25
+ readonly phase: LiveQueryPhase | 'disabled';
25
26
  readonly revision: bigint | undefined;
26
27
  readonly isLoading: boolean;
27
28
  readonly isRefreshing: boolean;
@@ -1,10 +1,9 @@
1
- import { canonicalValue, } from '@syncular/client';
1
+ import { canonicalValue, ClientSyncError, } from '@syncular/client';
2
2
  import { useCallback, useMemo, useSyncExternalStore } from 'react';
3
- import { inferTables } from './infer-tables.js';
4
3
  import { useReactiveStore } from './use-client.js';
5
4
  const DISABLED = {
6
5
  rows: [],
7
- phase: 'ready',
6
+ phase: 'disabled',
8
7
  revision: undefined,
9
8
  error: undefined,
10
9
  isRefreshing: false,
@@ -14,20 +13,24 @@ const noSubscribe = () => () => { };
14
13
  export function useRawSql(sql, params, options) {
15
14
  const store = useReactiveStore();
16
15
  const enabled = options?.enabled ?? true;
17
- const inferred = options?.tables ?? [...inferTables(sql)];
18
16
  const dependencies = options?.dependencies ??
19
- inferred.map((table) => ({
17
+ options?.tables?.map((table) => ({
20
18
  table,
21
19
  ...(options?.scopeKeys !== undefined
22
20
  ? { scopeKeys: options.scopeKeys }
23
21
  : {}),
24
22
  }));
23
+ if (dependencies === undefined) {
24
+ throw new ClientSyncError('client.raw_sql_dependencies_required', '@syncular/react: useRawSql needs `dependencies` or `tables` naming every table the SQL reads; the query re-runs only when one of them changes.');
25
+ }
25
26
  const coverage = options?.coverage ?? [];
27
+ const claimCoverage = options?.claimCoverage ?? true;
26
28
  const identity = canonicalValue({
27
29
  sql,
28
30
  params: params ?? [],
29
31
  dependencies,
30
32
  coverage,
33
+ claimCoverage,
31
34
  ...(options?.id !== undefined ? { id: options.id } : {}),
32
35
  });
33
36
  // `identity` canonically contains every value-shaped input. Depending on
@@ -44,7 +47,7 @@ export function useRawSql(sql, params, options) {
44
47
  ...(coverage.length > 0 ? { coverage } : {}),
45
48
  ...(options?.mapRow !== undefined ? { mapRow: options.mapRow } : {}),
46
49
  ...(options?.rowKey !== undefined ? { rowKey: options.rowKey } : {}),
47
- claimCoverage: options?.claimCoverage ?? true,
50
+ claimCoverage,
48
51
  }), [store, identity, options?.mapRow, options?.rowKey]);
49
52
  // oxlint-enable react-hooks/exhaustive-deps
50
53
  const snapshot = useSyncExternalStore(enabled ? entry.subscribe : noSubscribe, enabled ? entry.getSnapshot : () => DISABLED, enabled ? entry.getSnapshot : () => DISABLED);
@@ -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.58.0",
3
+ "version": "0.60.0",
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.58.0"
58
+ "@syncular/client": "0.60.0"
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.58.0",
66
- "@syncular/server": "0.58.0",
65
+ "@syncular/core": "0.60.0",
66
+ "@syncular/server": "0.60.0",
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
@@ -8,7 +8,6 @@
8
8
  * option.
9
9
  */
10
10
  export type { SyncClientLike } from './client';
11
- export { inferTables } from './infer-tables';
12
11
  export {
13
12
  type SyncBoundaryActions,
14
13
  type SyncBoundaryState,
@@ -30,11 +29,7 @@ export {
30
29
  useCommitOutcomes,
31
30
  } from './use-commit-outcomes';
32
31
  export { type UseConflictsResult, useConflicts } from './use-conflicts';
33
- export {
34
- type UseDiagnosticsOptions,
35
- type UseDiagnosticsResult,
36
- useDiagnostics,
37
- } from './use-diagnostics';
32
+ export { type UseDiagnosticsResult, useDiagnostics } from './use-diagnostics';
38
33
  export {
39
34
  type SyncTableDescriptor,
40
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.58.0';
6
+ export const SYNCULAR_REACT_RUNTIME_VERSION = '0.60.0';
@@ -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,5 +1,5 @@
1
1
  import type { MutationInput } from '@syncular/client';
2
- import { useCallback, useRef, useState } from 'react';
2
+ import { useCallback, useMemo, useRef, useState } from 'react';
3
3
  import { useSyncClient } from './use-client';
4
4
 
5
5
  export interface SyncTableDescriptor<Row, Insert, Update, Id> {
@@ -99,55 +99,40 @@ export function useMutation<Row, Insert, Update, Id>(
99
99
  error,
100
100
  resetError,
101
101
  };
102
- const upsert = useCallback(
103
- (values: Insert, baseVersion?: number): Promise<string> => {
104
- if (table === undefined)
105
- throw new Error('table mutation descriptor missing');
106
- return mutate([
107
- {
108
- table: table.name,
109
- op: 'upsert',
110
- values: values as Readonly<Record<string, unknown>>,
111
- ...(baseVersion !== undefined ? { baseVersion } : {}),
112
- },
113
- ]);
114
- },
115
- [mutate, table],
116
- );
117
- const patch = useCallback(
118
- (
119
- id: Id,
120
- partial: Partial<Update>,
121
- baseVersion?: number,
122
- ): Promise<string> => {
123
- if (table === undefined)
124
- throw new Error('table mutation descriptor missing');
125
- return run(() =>
126
- client.patch(
127
- table.name,
128
- String(id),
129
- partial as Readonly<Record<string, unknown>>,
130
- baseVersion !== undefined ? { baseVersion } : undefined,
131
- ),
132
- );
133
- },
134
- [client, run, table],
135
- );
136
- const remove = useCallback(
137
- (id: Id, baseVersion?: number): Promise<string> => {
138
- if (table === undefined)
139
- throw new Error('table mutation descriptor missing');
140
- return mutate([
141
- {
142
- table: table.name,
143
- op: 'delete',
144
- rowId: String(id),
145
- ...(baseVersion !== undefined ? { baseVersion } : {}),
146
- },
147
- ]);
148
- },
149
- [mutate, table],
102
+ const helpers = useMemo(
103
+ () =>
104
+ table === undefined
105
+ ? undefined
106
+ : {
107
+ upsert: (values: Insert, baseVersion?: number) =>
108
+ mutate([
109
+ {
110
+ table: table.name,
111
+ op: 'upsert',
112
+ values: values as Readonly<Record<string, unknown>>,
113
+ ...(baseVersion !== undefined ? { baseVersion } : {}),
114
+ },
115
+ ]),
116
+ patch: (id: Id, partial: Partial<Update>, baseVersion?: number) =>
117
+ run(() =>
118
+ client.patch(
119
+ table.name,
120
+ String(id),
121
+ partial as Readonly<Record<string, unknown>>,
122
+ baseVersion !== undefined ? { baseVersion } : undefined,
123
+ ),
124
+ ),
125
+ remove: (id: Id, baseVersion?: number) =>
126
+ mutate([
127
+ {
128
+ table: table.name,
129
+ op: 'delete',
130
+ rowId: String(id),
131
+ ...(baseVersion !== undefined ? { baseVersion } : {}),
132
+ },
133
+ ]),
134
+ },
135
+ [client, mutate, run, table],
150
136
  );
151
- if (table === undefined) return base;
152
- return { ...base, upsert, patch, remove };
137
+ return helpers === undefined ? base : { ...base, ...helpers };
153
138
  }
@@ -1,6 +1,8 @@
1
1
  import {
2
2
  canonicalValue,
3
+ ClientSyncError,
3
4
  type LiveQueryPhase,
5
+ type LiveQueryResult,
4
6
  type QueryDependency,
5
7
  type SqlRow,
6
8
  type SqlValue,
@@ -8,7 +10,6 @@ import {
8
10
  type WindowCoverage,
9
11
  } from '@syncular/client';
10
12
  import { useCallback, useMemo, useSyncExternalStore } from 'react';
11
- import { inferTables } from './infer-tables';
12
13
  import { useReactiveStore } from './use-client';
13
14
 
14
15
  export interface UseRawSqlOptions<Row = SqlRow> {
@@ -34,7 +35,8 @@ export interface UseRawSqlOptions<Row = SqlRow> {
34
35
 
35
36
  export interface UseRawSqlResult<Row> {
36
37
  readonly rows: readonly Row[];
37
- readonly phase: LiveQueryPhase;
38
+ /** `disabled` while `enabled` is `false`: the hook reads nothing. */
39
+ readonly phase: LiveQueryPhase | 'disabled';
38
40
  readonly revision: bigint | undefined;
39
41
  readonly isLoading: boolean;
40
42
  readonly isRefreshing: boolean;
@@ -45,7 +47,7 @@ export interface UseRawSqlResult<Row> {
45
47
 
46
48
  const DISABLED = {
47
49
  rows: [],
48
- phase: 'ready',
50
+ phase: 'disabled',
49
51
  revision: undefined,
50
52
  error: undefined,
51
53
  isRefreshing: false,
@@ -61,21 +63,28 @@ export function useRawSql<Row = SqlRow>(
61
63
  ): UseRawSqlResult<Row> {
62
64
  const store = useReactiveStore();
63
65
  const enabled = options?.enabled ?? true;
64
- const inferred = options?.tables ?? [...inferTables(sql)];
65
66
  const dependencies =
66
67
  options?.dependencies ??
67
- inferred.map((table) => ({
68
+ options?.tables?.map((table) => ({
68
69
  table,
69
70
  ...(options?.scopeKeys !== undefined
70
71
  ? { scopeKeys: options.scopeKeys }
71
72
  : {}),
72
73
  }));
74
+ if (dependencies === undefined) {
75
+ throw new ClientSyncError(
76
+ 'client.raw_sql_dependencies_required',
77
+ '@syncular/react: useRawSql needs `dependencies` or `tables` naming every table the SQL reads; the query re-runs only when one of them changes.',
78
+ );
79
+ }
73
80
  const coverage = options?.coverage ?? [];
81
+ const claimCoverage = options?.claimCoverage ?? true;
74
82
  const identity = canonicalValue({
75
83
  sql,
76
84
  params: params ?? [],
77
85
  dependencies,
78
86
  coverage,
87
+ claimCoverage,
79
88
  ...(options?.id !== undefined ? { id: options.id } : {}),
80
89
  });
81
90
  // `identity` canonically contains every value-shaped input. Depending on
@@ -94,12 +103,12 @@ export function useRawSql<Row = SqlRow>(
94
103
  ...(coverage.length > 0 ? { coverage } : {}),
95
104
  ...(options?.mapRow !== undefined ? { mapRow: options.mapRow } : {}),
96
105
  ...(options?.rowKey !== undefined ? { rowKey: options.rowKey } : {}),
97
- claimCoverage: options?.claimCoverage ?? true,
106
+ claimCoverage,
98
107
  }),
99
108
  [store, identity, options?.mapRow, options?.rowKey],
100
109
  );
101
110
  // oxlint-enable react-hooks/exhaustive-deps
102
- const snapshot = useSyncExternalStore(
111
+ const snapshot = useSyncExternalStore<LiveQueryResult<Row> | typeof DISABLED>(
103
112
  enabled ? entry.subscribe : noSubscribe,
104
113
  enabled ? entry.getSnapshot : () => DISABLED,
105
114
  enabled ? entry.getSnapshot : () => DISABLED,
@@ -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;
@@ -1,20 +0,0 @@
1
- /**
2
- * Conservative table inference for `useRawSql`: infer
3
- * conservatively from the SQL text's table names … documented as a
4
- * heuristic with the explicit option as the escape hatch").
5
- *
6
- * This is a SIMPLE identifier scan, NOT a SQL parser. It collects the
7
- * identifiers that follow `FROM` and `JOIN` — the tables a SELECT reads.
8
- * It is deliberately over-inclusive at the edges (a table aliased in a CTE,
9
- * a function-table, an odd quoting style) because the failure mode of
10
- * over-inclusion is a harmless extra re-run, whereas under-inclusion is a
11
- * stale query — the one thing live queries must never do. When a query's
12
- * real dependencies cannot be read off its text (dynamic SQL, views,
13
- * unusual syntax), pass the explicit `tables` option; that always wins.
14
- */
15
- /**
16
- * Extract the table names a SELECT reads. Returns a de-duplicated,
17
- * lower-nothing set (identifiers are compared to invalidation table names
18
- * as-is — SQLite table names are case-sensitive for our generated schema).
19
- */
20
- export declare function inferTables(sql: string): Set<string>;
@@ -1,33 +0,0 @@
1
- /**
2
- * Conservative table inference for `useRawSql`: infer
3
- * conservatively from the SQL text's table names … documented as a
4
- * heuristic with the explicit option as the escape hatch").
5
- *
6
- * This is a SIMPLE identifier scan, NOT a SQL parser. It collects the
7
- * identifiers that follow `FROM` and `JOIN` — the tables a SELECT reads.
8
- * It is deliberately over-inclusive at the edges (a table aliased in a CTE,
9
- * a function-table, an odd quoting style) because the failure mode of
10
- * over-inclusion is a harmless extra re-run, whereas under-inclusion is a
11
- * stale query — the one thing live queries must never do. When a query's
12
- * real dependencies cannot be read off its text (dynamic SQL, views,
13
- * unusual syntax), pass the explicit `tables` option; that always wins.
14
- */
15
- const FROM_JOIN_RE = /\b(?:from|join)\s+(?:"([^"]+)"|`([^`]+)`|\[([^\]]+)\]|([a-zA-Z_][a-zA-Z0-9_$]*))/gi;
16
- /**
17
- * Extract the table names a SELECT reads. Returns a de-duplicated,
18
- * lower-nothing set (identifiers are compared to invalidation table names
19
- * as-is — SQLite table names are case-sensitive for our generated schema).
20
- */
21
- export function inferTables(sql) {
22
- const tables = new Set();
23
- // Strip a leading schema qualifier (`main.tasks` → `tasks`) so the name
24
- // matches the invalidation event's bare table name.
25
- for (const match of sql.matchAll(FROM_JOIN_RE)) {
26
- const raw = match[1] ?? match[2] ?? match[3] ?? match[4];
27
- if (raw === undefined)
28
- continue;
29
- const dot = raw.lastIndexOf('.');
30
- tables.add(dot === -1 ? raw : raw.slice(dot + 1));
31
- }
32
- return tables;
33
- }
@@ -1,35 +0,0 @@
1
- /**
2
- * Conservative table inference for `useRawSql`: infer
3
- * conservatively from the SQL text's table names … documented as a
4
- * heuristic with the explicit option as the escape hatch").
5
- *
6
- * This is a SIMPLE identifier scan, NOT a SQL parser. It collects the
7
- * identifiers that follow `FROM` and `JOIN` — the tables a SELECT reads.
8
- * It is deliberately over-inclusive at the edges (a table aliased in a CTE,
9
- * a function-table, an odd quoting style) because the failure mode of
10
- * over-inclusion is a harmless extra re-run, whereas under-inclusion is a
11
- * stale query — the one thing live queries must never do. When a query's
12
- * real dependencies cannot be read off its text (dynamic SQL, views,
13
- * unusual syntax), pass the explicit `tables` option; that always wins.
14
- */
15
-
16
- const FROM_JOIN_RE =
17
- /\b(?:from|join)\s+(?:"([^"]+)"|`([^`]+)`|\[([^\]]+)\]|([a-zA-Z_][a-zA-Z0-9_$]*))/gi;
18
-
19
- /**
20
- * Extract the table names a SELECT reads. Returns a de-duplicated,
21
- * lower-nothing set (identifiers are compared to invalidation table names
22
- * as-is — SQLite table names are case-sensitive for our generated schema).
23
- */
24
- export function inferTables(sql: string): Set<string> {
25
- const tables = new Set<string>();
26
- // Strip a leading schema qualifier (`main.tasks` → `tasks`) so the name
27
- // matches the invalidation event's bare table name.
28
- for (const match of sql.matchAll(FROM_JOIN_RE)) {
29
- const raw = match[1] ?? match[2] ?? match[3] ?? match[4];
30
- if (raw === undefined) continue;
31
- const dot = raw.lastIndexOf('.');
32
- tables.add(dot === -1 ? raw : raw.slice(dot + 1));
33
- }
34
- return tables;
35
- }