jssm 5.65.10 → 5.66.0

package/CHANGELOG.md

@@ -1 +1,183 @@
+# Changelog
 
+All notable changes to this project will be documented in this file.
+
+873 merges; 70 releases; Changlogging the last 10 commits; Full changelog at [10](10)
+
+
+
+ 
+
+ 
+
+Published tags:
+
+<a href="#5__65__14">5.65.14</a>, <a href="#5__65__12">5.65.12</a>, <a href="#5__65__11">5.65.11</a>, <a href="#5__65__10">5.65.10</a>, <a href="#5__65__9">5.65.9</a>, <a href="#5__65__8">5.65.8</a>, <a href="#5__65__7">5.65.7</a>, <a href="#5__65__5">5.65.5</a>, <a href="#5__65__4">5.65.4</a>, <a href="#5__65__3">5.65.3</a>, <a href="#5__65__2">5.65.2</a>, <a href="#5__65__1">5.65.1</a>, <a href="#5__65__0">5.65.0</a>, <a href="#5__64__2">5.64.2</a>, <a href="#5__64__1">5.64.1</a>, <a href="#5__64__0">5.64.0</a>, <a href="#5__63__0">5.63.0</a>, <a href="#5__62__0">5.62.0</a>, <a href="#5__61__4">5.61.4</a>, <a href="#5__61__3">5.61.3</a>, <a href="#5__61__2">5.61.2</a>, <a href="#5__61__1">5.61.1</a>, <a href="#5__60__4">5.60.4</a>, <a href="#5__60__3">5.60.3</a>, <a href="#5__60__0">5.60.0</a>, <a href="#5__59__1">5.59.1</a>, <a href="#5__59__0">5.59.0</a>, <a href="#5__58__1">5.58.1</a>, <a href="#5__58__0">5.58.0</a>, <a href="#5__57__1">5.57.1</a>, <a href="#5__57__0">5.57.0</a>, <a href="#5__56__2">5.56.2</a>, <a href="#5__56__1">5.56.1</a>, <a href="#5__55__0">5.55.0</a>, <a href="#5__54__0">5.54.0</a>, <a href="#5__53__0">5.53.0</a>, <a href="#5__52__0">5.52.0</a>, <a href="#5__51__0">5.51.0</a>, <a href="#5__50__0">5.50.0</a>, <a href="#5__49__0">5.49.0</a>, <a href="#5__48__0">5.48.0</a>, <a href="#5__47__0">5.47.0</a>, <a href="#5__46__0">5.46.0</a>, <a href="#5__45__2">5.45.2</a>, <a href="#5__45__0">5.45.0</a>, <a href="#5__44__0">5.44.0</a>, <a href="#5__43__2">5.43.2</a>, <a href="#v5__42__0">v5.42.0</a>, <a href="#5__42__0">5.42.0</a>, <a href="#v5__41__15">v5.41.15</a>, <a href="#5__41__15">5.41.15</a>, <a href="#v5__41__14">v5.41.14</a>, <a href="#5__41__14">5.41.14</a>, <a href="#v5__41__12">v5.41.12</a>, <a href="#5__41__12">5.41.12</a>, <a href="#v5__41__10">v5.41.10</a>, <a href="#5__41__10">5.41.10</a>, <a href="#v5__41__9">v5.41.9</a>, <a href="#5__41__9">5.41.9</a>, <a href="#v5__41__8">v5.41.8</a>, <a href="#5__41__8">5.41.8</a>, <a href="#v5__41__7">v5.41.7</a>, <a href="#v5__41__2">v5.41.2</a>, <a href="#v5__41__1">v5.41.1</a>, <a href="#v5__32__14">v5.32.14</a>, <a href="#5__14__0">5.14.0</a>, <a href="#5__12__0">5.12.0</a>, <a href="#5__11__12">5.11.12</a>, <a href="#5__11__1">5.11.1</a>, <a href="#5__11__0">5.11.0</a>
+
+
+
+
+
+&nbsp;
+
+&nbsp;
+
+## [Untagged] - 6/6/2022 11:20:01 AM
+
+Commit [bcb1edaf59fbbd0a9fcfbb293d3ba1cfca129aa0](https://github.com/StoneCypher/jssm/commit/bcb1edaf59fbbd0a9fcfbb293d3ba1cfca129aa0)
+
+Author: `John Haugeland <stonecypher@gmail.com>`
+
+Merges [d19a094, 966e56b]
+
+  * Merge branch 'main' of github.com:StoneCypher/jssm
+
+
+
+
+&nbsp;
+
+&nbsp;
+
+## [Untagged] - 6/6/2022 11:19:47 AM
+
+Commit [d19a0949fdb44e76f946cf0f06020e9a497e8732](https://github.com/StoneCypher/jssm/commit/d19a0949fdb44e76f946cf0f06020e9a497e8732)
+
+Author: `John Haugeland <stonecypher@gmail.com>`
+
+  * Long and short changelogs to un-break GH releases
+
+
+
+
+&nbsp;
+
+&nbsp;
+
+## [Untagged] - 6/2/2022 7:14:41 PM
+
+Commit [966e56b5db15b792ee8efc648f76c279dd1c8b0c](https://github.com/StoneCypher/jssm/commit/966e56b5db15b792ee8efc648f76c279dd1c8b0c)
+
+Author: `John Haugeland <stonecypher@gmail.com>`
+
+  * Update README.md
+
+
+
+
+&nbsp;
+
+&nbsp;
+
+<a name="5__65__14" />
+
+## [5.65.14] - 5/25/2022 10:01:42 PM
+
+Commit [1c597f900bb8daa127d1ec490f1277db0dfc822e](https://github.com/StoneCypher/jssm/commit/1c597f900bb8daa127d1ec490f1277db0dfc822e)
+
+Author: `John Haugeland <stonecypher@gmail.com>`
+
+Merges [6a6f1c8, 4c2e830]
+
+  * Merge pull request #489 from StoneCypher/ImproveDocumentationLayout
+  * Improve documentation layout
+
+
+
+
+&nbsp;
+
+&nbsp;
+
+## [Untagged] - 5/25/2022 9:57:42 PM
+
+Commit [4c2e830a1a4cfc8f808a67a04cfb0efe7e6993c8](https://github.com/StoneCypher/jssm/commit/4c2e830a1a4cfc8f808a67a04cfb0efe7e6993c8)
+
+Author: `John Haugeland <stonecypher@gmail.com>`
+
+  * Needed version bump
+
+
+
+
+&nbsp;
+
+&nbsp;
+
+## [Untagged] - 5/25/2022 9:51:54 PM
+
+Commit [6353caf50948fc5985e1603fc06673add48bc376](https://github.com/StoneCypher/jssm/commit/6353caf50948fc5985e1603fc06673add48bc376)
+
+Author: `John Haugeland <stonecypher@gmail.com>`
+
+  * moar dox
+
+
+
+
+&nbsp;
+
+&nbsp;
+
+<a name="5__65__12" />
+
+## [5.65.12] - 5/22/2022 4:28:55 PM
+
+Commit [6a6f1c8a256f2f943c3230ec32dd32d2c2344927](https://github.com/StoneCypher/jssm/commit/6a6f1c8a256f2f943c3230ec32dd32d2c2344927)
+
+Author: `John Haugeland <stonecypher@gmail.com>`
+
+Merges [e084bf4, f0f3961]
+
+  * Merge pull request #488 from StoneCypher/Doc_Action_Transition_ForceTransition
+  * Document action, transition, force_transition; fixes StoneCypher/fsl#801, StoneCypher/fsl#802, StoneCypher/fsl#803
+
+
+
+
+&nbsp;
+
+&nbsp;
+
+## [Untagged] - 5/22/2022 4:24:24 PM
+
+Commit [f0f3961d25dc11cfb547eca55c7e3a65b9cf3ccf](https://github.com/StoneCypher/jssm/commit/f0f3961d25dc11cfb547eca55c7e3a65b9cf3ccf)
+
+Author: `John Haugeland <stonecypher@gmail.com>`
+
+  * Document action, transition, force_transition; fixes StoneCypher/fsl#801, StoneCypher/fsl#802, StoneCypher/fsl#803
+
+
+
+
+&nbsp;
+
+&nbsp;
+
+<a name="5__65__11" />
+
+## [5.65.11] - 5/22/2022 3:54:12 PM
+
+Commit [e084bf4a0936d419b5a9921e746a707644ad263f](https://github.com/StoneCypher/jssm/commit/e084bf4a0936d419b5a9921e746a707644ad263f)
+
+Author: `John Haugeland <stonecypher@gmail.com>`
+
+Merges [a7d9fba, b2558b2]
+
+  * Merge pull request #487 from StoneCypher/Doc_ListEdges_ListTransitions_ListEntrances_ListExits
+  * Doc list edges list transitions list entrances list exits
+
+
+
+
+&nbsp;
+
+&nbsp;
+
+## [Untagged] - 5/22/2022 3:44:19 PM
+
+Commit [b2558b2457dfaf6cb61782d0c758cf1ad043149b](https://github.com/StoneCypher/jssm/commit/b2558b2457dfaf6cb61782d0c758cf1ad043149b)
+
+Author: `John Haugeland <stonecypher@gmail.com>`
+
+  * Forgot to update benny labels

package/README.md

@@ -1009,6 +1009,8 @@ If you'd like to help, it's straightforward.
 
 ## Code and Language
 
+[Vat Raghavan](https://github.com/MachinShin) has participated extensively in language discussion and implemented several features.
+
 [Forest Belton](https://github.com/forestbelton) has provided guidance, bugfixes, parser and language commentary.
 
 [Jordan Harbrand](https://github.com/ljharb) suggested two interesting features and provided strong feedback on the initial tutorial draft.

package/dist/es6/jssm.d.ts

@@ -15,6 +15,8 @@ import { version } from './version';
  *  arrow_direction('<~=>');  // 'both'
  *  ```
  *
+ *  @param arrow The arrow to be evaluated
+ *
  */
 declare function arrow_direction(arrow: JssmArrow): JssmArrowDirection;
 /*********
@@ -31,6 +33,8 @@ declare function arrow_direction(arrow: JssmArrow): JssmArrowDirection;
  *  arrow_left_kind('->');    // 'none'
  *  ```
  *
+ *  @param arrow The arrow to be evaluated
+ *
  */
 declare function arrow_left_kind(arrow: JssmArrow): JssmArrowKind;
 /*********
@@ -47,6 +51,8 @@ declare function arrow_left_kind(arrow: JssmArrow): JssmArrowKind;
  *  arrow_left_kind('<-');    // 'none'
  *  ```
  *
+ *  @param arrow The arrow to be evaluated
+ *
  */
 declare function arrow_right_kind(arrow: JssmArrow): JssmArrowKind;
 /*********
@@ -101,6 +107,10 @@ declare function arrow_right_kind(arrow: JssmArrow): JssmArrowKind;
  *  `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
+ *
  */
 declare function wrap_parse(input: string, options?: Object): any;
 /*********
@@ -149,6 +159,10 @@ declare function wrap_parse(input: string, options?: Object): any;
  *  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
+ *
  */
 declare function compile<mDT>(tree: JssmParseTree): JssmGenericConfig<mDT>;
 /*********
@@ -157,6 +171,10 @@ declare function compile<mDT>(tree: JssmParseTree): JssmGenericConfig<mDT>;
  *  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
+ *
  */
 declare function make<mDT>(plan: string): JssmGenericConfig<mDT>;
 /*********
@@ -165,6 +183,8 @@ declare function make<mDT>(plan: string): JssmGenericConfig<mDT>;
  *  a single multi-faceted declaration, in the process of building a state.  Not
  *  generally meant for external use.
  *
+ *  @internal
+ *
  */
 declare function transfer_state_properties(state_decl: JssmStateDeclaration): JssmStateDeclaration;
 declare class Machine<mDT> {
@@ -217,6 +237,8 @@ declare class Machine<mDT> {
      *
      *  Internal method for fabricating states.  Not meant for external use.
      *
+     *  @internal
+     *
      */
     _new_state(state_config: JssmGenericState): StateType;
     /*********
@@ -233,6 +255,8 @@ declare class Machine<mDT> {
      *  console.log( switch.state() );             // 'off'
      *  ```
      *
+     *  @typeparam mDT The type of the machine data member; usually omitted
+     *
      */
     state(): StateType;
     /********
@@ -249,6 +273,10 @@ declare class Machine<mDT> {
      *  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: StateType): boolean;
     /********
@@ -266,6 +294,8 @@ declare class Machine<mDT> {
      *  console.log( final_test.is_final() );   // true
      *  ```
      *
+     *  @typeparam mDT The type of the machine data member; usually omitted
+     *
      */
     is_final(): boolean;
     graph_layout(): string;
@@ -295,6 +325,8 @@ declare class Machine<mDT> {
      *  console.log( switch.states() );             // ['on', 'off']
      *  ```
      *
+     *  @typeparam mDT The type of the machine data member; usually omitted
+     *
      */
     states(): Array<StateType>;
     state_for(whichState: StateType): JssmGenericState;
@@ -311,8 +343,45 @@ declare class Machine<mDT> {
      *  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: 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'
+     *    }
+     *  ]
+     *  ```
+     *
+     *  @typeparam mDT The type of the machine data member; usually omitted
+     *
+     */
     list_edges(): Array<JssmTransition<mDT>>;
     list_named_transitions(): Map<StateType, number>;
     list_actions(): Array<StateType>;
@@ -320,8 +389,66 @@ 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' ] }
+     *  ```
+     *
+     *  @typeparam mDT The type of the machine data member; usually omitted
+     *
+     *  @param whichState The state whose transitions to have listed
+     *
+     */
     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' ]
+     *  ```
+     *
+     *  @typeparam mDT The type of the machine data member; usually omitted
+     *
+     *  @param whichState The state whose entrances to have listed
+     *
+     */
     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' ]
+     *  ```
+     *
+     *  @typeparam mDT The type of the machine data member; usually omitted
+     *
+     *  @param whichState The state whose exits to have listed
+     *
+     */
     list_exits(whichState?: StateType): Array<StateType>;
     probable_exits_for(whichState: StateType): Array<JssmTransition<mDT>>;
     probabilistic_transition(): boolean;
@@ -356,6 +483,10 @@ declare class Machine<mDT> {
      *  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?: StateType): Array<StateType>;
     /********
@@ -375,6 +506,10 @@ declare class Machine<mDT> {
      *  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: StateType): Array<StateType>;
     list_exit_actions(whichState?: StateType): Array<StateType>;
@@ -400,8 +535,68 @@ 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'
+     *  ```
+     *
+     *  @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: 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'
+     *  ```
+     *
+     *  @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: 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'
+     *  ```
+     *
+     *  @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: StateType, newData?: mDT): boolean;
     current_action_for(action: StateType): number;
     current_action_edge_for(action: StateType): JssmTransition<mDT>;
@@ -427,6 +622,12 @@ declare class Machine<mDT> {
  *  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
+ *
  */
 declare function sm<mDT>(template_strings: TemplateStringsArray, ...remainder: any[]): Machine<mDT>;
 /*********
@@ -444,6 +645,12 @@ declare function sm<mDT>(template_strings: TemplateStringsArray, ...remainder: a
  *  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
+ *
  */
 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 };