jssm 5.72.4 → 5.73.1

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,4 +1,5 @@
 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, HookContext, HookResult, HookComplexResult } from './jssm_types';
 import { seq, weighted_rand_select, weighted_sample_select, histograph, weighted_histo_key } from './jssm_util';
@@ -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.

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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jssm",
-  "version": "5.72.4",
+  "version": "5.73.1",
   "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": {
@@ -119,6 +120,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",
@@ -129,6 +131,7 @@
     "typescript": "^4.6.4"
   },
   "dependencies": {
+    "circular_buffer_js": "^1.10.0",
     "better_git_changelog": "^1.6.1",
     "reduce-to-639-1": "^1.0.4"
   }