StateFlow.WTF

Distributed TypeScript workflows on xSync replicated actor logs. Define workflows once, run them across browsers, Next.js APIs, and Node workers, with capability-based placement, configurable claim policies, and S3-backed durable state.

Install

pnpm add @decoperations/stateflow-core \
        @decoperations/stateflow-runtime \
        @decoperations/stateflow-provider-local \
        @decoperations/xsync-client

Define a workflow

import { defineWorkflow, defineStep, link } from "@decoperations/stateflow-core"

export const demo = defineWorkflow({
  id: "demo.uppercase",
  version: "1.0.0",
  steps: {
    uppercase: defineStep({
      id: "uppercase",
      type: "text.uppercase",
      sideEffects: { kind: "pure", idempotencyRequired: false },
      claim: { mode: "optimistic-idempotent", duplicatePolicy: "first-valid-wins" },
    }),
  },
  links: [],
})

Run it on any TypeScript runtime

import { createXSync } from "@decoperations/xsync-client"
import { createStateFlowRuntime } from "@decoperations/stateflow-runtime"
import { detectLocalNode } from "@decoperations/stateflow-provider-local"
import { flowRunView } from "@decoperations/stateflow-core"

const client = await createXSync({ views: { flowRun: flowRunView } })
const runtime = createStateFlowRuntime({ node: detectLocalNode({ id: "local" }) })

runtime.register("text.uppercase", async (_ctx, input: string) => input.toUpperCase())

const run = await runtime.start({ client, workflow: demo, input: "hello" })
for await (const snap of run.observe()) console.log(snap.status, snap.steps)

What StateFlow gets from xSync (and doesn't reinvent)

• Signed events, multi-writer DAG, and Merkle replication.
• Pluggable stores: memory, indexeddb, fs, sqlite, s3worm.
• Pluggable transports: broadcast-channel, websocket, http, sse.
• The workQueueView, peerPresenceView, headsView.
• RuntimeNodeSpec, checkPlacement(), capability matching.
• Content-addressed artifact upload via @decoperations/xsync-artifacts.

What StateFlow adds

• Workflow definitions — typed steps + links + triggers.
• Lifecycle events — stateflow.workflow.*, stateflow.step.*, warnings, signals.
• FlowRun reducer + view — drop into any XSyncClient.
• Scheduler + claim resolver — pure functions; usable on any node.
• Run host — drives a workflow run on a single node, dispatching local executors.
• Provider adapters — local today; Vercel, Temporal, Durable Objects, Inngest, Trigger.dev later.

Spec

Full v1 specification lives in SPEC.md.