Merge pull request #483 from StoneCypher/Doc_State_States_HasState

Document state, has_state, states; fixes StoneCypher/fsl#791, fixes StoneCypher/fsl#792, fixes StoneCypher/fsl#793
StoneCypher · May 22, 2022 · 7705f10 · 7705f10
2 parents d486935 + 7e3e2e9
commit 7705f10
Show file tree

Hide file tree

Showing 27 changed files with 3,965 additions and 82 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="chart1653235458057" width="16" height="9"></canvas>
+      <canvas id="chart1653236544747" width="16" height="9"></canvas>
     </div>
     <script>
       const format = (num) => {
@@ -51,18 +51,18 @@
           chunked.map((chunk) => chunk.join('')).join(' ') + fractionStr
         )
       }
-      const ctx1653235458057 = document
-        .getElementById('chart1653235458057')
+      const ctx1653236544747 = document
+        .getElementById('chart1653236544747')
         .getContext('2d')
-      const chart1653235458057 = new Chart(ctx1653235458057, {
+      const chart1653236544747 = new Chart(ctx1653236544747, {
         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: [5492,11313,1222,6423,5530,4964,4063,4762,5262,12195,4250,575,807,5073,8971,7494,8212,63872,64640,64562,8935],
-              backgroundColor: ["hsl(10.200000000000001, 85%, 55%)","hsl(21, 85%, 55%)","hsl(2.2680000000000007, 85%, 55%)","hsl(11.927999999999997, 85%, 55%)","hsl(10.272000000000002, 85%, 55%)","hsl(9.216000000000008, 85%, 55%)","hsl(7.548000000000008, 85%, 55%)","hsl(8.844000000000005, 85%, 55%)","hsl(9.768, 85%, 55%)","hsl(22.644000000000005, 85%, 55%)","hsl(7.8839999999999915, 85%, 55%)","hsl(1.0680000000000005, 85%, 55%)","hsl(1.5, 85%, 55%)","hsl(9.419999999999993, 85%, 55%)","hsl(16.655999999999995, 85%, 55%)","hsl(13.908000000000003, 85%, 55%)","hsl(15.240000000000004, 85%, 55%)","hsl(118.572, 85%, 55%)","hsl(120, 85%, 55%)","hsl(119.856, 85%, 55%)","hsl(16.583999999999993, 85%, 55%)"],
-              borderColor: ["hsl(10.200000000000001, 85%, 55%)","hsl(21, 85%, 55%)","hsl(2.2680000000000007, 85%, 55%)","hsl(11.927999999999997, 85%, 55%)","hsl(10.272000000000002, 85%, 55%)","hsl(9.216000000000008, 85%, 55%)","hsl(7.548000000000008, 85%, 55%)","hsl(8.844000000000005, 85%, 55%)","hsl(9.768, 85%, 55%)","hsl(22.644000000000005, 85%, 55%)","hsl(7.8839999999999915, 85%, 55%)","hsl(1.0680000000000005, 85%, 55%)","hsl(1.5, 85%, 55%)","hsl(9.419999999999993, 85%, 55%)","hsl(16.655999999999995, 85%, 55%)","hsl(13.908000000000003, 85%, 55%)","hsl(15.240000000000004, 85%, 55%)","hsl(118.572, 85%, 55%)","hsl(120, 85%, 55%)","hsl(119.856, 85%, 55%)","hsl(16.583999999999993, 85%, 55%)"],
+              data: [5405,13112,1380,6135,5525,5660,5558,5882,5622,22389,13100,1535,1357,10637,11091,9793,9527,65738,64235,65433,7893],
+              backgroundColor: ["hsl(9.863999999999999, 85%, 55%)","hsl(23.940000000000005, 85%, 55%)","hsl(2.519999999999993, 85%, 55%)","hsl(11.195999999999998, 85%, 55%)","hsl(10.080000000000007, 85%, 55%)","hsl(10.331999999999999, 85%, 55%)","hsl(10.140000000000004, 85%, 55%)","hsl(10.740000000000002, 85%, 55%)","hsl(10.259999999999996, 85%, 55%)","hsl(40.872, 85%, 55%)","hsl(23.916000000000007, 85%, 55%)","hsl(2.8080000000000043, 85%, 55%)","hsl(2.4720000000000026, 85%, 55%)","hsl(19.416000000000007, 85%, 55%)","hsl(20.244000000000007, 85%, 55%)","hsl(17.880000000000006, 85%, 55%)","hsl(17.387999999999995, 85%, 55%)","hsl(120, 85%, 55%)","hsl(117.252, 85%, 55%)","hsl(119.44800000000001, 85%, 55%)","hsl(14.412000000000006, 85%, 55%)"],
+              borderColor: ["hsl(9.863999999999999, 85%, 55%)","hsl(23.940000000000005, 85%, 55%)","hsl(2.519999999999993, 85%, 55%)","hsl(11.195999999999998, 85%, 55%)","hsl(10.080000000000007, 85%, 55%)","hsl(10.331999999999999, 85%, 55%)","hsl(10.140000000000004, 85%, 55%)","hsl(10.740000000000002, 85%, 55%)","hsl(10.259999999999996, 85%, 55%)","hsl(40.872, 85%, 55%)","hsl(23.916000000000007, 85%, 55%)","hsl(2.8080000000000043, 85%, 55%)","hsl(2.4720000000000026, 85%, 55%)","hsl(19.416000000000007, 85%, 55%)","hsl(20.244000000000007, 85%, 55%)","hsl(17.880000000000006, 85%, 55%)","hsl(17.387999999999995, 85%, 55%)","hsl(120, 85%, 55%)","hsl(117.252, 85%, 55%)","hsl(119.44800000000001, 85%, 55%)","hsl(14.412000000000006, 85%, 55%)"],
               borderWidth: 2,
             },
           ],

diff --git a/benchmark/results/general.json b/benchmark/results/general.json
@@ -1,141 +1,141 @@
 {
   "name": "General performance suite",
-  "date": "2022-05-22T16:04:18.057Z",
+  "date": "2022-05-22T16:22:24.747Z",
   "version": "1.2.0",
   "results": [
     {
       "name": "Blind cycle a traffic light 500 times by transition",
-      "ops": 5492,
-      "margin": 2.84,
-      "percentSlower": 91.5
+      "ops": 5405,
+      "margin": 2.32,
+      "percentSlower": 91.78
     },
     {
       "name": "Blind cycle a traffic light 500 times by action",
-      "ops": 11313,
-      "margin": 2.04,
-      "percentSlower": 82.5
+      "ops": 13112,
+      "margin": 2.17,
+      "percentSlower": 80.05
     },
     {
       "name": "Blind cycle a basic-hooked traffic light 500 times by transition",
-      "ops": 1222,
-      "margin": 2.74,
-      "percentSlower": 98.11
+      "ops": 1380,
+      "margin": 0.84,
+      "percentSlower": 97.9
     },
     {
       "name": "Blind cycle a named-hooked traffic light 500 times by transition",
-      "ops": 6423,
-      "margin": 1.37,
-      "percentSlower": 90.06
+      "ops": 6135,
+      "margin": 1.21,
+      "percentSlower": 90.67
     },
     {
       "name": "Blind cycle an any-transition traffic light 500 times by transition",
-      "ops": 5530,
-      "margin": 2.17,
-      "percentSlower": 91.44
+      "ops": 5525,
+      "margin": 4.11,
+      "percentSlower": 91.6
     },
     {
       "name": "Blind cycle an exit hooked traffic light 500 times by transition",
-      "ops": 4964,
-      "margin": 3.35,
-      "percentSlower": 92.32
+      "ops": 5660,
+      "margin": 1.37,
+      "percentSlower": 91.39
     },
     {
       "name": "Blind cycle an enter hooked traffic light 500 times by transition",
-      "ops": 4063,
-      "margin": 3.54,
-      "percentSlower": 93.71
+      "ops": 5558,
+      "margin": 1.31,
+      "percentSlower": 91.55
     },
     {
       "name": "Blind cycle a standard-transition hooked light by transition",
-      "ops": 4762,
-      "margin": 4.35,
-      "percentSlower": 92.63
+      "ops": 5882,
+      "margin": 2.09,
+      "percentSlower": 91.05
     },
     {
       "name": "Blind cycle a main-transition hooked light by transition",
-      "ops": 5262,
-      "margin": 2.9,
-      "percentSlower": 91.86
+      "ops": 5622,
+      "margin": 2.3,
+      "percentSlower": 91.45
     },
     {
       "name": "Blind cycle a force-transition hooked light by transition",
-      "ops": 12195,
-      "margin": 5.82,
-      "percentSlower": 81.13
+      "ops": 22389,
+      "margin": 1.63,
+      "percentSlower": 65.94
     },
     {
       "name": "Blind cycle a traffic light 500 times by action",
-      "ops": 4250,
-      "margin": 6.67,
-      "percentSlower": 93.43
+      "ops": 13100,
+      "margin": 3.85,
+      "percentSlower": 80.07
     },
     {
       "name": "Blind cycle a basic-hooked traffic light 500 times by action",
-      "ops": 575,
-      "margin": 6.62,
-      "percentSlower": 99.11
+      "ops": 1535,
+      "margin": 1.76,
+      "percentSlower": 97.66
     },
     {
       "name": "Blind cycle a named-hooked traffic light 500 times by action",
-      "ops": 807,
-      "margin": 6.19,
-      "percentSlower": 98.75
+      "ops": 1357,
+      "margin": 2.2,
+      "percentSlower": 97.94
     },
     {
       "name": "Blind cycle an any-action traffic light 500 times by action",
-      "ops": 5073,
-      "margin": 6.73,
-      "percentSlower": 92.15
+      "ops": 10637,
+      "margin": 2.14,
+      "percentSlower": 83.82
     },
     {
       "name": "Blind cycle a global-action traffic light 500 times by action",
-      "ops": 8971,
-      "margin": 2.65,
-      "percentSlower": 86.12
+      "ops": 11091,
+      "margin": 2.05,
+      "percentSlower": 83.13
     },
     {
       "name": "Blind cycle an exit hooked traffic light 500 times by action",
-      "ops": 7494,
-      "margin": 2.34,
-      "percentSlower": 88.41
+      "ops": 9793,
+      "margin": 1.54,
+      "percentSlower": 85.1
     },
     {
       "name": "Blind cycle an enter hooked traffic light 500 times by action",
-      "ops": 8212,
-      "margin": 2.56,
-      "percentSlower": 87.3
+      "ops": 9527,
+      "margin": 0.91,
+      "percentSlower": 85.51
     },
     {
       "name": "Blind cycle a standard transition tl 500 times by action",
-      "ops": 63872,
-      "margin": 0.72,
-      "percentSlower": 1.19
+      "ops": 65738,
+      "margin": 1.68,
+      "percentSlower": 0
     },
     {
       "name": "Blind cycle a main transition tl 500 times by action",
-      "ops": 64640,
-      "margin": 0.79,
-      "percentSlower": 0
+      "ops": 64235,
+      "margin": 2.76,
+      "percentSlower": 2.29
     },
     {
       "name": "Blind cycle a forced transition tl 500 times by action",
-      "ops": 64562,
-      "margin": 1.86,
-      "percentSlower": 0.12
+      "ops": 65433,
+      "margin": 1.54,
+      "percentSlower": 0.46
     },
     {
       "name": "Kitchen Sink 500 times",
-      "ops": 8935,
-      "margin": 3.77,
-      "percentSlower": 86.18
+      "ops": 7893,
+      "margin": 9.14,
+      "percentSlower": 87.99
     }
   ],
   "fastest": {
-    "name": "Blind cycle a main transition tl 500 times by action",
-    "index": 18
+    "name": "Blind cycle a standard transition tl 500 times by action",
+    "index": 17
   },
   "slowest": {
-    "name": "Blind cycle a basic-hooked traffic light 500 times by action",
-    "index": 11
+    "name": "Blind cycle a named-hooked traffic light 500 times by action",
+    "index": 12
   }
 }
diff --git a/dist/es6/jssm.d.ts b/dist/es6/jssm.d.ts
@@ -214,6 +214,21 @@ declare class Machine<mDT> {
     _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>);
     _new_state(state_config: JssmGenericState): StateType;
+    /*********
+     *
+     *  Get the current state of a machine.
+     *
+     *  ```typescript
+     *  import * as jssm from './jssm';
+     *
+     *  const switch = jssm.from('on <=> off;');
+     *  console.log( switch.state() );             // 'on'
+     *
+     *  switch.transition('off');
+     *  console.log( switch.state() );             // 'off'
+     *  ```
+     *
+     */
     state(): StateType;
     state_is_final(whichState: StateType): boolean;
     is_final(): boolean;
@@ -232,8 +247,35 @@ declare class Machine<mDT> {
     state_declarations(): Map<StateType, JssmStateDeclaration>;
     fsl_version(): string;
     machine_state(): JssmMachineInternalState<mDT>;
+    /*********
+     *
+     *  List all the states known by the machine.  Please note that the order of
+     *  these states is not guaranteed.
+     *
+     *  ```typescript
+     *  import * as jssm from './jssm';
+     *
+     *  const switch = jssm.from('on <=> off;');
+     *  console.log( switch.states() );             // ['on', 'off']
+     *  ```
+     *
+     */
     states(): Array<StateType>;
     state_for(whichState: StateType): JssmGenericState;
+    /*********
+     *
+     *  Check whether the machine knows a given state.
+     *
+     *  ```typescript
+     *  import * as jssm from './jssm';
+     *
+     *  const switch = jssm.from('on <=> off;');
+  
+     *  console.log( switch.has_state('off') );     // true
+     *  console.log( switch.has_state('dance') );   // false
+     *  ```
+     *
+     */
     has_state(whichState: StateType): boolean;
     list_edges(): Array<JssmTransition<mDT>>;
     list_named_transitions(): Map<StateType, number>;

diff --git a/dist/es6/jssm.js b/dist/es6/jssm.js
@@ -650,6 +650,21 @@ class Machine {
         this._states.set(state_config.name, state_config);
         return state_config.name;
     }
+    /*********
+     *
+     *  Get the current state of a machine.
+     *
+     *  ```typescript
+     *  import * as jssm from './jssm';
+     *
+     *  const switch = jssm.from('on <=> off;');
+     *  console.log( switch.state() );             // 'on'
+     *
+     *  switch.transition('off');
+     *  console.log( switch.state() );             // 'off'
+     *  ```
+     *
+     */
     state() {
         return this._state;
     }
@@ -727,6 +742,19 @@ class Machine {
         return false; // todo whargarbl
       }
     */
+    /*********
+     *
+     *  List all the states known by the machine.  Please note that the order of
+     *  these states is not guaranteed.
+     *
+     *  ```typescript
+     *  import * as jssm from './jssm';
+     *
+     *  const switch = jssm.from('on <=> off;');
+     *  console.log( switch.states() );             // ['on', 'off']
+     *  ```
+     *
+     */
     states() {
         return Array.from(this._states.keys());
     }
@@ -739,6 +767,20 @@ class Machine {
             throw new JssmError(this, 'No such state', { requested_state: whichState });
         }
     }
+    /*********
+     *
+     *  Check whether the machine knows a given state.
+     *
+     *  ```typescript
+     *  import * as jssm from './jssm';
+     *
+     *  const switch = jssm.from('on <=> off;');
+  
+     *  console.log( switch.has_state('off') );     // true
+     *  console.log( switch.has_state('dance') );   // false
+     *  ```
+     *
+     */
     has_state(whichState) {
         return this._states.get(whichState) !== undefined;
     }

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