jssm 5.72.3 → 5.73.0

package/jest-spec.config.js

@@ -22,6 +22,12 @@ module.exports = {
     },
   },
 
-  collectCoverageFrom: ["src/ts/**/{!(jssm-dot),}.{js,ts}"]
+  collectCoverageFrom: ["src/ts/**/{!(jssm-dot),}.{js,ts}"],
+
+  reporters: [
+    ['default',             {}],
+    ['jest-json-reporter2', { outputDir: './coverage/spec', outputFile: 'metrics.json',          fullOutput: false }],
+//  ['jest-json-reporter2', { outputDir: './coverage/spec', outputFile: 'extended-metrics.json', fullOutput: true  }],
+  ]
 
 };

package/jssm.d.ts

@@ -1,6 +1,7 @@
 declare type StateType = string;
+import { circular_buffer } from 'circular_buffer_js';
 import { JssmGenericState, JssmGenericConfig, JssmTransition, JssmTransitionList, // JssmTransitionRule,
-JssmMachineInternalState, JssmParseTree, JssmStateDeclaration, JssmArrow, JssmArrowDirection, JssmArrowKind, JssmLayout, FslDirection, FslTheme, HookDescription, HookHandler, HookResult } from './jssm_types';
+JssmMachineInternalState, JssmParseTree, JssmStateDeclaration, JssmArrow, JssmArrowDirection, JssmArrowKind, JssmLayout, FslDirection, FslTheme, HookDescription, HookHandler, HookContext, HookResult, HookComplexResult } 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';
@@ -233,7 +234,9 @@ declare class Machine<mDT> {
     _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>);
+    _history: circular_buffer<[StateType, mDT]>;
+    _history_length: number;
+    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, history, data }: JssmGenericConfig<mDT>);
     /********
      *
      *  Internal method for fabricating states.  Not meant for external use.
@@ -551,6 +554,88 @@ declare class 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;
+    /*********
+     *
+     *  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(): [string, mDT][];
+    /*********
+     *
+     *  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(): [string, mDT][];
+    /*********
+     *
+     *  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(): number;
+    set history_length(to: number);
     /********
      *
      *  Instruct the machine to complete an action.
@@ -669,5 +754,7 @@ declare function sm<mDT>(template_strings: TemplateStringsArray, ...remainder: a
  *
  */
 declare function from<mDT>(MachineAsString: string, ExtraConstructorFields?: Partial<JssmGenericConfig<mDT>> | undefined): Machine<mDT>;
-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 };
+declare function is_hook_complex_result<mDT>(hr: unknown): hr is HookComplexResult<mDT>;
+declare function is_hook_rejection<mDT>(hr: HookResult<mDT>): boolean;
+declare function abstract_hook_step<mDT>(maybe_hook: HookHandler<mDT> | undefined, hook_args: HookContext<mDT>): HookComplexResult<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, is_hook_rejection, is_hook_complex_result, abstract_hook_step };

package/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;
@@ -203,11 +204,11 @@ declare type HookComplexResult<mDT> = {
     state?: StateType;
     data?: mDT;
 };
-declare type HookResult = true | false | undefined | void;
+declare type HookResult<mDT> = true | false | undefined | void | HookComplexResult<mDT>;
 declare type HookContext<mDT> = {
     data: mDT;
 };
-declare type HookHandler<mDT> = (hook_context: HookContext<mDT>) => HookResult;
+declare type HookHandler<mDT> = (hook_context: HookContext<mDT>) => HookResult<mDT>;
 declare type JssmErrorExtendedInfo = {
     requested_state?: StateType | undefined;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jssm",
-  "version": "5.72.3",
+  "version": "5.73.0",
   "engines": {
     "node": ">=10.0.0"
   },
@@ -47,7 +47,7 @@
     "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",
     "benny": "node ./src/buildjs/benchmark.js",
-    "build": "npm run vet && npm run test && npm run site && npm run changelog && npm run docs",
+    "build": "npm run vet && npm run test && npm run site && npm run changelog && npm run docs && npm run readme",
     "clean_bench": "npm run test && npm run benny",
     "qbuild": "npm run test",
     "ci_build": "npm run vet && npm run test",
@@ -56,6 +56,7 @@
     "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",
     "site": "cp src/site/* docs/ && cp -r src/assets docs/assets/",
     "docs": "typedoc src/ts/jssm.ts --options typedoc-options.js",
+    "readme": "rm ./README.md && node ./src/buildjs/make_readme.js",
     "changelog": "rm -f CHANGELOG.md && rm -f ./src/doc_md/CHANGELOG.md && better_git_changelog -b && cp CHANGELOG.* ./src/doc_md/"
   },
   "repository": {
@@ -109,6 +110,7 @@
     "@typescript-eslint/eslint-plugin": "^4.13.0",
     "@typescript-eslint/parser": "^4.13.0",
     "benny": "^3.7.1",
+    "circular_buffer_js": "^1.10.0",
     "coveralls": "^3.0.11",
     "eslint": "^7.32.0",
     "eslint-plugin-fp": "^2.3.0",
@@ -119,6 +121,7 @@
     "fast-check": "^2.12.0",
     "glob": "^7.1.6",
     "jest": "^27.3.1",
+    "jest-json-reporter2": "^1.1.0",
     "pegjs": "^0.10.0",
     "rollup": "^2.72.1",
     "semver": "^5.7.1",