jssm 5.65.3 → 5.65.7

package/dist/es6/jssm.d.ts

@@ -82,13 +82,15 @@ declare function arrow_right_kind(arrow: JssmArrow): JssmArrowKind;
  *  operator `sm`, and mostly falls back to `.from` when needing to parse
  *  strings dynamically instead of from template literals.
  *
+ *  Operator {@link sm}:
+ *
  *  ```typescript
  *  import { sm } from './jssm';
  *
  *  const switch = sm`on <=> off;`;
  *  ```
  *
- *  &hellip; or &hellip;
+ *  Method {@link from}:
  *
  *  ```typescript
  *  import * as jssm from './jssm';
@@ -131,13 +133,15 @@ declare function wrap_parse(input: string, options?: Object): any;
  *  operator `sm`, and mostly falls back to `.from` when needing to parse
  *  strings dynamically instead of from template literals.
  *
+ *  Operator {@link sm}:
+ *
  *  ```typescript
  *  import { sm } from './jssm';
  *
  *  const switch = sm`on <=> off;`;
  *  ```
  *
- *  &hellip; or &hellip;
+ *  Method {@link from}:
  *
  *  ```typescript
  *  import * as jssm from './jssm';
@@ -210,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;
@@ -228,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>;
@@ -281,6 +327,39 @@ declare class Machine<mDT> {
     instance_name(): string | undefined;
     sm(template_strings: TemplateStringsArray, ...remainder: any[]): Machine<mDT>;
 }
+/*********
+ *
+ *  Create a state machine from a template string.  This is one of the two main
+ *  paths for working with JSSM, alongside {@link from}.
+ *
+ *  Use this method when you want to work directly and conveniently with a
+ *  constant template expression.  Use `.from` when you want to pull from
+ *  dynamic strings.
+ *
+ *
+ *  ```typescript
+ *  import * as jssm from './jssm';
+ *
+ *  const switch = jssm.from('on <=> off;');
+ *  ```
+ *
+ */
 declare function sm<mDT>(template_strings: TemplateStringsArray, ...remainder: any[]): Machine<mDT>;
+/*********
+ *
+ *  Create a state machine from an implementation string.  This is one of the
+ *  two main paths for working with JSSM, alongside {@link sm}.
+ *
+ *  Use this method when you want to conveniently pull a state machine from a
+ *  string dynamically.  Use operator `sm` when you just want to work with a
+ *  template expression.
+ *
+ *  ```typescript
+ *  import * as jssm from './jssm';
+ *
+ *  const switch = jssm.from('on <=> off;');
+ *  ```
+ *
+ */
 declare function from<mDT>(MachineAsString: string, ExtraConstructorFields?: Partial<JssmGenericConfig<mDT>> | undefined): Machine<mDT>;
 export { version, transfer_state_properties, Machine, make, wrap_parse as parse, compile, sm, from, arrow_direction, arrow_left_kind, arrow_right_kind, seq, weighted_rand_select, histograph, weighted_sample_select, weighted_histo_key, shapes, gviz_shapes, named_colors };

package/dist/es6/jssm.js

@@ -253,13 +253,15 @@ function makeTransition(this_se, from, to, isRight, _wasList, _wasIndex) {
  *  operator `sm`, and mostly falls back to `.from` when needing to parse
  *  strings dynamically instead of from template literals.
  *
+ *  Operator {@link sm}:
+ *
  *  ```typescript
  *  import { sm } from './jssm';
  *
  *  const switch = sm`on <=> off;`;
  *  ```
  *
- *  &hellip; or &hellip;
+ *  Method {@link from}:
  *
  *  ```typescript
  *  import * as jssm from './jssm';
@@ -376,13 +378,15 @@ function compile_rule_handler(rule) {
  *  operator `sm`, and mostly falls back to `.from` when needing to parse
  *  strings dynamically instead of from template literals.
  *
+ *  Operator {@link sm}:
+ *
  *  ```typescript
  *  import { sm } from './jssm';
  *
  *  const switch = sm`on <=> off;`;
  *  ```
  *
- *  &hellip; or &hellip;
+ *  Method {@link from}:
  *
  *  ```typescript
  *  import * as jssm from './jssm';
@@ -646,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;
     }
@@ -723,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());
     }
@@ -735,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;
     }
@@ -1195,6 +1241,23 @@ class Machine {
         return sm(template_strings, ...remainder);
     }
 }
+/*********
+ *
+ *  Create a state machine from a template string.  This is one of the two main
+ *  paths for working with JSSM, alongside {@link from}.
+ *
+ *  Use this method when you want to work directly and conveniently with a
+ *  constant template expression.  Use `.from` when you want to pull from
+ *  dynamic strings.
+ *
+ *
+ *  ```typescript
+ *  import * as jssm from './jssm';
+ *
+ *  const switch = jssm.from('on <=> off;');
+ *  ```
+ *
+ */
 function sm(template_strings, ...remainder /* , arguments */) {
     // foo`a${1}b${2}c` will come in as (['a','b','c'],1,2)
     // this includes when a and c are empty strings
@@ -1208,6 +1271,22 @@ function sm(template_strings, ...remainder /* , arguments */) {
     /* eslint-enable  prefer-rest-params */
     )));
 }
+/*********
+ *
+ *  Create a state machine from an implementation string.  This is one of the
+ *  two main paths for working with JSSM, alongside {@link sm}.
+ *
+ *  Use this method when you want to conveniently pull a state machine from a
+ *  string dynamically.  Use operator `sm` when you just want to work with a
+ *  template expression.
+ *
+ *  ```typescript
+ *  import * as jssm from './jssm';
+ *
+ *  const switch = jssm.from('on <=> off;');
+ *  ```
+ *
+ */
 function from(MachineAsString, ExtraConstructorFields) {
     const to_decorate = make(MachineAsString);
     if (ExtraConstructorFields !== undefined) {

package/dist/es6/jssm_util.d.ts

@@ -1,10 +1,52 @@
+/*******
+ *
+ *  Predicate for validating an array for uniqueness.  Not generally meant for
+ *  external use.
+ *
+ */
 declare function arr_uniq_p<T>(el: T, i: number, source: T[]): boolean;
 declare const array_box_if_string: (n: any) => any;
 declare const weighted_rand_select: Function;
-declare const seq: Function;
+/*******
+ *
+ *  Returns, for a non-negative integer argument `n`, the series `[0 .. n]`.
+ *
+ *  ```typescript
+ *  import { seq } from './jssm';
+ *
+ *  seq(5);  // [0, 1, 2, 3, 4]
+ *  seq(0);  // []
+ *  ```
+ *
+ */
+declare function seq(n: number): number[];
+/*******
+ *
+ *  Returns the histograph of an array as a `Map`.  Makes no attempt to cope
+ *  with deep equality; will fail for complex contents, as such.
+ *
+ *  ```typescript
+ *  import { histograph } from './jssm';
+ *
+ *  histograph( [0, 0, 1, 1, 2, 2, 1] );  // Map()
+ *  ```
+ *
+ */
 declare const histograph: Function;
 declare const weighted_sample_select: Function;
 declare const weighted_histo_key: Function;
+/*******
+ *
+ *  Internal method generating names for edges for the hook lookup map.  Not
+ *  meant for external use.
+ *
+ */
 declare const hook_name: (from: string, to: string) => string;
+/*******
+ *
+ *  Internal method generating names for actions for the hook lookup map.  Not
+ *  meant for external use.
+ *
+ */
 declare const named_hook_name: (from: string, to: string, action: string) => string;
 export { seq, arr_uniq_p, histograph, weighted_histo_key, weighted_rand_select, weighted_sample_select, array_box_if_string, hook_name, named_hook_name };

package/dist/es6/jssm_util.js

@@ -1,3 +1,9 @@
+/*******
+ *
+ *  Predicate for validating an array for uniqueness.  Not generally meant for
+ *  external use.
+ *
+ */
 function arr_uniq_p(el, i, source) {
     return source.indexOf(el) === i;
 }
@@ -17,8 +23,41 @@ const weighted_rand_select = (options, probability_property = 'probability') =>
     return options[cursor - 1];
 };
 /* eslint-enable flowtype/no-weak-types */
-const seq = (n) => (new Array(n)).fill(true)
-    .map((_, i) => i);
+/*******
+ *
+ *  Returns, for a non-negative integer argument `n`, the series `[0 .. n]`.
+ *
+ *  ```typescript
+ *  import { seq } from './jssm';
+ *
+ *  seq(5);  // [0, 1, 2, 3, 4]
+ *  seq(0);  // []
+ *  ```
+ *
+ */
+function seq(n) {
+    if (!(Number.isInteger(n))) {
+        throw new TypeError('seq/1 takes a non-negative integer n as an argument');
+    }
+    if (n < 0) {
+        throw new TypeError('seq/1 takes a non-negative integer n as an argument');
+    }
+    return (new Array(n))
+        .fill(true)
+        .map((_, i) => i);
+}
+/*******
+ *
+ *  Returns the histograph of an array as a `Map`.  Makes no attempt to cope
+ *  with deep equality; will fail for complex contents, as such.
+ *
+ *  ```typescript
+ *  import { histograph } from './jssm';
+ *
+ *  histograph( [0, 0, 1, 1, 2, 2, 1] );  // Map()
+ *  ```
+ *
+ */
 const histograph = (ar) => // eslint-disable-line flowtype/no-weak-types
  ar.sort()
     .reduce((m, v) => // TODO FIXME eslint-disable-line flowtype/no-weak-types,no-sequences
@@ -31,6 +70,18 @@ const weighted_histo_key = (n, opts, prob_prop, extract) => // TODO FIXME no any
  histograph(weighted_sample_select(n, opts, prob_prop)
     .map((s) => s[extract] // TODO FIXME eslint-disable-line flowtype/no-weak-types
 ));
+/*******
+ *
+ *  Internal method generating names for edges for the hook lookup map.  Not
+ *  meant for external use.
+ *
+ */
 const hook_name = (from, to) => JSON.stringify([from, to]);
+/*******
+ *
+ *  Internal method generating names for actions for the hook lookup map.  Not
+ *  meant for external use.
+ *
+ */
 const named_hook_name = (from, to, action) => JSON.stringify([from, to, action]);
 export { seq, arr_uniq_p, histograph, weighted_histo_key, weighted_rand_select, weighted_sample_select, array_box_if_string, hook_name, named_hook_name };

package/dist/es6/version.js

@@ -1,2 +1,2 @@
-const version = "5.65.3";
+const version = "5.65.7";
 export { version };