jssm 5.65.10 → 5.66.0

package/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 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jssm",
-  "version": "5.65.10",
+  "version": "5.66.0",
   "engines": {
     "node": ">=10.0.0"
   },
@@ -44,16 +44,16 @@
     "audit": "text_audit -r -t major MAJOR wasteful WASTEFUL any mixed fixme FIXME checkme CHECKME testme TESTME stochable STOCHABLE todo TODO comeback COMEBACK whargarbl WHARGARBL -g ./src/ts/**/*.{js,ts}",
     "vet": "npm run eslint && npm run audit",
     "benny": "node ./src/buildjs/benchmark.js",
-    "build": "npm run vet && npm run test && npm run site && npm run docs && npm run benny",
-    "buildnb": "npm run vet && npm run test && npm run site && npm run docs",
+    "build": "npm run vet && npm run test && npm run site && npm run changelog && npm run docs && npm run benny",
+    "buildnb": "npm run vet && npm run test && npm run site && npm run changelog && npm run docs",
     "qbuild": "npm run test",
     "ci_build": "npm run vet && npm run test",
     "minify": "mv dist/es6/jssm-dot.js dist/es6/jssm-dot.nonmin.js && terser dist/es6/jssm-dot.nonmin.js > dist/es6/jssm-dot.js",
     "min_iife": "mv dist/jssm.es5.iife.js dist/jssm.es5.iife.nonmin.js && terser dist/jssm.es5.iife.nonmin.js > dist/jssm.es5.iife.js",
     "min_cjs": "mv dist/jssm.es5.cjs.js dist/jssm.es5.cjs.nonmin.js && terser dist/jssm.es5.cjs.nonmin.js > dist/jssm.es5.cjs.js",
     "site": "cp src/site/* docs/",
-    "docs": "typedoc src/ts/jssm.ts --out docs/docs --customCss ./src/site/typedoc-addon.css",
-    "changelog": "rm -f CHANGELOG.md && changelog-maker -a > CHANGELOG.md"
+    "docs": "typedoc src/ts/jssm.ts --options typedoc-options.js",
+    "changelog": "rm -f CHANGELOG.md && rm -f ./src/doc_md/CHANGELOG.md && better_git_changelog -b && cp CHANGELOG.* ./src/doc_md/"
   },
   "repository": {
     "type": "git",
@@ -96,6 +96,7 @@
   },
   "homepage": "https://stonecypher.github.io/jssm/",
   "devDependencies": {
+    "@knodes/typedoc-plugin-pages": "^0.22.5",
     "@rollup/plugin-commonjs": "^22.0.0",
     "@rollup/plugin-node-resolve": "^13.3.0",
     "@rollup/plugin-replace": "^4.0.0",
@@ -103,7 +104,6 @@
     "@typescript-eslint/eslint-plugin": "^4.13.0",
     "@typescript-eslint/parser": "^4.13.0",
     "benny": "^3.7.1",
-    "changelog-maker": "^2.3.2",
     "coveralls": "^3.0.11",
     "eslint": "^7.32.0",
     "eslint-plugin-fp": "^2.3.0",
@@ -120,11 +120,11 @@
     "terser": "^5.13.1",
     "text_audit": "^0.9.3",
     "ts-jest": "^27.0.7",
-    "tscheck": "^0.1.5",
     "typedoc": "^0.22.15",
     "typescript": "^4.6.4"
   },
   "dependencies": {
+    "better_git_changelog": "^1.6.0",
     "reduce-to-639-1": "^1.0.4"
   }
 }

package/typedoc-options.js

@@ -0,0 +1,50 @@
+module.exports = {
+  name: 'JSSM, a JavaScript state machine - the FSM for FSL',
+  readme: './src/doc_md/DocLandingPage.md',
+  out: 'docs/docs',
+  // entryPoints: [
+  //   'packages/*',
+  // ],
+  customCss: './src/site/typedoc-addon.css',
+  // entryPointStrategy: 'packages',
+  pluginPages: {
+    source: './src/doc_md/',
+    pages: [
+      { title: 'Tutorials', childrenDir: './', children: [
+        { title: 'Getting started',    source: 'GettingStarted.md' },
+        { title: 'Language reference', source: 'todo.md' },
+        { title: 'API reference',      source: 'todo.md' },
+        { title: 'Example machines',   source: 'todo.md' },
+        { title: 'Howtos and Recipes', source: 'todo.md' },
+      ] },
+      { title: 'Tools', childrenDir: './', children: [
+        { title: 'Live Editor',   source: 'todo.md' },
+        { title: 'Github Action', source: 'todo.md' }
+      ] },
+      { title: 'VIRTUAL', childrenDir: './', children: [
+        { title: 'Community', source: 'community.md' }
+      ] },
+      { title: 'VIRTUAL', childrenDir: './', children: [
+        { title: 'Changelog', source: 'CHANGELOG.md' }
+      ] },
+      // { title: 'VIRTUAL', childrenDir: '../', children: [
+      //   { title: 'Changelog', source: 'CHANGELOG.md' },
+      // ] },
+      // { title: '@knodes/typedoc-plugin-code-blocks', source: 'readme-extras.md', children: [
+      //   { title: 'Using options', source: 'options.md' },
+      // ] },
+      // { title: '@knodes/typedoc-plugin-monorepo-readmes', children: [
+      //   { title: 'Using options', source: 'options.md' },
+      // ] },
+      // { title: '@knodes/typedoc-plugin-pages', source: 'readme-extras.md', children: [
+      //   { title: 'Using options', source: 'options.md' },
+      //   { title: 'Pages tree', source: 'pages-tree.md' },
+      // ] },
+      // { title: '@knodes/typedoc-pluginutils', children: [
+      //   { title: 'Providing options', source: 'providing-options.md' },
+      // ] },
+    ]
+  },
+  // pluginCodeBlocks: { source: '__tests__/mock-fs' },
+  excludePrivate: true
+};