jssm 5.65.9 → 5.65.12

package/jssm.d.ts

@@ -9,7 +9,7 @@ import { version } from './version';
  *  Return the direction of an arrow - `right`, `left`, or `both`.
  *
  *  ```typescript
- *  import { arrow_direction } from './jssm';
+ *  import { arrow_direction } from 'jssm';
  *
  *  arrow_direction('->');    // 'right'
  *  arrow_direction('<~=>');  // 'both'
@@ -22,7 +22,7 @@ declare function arrow_direction(arrow: JssmArrow): JssmArrowDirection;
  *  Return the direction of an arrow - `right`, `left`, or `both`.
  *
  *  ```typescript
- *  import { arrow_left_kind } from './jssm';
+ *  import { arrow_left_kind } from 'jssm';
  *
  *  arrow_left_kind('<-');    // 'legal'
  *  arrow_left_kind('<=');    // 'main'
@@ -38,7 +38,7 @@ declare function arrow_left_kind(arrow: JssmArrow): JssmArrowKind;
  *  Return the direction of an arrow - `right`, `left`, or `both`.
  *
  *  ```typescript
- *  import { arrow_left_kind } from './jssm';
+ *  import { arrow_left_kind } from 'jssm';
  *
  *  arrow_left_kind('->');    // 'legal'
  *  arrow_left_kind('=>');    // 'main'
@@ -60,7 +60,7 @@ declare function arrow_right_kind(arrow: JssmArrow): JssmArrowKind;
  *  probably also using {@link compile} and {@link Machine.constructor}.
  *
  *  ```typescript
- *  import { parse, compile, Machine } from './jssm';
+ *  import { parse, compile, Machine } from 'jssm';
  *
  *  const intermediate = wrap_parse('a -> b;', {});
  *  // [ {key:'transition', from:'a', se:{kind:'->',to:'b'}} ]
@@ -85,7 +85,7 @@ declare function arrow_right_kind(arrow: JssmArrow): JssmArrowKind;
  *  Operator {@link sm}:
  *
  *  ```typescript
- *  import { sm } from './jssm';
+ *  import { sm } from 'jssm';
  *
  *  const switch = sm`on <=> off;`;
  *  ```
@@ -93,7 +93,7 @@ declare function arrow_right_kind(arrow: JssmArrow): JssmArrowKind;
  *  Method {@link from}:
  *
  *  ```typescript
- *  import * as jssm from './jssm';
+ *  import * as jssm from 'jssm';
  *
  *  const toggle = jssm.from('up <=> down;');
  *  ```
@@ -111,7 +111,7 @@ declare function wrap_parse(input: string, options?: Object): any;
  *  {@link Machine.construct} to turn the config object into a workable machine.
  *
  *  ```typescript
- *  import { parse, compile, Machine } from './jssm';
+ *  import { parse, compile, Machine } from 'jssm';
  *
  *  const intermediate = parse('a -> b;');
  *  // [ {key:'transition', from:'a', se:{kind:'->',to:'b'}} ]
@@ -136,7 +136,7 @@ declare function wrap_parse(input: string, options?: Object): any;
  *  Operator {@link sm}:
  *
  *  ```typescript
- *  import { sm } from './jssm';
+ *  import { sm } from 'jssm';
  *
  *  const switch = sm`on <=> off;`;
  *  ```
@@ -144,7 +144,7 @@ declare function wrap_parse(input: string, options?: Object): any;
  *  Method {@link from}:
  *
  *  ```typescript
- *  import * as jssm from './jssm';
+ *  import * as jssm from 'jssm';
  *
  *  const toggle = jssm.from('up <=> down;');
  *  ```
@@ -224,7 +224,7 @@ declare class Machine<mDT> {
      *  Get the current state of a machine.
      *
      *  ```typescript
-     *  import * as jssm from './jssm';
+     *  import * as jssm from 'jssm';
      *
      *  const switch = jssm.from('on <=> off;');
      *  console.log( switch.state() );             // 'on'
@@ -241,7 +241,7 @@ declare class Machine<mDT> {
      *  `complete`.)
      *
      *  ```typescript
-     *  import { sm, state_is_final } from './jssm';
+     *  import { sm, state_is_final } from 'jssm';
      *
      *  const final_test = sm`first -> second;`;
      *
@@ -257,7 +257,7 @@ declare class Machine<mDT> {
      *  `complete`.)
      *
      *  ```typescript
-     *  import { sm, state_is_final } from './jssm';
+     *  import { sm, state_is_final } from 'jssm';
      *
      *  const final_test = sm`first -> second;`;
      *
@@ -289,7 +289,7 @@ declare class Machine<mDT> {
      *  these states is not guaranteed.
      *
      *  ```typescript
-     *  import * as jssm from './jssm';
+     *  import * as jssm from 'jssm';
      *
      *  const switch = jssm.from('on <=> off;');
      *  console.log( switch.states() );             // ['on', 'off']
@@ -303,16 +303,47 @@ declare class Machine<mDT> {
      *  Check whether the machine knows a given state.
      *
      *  ```typescript
-     *  import * as jssm from './jssm';
+     *  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;
+    /*********
+     *
+     *  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'
+     *    }
+     *  ]
+     *  ```
+     *
+     */
     list_edges(): Array<JssmTransition<mDT>>;
     list_named_transitions(): Map<StateType, number>;
     list_actions(): Array<StateType>;
@@ -320,14 +351,108 @@ declare class Machine<mDT> {
     flow(): FslDirection;
     get_transition_by_state_names(from: StateType, to: StateType): number;
     lookup_transition_for(from: StateType, to: StateType): JssmTransition<mDT>;
+    /********
+     *
+     *  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' ] }
+     *  ```
+     *
+     */
     list_transitions(whichState?: StateType): JssmTransitionList;
+    /********
+     *
+     *  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' ]
+     *  ```
+     *
+     */
     list_entrances(whichState?: StateType): Array<StateType>;
+    /********
+     *
+     *  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' ]
+     *  ```
+     *
+     */
     list_exits(whichState?: StateType): Array<StateType>;
     probable_exits_for(whichState: StateType): Array<JssmTransition<mDT>>;
     probabilistic_transition(): boolean;
     probabilistic_walk(n: number): Array<StateType>;
     probabilistic_histo_walk(n: number): Map<StateType, number>;
+    /********
+     *
+     *  List all actions available from this state.  Please note that the order of
+     *  the actions is not guaranteed.
+     *
+     *  ```typescript
+     *  import { sm } from 'jssm';
+     *
+     *  const machine = sm`
+     *    red 'next' -> green 'next' -> yellow 'next' -> red;
+     *    [red yellow green] 'shutdown' ~> off 'start' -> red;
+     *  `;
+     *
+     *  console.log( machine.state() );    // logs 'red'
+     *  console.log( machine.actions() );  // logs ['next', 'shutdown']
+     *
+     *  machine.action('next');            // true
+     *  console.log( machine.state() );    // logs 'green'
+     *  console.log( machine.actions() );  // logs ['next', 'shutdown']
+     *
+     *  machine.action('shutdown');        // true
+     *  console.log( machine.state() );    // logs 'off'
+     *  console.log( machine.actions() );  // logs ['start']
+     *
+     *  machine.action('start');           // true
+     *  console.log( machine.state() );    // logs 'red'
+     *  console.log( machine.actions() );  // logs ['next', 'shutdown']
+     *  ```
+     *
+     */
     actions(whichState?: StateType): Array<StateType>;
+    /********
+     *
+     *  List all states that have a specific action attached.  Please note that
+     *  the order of the states is not guaranteed.
+     *
+     *  ```typescript
+     *  import { sm } from 'jssm';
+     *
+     *  const machine = sm`
+     *    red 'next' -> green 'next' -> yellow 'next' -> red;
+     *    [red yellow green] 'shutdown' ~> off 'start' -> red;
+     *  `;
+     *
+     *  console.log( machine.list_states_having_action('next') );    // ['red', 'green', 'yellow']
+     *  console.log( machine.list_states_having_action('start') );   // ['off']
+     *  ```
+     *
+     */
     list_states_having_action(whichState: StateType): Array<StateType>;
     list_exit_actions(whichState?: StateType): Array<StateType>;
     probable_action_exits(whichState?: StateType): Array<any>;
@@ -352,8 +477,50 @@ declare class Machine<mDT> {
     hook_exit(from: string, handler: HookHandler): Machine<mDT>;
     edges_between(from: string, to: string): JssmTransition<mDT>[];
     transition_impl(newStateOrAction: StateType, newData: mDT | undefined, wasForced: boolean, wasAction: boolean): boolean;
+    /********
+     *
+     *  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'
+     *  ```
+     *
+     */
     action(actionName: StateType, newData?: mDT): boolean;
+    /********
+     *
+     *  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'
+     *  ```
+     *
+     */
     transition(newState: StateType, newData?: mDT): boolean;
+    /********
+     *
+     *  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'
+     *  ```
+     *
+     */
     force_transition(newState: StateType, newData?: mDT): boolean;
     current_action_for(action: StateType): number;
     current_action_edge_for(action: StateType): JssmTransition<mDT>;
@@ -374,7 +541,7 @@ declare class Machine<mDT> {
  *
  *
  *  ```typescript
- *  import * as jssm from './jssm';
+ *  import * as jssm from 'jssm';
  *
  *  const switch = jssm.from('on <=> off;');
  *  ```
@@ -391,7 +558,7 @@ declare function sm<mDT>(template_strings: TemplateStringsArray, ...remainder: a
  *  template expression.
  *
  *  ```typescript
- *  import * as jssm from './jssm';
+ *  import * as jssm from 'jssm';
  *
  *  const switch = jssm.from('on <=> off;');
  *  ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jssm",
-  "version": "5.65.9",
+  "version": "5.65.12",
   "engines": {
     "node": ">=10.0.0"
   },