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 = { 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 = (OldState: StateType$1, NewState: StateType$1, OldData: DataType, NewData: DataType) => boolean; declare type JssmTransitionPermitterMaybeArray = JssmTransitionPermitter | Array>; /** * 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 = { from: StateType; to: StateType; after_time?: number; se?: JssmCompileSe; name?: StateType; action?: StateType; check?: JssmTransitionPermitterMaybeArray; 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 = JssmTransition[]; /** * 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; exits: Array; }; /** * 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; name: StateType$1; to: Array; 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 = { internal_state_impl_version: 1; state: StateType$1; states: Map; named_transitions: Map; edge_map: Map>; actions: Map>; reverse_actions: Map>; edges: Array>; }; declare type JssmStatePermitter = (OldState: StateType$1, NewState: StateType$1, OldData: DataType, NewData: DataType) => boolean; declare type JssmStatePermitterMaybeArray = JssmStatePermitter | Array>; /** * 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; 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; 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 = { graph_layout?: JssmLayout; complete?: Array; transitions: JssmTransitions; theme?: FslTheme[]; flow?: FslDirection; name?: string; data?: DataType; nodes?: Array; check?: JssmStatePermitterMaybeArray; 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; end_states?: Array; initial_state?: StateType; start_states_no_enforce?: boolean; state_declaration?: Object[]; property_definition?: JssmPropertyDefinition[]; state_property?: JssmPropertyDefinition[]; arrange_declaration?: Array>; arrange_start_declaration?: Array>; arrange_end_declaration?: Array>; machine_author?: string | Array; machine_comment?: string; machine_contributor?: string | Array; 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 = { to: StateType; se?: JssmCompileSe; kind: JssmArrow; l_action?: StateType; r_action?: StateType; l_probability: number; r_probability: number; l_after?: number; r_after?: number; }; declare type BasicHookDescription = { kind: 'hook'; from: string; to: string; handler: HookHandler; }; declare type HookDescriptionWithAction = { kind: 'named'; from: string; to: string; action: string; handler: HookHandler; }; declare type StandardTransitionHook = { kind: 'standard transition'; handler: HookHandler; }; declare type MainTransitionHook = { kind: 'main transition'; handler: HookHandler; }; declare type ForcedTransitionHook = { kind: 'forced transition'; handler: HookHandler; }; declare type AnyTransitionHook = { kind: 'any transition'; handler: HookHandler; }; declare type GlobalActionHook = { kind: 'global action'; action: string; handler: HookHandler; }; declare type AnyActionHook = { kind: 'any action'; handler: HookHandler; }; declare type EntryHook = { kind: 'entry'; to: string; handler: HookHandler; }; declare type ExitHook = { kind: 'exit'; from: string; handler: HookHandler; }; declare type AfterHook = { kind: 'after'; from: string; handler: HookHandler; }; declare type PostBasicHookDescription = { kind: 'post hook'; from: string; to: string; handler: PostHookHandler; }; declare type PostHookDescriptionWithAction = { kind: 'post named'; from: string; to: string; action: string; handler: PostHookHandler; }; declare type PostStandardTransitionHook = { kind: 'post standard transition'; handler: PostHookHandler; }; declare type PostMainTransitionHook = { kind: 'post main transition'; handler: PostHookHandler; }; declare type PostForcedTransitionHook = { kind: 'post forced transition'; handler: PostHookHandler; }; declare type PostAnyTransitionHook = { kind: 'post any transition'; handler: PostHookHandler; }; declare type PostGlobalActionHook = { kind: 'post global action'; action: string; handler: PostHookHandler; }; declare type PostAnyActionHook = { kind: 'post any action'; handler: PostHookHandler; }; declare type PostEntryHook = { kind: 'post entry'; to: string; handler: PostHookHandler; }; declare type PostExitHook = { kind: 'post exit'; from: string; handler: PostHookHandler; }; declare type PreEverythingHook = { kind: 'pre everything'; handler: EverythingHookHandler; }; declare type EverythingHook = { kind: 'everything'; handler: EverythingHookHandler; }; declare type PrePostEverythingHook = { kind: 'pre post everything'; handler: PostEverythingHookHandler; }; declare type PostEverythingHook = { kind: 'post everything'; handler: PostEverythingHookHandler; }; /** * 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 = BasicHookDescription | HookDescriptionWithAction | GlobalActionHook | AnyActionHook | StandardTransitionHook | MainTransitionHook | ForcedTransitionHook | AnyTransitionHook | EntryHook | ExitHook | AfterHook | PostBasicHookDescription | PostHookDescriptionWithAction | PostGlobalActionHook | PostAnyActionHook | PostStandardTransitionHook | PostMainTransitionHook | PostForcedTransitionHook | PostAnyTransitionHook | PostEntryHook | PostExitHook | PreEverythingHook | EverythingHook | PrePostEverythingHook | PostEverythingHook; /** * 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 = { 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 = true | false | undefined | void | HookComplexResult; /** * 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 = { 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 = HookContext & { 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 = (hook_context: HookContext) => HookResult; /** * 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 = (hook_context: HookContext) => 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 = (hook_context: EverythingHookContext) => HookResult; /** * Signature of an "everything" post-transition hook handler. Like * {@link PostHookHandler} but receives an {@link EverythingHookContext}. * The return value is ignored. */ declare type PostEverythingHookHandler = (hook_context: EverythingHookContext) => 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 = 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 { _state: StateType; _states: Map; _edges: Array>; _edge_map: Map>; _named_transitions: Map; _actions: Map>; _reverse_actions: Map>; _reverse_action_targets: Map>; _start_states: Set; _end_states: Set; _machine_author?: Array; _machine_comment?: string; _machine_contributor?: Array; _machine_definition?: string; _machine_language?: string; _machine_license?: string; _machine_name?: string; _machine_version?: string; _fsl_version?: string; _raw_state_declaration?: Array; _state_declarations: Map; _data?: mDT; _instance_name: string; _rng_seed: number; _rng: JssmRng; _graph_layout: JssmLayout; _dot_preamble: string; _arrange_declaration: Array>; _arrange_start_declaration: Array>; _arrange_end_declaration: Array>; _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>; _named_hooks: Map>; _entry_hooks: Map>; _exit_hooks: Map>; _after_hooks: Map>; _global_action_hooks: Map>; _any_action_hook: HookHandler | undefined; _standard_transition_hook: HookHandler | undefined; _main_transition_hook: HookHandler | undefined; _forced_transition_hook: HookHandler | undefined; _any_transition_hook: HookHandler | 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>; _post_named_hooks: Map>; _post_entry_hooks: Map>; _post_exit_hooks: Map>; _post_global_action_hooks: Map>; _post_any_action_hook: HookHandler | undefined; _post_standard_transition_hook: HookHandler | undefined; _post_main_transition_hook: HookHandler | undefined; _post_forced_transition_hook: HookHandler | undefined; _post_any_transition_hook: HookHandler | undefined; _pre_everything_hook: EverythingHookHandler | undefined; _everything_hook: EverythingHookHandler | undefined; _pre_post_everything_hook: PostEverythingHookHandler | undefined; _post_everything_hook: PostEverythingHookHandler | undefined; _property_keys: Set; _default_properties: Map; _state_properties: Map; _required_properties: Set; _history: JssmHistory; _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; _time_source: () => number; _create_started: number; _created: number; _after_mapping: Map; _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); /******** * * 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; /** 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; /** 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; /** 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; /** 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; /** 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; /********* * * 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; /** 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>; /** Get the map of named transitions (transitions with explicit names). * @returns A `Map` from transition name to edge index. */ list_named_transitions(): Map; /** List all distinct action names defined anywhere in the machine. * @returns An array of action name strings. */ list_actions(): Array; /** 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; /******** * * 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 green] 'shutdown' ~> off 'start' -> red;`; * * light.state(); // 'red' * light.list_entrances(); // [ 'yellow', 'off' ] * ``` * * @typeparam mDT The type of the machine data member; usually omitted * * @param whichState The state whose entrances to have listed * */ list_entrances(whichState?: StateType): Array; /******** * * List all exits attached to the current state. Please note that the order * of the list is not defined. This list includes both unforced and forced * exits; if this isn't desired, consider {@link list_unforced_exits} or * {@link list_forced_exits} as appropriate. * * ```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_exits(); // [ 'green', 'off' ] * ``` * * @typeparam mDT The type of the machine data member; usually omitted * * @param whichState The state whose exits to have listed * */ list_exits(whichState?: StateType): Array; /** Get the transitions available from a state for use by the probabilistic * walk system. * * If any exit declares a `probability`, only those probability-bearing * exits are returned, so that non-probability peers cannot dilute the * declared distribution. If no exit declares a `probability`, every * legal (non-forced) exit is returned, which `weighted_rand_select` * treats as equal weight. Forced-only exits (`~>`) are always excluded, * since they cannot be taken by an ordinary `transition()` call. * * Fixes StoneCypher/fsl#1325, in which the function previously returned * every exit unconditionally — including forced-only exits and exits * with no `probability`, which distorted the weighted distribution. * * @param whichState - The state to inspect. * @returns An array of {@link JssmTransition} edges exiting the state, * filtered as described above. May be empty. * @throws {JssmError} If the state does not exist. */ probable_exits_for(whichState: StateType): Array>; /** Take a single random transition from the current state, weighted by * edge probabilities. * @returns `true` if a transition was taken, `false` otherwise. */ probabilistic_transition(): boolean; /** Take `n` consecutive probabilistic transitions and return the sequence * of states visited (before each transition). * @param n - Number of steps to walk. * @returns An array of state names visited during the walk. */ probabilistic_walk(n: number): Array; /** Take `n` probabilistic steps and return a histograph of how many times * each state was visited. * @param n - Number of steps to walk. * @returns A `Map` from state name to visit count. */ probabilistic_histo_walk(n: number): Map; /******** * * List all actions available from this state. Please note that the order of * the actions is not guaranteed. * * ```typescript * import { sm } from 'jssm'; * * const machine = sm` * red 'next' -> green 'next' -> yellow 'next' -> red; * [red yellow green] 'shutdown' ~> off 'start' -> red; * `; * * console.log( machine.state() ); // logs 'red' * console.log( machine.actions() ); // logs ['next', 'shutdown'] * * machine.action('next'); // true * console.log( machine.state() ); // logs 'green' * console.log( machine.actions() ); // logs ['next', 'shutdown'] * * machine.action('shutdown'); // true * console.log( machine.state() ); // logs 'off' * console.log( machine.actions() ); // logs ['start'] * * machine.action('start'); // true * console.log( machine.state() ); // logs 'red' * console.log( machine.actions() ); // logs ['next', 'shutdown'] * ``` * * @typeparam mDT The type of the machine data member; usually omitted * * @param whichState The state whose actions to list. Defaults to the * current state. * * @returns An array of action names available from the given state. * */ actions(whichState?: StateType): Array; /******** * * List all states that have a specific action attached. Please note that * the order of the states is not guaranteed. * * ```typescript * import { sm } from 'jssm'; * * const machine = sm` * red 'next' -> green 'next' -> yellow 'next' -> red; * [red yellow green] 'shutdown' ~> off 'start' -> red; * `; * * console.log( machine.list_states_having_action('next') ); // ['red', 'green', 'yellow'] * console.log( machine.list_states_having_action('start') ); // ['off'] * ``` * * @typeparam mDT The type of the machine data member; usually omitted * * @param whichState The action to be checked for associated states * */ list_states_having_action(whichState: StateType): Array; /** List all action names available as exits from a given state. * @param whichState - The state to inspect. Defaults to the current state. * @returns An array of action name strings. * @throws {JssmError} If the state does not exist. */ list_exit_actions(whichState?: StateType): Array; /** List all action exits from a state with their probabilities. * @param whichState - The state to inspect. Defaults to the current state. * @returns An array of `{ action, probability }` objects. * @throws {JssmError} If the state does not exist. */ probable_action_exits(whichState?: StateType): Array; /** Check whether a state has no incoming transitions (unreachable after start). * @param whichState - The state to check. * @returns `true` if the state has zero entrances. * @throws {JssmError} If the state does not exist. */ is_unenterable(whichState: StateType): boolean; /** Check whether any state in the machine is unenterable. * @returns `true` if at least one state has no incoming transitions. */ has_unenterables(): boolean; /** Check whether the current state is terminal (has no exits). * @returns `true` if the current state has zero exits. */ is_terminal(): boolean; /** Check whether a specific state is terminal (has no exits). * @param whichState - The state to check. * @returns `true` if the state has zero exits. * @throws {JssmError} If the state does not exist. */ state_is_terminal(whichState: StateType): boolean; /** Check whether any state in the machine is terminal. * @returns `true` if at least one state has no exits. */ has_terminals(): boolean; /** Check whether the current state is complete (every exit has an action). * @returns `true` if the current state is complete. */ is_complete(): boolean; /** Check whether a specific state is complete (every exit has an action). * @param whichState - The state to check. * @returns `true` if the state is complete. * @throws {JssmError} If the state does not exist. */ state_is_complete(whichState: StateType): boolean; /** Check whether any state in the machine is complete. * @returns `true` if at least one state is complete. */ has_completes(): boolean; /** Low-level hook registration. Installs a handler described by a * {@link HookDescription} into the appropriate internal map. Prefer the * convenience wrappers ({@link hook}, {@link hook_entry}, etc.) over * calling this directly. * @param HookDesc - A hook descriptor specifying kind, states, and handler. */ set_hook(HookDesc: HookDescription): void; /** Register a pre-transition hook on a specific edge. Fires before * transitioning from `from` to `to`. If the handler returns `false`, the * transition is blocked. * * ```typescript * const m = sm`a -> b -> c;`; * m.hook('a', 'b', () => console.log('a->b')); * ``` * * @param from - Source state name. * @param to - Target state name. * @param handler - Callback invoked before the transition. * @returns `this` for chaining. */ hook(from: string, to: string, handler: HookHandler): Machine; /** Register a pre-transition hook on a specific action-labeled edge. * @param from - Source state name. * @param to - Target state name. * @param action - The action label that triggers this hook. * @param handler - Callback invoked before the transition. * @returns `this` for chaining. */ hook_action(from: string, to: string, action: string, handler: HookHandler): Machine; /** Register a pre-transition hook on any edge triggered by a specific action. * @param action - The action name to hook. * @param handler - Callback invoked before any transition with this action. * @returns `this` for chaining. */ hook_global_action(action: string, handler: HookHandler): Machine; /** Register a pre-transition hook on any action-driven transition. * @param handler - Callback invoked before any action transition. * @returns `this` for chaining. */ hook_any_action(handler: HookHandler): Machine; /** Register a pre-transition hook on any standard (`->`) transition. * @param handler - Callback invoked before any legal transition. * @returns `this` for chaining. */ hook_standard_transition(handler: HookHandler): Machine; /** Register a pre-transition hook on any main-path (`=>`) transition. * @param handler - Callback invoked before any main transition. * @returns `this` for chaining. */ hook_main_transition(handler: HookHandler): Machine; /** Register a pre-transition hook on any forced (`~>`) transition. * @param handler - Callback invoked before any forced transition. * @returns `this` for chaining. */ hook_forced_transition(handler: HookHandler): Machine; /** Register a pre-transition hook on any transition regardless of kind. * @param handler - Callback invoked before every transition. * @returns `this` for chaining. */ hook_any_transition(handler: HookHandler): Machine; /** Register a hook that fires when entering a specific state. * @param to - The state being entered. * @param handler - Callback invoked on entry. * @returns `this` for chaining. */ hook_entry(to: string, handler: HookHandler): Machine; /** Register a hook that fires when leaving a specific state. * @param from - The state being exited. * @param handler - Callback invoked on exit. * @returns `this` for chaining. */ hook_exit(from: string, handler: HookHandler): Machine; /** Register a hook that fires after leaving a specific state (post-exit). * @param from - The state that was exited. * @param handler - Callback invoked after exit completes. * @returns `this` for chaining. */ hook_after(from: string, handler: HookHandler): Machine; /** Post-transition hook on a specific edge. Fires after the transition * from `from` to `to` has completed. Cannot block the transition. * @param from - Source state name. * @param to - Target state name. * @param handler - Callback invoked after the transition. * @returns `this` for chaining. */ post_hook(from: string, to: string, handler: HookHandler): Machine; /** Post-transition hook on a specific action-labeled edge. * @param from - Source state name. * @param to - Target state name. * @param action - The action label. * @param handler - Callback invoked after the transition. * @returns `this` for chaining. */ post_hook_action(from: string, to: string, action: string, handler: HookHandler): Machine; /** Post-transition hook on any edge triggered by a specific action. * @param action - The action name. * @param handler - Callback invoked after any transition with this action. * @returns `this` for chaining. */ post_hook_global_action(action: string, handler: HookHandler): Machine; /** Post-transition hook on any action-driven transition. * @param handler - Callback invoked after any action transition. * @returns `this` for chaining. */ post_hook_any_action(handler: HookHandler): Machine; /** Post-transition hook on any standard (`->`) transition. * @param handler - Callback invoked after any legal transition. * @returns `this` for chaining. */ post_hook_standard_transition(handler: HookHandler): Machine; /** Post-transition hook on any main-path (`=>`) transition. * @param handler - Callback invoked after any main transition. * @returns `this` for chaining. */ post_hook_main_transition(handler: HookHandler): Machine; /** Post-transition hook on any forced (`~>`) transition. * @param handler - Callback invoked after any forced transition. * @returns `this` for chaining. */ post_hook_forced_transition(handler: HookHandler): Machine; /** Post-transition hook on any transition regardless of kind. * @param handler - Callback invoked after every transition. * @returns `this` for chaining. */ post_hook_any_transition(handler: HookHandler): Machine; /** Post-transition hook that fires after entering a specific state. * @param to - The state that was entered. * @param handler - Callback invoked after entry. * @returns `this` for chaining. */ post_hook_entry(to: string, handler: HookHandler): Machine; /** Post-transition hook that fires after leaving a specific state. * @param from - The state that was exited. * @param handler - Callback invoked after exit. * @returns `this` for chaining. */ post_hook_exit(from: string, handler: HookHandler): Machine; /** Register a pre-transition hook that fires **before** all other pre-hooks * on every transition. If the handler returns `false`, the transition is * blocked. The handler receives an {@link EverythingHookContext} whose * `hook_name` is `'pre everything'`. * * ```typescript * const m = sm`a -> b -> c;`; * m.hook_pre_everything(({ hook_name }) => { * console.log(`${hook_name} fired`); * return true; * }); * ``` * * @param handler - Callback invoked before all other pre-hooks. * @returns `this` for chaining. */ hook_pre_everything(handler: EverythingHookHandler): Machine; /** Register a pre-transition hook that fires **after** all other pre-hooks * on every transition. If the handler returns `false`, the transition is * blocked. The handler receives an {@link EverythingHookContext} whose * `hook_name` is `'everything'`. * * ```typescript * const m = sm`a -> b -> c;`; * m.hook_everything(({ hook_name }) => { * console.log(`${hook_name} fired`); * return true; * }); * ``` * * @param handler - Callback invoked after all other pre-hooks. * @returns `this` for chaining. */ hook_everything(handler: EverythingHookHandler): Machine; /** Register a post-transition hook that fires **after** all other * post-hooks on every transition. Cannot block the transition. The * handler receives an {@link EverythingHookContext} whose `hook_name` is * `'post everything'`. * * ```typescript * const m = sm`a -> b -> c;`; * m.hook_post_everything(({ hook_name }) => { * console.log(`${hook_name} fired`); * }); * ``` * * @param handler - Callback invoked after all other post-hooks. * @returns `this` for chaining. */ hook_post_everything(handler: PostEverythingHookHandler): Machine; /** Register a post-transition hook that fires **before** all other * post-hooks on every transition. Cannot block the transition. The * handler receives an {@link EverythingHookContext} whose `hook_name` is * `'pre post everything'`. * * ```typescript * const m = sm`a -> b -> c;`; * m.hook_pre_post_everything(({ hook_name }) => { * console.log(`${hook_name} fired`); * }); * ``` * * @param handler - Callback invoked before all other post-hooks. * @returns `this` for chaining. */ hook_pre_post_everything(handler: PostEverythingHookHandler): Machine; /** Get the current RNG seed used for probabilistic transitions. * @returns The numeric seed value. */ get rng_seed(): number; /** Set the RNG seed. Pass `undefined` to reseed from the current time. * Resets the internal PRNG so subsequent probabilistic operations use the * new seed. * @param to - The seed value, or `undefined` for time-based seeding. */ set rng_seed(to: number | undefined); /** Get all edges between two states (there can be multiple with * different actions). * @param from - Source state name. * @param to - Target state name. * @returns An array of matching {@link JssmTransition} objects. */ edges_between(from: string, to: string): JssmTransition[]; /********* * * Replace the current state and data with no regard to the graph. * * ```typescript * import { sm } from 'jssm'; * * const machine = sm`a -> b -> c;`; * console.log( machine.state() ); // 'a' * * machine.go('b'); * machine.go('c'); * console.log( machine.state() ); // 'c' * * machine.override('a'); * console.log( machine.state() ); // 'a' * ``` * */ override(newState: StateType, newData?: mDT | undefined): void; /********* * * Shared transition core used by {@link transition}, {@link force_transition}, * and {@link action}. Runs validation, fires the full hook pipeline (pre- * everything, any-action, after, any-transition, exit, named, basic, * edge-type, entry, everything), commits the new state if nothing * rejected, and returns whether the transition succeeded. * * Not meant for external use. Call one of the public wrappers instead: * - `transition` for an ordinary legal transition * - `force_transition` to bypass the legality check * - `action` to dispatch by action name rather than target state * * @remarks * Known sharp edges, carried over from the original `// TODO` comments: * - The forced-ness behavior needs to be cleaned up a lot here. * - The callbacks are not fully correct across the forced / action / plain * cases and should be revisited. * - When multiple edges exist between two states with different `kind` * values, only the first edge's kind is used to pick the edge-type hook. * * @typeparam mDT The type of the machine data member; usually omitted. * * @param newStateOrAction The target state name (for a plain or forced * transition) or the action name (when `wasAction` is true). * * @param newData Optional replacement machine data to install alongside * the transition. Hooks may further override this via complex results. * * @param wasForced `true` if the caller invoked `force_transition`, in * which case legality is checked against `valid_force_transition` rather * than `valid_transition`. * * @param wasAction `true` if the caller invoked `action`, in which case * `newStateOrAction` is an action name and the target state is looked up * via the current action edge. * * @returns `true` if the transition was valid and every hook passed; * `false` if the transition was invalid or any hook rejected. * * @internal * */ transition_impl(newStateOrAction: StateType, newData: mDT | undefined, wasForced: boolean, wasAction: boolean): boolean; /** If the current state has an `after` timeout configured, schedule it. * Called internally after each transition. */ auto_set_state_timeout(): void; /********* * * Get a truncated history of the recent states and data of the machine. * Turned off by default; configure with `.from('...', {data: 5})` by length, * or set `.history_length` at runtime. * * History *does not contain the current state*. If you want that, call * `.history_inclusive` instead. * * ```typescript * const foo = jssm.from( * "a 'next' -> b 'next' -> c 'next' -> d 'next' -> e;", * { history: 3 } * ); * * foo.action('next'); * foo.action('next'); * foo.action('next'); * foo.action('next'); * * foo.history; // [ ['b',undefined], ['c',undefined], ['d',undefined] ] * ``` * * Notice that the machine's current state, `e`, is not in the returned list. * * @typeparam mDT The type of the machine data member; usually omitted * */ get history(): [string, mDT][]; /********* * * Get a truncated history of the recent states and data of the machine, * including the current state. Turned off by default; configure with * `.from('...', {data: 5})` by length, or set `.history_length` at runtime. * * History inclusive contains the current state. If you only want past * states, call `.history` instead. * * The list returned will be one longer than the history buffer kept, as the * history buffer kept gets the current state added to it to produce this * list. * * ```typescript * const foo = jssm.from( * "a 'next' -> b 'next' -> c 'next' -> d 'next' -> e;", * { history: 3 } * ); * * foo.action('next'); * foo.action('next'); * foo.action('next'); * foo.action('next'); * * foo.history_inclusive; // [ ['b',undefined], ['c',undefined], ['d',undefined], ['e',undefined] ] * ``` * * Notice that the machine's current state, `e`, is in the returned list. * * @typeparam mDT The type of the machine data member; usually omitted * */ get history_inclusive(): [string, mDT][]; /********* * * Find out how long a history this machine is keeping. Defaults to zero. * Settable directly. * * ```typescript * const foo = jssm.from("a -> b;"); * foo.history_length; // 0 * * const bar = jssm.from("a -> b;", { history: 3 }); * foo.history_length; // 3 * foo.history_length = 5; * foo.history_length; // 5 * ``` * * @typeparam mDT The type of the machine data member; usually omitted * */ get history_length(): number; set history_length(to: number); /******** * * Instruct the machine to complete an action. Synonym for {@link do}. * * ```typescript * const light = sm`red 'next' -> green 'next' -> yellow 'next' -> red; [red yellow green] 'shutdown' ~> off 'start' -> red;`; * * light.state(); // 'red' * light.action('next'); // true * light.state(); // 'green' * ``` * * @typeparam mDT The type of the machine data member; usually omitted * * @param actionName The action to engage * * @param newData The data change to insert during the action * * @returns `true` if the action was valid and the transition occurred, * `false` otherwise. * */ action(actionName: StateType, newData?: mDT): boolean; /******** * * Get the standard style for a single state. ***Does not*** include * composition from an applied theme, or things from the underlying base * stylesheet; only the modifications applied by this machine. * * ```typescript * const light = sm`a -> b;`; * console.log(light.standard_state_style); * // {} * * const light = sm`a -> b; state: { shape: circle; };`; * console.log(light.standard_state_style); * // { shape: 'circle' } * ``` * * @typeparam mDT The type of the machine data member; usually omitted * * @returns The {@link JssmStateConfig} for standard states. * */ get standard_state_style(): JssmStateConfig; /******** * * Get the hooked state style. ***Does not*** include * composition from an applied theme, or things from the underlying base * stylesheet; only the modifications applied by this machine. * * The hooked style is only applied to nodes which have a named hook in the * graph. Open hooks set through the external API aren't graphed, because * that would be literally every node. * * ```typescript * const light = sm`a -> b;`; * console.log(light.hooked_state_style); * // {} * * const light = sm`a -> b; hooked_state: { shape: circle; };`; * console.log(light.hooked_state_style); * // { shape: 'circle' } * ``` * * @typeparam mDT The type of the machine data member; usually omitted * * @returns The {@link JssmStateConfig} for hooked states. * */ get hooked_state_style(): JssmStateConfig; /******** * * Get the start state style. ***Does not*** include composition from an * applied theme, or things from the underlying base stylesheet; only the * modifications applied by this machine. * * Start states are defined by the directive `start_states`, or in absentia, * are the first mentioned state. * * ```typescript * const light = sm`a -> b;`; * console.log(light.start_state_style); * // {} * * const light = sm`a -> b; start_state: { shape: circle; };`; * console.log(light.start_state_style); * // { shape: 'circle' } * ``` * * @typeparam mDT The type of the machine data member; usually omitted * * @returns The {@link JssmStateConfig} for start states. * */ get start_state_style(): JssmStateConfig; /******** * * Get the end state style. ***Does not*** include * composition from an applied theme, or things from the underlying base * stylesheet; only the modifications applied by this machine. * * End states are defined in the directive `end_states`, and are distinct * from terminal states. End states are voluntary successful endpoints for a * process. Terminal states are states that cannot be exited. By example, * most error states are terminal states, but not end states. Also, since * some end states can be exited and are determined by hooks, such as * recursive or iterative nodes, there is such a thing as an end state that * is not a terminal state. * * ```typescript * const light = sm`a -> b;`; * console.log(light.standard_state_style); * // {} * * const light = sm`a -> b; end_state: { shape: circle; };`; * console.log(light.standard_state_style); * // { shape: 'circle' } * ``` * * @typeparam mDT The type of the machine data member; usually omitted * * @returns The {@link JssmStateConfig} for end states. * */ get end_state_style(): JssmStateConfig; /******** * * Get the terminal state style. ***Does not*** include * composition from an applied theme, or things from the underlying base * stylesheet; only the modifications applied by this machine. * * Terminal state styles are automatically determined by the machine. Any * state without a valid exit transition is terminal. * * ```typescript * const light = sm`a -> b;`; * console.log(light.terminal_state_style); * // {} * * const light = sm`a -> b; terminal_state: { shape: circle; };`; * console.log(light.terminal_state_style); * // { shape: 'circle' } * ``` * * @typeparam mDT The type of the machine data member; usually omitted * * @returns The {@link JssmStateConfig} for terminal states. * */ get terminal_state_style(): JssmStateConfig; /******** * * Get the style for the active state. ***Does not*** include * composition from an applied theme, or things from the underlying base * stylesheet; only the modifications applied by this machine. * * ```typescript * const light = sm`a -> b;`; * console.log(light.active_state_style); * // {} * * const light = sm`a -> b; active_state: { shape: circle; };`; * console.log(light.active_state_style); * // { shape: 'circle' } * ``` * * @typeparam mDT The type of the machine data member; usually omitted * * @returns The {@link JssmStateConfig} for the active state. * */ get active_state_style(): JssmStateConfig; /******** * * Gets the composite style for a specific node by individually imposing the * style layers on a given object, after determining which layers are * appropriate. * * The order of composition is base, then theme, then user content. Each * item in the stack will be composited independently. First, the base state * style, then the theme state style, then the user state style. * * After the three state styles, we'll composite the hooked styles; then the * terminal styles; then the start styles; then the end styles; finally, the * active styles. Remember, last wins. * * The base state style must exist. All other styles are optional. * * @typeparam mDT The type of the machine data member; usually omitted * * @param state The state to compute the composite style for. * * @returns The fully composited {@link JssmStateConfig} for the given state. * */ style_for(state: StateType): JssmStateConfig; /******** * * Instruct the machine to complete an action. Synonym for {@link action}. * * ```typescript * const light = sm` * off 'start' -> red; * red 'next' -> green 'next' -> yellow 'next' -> red; * [red yellow green] 'shutdown' ~> off; * `; * * light.state(); // 'off' * light.do('start'); // true * light.state(); // 'red' * light.do('next'); // true * light.state(); // 'green' * light.do('next'); // true * light.state(); // 'yellow' * light.do('dance'); // !! false - no such action * light.state(); // 'yellow' * light.do('start'); // !! false - yellow does not have the action start * light.state(); // 'yellow' * ``` * * @typeparam mDT The type of the machine data member; usually omitted * * @param actionName The action to engage * * @param newData The data change to insert during the action * * @returns `true` if the action was valid and the transition occurred, * `false` otherwise. * */ do(actionName: StateType, newData?: mDT): boolean; /******** * * Instruct the machine to complete a transition. Synonym for {@link go}. * * ```typescript * const light = sm` * off 'start' -> red; * red 'next' -> green 'next' -> yellow 'next' -> red; * [red yellow green] 'shutdown' ~> off; * `; * * light.state(); // 'off' * light.go('red'); // true * light.state(); // 'red' * light.go('green'); // true * light.state(); // 'green' * light.go('blue'); // !! false - no such state * light.state(); // 'green' * light.go('red'); // !! false - green may not go directly to red, only to yellow * light.state(); // 'green' * ``` * * @typeparam mDT The type of the machine data member; usually omitted * * @param newState The state to switch to * * @param newData The data change to insert during the transition * * @returns `true` if the transition was legal and occurred, `false` otherwise. * */ transition(newState: StateType, newData?: mDT): boolean; /******** * * Instruct the machine to complete a transition. Synonym for {@link transition}. * * ```typescript * const light = sm`red -> green -> yellow -> red; [red yellow green] 'shutdown' ~> off 'start' -> red;`; * * light.state(); // 'red' * light.go('green'); // true * light.state(); // 'green' * ``` * * @typeparam mDT The type of the machine data member; usually omitted * * @param newState The state to switch to * * @param newData The data change to insert during the transition * * @returns `true` if the transition was legal and occurred, `false` otherwise. * */ go(newState: StateType, newData?: mDT): boolean; /******** * * Instruct the machine to complete a forced transition (which will reject if * called with a normal {@link transition} call.) * * ```typescript * const light = sm`red -> green -> yellow -> red; [red yellow green] 'shutdown' ~> off 'start' -> red;`; * * light.state(); // 'red' * light.transition('off'); // false * light.state(); // 'red' * light.force_transition('off'); // true * light.state(); // 'off' * ``` * * @typeparam mDT The type of the machine data member; usually omitted * * @param newState The state to switch to * * @param newData The data change to insert during the transition * * @returns `true` if a transition (forced or otherwise) existed and occurred, * `false` otherwise. * */ force_transition(newState: StateType, newData?: mDT): boolean; /** Get the edge index for an action from the current state. * @param action - The action name. * @returns The edge index, or `undefined` if the action is not available. */ current_action_for(action: StateType): number; /** Get the full transition object for an action from the current state. * @param action - The action name. * @returns The {@link JssmTransition} object. * @throws {JssmError} If the action is not available from the current state. */ current_action_edge_for(action: StateType): JssmTransition; /** Check whether an action is available from the current state. * @param action - The action name to check. * @param _newData - Reserved for future data validation. * @returns `true` if the action can be taken. */ valid_action(action: StateType, _newData?: mDT): boolean; /** Check whether a transition to a given state is legal (non-forced) from * the current state. * @param newState - The target state. * @param _newData - Reserved for future data validation. * @returns `true` if the transition is legal. */ valid_transition(newState: StateType, _newData?: mDT): boolean; /** Check whether a forced transition to a given state exists from the * current state. * @param newState - The target state. * @param _newData - Reserved for future data validation. * @returns `true` if a forced (or any) transition exists. */ valid_force_transition(newState: StateType, _newData?: mDT): boolean; /** Get the instance name of this machine, if one was assigned at creation. * @returns The instance name string, or `undefined`. */ instance_name(): string | undefined; /** Get the creation date of this machine as a `Date` object. * @returns A `Date` representing when the machine was created. */ get creation_date(): Date; /** Get the creation timestamp (milliseconds since epoch). * @returns The timestamp as a number. */ get creation_timestamp(): number; /** Get the timestamp when construction began (before parsing). * @returns The start-of-construction timestamp as a number. */ get create_start_time(): number; /** Schedule an automatic transition to `next_state` after `after_time` * milliseconds. Only one timeout may be active at a time. * @param next_state - The state to transition to when the timer fires. * @param after_time - Delay in milliseconds. * @throws {JssmError} If a timeout is already pending. */ set_state_timeout(next_state: StateType, after_time: number): void; /** Cancel any pending state timeout. Safe to call when no timeout is active. */ clear_state_timeout(): void; /** Get the configured `after` timeout for a given state, if any. * @param which_state - The state to look up. * @returns A `[targetState, delayMs]` tuple, or `undefined` if no timeout * is configured for that state. */ state_timeout_for(which_state: StateType): [StateType, number] | undefined; /** Get the configured `after` timeout for the current state, if any. * @returns A `[targetState, delayMs]` tuple, or `undefined`. */ current_state_timeout(): [StateType, number] | undefined; /** Convenience method to create a new machine from a tagged template literal. * Equivalent to calling the top-level `sm` function. * @param template_strings - The template string array. * @param remainder - Interpolated values. * @returns A new {@link Machine} instance. */ sm(template_strings: TemplateStringsArray, ...remainder: any[]): Machine; } /** * Inject runtime configuration for jssm/viz. Currently only accepts a * custom `DOMParser` constructor for use by `*_svg_element` functions in * environments that do not provide one globally (e.g. Node + jsdom). * * Idempotent — last call wins. No-op if called with no recognized keys. * * ```typescript * // Node, with jsdom: * import { JSDOM } from 'jsdom'; * import { configure, fsl_to_svg_element } from 'jssm/viz'; * * configure({ DOMParser: new JSDOM().window.DOMParser }); * const el = await fsl_to_svg_element('a -> b;'); * ``` * * @param opts Configuration overrides. * @param opts.DOMParser Constructor compatible with the WHATWG `DOMParser` * interface. Used as a fallback when `globalThis.DOMParser` is undefined. * * @throws {JssmError} if `DOMParser` is provided and is not a constructor. */ declare function configure(opts: { DOMParser?: typeof globalThis.DOMParser; }): void; /** * Look up a color from the default viz palette by key, returning empty * string if the key is unknown (so it disappears in feature concatenation). * * @internal */ declare function vc(col: string): string; /** * Build a graphviz-safe node identifier for a state, by index. Accepts * either a `string[]` (used historically; O(n) per call) or a * precomputed `Map` (used by rendering hot paths; O(1) * per call). The map form is used during dot generation; the array * form is retained for direct test access via `_test`. * * @internal */ declare function node_of(state: string, state_index: string[] | Map): string; /** * Convert an 8-channel hex color (`#RRGGBBAA`) to a 6-channel hex color * (`#RRGGBB`), discarding the alpha channel. Throws if the input is not * a 9-character `#`-prefixed string. * * Graphviz dot does not support alpha; this is a lossy projection. * * @internal */ declare function color8to6(color8: string): string; /** * Variant of {@link color8to6} that passes `undefined` through. * * @internal */ declare function u_color8to6(color8?: string): string | undefined; /** * Read the graphviz shape for a state through {@link jssm.Machine.style_for}, * so theme-supplied shapes are honoured along with per-state declarations. * Returns `undefined` if neither a theme nor a state declaration supplies a * shape. * * @internal */ declare function shape_for_state(u_jssm: Machine, state: string): string | undefined; /** * Read the image filename for a state through {@link jssm.Machine.style_for}, * so theme-supplied images are honoured along with per-state declarations. * Returns `undefined` if neither a theme nor a state declaration supplies an * image. * * @internal */ declare function image_for_state(u_jssm: Machine, state: string): string | undefined; /** * Compose a graphviz `style` string for a state by looking up its merged * style via {@link jssm.Machine.style_for}, then delegating to * {@link compose_style_string}. Theme-supplied `corners` and `lineStyle` * are honoured along with per-state declarations. * * @internal */ declare function style_for_state(u_jssm: Machine, state: string): string; /** * Render a {@link jssm.Machine} as a graphviz dot string. * * An optional `footer` may be supplied via `opts.footer`; it is emitted * verbatim just before the closing `}` of the dot source, after all * arrange declarations. This is a function-argument-only feature for * the moment — a machine-attribute equivalent is planned as a follow-up. * * ```typescript * import { sm } from 'jssm'; * import { machine_to_dot } from 'jssm/viz'; * * const dot = machine_to_dot(sm`a -> b;`); * // 'digraph G { ... }' * * const dot_with_footer = machine_to_dot(sm`a -> b;`, { footer: 'labelloc="b"; label="caption";' }); * // 'digraph G { ... labelloc="b"; label="caption"; }' * ``` * * @param u_jssm The machine to render. * @param opts Optional rendering options. * @param opts.footer Optional verbatim dot source inserted just before the closing `}`. * @returns A complete graphviz dot source string. */ declare function machine_to_dot(u_jssm: Machine, opts?: { footer?: string; }): string; /** * Render an FSL string directly to graphviz dot source. * * ```typescript * import { fsl_to_dot } from 'jssm/viz'; * const dot = fsl_to_dot('a -> b;'); * * const dot_with_footer = fsl_to_dot('a -> b;', { footer: 'label="caption";' }); * // 'digraph G { ... label="caption"; }' * ``` * * @param fsl The FSL source. * @param opts Optional rendering options. * @param opts.footer Optional verbatim dot source inserted just before the closing `}`. * @returns A complete graphviz dot source string. */ declare function fsl_to_dot(fsl: string, opts?: { footer?: string; }): string; /** * Render a graphviz dot source string to SVG using `@viz-js/viz`. The * underlying viz instance is lazy-initialized on first call and cached for * the lifetime of the module. * * ```typescript * const svg = await dot_to_svg('digraph G { a -> b }'); * const svg_neato = await dot_to_svg('digraph G { a -> b }', { engine: 'neato' }); * ``` * * @param dot Graphviz dot source. * @param options Optional renderer overrides. * @param options.engine Graphviz layout engine to use (e.g. `'dot'`, * `'neato'`, `'circo'`). Unrecognized engine names cause `@viz-js/viz` * to throw at render time. * @returns A promise resolving to an SVG XML string. */ declare function dot_to_svg(dot: string, options?: { engine?: string; }): Promise; /** * Render an FSL string directly to SVG. * * ```typescript * const svg = await fsl_to_svg_string('a -> b;'); * const svg_neato = await fsl_to_svg_string('a -> b;', { engine: 'neato' }); * ``` * * @param fsl The FSL source. * @param opts Optional rendering options. * @param opts.footer Optional verbatim dot source inserted just before the closing `}` of the intermediate dot source. * @param opts.engine Graphviz layout engine to use (e.g. `'dot'`, `'neato'`, `'circo'`). * Unrecognized engine names cause `@viz-js/viz` to throw at render time. * @returns A promise resolving to an SVG XML string. */ declare function fsl_to_svg_string(fsl: string, opts?: { footer?: string; engine?: string; }): Promise; /** * Render a {@link jssm.Machine} to SVG. * * @param u_jssm The machine to render. * @param opts Optional rendering options. * @param opts.footer Optional verbatim dot source inserted just before the closing `}` of the intermediate dot source. * @returns A promise resolving to an SVG XML string. */ declare function machine_to_svg_string(u_jssm: Machine, opts?: { footer?: string; }): Promise; /** * Render an FSL string directly to a parsed `SVGSVGElement`. * * @param fsl The FSL source. * @param opts Optional rendering options. * @param opts.footer Optional verbatim dot source inserted just before the closing `}` of the intermediate dot source. * @returns A promise resolving to a parsed `SVGSVGElement`. * @throws {JssmError} if no `DOMParser` is available (Node without `configure`). */ declare function fsl_to_svg_element(fsl: string, opts?: { footer?: string; }): Promise; /** * Render a {@link jssm.Machine} to a parsed `SVGSVGElement`. * * @param u_jssm The machine to render. * @param opts Optional rendering options. * @param opts.footer Optional verbatim dot source inserted just before the closing `}` of the intermediate dot source. * @returns A promise resolving to a parsed `SVGSVGElement`. * @throws {JssmError} if no `DOMParser` is available (Node without `configure`). */ declare function machine_to_svg_element(u_jssm: Machine, opts?: { footer?: string; }): Promise; /** * Compatibility wrapper for {@link machine_to_dot}, retained from * jssm-viz. Will be removed in the next major. * * @deprecated Use {@link machine_to_dot} instead. */ declare function dot(machine: Machine): string; /** @internal — test-only access to private helpers. */ declare const _test: { color8to6: typeof color8to6; u_color8to6: typeof u_color8to6; vc: typeof vc; node_of: typeof node_of; shape_for_state: typeof shape_for_state; image_for_state: typeof image_for_state; style_for_state: typeof style_for_state; }; export { _test, build_time, configure, dot, dot_to_svg, fsl_to_dot, fsl_to_svg_element, fsl_to_svg_string, machine_to_dot, machine_to_svg_element, machine_to_svg_string, version };