@syncular/client 0.53.0 → 0.53.1

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/dist/client.d.ts CHANGED
@@ -12,6 +12,7 @@ import { type SyncProgress, type SyncProgressListener } from './progress.js';
12
12
  import { type ScopeMap, type WakeReason } from '@syncular/core';
13
13
  import { type BlobRef, type BlobTransport, type CachedBlob } from './blob.js';
14
14
  import type { ClientDatabase, SqlRow, SqlValue } from './database.js';
15
+ import type { DevtoolsRegistrar } from './devtools.js';
15
16
  import { type ClientDiagnosticsListener, type ClientDiagnosticsRequest, type ClientDiagnosticsSnapshot, type RealtimePolicy } from './diagnostics.js';
16
17
  import type { EncryptionConfig } from './encryption.js';
17
18
  import { type ClientChangeListener, type CommandResult, type InvalidationListener, type LocalRevision, type SyncIntent, type SyncStatusSnapshot } from './invalidation.js';
@@ -146,6 +147,8 @@ export interface SyncClientLimits {
146
147
  readonly maxPushRequestBytes?: number;
147
148
  }
148
149
  export interface SyncClientConfig {
150
+ /** Explicit development console registry; absent means no registration. */
151
+ readonly devtools?: DevtoolsRegistrar;
149
152
  readonly transportEnabled?: boolean;
150
153
  /** Keep rejected/conflicting local intent visible until explicit resolution. */
151
154
  readonly retainFailedCommits?: boolean;
package/dist/client.js CHANGED
@@ -19,7 +19,6 @@ import { EncryptError } from '@syncular/core';
19
19
  import { EncodeError } from '@syncular/core';
20
20
  import { applyCommitFrame, applyRowsSegment, applySqliteSegment, deleteLocalRow, deleteScopedRows, localScopePredicate, evictScopedRows, yieldToHost, upsertLocalRow, } from './apply.js';
21
21
  import { clearPendingUpload, computeBlobId, deleteUnreferencedCachedBlobs, enforceBlobCacheCap, ensureBlobSchema, getCachedBlob, listPendingUploads, parseBlobRef, putCachedBlob, recordPendingUpload, schemaHasBlobs, serializeBlobRef, } from './blob.js';
22
- import { registerDevtools } from './devtools.js';
23
22
  import { CLIENT_DIAGNOSTICS_VERSION, ClientDiagnosticsEmitter, MAX_DIAGNOSTIC_DOMAINS, MAX_DIAGNOSTIC_EXPECTED_SUBSCRIPTIONS, MAX_DIAGNOSTIC_QUERY_FAILURES, } from './diagnostics.js';
24
23
  import { ClientSyncError, invalidRequest, classifySqliteFailure, REALTIME_LOST_CODE, RealtimeUnavailableError, } from './errors.js';
25
24
  import { ChangeAccumulator, ChangeEmitter, InvalidationEmitter, invalidationFromChange, } from './invalidation.js';
@@ -450,7 +449,7 @@ export class SyncClient {
450
449
  this.#emitSyncIntent({ kind: 'interactive' });
451
450
  }
452
451
  // Console introspection is a no-op outside a dev page.
453
- this.#devtoolsUnregister = registerDevtools({
452
+ this.#devtoolsUnregister = this.#config.devtools?.({
454
453
  kind: 'client',
455
454
  ref: this,
456
455
  clientId: () => this.#clientId,
@@ -1,6 +1,6 @@
1
1
  /**
2
- * The client-side introspection registry: every live
3
- * `SyncClient` / `SyncClientHandle` on a page registers itself on
2
+ * The optional client-side introspection registry: a configured
3
+ * `SyncClient` / `SyncClientHandle` on a development page registers itself on
4
4
  * `globalThis.__SYNCULAR__`, so a first integration debugs from the console
5
5
  * instead of hand-exposing the client:
6
6
  *
@@ -11,11 +11,9 @@
11
11
  * // last invalidation
12
12
  * __SYNCULAR__.clients[0].ref // the client itself — full API
13
13
  *
14
- * Gated to development: the registry installs only where a `window` exists
15
- * (worker cores register through their page-side handle) and NODE_ENV is
16
- * anything except `'production'` (bundlers statically replace it, so
17
- * production builds skip installation; environments without `process` are
18
- * treated as dev). Cost when gated off: one function call per client.
14
+ * The host explicitly supplies `registerDevtools` in its client config. The
15
+ * registry also requires a development or test environment signal and a
16
+ * `window`. A browser without a development signal leaves it disabled.
19
17
  */
20
18
  import type { InvalidationListener } from './invalidation.js';
21
19
  /** What a registrant supplies — plain lambdas over its own surface. */
@@ -34,6 +32,8 @@ export interface DevtoolsRegistration {
34
32
  readonly upgrading: () => Promise<boolean>;
35
33
  readonly onInvalidate: (listener: InvalidationListener) => () => void;
36
34
  }
35
+ /** Explicit development registry supplied to a client or worker handle. */
36
+ export type DevtoolsRegistrar = (registration: DevtoolsRegistration) => () => void;
37
37
  /** One live entry on the registry (a registration plus tracked state). */
38
38
  export interface DevtoolsEntry extends DevtoolsRegistration {
39
39
  /** The most recent invalidation event, timestamped (epoch ms). */
package/dist/devtools.js CHANGED
@@ -4,7 +4,13 @@ function registryHost() {
4
4
  const g = globalThis;
5
5
  if (g.window === undefined)
6
6
  return undefined;
7
- if (g.process?.env?.NODE_ENV === 'production')
7
+ if (typeof process !== 'undefined' && process.env.NODE_ENV === 'production')
8
+ return undefined;
9
+ if (!((typeof import.meta.env !== 'undefined' &&
10
+ import.meta.env.DEV === true) ||
11
+ (typeof process !== 'undefined' &&
12
+ (process.env.NODE_ENV === 'development' ||
13
+ process.env.NODE_ENV === 'test'))))
8
14
  return undefined;
9
15
  return g;
10
16
  }
@@ -27,6 +27,7 @@ import type { WakeReason } from '@syncular/core';
27
27
  import type { BlobRef, CachedBlob } from './blob.js';
28
28
  import type { ConflictRecord, CurrentBaseProof, MutationInput, PresencePeer, QueryReadSpec, QuerySnapshot, RejectionRecord, SecurityLifecycle, SnapshotRead, SnapshotReadRequest, SubscribeInput, SyncClientConfig, SyncClientLimits, SyncSummary, SyncIdleOptions, SyncIdleResult, WindowState } from './client.js';
29
29
  import type { SqlRow, SqlValue } from './database.js';
30
+ import type { DevtoolsRegistrar } from './devtools.js';
30
31
  import { ClientDiagnosticsEmitter, type ClientDiagnosticsListener, type ClientDiagnosticsRequest, type ClientDiagnosticsSnapshot, type RealtimePolicy } from './diagnostics.js';
31
32
  import type { EncryptionKeyringConfig } from './encryption.js';
32
33
  import { ClientSyncError } from './errors.js';
@@ -65,6 +66,8 @@ export declare function isolatedReplicaNames(options: {
65
66
  readonly replicaId: string;
66
67
  }): IsolatedReplicaNames;
67
68
  export interface SyncClientHandleConfig {
69
+ /** Explicit development console registry for this page's handle. */
70
+ readonly devtools?: DevtoolsRegistrar;
68
71
  /**
69
72
  * Spawns the worker running `startSyncWorker()` (a factory so bundlers
70
73
  * see `new Worker(new URL(...))` at the call site, and so no worker is
@@ -193,6 +196,7 @@ export declare class SyncClientHandle implements PromiseMethods<WorkerApi> {
193
196
  leadershipListeners?: Set<(state: LeadershipState) => void>;
194
197
  unreachableListeners?: Set<(event: LeaderUnreachableEvent) => void>;
195
198
  leadership?: LeadershipState;
199
+ devtools?: DevtoolsRegistrar;
196
200
  });
197
201
  /**
198
202
  * @internal — apply a leadership snapshot in place: a promotion flips the
@@ -1,5 +1,4 @@
1
1
  import { ProgressEmitter, } from './progress.js';
2
- import { registerDevtools } from './devtools.js';
3
2
  import { ClientDiagnosticsEmitter, withClientDiagnosticsHost, } from './diagnostics.js';
4
3
  import { ClientSyncError } from './errors.js';
5
4
  import { ChangeEmitter, InvalidationEmitter, invalidationFromChange, } from './invalidation.js';
@@ -107,7 +106,7 @@ export class SyncClientHandle {
107
106
  this.#leadershipListeners = internals.leadershipListeners ?? new Set();
108
107
  this.#unreachableListeners = internals.unreachableListeners ?? new Set();
109
108
  // Console introspection is a no-op outside a dev page.
110
- this.#devtoolsUnregister = registerDevtools({
109
+ this.#devtoolsUnregister = internals.devtools?.({
111
110
  kind: 'handle',
112
111
  ref: this,
113
112
  clientId: () => this.#clientId,
@@ -442,7 +441,7 @@ export class SyncClientHandle {
442
441
  return;
443
442
  this.#closed = true;
444
443
  this.#progress.clear();
445
- this.#devtoolsUnregister();
444
+ this.#devtoolsUnregister?.();
446
445
  await this.#tabs?.close();
447
446
  if (this.#core !== undefined) {
448
447
  const core = this.#core;
@@ -660,6 +659,9 @@ export async function createSyncClientHandle(config) {
660
659
  roleListeners,
661
660
  leadershipListeners,
662
661
  unreachableListeners,
662
+ ...(resolvedConfig.devtools !== undefined
663
+ ? { devtools: resolvedConfig.devtools }
664
+ : {}),
663
665
  };
664
666
  if (resolvedConfig.multiTab === false) {
665
667
  // Single-tab contract: the leader runs its core with no channel; a losing
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@syncular/client",
3
- "version": "0.53.0",
3
+ "version": "0.53.1",
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,11 +97,12 @@
97
97
  },
98
98
  "dependencies": {
99
99
  "@sqlite.org/sqlite-wasm": "^3.53.0-build1",
100
- "@syncular/core": "0.53.0"
100
+ "@syncular/core": "0.53.1"
101
101
  },
102
102
  "devDependencies": {
103
- "@syncular/server": "0.53.0",
103
+ "@syncular/server": "0.53.1",
104
104
  "playwright": "1.63.0",
105
- "@electric-sql/pglite": "^0.5.4"
105
+ "@electric-sql/pglite": "^0.5.4",
106
+ "vite": "8.3.4"
106
107
  }
107
108
  }
package/src/client.ts CHANGED
@@ -86,7 +86,7 @@ import {
86
86
  serializeBlobRef,
87
87
  } from './blob';
88
88
  import type { ClientDatabase, SqlRow, SqlValue } from './database';
89
- import { registerDevtools } from './devtools';
89
+ import type { DevtoolsRegistrar } from './devtools';
90
90
  import {
91
91
  CLIENT_DIAGNOSTICS_VERSION,
92
92
  ClientDiagnosticsEmitter,
@@ -417,6 +417,8 @@ export interface SyncClientLimits {
417
417
  }
418
418
 
419
419
  export interface SyncClientConfig {
420
+ /** Explicit development console registry; absent means no registration. */
421
+ readonly devtools?: DevtoolsRegistrar;
420
422
  readonly transportEnabled?: boolean;
421
423
  /** Keep rejected/conflicting local intent visible until explicit resolution. */
422
424
  readonly retainFailedCommits?: boolean;
@@ -1252,7 +1254,7 @@ export class SyncClient {
1252
1254
  this.#emitSyncIntent({ kind: 'interactive' });
1253
1255
  }
1254
1256
  // Console introspection is a no-op outside a dev page.
1255
- this.#devtoolsUnregister = registerDevtools({
1257
+ this.#devtoolsUnregister = this.#config.devtools?.({
1256
1258
  kind: 'client',
1257
1259
  ref: this,
1258
1260
  clientId: () => this.#clientId,
package/src/devtools.ts CHANGED
@@ -1,6 +1,6 @@
1
1
  /**
2
- * The client-side introspection registry: every live
3
- * `SyncClient` / `SyncClientHandle` on a page registers itself on
2
+ * The optional client-side introspection registry: a configured
3
+ * `SyncClient` / `SyncClientHandle` on a development page registers itself on
4
4
  * `globalThis.__SYNCULAR__`, so a first integration debugs from the console
5
5
  * instead of hand-exposing the client:
6
6
  *
@@ -11,11 +11,9 @@
11
11
  * // last invalidation
12
12
  * __SYNCULAR__.clients[0].ref // the client itself — full API
13
13
  *
14
- * Gated to development: the registry installs only where a `window` exists
15
- * (worker cores register through their page-side handle) and NODE_ENV is
16
- * anything except `'production'` (bundlers statically replace it, so
17
- * production builds skip installation; environments without `process` are
18
- * treated as dev). Cost when gated off: one function call per client.
14
+ * The host explicitly supplies `registerDevtools` in its client config. The
15
+ * registry also requires a development or test environment signal and a
16
+ * `window`. A browser without a development signal leaves it disabled.
19
17
  */
20
18
  import type { InvalidationEvent, InvalidationListener } from './invalidation';
21
19
 
@@ -36,6 +34,11 @@ export interface DevtoolsRegistration {
36
34
  readonly onInvalidate: (listener: InvalidationListener) => () => void;
37
35
  }
38
36
 
37
+ /** Explicit development registry supplied to a client or worker handle. */
38
+ export type DevtoolsRegistrar = (
39
+ registration: DevtoolsRegistration,
40
+ ) => () => void;
41
+
39
42
  /** One live entry on the registry (a registration plus tracked state). */
40
43
  export interface DevtoolsEntry extends DevtoolsRegistration {
41
44
  /** The most recent invalidation event, timestamped (epoch ms). */
@@ -55,12 +58,20 @@ const KEY = '__SYNCULAR__';
55
58
 
56
59
  /** The page global to install on, or undefined when gated off. */
57
60
  function registryHost(): Record<string, unknown> | undefined {
58
- const g = globalThis as Record<string, unknown> & {
59
- window?: unknown;
60
- process?: { env?: { NODE_ENV?: string } };
61
- };
61
+ const g = globalThis as Record<string, unknown> & { window?: unknown };
62
62
  if (g.window === undefined) return undefined;
63
- if (g.process?.env?.NODE_ENV === 'production') return undefined;
63
+ if (typeof process !== 'undefined' && process.env.NODE_ENV === 'production')
64
+ return undefined;
65
+ if (
66
+ !(
67
+ (typeof import.meta.env !== 'undefined' &&
68
+ (import.meta.env.DEV as boolean | string | undefined) === true) ||
69
+ (typeof process !== 'undefined' &&
70
+ (process.env.NODE_ENV === 'development' ||
71
+ process.env.NODE_ENV === 'test'))
72
+ )
73
+ )
74
+ return undefined;
64
75
  return g;
65
76
  }
66
77
 
@@ -49,7 +49,7 @@ import type {
49
49
  WindowState,
50
50
  } from './client';
51
51
  import type { SqlRow, SqlValue } from './database';
52
- import { registerDevtools } from './devtools';
52
+ import type { DevtoolsRegistrar } from './devtools';
53
53
  import {
54
54
  ClientDiagnosticsEmitter,
55
55
  type ClientDiagnosticsListener,
@@ -178,6 +178,8 @@ export function isolatedReplicaNames(options: {
178
178
  }
179
179
 
180
180
  export interface SyncClientHandleConfig {
181
+ /** Explicit development console registry for this page's handle. */
182
+ readonly devtools?: DevtoolsRegistrar;
181
183
  /**
182
184
  * Spawns the worker running `startSyncWorker()` (a factory so bundlers
183
185
  * see `new Worker(new URL(...))` at the call site, and so no worker is
@@ -337,7 +339,7 @@ export class SyncClientHandle implements PromiseMethods<WorkerApi> {
337
339
  readonly #roleListeners: Set<(role: HandleRole) => void>;
338
340
  readonly #leadershipListeners: Set<(state: LeadershipState) => void>;
339
341
  readonly #unreachableListeners: Set<(event: LeaderUnreachableEvent) => void>;
340
- readonly #devtoolsUnregister: () => void;
342
+ readonly #devtoolsUnregister: (() => void) | undefined;
341
343
  #closed = false;
342
344
 
343
345
  /** @internal — use {@link createSyncClientHandle}. */
@@ -355,6 +357,7 @@ export class SyncClientHandle implements PromiseMethods<WorkerApi> {
355
357
  leadershipListeners?: Set<(state: LeadershipState) => void>;
356
358
  unreachableListeners?: Set<(event: LeaderUnreachableEvent) => void>;
357
359
  leadership?: LeadershipState;
360
+ devtools?: DevtoolsRegistrar;
358
361
  }) {
359
362
  this.#role = internals.role;
360
363
  this.#clientId = internals.clientId;
@@ -380,7 +383,7 @@ export class SyncClientHandle implements PromiseMethods<WorkerApi> {
380
383
  this.#leadershipListeners = internals.leadershipListeners ?? new Set();
381
384
  this.#unreachableListeners = internals.unreachableListeners ?? new Set();
382
385
  // Console introspection is a no-op outside a dev page.
383
- this.#devtoolsUnregister = registerDevtools({
386
+ this.#devtoolsUnregister = internals.devtools?.({
384
387
  kind: 'handle',
385
388
  ref: this,
386
389
  clientId: () => this.#clientId,
@@ -832,7 +835,7 @@ export class SyncClientHandle implements PromiseMethods<WorkerApi> {
832
835
  if (this.#closed) return;
833
836
  this.#closed = true;
834
837
  this.#progress.clear();
835
- this.#devtoolsUnregister();
838
+ this.#devtoolsUnregister?.();
836
839
  await this.#tabs?.close();
837
840
  if (this.#core !== undefined) {
838
841
  const core = this.#core;
@@ -1076,6 +1079,9 @@ export async function createSyncClientHandle(
1076
1079
  roleListeners,
1077
1080
  leadershipListeners,
1078
1081
  unreachableListeners,
1082
+ ...(resolvedConfig.devtools !== undefined
1083
+ ? { devtools: resolvedConfig.devtools }
1084
+ : {}),
1079
1085
  };
1080
1086
 
1081
1087
  if (resolvedConfig.multiTab === false) {