jssm 5.112.3 → 5.113.0

package/README.md

@@ -18,10 +18,10 @@ Please edit the file it's derived from, instead: `./src/md/readme_base.md`
 
 
 
-* Generated for version 5.112.3 at 5/12/2026, 7:48:34 AM
+* Generated for version 5.112.4 at 5/12/2026, 11:13:56 AM
 
 -->
-# jssm 5.112.3
+# jssm 5.112.4
 
 [**Try the live editor**](https://stonecypher.github.io/jssm-viz-demo/graph_explorer.html) ·
 [Documentation](https://stonecypher.github.io/jssm/docs/) ·
@@ -334,7 +334,7 @@ If your contribution is missing here, please open an issue.
 ***5,342 tests***, run 14,351 times.
 
 - 5,251 specs with 100.0% coverage
-- 91 fuzz tests with 60.8% coverage
+- 91 fuzz tests with 62.2% coverage
 - 3,460 TypeScript lines - 1.5 tests per line, 4.1 generated tests per line
 
 [![Actions Status](https://github.com/StoneCypher/jssm/workflows/Node%20CI/badge.svg)](https://github.com/StoneCypher/jssm/actions)

package/dist/deno/README.md

@@ -0,0 +1,347 @@
+<!--
+
+I8,        8        ,8I                                     88
+`8b       d8b       d8'                                     ""
+ "8,     ,8"8,     ,8"
+  Y8     8P Y8     8P  ,adPPYYba,  8b,dPPYba,  8b,dPPYba,   88  8b,dPPYba,    ,adPPYb,d8
+  `8b   d8' `8b   d8'  ""     `Y8  88P'   "Y8  88P'   `"8a  88  88P'   `"8a  a8"    `Y88
+   `8a a8'   `8a a8'   ,adPPPPP88  88          88       88  88  88       88  8b       88
+    `8a8'     `8a8'    88,    ,88  88          88       88  88  88       88  "8a,   ,d88
+     `8'       `8'     `"8bbdP"Y8  88          88       88  88  88       88   `"YbbdP"Y8
+                                                                              aa,    ,88
+                                                                               "Y8bbdP"
+
+This file is generated.  If you edit it, the edits ***will be lost***.
+----------------------
+
+Please edit the file it's derived from, instead: `./src/md/readme_base.md`
+
+
+
+* Generated for version 5.112.4 at 5/12/2026, 11:13:56 AM
+
+-->
+# jssm 5.112.4
+
+[**Try the live editor**](https://stonecypher.github.io/jssm-viz-demo/graph_explorer.html) ·
+[Documentation](https://stonecypher.github.io/jssm/docs/) ·
+[Discord](https://discord.gg/9P95USqnMK) ·
+[Issues](https://github.com/StoneCypher/fsl/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.
+
+```javascript
+import { sm } from 'jssm';
+
+const TrafficLight = sm`Red -> Green -> Yellow -> Red;`;
+```
+
+That's it.  Using it is equally easy:
+
+```javascript
+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:
+
+```javascript
+TrafficLight.go('Red');    // false  - Green doesn't go to Red, only Yellow
+TrafficLight.go('Blue');   // throws - Blue doesn't exist at all
+```
+
+A more involved machine, with main paths, forced paths, and per-state
+styling, renders to:
+
+<img src="https://raw.githubusercontent.com/StoneCypher/jssm/main/src/assets/doc%20light%20styled.png" alt="A styled four-state traffic light"/>
+
+```javascript
+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**](https://stonecypher.github.io/jssm-viz-demo/graph_explorer.html) ·
+[Documentation](https://stonecypher.github.io/jssm/docs/) ·
+[Discord](https://discord.gg/9P95USqnMK) ·
+[Issues](https://github.com/StoneCypher/fsl/issues)
+
+
+
+<br/>
+
+## Install
+
+```
+npm install jssm
+```
+
+The package ships pure ES6, a CommonJS ES5 bundle, an IIFE for browsers,
+and TypeScript typings.  A Deno build is included.  Node 10 or newer.
+
+
+
+<br/>
+
+## Visualization
+
+`jssm` ships with a visualization subpath that renders state machines to
+SVG using Graphviz (via [`@viz-js/viz`](https://www.npmjs.com/package/@viz-js/viz)).
+
+```typescript
+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.
+
+
+
+<br/>
+
+## 60-second tour
+
+**Actions** let a machine advance without the caller knowing the next state:
+
+```javascript
+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:
+
+```javascript
+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:
+
+```javascript
+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 block
+```
+
+Pre-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.
+
+
+
+<br/>
+
+## Why jssm
+
+**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](https://github.com/StoneCypher/jssm/blob/main/src/doc_md/Tutorial_ATM.md)
+  is thirty.  Small enough to read top-to-bottom, diff in code review,
+  paste into a bug report, or drop into the
+  [live editor](https://stonecypher.github.io/jssm-viz-demo/graph_explorer.html)
+  for a rendered diagram you can step through.
+
+- **Fast.**  Tens of millions of transitions per second on commodity
+  hardware.  See [`src/buildjs/benchmark.cjs`](https://github.com/StoneCypher/jssm/blob/main/src/buildjs/benchmark.cjs)
+  or run `npm run benny` against your own machine.
+
+- **More thoroughly tested than any other JavaScript state-machine
+  library.**  5,342 tests at 100.0% line coverage
+  ([report](https://coveralls.io/github/StoneCypher/jssm)), plus
+  fuzz testing via `fast-check`, with parser test data across ten natural
+  languages and Emoji.
+
+
+
+<br/>
+
+## Documentation
+
+- [What are state machines?](https://github.com/StoneCypher/jssm/blob/main/src/doc_md/WhatAreStateMachines.md) - conceptual intro for newcomers
+- [Getting started](https://github.com/StoneCypher/jssm/blob/main/src/doc_md/GettingStarted.md) - install and use the library across Node, browser, Deno, ES5/ES6, CDN, and TypeScript
+- [Tutorial: a four-state traffic light](https://github.com/StoneCypher/jssm/blob/main/src/doc_md/Tutorial_TrafficLight.md) - short walkthrough that introduces the three arrow types
+- [Tutorial: building an ATM state machine](https://github.com/StoneCypher/jssm/blob/main/src/doc_md/Tutorial_ATM.md) - longer walkthrough that builds a real-world machine in nine incremental steps
+- [Language reference](https://github.com/StoneCypher/jssm/blob/main/src/doc_md/LanguageReference.md) - DSL reference for people already comfortable with state machines
+- [Catalog of example machines](https://github.com/StoneCypher/jssm/blob/main/src/doc_md/ExampleMachines.md) - comparison table of worked examples (light switch, traffic light, intersection, vending machine, more)
+- [Generated API reference](https://stonecypher.github.io/jssm/docs/) - full surface, generated from the TypeScript source
+
+
+
+<br/>
+
+## API at a glance
+
+| Method | Purpose |
+|---|---|
+| `` sm`...` `` | Build a machine from DSL |
+| `.state()` | The current state |
+| `.transition(state)` | Move to a state. Returns `false` if illegal, throws if unknown. |
+| `.force_transition(state)` | Move to a state across a `~>` forced edge |
+| `.action(name)` | Trigger a named action. The next state is derived from the current state. |
+| `.valid_transition(state)` · `.valid_action(name)` | Test whether a transition or action is legal from the current state, without taking it |
+| `.hook(from, to, fn)` | Run on a specific edge. Pre-hook; return `false` to block. |
+| `.hook_entry(state, fn)` · `.hook_exit(state, fn)` | Run when entering or leaving a state |
+| `.hook_action(from, to, action, fn)` | Run when a named action causes a specific edge |
+| `.hook_pre_everything(fn)` · `.hook_everything(fn)` | Bracket the pre-hook pipeline |
+| `.hook_pre_post_everything(fn)` · `.hook_post_everything(fn)` | Bracket the post-hook pipeline |
+
+The full surface - including history, validators, factories, data, and the
+graph-introspection methods - is in the [generated API
+docs](https://stonecypher.github.io/jssm/docs/).
+
+
+
+<br/>
+
+## Status
+
+In production use since May 2017.  Current series is 5.x and the DSL is
+stable; the runtime API has been additive for several years.  MIT licensed
+end to end.  Test data and parser cases are included for English, German,
+French, Spanish, Hebrew, Russian, Ukrainian, Belarusian, Bengali,
+Portuguese, and Emoji.
+
+
+
+<br/>
+
+## Community
+
+<a href="https://discord.gg/9P95USqnMK">![Discord community](https://discordapp.com/api/guilds/899910109642235924/widget.png?style=banner1)</a>
+
+Questions, design discussions, bug reports, and "what would you do for X?"
+are all welcome on Discord.  Issues that need a paper trail go in the
+[issue tracker](https://github.com/StoneCypher/fsl/issues).
+
+
+
+<br/>
+
+## Comparisons
+
+A direct, head-to-head comparison with the other actively-maintained JS state
+machine libraries - XState, Stately.js, Finity, machina.js, and others - is
+in progress and will live in
+[FeatureComparison.md](https://github.com/StoneCypher/jssm/blob/main/src/doc_md/FeatureComparison.md).
+
+A list of related projects, without commentary, is at the bottom of that
+file.
+
+
+
+<br/>
+
+## Contributing
+
+Issues and PRs are welcome.  The cheapest useful contribution is a language
+test case: open a PR with
+[`english.json`](https://github.com/StoneCypher/jssm/blob/main/src/ts/tests/language_data/english.json)
+translated into your language.  Translating
+[`traffic_light.fsl`](https://github.com/StoneCypher/fsl_traffic_light/blob/master/traffic_light.fsl)
+into a separate repo and publishing it goes a step further.
+
+
+
+<br/>
+
+## Acknowledgements
+
+[Michael Morgan](https://github.com/msmorgan/) has debated significant
+sections of the notation, invented several concepts and operators, helped
+with the parser and system nomenclature, and published the first non-author
+`FSL` machine.  [Vat Raghavan](https://github.com/MachinShin) participated
+extensively in language design and implemented several features.  [Forest
+Belton](https://github.com/forestbelton) provided guidance, bugfixes, and
+parser commentary.  [Jordan
+Harbrand](https://github.com/ljharb) suggested two interesting features and
+gave strong feedback on the initial tutorial draft.
+
+Translation contributors:
+
+- [Mykhaylo Les](https://github.com/miles91) - [Ukrainian](https://github.com/StoneCypher/jssm/blob/main/src/ts/tests/language_data/ukrainian.json), [Belarusian](https://github.com/StoneCypher/jssm/blob/main/src/ts/tests/language_data/belarussian.json), [Russian](https://github.com/StoneCypher/jssm/blob/main/src/ts/tests/language_data/russian.json)
+- [Tanvir Islam](https://github.com/tanvirrb) - [Bengali](https://github.com/StoneCypher/jssm/blob/main/src/ts/tests/language_data/bengali.json) (also published the first non-English `FSL` machine)
+- [Francisco Junior](https://github.com/fcojr) - [Portuguese](https://github.com/StoneCypher/jssm/blob/main/src/ts/tests/language_data/portuguese.json)
+- [Jeff Katz](https://github.com/kraln) - [German](https://github.com/StoneCypher/jssm/blob/main/src/ts/tests/language_data/german.json)
+- [Alex Cresswell](https://github.com/technophile77) - [Spanish](https://github.com/StoneCypher/jssm/blob/main/src/ts/tests/language_data/spanish.json)
+- [Dvir Cohen](https://github.com/cohendvir) - [Hebrew](https://github.com/StoneCypher/jssm/blob/main/src/ts/tests/language_data/hebrew.json)
+- [David de la Peña](https://github.com/daviddelapena) - [French](https://github.com/StoneCypher/jssm/blob/main/src/ts/tests/language_data/french.json)
+
+If your contribution is missing here, please open an issue.
+
+
+
+<br/>
+
+---
+
+<details>
+<summary>Stats, coverage, and badges</summary>
+
+<br/>
+
+***5,342 tests***, run 14,351 times.
+
+- 5,251 specs with 100.0% coverage
+- 91 fuzz tests with 62.2% coverage
+- 3,460 TypeScript lines - 1.5 tests per line, 4.1 generated tests per line
+
+[![Actions Status](https://github.com/StoneCypher/jssm/workflows/Node%20CI/badge.svg)](https://github.com/StoneCypher/jssm/actions)
+[![NPM version](https://img.shields.io/npm/v/jssm.svg)](https://www.npmjs.com/package/jssm)
+[![NPM downloads](https://img.shields.io/npm/dt/jssm.svg)](https://www.npmjs.com/package/jssm)
+[![License](https://img.shields.io/npm/l/jssm.svg)](https://github.com/StoneCypher/jssm/blob/main/LICENSE.md)
+[![Coveralls status](https://img.shields.io/coveralls/StoneCypher/jssm.svg)](https://coveralls.io/github/StoneCypher/jssm)
+[![Open issues](https://img.shields.io/github/issues/StoneCypher/fsl.svg)](https://github.com/StoneCypher/fsl/issues)
+
+</details>