快速、简单的 JavaScript 有限状态机,具有可视化功能;享受一行代码的 FSM,而不是数页的代码。 MIT;使用 Typescript;100% 的测试覆盖率。 实现了
快速、简单的 JavaScript 有限状态机,具有可视化功能;享受一行代码的 FSM,而不是数页的代码。 MIT;使用 Typescript;100% 的测试覆盖率。 实现了
Try the live editor · Documentation · Discord · Issues
Easy. Tiny. Fast. Finite state machines as one-liner strings, for TypeScript and JavaScript. Renders to PNG, SVG, and JPEG. Runs in Node, browsers, and Deno. MIT licensed.
import { sm } from 'jssm';
const TrafficLight = sm`Red -> Green -> Yellow -> Red;`;That's it. Using it is equally easy:
TrafficLight.state(); // 'Red'
TrafficLight.go('Green'); // true
TrafficLight.state(); // 'Green'The point of a state machine is to refuse to do things that aren't correct:
TrafficLight.go('Red'); // false - Green doesn't go to Red, only Yellow
TrafficLight.go('Blue'); // throws - Blue doesn't exist at allA more involved machine, with main paths, forced paths, and per-state styling, renders to:
const TrafficLightWithOff = sm`
Red 'next' => Green 'next' => Yellow 'next' => Red;
[Red Yellow Green] ~> Off -> Red;
flow: left;
state Red : { background-color: pink; corners: rounded; };
state Yellow : { background-color: lightyellow; corners: rounded; };
state Green : { background-color: lightgreen; corners: rounded; };
state Off : {
background-color : steelblue;
text-color : white;
shape : octagon;
linestyle : dashed;
};
`;The same string is the runtime and the diagram. They cannot drift apart.
Try it in the live editor · Documentation · Discord · Issues
npm install jssmThe package ships pure ES6, a CommonJS ES5 bundle, an IIFE for browsers, and TypeScript typings. A Deno build is included. Node 10 or newer.
jssm ships with a visualization subpath that renders state machines to
SVG using Graphviz (via @viz-js/viz).
import { sm } from 'jssm';
import { fsl_to_svg_string } from 'jssm/viz';
const svg = await fsl_to_svg_string('a -> b;');The viz subpath is opt-in - importing only from jssm does not pull in
@viz-js/viz. See the Visualization doc page for browser, ESM, and IIFE
usage patterns.
jssm ships a CLI for rendering FSL machines to images and other formats.
npm install -g jssmThis installs three binaries: fsl (the dispatcher), jssm (alias for fsl), and fsl-render (the render plugin).
Render a single machine to SVG (default):
fsl render machine.fsl
# → machine.svg next to inputSpecify a format:
fsl render machine.fsl --target=png --width=800
fsl render machine.fsl --target=dot --stdout > machine.dotRender multiple machines:
fsl render *.fsl --target=svg --out-dir=./diagramsPipe FSL via stdin:
cat machine.fsl | fsl render --target=dot | dot -Tpng > out.pngEvery fsl- executable on PATH is dispatched when you run fsl . Third-party plugins follow the same contract as first-party fsl-render. See notes/superpowers/specs/2026-05-12-fsl-cli-design.md for the contract.
The same render functions are available programmatically:
import { render, renderSet } from 'jssm/cli';
const result = await render(fslText, { target: 'svg' });
if (result.kind === 'text') console.log(result.content);jssm/fence)jssm/fence renders FSL code fences to static, editor-parity-highlighted HTML — no browser, no editor, no live machine required — for Markdown pipelines, static site generators, and doc tooling.
import { transform_markdown } from 'jssm/fence';
const html = await transform_markdown(markdown);
// every fsl/jssm fence becomes rendered, highlighted HTML
// everything else in the document passes through untouched
console.log(html);render_fence_gif walks a machine's main path (or every edge, if there is no main path) into a looping animated GIF, one Graphviz layout patched per frame: 70cs per-frame delay, loops forever, and a 64-frame walk cap by default, all overridable via options.
PNG, JPEG, and GIF output rasterize through the same optional backend as the CLI — install it with npm install @resvg/resvg-wasm.
jssm/grammar)jssm ships the canonical TextMate grammar for FSL as a data file at dist/grammars/fsl.tmLanguage.json (scope source.fsl), the single source consumed across the editor ecosystem — shiki (and the static-site generators built on it), GitHub Linguist, Monaco, Sublime, bat, and the vscode-fsl extension.
import grammar from 'jssm/grammar' with { type: 'json' };
// or read dist/grammars/fsl.tmLanguage.json from node_modules/jssmThe grammar is generated from — and build-verified against — the same fsl_parser.peg that drives the parser, so its highlighting never drifts from the language.
jssm ships Lit-based web components for use in plain HTML or as a base for framework wrappers.
CDN one-liner (with an import map for @viz-js/viz):
On -> Off;">npm one-liner:
import 'jssm/wc/viz/define';
// then use anywhere; is an accepted aliasFull documentation: src/doc_md/WebComponents.md.
Actions let a machine advance without the caller knowing the next state:
const Light = sm`Red 'next' -> Green 'next' -> Yellow 'next' -> Red;`;
Light.action('next'); // true
Light.state(); // 'Green'
Light.action('next'); // true
Light.state(); // 'Yellow'Three arrow types distinguish kinds of transition:
const Light = sm`
Red => Green => Yellow => Red; // => main path
[Red Yellow Green] ~> Off -> Red; // ~> forced, -> legal
`;-> is a legal transition. => is a legal transition that is also part of
the main path. ~> is a transition that requires force_transition -
useful for emergency stops, resets, and other rarities.
Hooks observe and gate transitions:
const m = sm`Red 'next' -> Green 'next' -> Yellow 'next' -> Red;`
.hook('Red', 'Green', () => console.log('GO')) // specific edge
.hook_entry('Red', () => console.log('STOP')) // entering a state
.hook_action('Yellow', 'Red', 'next', () => allowed()); // gate a specific action; return false to blockPre-hooks fire before the state changes and may return false to refuse the
transition. Post-hooks fire after. Four *_everything hooks
(hook_pre_everything, hook_everything, hook_pre_post_everything,
hook_post_everything) bracket the entire pipeline if you want a single
observation point.
Refusals and errors are deliberately different. An illegal transition
returns false. An unknown state throws. Branching code can rely on the
distinction.
Overlapping state groups let a state belong to several groups at once -
something a strict hierarchy can't express. A group is declared with &,
and the same &name then drives transitions, shared metadata, boundary
hooks, and runtime queries:
const req = sm`
&InProgress : [connecting sending receiving];
&Receiving : [receiving draining];
idle 'send' -> connecting 'open' -> sending 'reply' -> receiving;
receiving 'eof' -> draining 'done' -> idle;
&InProgress 'abort' -> idle; // a transition from every group member
on enter &Receiving do 'log_rx'; // boundary hook fires crossing in
`;
req.action('send');
req.isIn('InProgress'); // true - connecting is in &InProgress
req.groupsOf('receiving'); // Set { 'InProgress', 'Receiving' } - overlapreceiving is in both groups simultaneously - it is in-progress and
receiving. When two groups disagree about the same action, a CSS-like
cascade decides: state-specific edges win, then the innermost (nearest)
group, then the later-declared one. Groups render as nested Graphviz
clusters, or as bracketed chips on the node label where memberships
genuinely overlap.
See the cookbook's overlapping-groups recipes for fuller worked examples.
The big win: most state-machine libraries make you write a gargantuan JSON document, or call a builder API a few dozen times, to define a single machine. jssm machines are short, readable, arrow-driven strings - so they are easy to write, easy to read, easy to debug, and easy to share.
That decision shows up everywhere downstream:
A DSL with features other state-machine libraries don't have. Three
arrow types distinguish legal, main-path, and forced transitions. Array
notation collapses repeated edges - [Red Yellow Green] ~> Off replaces
three lines. Named actions, per-state styling, named edges, validators,
and live visualization all live in the same string the runtime parses.
Definition strings stay tiny, which makes machines easy to debug. The traffic light is one line; the full eight-step ATM walkthrough is thirty. Small enough to read top-to-bottom, diff in code review, paste into a bug report, or drop into the live editor for a rendered diagram you can step through.
Fast. Tens of millions of transitions per second on commodity
hardware. See src/buildjs/benchmark.cjs
or run npm run benny against your own machine.
More thoroughly tested than any other JavaScript state-machine
library. 10,142 tests at 100.0% line coverage
(report), plus
fuzz testing via fast-check, with parser test data across ten natural
languages and Emoji.
| M
暂无开放 Issues,或尚未同步最近议题。