state-machine-cat 10.1.2 → 10.1.5

package/src/state-machine-model.mjs

@@ -1,3 +1,9 @@
+// @ts-check
+/**
+ * @param {import("../types/state-machine-cat").IState[]} pStates
+ * @param {boolean} pHasParent
+ * @returns {any} // IFlattenedState  - a state, but flattened (statemachine is a boolean, the new attr hasParent as well)
+ */
 function flattenStates(pStates, pHasParent = false) {
   let lReturnValue = [];
 
@@ -6,6 +12,8 @@ function flattenStates(pStates, pHasParent = false) {
     .forEach((pState) => {
       if (Object.prototype.hasOwnProperty.call(pState.statemachine, "states")) {
         lReturnValue = lReturnValue.concat(
+          // @ts-expect-error TS doesn't detect that after the call in the filter
+          // the .statemachine is guaranteed to exist
           flattenStates(pState.statemachine.states, true)
         );
       }
@@ -21,10 +29,17 @@ function flattenStates(pStates, pHasParent = false) {
   );
 }
 
+/**
+ * @param {import("../types/state-machine-cat").IStateMachine} pStateMachine
+ * @returns {import("../types/state-machine-cat").ITransition[]}
+ */
 function flattenTransitions(pStateMachine) {
+  /** @type {import("../types/state-machine-cat").ITransition[]} */
   let lTransitions = [];
 
   if (Object.prototype.hasOwnProperty.call(pStateMachine, "transitions")) {
+    // @ts-expect-error TS doesn't detect that after the call in the if the
+    // .transitions is guaranteed to exist
     lTransitions = pStateMachine.transitions;
   }
   if (Object.prototype.hasOwnProperty.call(pStateMachine, "states")) {
@@ -32,6 +47,8 @@ function flattenTransitions(pStateMachine) {
       .filter((pState) => Boolean(pState.statemachine))
       .forEach((pState) => {
         lTransitions = lTransitions.concat(
+          // @ts-expect-error TS doesn't detect that after the call in the filter
+          // the .statemachine is guaranteed to exist
           flattenTransitions(pState.statemachine)
         );
       });
@@ -40,25 +57,42 @@ function flattenTransitions(pStateMachine) {
 }
 
 export default class StateMachineModel {
-  constructor(pAST) {
-    this._flattenedStates = flattenStates(pAST.states || []);
-    this._flattenedTransitions = flattenTransitions(pAST);
+  /**
+   * @param {import("../types/state-machine-cat").IStateMachine} pStateMachine
+   */
+  constructor(pStateMachine) {
+    this._flattenedStates = flattenStates(pStateMachine.states || []);
+    this._flattenedTransitions = flattenTransitions(pStateMachine);
   }
-
+  /**
+   * @returns {import("../types/state-machine-cat").ITransition[]}
+   */
   get flattenedTransitions() {
     return this._flattenedTransitions;
   }
 
+  /**
+   * @param {string} pName
+   * @returns {any} // IFlattenedState
+   */
   findStateByName(pName) {
     return this._flattenedStates.find((pState) => pState.name === pName);
   }
 
+  /**
+   * @param {import("../types/state-machine-cat").StateType[]} pTypes
+   * @returns {any} // IFlattenedState
+   */
   findStatesByTypes(pTypes) {
     return this._flattenedStates.filter((pState) =>
       pTypes.includes(pState.type)
     );
   }
 
+  /**
+   * @param {string} pStateName
+   * @returns {import("../types/state-machine-cat").ITransition[]}
+   */
   findExternalSelfTransitions(pStateName) {
     return this._flattenedTransitions.filter(
       (pTransition) =>
@@ -68,12 +102,20 @@ export default class StateMachineModel {
     );
   }
 
+  /**
+   * @param {string} pFromStateName
+   * @returns {import("../types/state-machine-cat").ITransition[]}
+   */
   findTransitionsByFrom(pFromStateName) {
     return this._flattenedTransitions.filter(
       (pTransition) => pTransition.from === pFromStateName
     );
   }
 
+  /**
+   * @param {string} pToStateName
+   * @returns {import("../types/state-machine-cat").ITransition[]}
+   */
   findTransitionsByTo(pToStateName) {
     return this._flattenedTransitions.filter(
       (pTransition) => pTransition.to === pToStateName

package/src/transform/desugar.mjs

@@ -1,14 +1,31 @@
+// @ts-check
 /* eslint-disable security/detect-object-injection */
 import cloneDeep from "lodash/cloneDeep.js";
 import reject from "lodash/reject.js";
 import StateMachineModel from "../state-machine-model.mjs";
 import utl from "./utl.mjs";
 
+/**
+ * @typedef {{[stateName: string]: import("../../types/state-machine-cat.js").ITransition[]}} ITransitionMap
+ */
+
+/**
+ * @param {string|undefined} pIncomingThing
+ * @param {string} pOutgoingThing
+ * @param {string} pJoinChar
+ * @returns {string}
+ */
 function fuseTransitionAttribute(pIncomingThing, pOutgoingThing, pJoinChar) {
   return pIncomingThing
     ? `${pIncomingThing}${pJoinChar}${pOutgoingThing}`
     : pOutgoingThing;
 }
+
+/**
+ * @param {import("../../types/state-machine-cat.js").ITransition} pIncomingTransition
+ * @param {import("../../types/state-machine-cat.js").ITransition} pOutgoingTransition
+ * @returns {import("../../types/state-machine-cat.js").ITransition}
+ */
 function fuseIncomingToOutgoing(pIncomingTransition, pOutgoingTransition) {
   // in:
   // a => ]: event [condition]/ action;
@@ -19,6 +36,7 @@ function fuseIncomingToOutgoing(pIncomingTransition, pOutgoingTransition) {
   //
   // events and conditions are illegal on transitions outgoing
   // from forks, so we ignore them
+  /** @type {import("../../types/state-machine-cat.js").ITransition} */
   const lReturnValue = {
     ...pIncomingTransition,
     ...pOutgoingTransition,
@@ -44,27 +62,50 @@ function fuseIncomingToOutgoing(pIncomingTransition, pOutgoingTransition) {
   return lReturnValue;
 }
 
+/**
+ * @param {import("../../types/state-machine-cat.js").ITransition[]} pTransitions
+ * @param {string[]} pPseudoStateNames
+ * @param {ITransitionMap} pOutgoingTransitionMap
+ * @returns {import("../../types/state-machine-cat.js").ITransition[]}
+ */
 function fuseTransitions(
   pTransitions,
   pPseudoStateNames,
   pOutgoingTransitionMap
 ) {
-  return pTransitions.reduce((pAll, pTransition) => {
-    pPseudoStateNames.forEach((pStateName, pIndex) => {
-      if (pStateName === pTransition.to && pOutgoingTransitionMap[pStateName]) {
-        pAll = pAll.concat(
-          pOutgoingTransitionMap[pStateName].map((pOutgoingTransition) =>
-            fuseIncomingToOutgoing(pTransition, pOutgoingTransition)
-          )
-        );
-      } else {
-        pAll = pIndex === 0 ? pAll.concat(pTransition) : pAll;
-      }
-    });
-    return pAll;
-  }, []);
+  return pTransitions.reduce(
+    /**
+     * @param {import("../../types/state-machine-cat.js").ITransition[]} pAll
+     * @param {import("../../types/state-machine-cat.js").ITransition} pTransition
+     * @returns {import("../../types/state-machine-cat.js").ITransition[]}
+     */
+    (pAll, pTransition) => {
+      pPseudoStateNames.forEach((pStateName, pIndex) => {
+        if (
+          pStateName === pTransition.to &&
+          pOutgoingTransitionMap[pStateName]
+        ) {
+          pAll = pAll.concat(
+            pOutgoingTransitionMap[pStateName].map((pOutgoingTransition) =>
+              fuseIncomingToOutgoing(pTransition, pOutgoingTransition)
+            )
+          );
+        } else {
+          pAll = pIndex === 0 ? pAll.concat(pTransition) : pAll;
+        }
+      });
+      return pAll;
+    },
+    []
+  );
 }
 
+/**
+ * @param {import("../../types/state-machine-cat.js").IStateMachine} pMachine
+ * @param {string[]} pPseudoStateNames
+ * @param {ITransitionMap} pOutgoingTransitionMap
+ * @returns {import("../../types/state-machine-cat.js").IStateMachine}
+ */
 function deSugarPseudoStates(
   pMachine,
   pPseudoStateNames,
@@ -96,6 +137,11 @@ function deSugarPseudoStates(
   return lMachine;
 }
 
+/**
+ * @param {import("../../types/state-machine-cat.js").IStateMachine} pMachine
+ * @param {string[]} pStateNames
+ * @returns {import("../../types/state-machine-cat.js").IStateMachine}
+ */
 function removeStatesCascading(pMachine, pStateNames) {
   const lMachine = cloneDeep(pMachine);
 
@@ -142,19 +188,22 @@ function removeStatesCascading(pMachine, pStateNames) {
  * b => d;
  * ```
  *
- * @param {IStateMachine} pMachine The state machine still containing forks
- * @param {StateType[]} pDesugarableStates array of de-sugarable states
- * @returns {IStateMachine}        the transformed state machine
+ * @param {import("../../types/state-machine-cat.js").IStateMachine} pMachine The state machine still containing forks
+ * @param {import("../../types/state-machine-cat.js").StateType[]} pDesugarableStates array of de-sugarable states
+ * @returns {import("../../types/state-machine-cat.js").IStateMachine} the transformed state machine
  */
 export default (
   pMachine,
   pDesugarableStates = ["fork", "junction", "choice"]
 ) => {
   const lModel = new StateMachineModel(pMachine);
+
+  /** @type {string[]} */
   const lPseudoStateNames = lModel
     .findStatesByTypes(pDesugarableStates)
-    .map((pState) => pState.name);
+    .map(({ name }) => name);
 
+  /** @type {ITransitionMap} */
   const lOutgoingTransitionMap = lPseudoStateNames.reduce(
     (pAll, pStateName) => {
       pAll[pStateName] = lModel.findTransitionsByFrom(pStateName);

package/src/transform/utl.mjs

@@ -1,3 +1,11 @@
+// @ts-check
+/**
+ *
+ * @param {string} [pEvent]
+ * @param {string} [pCond]
+ * @param {string} [pActions]
+ * @returns {string}
+ */
 function formatLabel(pEvent, pCond, pActions) {
   let lReturnValue = "";
 

package/src/version.mjs

@@ -1,2 +1,2 @@
 // generated by tools/get-version.mjs - edits will be overwritten
-export const version = "10.1.2";
+export const version = "10.1.5";

package/types/state-machine-cat.d.ts

@@ -183,13 +183,22 @@ export function getAllowedValues(): IAllowedValues;
 export type InputType = "smcat" | "json" | "scxml";
 
 export type OutputType =
-  | "smcat"
+  | "ast"
   | "dot"
+  | "eps"
   | "json"
-  | "ast"
-  | "svg"
+  | "oldeps"
+  | "oldps"
+  | "oldps2"
+  | "oldsvg"
+  | "pdf"
+  | "png"
+  | "ps"
+  | "ps2"
   | "scjson"
-  | "scxml";
+  | "scxml"
+  | "smcat"
+  | "svg";
 
 export type EngineType = "dot" | "circo" | "fdp" | "neato" | "osage" | "twopi";
 
@@ -204,7 +213,7 @@ export type dotAttributesType = {
   value: string;
 }[];
 
-export interface IRenderOptions {
+export interface IBaseRenderOptions {
   /**
    * How to interpret the input (defaults to 'smcat')
    */
@@ -222,6 +231,17 @@ export interface IRenderOptions {
    * (defaults to 'top-down')
    */
   direction?: DirectionType;
+  /**
+   * If true state machine cat will replace 'sugar' pseudo states
+   * (choice, forks and junctions) with their equivalent meaning
+   * (defaults to false).
+   *
+   * For details: https://github.com/sverweij/state-machine-cat/blob/master/docs/desugar.md
+   */
+  desugar?: boolean;
+}
+
+export interface IRenderOptions extends IBaseRenderOptions {
   /**
    * For the 'dot' renderer: Graph attributes to the engine
    */
@@ -234,18 +254,25 @@ export interface IRenderOptions {
    * For the 'dot' renderer: Edge attributes to the engine
    */
   dotEdgeAttrs?: dotAttributesType;
-  /**
-   * If true state machine cat will replace 'sugar' pseudo states
-   * (choice, forks and junctions) with their equivalent meaning
-   * (defaults to false).
-   *
-   * For details: https://github.com/sverweij/state-machine-cat/blob/master/docs/desugar.md
-   */
-  desugar?: boolean;
 }
 
+export type StringRenderFunctionType = (
+  pScript: IStateMachine,
+  pOptions: IRenderOptions
+) => string;
+
+export type WhateverRenderFunctionType = (
+  pScript: IStateMachine,
+  pOptions: IRenderOptions
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+) => any;
+
+export type RenderFunctionType =
+  | StringRenderFunctionType
+  | WhateverRenderFunctionType;
+
 /**
- * Translates the input script to an outputscript.
+ * Translates the input script to an output script.
  *
  * @param pScript     The script to translate
  * @param pOptions    options influencing parsing & rendering.