jssm 5.72.5 → 5.74.0

package/dist/es6/jssm.js

@@ -1,5 +1,6 @@
 // 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 { shapes, gviz_shapes, named_colors } from './jssm_constants';
 import { parse } from './jssm-dot';
@@ -534,7 +535,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, data }) {
+    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 }) {
         this._instance_name = instance_name;
         this._state = start_states[0];
         this._states = new Map();
@@ -569,7 +570,7 @@ class Machine {
         this._has_exit_hooks = false;
         this._has_global_action_hooks = false;
         this._has_transition_hooks = true;
-        // no need for a boolean has any transition hook, as it's one or nothing, so just test that for undefinedness
+        // 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();
@@ -580,8 +581,27 @@ class Machine {
         this._main_transition_hook = undefined;
         this._forced_transition_hook = undefined;
         this._any_transition_hook = undefined;
-        this._standard_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._history_length = history || 0;
+        this._history = new circular_buffer(this._history_length);
         if (state_declaration) {
             state_declaration.map((state_decl) => {
                 if (this._state_declarations.has(state_decl.state)) { // no repeats
@@ -1249,6 +1269,54 @@ class Machine {
                 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`);
         }
@@ -1293,6 +1361,46 @@ class Machine {
         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');
     // }
@@ -1328,15 +1436,16 @@ class Machine {
                 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) {
-                const hook_args = {
-                    data: this._data,
-                    action: fromAction,
-                    from: this._state,
-                    to: newState,
-                    forced: wasForced
-                };
                 function update_fields(res) {
                     if (res.hasOwnProperty('data')) {
                         hook_args.data = res.data;
@@ -1426,22 +1535,191 @@ class Machine {
                     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;
                 }
-                return true;
+                // 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;
-                return true;
+                // 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);
     }
     /********
      *

package/dist/es6/jssm_types.d.ts

@@ -102,6 +102,7 @@ declare type JssmGenericConfig<DataType> = {
     data?: DataType;
     nodes?: Array<StateType>;
     check?: JssmStatePermitterMaybeArray<DataType>;
+    history?: number;
     min_exits?: number;
     max_exits?: number;
     allow_islands?: false;
@@ -197,7 +198,55 @@ declare type ExitHook<mDT> = {
     from: string;
     handler: HookHandler<mDT>;
 };
-declare type HookDescription<mDT> = BasicHookDescription<mDT> | HookDescriptionWithAction<mDT> | GlobalActionHook<mDT> | AnyActionHook<mDT> | StandardTransitionHook<mDT> | MainTransitionHook<mDT> | ForcedTransitionHook<mDT> | AnyTransitionHook<mDT> | EntryHook<mDT> | ExitHook<mDT>;
+declare type PostBasicHookDescription<mDT> = {
+    kind: 'post hook';
+    from: string;
+    to: string;
+    handler: PostHookHandler<mDT>;
+};
+declare type PostHookDescriptionWithAction<mDT> = {
+    kind: 'post named';
+    from: string;
+    to: string;
+    action: string;
+    handler: PostHookHandler<mDT>;
+};
+declare type PostStandardTransitionHook<mDT> = {
+    kind: 'post standard transition';
+    handler: PostHookHandler<mDT>;
+};
+declare type PostMainTransitionHook<mDT> = {
+    kind: 'post main transition';
+    handler: PostHookHandler<mDT>;
+};
+declare type PostForcedTransitionHook<mDT> = {
+    kind: 'post forced transition';
+    handler: PostHookHandler<mDT>;
+};
+declare type PostAnyTransitionHook<mDT> = {
+    kind: 'post any transition';
+    handler: PostHookHandler<mDT>;
+};
+declare type PostGlobalActionHook<mDT> = {
+    kind: 'post global action';
+    action: string;
+    handler: PostHookHandler<mDT>;
+};
+declare type PostAnyActionHook<mDT> = {
+    kind: 'post any action';
+    handler: PostHookHandler<mDT>;
+};
+declare type PostEntryHook<mDT> = {
+    kind: 'post entry';
+    to: string;
+    handler: PostHookHandler<mDT>;
+};
+declare type PostExitHook<mDT> = {
+    kind: 'post exit';
+    from: string;
+    handler: PostHookHandler<mDT>;
+};
+declare type HookDescription<mDT> = BasicHookDescription<mDT> | HookDescriptionWithAction<mDT> | GlobalActionHook<mDT> | AnyActionHook<mDT> | StandardTransitionHook<mDT> | MainTransitionHook<mDT> | ForcedTransitionHook<mDT> | AnyTransitionHook<mDT> | EntryHook<mDT> | ExitHook<mDT> | PostBasicHookDescription<mDT> | PostHookDescriptionWithAction<mDT> | PostGlobalActionHook<mDT> | PostAnyActionHook<mDT> | PostStandardTransitionHook<mDT> | PostMainTransitionHook<mDT> | PostForcedTransitionHook<mDT> | PostAnyTransitionHook<mDT> | PostEntryHook<mDT> | PostExitHook<mDT>;
 declare type HookComplexResult<mDT> = {
     pass: boolean;
     state?: StateType;
@@ -208,6 +257,7 @@ declare type HookContext<mDT> = {
     data: mDT;
 };
 declare type HookHandler<mDT> = (hook_context: HookContext<mDT>) => HookResult<mDT>;
+declare type PostHookHandler<mDT> = (hook_context: HookContext<mDT>) => void;
 declare type JssmErrorExtendedInfo = {
     requested_state?: StateType | undefined;
 };

package/dist/es6/version.js

@@ -1,2 +1,2 @@
-const version = "5.72.5";
+const version = "5.74.0";
 export { version };