@effectstream/sm 0.200.5 → 0.200.6

package/README.md

@@ -1,9 +1,10 @@
 # @effectstream/sm
 
 The state-machine DSL inside an EffectStream node. Define a typed grammar
-of commands, register one generator per command, and `Stm` parses each
+of commands, register one generator per command, and `StateMachine` parses each
 incoming batcher input, dispatches it to the right handler, and yields
-SQL updates through the runtime.
+SQL updates through the runtime. `Stm` is an alias of the same constructor for
+source compatibility.
 
 - State-machine DSL: define a typed grammar, register one generator per command.
 - Parses each batcher input, dispatches to the handler, yields SQL through the runtime.
@@ -31,45 +32,73 @@ without a database) - see
 [`primitives/src/evm-erc20/erc20-primitive.test.ts`](https://github.com/effectstream/effectstream/blob/main/packages/node-sdk/sm/primitives/src/evm-erc20/erc20-primitive.test.ts).
 
 ```typescript
-import { Stm } from "@effectstream/sm";
+import { StateMachine } from "@effectstream/sm";
 import { World } from "@effectstream/coroutine";
 import { Type } from "@sinclair/typebox";
 import { join, leave } from "./queries.ts"; // pgtyped queries
 
+const stateMachine = new StateMachine({
+  join: [["user", Type.String()]],
+  leave: [["user", Type.String()]],
+})
+  .addStateTransition("join", function* ({ parsedInput, blockTimestamp }) {
+    yield* World.resolve(join, {
+      user: parsedInput.user,
+      ts: blockTimestamp,
+    });
+  })
+  .addStateTransition("leave", function* ({ parsedInput }) {
+    yield* World.resolve(leave, { user: parsedInput.user });
+  });
+```
+
+The constructor requires a grammar and exposes that exact object as
+`stateMachine.grammar`. `addStateTransition` returns the same instance, so the
+registrations above can be chained without introducing a wrapper or a second
+transition map. A host dispatches directly with
+`stateMachine.processInput(input)`.
+
+Use a named grammar when it is shared or when an application supplies an
+explicit events type:
+
+```typescript
+import { StateMachine, Stm } from "@effectstream/sm";
+import { Type } from "@sinclair/typebox";
+
 const grammar = {
   join: [["user", Type.String()]] as const,
-  leave: [["user", Type.String()]] as const,
 } as const;
 
-const stm = new Stm(grammar);
+const stateMachine = new StateMachine(grammar).addStateTransition(
+  "join",
+  function* ({ parsedInput }) {
+    console.log(parsedInput.user);
+  },
+);
 
-stm.addStateTransition("join", function* ({ parsedInput, msTimestamp }) {
-  yield* World.resolve(join, { user: parsedInput.user, ts: msTimestamp });
-});
+type Events = { readonly example: "event" };
+const compatible = new Stm<typeof grammar, Events>(grammar);
 
-stm.addStateTransition("leave", function* ({ parsedInput }) {
-  yield* World.resolve(leave, { user: parsedInput.user });
-});
+StateMachine === Stm; // true: Stm is the same value and type constructor
 ```
 
-The runtime calls `stm.processInput(input)` for every batcher subunit; the
-DSL parses against `grammar`, finds the right handler, and the generator
-yields `World.resolve(...)` so the runtime can execute the pgtyped queries.
-
 ## Inside EffectStream
 
-`Stm` is the central piece a node author writes. The runtime's per-block
-loop wires each user input through the corresponding `Stm` instance,
+`StateMachine` is the central piece a node author writes. The runtime's
+per-block loop wires each user input through the corresponding instance,
 collects yielded SQL, and commits it inside the per-block transaction.
 The built-in primitives package (`@effectstream/sm/builtin`) covers
 common on-chain events - ERC-20/721/1155 transfers, Cardano transfers,
-Midnight events, etc. - so you don't re-implement them.
+Midnight events, etc. - so you don't re-implement them. Canonical-runner
+adoption of the public `stateMachine.grammar` is separate downstream work; this
+package supplies the constructor-owned grammar and direct dispatcher.
 
 ## Key exports
 
-- `Stm<Grammar, Events>`: the state machine. `.addStateTransition(prefix, handler)`, `.processInput(input)`, `.grammar`, `.fullJsonGrammar`, `.keyedJsonGrammar`.
+- `StateMachine<Grammar, Events>`: the canonical state machine. `.addStateTransition(prefix, handler)`, `.processInput(input)`, `.grammar`, `.fullJsonGrammar`, `.keyedJsonGrammar`.
+- `Stm<Grammar, Events>`: compatibility alias of the exact `StateMachine` constructor.
 - `ParamToData<Params>` derives the typed argument shape from a grammar entry.
-- `BaseStfInput`: input shape passed to every handler. Includes `msTimestamp`, `blockHeight`, etc.
+- `BaseStfInput`: input shape passed to every handler. Includes `blockTimestamp`, `blockHeight`, etc.
 - `delegate-wallet` helpers - account delegation primitives reused by built-ins.
 
 `MessageListener<Events, Params>` is exported as the handler type but is
@@ -83,9 +112,6 @@ Subpath exports:
 ## Examples
 
 - [`primitives/src/evm-erc20/erc20-primitive.test.ts`](https://github.com/effectstream/effectstream/blob/main/packages/node-sdk/sm/primitives/src/evm-erc20/erc20-primitive.test.ts) - a real primitive's behavior unit-tested.
-- Game logic in
-  [`templates/dice/packages/node/`](https://github.com/effectstream/effectstream/tree/main/templates/dice/packages/node)
-  shows the full `new Stm(...).addStateTransition(...)` pattern.
 
 Runnable: [`test/examples.test.ts`](./test/examples.test.ts).
 

package/Stm.ts

@@ -21,9 +21,10 @@ export type MessageListener<
   input: BaseStfInput & { parsedInput: ParamToData<Params> },
 ) => SyncStateUpdateStream<void>;
 
-export class Stm<
-  Grammar extends GrammarDefinition,
-  Events extends AppEvents,
+export class StateMachine<
+  const Grammar extends GrammarDefinition,
+  Events extends AppEvents = AppEvents,
+  RegisteredPrefixes extends keyof Grammar & string = never,
 > {
   public readonly keyedJsonGrammar: CommandTuples<Grammar>;
   public readonly fullJsonGrammar: FullJsonGrammar<Grammar>;
@@ -45,13 +46,14 @@ export class Stm<
   addStateTransition<const Prefix extends keyof Grammar & string>(
     prefix: Prefix,
     call: MessageListener<Events, Grammar[Prefix]>,
-  ): void {
+  ): StateMachine<Grammar, Events, RegisteredPrefixes | Prefix> {
     if (this.messageListeners.has(prefix)) {
       throw new Error(
         `Disallowed: duplicate listener for prefix ${prefix}. Duplicate prefixes can cause determinism issues`,
       );
     }
     this.messageListeners.set(prefix, call);
+    return this;
   }
 
   *processInput(input: BaseStfInput): SyncStateUpdateStream<void> {
@@ -86,3 +88,5 @@ export class Stm<
     return;
   }
 }
+
+export { StateMachine as Stm };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@effectstream/sm",
-  "version": "0.200.5",
+  "version": "0.200.6",
   "license": "(MIT OR Apache-2.0)",
   "homepage": "https://effectstream.github.io/docs/",
   "repository": {
@@ -17,14 +17,14 @@
     "./grammar": "./primitives/src/grammar.ts"
   },
   "dependencies": {
-    "@effectstream/concise": "0.200.5",
-    "@effectstream/config": "0.200.5",
-    "@effectstream/coroutine": "0.200.5",
-    "@effectstream/crypto": "0.200.5",
-    "@effectstream/db": "0.200.5",
-    "@effectstream/event-client": "0.200.5",
-    "@effectstream/log": "0.200.5",
-    "@effectstream/utils": "0.200.5",
+    "@effectstream/concise": "0.200.6",
+    "@effectstream/config": "0.200.6",
+    "@effectstream/coroutine": "0.200.6",
+    "@effectstream/crypto": "0.200.6",
+    "@effectstream/db": "0.200.6",
+    "@effectstream/event-client": "0.200.6",
+    "@effectstream/log": "0.200.6",
+    "@effectstream/utils": "0.200.6",
     "@noble/hashes": "^2.2.0",
     "pg": "8.21.0",
     "pg-tx": "^1.0.1",

package/test/examples.test.ts

@@ -1,28 +1,31 @@
-// Examples for the README. We exercise Stm in isolation — define a
+// Examples for the README. We exercise StateMachine in isolation — define a
 // grammar, register handlers, and check `.processInput` dispatches to
 // the right one. The runtime side (executing yielded SQL) is the job of
 // @effectstream/runtime, not this package.
 
 import { test, expect } from "bun:test";
 import { Type } from "@sinclair/typebox";
-import { Stm } from "../Stm.ts";
+import { StateMachine } from "../Stm.ts";
 
-test("README: Stm dispatches inputs to the registered handler", () => {
+test("README: StateMachine dispatches inputs to the registered handler", () => {
   const grammar = {
     join: [["user", Type.String()]] as const,
     leave: [["user", Type.String()]] as const,
   } as const;
 
-  const stm = new Stm(grammar);
+  const stm = new StateMachine(grammar);
   const calls: string[] = [];
 
-  stm.addStateTransition("join", function* ({ parsedInput }) {
-    calls.push(`join:${parsedInput.user}`);
-    // Empty generator — no DB writes.
-  });
-  stm.addStateTransition("leave", function* ({ parsedInput }) {
-    calls.push(`leave:${parsedInput.user}`);
-  });
+  const registered = stm
+    .addStateTransition("join", function* ({ parsedInput }) {
+      calls.push(`join:${parsedInput.user}`);
+      // Empty generator — no DB writes.
+    })
+    .addStateTransition("leave", function* ({ parsedInput }) {
+      calls.push(`leave:${parsedInput.user}`);
+    });
+
+  expect(registered).toBe(stm);
 
   // Build the on-wire concise input.
   const input = JSON.stringify(["join", "alice"]);
@@ -40,7 +43,7 @@ test("README: Stm dispatches inputs to the registered handler", () => {
 
 test("README: duplicate prefix registration throws", () => {
   const grammar = { join: [["user", Type.String()]] as const } as const;
-  const stm = new Stm(grammar);
+  const stm = new StateMachine(grammar);
   stm.addStateTransition("join", function* () {});
   expect(() => stm.addStateTransition("join", function* () {})).toThrow();
 });

package/test/state-machine.test.ts

@@ -0,0 +1,112 @@
+import { expect, test } from "bun:test";
+import { Type } from "@sinclair/typebox";
+import { StateMachine, Stm } from "../Stm.ts";
+
+const input = (conciseInput: string) => ({
+  conciseInput,
+  blockHeight: 1,
+  blockTimestamp: 2,
+}) as any;
+
+const drain = (stream: Generator) => {
+  while (!stream.next().done) {}
+};
+
+test("StateMachine is the Stm constructor and chains on the same instance", () => {
+  expect(StateMachine).toBe(Stm);
+
+  const grammar = {
+    join: [["user", Type.String()]] as const,
+    leave: [["reason", Type.String()]] as const,
+  } as const;
+  const machine = new StateMachine(grammar);
+  const calls: string[] = [];
+
+  expect(machine.grammar).toBe(grammar);
+
+  const afterJoin = machine.addStateTransition(
+    "join",
+    function* ({ parsedInput }) {
+      calls.push(`join:${parsedInput.user}`);
+    },
+  );
+  expect(afterJoin).toBe(machine);
+
+  const afterLeave = afterJoin.addStateTransition(
+    "leave",
+    function* ({ parsedInput }) {
+      calls.push(`leave:${parsedInput.reason}`);
+    },
+  );
+  expect(afterLeave).toBe(machine);
+
+  drain(machine.processInput(input(JSON.stringify(["join", "alice"]))));
+  expect(calls).toEqual(["join:alice"]);
+
+  drain(machine.processInput(input(JSON.stringify(["leave", "done"]))));
+  expect(calls).toEqual(["join:alice", "leave:done"]);
+});
+
+test("duplicate transition registration remains rejected", () => {
+  const machine = new StateMachine({
+    join: [["user", Type.String()]] as const,
+  });
+  machine.addStateTransition("join", function* () {});
+
+  expect(() => machine.addStateTransition("join", function* () {})).toThrow(
+    "duplicate listener for prefix join",
+  );
+});
+
+test("parse errors and grammar matches without handlers log and return", () => {
+  const machine = new StateMachine({
+    join: [["user", Type.String()]] as const,
+  });
+  const originalError = console.error;
+  const errors: unknown[][] = [];
+  console.error = (...args: unknown[]) => errors.push(args);
+
+  try {
+    expect(machine.processInput(input("not-json")).next().done).toBe(true);
+    expect(errors).toHaveLength(2);
+    expect(errors[0]?.[0]).toBe("[STM] Parsing error:");
+    expect(errors[1]?.[0]).toBe(
+      "[STM] Cannot parse the input with the known grammar:",
+    );
+
+    errors.length = 0;
+    expect(
+      machine
+        .processInput(input(JSON.stringify(["join", "alice"])))
+        .next().done,
+    ).toBe(true);
+    expect(errors).toEqual([
+      [
+        "Grammar match, but no prefix found with corresponding state transition: join",
+      ],
+    ]);
+  } finally {
+    console.error = originalError;
+  }
+});
+
+test("processInput preserves handler yields and propagates handler errors", () => {
+  const machine = new StateMachine({
+    run: [["value", Type.Number()]] as const,
+  });
+  const yielded = ["query", { value: 7 }] as any;
+  let calls = 0;
+
+  machine.addStateTransition("run", function* ({ parsedInput }) {
+    calls += 1;
+    expect(parsedInput.value).toBe(7);
+    yield yielded;
+    throw new Error("handler failure");
+  });
+
+  const stream = machine.processInput(input(JSON.stringify(["run", 7])));
+  expect(stream.next()).toEqual({ done: false, value: yielded });
+  expect(calls).toBe(1);
+  expect(() => stream.next()).toThrow("handler failure");
+  expect(calls).toBe(1);
+});

package/test/state-machine.typecheck.ts

@@ -0,0 +1,69 @@
+import { Type } from "@sinclair/typebox";
+import { StateMachine, Stm } from "../Stm.ts";
+
+type Equal<Left, Right> =
+  (<Value>() => Value extends Left ? 1 : 2) extends
+    (<Value>() => Value extends Right ? 1 : 2) ? true : false;
+type Expect<Value extends true> = Value;
+type RegisteredPrefixes<Value> =
+  Value extends StateMachine<any, any, infer Prefix> ? Prefix : never;
+
+const grammar = {
+  join: [
+    ["user", Type.String()],
+    ["age", Type.Number()],
+  ] as const,
+  leave: [["reason", Type.String()]] as const,
+} as const;
+
+const machine = new StateMachine(grammar);
+const afterJoin = machine.addStateTransition("join", function* ({
+  parsedInput,
+}) {
+  const user: string = parsedInput.user;
+  const age: number = parsedInput.age;
+  void user;
+  void age;
+
+  // @ts-expect-error The join payload has no leave reason.
+  parsedInput.reason;
+});
+const afterLeave = afterJoin.addStateTransition("leave", function* ({
+  parsedInput,
+}) {
+  const reason: string = parsedInput.reason;
+  void reason;
+
+  // @ts-expect-error The leave payload has no join user.
+  parsedInput.user;
+});
+
+type _RegisteredPrefixes = Expect<
+  Equal<RegisteredPrefixes<typeof afterLeave>, "join" | "leave">
+>;
+
+// @ts-expect-error Prefixes must come from the constructor grammar.
+machine.addStateTransition("missing", function* () {});
+
+// @ts-expect-error The constructor grammar is mandatory.
+new StateMachine();
+
+new StateMachine({
+  inline: [["enabled", Type.Boolean()]],
+}).addStateTransition("inline", function* ({ parsedInput }) {
+  const enabled: boolean = parsedInput.enabled;
+  void enabled;
+
+  // @ts-expect-error Inline constructor inference retains exact fields.
+  parsedInput.missing;
+});
+
+type Events = { readonly example: "event" };
+const legacy = new Stm<typeof grammar, Events>(grammar);
+legacy.addStateTransition("join", function* ({ parsedInput }) {
+  const user: string = parsedInput.user;
+  void user;
+});
+
+const aliasConstructor: typeof StateMachine = Stm;
+void aliasConstructor;