@syncular/client 0.90.0 → 0.92.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 CHANGED
@@ -264,7 +264,9 @@ until it reloads. A leader answers a request with another identity with a
264
264
  identity and count as older: they never step down, so a newer tab next to
265
265
  one shows `leader: 'older'` until that tab reloads or closes. Bump
266
266
  `MULTI_TAB_PROTOCOL_VERSION` with every change to a message shape or to a
267
- forwarded method's arguments or result.
267
+ forwarded method's arguments or result: `test/multi-tab-protocol.test.ts`
268
+ pins a fingerprint of that surface to the constant and fails until both
269
+ change together.
268
270
 
269
271
  **A hidden leader keeps leadership.** A visible tab does not take leadership
270
272
  from a hidden leader. Web Locks `steal` revokes the lease while the leader's
package/dist/apply.d.ts CHANGED
@@ -10,6 +10,13 @@ import type { EncryptionConfig, SealedRow } from './encryption.js';
10
10
  import { type CompiledClientSchema, type CompiledClientTable, type JsonRowValue } from './schema.js';
11
11
  /** Lets the client wrap the physical write in its revision transaction. */
12
12
  export type ApplyTransaction = (fn: () => OverlayScope) => unknown;
13
+ /**
14
+ * A step of a generator-driven apply (§1.4 rule 4): the row count of the
15
+ * block it writes next, a negative boundary before work that runs outside a
16
+ * coalesced apply transaction, or async work the driver awaits outside any
17
+ * transaction and whose result it passes back.
18
+ */
19
+ export type ApplyStep = number | (() => Promise<unknown>);
13
20
  export declare function upsertLocalRow(db: ClientDatabase, table: CompiledClientTable, values: readonly RowValue[], syncVersion: number, sealed?: SealedRow): void;
14
21
  export declare function deleteLocalRow(db: ClientDatabase, table: CompiledClientTable, rowId: string, serverWrite?: boolean): void;
15
22
  /**
@@ -100,12 +107,15 @@ export declare function applySqliteSegment(db: ClientDatabase, schema: CompiledC
100
107
  readonly onChunk?: (appliedRows: number) => void;
101
108
  }): Promise<number>;
102
109
  /**
103
- * Apply a decoded rows segment: each block in one local transaction
110
+ * Apply a decoded rows segment: each block in its own transaction call
104
111
  * (§5.2/§1.4); `clearFirst` implements the §5.6 fresh-bootstrap first-page
105
- * delete inside the first block's transaction. Each row record carries its
112
+ * delete inside the first block's. Each row record carries its
106
113
  * `serverVersion` (§5.2), which lands in `_sync_version` exactly like a
107
114
  * `COMMIT` change's `rowVersion` (§5.6) — bootstrapped rows seed §6.2
108
- * `baseVersion` conflict detection immediately.
115
+ * `baseVersion` conflict detection immediately. The generator yields each
116
+ * block's row count before its write, so the caller can commit and yield to
117
+ * local reads there (§1.4 rule 4), and yields the async decryption as a step
118
+ * the caller awaits outside any transaction.
109
119
  */
110
120
  export declare function applyRowsSegment(db: ClientDatabase, schema: CompiledClientSchema, table: CompiledClientTable, segment: RowsSegment, options: {
111
121
  readonly clearFirst: boolean;
@@ -116,6 +126,6 @@ export declare function applyRowsSegment(db: ClientDatabase, schema: CompiledCli
116
126
  readonly transaction?: ApplyTransaction;
117
127
  readonly onProgress?: (rowsProcessed: number) => void;
118
128
  readonly isCurrent?: () => boolean;
119
- }, encryption?: EncryptionConfig): Promise<number>;
129
+ }, encryption?: EncryptionConfig): Generator<ApplyStep, number, unknown>;
120
130
  /** Let worker messages run only after the current SQLite transaction commits. */
121
131
  export declare function yieldToHost(): Promise<void>;
package/dist/apply.js CHANGED
@@ -342,13 +342,13 @@ export async function applySqliteSegment(db, schema, table, bytes, descriptor, o
342
342
  if (count !== descriptor.rowCount)
343
343
  imageInvalid('image row count does not match descriptor');
344
344
  const names = table.columns.map((column) => quoteIdent(column.name));
345
- const insertNames = [...names, quoteIdent(SYNC_VERSION_COLUMN)];
345
+ const version = quoteIdent(SYNC_VERSION_COLUMN);
346
+ const insertNames = [...names, version];
346
347
  const primaryKey = quoteIdent(table.primaryKey);
347
348
  const updates = insertNames
348
349
  .filter((name) => name !== primaryKey)
349
350
  .map((name) => `${name}=excluded.${name}`)
350
351
  .join(', ');
351
- const version = quoteIdent(SYNC_VERSION_COLUMN);
352
352
  // A statement copies the `rows` rows after `from`; NULL keys cannot
353
353
  // hide between statements.
354
354
  const range = (from, rows) => {
@@ -398,7 +398,7 @@ export async function applySqliteSegment(db, schema, table, bytes, descriptor, o
398
398
  const skipped = new Set();
399
399
  const landing = rows.filter((row) => lands(db, table, String(row[table.primaryKey]), Number(row._syncular_version), kept, skipped));
400
400
  for (;;) {
401
- db.exec(`INSERT INTO ${quoteIdent(table.name)}(${insertNames.join(', ')})SELECT ${[...names, quoteIdent('_syncular_version')].join(', ')} FROM ${source} AS image WHERE ${where} AND NOT EXISTS(SELECT 1 FROM ${quoteIdent(table.name)} AS held WHERE held.${primaryKey}=image.${primaryKey} AND held.${version}>=image._syncular_version) ON CONFLICT(${primaryKey})DO UPDATE SET ${updates}`, params);
401
+ db.exec(`INSERT INTO ${quoteIdent(table.name)}(${insertNames.join(', ')})SELECT ${names.join(', ')}, "_syncular_version" FROM ${source} AS image WHERE ${where} AND NOT EXISTS(SELECT 1 FROM ${quoteIdent(table.name)} AS held WHERE held.${primaryKey}=image.${primaryKey} AND held.${version}>=image._syncular_version) ON CONFLICT(${primaryKey})DO UPDATE SET ${updates}`, params);
402
402
  const copied = Number(db.query(`SELECT count(*)AS n FROM ${source} WHERE ${where}`, params)[0]?.n);
403
403
  applied += copied;
404
404
  chunk += copied;
@@ -436,42 +436,44 @@ export async function applySqliteSegment(db, schema, table, bytes, descriptor, o
436
436
  });
437
437
  }
438
438
  /**
439
- * Apply a decoded rows segment: each block in one local transaction
439
+ * Apply a decoded rows segment: each block in its own transaction call
440
440
  * (§5.2/§1.4); `clearFirst` implements the §5.6 fresh-bootstrap first-page
441
- * delete inside the first block's transaction. Each row record carries its
441
+ * delete inside the first block's. Each row record carries its
442
442
  * `serverVersion` (§5.2), which lands in `_sync_version` exactly like a
443
443
  * `COMMIT` change's `rowVersion` (§5.6) — bootstrapped rows seed §6.2
444
- * `baseVersion` conflict detection immediately.
444
+ * `baseVersion` conflict detection immediately. The generator yields each
445
+ * block's row count before its write, so the caller can commit and yield to
446
+ * local reads there (§1.4 rule 4), and yields the async decryption as a step
447
+ * the caller awaits outside any transaction.
445
448
  */
446
- export async function applyRowsSegment(db, schema, table, segment, options, encryption) {
449
+ export function* applyRowsSegment(db, schema, table, segment, options, encryption) {
447
450
  validateSegmentColumns(schema, table, segment);
448
451
  let applied = 0;
449
452
  let first = true;
450
- const blocks = segment.blocks.length > 0 ? segment.blocks : [[]];
451
- for (const block of blocks) {
452
- if (options.isCurrent?.() === false)
453
- break;
454
- // §5.11: decrypt this block's rows before opening the sync transaction
455
- // (WebCrypto is async; the SQLite transaction is not). Decrypt failure
456
- // aborts before any write in this block.
457
- const rows = [];
458
- for (const row of block) {
459
- if (table.hasEncryptedColumns) {
460
- const { decryptOrSealRowValues } = await import('./encryption.js');
461
- rows.push({
462
- ...(await decryptOrSealRowValues(encryption, table, row.values)),
463
- serverVersion: row.serverVersion,
464
- });
465
- }
466
- else
467
- rows.push(row);
468
- }
469
- if (options.isCurrent?.() === false)
470
- break;
453
+ let blocks = segment.blocks.length > 0 ? segment.blocks : [[]];
454
+ // §5.11: decrypt the segment's rows before any write (WebCrypto is async;
455
+ // the SQLite transaction is not). The rows decrypt concurrently; the first
456
+ // failing row in segment order decides the error, before any block writes.
457
+ if (table.hasEncryptedColumns)
458
+ blocks = (yield async () => {
459
+ const { decryptOrSealRowValues } = await import('./encryption.js');
460
+ return (await Promise.all(blocks.map((block) => Promise.allSettled(block.map(async (row) => ({
461
+ ...(await decryptOrSealRowValues(encryption, table, row.values)),
462
+ serverVersion: row.serverVersion,
463
+ })))))).map((block) => block.map((result) => {
464
+ if (result.status === 'rejected')
465
+ throw result.reason;
466
+ return result.value;
467
+ }));
468
+ });
469
+ for (const rows of blocks) {
471
470
  const clearThisBlock = first && options.clearFirst;
472
471
  first = false;
473
472
  if (!clearThisBlock && rows.length === 0)
474
473
  continue;
474
+ yield rows.length;
475
+ if (options.isCurrent?.() === false)
476
+ break;
475
477
  (options.transaction ?? ((fn) => db.transaction(fn)))(() => {
476
478
  const scope = [
477
479
  ...(hasUniqueIndex(table) ? [JSON.stringify([table.name])] : []),
@@ -505,7 +507,6 @@ export async function applyRowsSegment(db, schema, table, segment, options, encr
505
507
  return rebaseScope(scope, kept, skipped);
506
508
  });
507
509
  options.onProgress?.(applied);
508
- await yieldToHost();
509
510
  }
510
511
  options.onProgress?.(applied);
511
512
  return applied;
package/dist/client.d.ts CHANGED
@@ -120,6 +120,13 @@ export interface SyncIdleOptions {
120
120
  * shipped host loops pass it; the native bridge ignores it.
121
121
  */
122
122
  readonly skipEmpty?: boolean;
123
+ /**
124
+ * §8.4 host policy: after a round that applied data and left nothing
125
+ * pending, the round that confirms idle starts this many milliseconds
126
+ * later, so claims and writes made in reaction to that data ride in it.
127
+ * Default 0. The native bridge ignores it.
128
+ */
129
+ readonly coalesceMs?: number;
123
130
  }
124
131
  export type CurrentBaseProof = {
125
132
  readonly proven: true;