jssm 5.44.0 → 5.45.0

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.44.0",
+  "version": "5.45.0",
   "engines": {
     "node": ">=10.0.0"
   },

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';
 
 
@@ -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) => {
@@ -975,14 +984,73 @@ 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;
     }
@@ -993,11 +1061,35 @@ class Machine<mDT> {
     // 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
@@ -1006,18 +1098,44 @@ class Machine<mDT> {
     // 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> {
@@ -1081,7 +1199,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
 };
 

package/src/ts/tests/hooks.spec.ts

@@ -5,9 +5,7 @@ import { sm } from '../jssm';
 
 
 
-describe('Hooks', () => {
-
-
+describe('Hooks open and closed in grammar', () => {
 
   test.todo('Hooks open doesn\'t throw' /*, () => {
 
@@ -23,6 +21,189 @@ describe('Hooks', () => {
 
   } */);
 
+});
+
+
+
+
+
+describe('Basic hooks on API callpoint', () => {
+
+
+  test('Setting a regular hook doesn\'t throw', () => {
+
+    expect( () => {
+      const _foo = sm`a -> b;`;
+      _foo.set_hook({ from: 'a', to: 'b', handler: () => console.log('hi'), kind: 'hook' })
+    })
+      .not.toThrow();
+
+  } );
+
+
+  test('Setting a named hook doesn\'t throw', () => {
+
+    expect( () => {
+      const _foo = sm`a 'foo' -> b;`;
+      _foo.set_hook({ from: 'a', to: 'b', handler: () => console.log('hi'), kind: 'named', action: 'foo' })
+    })
+      .not.toThrow();
+
+  } );
+
+
+  test('Setting a kind of hook that doesn\'t exist throws', () => {
+
+    expect( () => {
+      const _foo = sm`a 'foo' -> b;`;
+      _foo.set_hook({ from: 'a', to: 'b', handler: () => console.log('hi'), kind: 'Smaug the Merciless', action: 'foo' } as any)
+    })
+      .toThrow();
+
+  } );
+
+});
+
+
+
+
+
+test('Basic hook rejection works', () => {
+
+  const foo = sm`a => b;`;
+
+  foo.set_hook({ from: 'a', to: 'b', kind: 'hook', handler: () => false });
+  expect(foo.transition('b')).toBe(false);
+  expect(foo.state()).toBe('a');
+
+  foo.set_hook({ from: 'a', to: 'b', kind: 'hook', handler: () => true });
+  expect(foo.transition('b')).toBe(true);
+  expect(foo.state()).toBe('b');
+
+});
+
+
+
+
+
+test('Basic hook rejection works on forced edges', () => {
+
+  const foo = sm`a ~> b ~> c;`;
+
+  foo.set_hook({ from: 'a', to: 'b', kind: 'hook', handler: () => false });
+  expect(foo.force_transition('b')).toBe(false);
+  expect(foo.state()).toBe('a');
+
+  foo.set_hook({ from: 'a', to: 'b', kind: 'hook', handler: () => true });
+  expect(foo.force_transition('b')).toBe(true);
+  expect(foo.state()).toBe('b');
+
+  // line completion for when a hook lookup finds nothing
+  expect(foo.force_transition('c')).toBe(true);
+  expect(foo.state()).toBe('c');
+
+});
+
+
+
+
+
+test('Named hook rejection works', () => {
+
+  const foo = sm`a 'foo' => b;`;
+
+  foo.set_hook({ from: 'a', to: 'b', action: 'foo', kind: 'named', handler: () => false });
+  expect(foo.action('foo')).toBe(false);
+  expect(foo.state()).toBe('a');
+
+  foo.set_hook({ from: 'a', to: 'b', action: 'foo', kind: 'named', handler: () => true });
+  expect(foo.action('foo')).toBe(true);
+  expect(foo.state()).toBe('b');
+
+});
+
+
+
+
+
+test('Named hook rejection doesn\'t block transitions', () => {
+
+  const foo = sm`a 'foo' => b;`;
+
+  foo.set_hook({ from: 'a', to: 'b', action: 'foo', kind: 'named', handler: () => false });
+  expect(foo.action('foo')).toBe(false);
+  expect(foo.state()).toBe('a');
+
+  expect(foo.transition('b')).toBe(true);
+  expect(foo.state()).toBe('b');
+
+});
+
+
+
+
+
+describe('Basic hooks on API callpoint', () => {
+
+  test('Basic hooks call their handler', () => {
+
+    const handler  = jest.fn(x => true),
+          uncalled = jest.fn(x => true);
+
+    expect( () => {
+      const _foo = sm`a -> b -> c;`;
+      _foo.set_hook({ from: 'a', to: 'b', handler,           kind: 'hook' });
+      _foo.set_hook({ from: 'b', to: 'a', handler: uncalled, kind: 'hook' });
+      _foo.set_hook({ from: 'b', to: 'c', handler: uncalled, kind: 'hook' });
+      _foo.transition('b');
+    })
+      .not.toThrow();
+
+    // should hook from first, but not from second
+    expect(handler.mock.calls.length).toBe(1);
+    expect(uncalled.mock.calls.length).toBe(0);
+
+  } );
+
+  test('Named hooks call their handler', () => {
+
+    const handler  = jest.fn(x => true),
+          uncalled = jest.fn(x => true);
+
+    expect( () => {
+      const _foo = sm`a 'next' -> b 'next' -> c;`;
+      _foo.set_hook({ from: 'a', to: 'b', handler,           kind: 'named', action: 'next' });
+      _foo.set_hook({ from: 'a', to: 'b', handler: uncalled, kind: 'named', action: 'borg' });
+      _foo.set_hook({ from: 'b', to: 'a', handler: uncalled, kind: 'named', action: 'next' });
+      _foo.action('next');
+      _foo.action('next');
+    })
+      .not.toThrow();
+
+    // should hook from first, but not from second
+    expect(handler.mock.calls.length).toBe(1);
+    expect(uncalled.mock.calls.length).toBe(0);
+
+  } );
+
+  test('Forced hooks call their handler', () => {
+
+    const handler  = jest.fn(x => true),
+          uncalled = jest.fn(x => true);
+
+    expect( () => {
+      const _foo = sm`a ~> b ~> c;`;
+      _foo.set_hook({ from: 'a', to: 'b', handler,           kind: 'hook' });
+      _foo.set_hook({ from: 'b', to: 'a', handler: uncalled, kind: 'hook' });
+      _foo.set_hook({ from: 'b', to: 'c', handler: uncalled, kind: 'hook' });
+      _foo.force_transition('b');
+    })
+      .not.toThrow();
+
+    // should hook from first, but not from second
+    expect(handler.mock.calls.length).toBe(1);
+    expect(uncalled.mock.calls.length).toBe(0);
 
+  } );
 
 });

package/src/ts/version.ts

@@ -1,3 +1,3 @@
 
-const version: string = "5.44.0";
+const version: string = "5.45.0";
 export { version };