jssm 5.72.0 → 5.72.3

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, HookDescription, HookHandler } from './jssm_types';
+JssmMachineInternalState, JssmParseTree, JssmStateDeclaration, JssmArrow, JssmArrowDirection, JssmArrowKind, JssmLayout, FslDirection, FslTheme, HookDescription, HookHandler, HookResult } from './jssm_types';
 import { seq, 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';
@@ -223,16 +223,16 @@ declare class Machine<mDT> {
     _has_exit_hooks: boolean;
     _has_global_action_hooks: boolean;
     _has_transition_hooks: boolean;
-    _hooks: Map<string, Function>;
-    _named_hooks: Map<string, Function>;
-    _entry_hooks: Map<string, Function>;
-    _exit_hooks: Map<string, Function>;
-    _global_action_hooks: Map<string, Function>;
-    _any_action_hook: HookHandler | undefined;
-    _standard_transition_hook: HookHandler | undefined;
-    _main_transition_hook: HookHandler | undefined;
-    _forced_transition_hook: HookHandler | undefined;
-    _any_transition_hook: HookHandler | undefined;
+    _hooks: Map<string, HookHandler<mDT>>;
+    _named_hooks: Map<string, HookHandler<mDT>>;
+    _entry_hooks: Map<string, HookHandler<mDT>>;
+    _exit_hooks: Map<string, HookHandler<mDT>>;
+    _global_action_hooks: Map<string, HookHandler<mDT>>;
+    _any_action_hook: HookHandler<mDT> | undefined;
+    _standard_transition_hook: HookHandler<mDT> | undefined;
+    _main_transition_hook: HookHandler<mDT> | undefined;
+    _forced_transition_hook: HookHandler<mDT> | undefined;
+    _any_transition_hook: HookHandler<mDT> | 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, instance_name, data }: JssmGenericConfig<mDT>);
     /********
      *
@@ -260,6 +260,21 @@ declare class Machine<mDT> {
      *
      */
     state(): StateType;
+    /*********
+     *
+     *  Get the current data of a machine.
+     *
+     *  ```typescript
+     *  import * as jssm from 'jssm';
+     *
+     *  const switch = jssm.from('on <=> off;', {data: 1});
+     *  console.log( switch.data() );              // 1
+     *  ```
+     *
+     *  @typeparam mDT The type of the machine data member; usually omitted
+     *
+     */
+    data(): mDT;
     /********
      *
      *  Check whether a given state is final (either has no exits or is marked
@@ -523,17 +538,17 @@ declare class Machine<mDT> {
     is_complete(): boolean;
     state_is_complete(whichState: StateType): boolean;
     has_completes(): boolean;
-    set_hook(HookDesc: HookDescription): void;
-    hook(from: string, to: string, handler: HookHandler): Machine<mDT>;
-    hook_action(from: string, to: string, action: string, handler: HookHandler): Machine<mDT>;
-    hook_global_action(action: string, handler: HookHandler): Machine<mDT>;
-    hook_any_action(handler: HookHandler): Machine<mDT>;
-    hook_standard_transition(handler: HookHandler): Machine<mDT>;
-    hook_main_transition(handler: HookHandler): Machine<mDT>;
-    hook_forced_transition(handler: HookHandler): Machine<mDT>;
-    hook_any_transition(handler: HookHandler): Machine<mDT>;
-    hook_entry(to: string, handler: HookHandler): Machine<mDT>;
-    hook_exit(from: string, handler: HookHandler): Machine<mDT>;
+    set_hook(HookDesc: HookDescription<mDT>): void;
+    hook(from: string, to: string, handler: HookHandler<mDT>): Machine<mDT>;
+    hook_action(from: string, to: string, action: string, handler: HookHandler<mDT>): Machine<mDT>;
+    hook_global_action(action: string, handler: HookHandler<mDT>): Machine<mDT>;
+    hook_any_action(handler: HookHandler<mDT>): Machine<mDT>;
+    hook_standard_transition(handler: HookHandler<mDT>): Machine<mDT>;
+    hook_main_transition(handler: HookHandler<mDT>): Machine<mDT>;
+    hook_forced_transition(handler: HookHandler<mDT>): Machine<mDT>;
+    hook_any_transition(handler: HookHandler<mDT>): Machine<mDT>;
+    hook_entry(to: string, handler: HookHandler<mDT>): Machine<mDT>;
+    hook_exit(from: string, handler: HookHandler<mDT>): Machine<mDT>;
     edges_between(from: string, to: string): JssmTransition<mDT>[];
     transition_impl(newStateOrAction: StateType, newData: mDT | undefined, wasForced: boolean, wasAction: boolean): boolean;
     /********
@@ -654,4 +669,5 @@ declare function sm<mDT>(template_strings: TemplateStringsArray, ...remainder: a
  *
  */
 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, shapes, gviz_shapes, named_colors };
+declare function is_hook_rejection(hr: HookResult): boolean;
+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 };

package/jssm_types.d.ts

@@ -149,57 +149,66 @@ declare type JssmCompileSeStart<DataType> = {
 };
 declare type JssmParseTree = Array<JssmCompileSeStart<StateType>>;
 declare type JssmParseFunctionType = (string: any) => JssmParseTree;
-declare type HookHandler = Function;
-declare type BasicHookDescription = {
+declare type BasicHookDescription<mDT> = {
     kind: 'hook';
     from: string;
     to: string;
-    handler: HookHandler;
+    handler: HookHandler<mDT>;
 };
-declare type HookDescriptionWithAction = {
+declare type HookDescriptionWithAction<mDT> = {
     kind: 'named';
     from: string;
     to: string;
     action: string;
-    handler: HookHandler;
+    handler: HookHandler<mDT>;
 };
-declare type StandardTransitionHook = {
+declare type StandardTransitionHook<mDT> = {
     kind: 'standard transition';
-    handler: HookHandler;
+    handler: HookHandler<mDT>;
 };
-declare type MainTransitionHook = {
+declare type MainTransitionHook<mDT> = {
     kind: 'main transition';
-    handler: HookHandler;
+    handler: HookHandler<mDT>;
 };
-declare type ForcedTransitionHook = {
+declare type ForcedTransitionHook<mDT> = {
     kind: 'forced transition';
-    handler: HookHandler;
+    handler: HookHandler<mDT>;
 };
-declare type AnyTransitionHook = {
+declare type AnyTransitionHook<mDT> = {
     kind: 'any transition';
-    handler: HookHandler;
+    handler: HookHandler<mDT>;
 };
-declare type GlobalActionHook = {
+declare type GlobalActionHook<mDT> = {
     kind: 'global action';
     action: string;
-    handler: HookHandler;
+    handler: HookHandler<mDT>;
 };
-declare type AnyActionHook = {
+declare type AnyActionHook<mDT> = {
     kind: 'any action';
-    handler: HookHandler;
+    handler: HookHandler<mDT>;
 };
-declare type EntryHook = {
+declare type EntryHook<mDT> = {
     kind: 'entry';
     to: string;
-    handler: HookHandler;
+    handler: HookHandler<mDT>;
 };
-declare type ExitHook = {
+declare type ExitHook<mDT> = {
     kind: 'exit';
     from: string;
-    handler: HookHandler;
+    handler: HookHandler<mDT>;
 };
-declare type HookDescription = BasicHookDescription | HookDescriptionWithAction | GlobalActionHook | AnyActionHook | StandardTransitionHook | MainTransitionHook | ForcedTransitionHook | AnyTransitionHook | EntryHook | ExitHook;
+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 HookComplexResult<mDT> = {
+    pass: boolean;
+    state?: StateType;
+    data?: mDT;
+};
+declare type HookResult = true | false | undefined | void;
+declare type HookContext<mDT> = {
+    data: mDT;
+};
+declare type HookHandler<mDT> = (hook_context: HookContext<mDT>) => HookResult;
 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 };
+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, HookContext, HookResult, HookComplexResult };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jssm",
-  "version": "5.72.0",
+  "version": "5.72.3",
   "engines": {
     "node": ">=10.0.0"
   },