import { circular_buffer } from 'circular_buffer_js'; declare type StateType = string; /** Composite type indicating success as part of a result. */ declare type JssmSuccess = { success: true; }; /** Composite type indicating an error, and the reason for it, as part of a result. */ declare type JssmFailure = { success: false; error: any; }; /** Composite type indicating that a result isn't finished yet. */ declare type JssmIncomplete = { success: 'incomplete'; }; /** * Discriminated union representing the outcome of an operation: either * success, failure (with an `error`), or incomplete. Used as the return * shape for operations that may need to report partial progress. */ declare type JssmResult = JssmSuccess | JssmFailure | JssmIncomplete; /** * 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; /** * Two-state policy flag: a feature is either `'required'` or `'disallowed'`. * Used by machine configuration where the option must take a definite stance. */ declare type JssmPermitted = 'required' | 'disallowed'; /** * 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; 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, NewState: StateType, 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; }; /** * Internal marker used by the compiler to indicate a cycle declaration in * the parse stream, rather than a literal state name. See * {@link JssmTransitionRule}. */ declare type JssmTransitionCycle = { key: 'cycle'; value: StateType; }; /** * An entry produced while parsing a transition rule: either a literal * state name (`StateType`) or a {@link JssmTransitionCycle} marker. */ declare type JssmTransitionRule = StateType | JssmTransitionCycle; /** * 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; 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; states: Map; named_transitions: Map; edge_map: Map>; actions: Map>; reverse_actions: Map>; edges: Array>; }; declare type JssmStatePermitter = (OldState: StateType, NewState: StateType, OldData: DataType, NewData: DataType) => boolean; declare type JssmStatePermitterMaybeArray = JssmStatePermitter | Array>; /** * Minimal machine description used internally and accepted by some * lower-level constructors. Most callers should use the richer * {@link JssmGenericConfig} instead. */ declare type JssmGenericMachine = { name?: string; state: StateType; data?: DataType; nodes?: Array; transitions: JssmTransitions; check?: JssmStatePermitterMaybeArray; min_transitions?: number; max_transitions?: number; allow_empty?: boolean; allow_islands?: boolean; allow_force?: boolean; keep_history?: boolean | number; }; /** * 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; 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[]; /** * Complete shape of a jssm-viz theme. A theme provides a style block for * each kind of state (`state`, `hooked`, `start`, `end`, `terminal`) as * well as a matching `active_*` variant used while that state is current. * * The `graph`, `legal`, `main`, `forced`, `action`, and `title` slots are * reserved for future use and currently typed as `undefined`. * * Most user-defined themes should be typed as {@link JssmTheme} (the * `Partial` of this) so that omitted fields fall back to the base theme. */ declare type JssmBaseTheme = { name: string; state: JssmStateConfig; hooked: JssmStateConfig; start: JssmStateConfig; end: JssmStateConfig; terminal: JssmStateConfig; active: JssmStateConfig; active_hooked: JssmStateConfig; active_start: JssmStateConfig; active_end: JssmStateConfig; active_terminal: JssmStateConfig; graph: undefined; legal: undefined; main: undefined; forced: undefined; action: undefined; title: undefined; }; /** * A user-supplied theme. Identical in shape to {@link JssmBaseTheme}, but * every field is optional so themes can be layered: omitted slots fall * through to the underlying base theme. */ declare type JssmTheme = Partial; /** * 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: a single aggregated rule produced while * folding a parse tree into a machine configuration. Not intended for * end-user code. * * @internal */ declare type JssmCompileRule = { agg_as: string; val: any; }; /** * 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>; /** * Signature of an FSL parse function: takes a source string and returns a * {@link JssmParseTree}. Used to type the parser export so consumers can * swap in alternative parser implementations. */ declare type JssmParseFunctionType = (string: any) => JssmParseTree; 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; 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; /** * Extra diagnostic information attached to a {@link JssmError} when it * carries machine-relative context — most often the state name a caller * asked about when the error was raised. */ declare type JssmErrorExtendedInfo = { requested_state?: StateType | undefined; }; /** * 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, 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; export { JssmColor, JssmShape, JssmTransition, JssmTransitions, JssmTransitionList, JssmTransitionRule, JssmArrow, JssmArrowKind, JssmArrowDirection, JssmGenericConfig, JssmGenericState, JssmGenericMachine, JssmParseTree, JssmCompileSe, JssmCompileSeStart, JssmCompileRule, JssmPermitted, JssmPermittedOpt, JssmResult, JssmStateDeclaration, JssmStateDeclarationRule, JssmStateConfig, JssmStateStyleKey, JssmStateStyleKeyList, JssmBaseTheme, JssmTheme, JssmLayout, JssmHistory, JssmSerialization, JssmPropertyDefinition, JssmAllowsOverride, JssmParseFunctionType, JssmMachineInternalState, JssmErrorExtendedInfo, FslDirections, FslDirection, FslThemes, FslTheme, HookDescription, HookHandler, HookContext, HookResult, HookComplexResult, EverythingHookContext, EverythingHookHandler, PostEverythingHookHandler, JssmRng };