Merge pull request #485 from StoneCypher/DocIsFinalAndStateIsFinal

Document is_final and state_is_final, fixes StoneCypher/fsl#796, fixes StoneCypher/fsl#797
StoneCypher · May 22, 2022 · 605f414 · 605f414
2 parents 48f1e98 + 75f33eb
commit 605f414
Show file tree

Hide file tree

Showing 18 changed files with 346 additions and 98 deletions.
diff --git a/benchmark/results/general.chart.html b/benchmark/results/general.chart.html
@@ -28,7 +28,7 @@
   </head>
   <body>
     <div class="container">
-      <canvas id="chart1653241143232" width="16" height="9"></canvas>
+      <canvas id="chart1653255747564" width="16" height="9"></canvas>
     </div>
     <script>
       const format = (num) => {
@@ -51,18 +51,18 @@
           chunked.map((chunk) => chunk.join('')).join(' ') + fractionStr
         )
       }
-      const ctx1653241143232 = document
-        .getElementById('chart1653241143232')
+      const ctx1653255747564 = document
+        .getElementById('chart1653255747564')
         .getContext('2d')
-      const chart1653241143232 = new Chart(ctx1653241143232, {
+      const chart1653255747564 = new Chart(ctx1653255747564, {
         type: 'bar',
         data: {
           labels: ["Blind cycle a traffic light 500 times by transition","Blind cycle a traffic light 500 times by action","Blind cycle a basic-hooked traffic light 500 times by transition","Blind cycle a named-hooked traffic light 500 times by transition","Blind cycle an any-transition traffic light 500 times by transition","Blind cycle an exit hooked traffic light 500 times by transition","Blind cycle an enter hooked traffic light 500 times by transition","Blind cycle a standard-transition hooked light by transition","Blind cycle a main-transition hooked light by transition","Blind cycle a force-transition hooked light by transition","Blind cycle a traffic light 500 times by action","Blind cycle a basic-hooked traffic light 500 times by action","Blind cycle a named-hooked traffic light 500 times by action","Blind cycle an any-action traffic light 500 times by action","Blind cycle a global-action traffic light 500 times by action","Blind cycle an exit hooked traffic light 500 times by action","Blind cycle an enter hooked traffic light 500 times by action","Blind cycle a standard transition tl 500 times by action","Blind cycle a main transition tl 500 times by action","Blind cycle a forced transition tl 500 times by action","Kitchen Sink 500 times"],
           datasets: [
             {
-              data: [5330,12241,1363,6536,6148,5888,5799,6104,5756,25262,13227,1523,1396,10517,10427,9342,9214,64778,67627,67085,9406],
-              backgroundColor: ["hsl(9.455999999999994, 85%, 55%)","hsl(21.71999999999999, 85%, 55%)","hsl(2.4239999999999955, 85%, 55%)","hsl(11.591999999999995, 85%, 55%)","hsl(10.908000000000005, 85%, 55%)","hsl(10.451999999999993, 85%, 55%)","hsl(10.283999999999992, 85%, 55%)","hsl(10.836, 85%, 55%)","hsl(10.212000000000007, 85%, 55%)","hsl(44.82, 85%, 55%)","hsl(23.472, 85%, 55%)","hsl(2.6999999999999997, 85%, 55%)","hsl(2.4720000000000026, 85%, 55%)","hsl(18.659999999999997, 85%, 55%)","hsl(18.504, 85%, 55%)","hsl(16.572000000000003, 85%, 55%)","hsl(16.344000000000005, 85%, 55%)","hsl(114.94800000000001, 85%, 55%)","hsl(120, 85%, 55%)","hsl(119.03999999999999, 85%, 55%)","hsl(16.691999999999997, 85%, 55%)"],
-              borderColor: ["hsl(9.455999999999994, 85%, 55%)","hsl(21.71999999999999, 85%, 55%)","hsl(2.4239999999999955, 85%, 55%)","hsl(11.591999999999995, 85%, 55%)","hsl(10.908000000000005, 85%, 55%)","hsl(10.451999999999993, 85%, 55%)","hsl(10.283999999999992, 85%, 55%)","hsl(10.836, 85%, 55%)","hsl(10.212000000000007, 85%, 55%)","hsl(44.82, 85%, 55%)","hsl(23.472, 85%, 55%)","hsl(2.6999999999999997, 85%, 55%)","hsl(2.4720000000000026, 85%, 55%)","hsl(18.659999999999997, 85%, 55%)","hsl(18.504, 85%, 55%)","hsl(16.572000000000003, 85%, 55%)","hsl(16.344000000000005, 85%, 55%)","hsl(114.94800000000001, 85%, 55%)","hsl(120, 85%, 55%)","hsl(119.03999999999999, 85%, 55%)","hsl(16.691999999999997, 85%, 55%)"],
+              data: [4959,11036,1319,5782,5556,5580,5479,5754,5739,19638,12330,1439,1383,9516,10484,9151,9032,67056,67313,67073,8697],
+              backgroundColor: ["hsl(8.844000000000005, 85%, 55%)","hsl(19.680000000000007, 85%, 55%)","hsl(2.3519999999999923, 85%, 55%)","hsl(10.308000000000003, 85%, 55%)","hsl(9.9, 85%, 55%)","hsl(9.948000000000008, 85%, 55%)","hsl(9.768, 85%, 55%)","hsl(10.259999999999996, 85%, 55%)","hsl(10.236000000000002, 85%, 55%)","hsl(35.004000000000005, 85%, 55%)","hsl(21.98399999999999, 85%, 55%)","hsl(2.5680000000000005, 85%, 55%)","hsl(2.459999999999997, 85%, 55%)","hsl(16.968, 85%, 55%)","hsl(18.695999999999998, 85%, 55%)","hsl(16.308000000000003, 85%, 55%)","hsl(16.104000000000003, 85%, 55%)","hsl(119.54400000000001, 85%, 55%)","hsl(120, 85%, 55%)","hsl(119.568, 85%, 55%)","hsl(15.504000000000001, 85%, 55%)"],
+              borderColor: ["hsl(8.844000000000005, 85%, 55%)","hsl(19.680000000000007, 85%, 55%)","hsl(2.3519999999999923, 85%, 55%)","hsl(10.308000000000003, 85%, 55%)","hsl(9.9, 85%, 55%)","hsl(9.948000000000008, 85%, 55%)","hsl(9.768, 85%, 55%)","hsl(10.259999999999996, 85%, 55%)","hsl(10.236000000000002, 85%, 55%)","hsl(35.004000000000005, 85%, 55%)","hsl(21.98399999999999, 85%, 55%)","hsl(2.5680000000000005, 85%, 55%)","hsl(2.459999999999997, 85%, 55%)","hsl(16.968, 85%, 55%)","hsl(18.695999999999998, 85%, 55%)","hsl(16.308000000000003, 85%, 55%)","hsl(16.104000000000003, 85%, 55%)","hsl(119.54400000000001, 85%, 55%)","hsl(120, 85%, 55%)","hsl(119.568, 85%, 55%)","hsl(15.504000000000001, 85%, 55%)"],
               borderWidth: 2,
             },
           ],

diff --git a/benchmark/results/general.json b/benchmark/results/general.json
@@ -1,133 +1,133 @@
 {
   "name": "General performance suite",
-  "date": "2022-05-22T17:39:03.232Z",
+  "date": "2022-05-22T21:42:27.564Z",
   "version": "1.2.0",
   "results": [
     {
       "name": "Blind cycle a traffic light 500 times by transition",
-      "ops": 5330,
-      "margin": 3.41,
-      "percentSlower": 92.12
+      "ops": 4959,
+      "margin": 3.56,
+      "percentSlower": 92.63
     },
     {
       "name": "Blind cycle a traffic light 500 times by action",
-      "ops": 12241,
-      "margin": 2.23,
-      "percentSlower": 81.9
+      "ops": 11036,
+      "margin": 1.9,
+      "percentSlower": 83.6
     },
     {
       "name": "Blind cycle a basic-hooked traffic light 500 times by transition",
-      "ops": 1363,
-      "margin": 0.73,
-      "percentSlower": 97.98
+      "ops": 1319,
+      "margin": 0.82,
+      "percentSlower": 98.04
     },
     {
       "name": "Blind cycle a named-hooked traffic light 500 times by transition",
-      "ops": 6536,
-      "margin": 0.97,
-      "percentSlower": 90.34
+      "ops": 5782,
+      "margin": 0.93,
+      "percentSlower": 91.41
     },
     {
       "name": "Blind cycle an any-transition traffic light 500 times by transition",
-      "ops": 6148,
-      "margin": 0.94,
-      "percentSlower": 90.91
+      "ops": 5556,
+      "margin": 1,
+      "percentSlower": 91.75
     },
     {
       "name": "Blind cycle an exit hooked traffic light 500 times by transition",
-      "ops": 5888,
-      "margin": 1,
-      "percentSlower": 91.29
+      "ops": 5580,
+      "margin": 0.89,
+      "percentSlower": 91.71
     },
     {
       "name": "Blind cycle an enter hooked traffic light 500 times by transition",
-      "ops": 5799,
-      "margin": 1.09,
-      "percentSlower": 91.43
+      "ops": 5479,
+      "margin": 1.74,
+      "percentSlower": 91.86
     },
     {
       "name": "Blind cycle a standard-transition hooked light by transition",
-      "ops": 6104,
-      "margin": 0.94,
-      "percentSlower": 90.97
+      "ops": 5754,
+      "margin": 2.1,
+      "percentSlower": 91.45
     },
     {
       "name": "Blind cycle a main-transition hooked light by transition",
-      "ops": 5756,
-      "margin": 3.47,
-      "percentSlower": 91.49
+      "ops": 5739,
+      "margin": 1.19,
+      "percentSlower": 91.47
     },
     {
       "name": "Blind cycle a force-transition hooked light by transition",
-      "ops": 25262,
-      "margin": 0.77,
-      "percentSlower": 62.65
+      "ops": 19638,
+      "margin": 0.72,
+      "percentSlower": 70.83
     },
     {
       "name": "Blind cycle a traffic light 500 times by action",
-      "ops": 13227,
-      "margin": 0.76,
-      "percentSlower": 80.44
+      "ops": 12330,
+      "margin": 7.49,
+      "percentSlower": 81.68
     },
     {
       "name": "Blind cycle a basic-hooked traffic light 500 times by action",
-      "ops": 1523,
-      "margin": 3.06,
-      "percentSlower": 97.75
+      "ops": 1439,
+      "margin": 6.88,
+      "percentSlower": 97.86
     },
     {
       "name": "Blind cycle a named-hooked traffic light 500 times by action",
-      "ops": 1396,
-      "margin": 1.46,
-      "percentSlower": 97.94
+      "ops": 1383,
+      "margin": 1.92,
+      "percentSlower": 97.95
     },
     {
       "name": "Blind cycle an any-action traffic light 500 times by action",
-      "ops": 10517,
-      "margin": 0.92,
-      "percentSlower": 84.45
+      "ops": 9516,
+      "margin": 7.89,
+      "percentSlower": 85.86
     },
     {
       "name": "Blind cycle a global-action traffic light 500 times by action",
-      "ops": 10427,
-      "margin": 2.11,
-      "percentSlower": 84.58
+      "ops": 10484,
+      "margin": 2.55,
+      "percentSlower": 84.42
     },
     {
       "name": "Blind cycle an exit hooked traffic light 500 times by action",
-      "ops": 9342,
-      "margin": 0.7,
-      "percentSlower": 86.19
+      "ops": 9151,
+      "margin": 0.92,
+      "percentSlower": 86.41
     },
     {
       "name": "Blind cycle an enter hooked traffic light 500 times by action",
-      "ops": 9214,
-      "margin": 1.63,
-      "percentSlower": 86.38
+      "ops": 9032,
+      "margin": 0.86,
+      "percentSlower": 86.58
     },
     {
       "name": "Blind cycle a standard transition tl 500 times by action",
-      "ops": 64778,
-      "margin": 0.64,
-      "percentSlower": 4.21
+      "ops": 67056,
+      "margin": 0.81,
+      "percentSlower": 0.38
     },
     {
       "name": "Blind cycle a main transition tl 500 times by action",
-      "ops": 67627,
-      "margin": 0.92,
+      "ops": 67313,
+      "margin": 1.41,
       "percentSlower": 0
     },
     {
       "name": "Blind cycle a forced transition tl 500 times by action",
-      "ops": 67085,
-      "margin": 0.71,
-      "percentSlower": 0.8
+      "ops": 67073,
+      "margin": 1.04,
+      "percentSlower": 0.36
     },
     {
       "name": "Kitchen Sink 500 times",
-      "ops": 9406,
-      "margin": 1.02,
-      "percentSlower": 86.09
+      "ops": 8697,
+      "margin": 0.93,
+      "percentSlower": 87.08
     }
   ],
   "fastest": {

diff --git a/dist/es6/jssm.d.ts b/dist/es6/jssm.d.ts
@@ -213,6 +213,11 @@ declare class Machine<mDT> {
     _forced_transition_hook: HookHandler | undefined;
     _any_transition_hook: HookHandler | 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 }: JssmGenericConfig<mDT>);
+    /********
+     *
+     *  Internal method for fabricating states.  Not meant for external use.
+     *
+     */
     _new_state(state_config: JssmGenericState): StateType;
     /*********
      *
@@ -230,7 +235,38 @@ declare class Machine<mDT> {
      *
      */
     state(): StateType;
+    /********
+     *
+     *  Check whether a given state is final (either has no exits or is marked
+     *  `complete`.)
+     *
+     *  ```typescript
+     *  import { sm, state_is_final } from './jssm';
+     *
+     *  const final_test = sm`first -> second;`;
+     *
+     *  console.log( final_test.state_is_final('first') );   // false
+     *  console.log( final_test.state_is_final('second') );  // true
+     *  ```
+     *
+     */
     state_is_final(whichState: StateType): boolean;
+    /********
+     *
+     *  Check whether the current state is final (either has no exits or is marked
+     *  `complete`.)
+     *
+     *  ```typescript
+     *  import { sm, state_is_final } from './jssm';
+     *
+     *  const final_test = sm`first -> second;`;
+     *
+     *  console.log( final_test.is_final() );   // false
+     *  state.transition('second');
+     *  console.log( final_test.is_final() );   // true
+     *  ```
+     *
+     */
     is_final(): boolean;
     graph_layout(): string;
     dot_preamble(): string;

diff --git a/dist/es6/jssm.js b/dist/es6/jssm.js
@@ -643,6 +643,11 @@ class Machine {
             }
         });
     }
+    /********
+     *
+     *  Internal method for fabricating states.  Not meant for external use.
+     *
+     */
     _new_state(state_config) {
         if (this._states.has(state_config.name)) {
             throw new JssmError(this, `state ${JSON.stringify(state_config.name)} already exists`);
@@ -675,9 +680,40 @@ class Machine {
         return true; // todo whargarbl
       }
     */
+    /********
+     *
+     *  Check whether a given state is final (either has no exits or is marked
+     *  `complete`.)
+     *
+     *  ```typescript
+     *  import { sm, state_is_final } from './jssm';
+     *
+     *  const final_test = sm`first -> second;`;
+     *
+     *  console.log( final_test.state_is_final('first') );   // false
+     *  console.log( final_test.state_is_final('second') );  // true
+     *  ```
+     *
+     */
     state_is_final(whichState) {
         return ((this.state_is_terminal(whichState)) && (this.state_is_complete(whichState)));
     }
+    /********
+     *
+     *  Check whether the current state is final (either has no exits or is marked
+     *  `complete`.)
+     *
+     *  ```typescript
+     *  import { sm, state_is_final } from './jssm';
+     *
+     *  const final_test = sm`first -> second;`;
+     *
+     *  console.log( final_test.is_final() );   // false
+     *  state.transition('second');
+     *  console.log( final_test.is_final() );   // true
+     *  ```
+     *
+     */
     is_final() {
         //  return ((!this.is_changing()) && this.state_is_final(this.state()));
         return this.state_is_final(this.state());

diff --git a/dist/es6/version.js b/dist/es6/version.js
@@ -1,2 +1,2 @@
-const version = "5.65.8";
+const version = "5.65.9";
 export { version };
diff --git a/dist/jssm.es5.cjs.js b/dist/jssm.es5.cjs.js