Signature of an "everything" pre-transition hook handler. Like
HookHandler but receives an EverythingHookContext so the
handler can dispatch on hook_name.
String literal type of the four supported FSL flow directions. This is
the type of the flow config key on a machine.
A source span produced by the FSL parser when parse(input, { locations: true }) is used. Mirrors PEG.js's native location() shape: byte
offsets (0-based, half-open) plus 1-based line/column for display.
const [t] = parse('a -> b;', { locations: true });
// t.loc === { start: { offset: 0, line: 1, column: 1 },
// end: { offset: 7, line: 1, column: 8 } }
String literal type of the built-in theme names. This is the element
type of the theme config key (which accepts an array so that themes
can be layered).
Kinds for FSL boundary hooks (on enter/exit &group do 'X' and the plain-
state analogue). These fire post-commit when a transition crosses the
subject's boundary and are not part of HookDescription (that union
covers only the programmatically-registered observational hooks), so the
registry widens its kind field with them.
Richer hook return value used when a hook needs to do more than just
accept or veto a transition. pass is the required accept/veto flag
(kept non-optional so that returning a stray object doesn't accidentally
veto everything). The optional state overrides the destination state,
data overrides the data observed by other hooks in the same chain,
and next_data overrides the data committed after the transition.
Context object passed to every HookHandler. data is the
data payload as it stands before the transition, and next_data is
the payload that will be committed if the transition is accepted —
handlers may inspect or mutate the latter via a
HookComplexResult return value.
Discriminated union of every kind of hook registration jssm understands,
pre-transition and post-transition. The kind field selects the
variant; remaining fields describe which transitions / states / actions
the hook is bound to and supply the HookHandler or
PostHookHandler to invoke.
Pre-transition variants ('hook', 'named', 'standard transition',
'main transition', 'forced transition', 'any transition',
'global action', 'any action', 'entry', 'exit', 'after')
may return a falsy value to veto a transition. Post-transition
variants ('post *') cannot veto and are invoked only after a
successful transition.
Signature of a pre-transition hook handler. Receives the current and proposed-next data payloads via a HookContext and returns a HookResult: a falsy result vetoes the transition, a truthy result allows it, and a HookComplexResult can additionally rewrite the next state or next data.
Whether an observational hook runs in the pre-transition phase (where it may veto/mutate the transition) or the post-transition phase (a pure observer that runs only after a successful transition commits).
Query for Machine.has_hook / Machine.hooks_on. A bare
string is read as a state name; an { from, to, action? } object is read
as an edge (optionally a named edge); an { action } object is read as a
named action; a { group } object is read as a named state group. This
mirrors the spec's hooks_on(state) / hooks_on(from→to) /
hooks_on(action) / hooks_on(&group) set with one parameter shape.
One row of the generated uniform observational-hook registry. kind is
either an original HookDescription discriminator (e.g. 'entry',
'post named') or a HookBoundaryKind for an FSL boundary hook,
phase is the HookPhase the hook runs in, and target is the
normalized HookTarget it is bound to. The triple
(kind, target, phase) is the registry key the spec calls for.
Return value from a HookHandler. May be a plain boolean to
accept (true/undefined/void) or veto (false) the transition, or
a HookComplexResult that additionally rewrites the next state
and/or the next data payload.
Normalized description of the target a registry entry is bound to. Exactly one scope variant applies; the present fields depend on the scope:
'edge' carries from + to (+ optional action for named hooks),'state' carries state,'action' carries action,'global' carries no further keys (it matches everything),'group' carries group (a named state group with a boundary hook). Coarse classification of what a hook observes, used to bucket every hook
kind into the uniform registry. 'edge' hooks watch a from→to
transition (optionally narrowed to a named action); 'state' hooks watch
a single state (entry/exit/after, or a state boundary hook); 'action'
hooks watch a named action regardless of edge; 'global' hooks watch every
transition or every action (the any-*, transition-class, and everything
observers); 'group' hooks watch a named state group's enter/exit boundary.
Detail payload fired with an action event. Fires when an action is
attempted, before transition validation runs.
Controls whether the state graph may contain disconnected components
(islands). true permits islands (default), false requires a single
connected component, and 'with_start' permits islands only when every
component contains at least one start state.
Tristate flag for whether a property may be overridden at runtime.
true permits overrides, false forbids them, and undefined defers
the decision to the surrounding configuration's default.
The set of ASCII arrow tokens recognized by the FSL grammar. Each arrow
encodes a direction (one-way left/right, or two-way) and a "kind" for
each direction (- legal, = main path, ~ forced-only). See the
Language Reference docs for the full semantic table.
Direction polarity of an arrow: pointing only 'left', only 'right',
or 'both' (a bidirectional arrow).
Semantic category of an arrow's transition. 'legal' is a normal
transition, 'main' is part of the machine's primary path, 'forced'
may only be taken via Machine.force_transition, and 'none'
means no transition exists in that direction.
Complete shape of a jssm-viz theme. A theme provides a style block for
each kind of state (state, hooked, start, end, terminal) as
well as a matching active_* variant used while that state is current.
The graph, legal, main, forced, action, and title slots are
reserved for future use and currently typed as undefined.
Most user-defined themes should be typed as JssmTheme (the
Partial of this) so that omitted fields fall back to the base theme.
The compiled boundary-hook surface for a single subject (a group or a
state): the action to run on entry (onEnter) and/or on exit (onExit).
Each is optional so a subject may declare only one direction; the compiler
merges an enter and an exit declaration for the same subject into one
of these.
A color value accepted by jssm-viz for state and arrow styling. Currently
any string, validated downstream by Graphviz / the named-colors list.
Intended to be narrowed to #RRGGBB / #RRGGBBAA and CSS named colors
in a future release.
Internal compiler intermediate: a single aggregated rule produced while folding a parse tree into a machine configuration. Not intended for end-user code.
Internal compiler intermediate: one link in a chained transition
expression (an "s-expression" segment). Carries both directions of an
arrow with optional per-direction action labels, probabilities, and
after-times. The recursive se field allows the parser to chain
arrows of the form A -> B -> C. Not intended for end-user code.
Internal compiler intermediate: the root of a chained transition
expression, anchored at a from state. Also doubles as the carrier
for non-transition rules (state declarations, property definitions,
machine metadata) via its key/value/name/state fields. Not
intended for end-user code.
Detail payload fired with a complete event. Indicates that the
machine has reached a FSL complete state.
Detail payload fired with a data-change event. Fires whenever the
machine's data payload is replaced. old_data is the value before the
change; new_data is the value after.
Structured render-size hint for a machine visualization, set by the FSL
default_size directive. All three forms are optional in the sense that
only one or two fields will be present depending on the form used:
{ width } — single-number form (default_size: 800;){ width, height } — bounding-box form (default_size: 800 600;){ height } — height-only form (default_size: height 600;)This is a hint, not a hard constraint. Renderers may ignore it.
Detail payload fired with an entry event. state is the entered
state. from is the predecessor state, if any. action is the
action that drove the entry, if any.
Detail payload fired with an error event. Wraps an exception caught
while running an event handler; source_event and source_detail
identify the event whose handler threw, and handler is the offending
function so consumers can correlate / blame.
Extra diagnostic information attached to a JssmError when it carries machine-relative context — most often the state name a caller asked about when the error was raised.
Mapped type from JssmEventName to the corresponding detail
payload. Drives the discriminated-union typing of Machine.on,
so e.action and friends only exist where they're meaningful.
Per-event filter object (as passed to Machine.on). Use
JssmEventDetailMap<mDT>[Ev] to find the matching detail type.
The type of the machine data member.
The event name.
Filter accepted by Machine.on / Machine.once for an individual event name. Only events whose detail key matches every filter entry fire the handler. Events that don't list a filter key in v1 take no filter properties.
The type of the machine data member.
The event name.
Per-event handler signature. Receives a detail object typed by event
name, so e.action (etc.) only exist where they're meaningful.
All event names that Machine.on accepts. These are observation events fired by the machine in addition to (not in place of) the hook system. Hooks intercept; events observe.
Detail payload fired with an exit event. state is the exited
state. to is the next state, if any. action is the action that
drove the exit, if any.
Full configuration object accepted by the Machine constructor and
by {@link from}. Carries the transition list and the optional knobs
governing layout, theming, history, start/end states, property
definitions, machine metadata (author, license, version, ...) and the
runtime hook surfaces (time_source, timeout_source, ...).
Most users never construct one of these directly — the sm tagged
template literal and {@link from} produce one from FSL source.
The state-name type (usually string).
The user-supplied data payload type (mDT).
Maximum depth of the boundary-hook action cascade before the machine throws a JssmError rather than risking a stack overflow or hang.
Each time a boundary action fires a transition that itself crosses a boundary, the depth counter increments. A cascade exceeding this limit is treated as a probable infinite loop and rejected.
Defaults to 100. Raise it for legitimate pipelines that genuinely nest
more than 100 transitions via boundary hooks.
Overlapping-state-group tables produced by the compile pass and consumed by the Task-3 runtime cascade.
group_registry maps each group name to its ordered list of direct
members (states and sub-group references) as declared in the FSL source.
group_metadata maps each group name to its RAW style object
{ declarations: [...] } — parsed style items from a
state &g : { … }; declaration, not condensed JssmStateConfig
style fields. Condensation is intentionally deferred to the Task-3
runtime cascade so that depth-specificity resolution can weight each
group's contribution before merging into per-state config.
group_hooks and state_hooks hold boundary-hook payloads keyed by
group name and state name respectively; firing is also a Task-3 concern.
All four fields are absent (undefined) on machines that declare no
groups or hooks.
Minimal machine description used internally and accepted by some lower-level constructors. Most callers should use the richer JssmGenericConfig instead.
Topology record for one node in a compiled machine: its name, the set of states it can be reached from, the set of states it can transition to, and whether reaching it constitutes "completing" the machine.
Graph-scope default-config style items folded from the deprecated
top-level graph keywords (graph_layout, graph_bg_color,
dot_preamble, theme, flow, and the edge-color/edge_color
default) into the consolidated graph: {} config. Each carries the
legacy parse key so downstream consumers can disambiguate.
The compiled value of a graph: {} config block: an ordered list of
graph-default style items. The compiler folds the deprecated top-level
graph keywords into this list first, then lets an explicit graph: {}
block override on key conflict.
import { compile, parse } from 'jssm';
const cfg = compile(parse('a -> b; graph_bg_color: #ffffff;'));
// the compiler canonicalizes the folded `graph_bg_color` alias to a
// `background-color` item, so:
// cfg.default_graph_config includes { key: 'background-color', value: '#ffffffff' }
The graph-wide default edge colour style item, produced by the
edge-color/edge_color line inside a transition: {} (or graph: {})
config block. Kept distinct from JssmStateStyleColor because it
applies to edges rather than nodes, and because it carries the legacy
graph_default_edge_color key the grammar emits.
A single item inside a graph: {} default-config block. For v1 this
reuses the per-state style items plus the graph-scope alias items
(JssmGraphAliasKey) folded in from the deprecated top-level
graph keywords.
Maps each group name that has at least one boundary hook to its merged JssmBoundaryHooks. Carried on JssmGenericConfig for the runtime to consume; depth-aware firing is a later task.
One ordered member of a named group's membership list. A 'state'
member is an ordinary state (a inside &g : [a]). A 'group' member
references another group: mode: 'nest' is the &child form, which
preserves the child group's identity for later precedence/viz, while
mode: 'spread' is the ...&child form, which inlines the child's
members and erases that identity. Both modes resolve to the same flat
set of states via JssmGroupRegistry resolution; only their
structural bookkeeping differs.
// `&outer : [&inner x];` direct members:
// [ { kind: 'group', name: 'inner', mode: 'nest' },
// { kind: 'state', name: 'x' } ]
A bare reference to a named group as it appears in the parse tree —
written &Name in FSL. Stands in for a state wherever a group may be
used (a transition source/target, a state declaration subject, or a
hook subject). Distinct from the &Name : [...] declaration form,
which defines the group's members.
import { parse } from 'jssm';
parse('&busy : [a b]; &busy -> idle;')[1].from;
// { key: 'group_ref', name: 'busy' }
The compiled group table: maps each declared group name to its
ordered, direct members (a JssmGroupMemberRef list). Order
is meaningful — it carries declaration/iteration/precedence order — so
this is always an array-valued Map, never a Set. Only direct
members are stored; transitive (flattened) membership is resolved
lazily so the group→group graph survives for viz and precedence.
// for `&inner : [a b]; &outer : [&inner c];`
// registry.get('inner') === [ { kind:'state', name:'a' },
// { kind:'state', name:'b' } ]
// registry.get('outer') === [ { kind:'group', name:'inner', mode:'nest' },
// { kind:'state', name:'c' } ]
Bounded history of recently-visited states paired with the data payload
observed in each. Backed by circular_buffer_js, so the oldest entry
is dropped silently once the configured capacity is exceeded.
A parsed FSL boundary-hook declaration — the on <enter|exit> <subject> do '<action>'; form. event is the boundary crossing the hook listens for,
subject is either a JssmGroupRef (a &Group) or a plain state
label string, and action is the (unquoted) action name to run. The
compiler routes a group subject into group_hooks and a state subject
into state_hooks on JssmGenericConfig; runtime firing is a
later task.
import { parse } from 'jssm';
parse("on enter &busy do 'log';")[0];
// { key:'hook_decl', event:'enter',
// subject:{ key:'group_ref', name:'busy' }, action:'log' }
Detail payload fired with hook-registration and hook-removal events.
Mirrors the HookDescription so inspector tools can mirror the
current hook set.
Graphviz layout engine selector. Controls how jssm-viz lays out the
rendered diagram; 'dot' is the default and most useful for state
machines. See the Graphviz documentation for the differences.
The full internal bookkeeping snapshot of a Machine, exposed for
advanced introspection. Contains the current state, the state map, the
edge map and reverse-action map, and the original edge list. The
internal_state_impl_version field exists so that consumers can detect
shape changes if this representation evolves.
Detail payload fired with an override event. Distinguishes a forced
state replacement from a normal transition.
Signature of an FSL parse function: takes a source string and returns a JssmParseTree. Used to type the parser export so consumers can swap in alternative parser implementations.
The output shape of the FSL parser: a flat array of JssmCompileSeStart entries, one per top-level rule in the source. Consumed by the compiler to build a machine configuration.
Two-state policy flag: a feature is either 'required' or 'disallowed'.
Used by machine configuration where the option must take a definite stance.
Three-state policy flag: 'required', 'disallowed', or 'optional'.
Used by machine configuration where a default-permissive middle ground
is meaningful (for example, the actions config key).
Declaration of a named property that a machine's states may carry.
Set required: true to force every state to define the property, or
provide default_value to fall back when the state does not specify it.
For state-property bindings (the state_property config list), the
compiler also writes property and state — the unserialized pair behind
the serialized name — so the Machine constructor can validate bindings
without parsing name back apart. Both are optional: hand-built configs
may carry only the serialized name, and global property definitions
never set them.
Detail payload fired with a rejection event. Carries the resolved
source and target plus an indication of who rejected the transition
and why. reason is 'invalid' when no edge existed, 'hook' when
a hook handler vetoed; hook_name is set when reason is 'hook'.
Discriminated union representing the outcome of an operation: either
success, failure (with an error), or incomplete. Used as the return
shape for operations that may need to report partial progress.
Pluggable random-number-generator function shape. Must return a value
in [0, 1) exactly as Math.random does. Supplied via the
rng_seed-aware machine configuration so that stochastic models can be
made reproducible.
Persistable snapshot of a Machine produced by Machine.serialize and consumed by deserialize. Carries the current state, the associated machine data, the recent history (subject to the configured capacity), and metadata to detect version-skew on rehydration.
The type of the user-supplied data payload (mDT).
A type teaching Typescript the various supported shapes for nodes, mostly inherited from GraphViz
A loosened version of JssmStateDeclaration where every field is optional. Used as the value type for theme entries and for default state configuration where most fields will be inherited or merged.
The fully-condensed declaration for a single state, including its raw
rule list (declarations) and the well-known styling fields jssm-viz
understands. Returned by Machine.state_declaration.
A single key/value pair from an FSL state X: { ... }; block, in the
raw form produced by the parser before being condensed into a
JssmStateDeclaration.
Maps each plain state name that has at least one boundary hook to its merged JssmBoundaryHooks. The state-subject analogue of JssmGroupHooks.
Tagged union of all individual style key/value pairs that may appear in
a state's style configuration. The key discriminator selects which
member, and the value is typed accordingly.
An ordered list of JssmStateStyleKey entries. Used by the
default_*_state_config machine config options to provide a fallback
style stack.
Detail payload fired with a terminal event. Indicates that the
machine has reached a state with no outgoing edges.
A user-supplied theme. Identical in shape to JssmBaseTheme, but every field is optional so themes can be layered: omitted slots fall through to the underlying base theme.
Detail payload fired with a timeout event. Fires when a configured
after clause causes an automatic transition.
A single directed transition (edge) within a state machine. Captures
both the topology (from / to), the FSL semantics (kind,
forced_only, main_path), and any optional metadata such as a
per-edge name, an action label, a guard check, a transition
probability for stochastic models, and an after_time for timed
transitions.
The state-name type (usually string).
The machine's data payload type (mDT).
The compiled value of a transition: {} config block: an ordered list of
edge-default style items. V1 mirrors the state-style shape used by
default_state_config; group machinery that consumes it lands in a later
task.
import { compile, parse } from 'jssm';
const cfg = compile(parse('a -> b; transition: { color: red; };'));
// cfg.default_transition_config === [ { key: 'color', value: '#ff0000ff' } ]
Detail payload fired with a transition event. Carries the resolved
source and target, the action name (if the transition was driven by an
action), the data observed before and after the change, the edge kind,
and whether the call was a forced transition.
The set of states that can immediately precede or follow a given state. Returned by jssm helpers that report a state's connectivity in the graph.
An entry produced while parsing a transition rule: either a literal
state name (StateType) or a JssmTransitionCycle marker.
A single item inside a transition: {} default-config block. For v1 this
reuses the per-state style items (so color: red; works inside a
transition: block exactly as inside a state: block) plus the
edge-scoped JssmGraphDefaultEdgeColor default.
A list of JssmTransitions — the edge set of a machine.
Function returned by Machine.on and Machine.once that removes the subscription. Calling it more than once is a no-op.
Signature of an "everything" post-transition hook handler. Like PostHookHandler but receives an EverythingHookContext. The return value is ignored.
Runtime-iterable list of valid flow directions for FSL diagrams.
Use this when you need to enumerate directions; for the type itself
see FslDirection.
Runtime-iterable list of the built-in theme names that ship with jssm-viz. Use this when you need to enumerate themes; for the type itself see FslTheme.
Generated using TypeDoc
Context object passed to "everything" hooks (EverythingHookHandler and PostEverythingHookHandler). Extends the usual HookContext with
hook_name, which identifies which specific hook fired so a single handler can route on it.