@syncular/react 0.86.0 → 0.90.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 +4 -0
- package/dist/client.d.ts +3 -2
- package/dist/index.d.ts +1 -0
- package/dist/index.js +1 -0
- package/dist/runtime-version.d.ts +1 -1
- package/dist/runtime-version.js +1 -1
- package/dist/use-commit-delivery.d.ts +16 -0
- package/dist/use-commit-delivery.js +76 -0
- package/package.json +4 -4
- package/src/client.ts +6 -1
- package/src/index.ts +4 -0
- package/src/runtime-version.ts +1 -1
- package/src/use-commit-delivery.ts +100 -0
package/README.md
CHANGED
|
@@ -265,6 +265,10 @@ not need a custom retention effect.
|
|
|
265
265
|
- `useCommitOutcomes()` observes the durable newest-first final-outcome journal
|
|
266
266
|
from exact `outcomesChanged` batches. Resolve entries through the client
|
|
267
267
|
returned by `useSyncClient()`.
|
|
268
|
+
- `useCommitDelivery(ids)` returns each listed commit's delivery status:
|
|
269
|
+
`pending` while the outbox holds it, `known` with its final outcome, or
|
|
270
|
+
`unknown` when neither the outbox nor the journal holds the ID. It reads in
|
|
271
|
+
one `snapshotRead` and re-reads on outbox and outcome-journal batches.
|
|
268
272
|
- `usePresence(scopeKey)` observes ephemeral realtime peers.
|
|
269
273
|
- `useSyncClient()` and `useReactiveStore()` expose the normalized low-level
|
|
270
274
|
surfaces for integrations. When the concrete client was passed through
|
package/dist/client.d.ts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
/** The provider uses the supplied client identity and canonical snapshot methods. */
|
|
2
|
-
import type { ClientSnapshotReader, SyncProgress, SyncProgressListener, ClientChangeListener, ClientDiagnosticsListener, CommitOutcome, CurrentBaseProof, InvalidationListener, LeadershipState, LocalDataPurgeInput, LocalDataPurgeResult, LocalDataRebootstrapInput, LocalDataRebootstrapResult, MutationInput, PresencePeer, QueryReadSpec, QuerySnapshot, SecurityLifecycle, SqlRow, SqlValue, WindowBase, WindowState } from '@syncular/client';
|
|
2
|
+
import type { ClientSnapshotReader, SyncProgress, SyncProgressListener, ClientChangeListener, ClientDiagnosticsListener, CommitOutcome, CurrentBaseProof, InvalidationListener, ReplaceCommitOutcomeInput, LeadershipState, LocalDataPurgeInput, LocalDataPurgeResult, LocalDataRebootstrapInput, LocalDataRebootstrapResult, MutationInput, OutboxCommit, PresencePeer, QueryReadSpec, QuerySnapshot, SecurityLifecycle, SqlRow, SqlValue, WindowBase, WindowState } from '@syncular/client';
|
|
3
3
|
export interface SyncClientLike extends ClientSnapshotReader {
|
|
4
4
|
readonly currentSchemaVersion?: number;
|
|
5
5
|
onProgress(listener: SyncProgressListener): () => void;
|
|
@@ -26,8 +26,9 @@ export interface SyncClientLike extends ClientSnapshotReader {
|
|
|
26
26
|
purgeLocalData(input: LocalDataPurgeInput): LocalDataPurgeResult | Promise<LocalDataPurgeResult>;
|
|
27
27
|
rebootstrapLocalData(input: LocalDataRebootstrapInput): LocalDataRebootstrapResult | Promise<LocalDataRebootstrapResult>;
|
|
28
28
|
querySnapshot<Row = SqlRow>(spec: QueryReadSpec): QuerySnapshot<Row> | Promise<QuerySnapshot<Row>>;
|
|
29
|
-
pendingCommits
|
|
29
|
+
pendingCommits(): OutboxCommit[] | Promise<OutboxCommit[]>;
|
|
30
30
|
proveCurrentBase(outcome: Pick<CommitOutcome, 'clientCommitId' | 'sequence'>, maxRounds?: number): CurrentBaseProof | Promise<CurrentBaseProof>;
|
|
31
|
+
replaceCommitOutcome(input: ReplaceCommitOutcomeInput): string | Promise<string>;
|
|
31
32
|
presence(scopeKey: string): readonly PresencePeer[] | Promise<readonly PresencePeer[]>;
|
|
32
33
|
setPresence(scopeKey: string, doc: Record<string, unknown> | null): void | Promise<void>;
|
|
33
34
|
/** §4.8 windowed subscriptions: set the live units for a window base. */
|
package/dist/index.d.ts
CHANGED
|
@@ -12,6 +12,7 @@ export { type SyncBoundaryActions, type SyncBoundaryState, SyncContext, SyncProv
|
|
|
12
12
|
export { createSyncClientResource, isSyncClientResource, type SyncClientResource, type SyncClientResourceSnapshot, } from './resource.js';
|
|
13
13
|
export { SYNCULAR_REACT_RUNTIME_VERSION } from './runtime-version.js';
|
|
14
14
|
export { useReactiveStore, useSyncClient } from './use-client.js';
|
|
15
|
+
export { type UseCommitDeliveryResult, useCommitDelivery, } from './use-commit-delivery.js';
|
|
15
16
|
export { type UseCommitOutcomesResult, useCommitOutcomes, } from './use-commit-outcomes.js';
|
|
16
17
|
export { type UseConflictsResult, useConflicts } from './use-conflicts.js';
|
|
17
18
|
export { type UseDiagnosticsResult, useDiagnostics } from './use-diagnostics.js';
|
package/dist/index.js
CHANGED
|
@@ -2,6 +2,7 @@ export { SyncContext, SyncProvider, SyncStoreContext, } from './provider.js';
|
|
|
2
2
|
export { createSyncClientResource, isSyncClientResource, } from './resource.js';
|
|
3
3
|
export { SYNCULAR_REACT_RUNTIME_VERSION } from './runtime-version.js';
|
|
4
4
|
export { useReactiveStore, useSyncClient } from './use-client.js';
|
|
5
|
+
export { useCommitDelivery, } from './use-commit-delivery.js';
|
|
5
6
|
export { useCommitOutcomes, } from './use-commit-outcomes.js';
|
|
6
7
|
export { useConflicts } from './use-conflicts.js';
|
|
7
8
|
export { useDiagnostics } from './use-diagnostics.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.90.0";
|
package/dist/runtime-version.js
CHANGED
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `useCommitDelivery(ids)`: the §7.5 delivery status of each client commit in
|
|
3
|
+
* `ids`, in request order, from one `snapshotRead`. The hook re-reads when a
|
|
4
|
+
* change batch carries a status (outbox writes and drains report one) or an
|
|
5
|
+
* outcome-journal change, so a commit moves from `pending` to `known` without
|
|
6
|
+
* polling. `unknown` means neither the outbox nor the journal holds the id:
|
|
7
|
+
* this client never wrote it, or retention pruned its outcome.
|
|
8
|
+
*/
|
|
9
|
+
import type { CommitDelivery } from '@syncular/client';
|
|
10
|
+
export interface UseCommitDeliveryResult {
|
|
11
|
+
/** One entry per requested id, in request order; empty until the first read. */
|
|
12
|
+
readonly deliveries: readonly CommitDelivery[];
|
|
13
|
+
readonly isLoading: boolean;
|
|
14
|
+
readonly error: Error | undefined;
|
|
15
|
+
}
|
|
16
|
+
export declare function useCommitDelivery(ids: readonly string[]): UseCommitDeliveryResult;
|
|
@@ -0,0 +1,76 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `useCommitDelivery(ids)`: the §7.5 delivery status of each client commit in
|
|
3
|
+
* `ids`, in request order, from one `snapshotRead`. The hook re-reads when a
|
|
4
|
+
* change batch carries a status (outbox writes and drains report one) or an
|
|
5
|
+
* outcome-journal change, so a commit moves from `pending` to `known` without
|
|
6
|
+
* polling. `unknown` means neither the outbox nor the journal holds the id:
|
|
7
|
+
* this client never wrote it, or retention pruned its outcome.
|
|
8
|
+
*/
|
|
9
|
+
import { useEffect, useState } from 'react';
|
|
10
|
+
import { useSyncClient } from './use-client.js';
|
|
11
|
+
const LOADING = {
|
|
12
|
+
deliveries: [],
|
|
13
|
+
isLoading: true,
|
|
14
|
+
error: undefined,
|
|
15
|
+
};
|
|
16
|
+
export function useCommitDelivery(ids) {
|
|
17
|
+
const client = useSyncClient();
|
|
18
|
+
const key = JSON.stringify(ids);
|
|
19
|
+
const [snapshot, setSnapshot] = useState(() => ({ client, key, result: LOADING }));
|
|
20
|
+
if (snapshot.client !== client || snapshot.key !== key) {
|
|
21
|
+
setSnapshot({ client, key, result: LOADING });
|
|
22
|
+
}
|
|
23
|
+
useEffect(() => {
|
|
24
|
+
const commitIds = JSON.parse(key);
|
|
25
|
+
let generation = 0;
|
|
26
|
+
const settle = (next) => setSnapshot((previous) => {
|
|
27
|
+
if (previous.client !== client || previous.key !== key)
|
|
28
|
+
return previous;
|
|
29
|
+
const current = previous.result;
|
|
30
|
+
// A status batch without a delivery transition keeps the snapshot.
|
|
31
|
+
// A journal entry changes only by resolution; `sequence` names it.
|
|
32
|
+
const same = !current.isLoading &&
|
|
33
|
+
current.error === next.error &&
|
|
34
|
+
current.deliveries.every((delivery, index) => {
|
|
35
|
+
const other = next.deliveries[index];
|
|
36
|
+
return delivery.status === 'known' && other.status === 'known'
|
|
37
|
+
? delivery.outcome.sequence === other.outcome.sequence &&
|
|
38
|
+
delivery.outcome.resolution === other.outcome.resolution
|
|
39
|
+
: delivery.status === other.status;
|
|
40
|
+
});
|
|
41
|
+
return same ? previous : { client, key, result: next };
|
|
42
|
+
});
|
|
43
|
+
const read = () => {
|
|
44
|
+
const request = ++generation;
|
|
45
|
+
void Promise.resolve()
|
|
46
|
+
.then(() => client.snapshotRead({ statements: [], commitIds }))
|
|
47
|
+
.then((result) => {
|
|
48
|
+
if (request === generation)
|
|
49
|
+
settle({
|
|
50
|
+
deliveries: result.deliveries,
|
|
51
|
+
isLoading: false,
|
|
52
|
+
error: undefined,
|
|
53
|
+
});
|
|
54
|
+
}, (error) => {
|
|
55
|
+
if (request === generation)
|
|
56
|
+
settle({
|
|
57
|
+
deliveries: [],
|
|
58
|
+
isLoading: false,
|
|
59
|
+
error: error instanceof Error ? error : new Error(String(error)),
|
|
60
|
+
});
|
|
61
|
+
});
|
|
62
|
+
};
|
|
63
|
+
const unsubscribe = client.onChange((batch) => {
|
|
64
|
+
if (batch.outcomesChanged || batch.status !== undefined)
|
|
65
|
+
read();
|
|
66
|
+
});
|
|
67
|
+
read();
|
|
68
|
+
return () => {
|
|
69
|
+
generation += 1;
|
|
70
|
+
unsubscribe();
|
|
71
|
+
};
|
|
72
|
+
}, [client, key]);
|
|
73
|
+
return snapshot.client === client && snapshot.key === key
|
|
74
|
+
? snapshot.result
|
|
75
|
+
: LOADING;
|
|
76
|
+
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@syncular/react",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.90.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.90.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.90.0",
|
|
66
|
+
"@syncular/server": "0.90.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/client.ts
CHANGED
|
@@ -8,12 +8,14 @@ import type {
|
|
|
8
8
|
CommitOutcome,
|
|
9
9
|
CurrentBaseProof,
|
|
10
10
|
InvalidationListener,
|
|
11
|
+
ReplaceCommitOutcomeInput,
|
|
11
12
|
LeadershipState,
|
|
12
13
|
LocalDataPurgeInput,
|
|
13
14
|
LocalDataPurgeResult,
|
|
14
15
|
LocalDataRebootstrapInput,
|
|
15
16
|
LocalDataRebootstrapResult,
|
|
16
17
|
MutationInput,
|
|
18
|
+
OutboxCommit,
|
|
17
19
|
PresencePeer,
|
|
18
20
|
QueryReadSpec,
|
|
19
21
|
QuerySnapshot,
|
|
@@ -63,11 +65,14 @@ export interface SyncClientLike extends ClientSnapshotReader {
|
|
|
63
65
|
querySnapshot<Row = SqlRow>(
|
|
64
66
|
spec: QueryReadSpec,
|
|
65
67
|
): QuerySnapshot<Row> | Promise<QuerySnapshot<Row>>;
|
|
66
|
-
pendingCommits
|
|
68
|
+
pendingCommits(): OutboxCommit[] | Promise<OutboxCommit[]>;
|
|
67
69
|
proveCurrentBase(
|
|
68
70
|
outcome: Pick<CommitOutcome, 'clientCommitId' | 'sequence'>,
|
|
69
71
|
maxRounds?: number,
|
|
70
72
|
): CurrentBaseProof | Promise<CurrentBaseProof>;
|
|
73
|
+
replaceCommitOutcome(
|
|
74
|
+
input: ReplaceCommitOutcomeInput,
|
|
75
|
+
): string | Promise<string>;
|
|
71
76
|
presence(
|
|
72
77
|
scopeKey: string,
|
|
73
78
|
): readonly PresencePeer[] | Promise<readonly PresencePeer[]>;
|
package/src/index.ts
CHANGED
|
@@ -24,6 +24,10 @@ export {
|
|
|
24
24
|
} from './resource';
|
|
25
25
|
export { SYNCULAR_REACT_RUNTIME_VERSION } from './runtime-version';
|
|
26
26
|
export { useReactiveStore, useSyncClient } from './use-client';
|
|
27
|
+
export {
|
|
28
|
+
type UseCommitDeliveryResult,
|
|
29
|
+
useCommitDelivery,
|
|
30
|
+
} from './use-commit-delivery';
|
|
27
31
|
export {
|
|
28
32
|
type UseCommitOutcomesResult,
|
|
29
33
|
useCommitOutcomes,
|
package/src/runtime-version.ts
CHANGED
|
@@ -0,0 +1,100 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `useCommitDelivery(ids)`: the §7.5 delivery status of each client commit in
|
|
3
|
+
* `ids`, in request order, from one `snapshotRead`. The hook re-reads when a
|
|
4
|
+
* change batch carries a status (outbox writes and drains report one) or an
|
|
5
|
+
* outcome-journal change, so a commit moves from `pending` to `known` without
|
|
6
|
+
* polling. `unknown` means neither the outbox nor the journal holds the id:
|
|
7
|
+
* this client never wrote it, or retention pruned its outcome.
|
|
8
|
+
*/
|
|
9
|
+
|
|
10
|
+
import type { CommitDelivery } from '@syncular/client';
|
|
11
|
+
import { useEffect, useState } from 'react';
|
|
12
|
+
import type { SyncClientLike } from './client';
|
|
13
|
+
import { useSyncClient } from './use-client';
|
|
14
|
+
|
|
15
|
+
export interface UseCommitDeliveryResult {
|
|
16
|
+
/** One entry per requested id, in request order; empty until the first read. */
|
|
17
|
+
readonly deliveries: readonly CommitDelivery[];
|
|
18
|
+
readonly isLoading: boolean;
|
|
19
|
+
readonly error: Error | undefined;
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
const LOADING: UseCommitDeliveryResult = {
|
|
23
|
+
deliveries: [],
|
|
24
|
+
isLoading: true,
|
|
25
|
+
error: undefined,
|
|
26
|
+
};
|
|
27
|
+
|
|
28
|
+
export function useCommitDelivery(
|
|
29
|
+
ids: readonly string[],
|
|
30
|
+
): UseCommitDeliveryResult {
|
|
31
|
+
const client = useSyncClient();
|
|
32
|
+
const key = JSON.stringify(ids);
|
|
33
|
+
const [snapshot, setSnapshot] = useState<{
|
|
34
|
+
client: SyncClientLike;
|
|
35
|
+
key: string;
|
|
36
|
+
result: UseCommitDeliveryResult;
|
|
37
|
+
}>(() => ({ client, key, result: LOADING }));
|
|
38
|
+
if (snapshot.client !== client || snapshot.key !== key) {
|
|
39
|
+
setSnapshot({ client, key, result: LOADING });
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
useEffect(() => {
|
|
43
|
+
const commitIds: readonly string[] = JSON.parse(key);
|
|
44
|
+
let generation = 0;
|
|
45
|
+
const settle = (next: UseCommitDeliveryResult) =>
|
|
46
|
+
setSnapshot((previous) => {
|
|
47
|
+
if (previous.client !== client || previous.key !== key) return previous;
|
|
48
|
+
const current = previous.result;
|
|
49
|
+
// A status batch without a delivery transition keeps the snapshot.
|
|
50
|
+
// A journal entry changes only by resolution; `sequence` names it.
|
|
51
|
+
const same =
|
|
52
|
+
!current.isLoading &&
|
|
53
|
+
current.error === next.error &&
|
|
54
|
+
current.deliveries.every((delivery, index) => {
|
|
55
|
+
const other = next.deliveries[index]!;
|
|
56
|
+
return delivery.status === 'known' && other.status === 'known'
|
|
57
|
+
? delivery.outcome.sequence === other.outcome.sequence &&
|
|
58
|
+
delivery.outcome.resolution === other.outcome.resolution
|
|
59
|
+
: delivery.status === other.status;
|
|
60
|
+
});
|
|
61
|
+
return same ? previous : { client, key, result: next };
|
|
62
|
+
});
|
|
63
|
+
const read = () => {
|
|
64
|
+
const request = ++generation;
|
|
65
|
+
void Promise.resolve()
|
|
66
|
+
.then(() => client.snapshotRead({ statements: [], commitIds }))
|
|
67
|
+
.then(
|
|
68
|
+
(result) => {
|
|
69
|
+
if (request === generation)
|
|
70
|
+
settle({
|
|
71
|
+
deliveries: result.deliveries,
|
|
72
|
+
isLoading: false,
|
|
73
|
+
error: undefined,
|
|
74
|
+
});
|
|
75
|
+
},
|
|
76
|
+
(error: unknown) => {
|
|
77
|
+
if (request === generation)
|
|
78
|
+
settle({
|
|
79
|
+
deliveries: [],
|
|
80
|
+
isLoading: false,
|
|
81
|
+
error:
|
|
82
|
+
error instanceof Error ? error : new Error(String(error)),
|
|
83
|
+
});
|
|
84
|
+
},
|
|
85
|
+
);
|
|
86
|
+
};
|
|
87
|
+
const unsubscribe = client.onChange((batch) => {
|
|
88
|
+
if (batch.outcomesChanged || batch.status !== undefined) read();
|
|
89
|
+
});
|
|
90
|
+
read();
|
|
91
|
+
return () => {
|
|
92
|
+
generation += 1;
|
|
93
|
+
unsubscribe();
|
|
94
|
+
};
|
|
95
|
+
}, [client, key]);
|
|
96
|
+
|
|
97
|
+
return snapshot.client === client && snapshot.key === key
|
|
98
|
+
? snapshot.result
|
|
99
|
+
: LOADING;
|
|
100
|
+
}
|