feat: add SSE live transport (live-client + live-server)

- src/live-client.ts: createLiveClient (EventSource + auto-reconnect),
  liveCollectionOptions, useLiveCollection, per-record/field subscription
  filters, in-memory subscriber queue
- src/live-server.ts: createLiveEventBus, createLiveSseHandler (30s heartbeat),
  createLiveControlHandler, per-connection handle, field-level intersection
  optimization
- new subpaths: ./live-client, ./live-server
- 41 new tests (16 client + 20 server + 5 integration); 180 total
- bump to 0.0.4

Author: doeixd

CHANGELOG.md

@@ -5,6 +5,24 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.0.4] - 2026-06-03
+
+### Added
+
+- First-party SSE live transport (subpath exports `./live-client` and `./live-server`)
+  - `createLiveClient({ url, controlUrl?, eventSourceCtor?, fetch?, reconnect?, ... })` — one per-app EventSource with automatic exponential-backoff reconnect
+  - `liveCollectionOptions<TItem>({ id?, entity, getKey?, live, initialFetch?, fields?, onDeleteMissing? })` — TanStack DB `Collection` bound to a live stream
+  - `useLiveCollection<TItem, View>({ collection, view? })` — reactive hook with view projection
+  - Per-connection field-level subscription filters (`fields ∩ changed` intersection)
+  - Per-record subscription filters (`subscribe(entity, cb, { id })`)
+  - In-memory bounded subscriber queue with `__dropped` accounting
+  - Resumable via `Last-Event-ID` (exposed, ready for durable backends)
+  - `createLiveEventBus({ maxQueueSize? })` — server-side event multiplexer
+  - `createLiveSseHandler(bus)(request)` — `text/event-stream` response with 30s heartbeat
+  - `createLiveControlHandler(bus)(request)` — POST JSON for control messages (subscribe/unsubscribe)
+  - Per-connection handle for server-pushed edge/invalidate events
+- Tests: 41 new tests (16 live-client, 20 live-server, 5 integration) — total 180
+
 ## [0.0.3] - 2026-06-03
 
 ### Added
@@ -54,3 +72,4 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 [0.0.3]: https://github.com/doeixd/tanstackstart-db/releases/tag/v0.0.3
 [0.0.2]: https://github.com/doeixd/tanstackstart-db/releases/tag/v0.0.2
 [0.0.1]: https://github.com/doeixd/tanstackstart-db/releases/tag/v0.0.1
+[0.0.4]: https://github.com/doeixd/tanstackstart-db/releases/tag/v0.0.4

README.md

@@ -579,6 +579,82 @@ The collection exposes all pagination primitives via `collection.utils`:
 - `getState()` - get the current pagination state snapshot
 - `getCollection()` - get the underlying collection instance
 
+## Live transport (SSE)
+
+`@doeixd/tanstackstart-db/live-client` and `@doeixd/tanstackstart-db/live-server`
+provide a complete client/server transport for streaming entity updates over
+Server-Sent Events. The client opens a single EventSource per app; the server
+multiplexes entity events across connections with a per-connection bounded
+queue, control messages for subscribe/unsubscribe, and per-record + per-field
+filtering.
+
+```ts
+// Server (e.g. a TanStack Start API route)
+import {
+  createLiveEventBus,
+  createLiveSseHandler,
+  createLiveControlHandler,
+} from "@doeixd/tanstackstart-db/live-server";
+
+const bus = createLiveEventBus();
+
+export const GET = createLiveSseHandler(bus);
+export const POST = createLiveControlHandler(bus);
+
+// Push a server-side event
+bus.update("Post", "1", { changed: ["likes"], value: { id: "1", likes: 99 } });
+```
+
+```tsx
+// Client
+import { createCollection } from "@tanstack/db";
+import {
+  createLiveClient,
+  liveCollectionOptions,
+  useLiveCollection,
+} from "@doeixd/tanstackstart-db/live-client";
+
+const live = createLiveClient({ url: "/api/live" });
+
+const posts = createCollection(
+  liveCollectionOptions<Post>({
+    id: "posts",
+    entity: "Post",
+    live,
+    initialFetch: () => fetch("/api/posts").then((r) => r.json()),
+  }),
+);
+
+function PostList() {
+  const list = useLiveCollection({ collection: posts, view: PostView });
+  return (
+    <ul>
+      {list.map((p) => (
+        <li key={p.id}>{p.title}</li>
+      ))}
+    </ul>
+  );
+}
+```
+
+Field-level subscription:
+
+```ts
+// Only receive "likes" changes for the Post entity
+live.subscribe(
+  "Post",
+  (event) => {
+    /* ... */
+  },
+  { fields: ["likes"] },
+);
+```
+
+The wire format is SSE `event: entity.create|update|delete|invalid` with JSON
+`data:` and an optional `id:` (used as `Last-Event-ID` for resumable streams).
+Control messages are POSTed to `${url}/control` (or `controlUrl` if provided)
+as JSON: `{ type: "subscribe"|"unsubscribe", connectionId, entity, id?, fields? }`.
+
 ## DB file routes
 
 The main application-level value of the React entrypoint is its DB file-route
@@ -800,6 +876,9 @@ expect(data.post.title).toBe("Hello");
 @doeixd/tanstackstart-db/react
 @doeixd/tanstackstart-db/server
 @doeixd/tanstackstart-db/testing
+@doeixd/tanstackstart-db/pagination
+@doeixd/tanstackstart-db/live-client
+@doeixd/tanstackstart-db/live-server
 @doeixd/tanstackstart-db/query-collection
 @doeixd/tanstackstart-db/local-storage-collection
 @doeixd/tanstackstart-db/sync-collection

package.json

@@ -1,17 +1,21 @@
 {
   "name": "@doeixd/tanstackstart-db",
-  "version": "0.0.3",
+  "version": "0.0.4",
   "description": "Typed schema, view, query, action, route, and hydration helpers for TanStack DB.",
   "keywords": [
     "crud",
     "cursor",
     "database",
+    "event-source",
     "hydration",
     "infinite-scroll",
+    "live",
     "optimistic",
     "pagination",
     "react",
+    "realtime",
     "schema",
+    "sse",
     "ssr",
     "tanstack",
     "tanstack-db",
@@ -34,6 +38,8 @@
   "sideEffects": false,
   "exports": {
     ".": "./dist/index.mjs",
+    "./live-client": "./dist/live-client.mjs",
+    "./live-server": "./dist/live-server.mjs",
     "./local-storage-collection": "./dist/local-storage-collection.mjs",
     "./pagination": "./dist/pagination.mjs",
     "./query-collection": "./dist/query-collection.mjs",