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"; /** * Direction polarity of an arrow: pointing only `'left'`, only `'right'`, * or `'both'` (a bidirectional arrow). */ declare type JssmArrowDirection = 'left' | 'right' | 'both'; /** * 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; }; /** * Internal compiler intermediate: the root of a chained transition * expression, anchored at a `from` state. Also doubles as the carrier * for non-transition rules (state declarations, property definitions, * machine metadata) via its `key`/`value`/`name`/`state` fields. Not * intended for end-user code. * * @internal */ declare type JssmCompileSeStart = { from: StateType; se: JssmCompileSe; key: string; value?: string | number; name?: string; state?: string; default_value?: any; required?: boolean; }; /** * The output shape of the FSL parser: a flat array of * {@link JssmCompileSeStart} entries, one per top-level rule in the * source. Consumed by the compiler to build a machine configuration. * * @internal */ declare type JssmParseTree = Array>; 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; /********* * * Return the direction of an arrow - `right`, `left`, or `both`. * * ```typescript * import { arrow_direction } from 'jssm'; * * arrow_direction('->'); // 'right' * arrow_direction('<~=>'); // 'both' * ``` * * @param arrow The arrow to be evaluated * */ declare function arrow_direction(arrow: JssmArrow): JssmArrowDirection; /********* * * Return the direction of an arrow - `right`, `left`, or `both`. * * ```typescript * import { arrow_left_kind } from 'jssm'; * * arrow_left_kind('<-'); // 'legal' * arrow_left_kind('<='); // 'main' * arrow_left_kind('<~'); // 'forced' * arrow_left_kind('<->'); // 'legal' * arrow_left_kind('->'); // 'none' * ``` * * @param arrow The arrow to be evaluated * */ declare function arrow_left_kind(arrow: JssmArrow): JssmArrowKind; /********* * * Return the direction of an arrow - `right`, `left`, or `both`. * * ```typescript * import { arrow_left_kind } from 'jssm'; * * arrow_left_kind('->'); // 'legal' * arrow_left_kind('=>'); // 'main' * arrow_left_kind('~>'); // 'forced' * arrow_left_kind('<->'); // 'legal' * arrow_left_kind('<-'); // 'none' * ``` * * @param arrow The arrow to be evaluated * */ declare function arrow_right_kind(arrow: JssmArrow): JssmArrowKind; /********* * * This method wraps the parser call that comes from the peg grammar, * {@link parse}. Generally neither this nor that should be used directly * unless you mean to develop plugins or extensions for the machine. * * Parses the intermediate representation of a compiled string down to a * machine configuration object. If you're using this (probably don't,) you're * probably also using {@link compile} and {@link Machine.constructor}. * * ```typescript * import { parse, compile, Machine } from 'jssm'; * * const intermediate = wrap_parse('a -> b;', {}); * // [ {key:'transition', from:'a', se:{kind:'->',to:'b'}} ] * * const cfg = compile(intermediate); * // { start_states:['a'], transitions: [{ from:'a', to:'b', kind:'legal', forced_only:false, main_path:false }] } * * const machine = new Machine(cfg); * // Machine { _instance_name: undefined, _state: 'a', ... * ``` * * This method is mostly for plugin and intermediate tool authors, or people * who need to work with the machine's intermediate representation. * * # Hey! * * Most people looking at this want either the `sm` operator or method `from`, * which perform all the steps in the chain. The library's author mostly uses * operator `sm`, and mostly falls back to `.from` when needing to parse * strings dynamically instead of from template literals. * * Operator {@link sm}: * * ```typescript * import { sm } from 'jssm'; * * const lswitch = sm`on <=> off;`; * ``` * * Method {@link from}: * * ```typescript * import * as jssm from 'jssm'; * * const toggle = jssm.from('up <=> down;'); * ``` * * `wrap_parse` itself is an internal convenience method for alting out an * object as the options call. Not generally meant for external use. * * @param input The FSL code to be evaluated * * @param options Things to control about the instance * */ declare function wrap_parse(input: string, options?: Object): any; /********* * * Compile a machine's JSON intermediate representation to a config object. If * you're using this (probably don't,) you're probably also using * {@link parse} to get the IR, and the object constructor * {@link Machine.construct} to turn the config object into a workable machine. * * ```typescript * import { parse, compile, Machine } from 'jssm'; * * const intermediate = parse('a -> b;'); * // [ {key:'transition', from:'a', se:{kind:'->',to:'b'}} ] * * const cfg = compile(intermediate); * // { start_states:['a'], transitions: [{ from:'a', to:'b', kind:'legal', forced_only:false, main_path:false }] } * * const machine = new Machine(cfg); * // Machine { _instance_name: undefined, _state: 'a', ... * ``` * * This method is mostly for plugin and intermediate tool authors, or people * who need to work with the machine's intermediate representation. * * # Hey! * * Most people looking at this want either the `sm` operator or method `from`, * which perform all the steps in the chain. The library's author mostly uses * operator `sm`, and mostly falls back to `.from` when needing to parse * strings dynamically instead of from template literals. * * Operator {@link sm}: * * ```typescript * import { sm } from 'jssm'; * * const lswitch = sm`on <=> off;`; * ``` * * Method {@link from}: * * ```typescript * import * as jssm from 'jssm'; * * const toggle = jssm.from('up <=> down;'); * ``` * * @typeparam mDT The type of the machine data member; usually omitted * * @param tree The parse tree to be boiled down into a machine config * */ declare function compile(tree: JssmParseTree): JssmGenericConfig; /********* * * An internal convenience wrapper for parsing then compiling a machine string. * Not generally meant for external use. Please see {@link compile} or * {@link sm}. * * @typeparam mDT The type of the machine data member; usually omitted * * @param plan The FSL code to be evaluated and built into a machine config * */ declare function make(plan: string): JssmGenericConfig; /******* * * Selects a single item from a weighted array of objects using cumulative * probability. Each object in the array should have a numeric property * indicating its relative weight (defaults to `'probability'`). Objects * missing the property are treated as weight 1. * * ```typescript * const opts = [ * { value: 'common', probability: 0.8 }, * { value: 'rare', probability: 0.2 } * ]; * * weighted_rand_select(opts); // most often { value: 'common', ... } * ``` * * @param options - Non-empty array of objects to choose from. * @param probability_property - Name of the numeric weight property on each * object. Defaults to `'probability'`. * @param rng - Optional random number generator `() => number` * in `[0, 1)`. Defaults to `Math.random`. * * @returns One element from `options`, chosen by weighted random selection. * * @throws {TypeError} If `options` is not a non-empty array of objects. * */ declare const weighted_rand_select: Function; /******* * * Returns, for a non-negative integer argument `n`, the series `[0 .. n]`. * * ```typescript * import { seq } from './jssm'; * * seq(5); // [0, 1, 2, 3, 4] * seq(0); // [] * ``` * */ declare function seq(n: number): number[]; /******* * * Returns the histograph of an array as a `Map`. Makes no attempt to cope * with deep equality; will fail for complex contents, as such. * * ```typescript * import { histograph } from './jssm'; * * histograph( [0, 0, 1, 1, 2, 2, 1] ); // Map() * ``` * */ declare const histograph: Function; /******* * * Draws `n` weighted random samples from an array of objects. Each draw is * independent (with replacement), delegating to {@link weighted_rand_select}. * * ```typescript * const opts = [ * { value: 'a', probability: 0.9 }, * { value: 'b', probability: 0.1 } * ]; * * weighted_sample_select(3, opts, 'probability'); * // e.g. [ { value: 'a', ... }, { value: 'a', ... }, { value: 'b', ... } ] * ``` * * @param n - Number of samples to draw. * @param options - Non-empty array of weighted objects. * @param probability_property - Name of the numeric weight property. * @param rng - Optional random number generator. * * @returns An array of `n` independently selected items. * */ declare const weighted_sample_select: Function; /******* * * Draws `n` weighted random samples, extracts a named key from each, and * returns a histograph (`Map`) of how often each key value appeared. Useful * for validating that a probabilistic transition distribution is roughly * correct over many trials. * * ```typescript * const opts = [ * { to: 'a', probability: 0.7 }, * { to: 'b', probability: 0.3 } * ]; * * weighted_histo_key(1000, opts, 'probability', 'to'); * // Map { 'a' => ~700, 'b' => ~300 } * ``` * * @param n - Number of samples to draw. * @param opts - Non-empty array of weighted objects. * @param prob_prop - Name of the numeric weight property. * @param extract - Name of the property to extract from each sample for * histogramming. * @param rng - Optional random number generator. * * @returns A `Map` from extracted key values to their occurrence counts. * */ declare const weighted_histo_key: Function; /******* * * Creates a SplitMix32 random generator. Used by the randomness test suite. * * Sourced from `bryc`: https://github.com/bryc/code/blob/master/jshash/PRNGs.md#splitmix32 * * Replaces the Mulberry generator, which was found to have problems * */ declare function gen_splitmix32(a?: number | undefined): () => number; /******* * * Reduces an array to its unique contents. Compares with `===` and makes no * effort to deep-compare contents; two matching arrays or objects contained * will be treated as distinct, according to javascript rules. This also means * that `NaNs` will be ***dropped***, because they do not self-compare. * * ```typescript * unique( [] ); // [] * unique( [0,0] ); // [0] * unique( [0,1,2, 0,1,2, 0,1,2] ); // [0,1,2] * unique( [ [1], [1] ] ); // [ [1], [1] ] because arrays don't match * unique( [0,NaN,2] ); // [0,2] * ``` * */ declare const unique: (arr: T[]) => T[]; /******* * * Lists all repeated items in an array along with their counts. Subject to * matching rules of Map. `NaN` is manually removed because of conflict rules * around {@link unique}. Because these are compared with `===` and because * arrays and objects never match that way unless they're the same object, * arrays and objects are never considered repeats. * * ```typescript * find_repeated([ ]); // [] * find_repeated([ "one" ]); // [] * find_repeated([ "one", "two" ]); // [] * find_repeated([ "one", "one" ]); // [ ["one", 2] ] * find_repeated([ "one", "two", "one" ]); // [ ["one", 2] ] * find_repeated([ 0, NaN, 0, NaN ]); // [ [0, 2] ] * ``` * */ declare function find_repeated(arr: T[]): [T, number][]; /******* * * Returns a `Promise` that resolves after `ms` milliseconds. Useful for * inserting delays in async test flows or demos. * * ```typescript * await sleep(100); // pauses execution for 100ms * ``` * * @param ms - Number of milliseconds to wait before resolving. * * @returns A `Promise` that resolves after the timeout. * */ declare function sleep(ms: number): Promise; /******* * * Convenience aliases for common mathematical and numeric constants from * `Number` and `Math`. Re-exported so that FSL data expressions and tests * can reference them without importing `Math` directly. * * Includes: `NegInfinity`, `PosInfinity`, `Epsilon`, `Pi`, `E`, `Root2`, * `RootHalf`, `Ln2`, `Ln10`, `Log2E`, `Log10E`, `MaxSafeInt`, `MinSafeInt`, * `MaxPosNum`, `MinPosNum`, `Phi` (golden ratio), `EulerC` (Euler–Mascheroni). * */ declare const NegInfinity: number; declare const PosInfinity: number; declare const Epsilon: number; declare const Pi: number; declare const E: number; declare const Root2: number; declare const RootHalf: number; declare const Ln2: number; declare const Ln10: number; declare const Log2E: number; declare const Log10E: number; declare const MaxSafeInt: number; declare const MinSafeInt: number; declare const MaxPosNum: number; declare const MinPosNum: number; declare const Phi = 1.618033988749895; declare const EulerC = 0.5772156649015329; /******* * * Complete list of node shapes supported by Graphviz. Used by jssm-viz to * validate and render state shapes in FSL `state ... : { shape: ... }` blocks. * * `shapes` is an alias for `gviz_shapes`. * */ declare const gviz_shapes$1: string[]; /** * Public alias for {@link gviz_shapes}. The list of node shapes supported * by Graphviz that jssm-viz accepts in FSL `state ... : { shape: ... }` * declarations. */ declare const shapes$1: string[]; /******* * * List of CSS/SVG named colors accepted by jssm-viz for state styling * properties like `background-color` and `text-color`. Case-insensitive * matching is done at parse time; the canonical casing here follows the * CSS specification. * */ declare const named_colors$1: string[]; /******* * * Character ranges accepted by the FSL grammar for identifier and label * tokens. Each entry is an inclusive `{from, to}` range of single Unicode * characters. Single-character entries (e.g. `.`) appear with `from === to`. * * These are intended for tooling, validators, and editors that need to know * which characters are legal in a given FSL token position without re-parsing * the PEG grammar. * */ /** * Inclusive character ranges accepted by `AtomLetter` — i.e., the characters * legal in any but the first position of an FSL state name (atom). * * Includes ASCII digits/letters and the symbols * `.`, `+`, `_`, `^`, `(`, `)`, `*`, `&`, `$`, `#`, `@`, `!`, `?`, `,`, * plus the high-Unicode range `U+0080`–`U+FFFF`. * * @example * state_name_chars.some(r => 'A' >= r.from && 'A' <= r.to); // true */ declare const state_name_chars$1: ReadonlyArray<{ from: string; to: string; }>; /** * Inclusive character ranges accepted by `AtomFirstLetter` — i.e., the * characters legal in the first position of an FSL state name (atom). * * Notably narrower than {@link state_name_chars}: omits `+`, `(`, `)`, `&`, * `#`, `@`. Includes ASCII digits/letters, `.`, `_`, `!`, `$`, `^`, `*`, * `?`, `,`, and the high-Unicode range `U+0080`–`U+FFFF`. * * @example * state_name_first_chars.some(r => '+' >= r.from && '+' <= r.to); // false */ declare const state_name_first_chars$1: ReadonlyArray<{ from: string; to: string; }>; /** * Inclusive character ranges accepted by `ActionLabelUnescaped` — i.e., the * characters legal inside a single-quoted action label without escaping. * Space (`U+0020`) is included; the apostrophe `'` (`U+0027`) is explicitly * excluded since it terminates the label. * * Three ranges: `U+0020`–`U+0026`, `U+0028`–`U+005B`, `U+005D`–`U+FFFF`. * * @example * action_label_chars.some(r => ' ' >= r.from && ' ' <= r.to); // true * action_label_chars.some(r => "'" >= r.from && "'" <= r.to); // false */ declare const action_label_chars$1: ReadonlyArray<{ from: string; to: string; }>; declare const jssm_constants_d_E: typeof E; declare const jssm_constants_d_Epsilon: typeof Epsilon; declare const jssm_constants_d_EulerC: typeof EulerC; declare const jssm_constants_d_Ln10: typeof Ln10; declare const jssm_constants_d_Ln2: typeof Ln2; declare const jssm_constants_d_Log10E: typeof Log10E; declare const jssm_constants_d_Log2E: typeof Log2E; declare const jssm_constants_d_MaxPosNum: typeof MaxPosNum; declare const jssm_constants_d_MaxSafeInt: typeof MaxSafeInt; declare const jssm_constants_d_MinPosNum: typeof MinPosNum; declare const jssm_constants_d_MinSafeInt: typeof MinSafeInt; declare const jssm_constants_d_NegInfinity: typeof NegInfinity; declare const jssm_constants_d_Phi: typeof Phi; declare const jssm_constants_d_Pi: typeof Pi; declare const jssm_constants_d_PosInfinity: typeof PosInfinity; declare const jssm_constants_d_Root2: typeof Root2; declare const jssm_constants_d_RootHalf: typeof RootHalf; declare namespace jssm_constants_d { export { jssm_constants_d_E as E, jssm_constants_d_Epsilon as Epsilon, jssm_constants_d_EulerC as EulerC, jssm_constants_d_Ln10 as Ln10, jssm_constants_d_Ln2 as Ln2, jssm_constants_d_Log10E as Log10E, jssm_constants_d_Log2E as Log2E, jssm_constants_d_MaxPosNum as MaxPosNum, jssm_constants_d_MaxSafeInt as MaxSafeInt, jssm_constants_d_MinPosNum as MinPosNum, jssm_constants_d_MinSafeInt as MinSafeInt, jssm_constants_d_NegInfinity as NegInfinity, jssm_constants_d_Phi as Phi, jssm_constants_d_Pi as Pi, jssm_constants_d_PosInfinity as PosInfinity, jssm_constants_d_Root2 as Root2, jssm_constants_d_RootHalf as RootHalf, action_label_chars$1 as action_label_chars, gviz_shapes$1 as gviz_shapes, named_colors$1 as named_colors, shapes$1 as shapes, state_name_chars$1 as state_name_chars, state_name_first_chars$1 as state_name_first_chars, }; } /** * 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; declare const shapes: string[]; declare const gviz_shapes: string[]; declare const named_colors: string[]; declare const state_name_chars: readonly { from: string; to: string; }[]; declare const state_name_first_chars: readonly { from: string; to: string; }[]; declare const action_label_chars: readonly { from: string; to: string; }[]; /********* * * An internal method meant to take a series of declarations and fold them into * a single multi-faceted declaration, in the process of building a state. Not * generally meant for external use. * * @internal * */ declare function transfer_state_properties(state_decl: JssmStateDeclaration): JssmStateDeclaration; /** * * Collapse a list of individual state-style key/value pairs into a single * {@link JssmStateConfig} object, remapping FSL-style kebab-case keys to the * camelCase field names the runtime uses. * * The parser emits state styling as a flat array like * `[{ key: 'color', value: 'red' }, { key: 'line-style', value: 'dashed' }]` * because that is the most natural shape for the grammar to produce. This * helper runs once per style bucket during `Machine` construction to turn * those arrays into the compact `{ color, lineStyle, ... }` objects the * graph-rendering code expects. * * ```typescript * state_style_condense([ * { key: 'color', value: 'red' }, * { key: 'shape', value: 'oval' }, * { key: 'line-style', value: 'dashed' } * ]); * // => { color: 'red', shape: 'oval', lineStyle: 'dashed' } * * state_style_condense(undefined); * // => {} * ``` * * @param jssk The list of style keys to condense. `undefined` is accepted * and yields an empty config. * * @param machine Optional `Machine` reference, used only so that any * {@link JssmError} thrown can point at the offending machine in its * diagnostic message. * * @returns A `JssmStateConfig` object containing every key from `jssk` * remapped into its camelCase field. * * @throws {JssmError} If `jssk` is neither an array nor `undefined`, if any * element is not an object, if the same key appears more than once, or if a * key is not one of the recognized style names. * * @internal * */ declare function state_style_condense(jssk: JssmStateStyleKeyList, machine?: any): JssmStateConfig; /******* * * 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; } /********* * * Create a state machine from a template string. This is one of the two main * paths for working with JSSM, alongside {@link from}. * * Use this method when you want to work directly and conveniently with a * constant template expression. Use `.from` when you want to pull from * dynamic strings. * * * ```typescript * import * as jssm from 'jssm'; * * const lswitch = jssm.from('on <=> off;'); * ``` * * @typeparam mDT The type of the machine data member; usually omitted * * @param template_strings The assembled code * * @param remainder The mechanic for template argument insertion * */ declare function sm(template_strings: TemplateStringsArray, ...remainder: any[]): Machine; /********* * * Create a state machine from an implementation string. This is one of the * two main paths for working with JSSM, alongside {@link sm}. * * Use this method when you want to conveniently pull a state machine from a * string dynamically. Use operator `sm` when you just want to work with a * template expression. * * ```typescript * import * as jssm from 'jssm'; * * const lswitch = jssm.from('on <=> off;'); * ``` * * @typeparam mDT The type of the machine data member; usually omitted * * @param MachineAsString The FSL code to evaluate * * @param ExtraConstructorFields Extra non-code configuration to pass at creation time * */ declare function from(MachineAsString: string, ExtraConstructorFields?: Partial> | undefined): Machine; /** * * Type guard that narrows an unknown value to a {@link HookComplexResult}. * * A hook complex result is an object with at minimum a boolean `pass` field, * and may optionally also carry replacement `data` / `next_data` fields that * the machine should adopt if the hook passes. This helper is used by the * hook-dispatch machinery to tell "hook returned a complex object" from * "hook returned a bare boolean / null / undefined". * * ```typescript * is_hook_complex_result({ pass: true }); // true * is_hook_complex_result({ pass: false, data: { x: 1 }}); // true * is_hook_complex_result(true); // false * is_hook_complex_result(null); // false * is_hook_complex_result({ other: 'thing' }); // false * ``` * * @typeparam mDT The type of the machine data member; usually omitted. * * @param hr The value to test. * * @returns `true` if `hr` is a non-null object with a boolean `pass` field; * `false` otherwise. When `true`, TypeScript narrows `hr` to * `HookComplexResult`. * */ declare function is_hook_complex_result(hr: unknown): hr is HookComplexResult; /** * * Normalize any legal hook return value to a single "did it reject?" boolean. * * Hooks in jssm may return any of the following to indicate success: * `true`, `undefined`, or a complex result whose `pass` field is `true`. * They may return any of the following to indicate rejection: * `false`, or a complex result whose `pass` field is `false`. This helper * collapses all of those shapes into one boolean so callers don't have to * re-implement the matrix. * * ```typescript * is_hook_rejection(true); // false (pass) * is_hook_rejection(undefined); // false (pass) * is_hook_rejection(false); // true (reject) * is_hook_rejection({ pass: true }); // false (pass) * is_hook_rejection({ pass: false }); // true (reject) * ``` * * @typeparam mDT The type of the machine data member; usually omitted. * * @param hr A hook result of any legal shape. * * @returns `true` if the hook rejected the transition; `false` if it passed. * * @throws {TypeError} If `hr` is not a recognized hook result shape (for * example, a number or a plain object without a `pass` field). * */ declare function is_hook_rejection(hr: HookResult): boolean; /** * * Invoke an optional transition/action hook and normalize its return value * into a {@link HookComplexResult}. * * This is the central adapter the transition pipeline uses to run every * non-"everything" hook kind (basic, named, entry, exit, after, action, etc). * It accepts `undefined` for the hook slot because most hooks are not set on * most machines; when no hook is installed the step is a no-op pass. * * The valid return shapes from a hook and their normalized meanings are: * - `undefined` → `{ pass: true }` * - `true` → `{ pass: true }` * - `false` → `{ pass: false }` * - `null` → `{ pass: false }` * - a complex result object → returned as-is * * Anything else is a programmer error and throws. * * @typeparam mDT The type of the machine data member; usually omitted. * * @param maybe_hook The hook handler to call, or `undefined` for the * "no hook installed" case. * * @param hook_args The context object passed to the hook. Includes the * current and proposed state, current and proposed data, action name, and * transition kind. * * @returns A {@link HookComplexResult} describing whether the hook passed * and, optionally, any data replacements it requested. * * @throws {TypeError} If the hook returns a value that is not one of the * legal shapes listed above. * * @internal * */ declare function abstract_hook_step(maybe_hook: HookHandler | undefined, hook_args: HookContext): HookComplexResult; /** * * Invoke an optional "everything" hook and normalize its return value into * a {@link HookComplexResult}. * * Mechanically identical to {@link abstract_hook_step}, but typed for the * everything-hook family (`pre_everything_hook` and `everything_hook`), * whose context object carries an extra `hook_name` field identifying which * bracket of the pipeline is firing. Separated from `abstract_hook_step` * so TypeScript can enforce that the hook handler and the context object * agree on shape. * * The valid return shapes and their meanings are the same as for * `abstract_hook_step`: * - `undefined` or `true` → `{ pass: true }` * - `false` or `null` → `{ pass: false }` * - a complex result → returned as-is * * @typeparam mDT The type of the machine data member; usually omitted. * * @param maybe_hook The everything-hook handler, or `undefined` when none * is installed. * * @param hook_args The everything-hook context object. Differs from a * normal hook context in that it also includes `hook_name`. * * @returns A {@link HookComplexResult} describing whether the hook passed * and any data replacements it requested. * * @throws {TypeError} If the hook returns a value outside the legal shapes. * * @internal * */ declare function abstract_everything_hook_step(maybe_hook: EverythingHookHandler | undefined, hook_args: EverythingHookContext): HookComplexResult; /** * Deserializes a previously serialized machine state. * * This function recreates a machine from a serialization object, restoring its * state, data, and history. For security and compatibility reasons, it will * refuse to deserialize data from future versions of the library. * * @typeparam mDT - The type of the machine data member * * @param {string} machine_string - The FSL string defining the machine structure * @param {JssmSerialization} ser - The serialization object to restore from * * @returns {Machine} - The restored machine instance * * @throws {Error} If the serialization is from a future version * * @example * const machine = jssm.from("a -> b;"); * const serialized = machine.serialize(); * const restored = jssm.deserialize("a -> b;", serialized); */ declare function deserialize(machine_string: string, ser: JssmSerialization): Machine; export { FslDirections, Machine, abstract_everything_hook_step, abstract_hook_step, action_label_chars, arrow_direction, arrow_left_kind, arrow_right_kind, build_time, compile, jssm_constants_d as constants, deserialize, find_repeated, from, gen_splitmix32, gviz_shapes, histograph, is_hook_complex_result, is_hook_rejection, make, named_colors, wrap_parse as parse, seq, shapes, sleep, sm, state_name_chars, state_name_first_chars, state_style_condense, transfer_state_properties, unique, version, weighted_histo_key, weighted_rand_select, weighted_sample_select };