@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 +21 -24
- package/dist/index.d.ts +1 -2
- package/dist/index.js +1 -2
- package/dist/runtime-version.d.ts +1 -1
- package/dist/runtime-version.js +1 -1
- package/dist/use-diagnostics.d.ts +3 -11
- package/dist/use-diagnostics.js +7 -18
- package/dist/use-mutation.js +23 -33
- package/dist/use-raw-sql.d.ts +2 -1
- package/dist/use-raw-sql.js +9 -6
- package/dist/use-sync-progress.d.ts +1 -1
- package/dist/use-sync-progress.js +1 -1
- package/package.json +4 -4
- package/src/index.ts +1 -6
- package/src/runtime-version.ts +1 -1
- package/src/use-diagnostics.ts +8 -37
- package/src/use-mutation.ts +36 -51
- package/src/use-raw-sql.ts +16 -7
- package/src/use-sync-progress.ts +1 -1
- package/dist/infer-tables.d.ts +0 -20
- package/dist/infer-tables.js +0 -33
- package/src/infer-tables.ts +0 -35
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`:
|
|
66
|
-
|
|
67
|
-
is `false`; previously read rows remain
|
|
68
|
-
|
|
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
|
-
|
|
223
|
-
|
|
224
|
-
|
|
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(
|
|
248
|
-
|
|
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
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
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
|
|
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
|
|
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.
|
|
6
|
+
export declare const SYNCULAR_REACT_RUNTIME_VERSION = "0.60.0";
|
package/dist/runtime-version.js
CHANGED
|
@@ -1,11 +1,4 @@
|
|
|
1
|
-
import type { ClientDiagnosticsSnapshot
|
|
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
|
|
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(
|
|
12
|
+
export declare function useDiagnostics(): UseDiagnosticsResult;
|
package/dist/use-diagnostics.js
CHANGED
|
@@ -1,21 +1,14 @@
|
|
|
1
|
-
import { useCallback, useEffect,
|
|
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
|
|
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(
|
|
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(
|
|
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
|
-
|
|
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
|
|
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
|
|
49
|
+
const current = state.client === client;
|
|
61
50
|
return {
|
|
62
51
|
snapshot: current ? state.snapshot : undefined,
|
|
63
52
|
isLoading: !current || !state.settled,
|
package/dist/use-mutation.js
CHANGED
|
@@ -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
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
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
|
}
|
package/dist/use-raw-sql.d.ts
CHANGED
|
@@ -21,7 +21,8 @@ export interface UseRawSqlOptions<Row = SqlRow> {
|
|
|
21
21
|
}
|
|
22
22
|
export interface UseRawSqlResult<Row> {
|
|
23
23
|
readonly rows: readonly Row[];
|
|
24
|
-
|
|
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;
|
package/dist/use-raw-sql.js
CHANGED
|
@@ -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: '
|
|
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
|
-
|
|
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
|
|
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.
|
|
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.
|
|
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.
|
|
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
|
+
"@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.
|
|
66
|
-
"@syncular/server": "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,
|
package/src/runtime-version.ts
CHANGED
package/src/use-diagnostics.ts
CHANGED
|
@@ -1,19 +1,7 @@
|
|
|
1
|
-
import type {
|
|
2
|
-
|
|
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
|
|
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(
|
|
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
|
-
|
|
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
|
|
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
|
|
67
|
+
const current = state.client === client;
|
|
97
68
|
return {
|
|
98
69
|
snapshot: current ? state.snapshot : undefined,
|
|
99
70
|
isLoading: !current || !state.settled,
|
package/src/use-mutation.ts
CHANGED
|
@@ -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
|
|
103
|
-
(
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
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
|
-
|
|
152
|
-
return { ...base, upsert, patch, remove };
|
|
137
|
+
return helpers === undefined ? base : { ...base, ...helpers };
|
|
153
138
|
}
|
package/src/use-raw-sql.ts
CHANGED
|
@@ -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
|
-
|
|
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: '
|
|
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
|
-
|
|
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
|
|
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,
|
package/src/use-sync-progress.ts
CHANGED
|
@@ -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.
|
|
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;
|
package/dist/infer-tables.d.ts
DELETED
|
@@ -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>;
|
package/dist/infer-tables.js
DELETED
|
@@ -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
|
-
}
|
package/src/infer-tables.ts
DELETED
|
@@ -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
|
-
}
|