@syncular/client 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 +34 -34
- package/dist/apply.d.ts +24 -14
- package/dist/apply.js +119 -70
- package/dist/authority.js +21 -16
- package/dist/blob.d.ts +17 -9
- package/dist/blob.js +5 -6
- package/dist/bun-database.d.ts +1 -0
- package/dist/bun-database.js +15 -0
- package/dist/client.d.ts +83 -75
- package/dist/client.js +982 -910
- package/dist/database.d.ts +5 -0
- package/dist/devtools.d.ts +2 -2
- package/dist/devtools.js +3 -3
- package/dist/diagnostics.d.ts +17 -28
- package/dist/diagnostics.js +1 -2
- package/dist/encryption.d.ts +2 -2
- package/dist/encryption.js +8 -2
- package/dist/errors.d.ts +3 -1
- package/dist/errors.js +5 -1
- package/dist/failed-overlay.d.ts +0 -1
- package/dist/failed-overlay.js +6 -6
- package/dist/http.d.ts +4 -1
- package/dist/http.js +67 -39
- package/dist/index.d.ts +1 -1
- package/dist/index.js +1 -1
- package/dist/invalidation.d.ts +14 -14
- package/dist/invalidation.js +24 -48
- package/dist/local-purge.js +9 -12
- package/dist/local-rebootstrap.js +2 -2
- package/dist/multi-tab.d.ts +89 -1
- package/dist/multi-tab.js +70 -31
- package/dist/native-bridge.d.ts +226 -0
- package/dist/native-bridge.js +764 -0
- package/dist/node-database.d.ts +1 -0
- package/dist/node-database.js +21 -1
- package/dist/outbox.d.ts +9 -12
- package/dist/outbox.js +20 -36
- package/dist/outcomes.js +3 -3
- package/dist/previous-version.js +96 -114
- package/dist/progress.d.ts +2 -2
- package/dist/query-guard.d.ts +34 -24
- package/dist/query-guard.js +61 -186
- package/dist/reactive-store.js +55 -13
- package/dist/realtime-supervisor.d.ts +9 -2
- package/dist/realtime-supervisor.js +31 -7
- package/dist/remote.js +19 -23
- package/dist/schema.d.ts +3 -2
- package/dist/schema.js +43 -22
- package/dist/state.d.ts +69 -36
- package/dist/state.js +178 -89
- package/dist/sync-scheduler.js +28 -2
- package/dist/transport.d.ts +19 -4
- package/dist/wasm-database.js +58 -21
- package/dist/window.d.ts +30 -52
- package/dist/window.js +33 -77
- package/dist/worker-core.d.ts +5 -0
- package/dist/worker-core.js +83 -75
- package/dist/worker-host.d.ts +19 -13
- package/dist/worker-host.js +75 -18
- package/dist/worker-local-authority.js +2 -2
- package/dist/worker-protocol.d.ts +15 -10
- package/package.json +11 -3
- package/src/apply.ts +176 -86
- package/src/authority.ts +31 -17
- package/src/blob.ts +28 -15
- package/src/bun-database.ts +24 -0
- package/src/client.ts +1282 -1217
- package/src/database.ts +5 -0
- package/src/devtools.ts +5 -5
- package/src/diagnostics.ts +17 -37
- package/src/encryption.ts +10 -5
- package/src/errors.ts +9 -1
- package/src/failed-overlay.ts +8 -7
- package/src/http.ts +95 -79
- package/src/index.ts +1 -1
- package/src/invalidation.ts +26 -61
- package/src/local-purge.ts +11 -13
- package/src/local-rebootstrap.ts +2 -3
- package/src/multi-tab.ts +88 -30
- package/src/native-bridge.ts +1153 -0
- package/src/node-database.ts +32 -1
- package/src/outbox.ts +20 -41
- package/src/outcomes.ts +3 -5
- package/src/previous-version.ts +103 -114
- package/src/progress.ts +2 -2
- package/src/query-guard.ts +77 -177
- package/src/reactive-store.ts +52 -12
- package/src/realtime-supervisor.ts +37 -12
- package/src/remote.ts +23 -31
- package/src/schema.ts +67 -25
- package/src/state.ts +246 -125
- package/src/sync-scheduler.ts +31 -1
- package/src/transport.ts +21 -2
- package/src/wasm-database.ts +76 -27
- package/src/window.ts +55 -134
- package/src/worker-core.ts +97 -77
- package/src/worker-host.ts +76 -32
- package/src/worker-local-authority.ts +2 -5
- package/src/worker-protocol.ts +14 -10
|
@@ -0,0 +1,226 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The command bridge shared by the native hosts: `@syncular/tauri` (the Tauri
|
|
3
|
+
* plugin over IPC) and the React Native binding (the C-ABI core behind a
|
|
4
|
+
* TurboModule). Both drive one Rust core through the driver-protocol command
|
|
5
|
+
* envelope `{method, params}`, so the codec, the security preflight gate, the
|
|
6
|
+
* event fanout, and every command method live here. A host subclass supplies
|
|
7
|
+
* the transport: the generic command, the query fast path, the snapshot read,
|
|
8
|
+
* header replacement, and shutdown.
|
|
9
|
+
*
|
|
10
|
+
* Bytes cross as `{$bytes: hex}` and unsafe SQLite integers as
|
|
11
|
+
* `{$bigint: decimal}`, the convention of the Rust command router. The browser
|
|
12
|
+
* client and worker entries never import this module.
|
|
13
|
+
*/
|
|
14
|
+
import { type ClientSnapshotMethods, type CurrentBaseProof, type MutationInput, type PresencePeer, type PromiseMethods, type QueryReadSpec, type QuerySnapshot, type SecurityLifecycle, type SnapshotRead, type SnapshotReadRequest, type SyncClientConfig, type WindowState } from './client.js';
|
|
15
|
+
import type { SqlRow, SqlValue } from './database.js';
|
|
16
|
+
import type { PresenceErrorCode, UnitScopes } from '@syncular/core';
|
|
17
|
+
import { type ClientDiagnosticsListener, type ClientDiagnosticsSnapshot } from './diagnostics.js';
|
|
18
|
+
import type { EncryptionKeyringConfig } from './encryption.js';
|
|
19
|
+
import type { ClientChangeListener, InvalidationListener, SyncStatusSnapshot } from './invalidation.js';
|
|
20
|
+
import type { LocalDataPurgeInput, LocalDataPurgeResult } from './local-purge.js';
|
|
21
|
+
import { type LocalDataRebootstrapInput, type LocalDataRebootstrapResult } from './local-rebootstrap.js';
|
|
22
|
+
import type { CommitOutcome, CommitOutcomeQuery, ConflictRecord, RejectionRecord, ResolveCommitOutcomeInput } from './outcomes.js';
|
|
23
|
+
import { type PreviousVersionAudit, type PreviousVersionReadSpec, type PreviousVersionSnapshot } from './previous-version.js';
|
|
24
|
+
import { type SyncProgress, type SyncProgressListener } from './progress.js';
|
|
25
|
+
import type { WindowBase } from './window.js';
|
|
26
|
+
/** A driver-protocol reply: `{result}` on success or `{error}` on failure. */
|
|
27
|
+
export interface NativeReply {
|
|
28
|
+
readonly result?: unknown;
|
|
29
|
+
readonly error?: {
|
|
30
|
+
readonly code: string;
|
|
31
|
+
readonly message: string;
|
|
32
|
+
readonly details?: Readonly<Record<string, unknown>> | null;
|
|
33
|
+
readonly retryable?: boolean;
|
|
34
|
+
};
|
|
35
|
+
}
|
|
36
|
+
/** One event the native core pushes (the derived client-observable set). */
|
|
37
|
+
export interface SyncularEvent {
|
|
38
|
+
readonly type: string;
|
|
39
|
+
readonly [key: string]: unknown;
|
|
40
|
+
}
|
|
41
|
+
/** The bytes envelope both sides share. */
|
|
42
|
+
export type BytesEnvelope = {
|
|
43
|
+
readonly $bytes: string;
|
|
44
|
+
};
|
|
45
|
+
/** The `create` options every native host forwards to the Rust core. */
|
|
46
|
+
export interface NativeCreateConfig {
|
|
47
|
+
/** The generated schema JSON (the app passes `schema` from typegen). */
|
|
48
|
+
readonly schema: unknown;
|
|
49
|
+
/**
|
|
50
|
+
* Client id for this device or actor. If omitted, the native core generates
|
|
51
|
+
* one and persists it in the database. Supplying a different id when opening
|
|
52
|
+
* an existing database fails with `client.identity_mismatch`.
|
|
53
|
+
*/
|
|
54
|
+
readonly clientId?: string;
|
|
55
|
+
/** §4.2 client limits. */
|
|
56
|
+
readonly limits?: Record<string, unknown>;
|
|
57
|
+
/**
|
|
58
|
+
* SPEC §8.8 realtime policy. Absent ⇒ `optional`. `required` refuses a sync
|
|
59
|
+
* round while the socket is not connected instead of falling back to HTTP.
|
|
60
|
+
*/
|
|
61
|
+
readonly realtimePolicy?: SyncClientConfig['realtimePolicy'];
|
|
62
|
+
/**
|
|
63
|
+
* Portable E2EE keys and declarative per-row key-id columns, installed in
|
|
64
|
+
* the Rust core. Raw keys are never sent to the server.
|
|
65
|
+
*/
|
|
66
|
+
readonly encryption?: EncryptionKeyringConfig;
|
|
67
|
+
/** Open the native replica behind the fail-closed security gate. */
|
|
68
|
+
readonly securityPreflight?: boolean;
|
|
69
|
+
/** RFC 0005 previous-version context (default off). */
|
|
70
|
+
readonly previousVersionContext?: SyncClientConfig['previousVersionContext'];
|
|
71
|
+
}
|
|
72
|
+
/** The error a native `{error}` reply surfaces (mirrors `ClientSyncError`). */
|
|
73
|
+
export declare class NativeSyncError extends Error {
|
|
74
|
+
readonly code: string;
|
|
75
|
+
readonly details: Readonly<Record<string, unknown>> | undefined;
|
|
76
|
+
readonly retryable: boolean;
|
|
77
|
+
constructor(code: string, message: string, details?: Readonly<Record<string, unknown>>, retryable?: boolean);
|
|
78
|
+
}
|
|
79
|
+
/**
|
|
80
|
+
* The `create` params every native host sends. Keys cannot be installed
|
|
81
|
+
* before a security preflight; that combination fails before the host is
|
|
82
|
+
* touched.
|
|
83
|
+
*/
|
|
84
|
+
export declare function nativeCreateParams(config: NativeCreateConfig, ErrorType: typeof NativeSyncError): Record<string, unknown>;
|
|
85
|
+
/**
|
|
86
|
+
* The `SyncClientLike` proxy over a native core. Every snapshot method
|
|
87
|
+
* returns a promise from one host round trip; React hooks accept the
|
|
88
|
+
* canonical snapshot interface directly.
|
|
89
|
+
*/
|
|
90
|
+
export declare abstract class NativeBridgeClient implements PromiseMethods<ClientSnapshotMethods> {
|
|
91
|
+
#private;
|
|
92
|
+
/**
|
|
93
|
+
* `release` detaches the host event listener; the bridge calls it once,
|
|
94
|
+
* after shutdown or after a failed `create`.
|
|
95
|
+
*/
|
|
96
|
+
constructor(kind: 'tauri' | 'react-native', ErrorType: typeof NativeSyncError, release: () => void, securityLifecycle: SecurityLifecycle);
|
|
97
|
+
/** Run one `{method, params}` command on the native core. */
|
|
98
|
+
protected abstract send(method: string, params: Record<string, unknown>): Promise<NativeReply>;
|
|
99
|
+
/** The read-only SQL fast path; `params` are already envelope-encoded. */
|
|
100
|
+
protected abstract sendQuery(sql: string, params: unknown): Promise<NativeReply>;
|
|
101
|
+
/** The atomic `querySnapshot` read. */
|
|
102
|
+
protected abstract sendQuerySnapshot(params: Record<string, unknown>): Promise<NativeReply>;
|
|
103
|
+
/** Replace the native transport's full header set. */
|
|
104
|
+
protected abstract sendHeaders(headers: Readonly<Record<string, string>>): Promise<NativeReply>;
|
|
105
|
+
/** Stop the native core. `close()` detaches listeners once it settles. */
|
|
106
|
+
protected abstract shutdown(): Promise<void>;
|
|
107
|
+
/** @internal Settle the native `create`; a failure detaches the listener. */
|
|
108
|
+
__open(create: () => Promise<NativeReply>): Promise<void>;
|
|
109
|
+
/** Dispatch a command through the closed check and the preflight gate. */
|
|
110
|
+
protected command(method: string, params: Record<string, unknown>): Promise<unknown>;
|
|
111
|
+
/** Additional preflight operations a host subclass permits. */
|
|
112
|
+
protected allowPreflightCommand(_method: string): boolean;
|
|
113
|
+
protected get closed(): boolean;
|
|
114
|
+
protected get preflight(): boolean;
|
|
115
|
+
protected requireOpen(): void;
|
|
116
|
+
/** Decode a native row. Reserved `_sync_*` columns stay engine-internal,
|
|
117
|
+
* so a `SELECT *` row round-trips into `mutate()` values. */
|
|
118
|
+
protected decodeRow(row: Readonly<Record<string, unknown>>): SqlRow;
|
|
119
|
+
/** @internal Fan an incoming native event out to the local listeners. */
|
|
120
|
+
__dispatchEvent(event: SyncularEvent): void;
|
|
121
|
+
securityLifecycle(): Promise<SecurityLifecycle>;
|
|
122
|
+
beginSecurityPreflight(): Promise<void>;
|
|
123
|
+
/**
|
|
124
|
+
* Complete the security preflight. `headers` optionally carries a fresh
|
|
125
|
+
* FULL transport header set that the native host applies atomically with
|
|
126
|
+
* the activation, before the startup sync it enqueues, so a preflight that
|
|
127
|
+
* outlives the boot token starts its first round with valid credentials
|
|
128
|
+
* (the direct `setHeaders` path stays refused while gated).
|
|
129
|
+
*/
|
|
130
|
+
activateSecurity(options?: {
|
|
131
|
+
readonly encryption?: EncryptionKeyringConfig;
|
|
132
|
+
readonly headers?: Readonly<Record<string, string>>;
|
|
133
|
+
}): Promise<void>;
|
|
134
|
+
onInvalidate(listener: InvalidationListener): () => void;
|
|
135
|
+
onProgress(listener: SyncProgressListener): () => void;
|
|
136
|
+
progressSnapshot(): SyncProgress | undefined;
|
|
137
|
+
onChange(listener: ClientChangeListener): () => void;
|
|
138
|
+
onDiagnostics(listener: ClientDiagnosticsListener): () => void;
|
|
139
|
+
onPresence(listener: (scopeKey: string, error?: PresenceErrorCode) => void): () => void;
|
|
140
|
+
query(sql: string, params?: readonly SqlValue[]): Promise<SqlRow[]>;
|
|
141
|
+
querySnapshot<Row = SqlRow>(spec: QueryReadSpec): Promise<QuerySnapshot<Row>>;
|
|
142
|
+
/**
|
|
143
|
+
* §7.5: one atomic read. Every statement and every catch-up and delivery
|
|
144
|
+
* read shares one revision and one read transaction.
|
|
145
|
+
*/
|
|
146
|
+
snapshotRead(request: SnapshotReadRequest): Promise<SnapshotRead>;
|
|
147
|
+
localRevision(): Promise<bigint>;
|
|
148
|
+
statusSnapshot(): Promise<SyncStatusSnapshot>;
|
|
149
|
+
diagnosticsSnapshot(): Promise<ClientDiagnosticsSnapshot>;
|
|
150
|
+
mutate(mutations: readonly MutationInput[]): Promise<string>;
|
|
151
|
+
patch(table: string, rowId: string, partial: Readonly<Record<string, unknown>>, options?: {
|
|
152
|
+
readonly baseVersion?: number;
|
|
153
|
+
}): Promise<string>;
|
|
154
|
+
purgeLocalData(input: LocalDataPurgeInput): Promise<LocalDataPurgeResult>;
|
|
155
|
+
rebootstrapLocalData(input: LocalDataRebootstrapInput): Promise<LocalDataRebootstrapResult>;
|
|
156
|
+
previousVersionSnapshot(spec: PreviousVersionReadSpec): Promise<PreviousVersionSnapshot>;
|
|
157
|
+
previousVersionAudit(): Promise<PreviousVersionAudit | undefined>;
|
|
158
|
+
previousVersionDiscard(): Promise<{
|
|
159
|
+
present: boolean;
|
|
160
|
+
discarded: boolean;
|
|
161
|
+
}>;
|
|
162
|
+
/**
|
|
163
|
+
* Replace the native transport's request headers at runtime, the auth
|
|
164
|
+
* rotation path. Pass the FULL header set: it replaces the current set.
|
|
165
|
+
* HTTP requests use the new set from the next call; the realtime socket
|
|
166
|
+
* applies it on its next (re)connect.
|
|
167
|
+
*/
|
|
168
|
+
setHeaders(headers: Readonly<Record<string, string>>): Promise<void>;
|
|
169
|
+
/** Materialize a `crdt` column's collaborative text from the stored
|
|
170
|
+
* (server-merged) Yjs bytes. `name` selects the shared text (default
|
|
171
|
+
* `"text"`). An absent row or NULL column is the empty document. */
|
|
172
|
+
crdtText(table: string, rowId: string, column: string, name?: string): Promise<string>;
|
|
173
|
+
/** Insert `value` at UTF-16 offset `index` in a `crdt` column's text and
|
|
174
|
+
* push the resulting Yjs update (baseVersion-less). Returns the commit id. */
|
|
175
|
+
crdtInsertText(table: string, rowId: string, column: string, index: number, value: string, name?: string): Promise<string>;
|
|
176
|
+
/** Delete `len` UTF-16 code units at `index` in a `crdt` column's text. */
|
|
177
|
+
crdtDeleteText(table: string, rowId: string, column: string, index: number, len: number, name?: string): Promise<string>;
|
|
178
|
+
/** Apply an arbitrary Yjs update onto a `crdt` column. */
|
|
179
|
+
crdtApplyUpdate(table: string, rowId: string, column: string, update: Uint8Array): Promise<string>;
|
|
180
|
+
/**
|
|
181
|
+
* Stage a blob for attachment (§5.9.7) and return the canonical `BlobRef`
|
|
182
|
+
* string to store in a `blob_ref` column. The native core owns the upload
|
|
183
|
+
* queue; write the referencing row after this resolves (§5.9.3).
|
|
184
|
+
*/
|
|
185
|
+
uploadBlob(bytes: Uint8Array, options?: {
|
|
186
|
+
readonly mediaType?: string;
|
|
187
|
+
readonly name?: string;
|
|
188
|
+
}): Promise<string>;
|
|
189
|
+
/**
|
|
190
|
+
* Resolve blob bytes for a `blob_ref` column value or a bare `blobId`
|
|
191
|
+
* (§5.9.7): the native core serves a local cache hit and otherwise
|
|
192
|
+
* downloads and verifies the content address.
|
|
193
|
+
*/
|
|
194
|
+
fetchBlob(ref: string): Promise<{
|
|
195
|
+
readonly blobId: string;
|
|
196
|
+
readonly byteLength: number;
|
|
197
|
+
readonly bytes: Uint8Array;
|
|
198
|
+
readonly mediaType?: string;
|
|
199
|
+
}>;
|
|
200
|
+
/** §4.1: register one unit; returns its id. */
|
|
201
|
+
subscribe(scopes: UnitScopes): Promise<string>;
|
|
202
|
+
/** Register several units in one local transaction; returns their ids. */
|
|
203
|
+
subscribeMany(units: readonly UnitScopes[]): Promise<string[]>;
|
|
204
|
+
unsubscribe(id: string): Promise<void>;
|
|
205
|
+
setWindow(base: WindowBase, units: readonly string[]): Promise<void>;
|
|
206
|
+
windowState(base: WindowBase): Promise<WindowState>;
|
|
207
|
+
sync(): Promise<unknown>;
|
|
208
|
+
syncUntilIdle(maxRounds?: number, timeoutMs?: number): Promise<unknown>;
|
|
209
|
+
proveCurrentBase(outcome: Pick<CommitOutcome, 'clientCommitId' | 'sequence'>, maxRounds?: number): Promise<CurrentBaseProof>;
|
|
210
|
+
conflicts(): Promise<readonly ConflictRecord[]>;
|
|
211
|
+
rejections(): Promise<readonly RejectionRecord[]>;
|
|
212
|
+
commitOutcome(clientCommitId: string): Promise<CommitOutcome | undefined>;
|
|
213
|
+
commitOutcomes(query?: CommitOutcomeQuery): Promise<readonly CommitOutcome[]>;
|
|
214
|
+
resolveCommitOutcome(input: ResolveCommitOutcomeInput): Promise<CommitOutcome>;
|
|
215
|
+
pendingCommits(): Promise<unknown[]>;
|
|
216
|
+
presence(scopeKey: string): Promise<readonly PresencePeer[]>;
|
|
217
|
+
setPresence(scopeKey: string, doc: Record<string, unknown> | null): Promise<void>;
|
|
218
|
+
connectRealtime(): Promise<void>;
|
|
219
|
+
disconnectRealtime(): Promise<void>;
|
|
220
|
+
/**
|
|
221
|
+
* Shut down the native core, then detach listeners. Every call returns the
|
|
222
|
+
* same promise, so a concurrent or repeated close settles only when the one
|
|
223
|
+
* native shutdown settles, with its outcome.
|
|
224
|
+
*/
|
|
225
|
+
close(): Promise<void>;
|
|
226
|
+
}
|