jssm 5.65.10 → 5.66.0

package/dist/es6/jssm.js

@@ -17,6 +17,8 @@ import { JssmError } from './jssm_error';
  *  arrow_direction('<~=>');  // 'both'
  *  ```
  *
+ *  @param arrow The arrow to be evaluated
+ *
  */
 function arrow_direction(arrow) {
     switch (String(arrow)) {
@@ -85,6 +87,8 @@ function arrow_direction(arrow) {
  *  arrow_left_kind('->');    // 'none'
  *  ```
  *
+ *  @param arrow The arrow to be evaluated
+ *
  */
 function arrow_left_kind(arrow) {
     switch (String(arrow)) {
@@ -142,6 +146,8 @@ function arrow_left_kind(arrow) {
  *  arrow_left_kind('<-');    // 'none'
  *  ```
  *
+ *  @param arrow The arrow to be evaluated
+ *
  */
 function arrow_right_kind(arrow) {
     switch (String(arrow)) {
@@ -189,7 +195,12 @@ function arrow_right_kind(arrow) {
  *  Internal method meant to perform factory assembly of an edge.  Not meant for
  *  external use.
  *
+ *  @internal
+ *
+ *  @typeparam mDT The type of the machine data member; usually omitted
+ *
  */
+// TODO add at-param to docblock
 function makeTransition(this_se, from, to, isRight, _wasList, _wasIndex) {
     const kind = isRight ? arrow_right_kind(this_se.kind) : arrow_left_kind(this_se.kind), edge = {
         from,
@@ -272,6 +283,10 @@ function makeTransition(this_se, from, to, isRight, _wasList, _wasIndex) {
  *  `wrap_parse` itself is an internal convenience method for alting out an
  *  object as the options call.  Not generally meant for external use.
  *
+ *  @param input The FSL code to be evaluated
+ *
+ *  @param options Things to control about the instance
+ *
  */
 function wrap_parse(input, options) {
     return parse(input, options || {});
@@ -281,6 +296,10 @@ function wrap_parse(input, options) {
  *  Internal method performing one step in compiling rules for transitions.  Not
  *  generally meant for external use.
  *
+ *  @internal
+ *
+ *  @typeparam mDT The type of the machine data member; usually omitted
+ *
  */
 function compile_rule_transition_step(acc, from, to, this_se, next_se) {
     const edges = [];
@@ -310,6 +329,8 @@ function compile_rule_transition_step(acc, from, to, this_se, next_se) {
  *  Internal method performing one step in compiling rules for transitions.  Not
  *  generally meant for external use.
  *
+ *  @internal
+ *
  */
 function compile_rule_handle_transition(rule) {
     return compile_rule_transition_step([], rule.from, rule.se.to, rule.se, rule.se.se);
@@ -319,6 +340,8 @@ function compile_rule_handle_transition(rule) {
  *  Internal method performing one step in compiling rules for transitions.  Not
  *  generally meant for external use.
  *
+ *  @internal
+ *
  */
 function compile_rule_handler(rule) {
     if (rule.key === 'transition') {
@@ -394,6 +417,10 @@ function compile_rule_handler(rule) {
  *  const toggle = jssm.from('up <=> down;');
  *  ```
  *
+ *  @typeparam mDT The type of the machine data member; usually omitted
+ *
+ *  @param tree The parse tree to be boiled down into a machine config
+ *
  */
 function compile(tree) {
     const results = {
@@ -458,6 +485,10 @@ function compile(tree) {
  *  Not generally meant for external use.  Please see {@link compile} or
  *  {@link sm}.
  *
+ *  @typeparam mDT The type of the machine data member; usually omitted
+ *
+ *  @param plan The FSL code to be evaluated and built into a machine config
+ *
  */
 function make(plan) {
     return compile(wrap_parse(plan));
@@ -468,6 +499,8 @@ function make(plan) {
  *  a single multi-faceted declaration, in the process of building a state.  Not
  *  generally meant for external use.
  *
+ *  @internal
+ *
  */
 function transfer_state_properties(state_decl) {
     state_decl.declarations.map((d) => {
@@ -498,6 +531,7 @@ function transfer_state_properties(state_decl) {
     });
     return state_decl;
 }
+// TODO add a lotta docblock here
 class Machine {
     // whargarbl this badly needs to be broken up, monolith master
     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 = undefined, arrange_declaration = [], arrange_start_declaration = [], arrange_end_declaration = [], theme = 'default', flow = 'down', graph_layout = 'dot', instance_name }) {
@@ -647,6 +681,8 @@ class Machine {
      *
      *  Internal method for fabricating states.  Not meant for external use.
      *
+     *  @internal
+     *
      */
     _new_state(state_config) {
         if (this._states.has(state_config.name)) {
@@ -669,6 +705,8 @@ class Machine {
      *  console.log( switch.state() );             // 'off'
      *  ```
      *
+     *  @typeparam mDT The type of the machine data member; usually omitted
+     *
      */
     state() {
         return this._state;
@@ -694,6 +732,10 @@ class Machine {
      *  console.log( final_test.state_is_final('second') );  // true
      *  ```
      *
+     *  @typeparam mDT The type of the machine data member; usually omitted
+     *
+     *  @param whichState The name of the state to check for finality
+     *
      */
     state_is_final(whichState) {
         return ((this.state_is_terminal(whichState)) && (this.state_is_complete(whichState)));
@@ -713,6 +755,8 @@ class Machine {
      *  console.log( final_test.is_final() );   // true
      *  ```
      *
+     *  @typeparam mDT The type of the machine data member; usually omitted
+     *
      */
     is_final() {
         //  return ((!this.is_changing()) && this.state_is_final(this.state()));
@@ -790,6 +834,8 @@ class Machine {
      *  console.log( switch.states() );             // ['on', 'off']
      *  ```
      *
+     *  @typeparam mDT The type of the machine data member; usually omitted
+     *
      */
     states() {
         return Array.from(this._states.keys());
@@ -816,10 +862,47 @@ class Machine {
      *  console.log( switch.has_state('dance') );   // false
      *  ```
      *
+     *  @typeparam mDT The type of the machine data member; usually omitted
+     *
+     *  @param whichState The state to be checked for extance
+     *
      */
     has_state(whichState) {
         return this._states.get(whichState) !== undefined;
     }
+    /*********
+     *
+     *  Lists all edges of a machine.
+     *
+     *  ```typescript
+     *  import { sm } from 'jssm';
+     *
+     *  const lswitch = sm`on 'toggle' <=> 'toggle' off;`;
+     *
+     *  lswitch.list_edges();
+     *  [
+     *    {
+     *      from: 'on',
+     *      to: 'off',
+     *      kind: 'main',
+     *      forced_only: false,
+     *      main_path: true,
+     *      action: 'toggle'
+     *    },
+     *    {
+     *      from: 'off',
+     *      to: 'on',
+     *      kind: 'main',
+     *      forced_only: false,
+     *      main_path: true,
+     *      action: 'toggle'
+     *    }
+     *  ]
+     *  ```
+     *
+     *  @typeparam mDT The type of the machine data member; usually omitted
+     *
+     */
     list_edges() {
         return this._edges;
     }
@@ -848,14 +931,72 @@ class Machine {
         const id = this.get_transition_by_state_names(from, to);
         return ((id === undefined) || (id === null)) ? undefined : this._edges[id];
     }
+    /********
+     *
+     *  List all transitions attached to the current state, sorted by entrance and
+     *  exit.  The order of each sublist is not defined.  A node could appear in
+     *  both lists.
+     *
+     *  ```typescript
+     *  import { sm } from 'jssm';
+     *
+     *  const light = sm`red 'next' -> green 'next' -> yellow 'next' -> red; [red yellow green] 'shutdown' ~> off 'start' -> red;`;
+     *
+     *  light.state();               // 'red'
+     *  light.list_transitions();    // { entrances: [ 'yellow', 'off' ], exits: [ 'green', 'off' ] }
+     *  ```
+     *
+     *  @typeparam mDT The type of the machine data member; usually omitted
+     *
+     *  @param whichState The state whose transitions to have listed
+     *
+     */
     list_transitions(whichState = this.state()) {
         return { entrances: this.list_entrances(whichState), exits: this.list_exits(whichState) };
     }
+    /********
+     *
+     *  List all entrances attached to the current state.  Please note that the
+     *  order of the list is not defined.
+     *
+     *  ```typescript
+     *  import { sm } from 'jssm';
+     *
+     *  const light = sm`red 'next' -> green 'next' -> yellow 'next' -> red; [red yellow green] 'shutdown' ~> off 'start' -> red;`;
+     *
+     *  light.state();               // 'red'
+     *  light.list_entrances();      // [ 'yellow', 'off' ]
+     *  ```
+     *
+     *  @typeparam mDT The type of the machine data member; usually omitted
+     *
+     *  @param whichState The state whose entrances to have listed
+     *
+     */
     list_entrances(whichState = this.state()) {
         return (this._states.get(whichState)
             || { from: undefined }).from
             || [];
     }
+    /********
+     *
+     *  List all exits attached to the current state.  Please note that the order
+     *  of the list is not defined.
+     *
+     *  ```typescript
+     *  import { sm } from 'jssm';
+     *
+     *  const light = sm`red 'next' -> green 'next' -> yellow 'next' -> red; [red yellow green] 'shutdown' ~> off 'start' -> red;`;
+     *
+     *  light.state();               // 'red'
+     *  light.list_exits();          // [ 'green', 'off' ]
+     *  ```
+     *
+     *  @typeparam mDT The type of the machine data member; usually omitted
+     *
+     *  @param whichState The state whose exits to have listed
+     *
+     */
     list_exits(whichState = this.state()) {
         return (this._states.get(whichState)
             || { to: undefined }).to
@@ -916,6 +1057,10 @@ class Machine {
      *  console.log( machine.actions() );  // logs ['next', 'shutdown']
      *  ```
      *
+     *  @typeparam mDT The type of the machine data member; usually omitted
+     *
+     *  @param whichState The state whose actions to have listed
+     *
      */
     actions(whichState = this.state()) {
         const wstate = this._reverse_actions.get(whichState);
@@ -943,6 +1088,10 @@ class Machine {
      *  console.log( machine.list_states_having_action('start') );   // ['off']
      *  ```
      *
+     *  @typeparam mDT The type of the machine data member; usually omitted
+     *
+     *  @param whichState The action to be checked for associated states
+     *
      */
     list_states_having_action(whichState) {
         const wstate = this._actions.get(whichState);
@@ -1271,13 +1420,72 @@ class Machine {
             return false;
         }
     }
+    /********
+     *
+     *  Instruct the machine to complete an action.
+     *
+     *  ```typescript
+     *  const light = sm`red 'next' -> green 'next' -> yellow 'next' -> red; [red yellow green] 'shutdown' ~> off 'start' -> red;`;
+     *
+     *  light.state();               // 'red'
+     *  light.action('next');        // true
+     *  light.state();               // 'green'
+     *  ```
+     *
+     *  @typeparam mDT The type of the machine data member; usually omitted
+     *
+     *  @param actionName The action to engage
+     *
+     *  @param newData The data change to insert during the action
+     *
+     */
     action(actionName, newData) {
         return this.transition_impl(actionName, newData, false, true);
     }
+    /********
+     *
+     *  Instruct the machine to complete a transition.
+     *
+     *  ```typescript
+     *  const light = sm`red -> green -> yellow -> red; [red yellow green] 'shutdown' ~> off 'start' -> red;`;
+     *
+     *  light.state();               // 'red'
+     *  light.transition('green');   // true
+     *  light.state();               // 'green'
+     *  ```
+     *
+     *  @typeparam mDT The type of the machine data member; usually omitted
+     *
+     *  @param newState The state to switch to
+     *
+     *  @param newData The data change to insert during the transition
+     *
+     */
     transition(newState, newData) {
         return this.transition_impl(newState, newData, false, false);
     }
-    // can leave machine in inconsistent state.  generally do not use
+    /********
+     *
+     *  Instruct the machine to complete a forced transition (which will reject if
+     *  called with a normal {@link transition} call.)
+     *
+     *  ```typescript
+     *  const light = sm`red -> green -> yellow -> red; [red yellow green] 'shutdown' ~> off 'start' -> red;`;
+     *
+     *  light.state();                     // 'red'
+     *  light.transition('off');           // false
+     *  light.state();                     // 'red'
+     *  light.force_transition('off');     // true
+     *  light.state();                     // 'off'
+     *  ```
+     *
+     *  @typeparam mDT The type of the machine data member; usually omitted
+     *
+     *  @param newState The state to switch to
+     *
+     *  @param newData The data change to insert during the transition
+     *
+     */
     force_transition(newState, newData) {
         return this.transition_impl(newState, newData, true, false);
     }
@@ -1341,6 +1549,12 @@ class Machine {
  *  const switch = jssm.from('on <=> off;');
  *  ```
  *
+ *  @typeparam mDT The type of the machine data member; usually omitted
+ *
+ *  @param template_strings The assembled code
+ *
+ *  @param remainder The mechanic for template argument insertion
+ *
  */
 function sm(template_strings, ...remainder /* , arguments */) {
     // foo`a${1}b${2}c` will come in as (['a','b','c'],1,2)
@@ -1370,6 +1584,12 @@ function sm(template_strings, ...remainder /* , arguments */) {
  *  const switch = jssm.from('on <=> off;');
  *  ```
  *
+ *  @typeparam mDT The type of the machine data member; usually omitted
+ *
+ *  @param MachineAsString The FSL code to evaluate
+ *
+ *  @param ExtraConstructorFields Extra non-code configuration to pass at creation time
+ *
  */
 function from(MachineAsString, ExtraConstructorFields) {
     const to_decorate = make(MachineAsString);

package/dist/es6/version.js

@@ -1,2 +1,2 @@
-const version = "5.65.10";
+const version = "5.66.0";
 export { version };