@syncular/client 0.52.0 → 0.53.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
@@ -393,6 +393,11 @@ and generated table names, never scopes. It lets a support screen distinguish
393
393
  an absent registration from a legitimate zero-row completed bootstrap. The
394
394
  snapshot also distinguishes reset, revocation, failure, schema floor, lease
395
395
  stop, pending outbox, offline transport, and storage pressure/unreadability.
396
+ Failed progress and `lastRound` diagnostics expose an optional bounded
397
+ `causeKind` and HTTP status. Worker leaders and followers receive the same
398
+ evidence. A new progress attempt clears its failure fields; a successful round
399
+ replaces the failed last round. `host.connectivity` describes the latest
400
+ endpoint observation and does not prove the device's network state.
396
401
  `queryFailures` retains at most 256 failed owned snapshot reads until each query
397
402
  reads successfully. An entry contains only its stable PHI-free owner id,
398
403
  generated table names, a stable code, an optional numeric SQLite result code,
package/dist/client.js CHANGED
@@ -1323,9 +1323,13 @@ export class SyncClient {
1323
1323
  : this.#lastRound?.status === 'succeeded'
1324
1324
  ? 'online'
1325
1325
  : this.#lastRound?.status === 'failed' &&
1326
- this.#transportFailureCode(this.#lastRound.errorCode)
1326
+ (this.#lastRound.causeKind === 'network' ||
1327
+ this.#lastRound.causeKind === 'connect')
1327
1328
  ? 'offline'
1328
- : 'unknown';
1329
+ : this.#lastRound?.status === 'failed' &&
1330
+ this.#lastRound.httpStatus !== undefined
1331
+ ? 'online'
1332
+ : 'unknown';
1329
1333
  const expectedOrder = new Map(expected.map((item, index) => [item.id, index]));
1330
1334
  const allSubscriptions = [...subscriptions.values()].sort((a, b) => {
1331
1335
  const aExpected = expectedOrder.get(a.id);
@@ -1713,6 +1717,14 @@ export class SyncClient {
1713
1717
  (!Number.isInteger(maxRounds) || maxRounds < 1 || maxRounds > 0xffffffff))
1714
1718
  throw invalidRequest('maxRounds must be a positive integer');
1715
1719
  const { clientCommitId, sequence } = outcome;
1720
+ const provable = (candidate) => candidate !== undefined &&
1721
+ candidate.sequence === sequence &&
1722
+ candidate.resolution === 'active' &&
1723
+ (candidate.status === 'conflict' || candidate.status === 'rejected') &&
1724
+ candidate.operations !== undefined &&
1725
+ candidate.retainedRows !== undefined &&
1726
+ candidate.operations.length === candidate.retainedRows.length &&
1727
+ candidate.retainedRows.length > 0;
1716
1728
  let initial;
1717
1729
  try {
1718
1730
  initial = readCommitOutcome(this.#db, clientCommitId);
@@ -1720,14 +1732,7 @@ export class SyncClient {
1720
1732
  catch {
1721
1733
  return { proven: false, reason: 'snapshot_failed' };
1722
1734
  }
1723
- if (initial === undefined ||
1724
- initial.sequence !== sequence ||
1725
- initial.resolution !== 'active' ||
1726
- (initial.status !== 'conflict' && initial.status !== 'rejected') ||
1727
- initial.operations === undefined ||
1728
- initial.retainedRows === undefined ||
1729
- initial.operations.length !== initial.retainedRows.length ||
1730
- initial.retainedRows.length === 0)
1735
+ if (!provable(initial))
1731
1736
  return { proven: false, reason: 'outcome_unavailable' };
1732
1737
  if (!this.#transportEnabled)
1733
1738
  return { proven: false, reason: 'offline' };
@@ -1778,15 +1783,7 @@ export class SyncClient {
1778
1783
  });
1779
1784
  const delivery = snapshot.deliveries[0];
1780
1785
  const current = readCommitOutcome(this.#db, clientCommitId);
1781
- if (delivery?.status !== 'known' ||
1782
- current === undefined ||
1783
- current.sequence !== sequence ||
1784
- current.resolution !== 'active' ||
1785
- (current.status !== 'conflict' && current.status !== 'rejected') ||
1786
- current.operations === undefined ||
1787
- current.retainedRows === undefined ||
1788
- current.operations.length !== current.retainedRows.length ||
1789
- current.retainedRows.length === 0)
1786
+ if (delivery?.status !== 'known' || !provable(current))
1790
1787
  return {
1791
1788
  proven: false,
1792
1789
  reason: report.revoked.length > 0 ? 'revoked' : 'outcome_unavailable',
@@ -2895,12 +2892,53 @@ export class SyncClient {
2895
2892
  const error = classifySqliteFailure(caught).error;
2896
2893
  const completedAtMs = this.#now();
2897
2894
  const code = error.code;
2895
+ const details = typeof error === 'object' && error !== null && 'details' in error
2896
+ ? error.details
2897
+ : undefined;
2898
+ const rawCause = typeof details === 'object' &&
2899
+ details !== null &&
2900
+ 'causeKind' in details
2901
+ ? details.causeKind
2902
+ : undefined;
2903
+ let causeKind;
2904
+ switch (rawCause) {
2905
+ case 'network':
2906
+ case 'connect':
2907
+ case 'tls':
2908
+ case 'io':
2909
+ case 'request':
2910
+ case 'protocol':
2911
+ case 'timeout':
2912
+ case 'round_deadline':
2913
+ case 'aborted':
2914
+ case 'body':
2915
+ case 'status':
2916
+ case 'redirect':
2917
+ case 'unknown':
2918
+ causeKind = rawCause;
2919
+ }
2920
+ const rawStatus = typeof details === 'object' &&
2921
+ details !== null &&
2922
+ 'httpStatus' in details
2923
+ ? details.httpStatus
2924
+ : undefined;
2925
+ const httpStatus = (causeKind === 'status' ||
2926
+ causeKind === 'body' ||
2927
+ causeKind === 'redirect') &&
2928
+ typeof rawStatus === 'number' &&
2929
+ Number.isInteger(rawStatus) &&
2930
+ rawStatus >= 100 &&
2931
+ rawStatus <= 599
2932
+ ? rawStatus
2933
+ : undefined;
2898
2934
  this.#progress.update(definedObject({
2899
2935
  state: 'failed',
2900
2936
  errorCode: typeof code === 'string'
2901
2937
  ? this.#diagnosticCode(code)
2902
2938
  : 'client.unknown_failure',
2903
2939
  retryDelayMs: this.#roundRetryDelayMs,
2940
+ causeKind,
2941
+ httpStatus,
2904
2942
  }));
2905
2943
  this.#lastRound = {
2906
2944
  status: 'failed',
@@ -2910,6 +2948,8 @@ export class SyncClient {
2910
2948
  errorCode: typeof code === 'string'
2911
2949
  ? this.#diagnosticCode(code)
2912
2950
  : 'client.unknown_failure',
2951
+ ...(causeKind !== undefined ? { causeKind } : {}),
2952
+ ...(httpStatus !== undefined ? { httpStatus } : {}),
2913
2953
  };
2914
2954
  this.#emitDiagnostics();
2915
2955
  throw error;
@@ -2937,13 +2977,6 @@ export class SyncClient {
2937
2977
  deferredCommits: summary.deferredCommits ?? 0,
2938
2978
  };
2939
2979
  }
2940
- #transportFailureCode(code) {
2941
- return (code === 'transport.failed' ||
2942
- code === 'transport.unavailable' ||
2943
- code === 'sync.transport_failed' ||
2944
- code === 'client.worker_failed' ||
2945
- code === 'client.worker_restart_required');
2946
- }
2947
2980
  #diagnosticCode(code) {
2948
2981
  return code.length <= 96 && /^[a-z][a-z0-9]*(?:[._-][a-z0-9]+)+$/.test(code)
2949
2982
  ? code
@@ -13,6 +13,8 @@ export declare const MAX_DIAGNOSTIC_QUERY_FAILURES = 256;
13
13
  export type ClientDiagnosticsHostKind = 'direct' | 'worker' | 'tauri' | 'react-native';
14
14
  export type ClientDiagnosticsHostRole = 'single' | 'leader' | 'follower' | 'unknown';
15
15
  export type ClientDiagnosticsConnectivity = 'online' | 'offline' | 'unknown';
16
+ /** Bounded transport classification shared by progress and diagnostics (§1.8). */
17
+ export type TransportCauseKind = 'network' | 'connect' | 'tls' | 'io' | 'request' | 'protocol' | 'timeout' | 'round_deadline' | 'aborted' | 'body' | 'status' | 'redirect' | 'unknown';
16
18
  /**
17
19
  * SPEC §8.8: how a client treats the realtime binding for sync rounds. The
18
20
  * default is `optional`.
@@ -82,6 +84,8 @@ export type DiagnosticLastRound = {
82
84
  readonly durationMs: number;
83
85
  /** Stable code only; never arbitrary transport/server prose. */
84
86
  readonly errorCode: string;
87
+ readonly causeKind?: TransportCauseKind;
88
+ readonly httpStatus?: number;
85
89
  };
86
90
  export interface DiagnosticLastChange {
87
91
  /** Decimal u64 for JSON/IPC parity. */
@@ -1,3 +1,4 @@
1
+ import type { TransportCauseKind } from './diagnostics.js';
1
2
  /** Ephemeral sync work, independent of committed change notifications (SPEC §7.6). */
2
3
  export interface SyncProgress {
3
4
  readonly attempt: number;
@@ -11,6 +12,8 @@ export interface SyncProgress {
11
12
  readonly rowsProcessed: number;
12
13
  readonly rowsTotal?: number;
13
14
  readonly errorCode?: string;
15
+ readonly causeKind?: TransportCauseKind;
16
+ readonly httpStatus?: number;
14
17
  /** Present on `failed` when the core scheduled a background retry. */
15
18
  readonly retryDelayMs?: number;
16
19
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@syncular/client",
3
- "version": "0.52.0",
3
+ "version": "0.53.0",
4
4
  "description": "Syncular TypeScript client core — offline-first sync over SQLite (WASM/OPFS, Bun, Node)",
5
5
  "license": "Apache-2.0",
6
6
  "author": "Benjamin Kniffler",
@@ -97,10 +97,10 @@
97
97
  },
98
98
  "dependencies": {
99
99
  "@sqlite.org/sqlite-wasm": "^3.53.0-build1",
100
- "@syncular/core": "0.52.0"
100
+ "@syncular/core": "0.53.0"
101
101
  },
102
102
  "devDependencies": {
103
- "@syncular/server": "0.52.0",
103
+ "@syncular/server": "0.53.0",
104
104
  "playwright": "1.63.0",
105
105
  "@electric-sql/pglite": "^0.5.4"
106
106
  }
package/src/client.ts CHANGED
@@ -104,6 +104,7 @@ import {
104
104
  MAX_DIAGNOSTIC_QUERY_FAILURES,
105
105
  type RealtimePolicy,
106
106
  type RealtimeState,
107
+ type TransportCauseKind,
107
108
  } from './diagnostics';
108
109
  import type { EncryptionConfig } from './encryption';
109
110
  import {
@@ -2290,9 +2291,13 @@ export class SyncClient {
2290
2291
  : this.#lastRound?.status === 'succeeded'
2291
2292
  ? 'online'
2292
2293
  : this.#lastRound?.status === 'failed' &&
2293
- this.#transportFailureCode(this.#lastRound.errorCode)
2294
+ (this.#lastRound.causeKind === 'network' ||
2295
+ this.#lastRound.causeKind === 'connect')
2294
2296
  ? 'offline'
2295
- : 'unknown';
2297
+ : this.#lastRound?.status === 'failed' &&
2298
+ this.#lastRound.httpStatus !== undefined
2299
+ ? 'online'
2300
+ : 'unknown';
2296
2301
  const expectedOrder = new Map(
2297
2302
  expected.map((item, index) => [item.id, index] as const),
2298
2303
  );
@@ -2776,22 +2781,26 @@ export class SyncClient {
2776
2781
  )
2777
2782
  throw invalidRequest('maxRounds must be a positive integer');
2778
2783
  const { clientCommitId, sequence } = outcome;
2784
+ const provable = (
2785
+ candidate: CommitOutcome | undefined,
2786
+ ): candidate is CommitOutcome & {
2787
+ readonly retainedRows: readonly RetainedCommitRow[];
2788
+ } =>
2789
+ candidate !== undefined &&
2790
+ candidate.sequence === sequence &&
2791
+ candidate.resolution === 'active' &&
2792
+ (candidate.status === 'conflict' || candidate.status === 'rejected') &&
2793
+ candidate.operations !== undefined &&
2794
+ candidate.retainedRows !== undefined &&
2795
+ candidate.operations.length === candidate.retainedRows.length &&
2796
+ candidate.retainedRows.length > 0;
2779
2797
  let initial: CommitOutcome | undefined;
2780
2798
  try {
2781
2799
  initial = readCommitOutcome(this.#db, clientCommitId);
2782
2800
  } catch {
2783
2801
  return { proven: false, reason: 'snapshot_failed' };
2784
2802
  }
2785
- if (
2786
- initial === undefined ||
2787
- initial.sequence !== sequence ||
2788
- initial.resolution !== 'active' ||
2789
- (initial.status !== 'conflict' && initial.status !== 'rejected') ||
2790
- initial.operations === undefined ||
2791
- initial.retainedRows === undefined ||
2792
- initial.operations.length !== initial.retainedRows.length ||
2793
- initial.retainedRows.length === 0
2794
- )
2803
+ if (!provable(initial))
2795
2804
  return { proven: false, reason: 'outcome_unavailable' };
2796
2805
  if (!this.#transportEnabled) return { proven: false, reason: 'offline' };
2797
2806
  await this.#opChain;
@@ -2841,17 +2850,7 @@ export class SyncClient {
2841
2850
  });
2842
2851
  const delivery = snapshot.deliveries[0];
2843
2852
  const current = readCommitOutcome(this.#db, clientCommitId);
2844
- if (
2845
- delivery?.status !== 'known' ||
2846
- current === undefined ||
2847
- current.sequence !== sequence ||
2848
- current.resolution !== 'active' ||
2849
- (current.status !== 'conflict' && current.status !== 'rejected') ||
2850
- current.operations === undefined ||
2851
- current.retainedRows === undefined ||
2852
- current.operations.length !== current.retainedRows.length ||
2853
- current.retainedRows.length === 0
2854
- )
2853
+ if (delivery?.status !== 'known' || !provable(current))
2855
2854
  return {
2856
2855
  proven: false,
2857
2856
  reason:
@@ -4227,6 +4226,49 @@ export class SyncClient {
4227
4226
  const error = classifySqliteFailure(caught).error;
4228
4227
  const completedAtMs = this.#now();
4229
4228
  const code = (error as { code?: unknown }).code;
4229
+ const details =
4230
+ typeof error === 'object' && error !== null && 'details' in error
4231
+ ? error.details
4232
+ : undefined;
4233
+ const rawCause =
4234
+ typeof details === 'object' &&
4235
+ details !== null &&
4236
+ 'causeKind' in details
4237
+ ? details.causeKind
4238
+ : undefined;
4239
+ let causeKind: TransportCauseKind | undefined;
4240
+ switch (rawCause) {
4241
+ case 'network':
4242
+ case 'connect':
4243
+ case 'tls':
4244
+ case 'io':
4245
+ case 'request':
4246
+ case 'protocol':
4247
+ case 'timeout':
4248
+ case 'round_deadline':
4249
+ case 'aborted':
4250
+ case 'body':
4251
+ case 'status':
4252
+ case 'redirect':
4253
+ case 'unknown':
4254
+ causeKind = rawCause;
4255
+ }
4256
+ const rawStatus =
4257
+ typeof details === 'object' &&
4258
+ details !== null &&
4259
+ 'httpStatus' in details
4260
+ ? details.httpStatus
4261
+ : undefined;
4262
+ const httpStatus =
4263
+ (causeKind === 'status' ||
4264
+ causeKind === 'body' ||
4265
+ causeKind === 'redirect') &&
4266
+ typeof rawStatus === 'number' &&
4267
+ Number.isInteger(rawStatus) &&
4268
+ rawStatus >= 100 &&
4269
+ rawStatus <= 599
4270
+ ? rawStatus
4271
+ : undefined;
4230
4272
  this.#progress.update(
4231
4273
  definedObject({
4232
4274
  state: 'failed',
@@ -4235,6 +4277,8 @@ export class SyncClient {
4235
4277
  ? this.#diagnosticCode(code)
4236
4278
  : 'client.unknown_failure',
4237
4279
  retryDelayMs: this.#roundRetryDelayMs,
4280
+ causeKind,
4281
+ httpStatus,
4238
4282
  }),
4239
4283
  );
4240
4284
  this.#lastRound = {
@@ -4246,6 +4290,8 @@ export class SyncClient {
4246
4290
  typeof code === 'string'
4247
4291
  ? this.#diagnosticCode(code)
4248
4292
  : 'client.unknown_failure',
4293
+ ...(causeKind !== undefined ? { causeKind } : {}),
4294
+ ...(httpStatus !== undefined ? { httpStatus } : {}),
4249
4295
  };
4250
4296
  this.#emitDiagnostics();
4251
4297
  throw error;
@@ -4275,16 +4321,6 @@ export class SyncClient {
4275
4321
  };
4276
4322
  }
4277
4323
 
4278
- #transportFailureCode(code: string): boolean {
4279
- return (
4280
- code === 'transport.failed' ||
4281
- code === 'transport.unavailable' ||
4282
- code === 'sync.transport_failed' ||
4283
- code === 'client.worker_failed' ||
4284
- code === 'client.worker_restart_required'
4285
- );
4286
- }
4287
-
4288
4324
  #diagnosticCode(code: string): string {
4289
4325
  return code.length <= 96 && /^[a-z][a-z0-9]*(?:[._-][a-z0-9]+)+$/.test(code)
4290
4326
  ? code
@@ -23,6 +23,21 @@ export type ClientDiagnosticsHostRole =
23
23
  | 'follower'
24
24
  | 'unknown';
25
25
  export type ClientDiagnosticsConnectivity = 'online' | 'offline' | 'unknown';
26
+ /** Bounded transport classification shared by progress and diagnostics (§1.8). */
27
+ export type TransportCauseKind =
28
+ | 'network'
29
+ | 'connect'
30
+ | 'tls'
31
+ | 'io'
32
+ | 'request'
33
+ | 'protocol'
34
+ | 'timeout'
35
+ | 'round_deadline'
36
+ | 'aborted'
37
+ | 'body'
38
+ | 'status'
39
+ | 'redirect'
40
+ | 'unknown';
26
41
  /**
27
42
  * SPEC §8.8: how a client treats the realtime binding for sync rounds. The
28
43
  * default is `optional`.
@@ -115,6 +130,8 @@ export type DiagnosticLastRound =
115
130
  readonly durationMs: number;
116
131
  /** Stable code only; never arbitrary transport/server prose. */
117
132
  readonly errorCode: string;
133
+ readonly causeKind?: TransportCauseKind;
134
+ readonly httpStatus?: number;
118
135
  };
119
136
 
120
137
  export interface DiagnosticLastChange {
package/src/progress.ts CHANGED
@@ -1,3 +1,5 @@
1
+ import type { TransportCauseKind } from './diagnostics';
2
+
1
3
  /** Ephemeral sync work, independent of committed change notifications (SPEC §7.6). */
2
4
  export interface SyncProgress {
3
5
  readonly attempt: number;
@@ -11,6 +13,8 @@ export interface SyncProgress {
11
13
  readonly rowsProcessed: number;
12
14
  readonly rowsTotal?: number;
13
15
  readonly errorCode?: string;
16
+ readonly causeKind?: TransportCauseKind;
17
+ readonly httpStatus?: number;
14
18
  /** Present on `failed` when the core scheduled a background retry. */
15
19
  readonly retryDelayMs?: number;
16
20
  }