@furystack/entity-sync 3.0.2 → 3.0.4

package/README.md

@@ -1,83 +1,83 @@
-# @furystack/entity-sync
-
-Shared protocol types for FuryStack entity synchronization over WebSocket.
-
-## Installation
-
-```bash
-npm install @furystack/entity-sync
-# or
-yarn add @furystack/entity-sync
-```
-
-## Overview
-
-This package defines the wire protocol used between `@furystack/entity-sync-client` and `@furystack/entity-sync-service`. It exports only TypeScript types -- there is no runtime code.
-
-### Protocol Flow
-
-```
-Client                                          Server
-  │                                               │
-  │──── subscribe-entity / subscribe-collection ──▶│
-  │                                               │
-  │◀──── subscribed (snapshot or delta) ──────────│
-  │                                               │
-  │◀──── entity-added / entity-updated / ─────────│
-  │      entity-removed (incremental)             │
-  │                                               │
-  │──── unsubscribe ──────────────────────────────▶│
-```
-
-## Types
-
-### `SyncVersion`
-
-Version metadata included in all server sync messages:
-
-```ts
-type SyncVersion = {
-  seq: number // Monotonically increasing sequence number per model
-  timestamp: string // ISO 8601 timestamp
-}
-```
-
-### `SyncChangeEntry`
-
-A single entry in a delta replay, representing one change to an entity:
-
-```ts
-type SyncChangeEntry =
-  | { type: 'added'; entity: unknown; version: SyncVersion }
-  | { type: 'updated'; id: unknown; change: Record<string, unknown>; version: SyncVersion }
-  | { type: 'removed'; id: unknown; version: SyncVersion }
-```
-
-### `ClientSyncMessage`
-
-Messages sent from client to server:
-
-- `subscribe-entity` -- subscribe to a single entity by primary key (with optional `lastSeq` for delta sync)
-- `subscribe-collection` -- subscribe to a filtered, ordered collection (with optional `lastSeq`)
-- `unsubscribe` -- remove a subscription by ID
-
-### `ServerSyncMessage`
-
-Messages sent from server to client:
-
-- `subscribed` -- subscription confirmation with either a full `snapshot` or a `delta` (array of `SyncChangeEntry`)
-- `entity-added` / `entity-updated` / `entity-removed` -- incremental changes pushed to active subscriptions
-- `subscription-error` -- error response for a subscription request
-
-### `SyncState<T>`
-
-Client-side discriminated union representing the current state of a subscription:
-
-```ts
-type SyncState<T> =
-  | { status: 'connecting' }
-  | { status: 'cached'; data: T }
-  | { status: 'suspended'; data: T }
-  | { status: 'synced'; data: T }
-  | { status: 'error'; error: string }
-```
+# @furystack/entity-sync
+
+Shared protocol types for FuryStack entity synchronization over WebSocket.
+
+## Installation
+
+```bash
+npm install @furystack/entity-sync
+# or
+yarn add @furystack/entity-sync
+```
+
+## Overview
+
+This package defines the wire protocol used between `@furystack/entity-sync-client` and `@furystack/entity-sync-service`. It exports only TypeScript types -- there is no runtime code.
+
+### Protocol Flow
+
+```
+Client                                          Server
+  │                                               │
+  │──── subscribe-entity / subscribe-collection ──▶│
+  │                                               │
+  │◀──── subscribed (snapshot or delta) ──────────│
+  │                                               │
+  │◀──── entity-added / entity-updated / ─────────│
+  │      entity-removed (incremental)             │
+  │                                               │
+  │──── unsubscribe ──────────────────────────────▶│
+```
+
+## Types
+
+### `SyncVersion`
+
+Version metadata included in all server sync messages:
+
+```ts
+type SyncVersion = {
+  seq: number // Monotonically increasing sequence number per model
+  timestamp: string // ISO 8601 timestamp
+}
+```
+
+### `SyncChangeEntry`
+
+A single entry in a delta replay, representing one change to an entity:
+
+```ts
+type SyncChangeEntry =
+  | { type: 'added'; entity: unknown; version: SyncVersion }
+  | { type: 'updated'; id: unknown; change: Record<string, unknown>; version: SyncVersion }
+  | { type: 'removed'; id: unknown; version: SyncVersion }
+```
+
+### `ClientSyncMessage`
+
+Messages sent from client to server:
+
+- `subscribe-entity` -- subscribe to a single entity by primary key (with optional `lastSeq` for delta sync)
+- `subscribe-collection` -- subscribe to a filtered, ordered collection (with optional `lastSeq`)
+- `unsubscribe` -- remove a subscription by ID
+
+### `ServerSyncMessage`
+
+Messages sent from server to client:
+
+- `subscribed` -- subscription confirmation with either a full `snapshot` or a `delta` (array of `SyncChangeEntry`)
+- `entity-added` / `entity-updated` / `entity-removed` -- incremental changes pushed to active subscriptions
+- `subscription-error` -- error response for a subscription request
+
+### `SyncState<T>`
+
+Client-side discriminated union representing the current state of a subscription:
+
+```ts
+type SyncState<T> =
+  | { status: 'connecting' }
+  | { status: 'cached'; data: T }
+  | { status: 'suspended'; data: T }
+  | { status: 'synced'; data: T }
+  | { status: 'error'; error: string }
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@furystack/entity-sync",
-  "version": "3.0.2",
+  "version": "3.0.4",
   "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.1.2"
+    "@furystack/core": "^17.1.4"
   },
   "devDependencies": {
     "typescript": "^7.0.2"

package/src/client-sync-message.ts

@@ -1,28 +1,28 @@
-import type { FilterType } from '@furystack/core'
-
-/**
- * Messages sent from client to server over the WebSocket sync protocol.
- * The `model` field is derived from `constructor.name` on both sides.
- */
-export type ClientSyncMessage =
-  | {
-      type: 'subscribe-entity'
-      requestId: string
-      model: string
-      key: unknown
-      lastSeq?: string
-    }
-  | {
-      type: 'subscribe-collection'
-      requestId: string
-      model: string
-      filter?: FilterType<unknown>
-      top?: number
-      skip?: number
-      order?: Record<string, 'ASC' | 'DESC'>
-      lastSeq?: string
-    }
-  | {
-      type: 'unsubscribe'
-      subscriptionId: string
-    }
+import type { FilterType } from '@furystack/core'
+
+/**
+ * Messages sent from client to server over the WebSocket sync protocol.
+ * The `model` field is derived from `constructor.name` on both sides.
+ */
+export type ClientSyncMessage =
+  | {
+      type: 'subscribe-entity'
+      requestId: string
+      model: string
+      key: unknown
+      lastSeq?: string
+    }
+  | {
+      type: 'subscribe-collection'
+      requestId: string
+      model: string
+      filter?: FilterType<unknown>
+      top?: number
+      skip?: number
+      order?: Record<string, 'ASC' | 'DESC'>
+      lastSeq?: string
+    }
+  | {
+      type: 'unsubscribe'
+      subscriptionId: string
+    }

package/src/index.ts

@@ -1,6 +1,6 @@
-export type * from './sync-version.js'
-export type * from './sync-change-entry.js'
-export type * from './client-sync-message.js'
-export type * from './server-sync-message.js'
-export type * from './sync-state.js'
-export type { FilterType } from '@furystack/core'
+export type * from './sync-version.js'
+export type * from './sync-change-entry.js'
+export type * from './client-sync-message.js'
+export type * from './server-sync-message.js'
+export type * from './sync-state.js'
+export type { FilterType } from '@furystack/core'

package/src/server-sync-message.ts

@@ -1,64 +1,64 @@
-import type { SyncChangeEntry } from './sync-change-entry.js'
-import type { SyncVersion } from './sync-version.js'
-
-/**
- * Messages sent from server to client over the WebSocket sync protocol
- */
-export type ServerSyncMessage =
-  | {
-      type: 'subscribed'
-      requestId: string
-      subscriptionId: string
-      model: string
-      /** The primary key field name (included for collection subscriptions) */
-      primaryKey?: string
-      mode: 'snapshot'
-      data: unknown
-      /** Total count of matching entities (ignoring top/skip). Included for collection subscriptions. */
-      totalCount?: number
-      version: SyncVersion
-    }
-  | {
-      type: 'subscribed'
-      requestId: string
-      subscriptionId: string
-      model: string
-      /** The primary key field name (included for collection subscriptions) */
-      primaryKey?: string
-      mode: 'delta'
-      changes: SyncChangeEntry[]
-      /** Total count of matching entities (ignoring top/skip). Included for collection subscriptions. */
-      totalCount?: number
-      version: SyncVersion
-    }
-  | {
-      type: 'entity-added'
-      subscriptionId: string
-      entity: unknown
-      version: SyncVersion
-    }
-  | {
-      type: 'entity-updated'
-      subscriptionId: string
-      id: unknown
-      change: Record<string, unknown>
-      version: SyncVersion
-    }
-  | {
-      type: 'entity-removed'
-      subscriptionId: string
-      id: unknown
-      version: SyncVersion
-    }
-  | {
-      type: 'collection-snapshot'
-      subscriptionId: string
-      data: unknown[]
-      totalCount: number
-      version: SyncVersion
-    }
-  | {
-      type: 'subscription-error'
-      requestId: string
-      error: string
-    }
+import type { SyncChangeEntry } from './sync-change-entry.js'
+import type { SyncVersion } from './sync-version.js'
+
+/**
+ * Messages sent from server to client over the WebSocket sync protocol
+ */
+export type ServerSyncMessage =
+  | {
+      type: 'subscribed'
+      requestId: string
+      subscriptionId: string
+      model: string
+      /** The primary key field name (included for collection subscriptions) */
+      primaryKey?: string
+      mode: 'snapshot'
+      data: unknown
+      /** Total count of matching entities (ignoring top/skip). Included for collection subscriptions. */
+      totalCount?: number
+      version: SyncVersion
+    }
+  | {
+      type: 'subscribed'
+      requestId: string
+      subscriptionId: string
+      model: string
+      /** The primary key field name (included for collection subscriptions) */
+      primaryKey?: string
+      mode: 'delta'
+      changes: SyncChangeEntry[]
+      /** Total count of matching entities (ignoring top/skip). Included for collection subscriptions. */
+      totalCount?: number
+      version: SyncVersion
+    }
+  | {
+      type: 'entity-added'
+      subscriptionId: string
+      entity: unknown
+      version: SyncVersion
+    }
+  | {
+      type: 'entity-updated'
+      subscriptionId: string
+      id: unknown
+      change: Record<string, unknown>
+      version: SyncVersion
+    }
+  | {
+      type: 'entity-removed'
+      subscriptionId: string
+      id: unknown
+      version: SyncVersion
+    }
+  | {
+      type: 'collection-snapshot'
+      subscriptionId: string
+      data: unknown[]
+      totalCount: number
+      version: SyncVersion
+    }
+  | {
+      type: 'subscription-error'
+      requestId: string
+      error: string
+    }

package/src/sync-change-entry.ts

@@ -1,9 +1,9 @@
-import type { SyncVersion } from './sync-version.js'
-
-/**
- * A single entry in a delta replay, representing one change to an entity
- */
-export type SyncChangeEntry =
-  | { type: 'added'; entity: unknown; version: SyncVersion }
-  | { type: 'updated'; id: unknown; change: Record<string, unknown>; version: SyncVersion }
-  | { type: 'removed'; id: unknown; version: SyncVersion }
+import type { SyncVersion } from './sync-version.js'
+
+/**
+ * A single entry in a delta replay, representing one change to an entity
+ */
+export type SyncChangeEntry =
+  | { type: 'added'; entity: unknown; version: SyncVersion }
+  | { type: 'updated'; id: unknown; change: Record<string, unknown>; version: SyncVersion }
+  | { type: 'removed'; id: unknown; version: SyncVersion }

package/src/sync-state.ts

@@ -1,20 +1,20 @@
-/**
- * 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' }
-  | { status: 'cached'; data: T }
-  | { status: 'suspended'; data: T }
-  | { status: 'synced'; data: T }
-  | { status: 'error'; error: string }
+/**
+ * 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' }
+  | { status: 'cached'; data: T }
+  | { status: 'suspended'; data: T }
+  | { status: 'synced'; data: T }
+  | { status: 'error'; error: string }

package/src/sync-version.ts

@@ -1,18 +1,18 @@
-/**
- * Version metadata included in all server sync messages.
- *
- * `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 = {
-  /** Adapter-assigned, opaque, ordered per-topic identifier. */
-  seq: string
-  /** ISO 8601 timestamp, used for time-based changelog pruning */
-  timestamp: string
-}
+/**
+ * Version metadata included in all server sync messages.
+ *
+ * `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 = {
+  /** Adapter-assigned, opaque, ordered per-topic identifier. */
+  seq: string
+  /** ISO 8601 timestamp, used for time-based changelog pruning */
+  timestamp: string
+}