state-machine-cat 10.1.1 → 10.1.3

package/src/options.mjs

@@ -1,3 +1,5 @@
+// @ts-check
+/** @type {import("../types/state-machine-cat").IAllowedValues} */
 const ALLOWED_VALUES = Object.freeze({
   inputType: {
     default: "smcat",
@@ -6,21 +8,22 @@ const ALLOWED_VALUES = Object.freeze({
   outputType: {
     default: "svg",
     values: [
-      { name: "svg" },
-      { name: "eps" },
-      { name: "ps" },
-      { name: "ps2" },
+      { name: "ast" },
       { name: "dot" },
-      { name: "smcat" },
+      { name: "eps" },
       { name: "json" },
-      { name: "ast" },
-      { name: "scxml" },
-      { name: "oldsvg" },
-      { name: "oldps2" },
       { name: "oldeps" },
-      { name: "scjson" },
+      { name: "oldps" },
+      { name: "oldps2" },
+      { name: "oldsvg" },
       { name: "pdf" },
       { name: "png" },
+      { name: "ps" },
+      { name: "ps2" },
+      { name: "scjson" },
+      { name: "scxml" },
+      { name: "smcat" },
+      { name: "svg" },
     ],
   },
   engine: {
@@ -53,15 +56,18 @@ const ALLOWED_VALUES = Object.freeze({
  * Returns the value for the option in the pOption object, and the default
  * for that option in all other cases
  *
- * @param {any} pOptions - the options as passed in the api `render` function
- * @param {string} pOptionName - the name of the option
- * @return {any} value
+ * @param {import("../types/state-machine-cat").IRenderOptions} pOptions - the options as passed in the api `render` function
+ * @param {keyof import("../types/state-machine-cat").IRenderOptions} pOptionName - the name of the option
+ * @return {string|boolean} value
  */
 function getOptionValue(pOptions, pOptionName) {
   // eslint-disable-next-line security/detect-object-injection
   return pOptions?.[pOptionName] ?? ALLOWED_VALUES[pOptionName].default;
 }
 
+/**
+ * @returns {import("../types/state-machine-cat").IAllowedValues}
+ */
 function getAllowedValues() {
   return ALLOWED_VALUES;
 }

package/src/parse/index.mjs

@@ -1,3 +1,4 @@
+// @ts-check
 import Ajv from "ajv";
 import options from "../options.mjs";
 import { parse as parseSmCat } from "./smcat/smcat-parser.mjs";
@@ -6,6 +7,11 @@ import $schema from "./smcat-ast.schema.mjs";
 
 const ajv = new Ajv();
 
+/**
+ * @param {typeof $schema} pSchema
+ * @param {any} pObject
+ * @throws {Error}
+ */
 function validateAgainstSchema(pSchema, pObject) {
   if (!ajv.validate(pSchema, pObject)) {
     throw new Error(
@@ -15,12 +21,18 @@ function validateAgainstSchema(pSchema, pObject) {
 }
 
 export default {
+  /**
+   * @param {string|import("../../types/state-machine-cat").IStateMachine} pScript
+   * @param {import("../../types/state-machine-cat").IRenderOptions} pOptions
+   * @returns {import("../../types/state-machine-cat").IStateMachine}
+   */
   getAST(pScript, pOptions) {
     let lReturnValue = pScript;
 
     if (options.getOptionValue(pOptions, "inputType") === "smcat") {
       lReturnValue = parseSmCat(pScript);
     } else if (options.getOptionValue(pOptions, "inputType") === "scxml") {
+      // @ts-expect-error inputType scxml => it's a string
       lReturnValue = parseSCXML(pScript);
     } else if (typeof pScript === "string") {
       // json
@@ -29,6 +41,7 @@ export default {
 
     validateAgainstSchema($schema, lReturnValue);
 
+    // @ts-expect-error by here lReturnValue is bound to be an IStateMachine
     return lReturnValue;
   },
 };

package/src/parse/parser-helpers.mjs

@@ -1,3 +1,4 @@
+// @ts-check
 /* eslint-disable security/detect-object-injection */
 import StateMachineModel from "../state-machine-model.mjs";
 
@@ -6,10 +7,20 @@ const TRIGGER_RE_AS_A_STRING =
 /* eslint security/detect-non-literal-regexp:0 */
 const TRIGGER_RE = new RegExp(TRIGGER_RE_AS_A_STRING);
 
+/**
+ * @param {string[]} pKnownStateNames
+ * @param {string} pName
+ * @returns {boolean}
+ */
 function stateExists(pKnownStateNames, pName) {
   return pKnownStateNames.includes(pName);
 }
-
+/**
+ * @type {{
+ *   re:RegExp;
+ *   stateType: import("../../types/state-machine-cat.js").StateType;
+ * }[]}
+ */
 const RE2STATE_TYPE = [
   {
     re: /initial/,
@@ -45,11 +56,19 @@ function matches(pName) {
   return (pEntry) => pEntry.re.test(pName);
 }
 
+/**
+ * @param {string} pName
+ * @returns {import("../../types/state-machine-cat.js").StateType}
+ */
 function getStateType(pName) {
   return (RE2STATE_TYPE.find(matches(pName)) || { stateType: "regular" })
     .stateType;
 }
 
+/**
+ * @param {string} pName
+ * @returns {import("../../types/state-machine-cat.js").IState}
+ */
 function initState(pName) {
   return {
     name: pName,
@@ -57,30 +76,45 @@ function initState(pName) {
   };
 }
 
+/**
+ * @param {import("../../types/state-machine-cat.js").IState} pState
+ * @returns {boolean}
+ */
 function isComposite(pState) {
   return Boolean(pState.statemachine);
 }
 
+/**
+ * @param {import("../../types/state-machine-cat.js").IStateMachine|undefined} pStateMachine
+ * @returns {string[]}
+ */
 function getAlreadyDeclaredStates(pStateMachine) {
-  const lStates = pStateMachine.states || [];
+  const lStates = pStateMachine?.states ?? [];
 
   return lStates.filter(isComposite).reduce(
     (pAllStateNames, pThisState) =>
       pAllStateNames.concat(getAlreadyDeclaredStates(pThisState.statemachine)),
-    lStates.map((pState) => pState.name)
+    lStates.map(({ name }) => name)
   );
 }
 
+/**
+ * @param {import("../../types/state-machine-cat.js").IStateMachine} pStateMachine
+ * @param {string[]} pKnownStateNames
+ * @returns {import("../../types/state-machine-cat.js").IState[]}
+ */
 function extractUndeclaredStates(pStateMachine, pKnownStateNames) {
   pKnownStateNames = pKnownStateNames
     ? pKnownStateNames
     : getAlreadyDeclaredStates(pStateMachine);
 
-  pStateMachine.states = pStateMachine.states || [];
-  const lTransitions = pStateMachine.transitions || [];
+  pStateMachine.states = pStateMachine?.states ?? [];
+  const lTransitions = pStateMachine?.transitions ?? [];
 
   pStateMachine.states.filter(isComposite).forEach((pState) => {
+    // @ts-expect-error isComposite guarantees the statemachine attribute exists, TS doesn't understand that yet, though
     pState.statemachine.states = extractUndeclaredStates(
+      // @ts-expect-error isComposite guarantees the statemachine attribute exists, TS doesn't understand that yet, though
       pState.statemachine,
       pKnownStateNames
     );
@@ -99,7 +133,13 @@ function extractUndeclaredStates(pStateMachine, pKnownStateNames) {
   return pStateMachine.states;
 }
 
+/**
+ * @param {number} pInComingCount
+ * @param {number} pOutGoingCount
+ * @returns {import("../../types/state-machine-cat.js").StateType}
+ */
 function classifyForkJoin(pInComingCount, pOutGoingCount) {
+  /** @type {import("../../types/state-machine-cat.js").StateType} */
   let lReturnValue = "junction";
 
   if (pInComingCount <= 1 && pOutGoingCount > 1) {
@@ -112,10 +152,16 @@ function classifyForkJoin(pInComingCount, pOutGoingCount) {
   return lReturnValue;
 }
 
+/**
+ * @param {import("../../types/state-machine-cat.js").IStateMachine} pStateMachine
+ * @param {StateMachineModel} pFlattenedStateMachineModel
+ * @returns {import("../../types/state-machine-cat.js").IStateMachine}
+ */
 function classifyForkJoins(
   pStateMachine,
   pFlattenedStateMachineModel = new StateMachineModel(pStateMachine)
 ) {
+  // TODO: mutates parameter
   pStateMachine.states = pStateMachine.states.map((pState) => {
     if (pState.type === "forkjoin" && !pState.typeExplicitlySet) {
       const lInComingCount = pFlattenedStateMachineModel.findTransitionsByTo(
@@ -139,6 +185,11 @@ function classifyForkJoins(
   return pStateMachine;
 }
 
+/**
+ * @param {import("../../types/state-machine-cat.js").IState} pStateOne
+ * @param {import("../../types/state-machine-cat.js").IState} pStateTwo
+ * @returns {boolean}
+ */
 function stateEqual(pStateOne, pStateTwo) {
   return pStateOne.name === pStateTwo.name;
 }
@@ -158,12 +209,17 @@ function uniq(pArray, pEqualFunction) {
   }, []);
 }
 
+/**
+ * @param {String} pString
+ * @returns {{event?: string; cond?: string; action?: string}}
+ */
 function parseTransitionExpression(pString) {
   // eslint-disable-next-line security/detect-unsafe-regex, unicorn/no-unsafe-regex
   const lTransitionExpressionRe = /([^[/]+)?(\[[^\]]+\])?[^/]*(\/.+)?/;
   const lReturnValue = {};
 
-  // match has no fallback because lTransitionExpressionRe will match
+  /** @type {RegExpMatchArray} */
+  // @ts-expect-error match has no fallback because lTransitionExpressionRe will match
   // any string (every part is optional)
   const lMatchResult = pString.match(lTransitionExpressionRe);
   const lEventPos = 1;
@@ -195,6 +251,10 @@ function setIfNotEmpty(pObject, pProperty, pValue) {
   setIf(pObject, pProperty, pValue, (pX) => pX && pX.length > 0);
 }
 
+/**
+ * @param {string} pActivityCandidate
+ * @returns {{type: string; body: string}}
+ */
 function extractAction(pActivityCandidate) {
   const lMatch = pActivityCandidate.match(TRIGGER_RE);
   const lTypePos = 1;
@@ -212,6 +272,10 @@ function extractAction(pActivityCandidate) {
   };
 }
 
+/**
+ * @param {string} pString
+ * @returns {{type: string; body: string}[]}
+ */
 function extractActions(pString) {
   return pString
     .split(/\n\s*/g)

package/src/parse/scxml/index.mjs

@@ -26,6 +26,11 @@ function extractActionsFromInvokes(pInvokeTriggers) {
   });
 }
 
+/**
+ * @param {import("./scxml").ISXCMLState} pState
+ * @returns {{type: string; body: string;}[]}
+ */
+
 function deriveActions(pState) {
   let lReturnValue = [];
 
@@ -43,11 +48,20 @@ function deriveActions(pState) {
   return lReturnValue;
 }
 
+/**
+ * @param {string} pType
+ * @param {import("./scxml").ISXCMLState} pState
+ * @returns {import("../../../types/state-machine-cat").StateType}
+ */
 function deriveStateType(pType, pState) {
   return pType === "history" && pState.type === "deep" ? "deephistory" : pType;
 }
 
 function mapState(pType) {
+  /**
+   * @param {import("./scxml").ISXCMLState} pState
+   * @return {import("../../../types/state-machine-cat").IState}
+   */
   return (pState) => {
     const lReturnValue = {
       name: pState.id,
@@ -73,6 +87,10 @@ function mapState(pType) {
   };
 }
 
+/**
+ * @param {import("./scxml").ISCXMLTransition} pTransition
+ * @returns {{event?: string; cond?: string; action?: string; type?: string;}}
+ */
 function extractTransitionAttributesFromObject(pTransition) {
   const lReturnValue = {};
 
@@ -95,6 +113,11 @@ function extractTransitionAttributesFromObject(pTransition) {
   return lReturnValue;
 }
 
+/**
+ *
+ * @param {import("./scxml").ISCXMLTransition} pTransition
+ * @returns {{action?: string; label?: string;event?: string; cond?: string; type?: string}}
+ */
 function extractTransitionAttributes(pTransition) {
   const lReturnValue = {};
 
@@ -120,7 +143,15 @@ function extractTransitionAttributes(pTransition) {
   return lReturnValue;
 }
 
+/**
+ * @param {import("./scxml").ISXCMLState} pState
+ */
 function reduceTransition(pState) {
+  /**
+   * @param {import("../../../types/state-machine-cat").ITransition[]} pAllTransitions
+   * @param {import("../../../types/state-machine-cat").ITransition} pTransition
+   * @returns {import("../../../types/state-machine-cat").ITransition}
+   */
   return (pAllTransitions, pTransition) => {
     // in SCXML spaces denote references to multiple states
     // => split into multiple transitions
@@ -139,6 +170,10 @@ function reduceTransition(pState) {
   };
 }
 
+/**
+ * @param {import("./scxml").ISXCMLState[]} pStates
+ * @returns {import("../../../types/state-machine-cat").ITransition[]}
+ */
 function extractTransitions(pStates) {
   return pStates
     .filter((pState) =>
@@ -156,6 +191,10 @@ function extractTransitions(pStates) {
     );
 }
 
+/**
+ * @param {import("./scxml").ISCXMLMachine} pMachine
+ * @returns {import("../../../types/state-machine-cat").IStateMachine}
+ */
 function mapMachine(pMachine) {
   const lMachine = normalizeMachine(pMachine);
   const lReturnValue = {};
@@ -181,7 +220,7 @@ function mapMachine(pMachine) {
  * Parses SCXML into a state machine AST.
  *
  * @param {string} pSCXMLString The SCXML to parse
- * @returns {IStateMachine} state machine AST
+ * @returns {import("../../../types/state-machine-cat").IStateMachine} state machine AST
  */
 export function parse(pSCXMLString) {
   const lSCXMLString = pSCXMLString.trim();

package/src/parse/scxml/normalize-machine.mjs

@@ -32,7 +32,7 @@ function normalizeInitial(pMachine) {
 
   if (pMachine.initial) {
     // => it's an xml node. This detection isn't fool proof...;
-    // if it's a node but it doesn't have a transtion (which
+    // if it's a node but it doesn't have a transition (which
     // looks like an odd corner case) we won't recognize the
     // initial
     // the initial.id shouldn't occur (not allowed in scxml

package/src/render/dot/attributebuilder.mjs

@@ -44,6 +44,13 @@ function toNameValueString(pAttribute) {
 }
 
 export default {
+  /**
+   *
+   * @param {string} pEngine
+   * @param {string} pDirection
+   * @param {*} pDotGraphAttributes
+   * @returns {string}
+   */
   buildGraphAttributes: (pEngine, pDirection, pDotGraphAttributes) =>
     GENERIC_GRAPH_ATTRIBUTES.concat(GRAPH_ATTRIBUTES[pEngine] || [])
       .concat(DIRECTION_ATTRIBUTES[pDirection] || [])

package/src/render/dot/counter.mjs

@@ -1,18 +1,31 @@
+// @ts-check
 export default class Counter {
   constructor() {
     this.reset();
   }
 
+  /**
+   * @returns {void}
+   */
   reset() {
     this.COUNTER = 0;
   }
 
+  /**
+   * @returns {number}
+   */
   next() {
+    // @ts-expect-error TS thinks COUNTER can possibly be null as it doesn't
+    // see that the function the constructor calls ensures it won't
     // eslint-disable-next-line no-plusplus
     return ++this.COUNTER;
   }
 
+  /**
+   * @returns {string}
+   */
   nextAsString() {
+    /** @type {number} */
     const lBase = 10;
 
     return this.next().toString(lBase);

package/src/render/dot/index.mjs

@@ -10,6 +10,10 @@ import utl from "./utl.mjs";
 
 let gCounter = {};
 
+/**
+ * @param {StateMachineModel} pStateMachineModel
+ * @returns {(pState: import("../../../types/state-machine-cat.js").IState) => import("../../../types/state-machine-cat.js").IState}
+ */
 function addExternalSelfTransitions(pStateMachineModel) {
   return (pState) => {
     if (Object.prototype.hasOwnProperty.call(pState, "statemachine")) {
@@ -21,6 +25,13 @@ function addExternalSelfTransitions(pStateMachineModel) {
   };
 }
 
+/**
+ * @param {import("../../../types/state-machine-cat.js").IState[]} pStates
+ * @param {string} pDirection
+ * @param {import("../../../types/state-machine-cat.js").dotAttributesType} pNodeAttributes
+ * @param {StateMachineModel} pStateMachineModel
+ * @returns {import("../../../types/state-machine-cat.js").IState[]}
+ */
 function transformStates(
   pStates,
   pDirection,
@@ -30,7 +41,11 @@ function transformStates(
   pStates
     .filter((pState) => pState.statemachine)
     .forEach((pState) => {
+      // @ts-expect-error - statemachine is _not_ potentially undefined, because of
+      // the filter
       pState.statemachine.states = transformStates(
+        // @ts-expect-error - statemachine is _not_ potentially undefined, because of
+        // the filter
         pState.statemachine.states,
         pDirection,
         pNodeAttributes,
@@ -51,30 +66,45 @@ function transformStates(
     .map(addExternalSelfTransitions(pStateMachineModel));
 }
 
-function splitStates(pAST) {
-  pAST.initialStates = pAST.states.filter(stateTransformers.isType("initial"));
-  pAST.regularStates = pAST.states.filter(
+/**
+ *
+ * @param {import("../../../types/state-machine-cat.js").IStateMachine} pStateMachine
+ * @returns {import("../../../types/state-machine-cat.js").IStateMachine}
+ */
+function splitStates(pStateMachine) {
+  pStateMachine.initialStates = pStateMachine.states.filter(
+    stateTransformers.isType("initial")
+  );
+  pStateMachine.regularStates = pStateMachine.states.filter(
     (pState) =>
       stateTransformers.isType("regular")(pState) && !pState.statemachine
   );
-  pAST.historyStates = pAST.states.filter(stateTransformers.isType("history"));
-  pAST.deepHistoryStates = pAST.states.filter(
+  pStateMachine.historyStates = pStateMachine.states.filter(
+    stateTransformers.isType("history")
+  );
+  pStateMachine.deepHistoryStates = pStateMachine.states.filter(
     stateTransformers.isType("deephistory")
   );
-  pAST.choiceStates = pAST.states.filter(stateTransformers.isType("choice"));
-  pAST.forkjoinStates = pAST.states.filter(
+  pStateMachine.choiceStates = pStateMachine.states.filter(
+    stateTransformers.isType("choice")
+  );
+  pStateMachine.forkjoinStates = pStateMachine.states.filter(
     stateTransformers.isOneOfTypes(["fork", "join", "forkjoin"])
   );
-  pAST.junctionStates = pAST.states.filter(
+  pStateMachine.junctionStates = pStateMachine.states.filter(
     stateTransformers.isType("junction")
   );
-  pAST.terminateStates = pAST.states.filter(
+  pStateMachine.terminateStates = pStateMachine.states.filter(
     stateTransformers.isType("terminate")
   );
-  pAST.finalStates = pAST.states.filter(stateTransformers.isType("final"));
-  pAST.compositeStates = pAST.states.filter((pState) => pState.statemachine);
+  pStateMachine.finalStates = pStateMachine.states.filter(
+    stateTransformers.isType("final")
+  );
+  pStateMachine.compositeStates = pStateMachine.states.filter(
+    (pState) => pState.statemachine
+  );
 
-  return pAST;
+  return pStateMachine;
 }
 
 function addEndTypes(pStateMachineModel) {
@@ -105,16 +135,23 @@ function addCompositeSelfFlag(pStateMachineModel) {
   };
 }
 
-function nameTransition(pTrans) {
-  pTrans.name = `tr_${pTrans.from}_${pTrans.to}_${gCounter.nextAsString()}`;
+function nameTransition(pTransition) {
+  pTransition.name = `tr_${pTransition.from}_${
+    pTransition.to
+  }_${gCounter.nextAsString()}`;
 
-  if (Boolean(pTrans.note)) {
-    pTrans.noteName = `note_${pTrans.name}`;
+  if (Boolean(pTransition.note)) {
+    pTransition.noteName = `note_${pTransition.name}`;
   }
 
-  return pTrans;
+  return pTransition;
 }
 
+/**
+ * @param {StateMachineModel} pStateMachineModel
+ * @param {string} pDirection
+ * @returns {import("../../../types/state-machine-cat.js").ITransition}
+ */
 function transformTransitions(pStateMachineModel, pDirection) {
   return pStateMachineModel.flattenedTransitions
     .map(nameTransition)
@@ -126,37 +163,38 @@ function transformTransitions(pStateMachineModel, pDirection) {
     .map(transitionTransformers.addPorts(pDirection));
 }
 
-export default (pAST, pOptions) => {
+/** @type {import("../../../types/state-machine-cat.js").StringRenderFunctionType} */
+export default (pStateMachine, pOptions) => {
   pOptions = pOptions || {};
   gCounter = new Counter();
 
-  let lAST = cloneDeep(pAST);
-  const lStateMachineModel = new StateMachineModel(lAST);
+  let lStateMachine = cloneDeep(pStateMachine);
+  const lStateMachineModel = new StateMachineModel(lStateMachine);
 
-  lAST.transitions = transformTransitions(
+  lStateMachine.transitions = transformTransitions(
     lStateMachineModel,
     pOptions.direction
   );
 
-  lAST.states = transformStates(
-    lAST.states,
+  lStateMachine.states = transformStates(
+    lStateMachine.states,
     pOptions.direction,
     pOptions.dotNodeAttrs,
     lStateMachineModel
   );
 
-  lAST = splitStates(lAST);
+  lStateMachine = splitStates(lStateMachine);
 
-  lAST.graphAttributes = attributebuilder.buildGraphAttributes(
+  lStateMachine.graphAttributes = attributebuilder.buildGraphAttributes(
     options.getOptionValue(pOptions, "engine"),
     options.getOptionValue(pOptions, "direction"),
     pOptions.dotGraphAttrs
   );
-  lAST.nodeAttributes = attributebuilder.buildNodeAttributes(
+  lStateMachine.nodeAttributes = attributebuilder.buildNodeAttributes(
     pOptions.dotNodeAttrs
   );
-  lAST.edgeAttributes = attributebuilder.buildEdgeAttributes(
+  lStateMachine.edgeAttributes = attributebuilder.buildEdgeAttributes(
     pOptions.dotEdgeAttrs
   );
-  return renderDotFromAST(lAST);
+  return renderDotFromAST(lStateMachine);
 };