jssm 5.65.8 → 5.65.11

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;');
  *  ```
@@ -213,13 +213,18 @@ 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;
     /*********
      *
      *  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'
@@ -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;
@@ -253,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']
@@ -267,16 +303,45 @@ 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
+     *  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>;
@@ -284,14 +349,99 @@ 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.
+     *
+     *  const lswitch = sm`on 'toggle' <=> 'toggle' off;`;
+     *  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.
+     *
+     *  const lswitch = sm`on 'toggle' <=> 'toggle' off;`;
+     *  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.
+     *
+     *  const lswitch = sm`on 'toggle' <=> 'toggle' off;`;
+     *  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>;
@@ -338,7 +488,7 @@ declare class Machine<mDT> {
  *
  *
  *  ```typescript
- *  import * as jssm from './jssm';
+ *  import * as jssm from 'jssm';
  *
  *  const switch = jssm.from('on <=> off;');
  *  ```
@@ -355,7 +505,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.8",
+  "version": "5.65.11",
   "engines": {
     "node": ">=10.0.0"
   },