@syncular/tauri 0.53.0 → 0.54.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 +6 -0
- package/dist/index.d.ts +8 -272
- package/dist/index.js +15 -962
- package/dist/remote.d.ts +266 -0
- package/dist/remote.js +953 -0
- package/package.json +12 -4
- package/src/index.ts +18 -1451
- package/src/remote.ts +1462 -0
package/README.md
CHANGED
|
@@ -20,6 +20,12 @@ import { schema } from './syncular.generated';
|
|
|
20
20
|
export const client = await createTauriSyncClient({ schema });
|
|
21
21
|
```
|
|
22
22
|
|
|
23
|
+
Use `@syncular/tauri/remote` for a client that only connects to a remote
|
|
24
|
+
authority, and leave the native plugin's `local_authority_path` unset. This
|
|
25
|
+
entry omits the JavaScript local-authority lifecycle methods while retaining
|
|
26
|
+
the other client APIs. It does not change the code compiled into the native
|
|
27
|
+
plugin. The default `@syncular/tauri` entry retains those lifecycle methods.
|
|
28
|
+
|
|
23
29
|
Register the native plugin as described in the
|
|
24
30
|
[Tauri guide](https://syncular.dev/platform-tauri/). React apps can separately
|
|
25
31
|
install `@syncular/react` for hooks over the same client.
|
package/dist/index.d.ts
CHANGED
|
@@ -1,279 +1,15 @@
|
|
|
1
|
-
import { type
|
|
2
|
-
|
|
3
|
-
/**
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
* The Tauri host runs a REAL Rust syncular client (file DB + native HTTP+WS
|
|
8
|
-
* transport). This module is a thin webview-side proxy that implements the SAME
|
|
9
|
-
* `SyncClientLike` interface the React package normalizes — so the hooks
|
|
10
|
-
* (`useRawSql`, `useMutation`, `usePresence`, …) work UNCHANGED against a
|
|
11
|
-
* Tauri app. It is the fourth host of one interface, after the direct
|
|
12
|
-
* `SyncClient`, the worker-leader `SyncClientHandle`, and the multi-tab
|
|
13
|
-
* follower.
|
|
14
|
-
*
|
|
15
|
-
* Every method forwards to the plugin's `syncular_command` command (the whole
|
|
16
|
-
* command surface in one JSON envelope — `{method, params}`), mirroring the FFI
|
|
17
|
-
* and the conformance shim. `query` uses the dedicated `syncular_query` fast
|
|
18
|
-
* path; atomic reactive reads use `syncular_query_snapshot`, backed by an
|
|
19
|
-
* independent read-only SQLite connection so network sync cannot stall local
|
|
20
|
-
* UI reads. Client-observable
|
|
21
|
-
* events (`change` / `presence`) arrive on
|
|
22
|
-
* the `syncular://event` Tauri event and fan out to the registered listeners.
|
|
23
|
-
*
|
|
24
|
-
* Bytes cross the command JSON as the established `{$bytes: hex}` envelope, the
|
|
25
|
-
* same convention the Rust command router and the driver protocol use.
|
|
26
|
-
*
|
|
27
|
-
* `@tauri-apps/api` is a required peer dependency: the bridge takes
|
|
28
|
-
* `invoke`/`listen` either from its ESM entry points, from the ambient
|
|
29
|
-
* `window.__TAURI__`, or via injected doubles (tests).
|
|
30
|
-
*/
|
|
31
|
-
import type { AuthorityReadPolicy, ClientChangeListener, ClientDiagnosticsListener, ClientDiagnosticsRequest, ClientDiagnosticsSnapshot, CommitOutcome, CommitOutcomeQuery, CurrentBaseProof, ConflictRecord, EncryptionKeyringConfig, InvalidationListener, LocalDataPurgeInput, LocalDataPurgeResult, LocalDataRebootstrapInput, LocalDataRebootstrapResult, MutationInput, PresencePeer, PreviousVersionAudit, PreviousVersionReadSpec, PreviousVersionSnapshot, QueryReadSpec, QuerySnapshot, RejectionRecord, ResolveCommitOutcomeInput, SecurityLifecycle, SnapshotRead, SnapshotReadRequest, SqlRow, SqlValue, SyncClientConfig, SyncStatusSnapshot, WindowBase, WindowState } from '@syncular/client';
|
|
32
|
-
/** One event pushed on `syncular://event` (the derived client-observable set). */
|
|
33
|
-
interface SyncularEvent {
|
|
34
|
-
readonly type: string;
|
|
35
|
-
readonly [key: string]: unknown;
|
|
36
|
-
}
|
|
37
|
-
/** §7.5: one read-only statement in an atomic sidecar snapshot read. */
|
|
38
|
-
export type { SnapshotStatement } from '@syncular/client';
|
|
39
|
-
/** §7.5: the catch-up state of one subscription from the sidecar. */
|
|
40
|
-
export type { SubscriptionCatchup } from '@syncular/client';
|
|
41
|
-
/** §7.5: delivery status for one client commit id. */
|
|
42
|
-
export type { CommitDelivery } from '@syncular/client';
|
|
43
|
-
/** §7.5: one atomic sidecar snapshot read result with decoded rows. */
|
|
44
|
-
export type SnapshotReadResult = SnapshotRead;
|
|
45
|
-
/** The two Tauri primitives the bridge needs — injectable for tests. */
|
|
46
|
-
export interface TauriApi {
|
|
47
|
-
invoke<T>(cmd: string, args?: Record<string, unknown>): Promise<T>;
|
|
48
|
-
listen<T>(event: string, handler: (event: {
|
|
49
|
-
payload: T;
|
|
50
|
-
}) => void): Promise<() => void>;
|
|
51
|
-
}
|
|
52
|
-
/** The plugin's Tauri event name — mirror of `tauri-plugin-syncular`. */
|
|
53
|
-
export declare const SYNCULAR_EVENT = "syncular://event";
|
|
54
|
-
/** SPEC §12 local authority lifecycle state. */
|
|
55
|
-
export type LocalAuthorityState = 'local' | 'attaching' | 'attached';
|
|
56
|
-
/** Config for {@link createTauriSyncClient}. */
|
|
57
|
-
export interface TauriSyncClientConfig {
|
|
58
|
-
/** The generated schema JSON (the app passes `schema` from typegen). */
|
|
59
|
-
readonly schema: unknown;
|
|
60
|
-
/**
|
|
61
|
-
* Client id for this device/actor. If omitted, the native client generates
|
|
62
|
-
* one and persists it in the database. Supplying a different id when opening
|
|
63
|
-
* an existing database fails with `client.identity_mismatch`.
|
|
64
|
-
*/
|
|
65
|
-
readonly clientId?: string;
|
|
66
|
-
/**
|
|
67
|
-
* Name of the native database to open, for example one replica per
|
|
68
|
-
* signed-in actor. The plugin opens `<database_dir>/<database>.db` from its
|
|
69
|
-
* `SyncularConfig`; a name is 1 to 128 ASCII letters, digits, `-`, `_` or
|
|
70
|
-
* `.` and starts with a letter or digit. Absent ⇒ the plugin's `db_path`.
|
|
71
|
-
*/
|
|
72
|
-
readonly database?: string;
|
|
73
|
-
/** §4.2 client limits, forwarded to the native `create`. */
|
|
74
|
-
readonly limits?: Record<string, unknown>;
|
|
75
|
-
/**
|
|
76
|
-
* SPEC §8.8 realtime policy, forwarded to the native `create`. Absent ⇒
|
|
77
|
-
* `optional`. `required` refuses a sync round while the socket is not
|
|
78
|
-
* connected instead of falling back to HTTP.
|
|
79
|
-
*/
|
|
80
|
-
readonly realtimePolicy?: SyncClientConfig['realtimePolicy'];
|
|
81
|
-
readonly retainFailedCommits?: boolean;
|
|
82
|
-
/**
|
|
83
|
-
* Portable E2EE keys and declarative per-row key-id columns. Raw keys are
|
|
84
|
-
* encoded into the native command envelope and never sent to the server.
|
|
85
|
-
*/
|
|
86
|
-
readonly encryption?: EncryptionKeyringConfig;
|
|
87
|
-
/** Fixed plain authority reads permitted before security activation. */
|
|
88
|
-
readonly authorityReads?: AuthorityReadPolicy;
|
|
89
|
-
/** Open the native replica behind the fail-closed security gate. */
|
|
90
|
-
readonly securityPreflight?: boolean;
|
|
91
|
-
/** Open local storage with network transport closed until explicitly resumed. */
|
|
92
|
-
readonly transportEnabled?: boolean;
|
|
93
|
-
/**
|
|
94
|
-
* RFC 0005 previous-version context, forwarded to the native `create`. The
|
|
95
|
-
* Rust create handler must read this key to enable capture; while it does
|
|
96
|
-
* not, the native core treats the feature as off (default-off).
|
|
97
|
-
*/
|
|
98
|
-
readonly previousVersionContext?: SyncClientConfig['previousVersionContext'];
|
|
99
|
-
/**
|
|
100
|
-
* The Tauri primitives. Omit in a real Tauri webview to auto-resolve from
|
|
101
|
-
* `@tauri-apps/api` (peer dep) or the ambient `window.__TAURI__`; inject in
|
|
102
|
-
* tests. Resolution is async, so construction is a factory (below).
|
|
103
|
-
*/
|
|
104
|
-
readonly tauri?: TauriApi;
|
|
105
|
-
}
|
|
106
|
-
/** The bytes envelope both sides share. */
|
|
107
|
-
export type BytesEnvelope = {
|
|
108
|
-
readonly $bytes: string;
|
|
109
|
-
};
|
|
110
|
-
/** @internal Shared native row codec. */
|
|
111
|
-
export declare function decodeRow(row: Record<string, unknown>): SqlRow;
|
|
112
|
-
/**
|
|
113
|
-
* The webview-side proxy implementing `SyncClientLike` over the plugin. Every
|
|
114
|
-
* snapshot method returns a promise from an IPC round trip. React hooks accept
|
|
115
|
-
* the canonical snapshot interface directly.
|
|
116
|
-
*/
|
|
117
|
-
export declare class TauriSyncClient implements PromiseMethods<ClientSnapshotMethods> {
|
|
118
|
-
#private;
|
|
119
|
-
/** @internal — use {@link createTauriSyncClient}. */
|
|
120
|
-
constructor(tauri: TauriApi, unlisten: () => void, securityLifecycle?: SecurityLifecycle);
|
|
121
|
-
/** @internal Shared command gate for explicit bridge extensions. */
|
|
122
|
-
protected command(method: string, params: Record<string, unknown>): Promise<unknown>;
|
|
123
|
-
/** @internal Recheck local close after an extension's asynchronous reply. */
|
|
124
|
-
protected requireOpen(): void;
|
|
125
|
-
/** @internal — fan an incoming plugin event out to the local listeners. */
|
|
126
|
-
__dispatchEvent(event: SyncularEvent): void;
|
|
127
|
-
securityLifecycle(): Promise<SecurityLifecycle>;
|
|
128
|
-
beginSecurityPreflight(): Promise<void>;
|
|
129
|
-
/**
|
|
130
|
-
* Complete the security preflight. `headers` optionally carries a fresh
|
|
131
|
-
* FULL transport header set that the native host applies atomically with
|
|
132
|
-
* the activation, before the startup sync it enqueues — so a preflight
|
|
133
|
-
* that outlives the boot token starts its first round with valid
|
|
134
|
-
* credentials (the direct `setHeaders` path stays refused while gated).
|
|
135
|
-
*/
|
|
136
|
-
activateSecurity(options?: {
|
|
137
|
-
readonly encryption?: EncryptionKeyringConfig;
|
|
138
|
-
readonly headers?: Readonly<Record<string, string>>;
|
|
139
|
-
}): Promise<void>;
|
|
140
|
-
onInvalidate(listener: InvalidationListener): () => void;
|
|
141
|
-
onProgress(listener: SyncProgressListener): () => void;
|
|
142
|
-
progressSnapshot(): SyncProgress | undefined;
|
|
143
|
-
onChange(listener: ClientChangeListener): () => void;
|
|
144
|
-
onDiagnostics(listener: ClientDiagnosticsListener): () => void;
|
|
145
|
-
onPresence(listener: (scopeKey: string) => void): () => void;
|
|
146
|
-
query(sql: string, params?: readonly SqlValue[]): Promise<SqlRow[]>;
|
|
147
|
-
querySnapshot<Row = SqlRow>(spec: QueryReadSpec): Promise<QuerySnapshot<Row>>;
|
|
148
|
-
localRevision(): Promise<bigint>;
|
|
149
|
-
/**
|
|
150
|
-
* §7.5: one atomic read over the file-backed sidecar. Every statement and
|
|
151
|
-
* every catch-up/delivery read shares one revision (a `bigint`, matching
|
|
152
|
-
* `querySnapshot`) and one read transaction; every query row is decoded.
|
|
153
|
-
*/
|
|
154
|
-
snapshotRead(request: SnapshotReadRequest): Promise<SnapshotRead>;
|
|
155
|
-
statusSnapshot(): Promise<SyncStatusSnapshot>;
|
|
156
|
-
diagnosticsSnapshot(request?: ClientDiagnosticsRequest): Promise<ClientDiagnosticsSnapshot>;
|
|
157
|
-
mutate(mutations: readonly MutationInput[]): Promise<string>;
|
|
158
|
-
patch(table: string, rowId: string, partial: Readonly<Record<string, unknown>>, options?: {
|
|
159
|
-
readonly baseVersion?: number;
|
|
160
|
-
}): Promise<string>;
|
|
161
|
-
purgeLocalData(input: LocalDataPurgeInput): Promise<LocalDataPurgeResult>;
|
|
162
|
-
rebootstrapLocalData(input: LocalDataRebootstrapInput): Promise<LocalDataRebootstrapResult>;
|
|
163
|
-
previousVersionSnapshot(spec: PreviousVersionReadSpec): Promise<PreviousVersionSnapshot>;
|
|
164
|
-
previousVersionAudit(): Promise<PreviousVersionAudit | undefined>;
|
|
165
|
-
previousVersionDiscard(): Promise<{
|
|
166
|
-
present: boolean;
|
|
167
|
-
discarded: boolean;
|
|
168
|
-
}>;
|
|
169
|
-
/** Suspend new network work while retaining local access and queued commits. */
|
|
170
|
-
setTransportEnabled(enabled: boolean): Promise<void>;
|
|
171
|
-
/** Browser offline-control parity; local reads and commits remain available. */
|
|
172
|
-
setOffline(offline: boolean): Promise<void>;
|
|
173
|
-
/**
|
|
174
|
-
* Replace the native transport's request headers at runtime — the auth
|
|
175
|
-
* rotation path. Pass the FULL header set (it replaces,
|
|
176
|
-
* it does not merge). HTTP requests use the new set from the next call;
|
|
177
|
-
* the realtime socket applies it on its next (re)connect.
|
|
178
|
-
*/
|
|
179
|
-
setHeaders(headers: Readonly<Record<string, string>>): Promise<void>;
|
|
180
|
-
/** Materialize a `crdt` column's collaborative text — decoded from the
|
|
181
|
-
* stored (server-merged) Yjs bytes. `name` selects the shared text
|
|
182
|
-
* (default `"text"`). An absent row / NULL column is the empty document. */
|
|
183
|
-
crdtText(table: string, rowId: string, column: string, name?: string): Promise<string>;
|
|
184
|
-
/** Insert `value` at UTF-16 offset `index` in a `crdt` column's text and
|
|
185
|
-
* push the resulting Yjs update (baseVersion-less). Returns the commit id. */
|
|
186
|
-
crdtInsertText(table: string, rowId: string, column: string, index: number, value: string, name?: string): Promise<string>;
|
|
187
|
-
/** Delete `len` UTF-16 code units at `index` in a `crdt` column's text. */
|
|
188
|
-
crdtDeleteText(table: string, rowId: string, column: string, index: number, len: number, name?: string): Promise<string>;
|
|
189
|
-
/** Escape hatch: apply an arbitrary Yjs update onto a `crdt` column. */
|
|
190
|
-
crdtApplyUpdate(table: string, rowId: string, column: string, update: Uint8Array): Promise<string>;
|
|
191
|
-
/**
|
|
192
|
-
* Stage a blob for attachment (§5.9.7) and return the canonical `BlobRef`
|
|
193
|
-
* string to store in a `blob_ref` column. The native core owns the upload
|
|
194
|
-
* queue; write the referencing row after this resolves (§5.9.3).
|
|
195
|
-
*/
|
|
196
|
-
uploadBlob(bytes: Uint8Array, options?: {
|
|
197
|
-
readonly mediaType?: string;
|
|
198
|
-
readonly name?: string;
|
|
199
|
-
}): Promise<string>;
|
|
200
|
-
/**
|
|
201
|
-
* Resolve blob bytes for a `blob_ref` column value or a bare `blobId`
|
|
202
|
-
* (§5.9.7): the native core serves a local cache hit and otherwise
|
|
203
|
-
* downloads and verifies the content address.
|
|
204
|
-
*/
|
|
205
|
-
fetchBlob(ref: string): Promise<{
|
|
206
|
-
readonly blobId: string;
|
|
207
|
-
readonly byteLength: number;
|
|
208
|
-
readonly bytes: Uint8Array;
|
|
209
|
-
readonly mediaType?: string;
|
|
210
|
-
}>;
|
|
211
|
-
subscribe(input: {
|
|
212
|
-
readonly id: string;
|
|
213
|
-
readonly table: string;
|
|
214
|
-
readonly scopes?: Record<string, readonly string[]>;
|
|
215
|
-
readonly params?: string;
|
|
216
|
-
}): Promise<void>;
|
|
217
|
-
/** Register several subscriptions in one local transaction. */
|
|
218
|
-
subscribeMany(inputs: readonly {
|
|
219
|
-
readonly id: string;
|
|
220
|
-
readonly table: string;
|
|
221
|
-
readonly scopes?: Record<string, readonly string[]>;
|
|
222
|
-
readonly params?: string;
|
|
223
|
-
}[]): Promise<void>;
|
|
224
|
-
unsubscribe(id: string): Promise<void>;
|
|
225
|
-
setWindow(base: WindowBase, units: readonly string[]): Promise<void>;
|
|
226
|
-
windowState(base: WindowBase): Promise<WindowState>;
|
|
227
|
-
sync(): Promise<unknown>;
|
|
228
|
-
/**
|
|
229
|
-
* Rotate the client id (§1.5) after a `sync.invalid_client_id` refusal
|
|
230
|
-
* (`recommendedAction: resetClientId`). The next round carries the new id;
|
|
231
|
-
* the replica and outbox stay in place.
|
|
232
|
-
*/
|
|
233
|
-
resetClientId(): Promise<string>;
|
|
234
|
-
/**
|
|
235
|
-
* SPEC §12 local authority state: `local` while rounds run against the
|
|
236
|
-
* in-process authority, `attaching` during an attach, `attached` once rounds
|
|
237
|
-
* run against `base_url`, and `null` when the plugin configured no
|
|
238
|
-
* `local_authority_path`.
|
|
239
|
-
*/
|
|
1
|
+
import { TauriSyncClient as RemoteTauriSyncClient, type LocalAuthorityState, type TauriSyncClientConfig } from './remote.js';
|
|
2
|
+
export * from './remote.js';
|
|
3
|
+
/** Tauri bridge with the optional local-authority lifecycle (§12). */
|
|
4
|
+
export declare class TauriSyncClient extends RemoteTauriSyncClient {
|
|
5
|
+
protected allowPreflightCommand(method: string): boolean;
|
|
6
|
+
/** Local authority state, or null when the plugin configured no authority. */
|
|
240
7
|
localAuthorityState(): Promise<LocalAuthorityState | null>;
|
|
241
|
-
/**
|
|
242
|
-
* Upload the local authority's live rows to the `base_url` server (§12.3).
|
|
243
|
-
* Rejects with `sync.attach_rejected` (`details.reason`) when the server
|
|
244
|
-
* refuses; call {@link abandonLocalAuthorityAttach} to roll back.
|
|
245
|
-
*/
|
|
8
|
+
/** Upload the authority's live rows to the remote server (§12.3). */
|
|
246
9
|
attachLocalAuthority(): Promise<void>;
|
|
247
|
-
/** Roll back
|
|
10
|
+
/** Roll back a stopped attach and resume the local authority. */
|
|
248
11
|
abandonLocalAuthorityAttach(): Promise<void>;
|
|
249
|
-
syncUntilIdle(maxRounds?: number): Promise<unknown>;
|
|
250
|
-
proveCurrentBase(outcome: Pick<CommitOutcome, 'clientCommitId' | 'sequence'>, maxRounds?: number): Promise<CurrentBaseProof>;
|
|
251
|
-
conflicts(): Promise<readonly ConflictRecord[]>;
|
|
252
|
-
rejections(): Promise<readonly RejectionRecord[]>;
|
|
253
|
-
commitOutcome(clientCommitId: string): Promise<CommitOutcome | undefined>;
|
|
254
|
-
commitOutcomes(query?: CommitOutcomeQuery): Promise<readonly CommitOutcome[]>;
|
|
255
|
-
resolveCommitOutcome(input: ResolveCommitOutcomeInput): Promise<CommitOutcome>;
|
|
256
|
-
pendingCommits(): Promise<unknown[]>;
|
|
257
|
-
presence(scopeKey: string): Promise<readonly PresencePeer[]>;
|
|
258
|
-
setPresence(scopeKey: string, doc: Record<string, unknown> | null): Promise<void>;
|
|
259
|
-
connectRealtime(): Promise<void>;
|
|
260
|
-
disconnectRealtime(): Promise<void>;
|
|
261
|
-
/** Shut down the native core, release its keyring, then detach listeners. */
|
|
262
|
-
close(): Promise<void>;
|
|
263
|
-
}
|
|
264
|
-
/** The error a `{error}` reply surfaces (mirrors the web-client `ClientSyncError`). */
|
|
265
|
-
export declare class TauriSyncError extends Error {
|
|
266
|
-
readonly code: string;
|
|
267
|
-
readonly details: Readonly<Record<string, unknown>> | undefined;
|
|
268
|
-
readonly retryable: boolean;
|
|
269
|
-
constructor(code: string, message: string, details?: Readonly<Record<string, unknown>>, retryable?: boolean);
|
|
270
12
|
}
|
|
271
|
-
/**
|
|
272
|
-
* Construct the bridge and issue the native `create` (opening/attaching the
|
|
273
|
-
* file DB on the Rust side per the plugin config). Returns a ready
|
|
274
|
-
* `TauriSyncClient` that satisfies `SyncClientLike` — pass it straight to the
|
|
275
|
-
* React `<SyncProvider client={…}>`.
|
|
276
|
-
*/
|
|
277
13
|
export declare function createTauriSyncClient(config: TauriSyncClientConfig): Promise<TauriSyncClient>;
|
|
278
14
|
/** @internal Explicit bridge extension used by the authority entry. */
|
|
279
15
|
export declare function createTauriSyncClient<Client extends TauriSyncClient>(config: TauriSyncClientConfig, createClient: (...args: ConstructorParameters<typeof TauriSyncClient>) => Client): Promise<Client>;
|