@furystack/entity-sync 2.0.0 → 3.0.0

package/CHANGELOG.md

@@ -1,5 +1,46 @@
 # Changelog
 
+## [3.0.0] - 2026-05-21
+
+### 📚 Documentation
+
+- Rewrote JSDoc on `SyncState` and the shared transport types to follow the new value-test guidance: dropped restate-the-type narration, kept intent / trade-offs / constraints.
+
+### 💥 Breaking Changes
+
+### `SyncVersion.seq` and `ClientSyncMessage.lastSeq` are now opaque strings
+
+`seq` is no longer a numeric counter assigned by the server — it is now an **opaque, ordered token** assigned by the underlying `@furystack/cross-node-bus` adapter (integer counters in-process, `<ms>-<n>` Redis Stream ids, etc.). Clients **must not** compare seqs lexicographically or numerically; the only safe operations are equality and round-tripping the value back to the server via `lastSeq`.
+
+**Affected types:**
+
+```typescript
+type SyncVersion = {
+  // ❌ Before
+  seq: number
+  // ✅ After
+  seq: string
+  timestamp: string
+}
+
+type ClientSyncMessage =
+  | { type: 'subscribe-entity'; /* ... */ lastSeq?: string /* was: number */ }
+  | { type: 'subscribe-collection'; /* ... */ lastSeq?: string /* was: number */ }
+// ...
+```
+
+**Impact:** Any code that does arithmetic on `seq` (e.g. `seq + 1`, `seq > previous`) breaks. Any persisted client-side state holding `lastSeq: number` becomes incompatible.
+
+**Migration:**
+
+1. Replace numeric comparisons with equality checks. Adapter-specific ordering, when needed, lives behind the bus's `compareSeq(a, b)` — do not re-implement it.
+2. Treat `seq` as a black-box token: store it, send it back, never inspect it.
+3. Persisted client caches (e.g. `SyncCacheEntry` in `@furystack/entity-sync-client`) carry `lastSeq` typed as `number` from previous versions and will not load. Either drop the cache on upgrade or write a one-shot migration that converts numeric seqs to their string representation.
+
+### ⬆️ Dependencies
+
+- Re-released to pick up the bumped workspace dependency `@furystack/core`. No source changes — version bump only.
+
 ## [2.0.0] - 2026-04-25
 
 ### 💥 Breaking Changes

package/esm/client-sync-message.d.ts

@@ -8,7 +8,7 @@ export type ClientSyncMessage = {
     requestId: string;
     model: string;
     key: unknown;
-    lastSeq?: number;
+    lastSeq?: string;
 } | {
     type: 'subscribe-collection';
     requestId: string;
@@ -17,7 +17,7 @@ export type ClientSyncMessage = {
     top?: number;
     skip?: number;
     order?: Record<string, 'ASC' | 'DESC'>;
-    lastSeq?: number;
+    lastSeq?: string;
 } | {
     type: 'unsubscribe';
     subscriptionId: string;

package/esm/sync-state.d.ts

@@ -1,5 +1,16 @@
 /**
- * Client-side sync state for a subscribed entity or collection
+ * Discriminated union over the lifecycle of a subscribed entity or
+ * collection on the client:
+ *
+ * - `connecting` — handshake in progress, no `data` yet (or first load).
+ * - `cached` — local cache hit; rendering immediately while a `delta` sync
+ *   confirms freshness.
+ * - `suspended` — connection dropped; the last-known `data` is still
+ *   served while reconnect attempts run in the background.
+ * - `synced` — server confirmed our seq matches; `data` is authoritative.
+ * - `error` — terminal: subscription rejected; `error` carries the reason.
+ *
+ * Discriminate on `status` to narrow.
  */
 export type SyncState<T> = {
     status: 'connecting';

package/esm/sync-state.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sync-state.d.ts","sourceRoot":"","sources":["../src/sync-state.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,MAAM,SAAS,CAAC,CAAC,IACnB;IAAE,MAAM,EAAE,YAAY,CAAA;CAAE,GACxB;IAAE,MAAM,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE,CAAC,CAAA;CAAE,GAC7B;IAAE,MAAM,EAAE,WAAW,CAAC;IAAC,IAAI,EAAE,CAAC,CAAA;CAAE,GAChC;IAAE,MAAM,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE,CAAC,CAAA;CAAE,GAC7B;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAA"}
+{"version":3,"file":"sync-state.d.ts","sourceRoot":"","sources":["../src/sync-state.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,SAAS,CAAC,CAAC,IACnB;IAAE,MAAM,EAAE,YAAY,CAAA;CAAE,GACxB;IAAE,MAAM,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE,CAAC,CAAA;CAAE,GAC7B;IAAE,MAAM,EAAE,WAAW,CAAC;IAAC,IAAI,EAAE,CAAC,CAAA;CAAE,GAChC;IAAE,MAAM,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE,CAAC,CAAA;CAAE,GAC7B;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAA"}

package/esm/sync-version.d.ts

@@ -1,10 +1,18 @@
 /**
  * Version metadata included in all server sync messages.
- * Every change to a model increments the seq and records a timestamp.
+ *
+ * `seq` is an **opaque, ordered token** assigned by the server's underlying
+ * cross-node bus adapter — the broadcaster never invents the value, it only
+ * forwards what the bus stamps on each message. Clients **must not** compare
+ * seqs lexicographically or numerically: the only safe operations are
+ * round-tripping the value back to the server (via `lastSeq` on
+ * `ClientSyncMessage`) and equality. The string encoding lets adapters use
+ * native id formats — e.g. integer counters in-process, `<ms>-<n>` Redis
+ * Stream ids — without a translation layer.
  */
 export type SyncVersion = {
-    /** Monotonically increasing sequence number per model */
-    seq: number;
+    /** Adapter-assigned, opaque, ordered per-topic identifier. */
+    seq: string;
     /** ISO 8601 timestamp, used for time-based changelog pruning */
     timestamp: string;
 };

package/esm/sync-version.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sync-version.d.ts","sourceRoot":"","sources":["../src/sync-version.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,MAAM,WAAW,GAAG;IACxB,yDAAyD;IACzD,GAAG,EAAE,MAAM,CAAA;IACX,gEAAgE;IAChE,SAAS,EAAE,MAAM,CAAA;CAClB,CAAA"}
+{"version":3,"file":"sync-version.d.ts","sourceRoot":"","sources":["../src/sync-version.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,WAAW,GAAG;IACxB,8DAA8D;IAC9D,GAAG,EAAE,MAAM,CAAA;IACX,gEAAgE;IAChE,SAAS,EAAE,MAAM,CAAA;CAClB,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@furystack/entity-sync",
-  "version": "2.0.0",
+  "version": "3.0.0",
   "description": "Shared protocol types for FuryStack entity synchronization",
   "type": "module",
   "scripts": {
@@ -37,7 +37,7 @@
   },
   "homepage": "https://github.com/furystack/furystack",
   "dependencies": {
-    "@furystack/core": "^17.0.0"
+    "@furystack/core": "^17.1.0"
   },
   "devDependencies": {
     "typescript": "^6.0.3"

package/src/client-sync-message.ts

@@ -10,7 +10,7 @@ export type ClientSyncMessage =
       requestId: string
       model: string
       key: unknown
-      lastSeq?: number
+      lastSeq?: string
     }
   | {
       type: 'subscribe-collection'
@@ -20,7 +20,7 @@ export type ClientSyncMessage =
       top?: number
       skip?: number
       order?: Record<string, 'ASC' | 'DESC'>
-      lastSeq?: number
+      lastSeq?: string
     }
   | {
       type: 'unsubscribe'

package/src/sync-state.ts

@@ -1,5 +1,16 @@
 /**
- * Client-side sync state for a subscribed entity or collection
+ * Discriminated union over the lifecycle of a subscribed entity or
+ * collection on the client:
+ *
+ * - `connecting` — handshake in progress, no `data` yet (or first load).
+ * - `cached` — local cache hit; rendering immediately while a `delta` sync
+ *   confirms freshness.
+ * - `suspended` — connection dropped; the last-known `data` is still
+ *   served while reconnect attempts run in the background.
+ * - `synced` — server confirmed our seq matches; `data` is authoritative.
+ * - `error` — terminal: subscription rejected; `error` carries the reason.
+ *
+ * Discriminate on `status` to narrow.
  */
 export type SyncState<T> =
   | { status: 'connecting' }

package/src/sync-version.ts

@@ -1,10 +1,18 @@
 /**
  * Version metadata included in all server sync messages.
- * Every change to a model increments the seq and records a timestamp.
+ *
+ * `seq` is an **opaque, ordered token** assigned by the server's underlying
+ * cross-node bus adapter — the broadcaster never invents the value, it only
+ * forwards what the bus stamps on each message. Clients **must not** compare
+ * seqs lexicographically or numerically: the only safe operations are
+ * round-tripping the value back to the server (via `lastSeq` on
+ * `ClientSyncMessage`) and equality. The string encoding lets adapters use
+ * native id formats — e.g. integer counters in-process, `<ms>-<n>` Redis
+ * Stream ids — without a translation layer.
  */
 export type SyncVersion = {
-  /** Monotonically increasing sequence number per model */
-  seq: number
+  /** Adapter-assigned, opaque, ordered per-topic identifier. */
+  seq: string
   /** ISO 8601 timestamp, used for time-based changelog pruning */
   timestamp: string
 }