jssm.js

// whargarbl lots of these return arrays could/should be sets
import { reduce as reduce_to_639 } from 'reduce-to-639-1';
import { circular_buffer } from 'circular_buffer_js';
import { base_theme } from './themes/jssm_base_stylesheet';
import { default_theme } from './themes/jssm_theme_default';
import { modern_theme } from './themes/jssm_theme_modern';
import { ocean_theme } from './themes/jssm_theme_ocean';
const themes = new Map();
themes.set('default', default_theme);
themes.set('modern', modern_theme);
themes.set('ocean', ocean_theme);
import { seq, unique, find_repeated, weighted_rand_select, weighted_sample_select, histograph, weighted_histo_key, array_box_if_string, name_bind_prop_and_state, hook_name, named_hook_name } from './jssm_util';
import * as constants from './jssm_constants';
const { shapes, gviz_shapes, named_colors } = constants;
import { parse } from './jssm-dot';
import { version } from './version'; // replaced from package.js in build
import { JssmError } from './jssm_error';
/* eslint-disable complexity */
/*********
 *
 *  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
 *
 */
function arrow_direction(arrow) {
    switch (String(arrow)) {
        case '->':
        case '→':
        case '=>':
        case '⇒':
        case '~>':
        case '↛':
            return 'right';
        case '<-':
        case '←':
        case '<=':
        case '⇐':
        case '<~':
        case '↚':
            return 'left';
        case '<->':
        case '↔':
        case '<-=>':
        case '←⇒':
        case '←=>':
        case '<-⇒':
        case '<-~>':
        case '←↛':
        case '←~>':
        case '<-↛':
        case '<=>':
        case '⇔':
        case '<=->':
        case '⇐→':
        case '⇐->':
        case '<=→':
        case '<=~>':
        case '⇐↛':
        case '⇐~>':
        case '<=↛':
        case '<~>':
        case '↮':
        case '<~->':
        case '↚→':
        case '↚->':
        case '<~→':
        case '<~=>':
        case '↚⇒':
        case '↚=>':
        case '<~⇒':
            return 'both';
        default:
            throw new JssmError(undefined, `arrow_direction: unknown arrow type ${arrow}`);
    }
}
/* eslint-enable complexity */
/* eslint-disable complexity */
/*********
 *
 *  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
 *
 */
function arrow_left_kind(arrow) {
    switch (String(arrow)) {
        case '->':
        case '→':
        case '=>':
        case '⇒':
        case '~>':
        case '↛':
            return 'none';
        case '<-':
        case '←':
        case '<->':
        case '↔':
        case '<-=>':
        case '←⇒':
        case '<-~>':
        case '←↛':
            return 'legal';
        case '<=':
        case '⇐':
        case '<=>':
        case '⇔':
        case '<=->':
        case '⇐→':
        case '<=~>':
        case '⇐↛':
            return 'main';
        case '<~':
        case '↚':
        case '<~>':
        case '↮':
        case '<~->':
        case '↚→':
        case '<~=>':
        case '↚⇒':
            return 'forced';
        default:
            throw new JssmError(undefined, `arrow_direction: unknown arrow type ${arrow}`);
    }
}
/* eslint-enable complexity */
/* eslint-disable complexity */
/*********
 *
 *  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
 *
 */
function arrow_right_kind(arrow) {
    switch (String(arrow)) {
        case '<-':
        case '←':
        case '<=':
        case '⇐':
        case '<~':
        case '↚':
            return 'none';
        case '->':
        case '→':
        case '<->':
        case '↔':
        case '<=->':
        case '⇐→':
        case '<~->':
        case '↚→':
            return 'legal';
        case '=>':
        case '⇒':
        case '<=>':
        case '⇔':
        case '<-=>':
        case '←⇒':
        case '<~=>':
        case '↚⇒':
            return 'main';
        case '~>':
        case '↛':
        case '<~>':
        case '↮':
        case '<-~>':
        case '←↛':
        case '<=~>':
        case '⇐↛':
            return 'forced';
        default:
            throw new JssmError(undefined, `arrow_direction: unknown arrow type ${arrow}`);
    }
}
/* eslint-enable complexity */
/*********
 *
 *  Internal method meant to perform factory assembly of an edge.  Not meant for
 *  external use.
 *
 *  @internal
 *
 *  @typeparam mDT The type of the machine data member; usually omitted
 *
 */
// TODO add at-param to docblock
function makeTransition(this_se, from, to, isRight, _wasList, _wasIndex) {
    const kind = isRight ? arrow_right_kind(this_se.kind) : arrow_left_kind(this_se.kind), edge = {
        from,
        to,
        kind,
        forced_only: kind === 'forced',
        main_path: kind === 'main'
    };
    //  if ((wasList  !== undefined) && (wasIndex === undefined)) { throw new JssmError(undefined, `Must have an index if transition was in a list"); }
    //  if ((wasIndex !== undefined) && (wasList  === undefined)) { throw new JssmError(undefined, `Must be in a list if transition has an index");   }
    /*
      if (typeof edge.to === 'object') {
  
        if (edge.to.key === 'cycle') {
          if (wasList === undefined) { throw new JssmError(undefined, "Must have a waslist if a to is type cycle"); }
          const nextIndex = wrapBy(wasIndex, edge.to.value, wasList.length);
          edge.to = wasList[nextIndex];
        }
  
      }
    */
    const action = isRight ? 'r_action' : 'l_action', probability = isRight ? 'r_probability' : 'l_probability';
    if (this_se[action]) {
        edge.action = this_se[action];
    }
    if (this_se[probability]) {
        edge.probability = this_se[probability];
    }
    return edge;
}
/*********
 *
 *  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
 *
 */
function wrap_parse(input, options) {
    return parse(input, options || {});
}
/*********
 *
 *  Internal method performing one step in compiling rules for transitions.  Not
 *  generally meant for external use.
 *
 *  @internal
 *
 *  @typeparam mDT The type of the machine data member; usually omitted
 *
 */
function compile_rule_transition_step(acc, from, to, this_se, next_se) {
    const edges = [];
    const uFrom = (Array.isArray(from) ? from : [from]), uTo = (Array.isArray(to) ? to : [to]);
    uFrom.map((f) => {
        uTo.map((t) => {
            const right = makeTransition(this_se, f, t, true);
            if (right.kind !== 'none') {
                edges.push(right);
            }
            const left = makeTransition(this_se, t, f, false);
            if (left.kind !== 'none') {
                edges.push(left);
            }
        });
    });
    const new_acc = acc.concat(edges);
    if (next_se) {
        return compile_rule_transition_step(new_acc, to, next_se.to, next_se, next_se.se);
    }
    else {
        return new_acc;
    }
}
/*********
 *
 *  Internal method performing one step in compiling rules for transitions.  Not
 *  generally meant for external use.
 *
 *  @internal
 *
 */
function compile_rule_handle_transition(rule) {
    return compile_rule_transition_step([], rule.from, rule.se.to, rule.se, rule.se.se);
}
/*********
 *
 *  Internal method performing one step in compiling rules for transitions.  Not
 *  generally meant for external use.
 *
 *  @internal
 *
 */
function compile_rule_handler(rule) {
    if (rule.key === 'transition') {
        return { agg_as: 'transition', val: compile_rule_handle_transition(rule) };
    }
    if (rule.key === 'machine_language') {
        return { agg_as: 'machine_language', val: reduce_to_639(rule.value) };
    }
    // manually rehandled to make `undefined` as a property safe
    if (rule.key === 'property_definition') {
        const ret = { agg_as: 'property_definition', val: { name: rule.name } };
        if (rule.hasOwnProperty('default_value')) {
            ret.val.default_value = rule.default_value;
        }
        if (rule.hasOwnProperty('required')) {
            ret.val.required = rule.required;
        }
        return ret;
    }
    // state properties are in here
    if (rule.key === 'state_declaration') {
        if (!rule.name) {
            throw new JssmError(undefined, 'State declarations must have a name');
        }
        return { agg_as: 'state_declaration', val: { state: rule.name, declarations: rule.value } };
    }
    if (['arrange_declaration', 'arrange_start_declaration',
        'arrange_end_declaration'].includes(rule.key)) {
        return { agg_as: rule.key, val: [rule.value] };
    }
    // things that can only exist once and are just a value under their own name
    const tautologies = [
        'graph_layout', 'start_states', 'end_states', 'machine_name', 'machine_version',
        'machine_comment', 'machine_author', 'machine_contributor', 'machine_definition',
        'machine_reference', 'machine_license', 'fsl_version', 'state_config', 'theme',
        'flow', 'dot_preamble', 'default_state_config', 'default_start_state_config',
        'default_end_state_config', 'default_hooked_state_config',
        'default_active_state_config', 'default_terminal_state_config'
    ];
    if (tautologies.includes(rule.key)) {
        return { agg_as: rule.key, val: rule.value };
    }
    throw new JssmError(undefined, `compile_rule_handler: Unknown rule: ${JSON.stringify(rule)}`);
}
/*********
 *
 *  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
 *
 */
function compile(tree) {
    const results = {
        graph_layout: [],
        transition: [],
        start_states: [],
        end_states: [],
        state_config: [],
        state_declaration: [],
        fsl_version: [],
        machine_author: [],
        machine_comment: [],
        machine_contributor: [],
        machine_definition: [],
        machine_language: [],
        machine_license: [],
        machine_name: [],
        machine_reference: [],
        property_definition: [],
        state_property: {},
        theme: [],
        flow: [],
        dot_preamble: [],
        arrange_declaration: [],
        arrange_start_declaration: [],
        arrange_end_declaration: [],
        machine_version: [],
        default_state_config: [],
        default_active_state_config: [],
        default_hooked_state_config: [],
        default_terminal_state_config: [],
        default_start_state_config: [],
        default_end_state_config: [],
    };
    tree.map((tr) => {
        const rule = compile_rule_handler(tr), agg_as = rule.agg_as, val = rule.val; // TODO FIXME no any
        results[agg_as] = results[agg_as].concat(val);
    });
    const property_keys = results['property_definition'].map(pd => pd.name), repeat_props = find_repeated(property_keys);
    if (repeat_props.length) {
        throw new JssmError(undefined, `Cannot repeat property definitions.  Saw ${JSON.stringify(repeat_props)}`);
    }
    const assembled_transitions = [].concat(...results['transition']);
    const result_cfg = {
        start_states: results.start_states.length ? results.start_states : [assembled_transitions[0].from],
        end_states: results.end_states,
        transitions: assembled_transitions,
        state_property: [],
    };
    const oneOnlyKeys = [
        'graph_layout', 'machine_name', 'machine_version', 'machine_comment',
        'fsl_version', 'machine_license', 'machine_definition', 'machine_language',
        'theme', 'flow', 'dot_preamble'
    ];
    oneOnlyKeys.map((oneOnlyKey) => {
        if (results[oneOnlyKey].length > 1) {
            throw new JssmError(undefined, `May only have one ${oneOnlyKey} statement maximum: ${JSON.stringify(results[oneOnlyKey])}`);
        }
        else {
            if (results[oneOnlyKey].length) {
                result_cfg[oneOnlyKey] = results[oneOnlyKey][0];
            }
        }
    });
    ['arrange_declaration', 'arrange_start_declaration', 'arrange_end_declaration',
        'machine_author', 'machine_contributor', 'machine_reference',
        'state_declaration', 'property_definition', 'default_state_config',
        'default_start_state_config', 'default_end_state_config',
        'default_hooked_state_config', 'default_terminal_state_config',
        'default_active_state_config'].map((multiKey) => {
        if (results[multiKey].length) {
            result_cfg[multiKey] = results[multiKey];
        }
    });
    // re-walk state declarations, already wrapped up, to get state properties,
    // which go out in a different datastructure
    results.state_declaration.forEach(sd => {
        sd.declarations.forEach(decl => {
            if (decl.key === 'state_property') {
                const label = name_bind_prop_and_state(decl.name, sd.state);
                if (result_cfg.state_property.findIndex(c => c.name === label) !== -1) {
                    throw new JssmError(undefined, `A state may only bind a property once (${sd.state} re-binds ${decl.name})`);
                }
                else {
                    result_cfg.state_property.push({ name: label, default_value: decl.value });
                }
            }
        });
    });
    return result_cfg;
}
/*********
 *
 *  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
 *
 */
function make(plan) {
    return compile(wrap_parse(plan));
}
/*********
 *
 *  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
 *
 */
function transfer_state_properties(state_decl) {
    state_decl.declarations.map((d) => {
        switch (d.key) {
            case 'shape':
                state_decl.shape = d.value;
                break;
            case 'color':
                state_decl.color = d.value;
                break;
            case 'corners':
                state_decl.corners = d.value;
                break;
            case 'line-style':
                state_decl.lineStyle = d.value;
                break;
            case 'text-color':
                state_decl.textColor = d.value;
                break;
            case 'background-color':
                state_decl.backgroundColor = d.value;
                break;
            case 'state-label':
                state_decl.stateLabel = d.value;
                break;
            case 'border-color':
                state_decl.borderColor = d.value;
                break;
            case 'state_property':
                state_decl.property = { name: d.name, value: d.value };
                break;
            default: throw new JssmError(undefined, `Unknown state property: '${JSON.stringify(d)}'`);
        }
    });
    return state_decl;
}
function state_style_condense(jssk) {
    const state_style = {};
    if (Array.isArray(jssk)) {
        jssk.forEach((key, i) => {
            if (typeof key !== 'object') {
                throw new JssmError(this, `invalid state item ${i} in state_style_condense list: ${JSON.stringify(key)}`);
            }
            switch (key.key) {
                case 'shape':
                    if (state_style.shape !== undefined) {
                        throw new JssmError(this, `cannot redefine 'shape' in state_style_condense, already defined`);
                    }
                    state_style.shape = key.value;
                    break;
                case 'color':
                    if (state_style.color !== undefined) {
                        throw new JssmError(this, `cannot redefine 'color' in state_style_condense, already defined`);
                    }
                    state_style.color = key.value;
                    break;
                case 'text-color':
                    if (state_style.textColor !== undefined) {
                        throw new JssmError(this, `cannot redefine 'text-color' in state_style_condense, already defined`);
                    }
                    state_style.textColor = key.value;
                    break;
                case 'corners':
                    if (state_style.corners !== undefined) {
                        throw new JssmError(this, `cannot redefine 'corners' in state_style_condense, already defined`);
                    }
                    state_style.corners = key.value;
                    break;
                case 'line-style':
                    if (state_style.lineStyle !== undefined) {
                        throw new JssmError(this, `cannot redefine 'line-style' in state_style_condense, already defined`);
                    }
                    state_style.lineStyle = key.value;
                    break;
                case 'background-color':
                    if (state_style.backgroundColor !== undefined) {
                        throw new JssmError(this, `cannot redefine 'background-color' in state_style_condense, already defined`);
                    }
                    state_style.backgroundColor = key.value;
                    break;
                case 'state-label':
                    if (state_style.stateLabel !== undefined) {
                        throw new JssmError(this, `cannot redefine 'state-label' in state_style_condense, already defined`);
                    }
                    state_style.stateLabel = key.value;
                    break;
                case 'border-color':
                    if (state_style.borderColor !== undefined) {
                        throw new JssmError(this, `cannot redefine 'border-color' in state_style_condense, already defined`);
                    }
                    state_style.borderColor = key.value;
                    break;
                default:
                    // TODO do that <never> trick to assert this list is complete
                    throw new JssmError(this, `unknown state style key in condense: ${key.key}`);
            }
        });
    }
    else if (jssk === undefined) {
        // do nothing, undefined is legal and means we should return the empty container above
    }
    else {
        throw new JssmError(this, 'state_style_condense received a non-array');
    }
    return state_style;
}
// TODO add a lotta docblock here
class Machine {
    // whargarbl this badly needs to be broken up, monolith master
    constructor({ start_states, end_states = [], 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 = undefined, arrange_declaration = [], arrange_start_declaration = [], arrange_end_declaration = [], theme = 'default', flow = 'down', graph_layout = 'dot', 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 }) {
        this._instance_name = instance_name;
        this._state = start_states[0];
        this._states = new Map();
        this._state_declarations = new Map();
        this._edges = [];
        this._edge_map = new Map();
        this._named_transitions = new Map();
        this._actions = new Map();
        this._reverse_actions = new Map();
        this._reverse_action_targets = new Map(); // todo
        this._start_states = new Set(start_states);
        this._end_states = new Set(end_states); // todo consider what to do about incorporating complete too
        this._machine_author = array_box_if_string(machine_author);
        this._machine_comment = machine_comment;
        this._machine_contributor = array_box_if_string(machine_contributor);
        this._machine_definition = machine_definition;
        this._machine_language = machine_language;
        this._machine_license = machine_license;
        this._machine_name = machine_name;
        this._machine_version = machine_version;
        this._raw_state_declaration = state_declaration || [];
        this._fsl_version = fsl_version;
        this._arrange_declaration = arrange_declaration;
        this._arrange_start_declaration = arrange_start_declaration;
        this._arrange_end_declaration = arrange_end_declaration;
        this._dot_preamble = dot_preamble;
        this._themes = [theme];
        this._flow = flow;
        this._graph_layout = graph_layout;
        this._has_hooks = false;
        this._has_basic_hooks = false;
        this._has_named_hooks = false;
        this._has_entry_hooks = false;
        this._has_exit_hooks = false;
        this._has_global_action_hooks = false;
        this._has_transition_hooks = true;
        // no need for a boolean for single hooks, just test for undefinedness
        this._hooks = new Map();
        this._named_hooks = new Map();
        this._entry_hooks = new Map();
        this._exit_hooks = new Map();
        this._global_action_hooks = new Map();
        this._any_action_hook = undefined;
        this._standard_transition_hook = undefined;
        this._main_transition_hook = undefined;
        this._forced_transition_hook = undefined;
        this._any_transition_hook = undefined;
        this._has_post_hooks = false;
        this._has_post_basic_hooks = false;
        this._has_post_named_hooks = false;
        this._has_post_entry_hooks = false;
        this._has_post_exit_hooks = false;
        this._has_post_global_action_hooks = false;
        this._has_post_transition_hooks = true;
        // no need for a boolean for single hooks, just test for undefinedness
        this._post_hooks = new Map();
        this._post_named_hooks = new Map();
        this._post_entry_hooks = new Map();
        this._post_exit_hooks = new Map();
        this._post_global_action_hooks = new Map();
        this._post_any_action_hook = undefined;
        this._post_standard_transition_hook = undefined;
        this._post_main_transition_hook = undefined;
        this._post_forced_transition_hook = undefined;
        this._post_any_transition_hook = undefined;
        this._data = data;
        this._property_keys = new Set();
        this._default_properties = new Map();
        this._state_properties = new Map();
        this._required_properties = new Set();
        this._state_style = state_style_condense(default_state_config);
        this._active_state_style = state_style_condense(default_active_state_config);
        this._hooked_state_style = state_style_condense(default_hooked_state_config);
        this._terminal_state_style = state_style_condense(default_terminal_state_config);
        this._start_state_style = state_style_condense(default_start_state_config);
        this._end_state_style = state_style_condense(default_end_state_config);
        this._history_length = history || 0;
        this._history = new circular_buffer(this._history_length);
        this._state_labels = new Map();
        // consolidate the state declarations
        if (state_declaration) {
            state_declaration.map((state_decl) => {
                if (this._state_declarations.has(state_decl.state)) { // no repeats
                    throw new JssmError(this, `Added the same state declaration twice: ${JSON.stringify(state_decl.state)}`);
                }
                this._state_declarations.set(state_decl.state, transfer_state_properties(state_decl));
            });
        }
        // walk the decls for labels; aggregate them when found
        [...this._state_declarations].map(sd => {
            const [key, decl] = sd, labelled = decl.declarations.filter(d => d.key === 'state-label');
            if (labelled.length > 1) {
                throw new JssmError(this, `state ${key} may only have one state-label; has ${labelled.length}`);
            }
            if (labelled.length === 1) {
                this._state_labels.set(key, labelled[0].value);
            }
        });
        // walk the transitions
        transitions.map((tr) => {
            if (tr.from === undefined) {
                throw new JssmError(this, `transition must define 'from': ${JSON.stringify(tr)}`);
            }
            if (tr.to === undefined) {
                throw new JssmError(this, `transition must define 'to': ${JSON.stringify(tr)}`);
            }
            // get the cursors.  what a mess
            const cursor_from = this._states.get(tr.from)
                || { name: tr.from, from: [], to: [], complete: complete.includes(tr.from) };
            if (!(this._states.has(tr.from))) {
                this._new_state(cursor_from);
            }
            const cursor_to = this._states.get(tr.to)
                || { name: tr.to, from: [], to: [], complete: complete.includes(tr.to) };
            if (!(this._states.has(tr.to))) {
                this._new_state(cursor_to);
            }
            // guard against existing connections being re-added
            if (cursor_from.to.includes(tr.to)) {
                throw new JssmError(this, `already has ${JSON.stringify(tr.from)} to ${JSON.stringify(tr.to)}`);
            }
            else {
                cursor_from.to.push(tr.to);
                cursor_to.from.push(tr.from);
            }
            // add the edge; note its id
            this._edges.push(tr);
            const thisEdgeId = this._edges.length - 1;
            // guard against repeating a transition name
            if (tr.name) {
                if (this._named_transitions.has(tr.name)) {
                    throw new JssmError(this, `named transition "${JSON.stringify(tr.name)}" already created`);
                }
                else {
                    this._named_transitions.set(tr.name, thisEdgeId);
                }
            }
            // set up the mapping, so that edges can be looked up by endpoint pairs
            const from_mapping = this._edge_map.get(tr.from) || new Map();
            if (!(this._edge_map.has(tr.from))) {
                this._edge_map.set(tr.from, from_mapping);
            }
            //    const to_mapping = from_mapping.get(tr.to);
            from_mapping.set(tr.to, thisEdgeId); // already checked that this mapping doesn't exist, above
            // set up the action mapping, so that actions can be looked up by origin
            if (tr.action) {
                // forward mapping first by action name
                let actionMap = this._actions.get(tr.action);
                if (!(actionMap)) {
                    actionMap = new Map();
                    this._actions.set(tr.action, actionMap);
                }
                if (actionMap.has(tr.from)) {
                    throw new JssmError(this, `action ${JSON.stringify(tr.action)} already attached to origin ${JSON.stringify(tr.from)}`);
                }
                else {
                    actionMap.set(tr.from, thisEdgeId);
                }
                // reverse mapping first by state origin name
                let rActionMap = this._reverse_actions.get(tr.from);
                if (!(rActionMap)) {
                    rActionMap = new Map();
                    this._reverse_actions.set(tr.from, rActionMap);
                }
                // no need to test for reverse mapping pre-presence;
                // forward mapping already covers collisions
                rActionMap.set(tr.action, thisEdgeId);
                // reverse mapping first by state target name
                if (!(this._reverse_action_targets.has(tr.to))) {
                    this._reverse_action_targets.set(tr.to, new Map());
                }
                /* todo comeback
                   fundamental problem is roActionMap needs to be a multimap
                        const roActionMap = this._reverse_action_targets.get(tr.to);  // wasteful - already did has - refactor
                        if (roActionMap) {
                          if (roActionMap.has(tr.action)) {
                            throw new JssmError(this, `ro-action ${tr.to} already attached to action ${tr.action}`);
                          } else {
                            roActionMap.set(tr.action, thisEdgeId);
                          }
                        } else {
                          throw new JssmError(this, `should be impossible - flow doesn\'t know .set precedes .get yet again.  severe error?');
                        }
                */
            }
        });
        if (Array.isArray(property_definition)) {
            property_definition.forEach(pr => {
                this._property_keys.add(pr.name);
                if (pr.hasOwnProperty('default_value')) {
                    this._default_properties.set(pr.name, pr.default_value);
                }
                if (pr.hasOwnProperty('required') && (pr.required === true)) {
                    this._required_properties.add(pr.name);
                }
            });
        }
        if (Array.isArray(state_property)) {
            state_property.forEach(sp => {
                this._state_properties.set(sp.name, sp.default_value);
            });
        }
        // done building, do checks
        this._state_properties.forEach((_value, key) => {
            const inside = JSON.parse(key);
            if (Array.isArray(inside)) {
                const j_property = inside[0];
                if (typeof j_property === 'string') {
                    const j_state = inside[1];
                    if (typeof j_state === 'string') {
                        if (!(this.known_prop(j_property))) {
                            throw new JssmError(this, `State "${j_state}" has property "${j_property}" which is not globally declared`);
                        }
                    }
                }
            }
        });
        this._required_properties.forEach(dp_key => {
            if (this._default_properties.has(dp_key)) {
                throw new JssmError(this, `The property "${dp_key}" is required, but also has a default; these conflict`);
            }
            this.states().forEach(s => {
                const bound_name = name_bind_prop_and_state(dp_key, s);
                if (!(this._state_properties.has(bound_name))) {
                    throw new JssmError(this, `State "${s}" is missing required property "${dp_key}"`);
                }
            });
        });
    }
    /********
     *
     *  Internal method for fabricating states.  Not meant for external use.
     *
     *  @internal
     *
     */
    _new_state(state_config) {
        if (this._states.has(state_config.name)) {
            throw new JssmError(this, `state ${JSON.stringify(state_config.name)} already exists`);
        }
        this._states.set(state_config.name, state_config);
        return state_config.name;
    }
    /*********
     *
     *  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
     *
     */
    state() {
        return this._state;
    }
    /*********
     *
     *  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!'
     *  ```
     *
     *  @typeparam mDT The type of the machine data member; usually omitted
     *
     */
    label_for(state) {
        return this._state_labels.get(state);
    }
    /*********
     *
     *  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
     *
     */
    data() {
        return this._data;
    }
    // NEEDS_DOCS
    /*********
     *
     *  Get the current value of a given property name.
     *
     *  ```typescript
     *
     *  ```
     *
     *  @param name The relevant property name to look up
     *
     *  @returns The value behind the prop name.  Because functional props are
     *  evaluated as getters, this can be anything.
     *
     */
    prop(name) {
        const bound_name = name_bind_prop_and_state(name, this.state());
        if (this._state_properties.has(bound_name)) {
            return this._state_properties.get(bound_name);
        }
        else if (this._default_properties.has(name)) {
            return this._default_properties.get(name);
        }
        else {
            return undefined;
        }
    }
    // NEEDS_DOCS
    /*********
     *
     *  Get the current value of a given property name.  If missing on the state
     *  and without a global default, throw, unlike {@link prop}, which would
     *  return `undefined` instead.
     *
     *  ```typescript
     *
     *  ```
     *
     *  @param name The relevant property name to look up
     *
     *  @returns The value behind the prop name.  Because functional props are
     *  evaluated as getters, this can be anything.
     *
     */
    strict_prop(name) {
        const bound_name = name_bind_prop_and_state(name, this.state());
        if (this._state_properties.has(bound_name)) {
            return this._state_properties.get(bound_name);
        }
        else if (this._default_properties.has(name)) {
            return this._default_properties.get(name);
        }
        else {
            throw new JssmError(this, `Strictly requested a prop '${name}' which doesn't exist on current state '${this.state()}' and has no default`);
        }
    }
    // NEEDS_DOCS
    // COMEBACK add prop_map, sparse_props and strict_props to doc text when implemented
    /*********
     *
     *  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; }
     *  ```
     *
     */
    props() {
        const ret = {};
        this.known_props().forEach(p => ret[p] = this.prop(p));
        return ret;
    }
    // NEEDS_DOCS
    // TODO COMEBACK
    /*********
     *
     *  Get the current value of every prop, as an object.  Compare
     *  {@link prop_map}, which returns a `Map`.
     *
     *  ```typescript
     *
     *  ```
     *
     */
    // sparse_props(name: string): object {
    // }
    // NEEDS_DOCS
    // TODO COMEBACK
    /*********
     *
     *  Get the current value of every prop, as an object.  Compare
     *  {@link prop_map}, which returns a `Map`.  Akin to {@link strict_prop},
     *  this throws if a required prop is missing.
     *
     *  ```typescript
     *
     *  ```
     *
     */
    // strict_props(name: string): 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) {
        return this._property_keys.has(prop_name);
    }
    // NEEDS_DOCS
    /*********
     *
     *  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
     *  ```
     *
     */
    known_props() {
        return [...this._property_keys];
    }
    /********
     *
     *  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) {
        return this._start_states.has(whichState);
    }
    /********
     *
     *  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) {
        return this._end_states.has(whichState);
    }
    /********
     *
     *  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) {
        return ((this.state_is_terminal(whichState)) || (this.state_is_complete(whichState)));
    }
    /********
     *
     *  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() {
        //  return ((!this.is_changing()) && this.state_is_final(this.state()));
        return this.state_is_final(this.state());
    }
    /********
     *
     *  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
     *
     */
    serialize(comment) {
        return {
            comment,
            state: this._state,
            data: this._data,
            jssm_version: version,
            history: this._history.toArray(),
            history_capacity: this._history.capacity,
            timestamp: new Date().getTime(),
        };
    }
    graph_layout() {
        return this._graph_layout;
    }
    dot_preamble() {
        return this._dot_preamble;
    }
    machine_author() {
        return this._machine_author;
    }
    machine_comment() {
        return this._machine_comment;
    }
    machine_contributor() {
        return this._machine_contributor;
    }
    machine_definition() {
        return this._machine_definition;
    }
    machine_language() {
        return this._machine_language;
    }
    machine_license() {
        return this._machine_license;
    }
    machine_name() {
        return this._machine_name;
    }
    machine_version() {
        return this._machine_version;
    }
    raw_state_declarations() {
        return this._raw_state_declaration;
    }
    state_declaration(which) {
        return this._state_declarations.get(which);
    }
    state_declarations() {
        return this._state_declarations;
    }
    fsl_version() {
        return this._fsl_version;
    }
    machine_state() {
        return {
            internal_state_impl_version: 1,
            actions: this._actions,
            edge_map: this._edge_map,
            edges: this._edges,
            named_transitions: this._named_transitions,
            reverse_actions: this._reverse_actions,
            // reverse_action_targets : this._reverse_action_targets,
            state: this._state,
            states: this._states
        };
    }
    /*********
     *
     *  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
     *
     */
    states() {
        return Array.from(this._states.keys());
    }
    state_for(whichState) {
        const state = this._states.get(whichState);
        if (state) {
            return state;
        }
        else {
            throw new JssmError(this, 'No such state', { requested_state: whichState });
        }
    }
    /*********
     *
     *  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 extance
     *
     */
    has_state(whichState) {
        return this._states.get(whichState) !== undefined;
    }
    /*********
     *
     *  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
     *
     */
    list_edges() {
        return this._edges;
    }
    list_named_transitions() {
        return this._named_transitions;
    }
    list_actions() {
        return Array.from(this._actions.keys());
    }
    theme() {
        return this._themes[0]; // returns topmost only
    }
    themes() {
        return this._themes; // constructor sets this to "default" otherwise
    }
    flow() {
        return this._flow;
    }
    get_transition_by_state_names(from, to) {
        const emg = this._edge_map.get(from);
        if (emg) {
            return emg.get(to);
        }
        else {
            return undefined;
        }
    }
    lookup_transition_for(from, to) {
        const id = this.get_transition_by_state_names(from, to);
        return ((id === undefined) || (id === null)) ? undefined : this._edges[id];
    }
    /********
     *
     *  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 = this.state()) {
        return { entrances: this.list_entrances(whichState), exits: this.list_exits(whichState) };
    }
    /********
     *
     *  List all entrances attached to the current state.  Please note that the
     *  order of the list is not defined.
     *
     *  ```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 = this.state()) {
        return (this._states.get(whichState)
            || { from: undefined }).from
            || [];
    }
    /********
     *
     *  List all exits attached to the current state.  Please note that the order
     *  of the list is not defined.
     *
     *  ```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 = this.state()) {
        return (this._states.get(whichState)
            || { to: undefined }).to
            || [];
    }
    probable_exits_for(whichState) {
        const wstate = this._states.get(whichState);
        if (!(wstate)) {
            throw new JssmError(this, `No such state ${JSON.stringify(whichState)} in probable_exits_for`);
        }
        const wstate_to = wstate.to, wtf // wstate_to_filtered -> wtf
         = wstate_to
            .map((ws) => this.lookup_transition_for(this.state(), ws))
            .filter(Boolean);
        return wtf;
    }
    probabilistic_transition() {
        const selected = weighted_rand_select(this.probable_exits_for(this.state()));
        return this.transition(selected.to);
    }
    probabilistic_walk(n) {
        return seq(n)
            .map(() => {
            const state_was = this.state();
            this.probabilistic_transition();
            return state_was;
        })
            .concat([this.state()]);
    }
    probabilistic_histo_walk(n) {
        return histograph(this.probabilistic_walk(n));
    }
    /********
     *
     *  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 have listed
     *
     */
    actions(whichState = this.state()) {
        const wstate = this._reverse_actions.get(whichState);
        if (wstate) {
            return Array.from(wstate.keys());
        }
        else {
            throw new JssmError(this, `No such state ${JSON.stringify(whichState)}`);
        }
    }
    /********
     *
     *  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) {
        const wstate = this._actions.get(whichState);
        if (wstate) {
            return Array.from(wstate.keys());
        }
        else {
            throw new JssmError(this, `No such state ${JSON.stringify(whichState)}`);
        }
    }
    // comeback
    /*
      list_entrance_actions(whichState: mNT = this.state() ) : Array<mNT> {
        return [... (this._reverse_action_targets.get(whichState) || new Map()).values()] // wasteful
               .map( (edgeId:any) => (this._edges[edgeId] : any)) // whargarbl burn out any
               .filter( (o:any) => o.to === whichState)
               .map( filtered => filtered.from );
      }
    */
    list_exit_actions(whichState = this.state()) {
        const ra_base = this._reverse_actions.get(whichState);
        if (!(ra_base)) {
            throw new JssmError(this, `No such state ${JSON.stringify(whichState)}`);
        }
        return Array.from(ra_base.values())
            .map((edgeId) => this._edges[edgeId])
            .filter((o) => o.from === whichState)
            .map((filtered) => filtered.action);
    }
    probable_action_exits(whichState = this.state()) {
        const ra_base = this._reverse_actions.get(whichState);
        if (!(ra_base)) {
            throw new JssmError(this, `No such state ${JSON.stringify(whichState)}`);
        }
        return Array.from(ra_base.values())
            .map((edgeId) => this._edges[edgeId])
            .filter((o) => o.from === whichState)
            .map((filtered) => ({
            action: filtered.action,
            probability: filtered.probability
        }));
    }
    // TODO FIXME test that is_unenterable on non-state throws
    is_unenterable(whichState) {
        if (!(this.has_state(whichState))) {
            throw new JssmError(this, `No such state ${whichState}`);
        }
        return this.list_entrances(whichState).length === 0;
    }
    has_unenterables() {
        return this.states().some((x) => this.is_unenterable(x));
    }
    is_terminal() {
        return this.state_is_terminal(this.state());
    }
    // TODO FIXME test that state_is_terminal on non-state throws
    state_is_terminal(whichState) {
        if (!(this.has_state(whichState))) {
            throw new JssmError(this, `No such state ${whichState}`);
        }
        return this.list_exits(whichState).length === 0;
    }
    has_terminals() {
        return this.states().some((x) => this.state_is_terminal(x));
    }
    is_complete() {
        return this.state_is_complete(this.state());
    }
    state_is_complete(whichState) {
        const wstate = this._states.get(whichState);
        if (wstate) {
            return wstate.complete;
        }
        else {
            throw new JssmError(this, `No such state ${JSON.stringify(whichState)}`);
        }
    }
    has_completes() {
        return this.states().some((x) => this.state_is_complete(x));
    }
    // basic toolable hook call.  convenience wrappers will follow, like
    // hook(from, to, handler) and exit_hook(from, handler) and etc
    set_hook(HookDesc) {
        switch (HookDesc.kind) {
            case 'hook':
                this._hooks.set(hook_name(HookDesc.from, HookDesc.to), HookDesc.handler);
                this._has_hooks = true;
                this._has_basic_hooks = true;
                break;
            case 'named':
                this._named_hooks.set(named_hook_name(HookDesc.from, HookDesc.to, HookDesc.action), HookDesc.handler);
                this._has_hooks = true;
                this._has_named_hooks = true;
                break;
            case 'global action':
                this._global_action_hooks.set(HookDesc.action, HookDesc.handler);
                this._has_hooks = true;
                this._has_global_action_hooks = true;
                break;
            case 'any action':
                this._any_action_hook = HookDesc.handler;
                this._has_hooks = true;
                break;
            case 'standard transition':
                this._standard_transition_hook = HookDesc.handler;
                this._has_transition_hooks = true;
                this._has_hooks = true;
                break;
            case 'main transition':
                this._main_transition_hook = HookDesc.handler;
                this._has_transition_hooks = true;
                this._has_hooks = true;
                break;
            case 'forced transition':
                this._forced_transition_hook = HookDesc.handler;
                this._has_transition_hooks = true;
                this._has_hooks = true;
                break;
            case 'any transition':
                this._any_transition_hook = HookDesc.handler;
                this._has_hooks = true;
                break;
            case 'entry':
                this._entry_hooks.set(HookDesc.to, HookDesc.handler);
                this._has_hooks = true;
                this._has_entry_hooks = true;
                break;
            case 'exit':
                this._exit_hooks.set(HookDesc.from, HookDesc.handler);
                this._has_hooks = true;
                this._has_exit_hooks = true;
                break;
            case 'post hook':
                this._post_hooks.set(hook_name(HookDesc.from, HookDesc.to), HookDesc.handler);
                this._has_post_hooks = true;
                this._has_post_basic_hooks = true;
                break;
            case 'post named':
                this._post_named_hooks.set(named_hook_name(HookDesc.from, HookDesc.to, HookDesc.action), HookDesc.handler);
                this._has_post_hooks = true;
                this._has_post_named_hooks = true;
                break;
            case 'post global action':
                this._post_global_action_hooks.set(HookDesc.action, HookDesc.handler);
                this._has_post_hooks = true;
                this._has_post_global_action_hooks = true;
                break;
            case 'post any action':
                this._post_any_action_hook = HookDesc.handler;
                this._has_post_hooks = true;
                break;
            case 'post standard transition':
                this._post_standard_transition_hook = HookDesc.handler;
                this._has_post_transition_hooks = true;
                this._has_post_hooks = true;
                break;
            case 'post main transition':
                this._post_main_transition_hook = HookDesc.handler;
                this._has_post_transition_hooks = true;
                this._has_post_hooks = true;
                break;
            case 'post forced transition':
                this._post_forced_transition_hook = HookDesc.handler;
                this._has_post_transition_hooks = true;
                this._has_post_hooks = true;
                break;
            case 'post any transition':
                this._post_any_transition_hook = HookDesc.handler;
                this._has_post_hooks = true;
                break;
            case 'post entry':
                this._post_entry_hooks.set(HookDesc.to, HookDesc.handler);
                this._has_post_entry_hooks = true;
                this._has_post_hooks = true;
                break;
            case 'post exit':
                this._post_exit_hooks.set(HookDesc.from, HookDesc.handler);
                this._has_post_exit_hooks = true;
                this._has_post_hooks = true;
                break;
            default:
                throw new JssmError(this, `Unknown hook type ${HookDesc.kind}, should be impossible`);
        }
    }
    hook(from, to, handler) {
        this.set_hook({ kind: 'hook', from, to, handler });
        return this;
    }
    hook_action(from, to, action, handler) {
        this.set_hook({ kind: 'named', from, to, action, handler });
        return this;
    }
    hook_global_action(action, handler) {
        this.set_hook({ kind: 'global action', action, handler });
        return this;
    }
    hook_any_action(handler) {
        this.set_hook({ kind: 'any action', handler });
        return this;
    }
    hook_standard_transition(handler) {
        this.set_hook({ kind: 'standard transition', handler });
        return this;
    }
    hook_main_transition(handler) {
        this.set_hook({ kind: 'main transition', handler });
        return this;
    }
    hook_forced_transition(handler) {
        this.set_hook({ kind: 'forced transition', handler });
        return this;
    }
    hook_any_transition(handler) {
        this.set_hook({ kind: 'any transition', handler });
        return this;
    }
    hook_entry(to, handler) {
        this.set_hook({ kind: 'entry', to, handler });
        return this;
    }
    hook_exit(from, handler) {
        this.set_hook({ kind: 'exit', from, handler });
        return this;
    }
    post_hook(from, to, handler) {
        this.set_hook({ kind: 'post hook', from, to, handler });
        return this;
    }
    post_hook_action(from, to, action, handler) {
        this.set_hook({ kind: 'post named', from, to, action, handler });
        return this;
    }
    post_hook_global_action(action, handler) {
        this.set_hook({ kind: 'post global action', action, handler });
        return this;
    }
    post_hook_any_action(handler) {
        this.set_hook({ kind: 'post any action', handler });
        return this;
    }
    post_hook_standard_transition(handler) {
        this.set_hook({ kind: 'post standard transition', handler });
        return this;
    }
    post_hook_main_transition(handler) {
        this.set_hook({ kind: 'post main transition', handler });
        return this;
    }
    post_hook_forced_transition(handler) {
        this.set_hook({ kind: 'post forced transition', handler });
        return this;
    }
    post_hook_any_transition(handler) {
        this.set_hook({ kind: 'post any transition', handler });
        return this;
    }
    post_hook_entry(to, handler) {
        this.set_hook({ kind: 'post entry', to, handler });
        return this;
    }
    post_hook_exit(from, handler) {
        this.set_hook({ kind: 'post exit', from, handler });
        return this;
    }
    // remove_hook(HookDesc: HookDescription) {
    //   throw new JssmError(this, 'TODO: Should remove hook here');
    // }
    edges_between(from, to) {
        return this._edges.filter(edge => ((edge.from === from) && (edge.to === to)));
    }
    transition_impl(newStateOrAction, newData, wasForced, wasAction) {
        // TODO the forced-ness behavior needs to be cleaned up a lot here
        // TODO all the callbacks are wrong on forced, action, etc
        let valid = false, trans_type, newState, fromAction = undefined;
        if (wasForced) {
            if (this.valid_force_transition(newStateOrAction, newData)) {
                valid = true;
                trans_type = 'forced';
                newState = newStateOrAction;
            }
        }
        else if (wasAction) {
            if (this.valid_action(newStateOrAction, newData)) {
                const edge = this.current_action_edge_for(newStateOrAction);
                valid = true;
                trans_type = edge.kind;
                newState = edge.to;
                fromAction = newStateOrAction;
            }
        }
        else {
            if (this.valid_transition(newStateOrAction, newData)) {
                if (this._has_transition_hooks) {
                    trans_type = this.edges_between(this._state, newStateOrAction)[0].kind; // TODO this won't do the right thing if various edges have different types
                }
                valid = true;
                newState = newStateOrAction;
            }
        }
        const hook_args = {
            data: this._data,
            action: fromAction,
            from: this._state,
            to: newState,
            forced: wasForced,
            trans_type
        };
        if (valid) {
            if (this._has_hooks) {
                function update_fields(res) {
                    if (res.hasOwnProperty('data')) {
                        hook_args.data = res.data;
                        data_changed = true;
                    }
                }
                let data_changed = false;
                if (wasAction) {
                    // 1. any action hook
                    const outcome = abstract_hook_step(this._any_action_hook, hook_args);
                    if (outcome.pass === false) {
                        return false;
                    }
                    update_fields(outcome);
                    // 2. global specific action hook
                    const outcome2 = abstract_hook_step(this._global_action_hooks.get(newStateOrAction), hook_args);
                    if (outcome2.pass === false) {
                        return false;
                    }
                    update_fields(outcome2);
                }
                // 3. any transition hook
                if (this._any_transition_hook !== undefined) {
                    const outcome = abstract_hook_step(this._any_transition_hook, hook_args);
                    if (outcome.pass === false) {
                        return false;
                    }
                    update_fields(outcome);
                }
                // 4. exit hook
                if (this._has_exit_hooks) {
                    const outcome = abstract_hook_step(this._exit_hooks.get(this._state), hook_args);
                    if (outcome.pass === false) {
                        return false;
                    }
                    update_fields(outcome);
                }
                // 5. named transition / action hook
                if (this._has_named_hooks) {
                    if (wasAction) {
                        const nhn = named_hook_name(this._state, newState, newStateOrAction), outcome = abstract_hook_step(this._named_hooks.get(nhn), hook_args);
                        if (outcome.pass === false) {
                            return false;
                        }
                        update_fields(outcome);
                    }
                }
                // 6. regular hook
                if (this._has_basic_hooks) {
                    const hn = hook_name(this._state, newState), outcome = abstract_hook_step(this._hooks.get(hn), hook_args);
                    if (outcome.pass === false) {
                        return false;
                    }
                    update_fields(outcome);
                }
                // 7. edge type hook
                // 7a. standard transition hook
                if (trans_type === 'legal') {
                    const outcome = abstract_hook_step(this._standard_transition_hook, hook_args);
                    if (outcome.pass === false) {
                        return false;
                    }
                    update_fields(outcome);
                }
                // 7b. main type hook
                if (trans_type === 'main') {
                    const outcome = abstract_hook_step(this._main_transition_hook, hook_args);
                    if (outcome.pass === false) {
                        return false;
                    }
                    update_fields(outcome);
                }
                // 7c. forced transition hook
                if (trans_type === 'forced') {
                    const outcome = abstract_hook_step(this._forced_transition_hook, hook_args);
                    if (outcome.pass === false) {
                        return false;
                    }
                    update_fields(outcome);
                }
                // 8. entry hook
                if (this._has_entry_hooks) {
                    const outcome = abstract_hook_step(this._entry_hooks.get(newState), hook_args);
                    if (outcome.pass === false) {
                        return false;
                    }
                    update_fields(outcome);
                }
                // all hooks passed!  let's now establish the result
                if (this._history_length) {
                    this._history.shove([this._state, this._data]);
                }
                this._state = newState;
                if (data_changed) {
                    this._data = hook_args.data;
                }
                // success fallthrough to posthooks; intentionally no return here
                // look for "posthooks begin here"
                // or without hooks
            }
            else {
                if (this._history_length) {
                    this._history.shove([this._state, this._data]);
                }
                this._state = newState;
                // success fallthrough to posthooks; intentionally no return here
                // look for "posthooks begin here"
            }
            // not valid
        }
        else {
            return false;
        }
        // posthooks begin here
        if (this._has_post_hooks) {
            if (wasAction) {
                // 1. any action posthook
                if (this._post_any_action_hook !== undefined) {
                    this._post_any_action_hook(hook_args);
                }
                // 2. global specific action hook
                const pgah = this._post_global_action_hooks.get(hook_args.action);
                if (pgah !== undefined) {
                    pgah(hook_args);
                }
            }
            // 3. any transition hook
            if (this._post_any_transition_hook !== undefined) {
                this._post_any_transition_hook(hook_args);
            }
            // 4. exit hook
            if (this._has_post_exit_hooks) {
                const peh = this._post_exit_hooks.get(hook_args.from); // todo this is probably from instead
                if (peh !== undefined) {
                    peh(hook_args);
                }
            }
            // 5. named transition / action hook
            if (this._has_post_named_hooks) {
                if (wasAction) {
                    const nhn = named_hook_name(hook_args.from, hook_args.to, hook_args.action), pnh = this._post_named_hooks.get(nhn);
                    if (pnh !== undefined) {
                        pnh(hook_args);
                    }
                }
            }
            // 6. regular hook
            if (this._has_post_basic_hooks) {
                const hook = this._post_hooks.get(hook_name(hook_args.from, hook_args.to));
                if (hook !== undefined) {
                    hook(hook_args);
                }
            }
            // 7. edge type hook
            // 7a. standard transition hook
            if (trans_type === 'legal') {
                if (this._post_standard_transition_hook !== undefined) {
                    this._post_standard_transition_hook(hook_args);
                }
            }
            // 7b. main type hook
            if (trans_type === 'main') {
                if (this._post_main_transition_hook !== undefined) {
                    this._post_main_transition_hook(hook_args);
                }
            }
            // 7c. forced transition hook
            if (trans_type === 'forced') {
                if (this._post_forced_transition_hook !== undefined) {
                    this._post_forced_transition_hook(hook_args);
                }
            }
            // 8. entry hook
            if (this._has_post_entry_hooks) {
                const hook = this._post_entry_hooks.get(hook_args.to);
                if (hook !== undefined) {
                    hook(hook_args);
                }
            }
        }
        return true;
    }
    /*********
     *
     *  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() {
        return this._history.toArray();
    }
    /*********
     *
     *  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() {
        const ret = this._history.toArray();
        ret.push([this.state(), this.data()]);
        return ret;
    }
    /*********
     *
     *  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() {
        return this._history_length;
    }
    set history_length(to) {
        this._history_length = to;
        this._history.resize(to, true);
    }
    /********
     *
     *  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
     *
     */
    action(actionName, newData) {
        return this.transition_impl(actionName, newData, false, true);
    }
    /********
     *
     *  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
     *
     */
    get standard_state_style() {
        return this._state_style;
    }
    /********
     *
     *  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
     *
     */
    get hooked_state_style() {
        return this._hooked_state_style;
    }
    /********
     *
     *  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
     *
     */
    get start_state_style() {
        return this._start_state_style;
    }
    /********
     *
     *  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
     *
     */
    get end_state_style() {
        return this._end_state_style;
    }
    /********
     *
     *  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
     *
     */
    get terminal_state_style() {
        return this._terminal_state_style;
    }
    /********
     *
     *  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
     *
     */
    get active_state_style() {
        return this._active_state_style;
    }
    /*
     */
    // TODO COMEBACK IMPLEMENTME FIXME
    has_hooks(state) {
        return false;
    }
    /********
     *
     *  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
     *
     */
    style_for(state) {
        // TODO
        const themes = [];
        // basic state style
        const layers = [base_theme.state];
        themes.map(theme => {
            if (theme.state) {
                layers.push(theme.state);
            }
        });
        if (this._state_style) {
            layers.push(this._state_style);
        }
        // hooked state style
        if (this.has_hooks(state)) {
            layers.push(base_theme.hooked);
            themes.map(theme => {
                if (theme.hooked) {
                    layers.push(theme.hooked);
                }
            });
            if (this._hooked_state_style) {
                layers.push(this._hooked_state_style);
            }
        }
        // terminal state style
        if (this.state_is_terminal(state)) {
            layers.push(base_theme.terminal);
            themes.map(theme => {
                if (theme.terminal) {
                    layers.push(theme.terminal);
                }
            });
            if (this._terminal_state_style) {
                layers.push(this._terminal_state_style);
            }
        }
        // start state style
        if (this.is_start_state(state)) {
            layers.push(base_theme.start);
            themes.map(theme => {
                if (theme.start) {
                    layers.push(theme.start);
                }
            });
            if (this._start_state_style) {
                layers.push(this._start_state_style);
            }
        }
        // end state style
        if (this.is_end_state(state)) {
            layers.push(base_theme.end);
            themes.map(theme => {
                if (theme.end) {
                    layers.push(theme.end);
                }
            });
            if (this._end_state_style) {
                layers.push(this._end_state_style);
            }
        }
        // active state style
        if (this.state() === state) {
            layers.push(base_theme.active);
            themes.map(theme => {
                if (theme.active) {
                    layers.push(theme.active);
                }
            });
            if (this._active_state_style) {
                layers.push(this._active_state_style);
            }
        }
        const individual_style = {}, decl = this._state_declarations.get(state);
        individual_style.color = decl === null || decl === void 0 ? void 0 : decl.color;
        individual_style.textColor = decl === null || decl === void 0 ? void 0 : decl.textColor;
        individual_style.borderColor = decl === null || decl === void 0 ? void 0 : decl.borderColor;
        individual_style.backgroundColor = decl === null || decl === void 0 ? void 0 : decl.backgroundColor;
        individual_style.lineStyle = decl === null || decl === void 0 ? void 0 : decl.lineStyle;
        individual_style.corners = decl === null || decl === void 0 ? void 0 : decl.corners;
        individual_style.shape = decl === null || decl === void 0 ? void 0 : decl.shape;
        layers.push(individual_style);
        return layers.reduce((acc, cur) => {
            const composite_state = acc;
            Object.keys(cur).forEach(key => { var _a; return composite_state[key] = (_a = cur[key]) !== null && _a !== void 0 ? _a : composite_state[key]; });
            return composite_state;
        }, {});
    }
    /********
     *
     *  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
     *
     */
    do(actionName, newData) {
        return this.transition_impl(actionName, newData, false, true);
    }
    /********
     *
     *  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
     *
     */
    transition(newState, newData) {
        return this.transition_impl(newState, newData, false, false);
    }
    /********
     *
     *  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
     *
     */
    go(newState, newData) {
        return this.transition_impl(newState, newData, false, false);
    }
    /********
     *
     *  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
     *
     */
    force_transition(newState, newData) {
        return this.transition_impl(newState, newData, true, false);
    }
    current_action_for(action) {
        const action_base = this._actions.get(action);
        return action_base
            ? action_base.get(this.state())
            : undefined;
    }
    current_action_edge_for(action) {
        const idx = this.current_action_for(action);
        if ((idx === undefined) || (idx === null)) {
            throw new JssmError(this, `No such action ${JSON.stringify(action)}`);
        }
        return this._edges[idx];
    }
    valid_action(action, _newData) {
        // todo whargarbl implement data stuff
        // todo major incomplete whargarbl comeback
        return this.current_action_for(action) !== undefined;
    }
    valid_transition(newState, _newData) {
        // todo whargarbl implement data stuff
        // todo major incomplete whargarbl comeback
        const transition_for = this.lookup_transition_for(this.state(), newState);
        if (!(transition_for)) {
            return false;
        }
        if (transition_for.forced_only) {
            return false;
        }
        return true;
    }
    valid_force_transition(newState, _newData) {
        // todo whargarbl implement data stuff
        // todo major incomplete whargarbl comeback
        return (this.lookup_transition_for(this.state(), newState) !== undefined);
    }
    instance_name() {
        return this._instance_name;
    }
    /* eslint-disable no-use-before-define */
    /* eslint-disable class-methods-use-this */
    sm(template_strings, ...remainder /* , arguments */) {
        return sm(template_strings, ...remainder);
    }
}
/*********
 *
 *  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
 *
 */
function sm(template_strings, ...remainder /* , arguments */) {
    // foo`a${1}b${2}c` will come in as (['a','b','c'],1,2)
    // this includes when a and c are empty strings
    // therefore template_strings will always have one more el than template_args
    // therefore map the smaller container and toss the last one on on the way out
    return new Machine(make(template_strings.reduce(
    // in general avoiding `arguments` is smart.  however with the template
    // string notation, as designed, it's not really worth the hassle
    /* eslint-disable prefer-rest-params */
    (acc, val, idx) => `${acc}${remainder[idx - 1]}${val}` // arguments[0] is never loaded, so args doesn't need to be gated
    /* eslint-enable  prefer-rest-params */
    )));
}
/*********
 *
 *  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
 *
 */
function from(MachineAsString, ExtraConstructorFields) {
    const to_decorate = make(MachineAsString);
    if (ExtraConstructorFields !== undefined) {
        Object.keys(ExtraConstructorFields).map(key => to_decorate[key] = ExtraConstructorFields[key]);
    }
    return new Machine(to_decorate);
}
function is_hook_complex_result(hr) {
    if (typeof hr === 'object') {
        if (typeof hr.pass === 'boolean') {
            return true;
        }
    }
    return false;
}
function is_hook_rejection(hr) {
    if (hr === true) {
        return false;
    }
    if (hr === undefined) {
        return false;
    }
    if (hr === false) {
        return true;
    }
    if (is_hook_complex_result(hr)) {
        return (!(hr.pass));
    }
    throw new TypeError('unknown hook rejection type result');
}
function abstract_hook_step(maybe_hook, hook_args) {
    if (maybe_hook !== undefined) {
        const result = maybe_hook(hook_args);
        if (result === undefined) {
            return { pass: true };
        }
        if (result === true) {
            return { pass: true };
        }
        if (result === false) {
            return { pass: false };
        }
        if (is_hook_complex_result(result)) {
            return result;
        }
        throw new TypeError(`Unknown hook result type ${result}`);
    }
    else {
        return { pass: true };
    }
}
function deserialize(machine_string, ser) {
    const machine = from(machine_string, { data: ser.data, history: ser.history_capacity });
    machine._state = ser.state;
    ser.history.forEach(history_item => machine._history.push(history_item));
    return machine;
}
export { version, transfer_state_properties, Machine, deserialize, make, wrap_parse as parse, compile, sm, from, arrow_direction, arrow_left_kind, arrow_right_kind, 
// WHARGARBL TODO these should be exported to a utility library
seq, unique, find_repeated, weighted_rand_select, histograph, weighted_sample_select, weighted_histo_key, constants, shapes, gviz_shapes, named_colors, is_hook_rejection, is_hook_complex_result, abstract_hook_step, state_style_condense };