@syncular/client 0.77.4 → 0.78.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.
@@ -89,7 +89,9 @@ export declare class ReactiveClientStore {
89
89
  /** Retain a composable window working set outside React. The returned
90
90
  * handle exposes registration completion and releases only this owner. */
91
91
  retainWindow(base: WindowBase, units: readonly string[]): WindowRetention;
92
- window(base: WindowBase): ExternalStoreEntry<WindowState>;
92
+ window(base: WindowBase): ExternalStoreEntry<WindowState & {
93
+ readonly loaded: boolean;
94
+ }>;
93
95
  setWindowClaim(owner: symbol, base: WindowBase, units: readonly string[]): Promise<void>;
94
96
  /** Settles once every core window edit that drops the owner's claims ran. */
95
97
  releaseWindowClaims(owner: symbol): Promise<void>;
@@ -731,7 +731,11 @@ class WindowEntry {
731
731
  baseKey;
732
732
  cache;
733
733
  #listeners = new Set();
734
- #state = { units: [], pending: [] };
734
+ #state = {
735
+ units: [],
736
+ pending: [],
737
+ loaded: false,
738
+ };
735
739
  #generation = 0;
736
740
  #delegate;
737
741
  #running = false;
@@ -776,7 +780,7 @@ class WindowEntry {
776
780
  this.#generation += 1;
777
781
  this.#running = false;
778
782
  this.#requested = false;
779
- this.#state = { units: [], pending: [] };
783
+ this.#state = { units: [], pending: [], loaded: false };
780
784
  }
781
785
  dispose() {
782
786
  this.#listeners.clear();
@@ -800,9 +804,14 @@ class WindowEntry {
800
804
  const next = await this.store.client.windowState(this.base);
801
805
  if (generation !== this.#generation || this.#listeners.size === 0)
802
806
  return;
803
- if (canonicalValue(next.units) !== canonicalValue(this.#state.units) ||
807
+ if (!this.#state.loaded ||
808
+ canonicalValue(next.units) !== canonicalValue(this.#state.units) ||
804
809
  canonicalValue(next.pending) !== canonicalValue(this.#state.pending)) {
805
- this.#state = next;
810
+ this.#state = {
811
+ units: next.units,
812
+ pending: next.pending,
813
+ loaded: true,
814
+ };
806
815
  for (const listener of this.#listeners)
807
816
  listener();
808
817
  }
@@ -1033,9 +1042,15 @@ export class ReactiveClientStore {
1033
1042
  try {
1034
1043
  while (group.requested) {
1035
1044
  group.requested = false;
1036
- const units = [
1037
- ...new Set([...group.claims.values()].flatMap((set) => [...set])),
1038
- ].sort();
1045
+ // §7.8: a claim never releases a unit the core held before this
1046
+ // group's first edit until a claim of this store has named it.
1047
+ group.unclaimed ??= new Set((await this.client.windowState(group.base)).units);
1048
+ if (this.#windowClaims.get(baseKey) !== group)
1049
+ return;
1050
+ const claimed = new Set([...group.claims.values()].flatMap((set) => [...set]));
1051
+ for (const unit of claimed)
1052
+ group.unclaimed.delete(unit);
1053
+ const units = [...claimed, ...group.unclaimed].sort();
1039
1054
  const key = canonicalValue(units);
1040
1055
  if (key !== group.appliedKey) {
1041
1056
  group.inFlightUnits = new Set(units);
@@ -1172,6 +1187,10 @@ export class ReactiveClientStore {
1172
1187
  for (const waiter of group.waiters.splice(0)) {
1173
1188
  waiter.reject(new ClientSyncError('client.reactive_store_disposed', 'reactive store disposed'));
1174
1189
  }
1190
+ // Disposal releases the claims of this store; units it never claimed
1191
+ // stay held. A group that never read the core applied nothing.
1192
+ if (group.unclaimed === undefined)
1193
+ continue;
1175
1194
  // Releasing a window is best-effort teardown. A resource owner may have
1176
1195
  // already closed the underlying worker/native handle before React effect
1177
1196
  // cleanup runs (notably during schema-changing HMR). Do not let that
@@ -1179,7 +1198,7 @@ export class ReactiveClientStore {
1179
1198
  // interface permits a plain void return, so a closed handle may also
1180
1199
  // throw synchronously; swallow that the same way.
1181
1200
  try {
1182
- void Promise.resolve(this.client.setWindow(group.base, [])).catch(() => undefined);
1201
+ void Promise.resolve(this.client.setWindow(group.base, [...group.unclaimed])).catch(() => undefined);
1183
1202
  }
1184
1203
  catch {
1185
1204
  // Same teardown race, surfaced synchronously.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@syncular/client",
3
- "version": "0.77.4",
3
+ "version": "0.78.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",
@@ -121,11 +121,11 @@
121
121
  },
122
122
  "dependencies": {
123
123
  "@sqlite.org/sqlite-wasm": "^3.53.0-build1",
124
- "@syncular/core": "0.77.4"
124
+ "@syncular/core": "0.78.1"
125
125
  },
126
126
  "devDependencies": {
127
127
  "@electric-sql/pglite": "^0.5.4",
128
- "@syncular/server": "0.77.4",
128
+ "@syncular/server": "0.78.1",
129
129
  "playwright": "1.63.0",
130
130
  "vite": "8.3.4"
131
131
  }
@@ -889,6 +889,9 @@ interface WindowClaimGroup {
889
889
  appliedKey: string;
890
890
  appliedUnits: ReadonlySet<string>;
891
891
  inFlightUnits?: ReadonlySet<string> | undefined;
892
+ /** §7.8: units the core held before this group's first edit that no claim
893
+ * has named since. The store keeps them; undefined until read. */
894
+ unclaimed?: Set<string> | undefined;
892
895
  scheduled: boolean;
893
896
  running: boolean;
894
897
  requested: boolean;
@@ -898,9 +901,15 @@ interface WindowClaimGroup {
898
901
  }>;
899
902
  }
900
903
 
901
- class WindowEntry implements ExternalStoreEntry<WindowState> {
904
+ class WindowEntry implements ExternalStoreEntry<
905
+ WindowState & { readonly loaded: boolean }
906
+ > {
902
907
  readonly #listeners = new Set<() => void>();
903
- #state: WindowState = { units: [], pending: [] };
908
+ #state: WindowState & { readonly loaded: boolean } = {
909
+ units: [],
910
+ pending: [],
911
+ loaded: false,
912
+ };
904
913
  #generation = 0;
905
914
  #delegate: WindowEntry | undefined;
906
915
  #running = false;
@@ -913,7 +922,8 @@ class WindowEntry implements ExternalStoreEntry<WindowState> {
913
922
  private readonly cache: ObservationCache,
914
923
  ) {}
915
924
 
916
- getSnapshot = (): WindowState => this.#delegate?.getSnapshot() ?? this.#state;
925
+ getSnapshot = (): WindowState & { readonly loaded: boolean } =>
926
+ this.#delegate?.getSnapshot() ?? this.#state;
917
927
  subscribe = (listener: () => void): (() => void) => {
918
928
  const current = this.cache.activate(this.baseKey, this);
919
929
  if (current !== this) {
@@ -944,7 +954,7 @@ class WindowEntry implements ExternalStoreEntry<WindowState> {
944
954
  this.#generation += 1;
945
955
  this.#running = false;
946
956
  this.#requested = false;
947
- this.#state = { units: [], pending: [] };
957
+ this.#state = { units: [], pending: [], loaded: false };
948
958
  }
949
959
  dispose(): void {
950
960
  this.#listeners.clear();
@@ -971,10 +981,15 @@ class WindowEntry implements ExternalStoreEntry<WindowState> {
971
981
  if (generation !== this.#generation || this.#listeners.size === 0)
972
982
  return;
973
983
  if (
984
+ !this.#state.loaded ||
974
985
  canonicalValue(next.units) !== canonicalValue(this.#state.units) ||
975
986
  canonicalValue(next.pending) !== canonicalValue(this.#state.pending)
976
987
  ) {
977
- this.#state = next;
988
+ this.#state = {
989
+ units: next.units,
990
+ pending: next.pending,
991
+ loaded: true,
992
+ };
978
993
  for (const listener of this.#listeners) listener();
979
994
  }
980
995
  } while (this.#requested && this.#listeners.size > 0);
@@ -1142,7 +1157,9 @@ export class ReactiveClientStore {
1142
1157
  };
1143
1158
  }
1144
1159
 
1145
- window(base: WindowBase): ExternalStoreEntry<WindowState> {
1160
+ window(
1161
+ base: WindowBase,
1162
+ ): ExternalStoreEntry<WindowState & { readonly loaded: boolean }> {
1146
1163
  const key = windowBaseKey(base);
1147
1164
  let entry = this.#windows.get(key) as WindowEntry | undefined;
1148
1165
  if (entry === undefined) {
@@ -1233,9 +1250,17 @@ export class ReactiveClientStore {
1233
1250
  try {
1234
1251
  while (group.requested) {
1235
1252
  group.requested = false;
1236
- const units = [
1237
- ...new Set([...group.claims.values()].flatMap((set) => [...set])),
1238
- ].sort();
1253
+ // §7.8: a claim never releases a unit the core held before this
1254
+ // group's first edit until a claim of this store has named it.
1255
+ group.unclaimed ??= new Set(
1256
+ (await this.client.windowState(group.base)).units,
1257
+ );
1258
+ if (this.#windowClaims.get(baseKey) !== group) return;
1259
+ const claimed = new Set(
1260
+ [...group.claims.values()].flatMap((set) => [...set]),
1261
+ );
1262
+ for (const unit of claimed) group.unclaimed.delete(unit);
1263
+ const units = [...claimed, ...group.unclaimed].sort();
1239
1264
  const key = canonicalValue(units);
1240
1265
  if (key !== group.appliedKey) {
1241
1266
  group.inFlightUnits = new Set(units);
@@ -1385,6 +1410,9 @@ export class ReactiveClientStore {
1385
1410
  ),
1386
1411
  );
1387
1412
  }
1413
+ // Disposal releases the claims of this store; units it never claimed
1414
+ // stay held. A group that never read the core applied nothing.
1415
+ if (group.unclaimed === undefined) continue;
1388
1416
  // Releasing a window is best-effort teardown. A resource owner may have
1389
1417
  // already closed the underlying worker/native handle before React effect
1390
1418
  // cleanup runs (notably during schema-changing HMR). Do not let that
@@ -1392,9 +1420,9 @@ export class ReactiveClientStore {
1392
1420
  // interface permits a plain void return, so a closed handle may also
1393
1421
  // throw synchronously; swallow that the same way.
1394
1422
  try {
1395
- void Promise.resolve(this.client.setWindow(group.base, [])).catch(
1396
- () => undefined,
1397
- );
1423
+ void Promise.resolve(
1424
+ this.client.setWindow(group.base, [...group.unclaimed]),
1425
+ ).catch(() => undefined);
1398
1426
  } catch {
1399
1427
  // Same teardown race, surfaced synchronously.
1400
1428
  }