jssm 5.43.2 → 5.45.2

package/jssm.d.ts

@@ -1,6 +1,6 @@
 declare type StateType = string;
 import { JssmGenericState, JssmGenericConfig, JssmTransition, JssmTransitionList, // JssmTransitionRule,
-JssmMachineInternalState, JssmParseTree, JssmStateDeclaration, JssmArrow, JssmArrowDirection, JssmArrowKind, JssmLayout, FslDirection, FslTheme } from './jssm_types';
+JssmMachineInternalState, JssmParseTree, JssmStateDeclaration, JssmArrow, JssmArrowDirection, JssmArrowKind, JssmLayout, FslDirection, FslTheme, HookDescription } from './jssm_types';
 import { seq, weighted_rand_select, weighted_sample_select, histograph, weighted_histo_key } from './jssm_util';
 import { version } from './version';
 declare function arrow_direction(arrow: JssmArrow): JssmArrowDirection;
@@ -37,6 +37,9 @@ declare class Machine<mDT> {
     _arrange_end_declaration: Array<Array<StateType>>;
     _theme: FslTheme;
     _flow: FslDirection;
+    _has_hooks: boolean;
+    _hooks: Map<string, Function>;
+    _named_hooks: Map<string, Function>;
     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>);
     _new_state(state_config: JssmGenericState): StateType;
     state(): StateType;
@@ -86,6 +89,7 @@ declare class Machine<mDT> {
     is_complete(): boolean;
     state_is_complete(whichState: StateType): boolean;
     has_completes(): boolean;
+    set_hook(HookDesc: HookDescription): void;
     action(name: StateType, newData?: mDT): boolean;
     transition(newState: StateType, newData?: mDT): boolean;
     force_transition(newState: StateType, newData?: mDT): boolean;

package/jssm_types.d.ts

@@ -148,4 +148,28 @@ declare type JssmCompileSeStart<DataType> = {
 };
 declare type JssmParseTree = Array<JssmCompileSeStart<StateType>>;
 declare type JssmParseFunctionType = (string: any) => JssmParseTree;
-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 };
+declare type BasicHookDescription = {
+    kind: 'hook';
+    from: string;
+    to: string;
+    handler: Function;
+};
+declare type HookDescriptionWithAction = {
+    kind: 'named';
+    from: string;
+    to: string;
+    action: string;
+    handler: Function;
+};
+declare type EntryHook = {
+    kind: 'entry';
+    to: string;
+    handler: Function;
+};
+declare type ExitHook = {
+    kind: 'exit';
+    from: string;
+    handler: Function;
+};
+declare type HookDescription = BasicHookDescription | HookDescriptionWithAction | 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 };

package/jssm_util.d.ts

@@ -5,4 +5,6 @@ declare const seq: Function;
 declare const histograph: Function;
 declare const weighted_sample_select: Function;
 declare const weighted_histo_key: Function;
-export { seq, arr_uniq_p, histograph, weighted_histo_key, weighted_rand_select, weighted_sample_select, array_box_if_string };
+declare const hook_name: (from: string, to: string) => string;
+declare const named_hook_name: (from: string, to: string, action: string) => string;
+export { seq, arr_uniq_p, histograph, weighted_histo_key, weighted_rand_select, weighted_sample_select, array_box_if_string, hook_name, named_hook_name };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jssm",
-  "version": "5.43.2",
+  "version": "5.45.2",
   "engines": {
     "node": ">=10.0.0"
   },
@@ -16,7 +16,7 @@
       }
     ]
   },
-  "description": "A Javascript finite state machine (FSM) with a terse DSL and a simple API. Well tested, and typed with Flowtype. MIT License.",
+  "description": "A Javascript finite state machine (FSM) with a terse DSL and a simple API. Well tested, and typed with TypeScript. MIT License.",
   "main": "dist/jssm.es5.cjs.js",
   "module": "dist/es6/jssm.js",
   "types": "./jssm.d.ts",
@@ -39,8 +39,9 @@
     "eslint": "eslint --color src/ts/jssm.ts src/ts/jssm_types.ts src/ts/tests/*.ts",
     "audit": "text_audit -r -t major MAJOR wasteful WASTEFUL any mixed fixme FIXME checkme CHECKME testme TESTME stochable STOCHABLE todo TODO comeback COMEBACK whargarbl WHARGARBL -g ./src/ts/**/*.{js,ts}",
     "vet": "npm run eslint && npm run audit",
-    "build": "npm run vet && npm run test && npm run site && npm run docs",
-    "ci_build": "npm run vet && npm run test",
+    "benny": "node ./src/buildjs/benchmark.js",
+    "build": "npm run vet && npm run test && npm run site && npm run docs && npm run benny",
+    "ci_build": "npm run vet && npm run test && npm run benny",
     "minify": "mv dist/es6/jssm-dot.js dist/es6/jssm-dot.nonmin.js && terser dist/es6/jssm-dot.nonmin.js > dist/es6/jssm-dot.js",
     "min_iife": "mv dist/jssm.es5.iife.js dist/jssm.es5.iife.nonmin.js && terser dist/jssm.es5.iife.nonmin.js > dist/jssm.es5.iife.js",
     "min_cjs": "mv dist/jssm.es5.cjs.js dist/jssm.es5.cjs.nonmin.js && terser dist/jssm.es5.cjs.nonmin.js > dist/jssm.es5.cjs.js",
@@ -69,7 +70,6 @@
     "tested",
     "typed",
     "typed-js",
-    "flowtype",
     "mealy",
     "moore",
     "mealy machine",
@@ -80,6 +80,7 @@
     "viz.js",
     "flowchart",
     "visualization",
+    "TypeScript",
     "StoneCypher"
   ],
   "author": "John Haugeland <stonecypher@gmail.com>",
@@ -92,6 +93,7 @@
     "@types/jest": "^27.0.2",
     "@typescript-eslint/eslint-plugin": "^4.13.0",
     "@typescript-eslint/parser": "^4.13.0",
+    "benny": "^3.7.1",
     "changelog-maker": "^2.3.2",
     "coveralls": "^3.0.11",
     "eslint": "^7.32.0",
@@ -114,8 +116,7 @@
     "text_audit": "^0.9.3",
     "ts-jest": "^27.0.7",
     "typedoc": "^0.22.15",
-    "typescript": "^4.1.3",
-    "viz.js": "^1.7.1"
+    "typescript": "^4.1.3"
   },
   "dependencies": {
     "reduce-to-639-1": "^1.0.4"

package/src/ts/jssm.ts

@@ -19,7 +19,8 @@ import {
   JssmCompileSe, JssmCompileSeStart, JssmCompileRule,
   JssmArrow, JssmArrowDirection, JssmArrowKind,
   JssmLayout,
-  FslDirection, FslTheme
+  FslDirection, FslTheme,
+  HookDescription
 
 } from './jssm_types';
 
@@ -29,7 +30,7 @@ import {
 
 import {
   seq, weighted_rand_select, weighted_sample_select, histograph,
-  weighted_histo_key, array_box_if_string
+  weighted_histo_key, array_box_if_string, hook_name, named_hook_name
 } from './jssm_util';
 
 
@@ -38,7 +39,7 @@ import {
 
 import { parse } from './jssm-dot';  // TODO FIXME WHARGARBL this could be post-typed
 
-import { version } from './version'; // replaced from package.js in build // TODO FIXME currently broken
+import { version } from './version'; // replaced from package.js in build
 
 
 
@@ -229,7 +230,7 @@ function compile_rule_transition_step<mDT>(
              to      : string,
              this_se : JssmCompileSe,
              next_se : JssmCompileSe
-         ) : Array< JssmTransition<mDT> > { // todo flow describe the parser representation of a transition step extension
+         ) : Array< JssmTransition<mDT> > { // todo typescript describe the parser representation of a transition step extension
 
   const edges : Array< JssmTransition<mDT> > = [];
 
@@ -260,13 +261,13 @@ function compile_rule_transition_step<mDT>(
 
 
 
-function compile_rule_handle_transition(rule: JssmCompileSeStart<StateType>): any { // TODO FIXME no any // todo flow describe the parser representation of a transition
+function compile_rule_handle_transition(rule: JssmCompileSeStart<StateType>): any { // TODO FIXME no any // todo typescript describe the parser representation of a transition
   return compile_rule_transition_step([], rule.from, rule.se.to, rule.se, rule.se.se);
 }
 
 
 
-function compile_rule_handler(rule: JssmCompileSeStart<StateType>): JssmCompileRule { // todo flow describe the output of the parser
+function compile_rule_handler(rule: JssmCompileSeStart<StateType>): JssmCompileRule {
 
   if (rule.key === 'transition') {
     return { agg_as: 'transition', val: compile_rule_handle_transition(rule) };
@@ -305,7 +306,7 @@ function compile_rule_handler(rule: JssmCompileSeStart<StateType>): JssmCompileR
 
 
 
-function compile<mDT>(tree: JssmParseTree): JssmGenericConfig<mDT> {  // todo flow describe the output of the parser
+function compile<mDT>(tree: JssmParseTree): JssmGenericConfig<mDT> {
 
   const results : {
     graph_layout              : Array< JssmLayout >,
@@ -475,11 +476,15 @@ class Machine<mDT> {
   _theme                     : FslTheme;
   _flow                      : FslDirection;
 
+  _has_hooks                 : boolean;
+  _hooks                     : Map<string, Function>;
+  _named_hooks               : Map<string, Function>;
+
 
   // whargarbl this badly needs to be broken up, monolith master
   constructor({
     start_states,
-    complete        = [],
+    complete                  = [],
     transitions,
     machine_author,
     machine_comment,
@@ -530,6 +535,10 @@ class Machine<mDT> {
     this._flow                      = flow;
     this._graph_layout              = graph_layout;
 
+    this._has_hooks                 = false;
+    this._hooks                     = new Map();
+    this._named_hooks               = new Map();
+
 
     if (state_declaration) {
       state_declaration.map( (state_decl: JssmStateDeclaration) => {
@@ -601,7 +610,7 @@ class Machine<mDT> {
 
 
         // forward mapping first by action name
-        let actionMap: Map<StateType, number> = this._actions.get(tr.action);  // TODO FIXME ?Map equiv
+        let actionMap: Map<StateType, number> = this._actions.get(tr.action);
         if (!(actionMap)) {
           actionMap = new Map();
           this._actions.set(tr.action, actionMap);
@@ -615,7 +624,7 @@ class Machine<mDT> {
 
 
         // reverse mapping first by state origin name
-        let rActionMap: Map<StateType, number> = this._reverse_actions.get(tr.from);  // TODO FIXME ?Map equiv
+        let rActionMap: Map<StateType, number> = this._reverse_actions.get(tr.from);
         if (!(rActionMap)) {
           rActionMap = new Map();
           this._reverse_actions.set(tr.from, rActionMap);
@@ -975,49 +984,165 @@ class Machine<mDT> {
 
 
 
+  // basic toolable hook call.  convenience wrappers will follow, like
+  // hook(from, to, handler) and exit_hook(from, handler) and etc
+  set_hook(HookDesc: HookDescription) {
+
+    switch (HookDesc.kind) {
+
+      case 'hook':
+        this._hooks.set(hook_name(HookDesc.from, HookDesc.to), HookDesc.handler);
+        this._has_hooks = true;
+        break;
+
+      case 'named':
+        this._named_hooks.set(named_hook_name(HookDesc.from, HookDesc.to, HookDesc.action), HookDesc.handler);
+        this._has_hooks = true;
+        break;
+
+      // case 'entry':
+      //   console.log('TODO: Should add entry hook here');
+      //   throw 'TODO: Should add entry hook here';
+
+      // case 'exit':
+      //   console.log('TODO: Should add exit hook here');
+      //   throw 'TODO: Should add exit hook here';
+
+      default:
+        console.log(`Unknown hook type ${(HookDesc as any).kind}, should be impossible`);
+        throw new RangeError(`Unknown hook type ${(HookDesc as any).kind}, should be impossible`);
+
+    }
+  }
+
+  // remove_hook(HookDesc: HookDescription) {
+  //   throw 'TODO: Should remove hook here';
+  // }
+
+
+
   action(name: StateType, newData?: mDT): boolean {
     // todo whargarbl implement hooks
     // todo whargarbl implement data stuff
     // todo major incomplete whargarbl comeback
     if (this.valid_action(name, newData)) {
-      const edge: JssmTransition<mDT> = this.current_action_edge_for(name);
-      this._state = edge.to;
-      return true;
+
+      const edge : JssmTransition<mDT> = this.current_action_edge_for(name);
+
+      if (this._has_hooks) {
+
+        let hook_permits : boolean | undefined = undefined;
+
+        const nhn : string = named_hook_name(this._state, edge.to, name),
+              maybe_hook   = this._named_hooks.get(nhn);
+
+        if (maybe_hook === undefined) { hook_permits = true; }
+        else                          { hook_permits = maybe_hook( { from: this._state, to: edge.to, action: name } ); }
+
+        if (hook_permits !== false) {
+          this._state = edge.to;
+          return true;
+        } else {
+          return false;
+        }
+
+      } else {
+        this._state = edge.to;
+        return true;
+      }
+
     } else {
       return false;
     }
   }
 
+
+
   transition(newState: StateType, newData?: mDT): boolean {
+
     // todo whargarbl implement hooks
     // todo whargarbl implement data stuff
     // todo major incomplete whargarbl comeback
     if (this.valid_transition(newState, newData)) {
-      this._state = newState;
-      return true;
+
+      if (this._has_hooks) {
+
+        let hook_permits : boolean | undefined = undefined;
+
+        const hn         : string               = hook_name(this._state, newState),
+              maybe_hook : Function | undefined = this._hooks.get(hn);
+
+        if (maybe_hook === undefined) { hook_permits = true; }
+        else                          { hook_permits = maybe_hook( { from: this._state, to: newState } ); }
+
+        if (hook_permits !== false) {
+          this._state = newState;
+          return true;
+        } else {
+          return false;
+        }
+
+      } else {
+
+        this._state = newState;
+        return true;
+
+      }
+
     } else {
       return false;
     }
+
   }
 
+
+
   // can leave machine in inconsistent state.  generally do not use
+
   force_transition(newState: StateType, newData?: mDT): boolean {
+
     // todo whargarbl implement hooks
     // todo whargarbl implement data stuff
     // todo major incomplete whargarbl comeback
     if (this.valid_force_transition(newState, newData)) {
-      this._state = newState;
-      return true;
+
+      if (this._has_hooks) {
+
+        let hook_permits : boolean | undefined = undefined;
+
+        const hn         : string               = hook_name(this._state, newState),
+              maybe_hook : Function | undefined = this._hooks.get(hn);
+
+        if (maybe_hook === undefined) { hook_permits = true; }
+        else                          { hook_permits = maybe_hook({ from: this._state, to: newState, forced: true }); }
+
+        if (hook_permits !== false) {
+          this._state = newState;
+          return true;
+        } else {
+          return false;
+        }
+
+      } else {
+
+        this._state = newState;
+        return true;
+
+      }
+
     } else {
       return false;
     }
+
   }
 
 
 
   current_action_for(action: StateType): number {
     const action_base: Map<StateType, number> = this._actions.get(action);
-    return action_base? action_base.get(this.state()): undefined;
+    return action_base
+      ? action_base.get(this.state())
+      : undefined;
   }
 
   current_action_edge_for(action: StateType): JssmTransition<mDT> {
@@ -1027,14 +1152,12 @@ class Machine<mDT> {
   }
 
   valid_action(action: StateType, _newData?: mDT): boolean {  // todo comeback unignore newData
-    // todo whargarbl implement hooks
     // todo whargarbl implement data stuff
     // todo major incomplete whargarbl comeback
     return this.current_action_for(action) !== undefined;
   }
 
   valid_transition(newState: StateType, _newData?: mDT): boolean {  // todo comeback unignore newData
-    // todo whargarbl implement hooks
     // todo whargarbl implement data stuff
     // todo major incomplete whargarbl comeback
     const transition_for: JssmTransition<mDT> = this.lookup_transition_for(this.state(), newState);
@@ -1047,7 +1170,6 @@ class Machine<mDT> {
   }
 
   valid_force_transition(newState: StateType, _newData?: mDT): boolean {  // todo comeback unignore newData
-    // todo whargarbl implement hooks
     // todo whargarbl implement data stuff
     // todo major incomplete whargarbl comeback
     return (this.lookup_transition_for(this.state(), newState) !== undefined);
@@ -1081,7 +1203,8 @@ function sm<mDT>(template_strings: TemplateStringsArray, ... remainder /* , argu
       // string notation, as designed, it's not really worth the hassle
 
       /* eslint-disable prefer-rest-params */
-      (acc, val, idx): string => `${acc}${remainder[idx-1]}${val}`  // arguments[0] is never loaded, so args doesn't need to be gated
+      (acc, val, idx): string =>
+        `${acc}${remainder[idx-1]}${val}`  // arguments[0] is never loaded, so args doesn't need to be gated
       /* eslint-enable  prefer-rest-params */
 
     )));

package/src/ts/jssm_types.ts

@@ -305,6 +305,43 @@ type JssmParseFunctionType =
 
 
 
+type BasicHookDescription = {
+  kind    : 'hook'
+  from    : string,
+  to      : string,
+  handler : Function
+};
+
+type HookDescriptionWithAction = {
+  kind    : 'named',
+  from    : string,
+  to      : string,
+  action  : string,
+  handler : Function
+};
+
+type EntryHook = {
+  kind    : 'entry',
+  to      : string,
+  handler : Function
+};
+
+type ExitHook = {
+  kind    : 'exit',
+  from    : string,
+  handler : Function
+};
+
+type HookDescription
+  = BasicHookDescription
+  | HookDescriptionWithAction
+  | EntryHook
+  | ExitHook;
+
+
+
+
+
 export {
 
   JssmColor,
@@ -341,6 +378,8 @@ export {
   JssmMachineInternalState,
 
   FslDirection,
-    FslTheme
+    FslTheme,
+
+  HookDescription
 
 };

package/src/ts/jssm_util.ts

@@ -90,11 +90,28 @@ const weighted_histo_key: Function = (n: number, opts: Array<any>, prob_prop: st
 
 
 
+const hook_name = (from: string, to: string): string =>
+
+  JSON.stringify([from, to]);
+
+
+
+
+
+const named_hook_name = (from: string, to: string, action: string): string =>
+
+  JSON.stringify([from, to, action]);
+
+
+
+
+
 export {
   seq,
   arr_uniq_p,
   histograph, weighted_histo_key,
   weighted_rand_select, weighted_sample_select,
-  array_box_if_string
+  array_box_if_string,
+  hook_name, named_hook_name
 };