@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.
Files changed (99) hide show
  1. package/README.md +34 -34
  2. package/dist/apply.d.ts +24 -14
  3. package/dist/apply.js +119 -70
  4. package/dist/authority.js +21 -16
  5. package/dist/blob.d.ts +17 -9
  6. package/dist/blob.js +5 -6
  7. package/dist/bun-database.d.ts +1 -0
  8. package/dist/bun-database.js +15 -0
  9. package/dist/client.d.ts +83 -75
  10. package/dist/client.js +982 -910
  11. package/dist/database.d.ts +5 -0
  12. package/dist/devtools.d.ts +2 -2
  13. package/dist/devtools.js +3 -3
  14. package/dist/diagnostics.d.ts +17 -28
  15. package/dist/diagnostics.js +1 -2
  16. package/dist/encryption.d.ts +2 -2
  17. package/dist/encryption.js +8 -2
  18. package/dist/errors.d.ts +3 -1
  19. package/dist/errors.js +5 -1
  20. package/dist/failed-overlay.d.ts +0 -1
  21. package/dist/failed-overlay.js +6 -6
  22. package/dist/http.d.ts +4 -1
  23. package/dist/http.js +67 -39
  24. package/dist/index.d.ts +1 -1
  25. package/dist/index.js +1 -1
  26. package/dist/invalidation.d.ts +14 -14
  27. package/dist/invalidation.js +24 -48
  28. package/dist/local-purge.js +9 -12
  29. package/dist/local-rebootstrap.js +2 -2
  30. package/dist/multi-tab.d.ts +89 -1
  31. package/dist/multi-tab.js +70 -31
  32. package/dist/native-bridge.d.ts +226 -0
  33. package/dist/native-bridge.js +764 -0
  34. package/dist/node-database.d.ts +1 -0
  35. package/dist/node-database.js +21 -1
  36. package/dist/outbox.d.ts +9 -12
  37. package/dist/outbox.js +20 -36
  38. package/dist/outcomes.js +3 -3
  39. package/dist/previous-version.js +96 -114
  40. package/dist/progress.d.ts +2 -2
  41. package/dist/query-guard.d.ts +34 -24
  42. package/dist/query-guard.js +61 -186
  43. package/dist/reactive-store.js +55 -13
  44. package/dist/realtime-supervisor.d.ts +9 -2
  45. package/dist/realtime-supervisor.js +31 -7
  46. package/dist/remote.js +19 -23
  47. package/dist/schema.d.ts +3 -2
  48. package/dist/schema.js +43 -22
  49. package/dist/state.d.ts +69 -36
  50. package/dist/state.js +178 -89
  51. package/dist/sync-scheduler.js +28 -2
  52. package/dist/transport.d.ts +19 -4
  53. package/dist/wasm-database.js +58 -21
  54. package/dist/window.d.ts +30 -52
  55. package/dist/window.js +33 -77
  56. package/dist/worker-core.d.ts +5 -0
  57. package/dist/worker-core.js +83 -75
  58. package/dist/worker-host.d.ts +19 -13
  59. package/dist/worker-host.js +75 -18
  60. package/dist/worker-local-authority.js +2 -2
  61. package/dist/worker-protocol.d.ts +15 -10
  62. package/package.json +11 -3
  63. package/src/apply.ts +176 -86
  64. package/src/authority.ts +31 -17
  65. package/src/blob.ts +28 -15
  66. package/src/bun-database.ts +24 -0
  67. package/src/client.ts +1282 -1217
  68. package/src/database.ts +5 -0
  69. package/src/devtools.ts +5 -5
  70. package/src/diagnostics.ts +17 -37
  71. package/src/encryption.ts +10 -5
  72. package/src/errors.ts +9 -1
  73. package/src/failed-overlay.ts +8 -7
  74. package/src/http.ts +95 -79
  75. package/src/index.ts +1 -1
  76. package/src/invalidation.ts +26 -61
  77. package/src/local-purge.ts +11 -13
  78. package/src/local-rebootstrap.ts +2 -3
  79. package/src/multi-tab.ts +88 -30
  80. package/src/native-bridge.ts +1153 -0
  81. package/src/node-database.ts +32 -1
  82. package/src/outbox.ts +20 -41
  83. package/src/outcomes.ts +3 -5
  84. package/src/previous-version.ts +103 -114
  85. package/src/progress.ts +2 -2
  86. package/src/query-guard.ts +77 -177
  87. package/src/reactive-store.ts +52 -12
  88. package/src/realtime-supervisor.ts +37 -12
  89. package/src/remote.ts +23 -31
  90. package/src/schema.ts +67 -25
  91. package/src/state.ts +246 -125
  92. package/src/sync-scheduler.ts +31 -1
  93. package/src/transport.ts +21 -2
  94. package/src/wasm-database.ts +76 -27
  95. package/src/window.ts +55 -134
  96. package/src/worker-core.ts +97 -77
  97. package/src/worker-host.ts +76 -32
  98. package/src/worker-local-authority.ts +2 -5
  99. 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
+ }