jssm
Version:
A Javascript finite state machine (FSM) with a terse DSL and a simple API. Most FSMs are one-liners. Fast, easy, powerful, well tested, typed with TypeScript, and visualizations. MIT License.
1,293 lines (1,289 loc) • 97.8 kB
text/typescript
import { circular_buffer } from 'circular_buffer_js';
declare type StateType$1 = string;
/**
* 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.
*/
declare type JssmColor = string;
/**
* 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).
*/
declare type JssmPermittedOpt = 'required' | 'disallowed' | 'optional';
/**
* 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.
*/
declare type JssmArrow = '->' | '<-' | '<->' | '<=->' | '<~->' | '=>' | '<=' | '<=>' | '<-=>' | '<~=>' | '~>' | '<~' | '<~>' | '<-~>' | '<=~>';
/**
* A type teaching Typescript the various supported shapes for nodes, mostly inherited from GraphViz
*/
declare type JssmShape = "box" | "polygon" | "ellipse" | "oval" | "circle" | "point" | "egg" | "triangle" | "plaintext" | "plain" | "diamond" | "trapezium" | "parallelogram" | "house" | "pentagon" | "hexagon" | "septagon" | "octagon" | "doublecircle" | "doubleoctagon" | "tripleoctagon" | "invtriangle" | "invtrapezium" | "invhouse" | "Mdiamond" | "Msquare" | "Mcircle" | "rect" | "rectangle" | "square" | "star" | "none" | "underline" | "cylinder" | "note" | "tab" | "folder" | "box3d" | "component" | "promoter" | "cds" | "terminator" | "utr" | "primersite" | "restrictionsite" | "fivepoverhang" | "threepoverhang" | "noverhang" | "assembly" | "signature" | "insulator" | "ribosite" | "rnastab" | "proteasesite" | "proteinstab" | "rpromoter" | "rarrow" | "larrow" | "lpromoter" | "record";
/**
* 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 {@link Machine.force_transition}, and `'none'`
* means no transition exists in that direction.
*/
declare type JssmArrowKind = 'none' | 'legal' | 'main' | 'forced';
/**
* 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.
*/
declare type JssmLayout = 'dot' | 'circo' | 'twopi' | 'fdp' | 'neato';
declare type JssmCorner = 'regular' | 'rounded' | 'lined';
declare type JssmLineStyle = 'solid' | 'dashed' | 'dotted';
/**
* 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.
*/
declare type JssmAllowsOverride = true | false | undefined;
/**
* Runtime-iterable list of valid `flow` directions for FSL diagrams.
* Use this when you need to enumerate directions; for the type itself
* see {@link FslDirection}.
*/
declare const FslDirections: readonly ["up", "right", "down", "left"];
/**
* String literal type of the four supported FSL flow directions. This is
* the type of the `flow` config key on a machine.
*/
declare type FslDirection = typeof FslDirections[number];
/**
* 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
* {@link FslTheme}.
*/
declare const FslThemes: readonly ["default", "ocean", "modern", "plain", "bold"];
/**
* 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).
*/
declare type FslTheme = typeof FslThemes[number];
/**
* Persistable snapshot of a Machine produced by {@link Machine.serialize}
* and consumed by {@link 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.
*
* @typeParam DataType - The type of the user-supplied data payload (`mDT`).
*/
declare type JssmSerialization<DataType> = {
jssm_version: string;
timestamp: number;
comment?: string | undefined;
state: StateType$1;
history: [string, DataType][];
history_capacity: number;
data: DataType;
};
/**
* 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.
*/
declare type JssmPropertyDefinition = {
name: string;
default_value?: any;
required?: boolean;
};
declare type JssmTransitionPermitter<DataType> = (OldState: StateType$1, NewState: StateType$1, OldData: DataType, NewData: DataType) => boolean;
declare type JssmTransitionPermitterMaybeArray<DataType> = JssmTransitionPermitter<DataType> | Array<JssmTransitionPermitter<DataType>>;
/**
* 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.
*
* @typeParam StateType - The state-name type (usually `string`).
* @typeParam DataType - The machine's data payload type (`mDT`).
*/
declare type JssmTransition<StateType, DataType> = {
from: StateType;
to: StateType;
after_time?: number;
se?: JssmCompileSe<StateType, DataType>;
name?: StateType;
action?: StateType;
check?: JssmTransitionPermitterMaybeArray<DataType>;
probability?: number;
kind: JssmArrowKind;
forced_only: boolean;
main_path: boolean;
};
/** A list of {@link JssmTransition}s — the edge set of a machine. */
declare type JssmTransitions<StateType, DataType> = JssmTransition<StateType, DataType>[];
/**
* 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.
*/
declare type JssmTransitionList = {
entrances: Array<StateType$1>;
exits: Array<StateType$1>;
};
/**
* 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.
*/
declare type JssmGenericState = {
from: Array<StateType$1>;
name: StateType$1;
to: Array<StateType$1>;
complete: boolean;
};
/**
* The full internal bookkeeping snapshot of a {@link 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.
*/
declare type JssmMachineInternalState<DataType> = {
internal_state_impl_version: 1;
state: StateType$1;
states: Map<StateType$1, JssmGenericState>;
named_transitions: Map<StateType$1, number>;
edge_map: Map<StateType$1, Map<StateType$1, number>>;
actions: Map<StateType$1, Map<StateType$1, number>>;
reverse_actions: Map<StateType$1, Map<StateType$1, number>>;
edges: Array<JssmTransition<StateType$1, DataType>>;
};
declare type JssmStatePermitter<DataType> = (OldState: StateType$1, NewState: StateType$1, OldData: DataType, NewData: DataType) => boolean;
declare type JssmStatePermitterMaybeArray<DataType> = JssmStatePermitter<DataType> | Array<JssmStatePermitter<DataType>>;
/**
* A single key/value pair from an FSL `state X: { ... };` block, in the
* raw form produced by the parser before being condensed into a
* {@link JssmStateDeclaration}.
*/
declare type JssmStateDeclarationRule = {
key: string;
value: any;
name?: string;
};
/**
* 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 {@link Machine.state_declaration}.
*/
declare type JssmStateDeclaration = {
declarations: Array<JssmStateDeclarationRule>;
shape?: JssmShape;
color?: JssmColor;
corners?: JssmCorner;
lineStyle?: JssmLineStyle;
stateLabel?: string;
textColor?: JssmColor;
backgroundColor?: JssmColor;
borderColor?: JssmColor;
image?: string;
state: StateType$1;
property?: {
name: string;
value: unknown;
};
};
/**
* A loosened version of {@link 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.
*/
declare type JssmStateConfig = Partial<JssmStateDeclaration>;
declare type JssmStateStyleShape = {
key: 'shape';
value: JssmShape;
};
declare type JssmStateStyleColor = {
key: 'color';
value: JssmColor;
};
declare type JssmStateStyleTextColor = {
key: 'text-color';
value: JssmColor;
};
declare type JssmStateStyleCorners = {
key: 'corners';
value: JssmCorner;
};
declare type JssmStateStyleLineStyle = {
key: 'line-style';
value: JssmLineStyle;
};
declare type JssmStateStyleStateLabel = {
key: 'state-label';
value: string;
};
declare type JssmStateStyleBackgroundColor = {
key: 'background-color';
value: JssmColor;
};
declare type JssmStateStyleBorderColor = {
key: 'border-color';
value: JssmColor;
};
declare type JssmStateStyleImage = {
key: 'image';
value: string;
};
/**
* 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.
*/
declare type JssmStateStyleKey = JssmStateStyleShape | JssmStateStyleColor | JssmStateStyleTextColor | JssmStateStyleCorners | JssmStateStyleLineStyle | JssmStateStyleBackgroundColor | JssmStateStyleStateLabel | JssmStateStyleBorderColor | JssmStateStyleImage;
/**
* An ordered list of {@link JssmStateStyleKey} entries. Used by the
* `default_*_state_config` machine config options to provide a fallback
* style stack.
*/
declare type JssmStateStyleKeyList = JssmStateStyleKey[];
/**
* Full configuration object accepted by the {@link 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.
*
* @typeParam StateType - The state-name type (usually `string`).
* @typeParam DataType - The user-supplied data payload type (`mDT`).
*/
declare type JssmGenericConfig<StateType, DataType> = {
graph_layout?: JssmLayout;
complete?: Array<StateType>;
transitions: JssmTransitions<StateType, DataType>;
theme?: FslTheme[];
flow?: FslDirection;
name?: string;
data?: DataType;
nodes?: Array<StateType>;
check?: JssmStatePermitterMaybeArray<DataType>;
history?: number;
min_exits?: number;
max_exits?: number;
allow_islands?: false;
allow_force?: false;
actions?: JssmPermittedOpt;
simplify_bidi?: boolean;
allows_override?: JssmAllowsOverride;
config_allows_override?: JssmAllowsOverride;
dot_preamble?: string;
start_states: Array<StateType>;
end_states?: Array<StateType>;
initial_state?: StateType;
start_states_no_enforce?: boolean;
state_declaration?: Object[];
property_definition?: JssmPropertyDefinition[];
state_property?: JssmPropertyDefinition[];
arrange_declaration?: Array<Array<StateType>>;
arrange_start_declaration?: Array<Array<StateType>>;
arrange_end_declaration?: Array<Array<StateType>>;
machine_author?: string | Array<string>;
machine_comment?: string;
machine_contributor?: string | Array<string>;
machine_definition?: string;
machine_language?: string;
machine_license?: string;
machine_name?: string;
machine_version?: string;
fsl_version?: string;
auto_api?: boolean | string;
instance_name?: string | undefined;
default_state_config?: JssmStateStyleKeyList;
default_start_state_config?: JssmStateStyleKeyList;
default_end_state_config?: JssmStateStyleKeyList;
default_hooked_state_config?: JssmStateStyleKeyList;
default_terminal_state_config?: JssmStateStyleKeyList;
default_active_state_config?: JssmStateStyleKeyList;
rng_seed?: number | undefined;
time_source?: () => number;
timeout_source?: (Function: any, number: any) => number;
clear_timeout_source?: (number: any) => void;
};
/**
* 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
*/
declare type JssmCompileSe<StateType, mDT> = {
to: StateType;
se?: JssmCompileSe<StateType, mDT>;
kind: JssmArrow;
l_action?: StateType;
r_action?: StateType;
l_probability: number;
r_probability: number;
l_after?: number;
r_after?: number;
};
declare type BasicHookDescription<mDT> = {
kind: 'hook';
from: string;
to: string;
handler: HookHandler<mDT>;
};
declare type HookDescriptionWithAction<mDT> = {
kind: 'named';
from: string;
to: string;
action: string;
handler: HookHandler<mDT>;
};
declare type StandardTransitionHook<mDT> = {
kind: 'standard transition';
handler: HookHandler<mDT>;
};
declare type MainTransitionHook<mDT> = {
kind: 'main transition';
handler: HookHandler<mDT>;
};
declare type ForcedTransitionHook<mDT> = {
kind: 'forced transition';
handler: HookHandler<mDT>;
};
declare type AnyTransitionHook<mDT> = {
kind: 'any transition';
handler: HookHandler<mDT>;
};
declare type GlobalActionHook<mDT> = {
kind: 'global action';
action: string;
handler: HookHandler<mDT>;
};
declare type AnyActionHook<mDT> = {
kind: 'any action';
handler: HookHandler<mDT>;
};
declare type EntryHook<mDT> = {
kind: 'entry';
to: string;
handler: HookHandler<mDT>;
};
declare type ExitHook<mDT> = {
kind: 'exit';
from: string;
handler: HookHandler<mDT>;
};
declare type AfterHook<mDT> = {
kind: 'after';
from: string;
handler: HookHandler<mDT>;
};
declare type PostBasicHookDescription<mDT> = {
kind: 'post hook';
from: string;
to: string;
handler: PostHookHandler<mDT>;
};
declare type PostHookDescriptionWithAction<mDT> = {
kind: 'post named';
from: string;
to: string;
action: string;
handler: PostHookHandler<mDT>;
};
declare type PostStandardTransitionHook<mDT> = {
kind: 'post standard transition';
handler: PostHookHandler<mDT>;
};
declare type PostMainTransitionHook<mDT> = {
kind: 'post main transition';
handler: PostHookHandler<mDT>;
};
declare type PostForcedTransitionHook<mDT> = {
kind: 'post forced transition';
handler: PostHookHandler<mDT>;
};
declare type PostAnyTransitionHook<mDT> = {
kind: 'post any transition';
handler: PostHookHandler<mDT>;
};
declare type PostGlobalActionHook<mDT> = {
kind: 'post global action';
action: string;
handler: PostHookHandler<mDT>;
};
declare type PostAnyActionHook<mDT> = {
kind: 'post any action';
handler: PostHookHandler<mDT>;
};
declare type PostEntryHook<mDT> = {
kind: 'post entry';
to: string;
handler: PostHookHandler<mDT>;
};
declare type PostExitHook<mDT> = {
kind: 'post exit';
from: string;
handler: PostHookHandler<mDT>;
};
declare type PreEverythingHook<mDT> = {
kind: 'pre everything';
handler: EverythingHookHandler<mDT>;
};
declare type EverythingHook<mDT> = {
kind: 'everything';
handler: EverythingHookHandler<mDT>;
};
declare type PrePostEverythingHook<mDT> = {
kind: 'pre post everything';
handler: PostEverythingHookHandler<mDT>;
};
declare type PostEverythingHook<mDT> = {
kind: 'post everything';
handler: PostEverythingHookHandler<mDT>;
};
/**
* 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 {@link HookHandler} or
* {@link 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.
*/
declare type HookDescription<mDT> = BasicHookDescription<mDT> | HookDescriptionWithAction<mDT> | GlobalActionHook<mDT> | AnyActionHook<mDT> | StandardTransitionHook<mDT> | MainTransitionHook<mDT> | ForcedTransitionHook<mDT> | AnyTransitionHook<mDT> | EntryHook<mDT> | ExitHook<mDT> | AfterHook<mDT> | PostBasicHookDescription<mDT> | PostHookDescriptionWithAction<mDT> | PostGlobalActionHook<mDT> | PostAnyActionHook<mDT> | PostStandardTransitionHook<mDT> | PostMainTransitionHook<mDT> | PostForcedTransitionHook<mDT> | PostAnyTransitionHook<mDT> | PostEntryHook<mDT> | PostExitHook<mDT> | PreEverythingHook<mDT> | EverythingHook<mDT> | PrePostEverythingHook<mDT> | PostEverythingHook<mDT>;
/**
* 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.
*/
declare type HookComplexResult<mDT> = {
pass: boolean;
state?: StateType$1;
data?: mDT;
next_data?: mDT;
};
/**
* Return value from a {@link HookHandler}. May be a plain boolean to
* accept (`true`/`undefined`/`void`) or veto (`false`) the transition, or
* a {@link HookComplexResult} that additionally rewrites the next state
* and/or the next data payload.
*/
declare type HookResult<mDT> = true | false | undefined | void | HookComplexResult<mDT>;
/**
* Context object passed to every {@link 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
* {@link HookComplexResult} return value.
*/
declare type HookContext<mDT> = {
data: mDT;
next_data: mDT;
};
/**
* Context object passed to "everything" hooks ({@link EverythingHookHandler}
* and {@link PostEverythingHookHandler}). Extends the usual
* {@link HookContext} with `hook_name`, which identifies which specific
* hook fired so a single handler can route on it.
*/
declare type EverythingHookContext<mDT> = HookContext<mDT> & {
hook_name: string;
};
/**
* Signature of a pre-transition hook handler. Receives the current and
* proposed-next data payloads via a {@link HookContext} and returns a
* {@link HookResult}: a falsy result vetoes the transition, a truthy
* result allows it, and a {@link HookComplexResult} can additionally
* rewrite the next state or next data.
*/
declare type HookHandler<mDT> = (hook_context: HookContext<mDT>) => HookResult<mDT>;
/**
* Signature of a post-transition hook handler. Invoked after a successful
* transition has been committed; the return value is ignored (the
* transition cannot be undone).
*/
declare type PostHookHandler<mDT> = (hook_context: HookContext<mDT>) => void;
/**
* Signature of an "everything" pre-transition hook handler. Like
* {@link HookHandler} but receives an {@link EverythingHookContext} so the
* handler can dispatch on `hook_name`.
*/
declare type EverythingHookHandler<mDT> = (hook_context: EverythingHookContext<mDT>) => HookResult<mDT>;
/**
* Signature of an "everything" post-transition hook handler. Like
* {@link PostHookHandler} but receives an {@link EverythingHookContext}.
* The return value is ignored.
*/
declare type PostEverythingHookHandler<mDT> = (hook_context: EverythingHookContext<mDT>) => void;
/**
* 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.
*/
declare type JssmHistory<mDT> = circular_buffer<[StateType$1, mDT]>;
/**
* 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.
*/
declare type JssmRng = () => number;
/**
* The published semantic version of the jssm package this build was cut from.
* Mirrored from `package.json` by `src/buildjs/makever.cjs` at build time.
* Useful for runtime diagnostics and for embedding in serialized machine
* snapshots so that deserializers can detect version-skew.
*/
declare const version: string;
/**
* The Unix epoch timestamp (in milliseconds) at which this build was produced,
* written by `src/buildjs/makever.cjs`. Useful for distinguishing builds
* with the same `version` string during development, and for diagnostic logs.
*/
declare const build_time: number;
declare type StateType = string;
/*******
*
* Core finite state machine class. Holds the full graph of states and
* transitions, the current state, hooks, data, properties, and all runtime
* behavior. Typically created via the {@link sm} tagged template literal
* rather than constructed directly.
*
* ```typescript
* import { sm } from 'jssm';
*
* const light = sm`Red 'next' => Green 'next' => Yellow 'next' => Red;`;
* light.state(); // 'Red'
* light.action('next'); // true
* light.state(); // 'Green'
* ```
*
* @typeparam mDT The machine data type — the type of the value stored in
* `.data()`. Defaults to `undefined` when no data is used.
*
*/
declare class Machine<mDT> {
_state: StateType;
_states: Map<StateType, JssmGenericState>;
_edges: Array<JssmTransition<StateType, mDT>>;
_edge_map: Map<StateType, Map<StateType, number>>;
_named_transitions: Map<StateType, number>;
_actions: Map<StateType, Map<StateType, number>>;
_reverse_actions: Map<StateType, Map<StateType, number>>;
_reverse_action_targets: Map<StateType, Map<StateType, number>>;
_start_states: Set<StateType>;
_end_states: Set<StateType>;
_machine_author?: Array<string>;
_machine_comment?: string;
_machine_contributor?: Array<string>;
_machine_definition?: string;
_machine_language?: string;
_machine_license?: string;
_machine_name?: string;
_machine_version?: string;
_fsl_version?: string;
_raw_state_declaration?: Array<Object>;
_state_declarations: Map<StateType, JssmStateDeclaration>;
_data?: mDT;
_instance_name: string;
_rng_seed: number;
_rng: JssmRng;
_graph_layout: JssmLayout;
_dot_preamble: string;
_arrange_declaration: Array<Array<StateType>>;
_arrange_start_declaration: Array<Array<StateType>>;
_arrange_end_declaration: Array<Array<StateType>>;
_themes: FslTheme[];
_flow: FslDirection;
_has_hooks: boolean;
_has_basic_hooks: boolean;
_has_named_hooks: boolean;
_has_entry_hooks: boolean;
_has_exit_hooks: boolean;
_has_after_hooks: boolean;
_has_global_action_hooks: boolean;
_has_transition_hooks: boolean;
_has_forced_transitions: boolean;
_hooks: Map<string, HookHandler<mDT>>;
_named_hooks: Map<string, HookHandler<mDT>>;
_entry_hooks: Map<string, HookHandler<mDT>>;
_exit_hooks: Map<string, HookHandler<mDT>>;
_after_hooks: Map<string, HookHandler<mDT>>;
_global_action_hooks: Map<string, HookHandler<mDT>>;
_any_action_hook: HookHandler<mDT> | undefined;
_standard_transition_hook: HookHandler<mDT> | undefined;
_main_transition_hook: HookHandler<mDT> | undefined;
_forced_transition_hook: HookHandler<mDT> | undefined;
_any_transition_hook: HookHandler<mDT> | undefined;
_has_post_hooks: boolean;
_has_post_basic_hooks: boolean;
_has_post_named_hooks: boolean;
_has_post_entry_hooks: boolean;
_has_post_exit_hooks: boolean;
_has_post_global_action_hooks: boolean;
_has_post_transition_hooks: boolean;
_code_allows_override: JssmAllowsOverride;
_config_allows_override: JssmAllowsOverride;
_post_hooks: Map<string, HookHandler<mDT>>;
_post_named_hooks: Map<string, HookHandler<mDT>>;
_post_entry_hooks: Map<string, HookHandler<mDT>>;
_post_exit_hooks: Map<string, HookHandler<mDT>>;
_post_global_action_hooks: Map<string, HookHandler<mDT>>;
_post_any_action_hook: HookHandler<mDT> | undefined;
_post_standard_transition_hook: HookHandler<mDT> | undefined;
_post_main_transition_hook: HookHandler<mDT> | undefined;
_post_forced_transition_hook: HookHandler<mDT> | undefined;
_post_any_transition_hook: HookHandler<mDT> | undefined;
_pre_everything_hook: EverythingHookHandler<mDT> | undefined;
_everything_hook: EverythingHookHandler<mDT> | undefined;
_pre_post_everything_hook: PostEverythingHookHandler<mDT> | undefined;
_post_everything_hook: PostEverythingHookHandler<mDT> | undefined;
_property_keys: Set<string>;
_default_properties: Map<string, any>;
_state_properties: Map<string, any>;
_required_properties: Set<string>;
_history: JssmHistory<mDT>;
_history_length: number;
_state_style: JssmStateConfig;
_active_state_style: JssmStateConfig;
_hooked_state_style: JssmStateConfig;
_terminal_state_style: JssmStateConfig;
_start_state_style: JssmStateConfig;
_end_state_style: JssmStateConfig;
_state_labels: Map<string, string>;
_time_source: () => number;
_create_started: number;
_created: number;
_after_mapping: Map<string, [string, number]>;
_timeout_source: (Function: any, number: any) => number;
_clear_timeout_source: (h: any) => void;
_timeout_handle: number | undefined;
_timeout_target: string | undefined;
_timeout_target_time: number | undefined;
constructor({ start_states, end_states, initial_state, start_states_no_enforce, complete, transitions, machine_author, machine_comment, machine_contributor, machine_definition, machine_language, machine_license, machine_name, machine_version, state_declaration, property_definition, state_property, fsl_version, dot_preamble, arrange_declaration, arrange_start_declaration, arrange_end_declaration, theme, flow, graph_layout, instance_name, history, data, default_state_config, default_active_state_config, default_hooked_state_config, default_terminal_state_config, default_start_state_config, default_end_state_config, allows_override, config_allows_override, rng_seed, time_source, timeout_source, clear_timeout_source }: JssmGenericConfig<StateType, mDT>);
/********
*
* Internal method for fabricating states. Not meant for external use.
*
* @internal
*
*/
_new_state(state_config: JssmGenericState): StateType;
/*********
*
* Get the current state of a machine.
*
* ```typescript
* import * as jssm from 'jssm';
*
* const lswitch = jssm.from('on <=> off;');
* console.log( lswitch.state() ); // 'on'
*
* lswitch.transition('off');
* console.log( lswitch.state() ); // 'off'
* ```
*
* @typeparam mDT The type of the machine data member; usually omitted
*
* @returns The current state name.
*
*/
state(): StateType;
/*********
*
* Get the label for a given state, if any; return `undefined` otherwise.
*
* ```typescript
* import * as jssm from 'jssm';
*
* const lswitch = jssm.from('a -> b; state a: { label: "Foo!"; };');
* console.log( lswitch.label_for('a') ); // 'Foo!'
* console.log( lswitch.label_for('b') ); // undefined
* ```
*
* See also {@link display_text}.
*
* @typeparam mDT The type of the machine data member; usually omitted
*
* @param state The state to get the label for.
*
* @returns The label string, or `undefined` if no label is set.
*
*/
label_for(state: StateType): string;
/*********
*
* Get whatever the node should show as text.
*
* Currently, this means to get the label for a given state, if any;
* otherwise to return the node's name. However, this definition is expected
* to grow with time, and it is currently considered ill-advised to manually
* parse this text.
*
* See also {@link label_for}.
*
* ```typescript
* import * as jssm from 'jssm';
*
* const lswitch = jssm.from('a -> b; state a: { label: "Foo!"; };');
* console.log( lswitch.display_text('a') ); // 'Foo!'
* console.log( lswitch.display_text('b') ); // 'b'
* ```
*
* @typeparam mDT The type of the machine data member; usually omitted
*
* @param state The state to get display text for.
*
* @returns The label if one exists, otherwise the state's name.
*
*/
display_text(state: StateType): string;
/*********
*
* Get the current data of a machine.
*
* ```typescript
* import * as jssm from 'jssm';
*
* const lswitch = jssm.from('on <=> off;', {data: 1});
* console.log( lswitch.data() ); // 1
* ```
*
* @typeparam mDT The type of the machine data member; usually omitted
*
* @returns A deep clone of the machine's current data value.
*
*/
data(): mDT;
/*********
*
* Get the current value of a given property name. Checks the current
* state's properties first, then falls back to the global default.
* Returns `undefined` if neither exists. For a throwing variant, see
* {@link strict_prop}.
*
* ```typescript
* const m = sm`property color default "grey"; a -> b;
* state b: { property color "blue"; };`;
*
* m.prop('color'); // 'grey' (default, because state is 'a')
* m.go('b');
* m.prop('color'); // 'blue' (state 'b' overrides the default)
* m.prop('size'); // undefined (no such property)
* ```
*
* @param name The relevant property name to look up.
*
* @returns The value behind the prop name, or `undefined` if not defined.
*
*/
prop(name: string): any;
/*********
*
* Get the current value of a given property name. If missing on the state
* and without a global default, throws a {@link JssmError}, unlike
* {@link prop}, which would return `undefined` instead.
*
* ```typescript
* const m = sm`property color default "grey"; a -> b;`;
*
* m.strict_prop('color'); // 'grey'
* m.strict_prop('size'); // throws JssmError
* ```
*
* @param name The relevant property name to look up.
*
* @returns The value behind the prop name.
*
* @throws {JssmError} If the property is not defined on the current state
* and has no default.
*
*/
strict_prop(name: string): any;
/*********
*
* Get the current value of every prop, as an object. If no current definition
* exists for a prop — that is, if the prop was defined without a default and
* the current state also doesn't define the prop — then that prop will be listed
* in the returned object with a value of `undefined`.
*
* ```typescript
* const traffic_light = sm`
*
* property can_go default true;
* property hesitate default true;
* property stop_first default false;
*
* Off -> Red => Green => Yellow => Red;
* [Red Yellow Green] ~> [Off FlashingRed];
* FlashingRed -> Red;
*
* state Red: { property stop_first true; property can_go false; };
* state Off: { property stop_first true; };
* state FlashingRed: { property stop_first true; };
* state Green: { property hesitate false; };
*
* `;
*
* traffic_light.state(); // Off
* traffic_light.props(); // { can_go: true, hesitate: true, stop_first: true; }
*
* traffic_light.go('Red');
* traffic_light.props(); // { can_go: false, hesitate: true, stop_first: true; }
*
* traffic_light.go('Green');
* traffic_light.props(); // { can_go: true, hesitate: false, stop_first: false; }
* ```
*
* @returns An object mapping every known property name to its current value
* (or `undefined` if the property has no default and the current state
* doesn't define it).
*
*/
props(): object;
/*********
*
* Check whether a given string is a known property's name.
*
* ```typescript
* const example = sm`property foo default 1; a->b;`;
*
* example.known_prop('foo'); // true
* example.known_prop('bar'); // false
* ```
*
* @param prop_name The relevant property name to look up
*
*/
known_prop(prop_name: string): boolean;
/*********
*
* List all known property names. If you'd also like values, use
* {@link props} instead. The order of the properties is not defined, and
* the properties generally will not be sorted.
*
* ```typescript
* const m = sm`property color default "grey"; property size default 1; a -> b;`;
*
* m.known_props(); // ['color', 'size']
* ```
*
* @returns An array of all property name strings defined on this machine.
*
*/
known_props(): string[];
/********
*
* Check whether a given state is a valid start state (either because it was
* explicitly named as such, or because it was the first mentioned state.)
*
* ```typescript
* import { sm, is_start_state } from 'jssm';
*
* const example = sm`a -> b;`;
*
* console.log( final_test.is_start_state('a') ); // true
* console.log( final_test.is_start_state('b') ); // false
*
* const example = sm`start_states: [a b]; a -> b;`;
*
* console.log( final_test.is_start_state('a') ); // true
* console.log( final_test.is_start_state('b') ); // true
* ```
*
* @typeparam mDT The type of the machine data member; usually omitted
*
* @param whichState The name of the state to check
*
*/
is_start_state(whichState: StateType): boolean;
/********
*
* Check whether a given state is a valid start state (either because it was
* explicitly named as such, or because it was the first mentioned state.)
*
* ```typescript
* import { sm, is_end_state } from 'jssm';
*
* const example = sm`a -> b;`;
*
* console.log( final_test.is_start_state('a') ); // false
* console.log( final_test.is_start_state('b') ); // true
*
* const example = sm`end_states: [a b]; a -> b;`;
*
* console.log( final_test.is_start_state('a') ); // true
* console.log( final_test.is_start_state('b') ); // true
* ```
*
* @typeparam mDT The type of the machine data member; usually omitted
*
* @param whichState The name of the state to check
*
*/
is_end_state(whichState: StateType): boolean;
/********
*
* Check whether a given state is final (either has no exits or is marked
* `complete`.)
*
* ```typescript
* import { sm, state_is_final } from 'jssm';
*
* const final_test = sm`first -> second;`;
*
* console.log( final_test.state_is_final('first') ); // false
* console.log( final_test.state_is_final('second') ); // true
* ```
*
* @typeparam mDT The type of the machine data member; usually omitted
*
* @param whichState The name of the state to check for finality
*
*/
state_is_final(whichState: StateType): boolean;
/********
*
* Check whether the current state is final (either has no exits or is marked
* `complete`.)
*
* ```typescript
* import { sm, is_final } from 'jssm';
*
* const final_test = sm`first -> second;`;
*
* console.log( final_test.is_final() ); // false
* state.transition('second');
* console.log( final_test.is_final() ); // true
* ```
*
*/
is_final(): boolean;
/********
*
* Serialize the current machine, including all defining state but not the
* machine string, to a structure. This means you will need the machine
* string to recreate (to not waste repeated space;) if you want the machine
* string embedded, call {@link serialize_with_string} instead.
*
* @typeparam mDT The type of the machine data member; usually omitted
*
* @param comment An optional comment string to embed in the serialized
* output for identification or debugging.
*
* @returns A {@link JssmSerialization} object containing the machine's
* current state, data, and timestamp.
*
*/
serialize(comment?: string | undefined): JssmSerialization<mDT>;
/** Get the graph layout direction (e.g. `'LR'`, `'TB'`). Set via the
* FSL `graph_layout` directive.
* @returns The layout string, or the default if not set.
*/
graph_layout(): string;
/** Get the Graphviz DOT preamble string, injected before the graph body
* during visualization. Set via the FSL `dot_preamble` directive.
* @returns The preamble string.
*/
dot_preamble(): string;
/** Get the machine's author list. Set via the FSL `machine_author` directive.
* @returns An array of author name strings.
*/
machine_author(): Array<string>;
/** Get the machine's comment string. Set via the FSL `machine_comment` directive.
* @returns The comment string.
*/
machine_comment(): string;
/** Get the machine's contributor list. Set via the FSL `machine_contributor` directive.
* @returns An array of contributor name strings.
*/
machine_contributor(): Array<string>;
/** Get the machine's definition string. Set via the FSL `machine_definition` directive.
* @returns The definition string.
*/
machine_definition(): string;
/** Get the machine's language (ISO 639-1). Set via the FSL `machine_language` directive.
* @returns The language code string.
*/
machine_language(): string;
/** Get the machine's license string. Set via the FSL `machine_license` directive.
* @returns The license string.
*/
machine_license(): string;
/** Get the machine's name. Set via the FSL `machine_name` directive.
* @returns The machine name string.
*/
machine_name(): string;
/** Get the machine's version string. Set via the FSL `machine_version` directive.
* @returns The version string.
*/
machine_version(): string;
/** Get the raw state declaration objects as parsed from the FSL source.
* @returns An array of raw state declaration objects.
*/
raw_state_declarations(): Array<Object>;
/** Get the processed state declaration for a specific state.
* @param which - The state to look up.
* @returns The {@link JssmStateDeclaration} for the given state.
*/
state_declaration(which: StateType): JssmStateDeclaration;
/** Get all processed state declarations as a Map.
* @returns A `Map` from state name to {@link JssmStateDeclaration}.
*/
state_declarations(): Map<StateType, JssmStateDeclaration>;
/** Get the FSL language version this machine was compiled under.
* @returns The FSL version string.
*/
fsl_version(): string;
/** Get the complete internal state of the machine as a serializable
* structure. Includes actions, edges, edge map, named transitions,
* reverse actions, current state, and states map.
* @returns A {@link JssmMachineInternalState} snapshot.
*/
machine_state(): JssmMachineInternalState<mDT>;
/*********
*
* List all the states known by the machine. Please note that the order of
* these states is not guaranteed.
*
* ```typescript
* import * as jssm from 'jssm';
*
* const lswitch = jssm.from('on <=> off;');
* console.log( lswitch.states() ); // ['on', 'off']
* ```
*
* @typeparam mDT The type of the machine data member; usually omitted
*
* @returns An array of all state names in the machine.
*
*/
states(): Array<StateType>;
/** Get the internal state descriptor for a given state name.
* @param whichState - The state to look up.
* @returns The {@link JssmGenericState} descriptor.
* @throws {JssmError} If the state does not exist.
*/
state_for(whichState: StateType): JssmGenericState;
/*********
*
* Check whether the machine knows a given state.
*
* ```typescript
* import * as jssm from 'jssm';
*
* const lswitch = jssm.from('on <=> off;');
*
* console.log( lswitch.has_state('off') ); // true
* console.log( lswitch.has_state('dance') ); // false
* ```
*
* @typeparam mDT The type of the machine data member; usually omitted
*
* @param whichState The state to be checked for existence.
*
* @returns `true` if the state exists, `false` otherwise.
*
*/
has_state(whichState: StateType): boolean;
/*********
*
* Lists all edges of a machine.
*
* ```typescript
* import { sm } from 'jssm';
*
* const lswitch = sm`on 'toggle' <=> 'toggle' off;`;
*
* lswitch.list_edges();
* [
* {
* from: 'on',
* to: 'off',
* kind: 'main',
* forced_only: false,
* main_path: true,
* action: 'toggle'
* },
* {
* from: 'off',
* to: 'on',
* kind: 'main',
* forced_only: false,
* main_path: true,
* action: 'toggle'
* }
* ]
* ```
*
* @typeparam mDT The type of the machine data member; usually omitted
*
* @returns An array of all {@link JssmTransition} edge objects.
*
*/
list_edges(): Array<JssmTransition<StateType, mDT>>;
/** Get the map of named transitions (transitions with explicit names).
* @returns A `Map` from transition name to edge index.
*/
list_named_transitions(): Map<StateType, number>;
/** List all distinct action names defined anywhere in the machine.
* @returns An array of action name strings.
*/
list_actions(): Array<StateType>;
/** Whether any actions are defined on this machine.
* @returns `true` if the machine has at least one action.
*/
get uses_actions(): boolean;
/** Whether any forced (`~>`) transitions exist in this machine.
* @returns `true` if at least one forced transition is defined.
*/
get uses_forced_transitions(): boolean;
/*********
*
* Check if the code that built the machine allows overriding state and data.
*
* @returns The override permission from the FSL source code.
*
*/
get code_allows_override(): JssmAllowsOverride;
/*********
*
* Check if the machine config allows overriding state and data.
*
* @returns The override permission from the runtime config.
*
*/
get config_allows_override(): JssmAllowsOverride;
/*********
*
* Check if a machine allows overriding state and data. Resolves the
* combined effect of code and config permissions — config may not be
* less strict than code.
*
* @returns The effective override permission.
*
*/
get allows_override(): JssmAllowsOverride;
/** List all available theme names.
* @returns An array of theme name strings.
*/
all_themes(): FslTheme[];
/** List the character ranges accepted by the FSL grammar in any but the
* first position of a state name (atom). Each entry is an inclusive
* `{from, to}` range of single Unicode characters.
*
* @returns An array of `{from, to}` inclusive character ranges.
*
* @example
* const m = sm`a -> b;`;
* m.all_state_name_chars().some(r => '+' >= r.from && '+' <= r.to); // true
*/
all_state_name_chars(): ReadonlyArray<{
from: string;
to: string;
}>;
/** List the character ranges accepted by the FSL grammar in the first
* position of a state name (atom). Narrower than
* {@link all_state_name_chars}: notably omits `+`, `(`, `)`, `&`, `#`, `@`.
*
* @returns An array of `{from, to}` inclusive character ranges.
*
* @example
* const m = sm`a -> b;`;
* m.all_state_name_first_chars().some(r => '+' >= r.from && '+' <= r.to); // false
*/
all_state_name_first_chars(): ReadonlyArray<{
from: string;
to: string;
}>;
/** List the character ranges accepted inside a single-quoted FSL action
* label without escaping. Space is allowed; the apostrophe `'` is
* explicitly excluded since it terminates the label.
*
* @returns An array of `{from, to}` inclusive character ranges.
*
* @example
* const m = sm`a -> b;`;
* m.all_action_label_chars().some(r => ' ' >= r.from && ' ' <= r.to); // true
* m.all_action_label_chars().some(r => "'" >= r.from && "'" <= r.to); // false
*/
all_action_label_chars(): ReadonlyArray<{
from: string;
to: string;
}>;
/** Get the active theme(s) for this machine. Always stored as an array
* internally; the union return type exists for setter compatibility.
* @returns The current theme or array of themes.
*/
get themes(): FslTheme | FslTheme[];
/** Set the active theme(s). Accepts a single theme name or an array.
* @param to - A theme name or array of theme names to apply.
*/
set themes(to: FslTheme | FslTheme[]);
/** Get the flow direction for graph layout (e.g. `'right'`, `'down'`).
* Set via the FSL `flow` directive.
* @returns The current flow direction.
*/
flow(): FslDirection;
/** Look up a transition's edge index by source and target state names.
* @param from - Source state name.
* @param to - Target state name.
* @returns The edge index in the edges array, or `undefined` if no
* such transition exists.
*/
get_transition_by_state_names(from: StateType, to: StateType): number;
/** Look up the full transition object for a given source→target pair.
* @param from - Source state name.
* @param to - Target state name.
* @returns The {@link JssmTransition} object, or `undefined` if none exists.
*/
lookup_transition_for(from: StateType, to: StateType): JssmTransition<StateType, mDT>;
/********
*
* List all transitions attached to the current state, sorted by entrance and
* exit. The order of each sublist is not defined. A node could appear in
* both lists.
*
* ```typescript
* import { sm } from 'jssm';
*
* const light = sm`red 'next' -> green 'next' -> yellow 'next' -> red; [red yellow green] 'shutdown' ~> off 'start' -> red;`;
*
* light.state(); // 'red'
* light.list_transitions(); // { entrances: [ 'yellow', 'off' ], exits: [ 'green', 'off' ] }
* ```
*
* @typeparam mDT The type of the machine data member; usually omitted
*
* @param whichState The state whose transitions to have listed
*
*/
list_transitions(whichState?: StateType): JssmTransitionList;
/********
*
* List all entrances attached to the current state. Please note that the
* order of the list is not defined. This list includes both unforced and
* forced entrances; if this isn't desired, consider
* {@link list_unforced_entrances} or {@link list_forced_entrances} as
* appropriate.
*
* ```typescript
* import { sm } from 'jssm';
*
* const light = sm`red 'next' -> green 'next' -> yellow 'next' -> red; [red yellow gre