jssm 5.61.3 → 5.63.0

package/README.md

@@ -42,18 +42,39 @@ log( TrafficLight.state() );  // 'Green'
 What if the notation supported action names easily?
 
 ```javascript
-const TrafficLightWithActions = sm`Red 'next' -> Green 'next' -> Yellow 'next' -> Red;`;
+const TLWA = sm`Red 'next' -> Green 'next' -> Yellow 'next' -> Red;`;  // TLWA = Traffic Light With Actions
 
-log( TrafficLightWithActions.state() );  // 'Red'
+log( TLWA.state() );  // 'Red'
 
-TrafficLightWithActions.action('next');  // true
-log( TrafficLightWithActions.state() );  // 'Green'
+TLWA.action('next');  // true
+log( TLWA.state() );  // 'Green'
 
-TrafficLightWithActions.action('next');  // true
-log( TrafficLightWithActions.state() );  // 'Yellow'
+TLWA.action('next');  // true
+log( TLWA.state() );  // 'Yellow'
 
-TrafficLightWithActions.action('next');  // true
-log( TrafficLightWithActions.state() );  // 'Red'
+TLWA.action('next');  // true
+log( TLWA.state() );  // 'Red'
+```
+
+<br/>
+
+What if integration with the outside was straightforward?
+
+```javascript
+const MTL = sm`Red 'next' -> Green 'next' -> Yellow 'next' -> Red;`  // MTL = More Traffic Lights
+              .hook('Red', 'Green', () => log('GO GO GO') )          // node will jump the gun when you hit return, though
+              .hook_entry('Red', () => log('STOP') );                // so put it on one line in node
+
+log( MTL.state() );  // 'Red'
+
+TLWA.action('next');  // true, console logs 'GO GO GO'
+log( TLWA.state() );  // 'Green'
+
+TLWA.action('next');  // true
+log( TLWA.state() );  // 'Yellow'
+
+TLWA.action('next');  // true, console logs 'STOP'
+log( TLWA.state() );  // 'Red'
 ```
 
 <br/>
@@ -61,11 +82,11 @@ log( TrafficLightWithActions.state() );  // 'Red'
 What if the machine followed JS standards, and distinguished refusals as `false` from mistakes as `throw`n?
 
 ```javascript
-const AnotherTrafficLight = sm`Red -> Green -> Yellow -> Red;`;
+const ATL = sm`Red -> Green -> Yellow -> Red;`;  // ATL = Another Traffic Light
 
-log( AnotherTrafficLight.state() );         // 'Red' - uses 1st state unless told otherwise
-AnotherTrafficLight.transition('Yellow');   // false (Yellow isn't allowed from Red)
-AnotherTrafficLight.transition('Blue');     // throws (Blue isn't a state at all)
+log( ATL.state() );         // 'Red' - uses 1st state unless told otherwise
+ATL.transition('Yellow');   // false (Yellow isn't allowed from Red)
+ATL.transition('Blue');     // throws (Blue isn't a state at all)
 ```
 
 <br/>

package/dist/es6/jssm.d.ts

@@ -30,6 +30,7 @@ declare class Machine<mDT> {
     _fsl_version?: string;
     _raw_state_declaration?: Array<Object>;
     _state_declarations: Map<StateType, JssmStateDeclaration>;
+    _instance_name: string;
     _graph_layout: JssmLayout;
     _dot_preamble: string;
     _arrange_declaration: Array<Array<StateType>>;
@@ -54,7 +55,7 @@ declare class Machine<mDT> {
     _main_transition_hook: HookHandler | undefined;
     _forced_transition_hook: HookHandler | undefined;
     _any_transition_hook: HookHandler | undefined;
-    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 }: 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, fsl_version, dot_preamble, arrange_declaration, arrange_start_declaration, arrange_end_declaration, theme, flow, graph_layout, instance_name }: JssmGenericConfig<mDT>);
     _new_state(state_config: JssmGenericState): StateType;
     state(): StateType;
     state_is_final(whichState: StateType): boolean;
@@ -124,7 +125,9 @@ declare class Machine<mDT> {
     valid_action(action: StateType, _newData?: mDT): boolean;
     valid_transition(newState: StateType, _newData?: mDT): boolean;
     valid_force_transition(newState: StateType, _newData?: mDT): boolean;
+    instance_name(): string | undefined;
     sm(template_strings: TemplateStringsArray, ...remainder: any[]): Machine<mDT>;
 }
 declare function sm<mDT>(template_strings: TemplateStringsArray, ...remainder: any[]): Machine<mDT>;
-export { version, transfer_state_properties, Machine, make, wrap_parse as parse, compile, sm, arrow_direction, arrow_left_kind, arrow_right_kind, seq, weighted_rand_select, histograph, weighted_sample_select, weighted_histo_key };
+declare function from<mDT>(MachineAsString: string, ExtraConstructorFields?: Partial<JssmGenericConfig<mDT>> | undefined): Machine<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 };

package/dist/es6/jssm.js

@@ -1,8 +1,9 @@
 // whargarbl lots of these return arrays could/should be sets
 import { reduce as reduce_to_639 } from 'reduce-to-639-1';
 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 { parse } from './jssm-dot'; // TODO FIXME WHARGARBL this could be post-typed
+import { parse } from './jssm-dot';
 import { version } from './version'; // replaced from package.js in build
+import { JssmError } from './jssm_error';
 /* eslint-disable complexity */
 function arrow_direction(arrow) {
     switch (String(arrow)) {
@@ -52,7 +53,7 @@ function arrow_direction(arrow) {
         case '<~⇒':
             return 'both';
         default:
-            throw new Error(`arrow_direction: unknown arrow type ${arrow}`);
+            throw new JssmError(undefined, `arrow_direction: unknown arrow type ${arrow}`);
     }
 }
 /* eslint-enable complexity */
@@ -94,7 +95,7 @@ function arrow_left_kind(arrow) {
         case '↚⇒':
             return 'forced';
         default:
-            throw new Error(`arrow_direction: unknown arrow type ${arrow}`);
+            throw new JssmError(undefined, `arrow_direction: unknown arrow type ${arrow}`);
     }
 }
 /* eslint-enable complexity */
@@ -136,7 +137,7 @@ function arrow_right_kind(arrow) {
         case '⇐↛':
             return 'forced';
         default:
-            throw new Error(`arrow_direction: unknown arrow type ${arrow}`);
+            throw new JssmError(undefined, `arrow_direction: unknown arrow type ${arrow}`);
     }
 }
 /* eslint-enable complexity */
@@ -148,13 +149,13 @@ function makeTransition(this_se, from, to, isRight, _wasList, _wasIndex) {
         forced_only: kind === 'forced',
         main_path: kind === 'main'
     };
-    //  if ((wasList  !== undefined) && (wasIndex === undefined)) { throw new TypeError("Must have an index if transition was in a list"); }
-    //  if ((wasIndex !== undefined) && (wasList  === undefined)) { throw new TypeError("Must be in a list if transition has an index");   }
+    //  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 "Must have a waslist if a to is type 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];
         }
@@ -208,7 +209,7 @@ function compile_rule_handler(rule) {
     }
     if (rule.key === 'state_declaration') {
         if (!rule.name) {
-            throw new Error('State declarations must have a name');
+            throw new JssmError(undefined, 'State declarations must have a name');
         }
         return { agg_as: 'state_declaration', val: { state: rule.name, declarations: rule.value } };
     }
@@ -225,7 +226,7 @@ function compile_rule_handler(rule) {
     if (tautologies.includes(rule.key)) {
         return { agg_as: rule.key, val: rule.value };
     }
-    throw new Error(`compile_rule_handler: Unknown rule: ${JSON.stringify(rule)}`);
+    throw new JssmError(undefined, `compile_rule_handler: Unknown rule: ${JSON.stringify(rule)}`);
 }
 function compile(tree) {
     const results = {
@@ -268,7 +269,7 @@ function compile(tree) {
     ];
     oneOnlyKeys.map((oneOnlyKey) => {
         if (results[oneOnlyKey].length > 1) {
-            throw new Error(`May only have one ${oneOnlyKey} statement maximum: ${JSON.stringify(results[oneOnlyKey])}`);
+            throw new JssmError(undefined, `May only have one ${oneOnlyKey} statement maximum: ${JSON.stringify(results[oneOnlyKey])}`);
         }
         else {
             if (results[oneOnlyKey].length) {
@@ -311,14 +312,15 @@ function transfer_state_properties(state_decl) {
             case 'border-color':
                 state_decl.borderColor = d.value;
                 break;
-            default: throw new Error(`Unknown state property: '${JSON.stringify(d)}'`);
+            default: throw new JssmError(undefined, `Unknown state property: '${JSON.stringify(d)}'`);
         }
     });
     return state_decl;
 }
 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' }) {
+    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 }) {
+        this._instance_name = instance_name;
         this._state = start_states[0];
         this._states = new Map();
         this._state_declarations = new Map();
@@ -367,17 +369,17 @@ class Machine {
         if (state_declaration) {
             state_declaration.map((state_decl) => {
                 if (this._state_declarations.has(state_decl.state)) { // no repeats
-                    throw new Error(`Added the same state declaration twice: ${JSON.stringify(state_decl.state)}`);
+                    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));
             });
         }
         transitions.map((tr) => {
             if (tr.from === undefined) {
-                throw new Error(`transition must define 'from': ${JSON.stringify(tr)}`);
+                throw new JssmError(this, `transition must define 'from': ${JSON.stringify(tr)}`);
             }
             if (tr.to === undefined) {
-                throw new Error(`transition must define 'to': ${JSON.stringify(tr)}`);
+                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)
@@ -392,7 +394,7 @@ class Machine {
             }
             // guard against existing connections being re-added
             if (cursor_from.to.includes(tr.to)) {
-                throw new Error(`already has ${JSON.stringify(tr.from)} to ${JSON.stringify(tr.to)}`);
+                throw new JssmError(this, `already has ${JSON.stringify(tr.from)} to ${JSON.stringify(tr.to)}`);
             }
             else {
                 cursor_from.to.push(tr.to);
@@ -404,7 +406,7 @@ class Machine {
             // guard against repeating a transition name
             if (tr.name) {
                 if (this._named_transitions.has(tr.name)) {
-                    throw new Error(`named transition "${JSON.stringify(tr.name)}" already created`);
+                    throw new JssmError(this, `named transition "${JSON.stringify(tr.name)}" already created`);
                 }
                 else {
                     this._named_transitions.set(tr.name, thisEdgeId);
@@ -426,7 +428,7 @@ class Machine {
                     this._actions.set(tr.action, actionMap);
                 }
                 if (actionMap.has(tr.from)) {
-                    throw new Error(`action ${JSON.stringify(tr.action)} already attached to origin ${JSON.stringify(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);
@@ -449,12 +451,12 @@ class Machine {
                         const roActionMap = this._reverse_action_targets.get(tr.to);  // wasteful - already did has - refactor
                         if (roActionMap) {
                           if (roActionMap.has(tr.action)) {
-                            throw new Error(`ro-action ${tr.to} already attached to action ${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 Error('should be impossible - flow doesn\'t know .set precedes .get yet again.  severe error?');
+                          throw new JssmError(this, `should be impossible - flow doesn\'t know .set precedes .get yet again.  severe error?');
                         }
                 */
             }
@@ -462,7 +464,7 @@ class Machine {
     }
     _new_state(state_config) {
         if (this._states.has(state_config.name)) {
-            throw new Error(`state ${JSON.stringify(state_config.name)} already exists`);
+            throw new JssmError(this, `state ${JSON.stringify(state_config.name)} already exists`);
         }
         this._states.set(state_config.name, state_config);
         return state_config.name;
@@ -534,7 +536,7 @@ class Machine {
             edges: this._edges,
             named_transitions: this._named_transitions,
             reverse_actions: this._reverse_actions,
-            //    reverse_action_targets : this._reverse_action_targets,
+            // reverse_action_targets : this._reverse_action_targets,
             state: this._state,
             states: this._states
         };
@@ -553,7 +555,7 @@ class Machine {
             return state;
         }
         else {
-            throw new Error(`no such state ${JSON.stringify(state)}`);
+            throw new JssmError(this, 'No such state', { requested_state: whichState });
         }
     }
     has_state(whichState) {
@@ -603,7 +605,7 @@ class Machine {
     probable_exits_for(whichState) {
         const wstate = this._states.get(whichState);
         if (!(wstate)) {
-            throw new Error(`No such state ${JSON.stringify(whichState)} in probable_exits_for`);
+            throw new JssmError(this, `No such state ${JSON.stringify(whichState)} in probable_exits_for`);
         }
         const wstate_to = wstate.to, wtf = wstate_to
             .map((ws) => this.lookup_transition_for(this.state(), ws))
@@ -632,7 +634,7 @@ class Machine {
             return Array.from(wstate.keys());
         }
         else {
-            throw new Error(`No such state ${JSON.stringify(whichState)}`);
+            throw new JssmError(this, `No such state ${JSON.stringify(whichState)}`);
         }
     }
     list_states_having_action(whichState) {
@@ -641,7 +643,7 @@ class Machine {
             return Array.from(wstate.keys());
         }
         else {
-            throw new Error(`No such state ${JSON.stringify(whichState)}`);
+            throw new JssmError(this, `No such state ${JSON.stringify(whichState)}`);
         }
     }
     // comeback
@@ -656,7 +658,7 @@ class Machine {
     list_exit_actions(whichState = this.state()) {
         const ra_base = this._reverse_actions.get(whichState);
         if (!(ra_base)) {
-            throw new Error(`No such state ${JSON.stringify(whichState)}`);
+            throw new JssmError(this, `No such state ${JSON.stringify(whichState)}`);
         }
         return Array.from(ra_base.values())
             .map((edgeId) => this._edges[edgeId])
@@ -666,7 +668,7 @@ class Machine {
     probable_action_exits(whichState = this.state()) {
         const ra_base = this._reverse_actions.get(whichState);
         if (!(ra_base)) {
-            throw new Error(`No such state ${JSON.stringify(whichState)}`);
+            throw new JssmError(this, `No such state ${JSON.stringify(whichState)}`);
         }
         return Array.from(ra_base.values())
             .map((edgeId) => this._edges[edgeId])
@@ -679,7 +681,7 @@ class Machine {
     // TODO FIXME test that is_unenterable on non-state throws
     is_unenterable(whichState) {
         if (!(this.has_state(whichState))) {
-            throw new Error(`No such state ${whichState}`);
+            throw new JssmError(this, `No such state ${whichState}`);
         }
         return this.list_entrances(whichState).length === 0;
     }
@@ -692,7 +694,7 @@ class Machine {
     // TODO FIXME test that state_is_terminal on non-state throws
     state_is_terminal(whichState) {
         if (!(this.has_state(whichState))) {
-            throw new Error(`No such state ${whichState}`);
+            throw new JssmError(this, `No such state ${whichState}`);
         }
         return this.list_exits(whichState).length === 0;
     }
@@ -708,7 +710,7 @@ class Machine {
             return wstate.complete;
         }
         else {
-            throw new Error(`No such state ${JSON.stringify(whichState)}`);
+            throw new JssmError(this, `No such state ${JSON.stringify(whichState)}`);
         }
     }
     has_completes() {
@@ -767,8 +769,7 @@ class Machine {
                 this._has_exit_hooks = true;
                 break;
             default:
-                console.log(`Unknown hook type ${HookDesc.kind}, should be impossible`);
-                throw new RangeError(`Unknown hook type ${HookDesc.kind}, should be impossible`);
+                throw new JssmError(this, `Unknown hook type ${HookDesc.kind}, should be impossible`);
         }
     }
     hook(from, to, handler) {
@@ -822,7 +823,7 @@ class Machine {
         return this;
     }
     // remove_hook(HookDesc: HookDescription) {
-    //   throw 'TODO: Should remove hook here';
+    //   throw new JssmError(this, 'TODO: Should remove hook here');
     // }
     edges_between(from, to) {
         return this._edges.filter(edge => ((edge.from === from) && (edge.to === to)));
@@ -982,7 +983,7 @@ class Machine {
     current_action_edge_for(action) {
         const idx = this.current_action_for(action);
         if ((idx === undefined) || (idx === null)) {
-            throw new Error(`No such action ${JSON.stringify(action)}`);
+            throw new JssmError(this, `No such action ${JSON.stringify(action)}`);
         }
         return this._edges[idx];
     }
@@ -1008,6 +1009,9 @@ class Machine {
         // 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 */) {
@@ -1027,6 +1031,13 @@ function sm(template_strings, ...remainder /* , arguments */) {
     /* eslint-enable  prefer-rest-params */
     )));
 }
-export { version, transfer_state_properties, Machine, make, wrap_parse as parse, compile, sm, arrow_direction, arrow_left_kind, arrow_right_kind, 
+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);
+}
+export { version, transfer_state_properties, Machine, 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 };

package/dist/es6/jssm_error.d.ts

@@ -0,0 +1,8 @@
+import { JssmErrorExtendedInfo } from './jssm_types';
+declare class JssmError extends Error {
+    message: string;
+    base_message: string;
+    requested_state: string | undefined;
+    constructor(machine: any, message: string, JEEI?: JssmErrorExtendedInfo);
+}
+export { JssmError };

package/dist/es6/jssm_error.js

@@ -0,0 +1,28 @@
+class JssmError extends Error {
+    constructor(machine, message, JEEI) {
+        const { requested_state } = (JEEI === undefined)
+            ? { requested_state: undefined }
+            : JEEI;
+        const follow_ups = [];
+        if (machine) {
+            if (machine.state() !== undefined) {
+                follow_ups.push(`at "${machine.state()}"`);
+            }
+        }
+        if (requested_state !== undefined) {
+            follow_ups.push(`requested "${requested_state}"`);
+        }
+        const complex_msg = `${((machine === null || machine === void 0 ? void 0 : machine.instance_name()) !== undefined)
+            ? `[[${machine.instance_name()}]]: `
+            : ''}${message}${follow_ups.length
+            ? ` (${follow_ups.join(', ')})`
+            : ''}`;
+        super(complex_msg);
+        this.name = 'JssmError';
+        this.message = complex_msg;
+        this.base_message = message;
+        this.requested_state = requested_state;
+    }
+}
+;
+export { JssmError };

package/dist/es6/jssm_types.d.ts

@@ -125,6 +125,7 @@ declare type JssmGenericConfig<DataType> = {
     machine_version?: string;
     fsl_version?: string;
     auto_api?: boolean | string;
+    instance_name?: string | undefined;
 };
 declare type JssmCompileRule = {
     agg_as: string;
@@ -198,4 +199,7 @@ declare type ExitHook = {
     handler: HookHandler;
 };
 declare type HookDescription = BasicHookDescription | HookDescriptionWithAction | GlobalActionHook | AnyActionHook | StandardTransitionHook | MainTransitionHook | ForcedTransitionHook | AnyTransitionHook | EntryHook | ExitHook;
-export { JssmColor, JssmTransition, JssmTransitions, JssmTransitionList, JssmTransitionRule, JssmArrow, JssmArrowKind, JssmArrowDirection, JssmGenericConfig, JssmGenericState, JssmGenericMachine, JssmParseTree, JssmCompileSe, JssmCompileSeStart, JssmCompileRule, JssmPermitted, JssmPermittedOpt, JssmResult, JssmStateDeclaration, JssmStateDeclarationRule, JssmLayout, JssmParseFunctionType, JssmMachineInternalState, FslDirection, FslTheme, HookDescription, HookHandler };
+declare type JssmErrorExtendedInfo = {
+    requested_state?: StateType | undefined;
+};
+export { JssmColor, JssmTransition, JssmTransitions, JssmTransitionList, JssmTransitionRule, JssmArrow, JssmArrowKind, JssmArrowDirection, JssmGenericConfig, JssmGenericState, JssmGenericMachine, JssmParseTree, JssmCompileSe, JssmCompileSeStart, JssmCompileRule, JssmPermitted, JssmPermittedOpt, JssmResult, JssmStateDeclaration, JssmStateDeclarationRule, JssmLayout, JssmParseFunctionType, JssmMachineInternalState, JssmErrorExtendedInfo, FslDirection, FslTheme, HookDescription, HookHandler };

package/dist/es6/version.js

@@ -1,2 +1,2 @@
-const version = "5.61.3";
+const version = "5.63.0";
 export { version };