@syncular/client 0.85.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.
Files changed (58) hide show
  1. package/README.md +13 -4
  2. package/dist/apply.d.ts +1 -1
  3. package/dist/apply.js +25 -26
  4. package/dist/blob.d.ts +0 -4
  5. package/dist/blob.js +7 -22
  6. package/dist/client.d.ts +31 -10
  7. package/dist/client.js +501 -465
  8. package/dist/diagnostics.d.ts +2 -4
  9. package/dist/diagnostics.js +3 -17
  10. package/dist/encryption.js +5 -30
  11. package/dist/errors.d.ts +2 -0
  12. package/dist/errors.js +4 -0
  13. package/dist/failed-overlay.d.ts +8 -2
  14. package/dist/failed-overlay.js +33 -22
  15. package/dist/local-purge.d.ts +1 -0
  16. package/dist/local-purge.js +1 -1
  17. package/dist/local-rebootstrap-receipt.js +2 -2
  18. package/dist/local-rebootstrap.js +1 -1
  19. package/dist/native-bridge.d.ts +8 -3
  20. package/dist/native-bridge.js +29 -12
  21. package/dist/outcomes.d.ts +13 -1
  22. package/dist/outcomes.js +21 -20
  23. package/dist/previous-version.js +23 -35
  24. package/dist/progress.d.ts +4 -0
  25. package/dist/progress.js +14 -2
  26. package/dist/realtime-supervisor.d.ts +4 -1
  27. package/dist/realtime-supervisor.js +2 -2
  28. package/dist/schema.js +14 -13
  29. package/dist/state.d.ts +16 -4
  30. package/dist/state.js +83 -44
  31. package/dist/sync-scheduler.d.ts +8 -2
  32. package/dist/sync-scheduler.js +11 -3
  33. package/dist/worker-core.js +14 -10
  34. package/dist/worker-host.d.ts +10 -2
  35. package/dist/worker-host.js +15 -0
  36. package/dist/worker-protocol.d.ts +4 -1
  37. package/package.json +3 -3
  38. package/src/apply.ts +34 -47
  39. package/src/blob.ts +7 -24
  40. package/src/client.ts +699 -553
  41. package/src/diagnostics.ts +3 -19
  42. package/src/encryption.ts +15 -40
  43. package/src/errors.ts +5 -0
  44. package/src/failed-overlay.ts +39 -29
  45. package/src/local-purge.ts +1 -1
  46. package/src/local-rebootstrap-receipt.ts +2 -5
  47. package/src/local-rebootstrap.ts +1 -2
  48. package/src/native-bridge.ts +40 -14
  49. package/src/outcomes.ts +36 -31
  50. package/src/previous-version.ts +31 -40
  51. package/src/progress.ts +18 -2
  52. package/src/realtime-supervisor.ts +7 -3
  53. package/src/schema.ts +13 -13
  54. package/src/state.ts +107 -64
  55. package/src/sync-scheduler.ts +17 -5
  56. package/src/worker-core.ts +14 -18
  57. package/src/worker-host.ts +30 -1
  58. package/src/worker-protocol.ts +4 -0
@@ -6,6 +6,7 @@
6
6
  * diagnostic prose.
7
7
  */
8
8
  import type { SecurityLifecycle } from './client.js';
9
+ import { ChangeEmitter } from './invalidation.js';
9
10
  export declare const CLIENT_DIAGNOSTICS_VERSION: 2;
10
11
  export declare const MAX_DIAGNOSTIC_DOMAINS = 256;
11
12
  export declare const MAX_DIAGNOSTIC_QUERY_FAILURES = 256;
@@ -147,11 +148,8 @@ export interface ClientDiagnosticsSnapshot {
147
148
  readonly queryFailures: readonly DiagnosticQueryFailure[];
148
149
  }
149
150
  export type ClientDiagnosticsListener = (snapshot: ClientDiagnosticsSnapshot) => void;
150
- export declare class ClientDiagnosticsEmitter {
151
- #private;
151
+ export declare class ClientDiagnosticsEmitter extends ChangeEmitter<ClientDiagnosticsSnapshot> {
152
152
  get observed(): boolean;
153
- on(listener: ClientDiagnosticsListener): () => void;
154
- emit(snapshot: ClientDiagnosticsSnapshot): void;
155
153
  }
156
154
  /** Host wrappers replace topology facts without changing core evidence. */
157
155
  export declare function withClientDiagnosticsHost(snapshot: ClientDiagnosticsSnapshot, host: ClientDiagnosticsHost): ClientDiagnosticsSnapshot;
@@ -1,24 +1,10 @@
1
+ import { ChangeEmitter } from './invalidation.js';
1
2
  export const CLIENT_DIAGNOSTICS_VERSION = 2;
2
3
  export const MAX_DIAGNOSTIC_DOMAINS = 256;
3
4
  export const MAX_DIAGNOSTIC_QUERY_FAILURES = 256;
4
- export class ClientDiagnosticsEmitter {
5
- #listeners = new Set();
5
+ export class ClientDiagnosticsEmitter extends ChangeEmitter {
6
6
  get observed() {
7
- return this.#listeners.size > 0;
8
- }
9
- on(listener) {
10
- this.#listeners.add(listener);
11
- return () => this.#listeners.delete(listener);
12
- }
13
- emit(snapshot) {
14
- for (const listener of this.#listeners) {
15
- try {
16
- listener(snapshot);
17
- }
18
- catch {
19
- // Diagnostics observers cannot alter sync correctness.
20
- }
21
- }
7
+ return this.size > 0;
22
8
  }
23
9
  }
24
10
  /** Host wrappers replace topology facts without changing core evidence. */
@@ -46,16 +46,10 @@ function encryptionKeyId(config, table, rowId, values) {
46
46
  const selectorColumn = config.keyIdColumns?.[table.name];
47
47
  if (selectorColumn === undefined)
48
48
  return table.name;
49
- const index = table.columns.findIndex((column) => column.name === selectorColumn);
50
- if (index < 0) {
51
- throw new EncryptError(`encryption key-id column ${JSON.stringify(selectorColumn)} is not present on table ${JSON.stringify(table.name)}`);
52
- }
53
- if (table.columns[index]?.encrypted === true) {
54
- throw new EncryptError(`encryption key-id column ${JSON.stringify(selectorColumn)} on table ${JSON.stringify(table.name)} must not be encrypted`);
55
- }
56
- const selected = values[index];
49
+ // The column must exist, stay plaintext, and hold a non-empty string.
50
+ const selected = values[table.columns.findIndex((column) => column.name === selectorColumn && column.encrypted !== true)];
57
51
  if (typeof selected !== 'string' || selected.length === 0) {
58
- throw new EncryptError(`encryption key-id column ${JSON.stringify(selectorColumn)} on table ${JSON.stringify(table.name)} must contain a non-empty string`);
52
+ throw new EncryptError(`encryption key-id column ${JSON.stringify(selectorColumn)} on table ${JSON.stringify(table.name)} must be a plaintext column holding a non-empty string`);
59
53
  }
60
54
  return selected;
61
55
  }
@@ -72,22 +66,10 @@ function declaredTypeOf(column) {
72
66
  * unencrypted (§5.11).
73
67
  */
74
68
  export async function encryptRowValues(config, table, rowId, values, storedKeyId) {
75
- if (!table.hasEncryptedColumns)
76
- return values.slice();
77
69
  const out = values.slice();
78
70
  // Sparse semantics: absent (undefined) and NULL columns are never
79
71
  // re-encrypted, so a patch that presents no encrypted value needs no key.
80
- let hasPresentEncrypted = false;
81
- for (let i = 0; i < table.columns.length; i++) {
82
- if (table.columns[i]?.encrypted !== true)
83
- continue;
84
- const value = out[i];
85
- if (value !== undefined && value !== null) {
86
- hasPresentEncrypted = true;
87
- break;
88
- }
89
- }
90
- if (!hasPresentEncrypted)
72
+ if (!table.columns.some((column, i) => column.encrypted && out[i] != null))
91
73
  return out;
92
74
  if (config === undefined) {
93
75
  throw new EncryptError('encrypted columns need an encryption config');
@@ -162,8 +144,6 @@ export async function decryptOrSealRowValues(config, table, values) {
162
144
  * wrong key or malformed envelope throws `client.decrypt_failed` (§5.11).
163
145
  */
164
146
  export async function decryptRowValues(config, table, values) {
165
- if (!table.hasEncryptedColumns)
166
- return values.slice();
167
147
  const out = values.slice();
168
148
  for (let i = 0; i < table.columns.length; i++) {
169
149
  const column = table.columns[i];
@@ -178,12 +158,7 @@ export async function decryptRowValues(config, table, values) {
178
158
  if (config === undefined) {
179
159
  throw new DecryptError('encrypted columns need an encryption config');
180
160
  }
181
- out[i] = deserializeGuard(await decryptValue(declaredTypeOf(column), value, config.keyProvider, table.name));
161
+ out[i] = await decryptValue(declaredTypeOf(column), value, config.keyProvider, table.name);
182
162
  }
183
163
  return out;
184
164
  }
185
- // decryptValue already returns a PlainValue; RowValue is a superset, so this
186
- // is just the type widening (kept explicit for clarity at the seam).
187
- function deserializeGuard(value) {
188
- return value;
189
- }
package/dist/errors.d.ts CHANGED
@@ -33,6 +33,8 @@ export declare class ClientSyncError extends Error {
33
33
  readonly recommendedAction: string | undefined;
34
34
  constructor(code: string, message: string, retryable?: boolean, details?: Readonly<Record<string, unknown>>, recommendedAction?: string);
35
35
  }
36
+ /** `sync.local_corrupt`: persisted local state this client cannot read. */
37
+ export declare function localStateCorrupt(message: string): ClientSyncError;
36
38
  /** Shared invalid-request construction for client validators and transport guards. */
37
39
  export declare function invalidRequest(message: string, retryable?: boolean, details?: Readonly<Record<string, unknown>>): ClientSyncError;
38
40
  /** Shared retryable `sync.transport_failed` construction for client transports. */
package/dist/errors.js CHANGED
@@ -39,6 +39,10 @@ export class ClientSyncError extends Error {
39
39
  this.recommendedAction = recommendedAction;
40
40
  }
41
41
  }
42
+ /** `sync.local_corrupt`: persisted local state this client cannot read. */
43
+ export function localStateCorrupt(message) {
44
+ return new ClientSyncError('sync.local_corrupt', message);
45
+ }
42
46
  /** Shared invalid-request construction for client validators and transport guards. */
43
47
  export function invalidRequest(message, retryable = false, details) {
44
48
  return new ClientSyncError('sync.invalid_request', message, retryable, details);
@@ -5,12 +5,18 @@ import type { RowValue } from '@syncular/core';
5
5
  import type { RetainedCommitRow } from './outcomes.js';
6
6
  import type { OutboxCommit, OutboxBeforeImage } from './outbox.js';
7
7
  export declare function ensureFailedOverlaySchema(db: ClientDatabase): void;
8
- export declare function retainedBaseWrite(db: ClientDatabase, table: CompiledClientTable, rowId: string, values?: Readonly<Record<string, JsonRowValue>>, version?: number): void;
8
+ /**
9
+ * Server writes, after they are stored: each `written` row replaces the base
10
+ * of its key's retained rows (`undefined`: deleted), and the table's retained
11
+ * intents re-read their unique conflicts with the written keys. A written row
12
+ * without a retained row costs no statement.
13
+ */
14
+ export declare function retainedBaseWrite(db: ClientDatabase, table: CompiledClientTable, written: ReadonlyMap<string, readonly [readonly RowValue[], number] | undefined>): void;
9
15
  export declare function retainFailedRows(db: ClientDatabase, commit: OutboxCommit, images: readonly OutboxBeforeImage[], commitSeq?: number): void;
10
16
  /** Match declared keys through SQLite, preserving index affinity and NULL semantics. */
11
17
  export declare function uniqueConflicts(db: ClientDatabase, table: CompiledClientTable, values: Readonly<Record<string, RowValue>>): NonNullable<RetainedCommitRow['uniqueConflicts']>;
12
18
  /** Exact row keys are JSON [table,id]; table scopes include unique-key peers. */
13
19
  export type OverlayScope = readonly string[];
14
- export declare function restoreFailedBases(db: ClientDatabase, schema: CompiledClientSchema, scope?: OverlayScope): boolean;
20
+ export declare function restoreFailedBases(db: ClientDatabase, schema: CompiledClientSchema, scope?: OverlayScope): void;
15
21
  export declare function failedOverlayCommits(db: ClientDatabase, acknowledged?: boolean, scope?: OverlayScope, schema?: CompiledClientSchema): OutboxCommit[];
16
22
  export declare function dropFailedRows(db: ClientDatabase, schema: CompiledClientSchema, matches: (table: string, values: Readonly<Record<string, JsonRowValue>>) => boolean): OutboxCommit[];
@@ -2,11 +2,11 @@ import { hasUniqueIndex } from './schema.js';
2
2
  import { OUTCOMES_TABLE } from './outcomes.js';
3
3
  import { OUTBOX_IMAGES } from './outbox.js';
4
4
  export const RETAINED_ROWS = '_syncular_failed_rows';
5
- import { ClientSyncError } from './errors.js';
5
+ import { localStateCorrupt } from './errors.js';
6
6
  import { mapRowValues, fromSqlValue, jsonToRowValue, pkSqlValue, quoteIdent, rowValueToJson, SYNC_VERSION_COLUMN, toSqlValue, } from './schema.js';
7
7
  import { deleteLocalRow, upsertLocalRow } from './apply.js';
8
8
  /** Protected failure state. The server base advances independently of intent. */
9
- const SET_UNIQUE_CONFLICTS = `UPDATE ${RETAINED_ROWS} SET unique_conflicts=? WHERE commit_id=? AND idx=?`;
9
+ const SET_UNIQUE_CONFLICTS = `UPDATE ${RETAINED_ROWS} SET unique_conflicts=? WHERE rowid=?`;
10
10
  export function ensureFailedOverlaySchema(db) {
11
11
  db.exec(`CREATE TABLE IF NOT EXISTS ${RETAINED_ROWS}(commit_id TEXT NOT NULL,idx INTEGER NOT NULL,tbl TEXT NOT NULL,id TEXT NOT NULL,at INTEGER NOT NULL,op TEXT NOT NULL,intent TEXT,base TEXT,version INTEGER,unique_conflicts TEXT,commit_seq INTEGER,PRIMARY KEY(commit_id,idx))`);
12
12
  const columns = db.query(`PRAGMA table_info(${RETAINED_ROWS})`);
@@ -15,24 +15,38 @@ export function ensureFailedOverlaySchema(db) {
15
15
  db.exec(`ALTER TABLE ${RETAINED_ROWS} ADD COLUMN ${column}`);
16
16
  db.exec(`CREATE INDEX IF NOT EXISTS ${RETAINED_ROWS}_row ON ${RETAINED_ROWS}(tbl,id)`);
17
17
  }
18
- export function retainedBaseWrite(db, table, rowId, values, version) {
19
- db.exec(`UPDATE ${RETAINED_ROWS} SET base=?,version=? WHERE tbl=? AND id=?`, [
20
- values === undefined ? null : JSON.stringify(values),
21
- version ?? null,
22
- table.name,
23
- rowId,
24
- ]);
25
- if (!hasUniqueIndex(table))
18
+ /**
19
+ * Server writes, after they are stored: each `written` row replaces the base
20
+ * of its key's retained rows (`undefined`: deleted), and the table's retained
21
+ * intents re-read their unique conflicts with the written keys. A written row
22
+ * without a retained row costs no statement.
23
+ */
24
+ export function retainedBaseWrite(db, table, written) {
25
+ if (!written.size)
26
26
  return;
27
- for (const retained of db.query(`SELECT commit_id,idx,intent,unique_conflicts FROM ${RETAINED_ROWS} WHERE tbl=? AND commit_seq IS NULL`, [table.name])) {
27
+ for (const retained of db.query(`SELECT rowid AS r,* FROM ${RETAINED_ROWS} WHERE tbl=?`, [table.name])) {
28
+ const base = written.get(retained.id);
29
+ if (written.has(retained.id))
30
+ db.exec(`UPDATE ${RETAINED_ROWS} SET base=?,version=? WHERE rowid=?`, [
31
+ base
32
+ ? JSON.stringify(Object.fromEntries(table.columns.map((column, index) => [
33
+ column.name,
34
+ rowValueToJson(base[0][index] ?? null),
35
+ ])))
36
+ : null,
37
+ base?.[1] ?? null,
38
+ retained.r,
39
+ ]);
40
+ if (!hasUniqueIndex(table) || retained.commit_seq !== null)
41
+ continue;
28
42
  const prior = retained.unique_conflicts === null
29
43
  ? []
30
44
  : JSON.parse(retained.unique_conflicts);
31
- const conflicts = prior.filter((conflict) => conflict.rowId !== rowId);
32
- if (values !== undefined && retained.intent !== null) {
45
+ const conflicts = prior.filter((conflict) => !written.has(conflict.rowId));
46
+ if (retained.intent !== null) {
33
47
  const intent = JSON.parse(retained.intent);
34
48
  conflicts.push(...uniqueConflicts(db, table, mapRowValues(intent, jsonToRowValue))
35
- .filter((conflict) => conflict.rowId === rowId)
49
+ .filter((conflict) => written.has(conflict.rowId))
36
50
  .map((conflict) => ({
37
51
  ...conflict,
38
52
  serverRow: mapRowValues(conflict.serverRow, rowValueToJson),
@@ -43,8 +57,7 @@ export function retainedBaseWrite(db, table, rowId, values, version) {
43
57
  ? JSON.stringify(conflicts.sort((a, b) => table.indexes.findIndex((index) => index.name === a.index) -
44
58
  table.indexes.findIndex((index) => index.name === b.index)))
45
59
  : null,
46
- retained.commit_id,
47
- Number(retained.idx),
60
+ retained.r,
48
61
  ]);
49
62
  }
50
63
  }
@@ -57,7 +70,7 @@ export function retainFailedRows(db, commit, images, commitSeq) {
57
70
  ? { ...image?.values, ...operation.values }
58
71
  : undefined;
59
72
  if (!image)
60
- throw new ClientSyncError('sync.local_corrupt', 'missing intent before-image');
73
+ throw localStateCorrupt('missing intent before-image');
61
74
  db.exec(`INSERT INTO ${RETAINED_ROWS}(commit_id,idx,tbl,id,at,op,intent,base,version,commit_seq)VALUES(?,?,?,?,?,?,?,?,?,?)`, [
62
75
  commit.clientCommitId,
63
76
  index,
@@ -95,7 +108,7 @@ export function uniqueConflicts(db, table, values) {
95
108
  function retainedRows(db, scope, acknowledged) {
96
109
  // A scope joins through the (tbl, id) index; a scan per applied commit
97
110
  // would make a drained batch quadratic.
98
- return db.query(`SELECT * FROM ${RETAINED_ROWS} WHERE (?1 IS NULL OR rowid IN(SELECT r.rowid FROM json_each(?1) k JOIN ${RETAINED_ROWS} r ON r.tbl=json_extract(k.value,'$[0]') AND r.id=json_extract(k.value,'$[1]') UNION SELECT r.rowid FROM json_each(?1) k JOIN ${RETAINED_ROWS} r ON json_array_length(k.value)=1 AND r.tbl=json_extract(k.value,'$[0]')))${acknowledged === undefined ? '' : ` AND commit_seq IS${acknowledged ? ' NOT' : ''} NULL`} ORDER BY commit_seq,at,commit_id,idx`, [scope ? JSON.stringify(scope) : null]);
111
+ return db.query(`SELECT rowid AS r,* FROM ${RETAINED_ROWS} WHERE (?1 IS NULL OR rowid IN(SELECT r.rowid FROM json_each(?1) k JOIN ${RETAINED_ROWS} r ON r.tbl=json_extract(k.value,'$[0]') AND r.id=json_extract(k.value,'$[1]') UNION SELECT r.rowid FROM json_each(?1) k JOIN ${RETAINED_ROWS} r ON json_array_length(k.value)=1 AND r.tbl=json_extract(k.value,'$[0]')))${acknowledged === undefined ? '' : ` AND commit_seq IS${acknowledged ? ' NOT' : ''} NULL`} ORDER BY commit_seq,at,commit_id,idx`, [scope ? JSON.stringify(scope) : null]);
99
112
  }
100
113
  export function restoreFailedBases(db, schema, scope) {
101
114
  const seen = new Set();
@@ -114,10 +127,9 @@ export function restoreFailedBases(db, schema, scope) {
114
127
  deleteLocalRow(db, table, row.id, false);
115
128
  else {
116
129
  const values = JSON.parse(String(row.base));
117
- upsertLocalRow(db, table, table.columns.map((column) => jsonToRowValue(values[column.name] ?? null)), (row.version ?? -1), false);
130
+ upsertLocalRow(db, table, table.columns.map((column) => jsonToRowValue(values[column.name] ?? null)), (row.version ?? -1));
118
131
  }
119
132
  }
120
- return seen.size > 0;
121
133
  }
122
134
  export function failedOverlayCommits(db, acknowledged = false, scope, schema) {
123
135
  const commits = new Map();
@@ -149,8 +161,7 @@ export function failedOverlayCommits(db, acknowledged = false, scope, schema) {
149
161
  ...conflict,
150
162
  serverRow: mapRowValues(conflict.serverRow, rowValueToJson),
151
163
  }))),
152
- row.commit_id,
153
- row.idx,
164
+ row.r,
154
165
  ]);
155
166
  }
156
167
  }
@@ -8,6 +8,7 @@
8
8
  * generated FTS projections, doomed optimistic commits, and blob references.
9
9
  */
10
10
  import type { CompiledClientSchema, CompiledClientTable } from './schema.js';
11
+ export declare const CODE_LIKE_VALUE: RegExp;
11
12
  /** One AND-combined selector set. Targets are OR-combined. */
12
13
  export interface LocalDataPurgeTarget {
13
14
  readonly table: string;
@@ -12,7 +12,7 @@ const MAX_TARGETS = 64;
12
12
  const MAX_SELECTORS_PER_TARGET = 8;
13
13
  const MAX_VALUES_PER_SELECTOR = 128;
14
14
  const MAX_ROUTING_VALUE_LENGTH = 256;
15
- const CODE_LIKE_VALUE = /^[A-Za-z0-9][A-Za-z0-9._:-]*$/;
15
+ export const CODE_LIKE_VALUE = /^[A-Za-z0-9][A-Za-z0-9._:-]*$/;
16
16
  function compareCodeLike(left, right) {
17
17
  return left < right ? -1 : left > right ? 1 : 0;
18
18
  }
@@ -1,4 +1,4 @@
1
- import { ClientSyncError } from './errors.js';
1
+ import { localStateCorrupt } from './errors.js';
2
2
  const LEGACY_MARKER = 'v1';
3
3
  const RECEIPT_VERSION = 2;
4
4
  const RECEIPT_KEYS = [
@@ -7,7 +7,7 @@ const RECEIPT_KEYS = [
7
7
  'version',
8
8
  ];
9
9
  function invalidReceipt() {
10
- throw new ClientSyncError('sync.local_corrupt', 'persisted local rebootstrap receipt is invalid');
10
+ throw localStateCorrupt('persisted local rebootstrap receipt is invalid');
11
11
  }
12
12
  function isCount(value) {
13
13
  return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0;
@@ -7,7 +7,7 @@
7
7
  * projection state so the registered subscriptions can bootstrap it again.
8
8
  */
9
9
  import { ClientSyncError, invalidRequest } from './errors.js';
10
- const CODE_LIKE_VALUE = /^[A-Za-z0-9][A-Za-z0-9._:-]*$/;
10
+ import { CODE_LIKE_VALUE } from './local-purge.js';
11
11
  const RESULT_KEYS = [
12
12
  'alreadyApplied',
13
13
  'resetSubscriptions',
@@ -11,7 +11,7 @@
11
11
  * `{$bigint: decimal}`, the convention of the Rust command router. The browser
12
12
  * client and worker entries never import this module.
13
13
  */
14
- import { type ClientSnapshotMethods, type CurrentBaseProof, type MutationInput, type PresencePeer, type PromiseMethods, type QueryReadSpec, type QuerySnapshot, type SecurityLifecycle, type SnapshotRead, type SnapshotReadRequest, type SyncClient, type SyncClientConfig, type UnitCatchup, type WindowState } from './client.js';
14
+ import { type ClientSnapshotMethods, type CommitDelivery, type CurrentBaseProof, type MutationInput, type ReplaceCommitOutcomeInput, type PresencePeer, type PromiseMethods, type QueryReadSpec, type QuerySnapshot, type SecurityLifecycle, type SnapshotRead, type SnapshotReadRequest, type SyncClient, type SyncClientConfig, type SyncIdleOptions, type UnitCatchup, type WindowState } from './client.js';
15
15
  import type { SqlRow, SqlValue } from './database.js';
16
16
  import type { PresenceErrorCode, UnitScopes } from '@syncular/core';
17
17
  export { unitId, type UnitScopes } from '@syncular/core';
@@ -24,6 +24,7 @@ import type { CommitOutcome, CommitOutcomeQuery, ConflictRecord, RejectionRecord
24
24
  import { type PreviousVersionAudit, type PreviousVersionReadSpec, type PreviousVersionSnapshot } from './previous-version.js';
25
25
  import { type SyncProgress, type SyncProgressListener } from './progress.js';
26
26
  import type { UnitRecord } from './state.js';
27
+ import type { OutboxCommit } from './outbox.js';
27
28
  import type { WindowBase } from './window.js';
28
29
  /** A driver-protocol reply: `{result}` on success or `{error}` on failure. */
29
30
  export interface NativeReply {
@@ -213,17 +214,21 @@ export declare abstract class NativeBridgeClient implements PromiseMethods<Clien
213
214
  unit(id: string): Promise<UnitRecord | undefined>;
214
215
  /** §7.5: one unit's persisted catch-up state (never the owner cache). */
215
216
  unitCatchup(id: string): Promise<UnitCatchup>;
217
+ /** §7.5: one client commit's delivery status, from the same snapshot read. */
218
+ commitDelivery(id: string): Promise<CommitDelivery>;
216
219
  setWindow(base: WindowBase, units: readonly string[]): Promise<void>;
217
220
  windowState(base: WindowBase): Promise<WindowState>;
218
221
  sync(): Promise<unknown>;
219
- syncUntilIdle(maxRounds?: number, timeoutMs?: number): Promise<unknown>;
222
+ /** The Rust core has no §8.4 empty-replica gate: `skipEmpty` is not sent. */
223
+ syncUntilIdle(options?: number | SyncIdleOptions, timeoutMs?: number): Promise<unknown>;
220
224
  proveCurrentBase(outcome: Pick<CommitOutcome, 'clientCommitId' | 'sequence'>, maxRounds?: number): Promise<CurrentBaseProof>;
221
225
  conflicts(): Promise<readonly ConflictRecord[]>;
222
226
  rejections(): Promise<readonly RejectionRecord[]>;
223
227
  commitOutcome(clientCommitId: string): Promise<CommitOutcome | undefined>;
224
228
  commitOutcomes(query?: CommitOutcomeQuery): Promise<readonly CommitOutcome[]>;
225
229
  resolveCommitOutcome(input: ResolveCommitOutcomeInput): Promise<CommitOutcome>;
226
- pendingCommits(): Promise<unknown[]>;
230
+ replaceCommitOutcome({ clientCommitId, sequence, replacement, }: ReplaceCommitOutcomeInput): Promise<string>;
231
+ pendingCommits(): Promise<OutboxCommit[]>;
227
232
  presence(scopeKey: string): Promise<readonly PresencePeer[]>;
228
233
  setPresence(scopeKey: string, doc: Record<string, unknown> | null): Promise<void>;
229
234
  connectRealtime(): Promise<void>;
@@ -496,7 +496,7 @@ export class NativeBridgeClient {
496
496
  sql: spec.sql,
497
497
  params: encodeValue(spec.params ?? []),
498
498
  coverage: spec.coverage ?? [],
499
- ...(spec.owner !== undefined ? { owner: spec.owner } : {}),
499
+ owner: spec.owner,
500
500
  })));
501
501
  return {
502
502
  revision: BigInt(result.revision),
@@ -517,7 +517,7 @@ export class NativeBridgeClient {
517
517
  coverage: request.coverage ?? [],
518
518
  units: request.units ?? [],
519
519
  commitIds: request.commitIds ?? [],
520
- ...(request.owner !== undefined ? { owner: request.owner } : {}),
520
+ owner: request.owner,
521
521
  }));
522
522
  return {
523
523
  revision: BigInt(result.revision),
@@ -660,10 +660,8 @@ export class NativeBridgeClient {
660
660
  async uploadBlob(bytes, options) {
661
661
  const result = (await this.command('uploadBlob', {
662
662
  bytes: encodeValue(bytes),
663
- ...(options?.mediaType !== undefined
664
- ? { mediaType: options.mediaType }
665
- : {}),
666
- ...(options?.name !== undefined ? { name: options.name } : {}),
663
+ mediaType: options?.mediaType,
664
+ name: options?.name,
667
665
  }));
668
666
  return result.ref;
669
667
  }
@@ -709,6 +707,11 @@ export class NativeBridgeClient {
709
707
  async unitCatchup(id) {
710
708
  return (await this.snapshotRead({ statements: [], units: [id] })).units[0];
711
709
  }
710
+ /** §7.5: one client commit's delivery status, from the same snapshot read. */
711
+ async commitDelivery(id) {
712
+ return (await this.snapshotRead({ statements: [], commitIds: [id] }))
713
+ .deliveries[0];
714
+ }
712
715
  async setWindow(base, units) {
713
716
  await this.command('setWindow', { base, units });
714
717
  }
@@ -719,10 +722,14 @@ export class NativeBridgeClient {
719
722
  async sync() {
720
723
  return this.command('sync', {});
721
724
  }
722
- async syncUntilIdle(maxRounds, timeoutMs) {
725
+ /** The Rust core has no §8.4 empty-replica gate: `skipEmpty` is not sent. */
726
+ async syncUntilIdle(options, timeoutMs) {
727
+ const maxRounds = typeof options === 'object' ? options.maxRounds : options;
728
+ if (typeof options === 'object')
729
+ timeoutMs = options.timeoutMs;
723
730
  return this.command('syncUntilIdle', {
724
- ...(maxRounds !== undefined ? { maxRounds } : {}),
725
- ...(timeoutMs !== undefined ? { timeoutMs } : {}),
731
+ maxRounds,
732
+ timeoutMs,
726
733
  });
727
734
  }
728
735
  async proveCurrentBase(outcome, maxRounds) {
@@ -734,7 +741,7 @@ export class NativeBridgeClient {
734
741
  clientCommitId: outcome.clientCommitId,
735
742
  sequence: outcome.sequence,
736
743
  },
737
- ...(maxRounds !== undefined ? { maxRounds } : {}),
744
+ maxRounds,
738
745
  }));
739
746
  return proof.proven
740
747
  ? { proven: true, rows: this.#retainedRows(proof.rows) }
@@ -766,9 +773,19 @@ export class NativeBridgeClient {
766
773
  }));
767
774
  return this.#commitOutcome(result.outcome);
768
775
  }
776
+ async replaceCommitOutcome({ clientCommitId, sequence, replacement, }) {
777
+ const result = (await this.command('replaceCommitOutcome', {
778
+ clientCommitId,
779
+ sequence,
780
+ ...(replacement === undefined
781
+ ? {}
782
+ : { replacement: encodeValue(replacement) }),
783
+ }));
784
+ return result.clientCommitId;
785
+ }
769
786
  async pendingCommits() {
770
- const result = (await this.command('pendingCommitIds', {}));
771
- return result.ids;
787
+ const result = (await this.command('pendingCommits', {}));
788
+ return result.commits;
772
789
  }
773
790
  async presence(scopeKey) {
774
791
  const result = (await this.command('presence', { scopeKey }));
@@ -84,8 +84,19 @@ export interface CommitOutcome {
84
84
  readonly retainedRows?: readonly RetainedCommitRow[];
85
85
  readonly resolution: CommitOutcomeResolution;
86
86
  readonly resolvedAtMs?: number;
87
+ /**
88
+ * The replacement commit of a `superseded` outcome; on an `active`
89
+ * outcome, the replacement of a pending decision (§7.2.2).
90
+ */
87
91
  readonly replacementClientCommitId?: string;
88
92
  }
93
+ export interface PendingDecision {
94
+ readonly clientCommitId: string;
95
+ readonly sequence: number;
96
+ readonly replacementClientCommitId: string;
97
+ }
98
+ /** §7.2.2: active outcomes whose replacement waits for a proven base. */
99
+ export declare function pendingDecisions(db: ClientDatabase): PendingDecision[];
89
100
  export interface CommitOutcomeQuery {
90
101
  /** Newest-first result cap. Defaults to all retained entries. */
91
102
  readonly limit?: number;
@@ -111,7 +122,8 @@ export declare function listCommitOutcomes(db: ClientDatabase, query?: CommitOut
111
122
  export declare function persistCommitOutcomeResolution(db: ClientDatabase, input: ResolveCommitOutcomeInput, nowMs: number): CommitOutcome | undefined;
112
123
  /**
113
124
  * Bound journal growth without deleting active failures. If active failures
114
- * alone exceed the cap the journal intentionally remains over-capacity.
125
+ * alone exceed the cap the journal intentionally remains over-capacity. The
126
+ * client constructor validates `maxEntries`.
115
127
  */
116
128
  export declare function pruneCommitOutcomes(db: ClientDatabase, maxEntries: number): number;
117
129
  export declare function activeFailureRecords(outcomes: readonly CommitOutcome[]): {
package/dist/outcomes.js CHANGED
@@ -10,8 +10,18 @@ import { RETAINED_ROWS } from './failed-overlay.js';
10
10
  * deliberately stay local; retention never deletes an unresolved failure.
11
11
  */
12
12
  import { normalizeRejectionDetails, } from '@syncular/core';
13
- import { ClientSyncError, invalidRequest } from './errors.js';
13
+ import { invalidRequest, localStateCorrupt } from './errors.js';
14
14
  import { isBytesEnvelope, mapRowValues, jsonToRowValue, rowValueToJson, } from './schema.js';
15
+ /** §7.2.2: active outcomes whose replacement waits for a proven base. */
16
+ export function pendingDecisions(db) {
17
+ return db
18
+ .query(`SELECT seq,client_commit_id,replacement_client_commit_id FROM ${OUTCOMES_TABLE} WHERE resolution='active' AND replacement_client_commit_id IS NOT NULL`)
19
+ .map((row) => ({
20
+ clientCommitId: row.client_commit_id,
21
+ sequence: row.seq,
22
+ replacementClientCommitId: row.replacement_client_commit_id,
23
+ }));
24
+ }
15
25
  function encodeResults(results) {
16
26
  const stored = results.map((result) => {
17
27
  if (result.status !== 'conflict')
@@ -51,10 +61,12 @@ export function isStoredOperation(value) {
51
61
  value.values === undefined &&
52
62
  value.insert === undefined)));
53
63
  }
64
+ function corrupt() {
65
+ throw localStateCorrupt('persisted commit outcome is invalid');
66
+ }
54
67
  function decodeResults(raw) {
55
- function corrupt() {
56
- throw new ClientSyncError('sync.local_corrupt', 'persisted commit outcome is invalid');
57
- }
68
+ // §6.1 op indexes are i32.
69
+ const badIndex = (index) => !Number.isInteger(index) || index < -2147483648 || index > 2147483647;
58
70
  const stored = JSON.parse(raw);
59
71
  if (!Array.isArray(stored))
60
72
  corrupt();
@@ -62,9 +74,7 @@ function decodeResults(raw) {
62
74
  if (!isRecord(result))
63
75
  corrupt();
64
76
  if (result.status === 'applied') {
65
- if (!Number.isInteger(result.opIndex) ||
66
- result.opIndex < -2147483648 ||
67
- result.opIndex > 2147483647)
77
+ if (badIndex(result.opIndex))
68
78
  corrupt();
69
79
  return result;
70
80
  }
@@ -73,9 +83,7 @@ function decodeResults(raw) {
73
83
  if (!isRecord(conflict) ||
74
84
  !isStoredRow(conflict.serverRow) ||
75
85
  typeof conflict.clientCommitId !== 'string' ||
76
- !Number.isInteger(conflict.opIndex) ||
77
- conflict.opIndex < -2147483648 ||
78
- conflict.opIndex > 2147483647 ||
86
+ badIndex(conflict.opIndex) ||
79
87
  typeof conflict.table !== 'string' ||
80
88
  typeof conflict.rowId !== 'string' ||
81
89
  typeof conflict.code !== 'string' ||
@@ -102,9 +110,7 @@ function decodeResults(raw) {
102
110
  const rejection = result.rejection;
103
111
  if (!isRecord(rejection) ||
104
112
  typeof rejection.clientCommitId !== 'string' ||
105
- !Number.isInteger(rejection.opIndex) ||
106
- rejection.opIndex < -2147483648 ||
107
- rejection.opIndex > 2147483647 ||
113
+ badIndex(rejection.opIndex) ||
108
114
  typeof rejection.code !== 'string' ||
109
115
  typeof rejection.message !== 'string' ||
110
116
  typeof rejection.retryable !== 'boolean' ||
@@ -206,9 +212,6 @@ export function persistedCommitOutcome(db, clientCommitId) {
206
212
  const row = outcomeRow(db, clientCommitId);
207
213
  if (row === undefined)
208
214
  return undefined;
209
- function corrupt() {
210
- throw new ClientSyncError('sync.local_corrupt', 'persisted commit outcome is invalid');
211
- }
212
215
  const status = row.status;
213
216
  const resolution = row.resolution;
214
217
  if ((status !== 'applied' &&
@@ -272,12 +275,10 @@ export function persistCommitOutcomeResolution(db, input, nowMs) {
272
275
  }
273
276
  /**
274
277
  * Bound journal growth without deleting active failures. If active failures
275
- * alone exceed the cap the journal intentionally remains over-capacity.
278
+ * alone exceed the cap the journal intentionally remains over-capacity. The
279
+ * client constructor validates `maxEntries`.
276
280
  */
277
281
  export function pruneCommitOutcomes(db, maxEntries) {
278
- if (!Number.isSafeInteger(maxEntries) || maxEntries < 1) {
279
- throw invalidRequest('outcome retention maxEntries must be a positive safe integer');
280
- }
281
282
  const count = db.query(`SELECT COUNT(*) AS count FROM ${OUTCOMES_TABLE}`)[0]
282
283
  ?.count;
283
284
  const excess = Math.max(0, (count ?? 0) - maxEntries);