jssm 5.77.1 → 5.79.1

package/dist/es6/jssm.d.ts

@@ -1,8 +1,7 @@
 declare type StateType = string;
-import { circular_buffer } from 'circular_buffer_js';
 import { JssmGenericState, JssmGenericConfig, JssmTransition, JssmTransitionList, // JssmTransitionRule,
-JssmMachineInternalState, JssmParseTree, JssmStateDeclaration, JssmArrow, JssmArrowDirection, JssmArrowKind, JssmLayout, FslDirection, FslTheme, HookDescription, HookHandler, HookContext, HookResult, HookComplexResult } from './jssm_types';
-import { seq, weighted_rand_select, weighted_sample_select, histograph, weighted_histo_key } from './jssm_util';
+JssmMachineInternalState, JssmParseTree, JssmStateDeclaration, JssmArrow, JssmArrowDirection, JssmArrowKind, JssmLayout, JssmHistory, JssmSerialization, FslDirection, FslTheme, HookDescription, HookHandler, HookContext, HookResult, HookComplexResult } from './jssm_types';
+import { seq, unique, find_repeated, weighted_rand_select, weighted_sample_select, histograph, weighted_histo_key } from './jssm_util';
 import { shapes, gviz_shapes, named_colors } from './jssm_constants';
 import { version } from './version';
 /*********
@@ -251,9 +250,12 @@ declare class Machine<mDT> {
     _post_main_transition_hook: HookHandler<mDT> | undefined;
     _post_forced_transition_hook: HookHandler<mDT> | undefined;
     _post_any_transition_hook: HookHandler<mDT> | undefined;
-    _history: circular_buffer<[StateType, mDT]>;
+    _property_keys: Set<string>;
+    _default_properties: Map<string, any>;
+    _state_properties: Map<string, any>;
+    _history: JssmHistory<mDT>;
     _history_length: number;
-    constructor({ start_states, complete, transitions, machine_author, machine_comment, machine_contributor, machine_definition, machine_language, machine_license, machine_name, machine_version, state_declaration, fsl_version, dot_preamble, arrange_declaration, arrange_start_declaration, arrange_end_declaration, theme, flow, graph_layout, instance_name, history, data }: JssmGenericConfig<mDT>);
+    constructor({ start_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, arrange_declaration, arrange_start_declaration, arrange_end_declaration, theme, flow, graph_layout, instance_name, history, data }: JssmGenericConfig<mDT>);
     /********
      *
      *  Internal method for fabricating states.  Not meant for external use.
@@ -295,6 +297,122 @@ declare class Machine<mDT> {
      *
      */
     data(): mDT;
+    /*********
+     *
+     *  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: string): any;
+    /*********
+     *
+     *  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: string): any;
+    /*********
+     *
+     *  Get the current value of every prop, as an object.  If no current definition
+     *  exists for a prop - that is, if the prop was defined without a default and
+     *  the current state also doesn't define the prop - then that prop will be listed
+     *  in the returned object with a value of `undefined`.
+     *
+     *  ```typescript
+     *  const traffic_light = sm`
+     *
+     *    property can_go     default true;
+     *    property hesitate   default true;
+     *    property stop_first default false;
+     *
+     *    Off -> Red => Green => Yellow => Red;
+     *    [Red Yellow Green] ~> [Off FlashingRed];
+     *    FlashingRed -> Red;
+     *
+     *    state Red:         { property stop_first true;  property can_go false; };
+     *    state Off:         { property stop_first true;  };
+     *    state FlashingRed: { property stop_first true;  };
+     *    state Green:       { property hesitate   false; };
+     *
+     *  `;
+     *
+     *  traffic_light.state();  // Off
+     *  traffic_light.props();  // { can_go: true,  hesitate: true,  stop_first: true;  }
+     *
+     *  traffic_light.go('Red');
+     *  traffic_light.props();  // { can_go: false, hesitate: true,  stop_first: true;  }
+     *
+     *  traffic_light.go('Green');
+     *  traffic_light.props();  // { can_go: true,  hesitate: false, stop_first: false; }
+     *  ```
+     *
+     */
+    props(): object;
+    /*********
+     *
+     *  Get the current value of every prop, as an object.  Compare
+     *  {@link prop_map}, which returns a `Map`.
+     *
+     *  ```typescript
+     *
+     *  ```
+     *
+     */
+    /*********
+     *
+     *  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
+     *
+     *  ```
+     *
+     */
+    /*********
+     *
+     *  Check whether a given string is a known property's name.
+     *
+     *  ```typescript
+     *  const example = sm`property foo default 1; a->b;`;
+     *
+     *  example.known_prop('foo');  // true
+     *  example.known_prop('bar');  // false
+     *  ```
+     *
+     *  @param prop_name The relevant property name to look up
+     *
+     */
+    known_prop(prop_name: string): boolean;
+    /*********
+     *
+     *  List all known property names.  If you'd also like values, use
+     *  {@link props} instead.  The order of the properties is not defined, and
+     *  the properties generally will not be sorted.
+     *
+     *  ```typescript
+     *  ```
+     *
+     */
+    known_props(): string[];
     /********
      *
      *  Check whether a given state is final (either has no exits or is marked
@@ -330,10 +448,19 @@ declare class Machine<mDT> {
      *  console.log( final_test.is_final() );   // true
      *  ```
      *
+     */
+    is_final(): boolean;
+    /********
+     *
+     *  Serialize the current machine, including all defining state but not the
+     *  machine string, to a structure.  This means you will need the machine
+     *  string to recreate (to not waste repeated space;) if you want the machine
+     *  string embedded, call {@link serialize_with_string} instead.
+     *
      *  @typeparam mDT The type of the machine data member; usually omitted
      *
      */
-    is_final(): boolean;
+    serialize(comment?: string | undefined): JssmSerialization<mDT>;
     graph_layout(): string;
     dot_preamble(): string;
     machine_author(): Array<string>;
@@ -688,15 +815,27 @@ declare class Machine<mDT> {
      *  Instruct the machine to complete an action.  Synonym for {@link action}.
      *
      *  ```typescript
-     *  const light = sm`red 'next' -> green 'next' -> yellow 'next' -> red; [red yellow green] 'shutdown' ~> off 'start' -> red;`;
+     *  const light = sm`
+     *    off 'start' -> red;
+     *    red 'next' -> green 'next' -> yellow 'next' -> red;
+     *    [red yellow green] 'shutdown' ~> off;
+     *  `;
      *
-     *  light.state();           // 'red'
-     *  light.do('next');        // true
-     *  light.state();           // 'green'
+     *  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
-     *
+  b   *
      *  @param actionName The action to engage
      *
      *  @param newData The data change to insert during the action
@@ -708,11 +847,21 @@ declare class Machine<mDT> {
      *  Instruct the machine to complete a transition.  Synonym for {@link go}.
      *
      *  ```typescript
-     *  const light = sm`red -> green -> yellow -> red; [red yellow green] 'shutdown' ~> off 'start' -> red;`;
+     *  const light = sm`
+     *    off 'start' -> red;
+     *    red 'next' -> green 'next' -> yellow 'next' -> red;
+     *    [red yellow green] 'shutdown' ~> off;
+     *  `;
      *
-     *  light.state();               // 'red'
-     *  light.transition('green');   // true
-     *  light.state();               // 'green'
+     *  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
@@ -824,4 +973,5 @@ declare function from<mDT>(MachineAsString: string, ExtraConstructorFields?: Par
 declare function is_hook_complex_result<mDT>(hr: unknown): hr is HookComplexResult<mDT>;
 declare function is_hook_rejection<mDT>(hr: HookResult<mDT>): boolean;
 declare function abstract_hook_step<mDT>(maybe_hook: HookHandler<mDT> | undefined, hook_args: HookContext<mDT>): HookComplexResult<mDT>;
-export { version, transfer_state_properties, Machine, make, wrap_parse as parse, compile, sm, from, arrow_direction, arrow_left_kind, arrow_right_kind, seq, weighted_rand_select, histograph, weighted_sample_select, weighted_histo_key, shapes, gviz_shapes, named_colors, is_hook_rejection, is_hook_complex_result, abstract_hook_step };
+declare function deserialize<mDT>(machine_string: string, ser: JssmSerialization<mDT>): Machine<mDT>;
+export { version, transfer_state_properties, Machine, deserialize, make, wrap_parse as parse, compile, sm, from, arrow_direction, arrow_left_kind, arrow_right_kind, seq, unique, find_repeated, weighted_rand_select, histograph, weighted_sample_select, weighted_histo_key, shapes, gviz_shapes, named_colors, is_hook_rejection, is_hook_complex_result, abstract_hook_step };

package/dist/es6/jssm.js

@@ -1,7 +1,7 @@
 // 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 { seq, weighted_rand_select, weighted_sample_select, histograph, weighted_histo_key, array_box_if_string, hook_name, named_hook_name } from './jssm_util';
+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 { shapes, gviz_shapes, named_colors } from './jssm_constants';
 import { parse } from './jssm-dot';
 import { version } from './version'; // replaced from package.js in build
@@ -351,6 +351,16 @@ function compile_rule_handler(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') {
+        if (rule.hasOwnProperty('default_value')) {
+            return { agg_as: 'property_definition', val: { name: rule.name, default_value: rule.default_value } };
+        }
+        else {
+            return { agg_as: 'property_definition', val: { name: rule.name } };
+        }
+    }
+    // state properties are in here
     if (rule.key === 'state_declaration') {
         if (!rule.name) {
             throw new JssmError(undefined, 'State declarations must have a name');
@@ -361,6 +371,7 @@ function compile_rule_handler(rule) {
         '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',
@@ -440,6 +451,8 @@ function compile(tree) {
         machine_license: [],
         machine_name: [],
         machine_reference: [],
+        property_definition: [],
+        state_property: {},
         theme: [],
         flow: [],
         dot_preamble: [],
@@ -452,10 +465,15 @@ function compile(tree) {
         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],
-        transitions: assembled_transitions
+        transitions: assembled_transitions,
+        state_property: []
     };
     const oneOnlyKeys = [
         'graph_layout', 'machine_name', 'machine_version', 'machine_comment',
@@ -473,11 +491,28 @@ function compile(tree) {
         }
     });
     ['arrange_declaration', 'arrange_start_declaration', 'arrange_end_declaration',
-        'machine_author', 'machine_contributor', 'machine_reference', 'state_declaration'].map((multiKey) => {
+        'machine_author', 'machine_contributor', 'machine_reference',
+        'state_declaration', 'property_definition'].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);
+                console.log(`Bind ${sd.state}:${decl.name} as ${label}`);
+                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;
 }
 /*********
@@ -527,6 +562,9 @@ function transfer_state_properties(state_decl) {
             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)}'`);
         }
     });
@@ -535,7 +573,7 @@ function transfer_state_properties(state_decl) {
 // TODO add a lotta docblock here
 class Machine {
     // whargarbl this badly needs to be broken up, monolith master
-    constructor({ start_states, complete = [], transitions, machine_author, machine_comment, machine_contributor, machine_definition, machine_language, machine_license, machine_name, machine_version, state_declaration, fsl_version, dot_preamble = undefined, arrange_declaration = [], arrange_start_declaration = [], arrange_end_declaration = [], theme = 'default', flow = 'down', graph_layout = 'dot', instance_name, history, data }) {
+    constructor({ start_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 }) {
         this._instance_name = instance_name;
         this._state = start_states[0];
         this._states = new Map();
@@ -600,6 +638,9 @@ class Machine {
         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._history_length = history || 0;
         this._history = new circular_buffer(this._history_length);
         if (state_declaration) {
@@ -697,6 +738,19 @@ class Machine {
                 */
             }
         });
+        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 (Array.isArray(state_property)) {
+            state_property.forEach(sp => {
+                this._state_properties.set(sp.name, sp.default_value);
+            });
+        }
     }
     /********
      *
@@ -763,6 +817,165 @@ class Machine {
         return true; // todo whargarbl
       }
     */
+    // 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 final (either has no exits or is marked
@@ -800,13 +1013,32 @@ class Machine {
      *  console.log( final_test.is_final() );   // true
      *  ```
      *
-     *  @typeparam mDT The type of the machine data member; usually omitted
-     *
      */
     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;
     }
@@ -862,11 +1094,6 @@ class Machine {
             states: this._states
         };
     }
-    /*
-      load_machine_state(): boolean {
-        return false; // todo whargarbl
-      }
-    */
     /*********
      *
      *  List all the states known by the machine.  Please note that the order of
@@ -1749,15 +1976,27 @@ class Machine {
      *  Instruct the machine to complete an action.  Synonym for {@link action}.
      *
      *  ```typescript
-     *  const light = sm`red 'next' -> green 'next' -> yellow 'next' -> red; [red yellow green] 'shutdown' ~> off 'start' -> red;`;
+     *  const light = sm`
+     *    off 'start' -> red;
+     *    red 'next' -> green 'next' -> yellow 'next' -> red;
+     *    [red yellow green] 'shutdown' ~> off;
+     *  `;
      *
-     *  light.state();           // 'red'
-     *  light.do('next');        // true
-     *  light.state();           // 'green'
+     *  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
-     *
+  b   *
      *  @param actionName The action to engage
      *
      *  @param newData The data change to insert during the action
@@ -1771,11 +2010,21 @@ class Machine {
      *  Instruct the machine to complete a transition.  Synonym for {@link go}.
      *
      *  ```typescript
-     *  const light = sm`red -> green -> yellow -> red; [red yellow green] 'shutdown' ~> off 'start' -> red;`;
+     *  const light = sm`
+     *    off 'start' -> red;
+     *    red 'next' -> green 'next' -> yellow 'next' -> red;
+     *    [red yellow green] 'shutdown' ~> off;
+     *  `;
      *
-     *  light.state();               // 'red'
-     *  light.transition('green');   // true
-     *  light.state();               // 'green'
+     *  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
@@ -1988,6 +2237,12 @@ function abstract_hook_step(maybe_hook, hook_args) {
         return { pass: true };
     }
 }
-export { version, transfer_state_properties, Machine, make, wrap_parse as parse, compile, sm, from, arrow_direction, arrow_left_kind, arrow_right_kind, 
+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, weighted_rand_select, histograph, weighted_sample_select, weighted_histo_key, shapes, gviz_shapes, named_colors, is_hook_rejection, is_hook_complex_result, abstract_hook_step };
+seq, unique, find_repeated, weighted_rand_select, histograph, weighted_sample_select, weighted_histo_key, shapes, gviz_shapes, named_colors, is_hook_rejection, is_hook_complex_result, abstract_hook_step };