@durable-streams/state 0.2.1 → 0.2.2

package/bin/intent.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+// Auto-generated by @tanstack/intent setup
+// Exposes the intent end-user CLI for consumers of this library.
+// Commit this file, then add to your package.json:
+//   "bin": { "intent": "./bin/intent.js" }
+await import("@tanstack/intent/intent-library")

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@durable-streams/state",
   "description": "State change event protocol for Durable Streams",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "author": "Durable Stream contributors",
   "license": "Apache-2.0",
   "repository": {
@@ -36,23 +36,30 @@
     "./package.json": "./package.json"
   },
   "sideEffects": false,
+  "bin": {
+    "intent": "./bin/intent.js"
+  },
   "files": [
     "dist",
     "src",
     "state-protocol.schema.json",
-    "STATE-PROTOCOL.md"
+    "STATE-PROTOCOL.md",
+    "skills",
+    "bin",
+    "!skills/_artifacts"
   ],
   "dependencies": {
     "@standard-schema/spec": "^1.0.0",
-    "@durable-streams/client": "0.2.1"
+    "@durable-streams/client": "0.2.2"
   },
   "peerDependencies": {
     "@tanstack/db": ">=0.5.0"
   },
   "devDependencies": {
     "@tanstack/db": "latest",
+    "@tanstack/intent": "latest",
     "tsdown": "^0.9.0",
-    "@durable-streams/server": "0.2.1"
+    "@durable-streams/server": "0.2.2"
   },
   "engines": {
     "node": ">=18.0.0"

package/skills/state-schema/SKILL.md

@@ -0,0 +1,254 @@
+---
+name: state-schema
+description: >
+  Defining typed state schemas for @durable-streams/state. createStateSchema()
+  with CollectionDefinition (schema, type, primaryKey), Standard Schema
+  validators (Zod, Valibot, ArkType), event helpers insert/update/delete/upsert,
+  ChangeEvent and ControlEvent types, State Protocol operations, transaction
+  IDs (txid) for write confirmation. Load when defining entity types, choosing
+  a schema validator, or creating typed change events.
+type: core
+library: durable-streams
+library_version: "0.2.1"
+sources:
+  - "durable-streams/durable-streams:packages/state/src/stream-db.ts"
+  - "durable-streams/durable-streams:packages/state/src/types.ts"
+  - "durable-streams/durable-streams:packages/state/STATE-PROTOCOL.md"
+  - "durable-streams/durable-streams:packages/state/README.md"
+---
+
+# Durable Streams — State Schema
+
+Define typed entity collections over durable streams using Standard Schema
+validators. Schemas route stream events to collections, validate data, and
+provide typed helpers for creating change events.
+
+## Setup
+
+```typescript
+import { createStateSchema } from "@durable-streams/state"
+import { z } from "zod" // Use the correct import for your Zod version (e.g. "zod/v4" for Zod v4)
+
+const userSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  email: z.string().email(),
+})
+
+const messageSchema = z.object({
+  id: z.string(),
+  text: z.string(),
+  userId: z.string(),
+  timestamp: z.number(),
+})
+
+const schema = createStateSchema({
+  users: {
+    schema: userSchema,
+    type: "user", // Event type field — routes events to this collection
+    primaryKey: "id", // Field in value used as unique key
+  },
+  messages: {
+    schema: messageSchema,
+    type: "message",
+    primaryKey: "id",
+  },
+})
+```
+
+## Core Patterns
+
+### Creating typed change events
+
+Schema collections provide typed helpers for building events:
+
+```typescript
+// Insert
+const insertEvent = schema.users.insert({
+  value: { id: "1", name: "Kyle", email: "kyle@example.com" },
+})
+
+// Update
+const updateEvent = schema.users.update({
+  value: { id: "1", name: "Kyle Mathews", email: "kyle@example.com" },
+  oldValue: { id: "1", name: "Kyle", email: "kyle@example.com" },
+})
+
+// Delete
+const deleteEvent = schema.users.delete({
+  key: "1",
+  oldValue: { id: "1", name: "Kyle", email: "kyle@example.com" },
+})
+```
+
+### Using transaction IDs for confirmation
+
+```typescript
+const txid = crypto.randomUUID()
+
+const event = schema.users.insert({
+  value: { id: "1", name: "Kyle", email: "kyle@example.com" },
+  headers: { txid },
+})
+
+await stream.append(event)
+// Then use db.utils.awaitTxId(txid) in StreamDB for confirmation
+```
+
+### Choosing a schema validator
+
+Any library implementing [Standard Schema](https://standardschema.dev/) works:
+
+```typescript
+// Zod
+import { z } from "zod"
+const userSchema = z.object({ id: z.string(), name: z.string() })
+
+// Valibot
+import * as v from "valibot"
+const userSchema = v.object({ id: v.string(), name: v.string() })
+
+// Manual Standard Schema implementation
+const userSchema = {
+  "~standard": {
+    version: 1,
+    vendor: "my-app",
+    validate: (value) => {
+      if (typeof value === "object" && value !== null && "id" in value) {
+        return { value }
+      }
+      return { issues: [{ message: "Invalid user" }] }
+    },
+  },
+}
+```
+
+### Event types and type guards
+
+```typescript
+import { isChangeEvent, isControlEvent } from "@durable-streams/state"
+import type {
+  StateEvent,
+  ChangeEvent,
+  ControlEvent,
+} from "@durable-streams/state"
+
+function handleEvent(event: StateEvent) {
+  if (isChangeEvent(event)) {
+    // event.type, event.key, event.value, event.headers.operation
+    console.log(`${event.headers.operation}: ${event.type}/${event.key}`)
+  }
+  if (isControlEvent(event)) {
+    // event.headers.control: "snapshot-start" | "snapshot-end" | "reset"
+    console.log(`Control: ${event.headers.control}`)
+  }
+}
+```
+
+## Common Mistakes
+
+### CRITICAL Using primitive values instead of objects in collections
+
+Wrong:
+
+```typescript
+{ type: "count", key: "views", value: 42 }
+```
+
+Correct:
+
+```typescript
+{ type: "count", key: "views", value: { count: 42 } }
+```
+
+Collections require object values so the `primaryKey` field can be extracted. Primitive values throw during dispatch.
+
+Source: packages/state/README.md best practices
+
+### HIGH Using duplicate event types across collections
+
+Wrong:
+
+```typescript
+createStateSchema({
+  users: { schema: userSchema, type: "entity", primaryKey: "id" },
+  posts: { schema: postSchema, type: "entity", primaryKey: "id" },
+})
+```
+
+Correct:
+
+```typescript
+createStateSchema({
+  users: { schema: userSchema, type: "user", primaryKey: "id" },
+  posts: { schema: postSchema, type: "post", primaryKey: "id" },
+})
+```
+
+`createStateSchema()` throws if two collections share the same `type` string. The `type` field routes events to collections — duplicates would be ambiguous.
+
+Source: packages/state/src/stream-db.ts createStateSchema validation
+
+### HIGH Forgetting to use a Standard Schema-compatible validator
+
+Wrong:
+
+```typescript
+interface User {
+  id: string
+  name: string
+}
+createStateSchema({
+  users: { schema: User, type: "user", primaryKey: "id" }, // Not a validator!
+})
+```
+
+Correct:
+
+```typescript
+import { z } from "zod"
+const userSchema = z.object({ id: z.string(), name: z.string() })
+createStateSchema({
+  users: { schema: userSchema, type: "user", primaryKey: "id" },
+})
+```
+
+The `schema` field requires an object implementing the `~standard` interface. TypeScript interfaces and plain types are not validators.
+
+Source: packages/state/README.md Standard Schema support section
+
+### MEDIUM Using reserved collection names
+
+Wrong:
+
+```typescript
+createStateSchema({
+  actions: { schema: actionSchema, type: "action", primaryKey: "id" },
+})
+```
+
+Correct:
+
+```typescript
+createStateSchema({
+  userActions: { schema: actionSchema, type: "action", primaryKey: "id" },
+})
+```
+
+Collection names `collections`, `preload`, `close`, `utils`, and `actions` are reserved — they collide with the StreamDB API surface.
+
+Source: packages/state/src/stream-db.ts reserved name check
+
+### HIGH Tension: Schema strictness vs. prototyping speed
+
+This skill's patterns conflict with getting-started. The state package requires Standard Schema validators and typed collections, while quick prototyping favors raw JSON streams without schemas. Agents may jump to StreamDB for a simple demo when raw `stream()` with JSON mode would be faster.
+
+See also: durable-streams/getting-started/SKILL.md
+
+## See also
+
+- [stream-db](../stream-db/SKILL.md) — Wire schemas into a reactive StreamDB
+
+## Version
+
+Targets @durable-streams/state v0.2.1.

package/skills/stream-db/SKILL.md

@@ -0,0 +1,264 @@
+---
+name: stream-db
+description: >
+  Stream-backed reactive database with @durable-streams/state. createStreamDB()
+  with schema and stream options, db.preload() lazy initialization,
+  db.collections for TanStack DB collections, optimistic actions with onMutate
+  and mutationFn, db.utils.awaitTxId() for transaction confirmation, control
+  events (snapshot-start, snapshot-end, reset), db.close() cleanup, re-exported
+  TanStack DB operators (eq, gt, and, or, count, sum, avg, min, max).
+type: core
+library: durable-streams
+library_version: "0.2.1"
+requires:
+  - state-schema
+sources:
+  - "durable-streams/durable-streams:packages/state/src/stream-db.ts"
+  - "durable-streams/durable-streams:packages/state/README.md"
+---
+
+This skill builds on durable-streams/state-schema. Read it first for schema definition and event types.
+
+# Durable Streams — StreamDB
+
+Create a stream-backed reactive database that syncs structured state from a
+durable stream into TanStack DB collections. Provides reactive queries,
+optimistic actions, and transaction confirmation.
+
+## Setup
+
+```typescript
+import { createStreamDB, createStateSchema } from "@durable-streams/state"
+import { DurableStream } from "@durable-streams/client"
+import { z } from "zod"
+
+const schema = createStateSchema({
+  users: {
+    schema: z.object({ id: z.string(), name: z.string(), email: z.string() }),
+    type: "user",
+    primaryKey: "id",
+  },
+  messages: {
+    schema: z.object({ id: z.string(), text: z.string(), userId: z.string() }),
+    type: "message",
+    primaryKey: "id",
+  },
+})
+
+const db = createStreamDB({
+  streamOptions: {
+    url: "https://your-server.com/v1/stream/my-app",
+    contentType: "application/json",
+  },
+  state: schema,
+})
+
+// The stream must already exist on the server before preload().
+// Use DurableStream.connect() to attach to an existing stream,
+// or create it first if it doesn't exist yet:
+try {
+  await DurableStream.create({
+    url: "https://your-server.com/v1/stream/my-app",
+    contentType: "application/json",
+  })
+} catch (e) {
+  if (e.code !== "CONFLICT_EXISTS") throw e // Already exists is fine
+}
+
+// Connect and load initial data
+await db.preload()
+
+// Access TanStack DB collections
+const users = db.collections.users
+const messages = db.collections.messages
+```
+
+## Core Patterns
+
+### Reactive queries with TanStack DB
+
+StreamDB collections are TanStack DB collections. Use framework adapters for reactive queries:
+
+```typescript
+import { useLiveQuery } from "@tanstack/react-db"
+import { eq } from "@durable-streams/state"
+
+function UserProfile({ userId }: { userId: string }) {
+  const userQuery = useLiveQuery((q) =>
+    q
+      .from({ users: db.collections.users })
+      .where(({ users }) => eq(users.id, userId))
+      .findOne()
+  )
+
+  if (!userQuery.data) return null
+  return <div>{userQuery.data.name}</div>
+}
+```
+
+### Optimistic actions with server confirmation
+
+```typescript
+import { createStreamDB, createStateSchema } from "@durable-streams/state"
+import { z } from "zod"
+
+const schema = createStateSchema({
+  users: {
+    schema: z.object({ id: z.string(), name: z.string() }),
+    type: "user",
+    primaryKey: "id",
+  },
+})
+
+const db = createStreamDB({
+  streamOptions: {
+    url: "https://your-server.com/v1/stream/my-app",
+    contentType: "application/json",
+  },
+  state: schema,
+  actions: ({ db, stream }) => ({
+    addUser: {
+      onMutate: (user) => {
+        db.collections.users.insert(user) // Optimistic — shows immediately
+      },
+      mutationFn: async (user) => {
+        const txid = crypto.randomUUID()
+        await stream.append(
+          JSON.stringify(
+            schema.users.insert({ value: user, headers: { txid } })
+          )
+        )
+        await db.utils.awaitTxId(txid, 10000) // Wait for confirmation
+      },
+    },
+  }),
+})
+
+await db.preload()
+await db.actions.addUser({ id: "1", name: "Kyle" })
+```
+
+### Cleanup on unmount
+
+```typescript
+import { useEffect, useState } from "react"
+
+function App() {
+  const [db, setDb] = useState(null)
+
+  useEffect(() => {
+    const database = createStreamDB({ streamOptions, state: schema })
+    database.preload().then(() => setDb(database))
+    return () => database.close()  // Clean up connections and timers
+  }, [])
+
+  if (!db) return <div>Loading...</div>
+  return <Dashboard db={db} />
+}
+```
+
+### SSR: StreamDB is client-only
+
+StreamDB holds open HTTP connections and relies on browser/Node.js runtime features. In meta-frameworks (TanStack Start, Next.js, Remix), ensure StreamDB only runs on the client:
+
+```typescript
+// TanStack Start / React Router — mark the route as client-only
+export const Route = createFileRoute("/dashboard")({
+  ssr: false,
+  component: Dashboard,
+})
+```
+
+Without `ssr: false`, the server-side render will attempt to create StreamDB and fail or produce `instanceof` mismatches between server and client bundles.
+
+## Common Mistakes
+
+### CRITICAL Forgetting to call preload() before accessing data
+
+Wrong:
+
+```typescript
+const db = createStreamDB({ streamOptions, state: schema })
+const users = db.collections.users // Collections are empty!
+```
+
+Correct:
+
+```typescript
+const db = createStreamDB({ streamOptions, state: schema })
+await db.preload() // Connect and load initial data
+const users = db.collections.users
+```
+
+StreamDB creates the stream lazily. Without `preload()`, no connection is established and collections remain empty.
+
+Source: packages/state/src/stream-db.ts
+
+### HIGH Not calling close() on unmount/cleanup
+
+Wrong:
+
+```typescript
+useEffect(() => {
+  const db = createStreamDB({ streamOptions, state: schema })
+  db.preload()
+  setDb(db)
+}, [])
+```
+
+Correct:
+
+```typescript
+useEffect(() => {
+  const db = createStreamDB({ streamOptions, state: schema })
+  db.preload()
+  setDb(db)
+  return () => db.close()
+}, [])
+```
+
+StreamDB holds open HTTP connections and a 15-second health check interval. Forgetting `close()` leaks connections and timers.
+
+Source: packages/state/README.md best practices
+
+### HIGH Not using awaitTxId for critical writes
+
+Wrong:
+
+```typescript
+mutationFn: async (user) => {
+  await stream.append(JSON.stringify(schema.users.insert({ value: user })))
+  // No confirmation — optimistic state may diverge from server
+}
+```
+
+Correct:
+
+```typescript
+mutationFn: async (user) => {
+  const txid = crypto.randomUUID()
+  await stream.append(
+    JSON.stringify(schema.users.insert({ value: user, headers: { txid } }))
+  )
+  await db.utils.awaitTxId(txid, 10000) // Wait up to 10 seconds
+}
+```
+
+Without `awaitTxId`, the client has no confirmation that the write was persisted. Optimistic state may diverge if the write fails silently.
+
+Source: packages/state/README.md transaction IDs section
+
+### HIGH Tension: Catch-up completeness vs. live latency
+
+This skill's patterns conflict with reading-streams. `preload()` waits for all existing data before resolving, which may take time for large streams. Agents may forget that after `preload()`, the StreamDB is already in live-tailing mode — no additional subscription setup is needed.
+
+See also: durable-streams/reading-streams/SKILL.md
+
+## See also
+
+- [state-schema](../state-schema/SKILL.md) — Define schemas before creating a StreamDB
+- [reading-streams](../../../client/skills/reading-streams/SKILL.md) — Understanding live modes and offset management
+
+## Version
+
+Targets @durable-streams/state v0.2.1.