state-machine-cat 10.1.2 → 10.1.5

package/src/render/dot/README.md

@@ -0,0 +1,12 @@
+## Why does this renderer use `#FFFFFF01` instead of `transparent` for transparency?
+
+Typically you'll use the `dot` output to translate it to scalable vector graphics
+(svg) with GraphViz. In svg `transparent` isn't a color, though (see issue [#129](https://github.com/sverweij/state-machine-cat/issues/129)).
+In web browsers this isn't a problem, but less lenient svg interpreters will
+render it as black instead. This is suboptimal.
+
+The obvious alternative is to use `#FFFFFF00` (as svg does allow RGBA), however
+GraphViz translates this into `transparent` nonetheless. So to hack around this
+the dot renderer uses `01` in the alpha channel in stead (`#FFFFFF01`). GrapViz
+nicely translates this to `fill="#ffffff" fill-opacity="0.004"` which is sufficiently
+transparent for all practical purposes.

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);
 };

package/src/render/dot/render-dot-from-ast.js

@@ -1,3 +1,4 @@
+/** @type {any} - the Handlebars delivered types don't seem to cover everythint in handlebars ...*/
 const Handlebars = require("handlebars/dist/handlebars.runtime.js");
 // eslint-disable-next-line import/no-unassigned-import
 require("./dot.template.js");
@@ -15,34 +16,55 @@ Handlebars.registerHelper("stateSection", (pStateMachine) =>
 );
 
 // TODO: duplicate from the one in state-transformers.js
+/**
+ *
+ * @param {string} pString
+ * @returns {(pState: import("../../../types/state-machine-cat.js").IState) => Boolean}
+ */
 function isType(pString) {
   return (pState) => pState.type === pString;
 }
+/**
+ *
+ * @param {string[]} pStringArray
+ * @returns {(pState: import("../../../types/state-machine-cat.js").IState) => Boolean}
+ */
 // TODO: duplicate from the one in state-transformers.js
 function isOneOfTypes(pStringArray) {
   return (pState) => pStringArray.includes(pState.type);
 }
 
 // TODO: duplicate from the one in index.js
-function splitStates(pAST) {
-  pAST.initialStates = pAST.states.filter(isType("initial"));
-  pAST.regularStates = pAST.states.filter(
+function splitStates(pStateMachine) {
+  pStateMachine.initialStates = pStateMachine.states.filter(isType("initial"));
+  pStateMachine.regularStates = pStateMachine.states.filter(
     (pState) => isType("regular")(pState) && !pState.statemachine
   );
-  pAST.historyStates = pAST.states.filter(isType("history"));
-  pAST.deepHistoryStates = pAST.states.filter(isType("deephistory"));
-  pAST.choiceStates = pAST.states.filter(isType("choice"));
-  pAST.forkjoinStates = pAST.states.filter(
+  pStateMachine.historyStates = pStateMachine.states.filter(isType("history"));
+  pStateMachine.deepHistoryStates = pStateMachine.states.filter(
+    isType("deephistory")
+  );
+  pStateMachine.choiceStates = pStateMachine.states.filter(isType("choice"));
+  pStateMachine.forkjoinStates = pStateMachine.states.filter(
     isOneOfTypes(["fork", "join", "forkjoin"])
   );
-  pAST.junctionStates = pAST.states.filter(isType("junction"));
-  pAST.terminateStates = pAST.states.filter(isType("terminate"));
-  pAST.finalStates = pAST.states.filter(isType("final"));
-  pAST.compositeStates = pAST.states.filter((pState) => pState.statemachine);
+  pStateMachine.junctionStates = pStateMachine.states.filter(
+    isType("junction")
+  );
+  pStateMachine.terminateStates = pStateMachine.states.filter(
+    isType("terminate")
+  );
+  pStateMachine.finalStates = pStateMachine.states.filter(isType("final"));
+  pStateMachine.compositeStates = pStateMachine.states.filter(
+    (pState) => pState.statemachine
+  );
 
-  return pAST;
+  return pStateMachine;
 }
-
-module.exports = function renderDotFromAST(pAST) {
-  return Handlebars.templates["dot.template.hbs"](pAST);
+/**
+ * @param {import("../../../types/state-machine-cat.js").IStateMachine} pStateMachine
+ * @returns {string}
+ */
+module.exports = function renderDotFromAST(pStateMachine) {
+  return Handlebars.templates["dot.template.hbs"](pStateMachine);
 };

package/src/render/dot/state-transformers.mjs

@@ -1,3 +1,4 @@
+import cloneDeep from "lodash/cloneDeep.js";
 import utl from "./utl.mjs";
 
 function isType(pString) {
@@ -8,8 +9,9 @@ function isOneOfTypes(pStringArray) {
 }
 
 function setLabel(pState) {
-  pState.label = pState.label || pState.name;
-  return pState;
+  const lState = cloneDeep(pState);
+  lState.label = pState.label || pState.name;
+  return lState;
 }
 
 function nameNote(pState) {

package/src/render/dot/utl.mjs

@@ -1,3 +1,9 @@
+// @ts-check
+
+/**
+ * @param {string} pString
+ * @returns {string}
+ */
 function escapeString(pString) {
   return pString
     .replace(/\\/g, "\\\\")
@@ -6,6 +12,10 @@ function escapeString(pString) {
     .concat("\\l");
 }
 
+/**
+ * @param {string} pString
+ * @returns {string}
+ */
 function escapeLabelString(pString) {
   return pString
     .replace(/\\/g, "\\\\")
@@ -14,12 +24,22 @@ function escapeLabelString(pString) {
     .concat("   \\l");
 }
 
+/**
+ * @param {string} pDirection
+ * @returns {boolean}
+ */
 function isVertical(pDirection) {
   const lDirection = pDirection || "top-down";
 
   return lDirection === "top-down" || lDirection === "bottom-top";
 }
 
+/**
+ *
+ * @param {import("../../state-machine-model.mjs").default} pStateMachineModel
+ * @param {import("../../../types/state-machine-cat").ITransition} pTransition
+ * @returns {boolean}
+ */
 function isCompositeSelf(pStateMachineModel, pTransition) {
   return (
     pTransition.from === pTransition.to &&

package/src/render/index-node.mjs

@@ -1,3 +1,4 @@
+// @ts-check
 /* eslint-disable security/detect-object-injection */
 import has from "lodash/has.js";
 import smcat from "./smcat/index.js";
@@ -7,8 +8,13 @@ import oldVector from "./vector/vector-with-viz-js.mjs";
 import scjson from "./scjson/index.mjs";
 import scxml from "./scxml/index.mjs";
 
+/**
+ *
+ * @param {import("../../types/state-machine-cat.js").OutputType} pOutputType
+ * @returns {import("../../types/state-machine-cat.js").RenderFunctionType}
+ */
 export default function getRenderFunction(pOutputType) {
-  const lOutputtype2Renderfunction = {
+  const lOutputType2RenderFunction = {
     smcat,
     dot,
     svg: vector,
@@ -24,7 +30,7 @@ export default function getRenderFunction(pOutputType) {
     scxml,
   };
 
-  return has(lOutputtype2Renderfunction, pOutputType)
-    ? lOutputtype2Renderfunction[pOutputType]
+  return has(lOutputType2RenderFunction, pOutputType)
+    ? lOutputType2RenderFunction[pOutputType]
     : (pX) => pX;
 }

package/src/render/index.mjs

@@ -7,7 +7,7 @@ import scjson from "./scjson/index.mjs";
 import scxml from "./scxml/index.mjs";
 
 export default function getRenderFunction(pOutputType) {
-  const lOutputtype2Renderfunction = {
+  const lOutputType2RenderFunction = {
     smcat,
     dot,
     svg,
@@ -16,7 +16,7 @@ export default function getRenderFunction(pOutputType) {
     scxml,
   };
 
-  return has(lOutputtype2Renderfunction, pOutputType)
-    ? lOutputtype2Renderfunction[pOutputType]
+  return has(lOutputType2RenderFunction, pOutputType)
+    ? lOutputType2RenderFunction[pOutputType]
     : (pX) => pX;
 }

package/src/render/scjson/index.mjs

@@ -137,6 +137,12 @@ function findInitialStateName(pStateMachine, pInitialPseudoStateName) {
   return lReturnValue;
 }
 
+/**
+ * @param {import("../../..").IStateMachine} pStateMachine
+ * @param {import("../../..").IRenderOptions} [_pOptions]
+ * @param {import("../../..").ITransition[]} [pTransitions] (no need to specify - used in recursion)
+ * @returns {any} TODO: scjson data structure
+ */
 export default function render(pStateMachine, _pOptions, pTransitions) {
   const lInitialPseudoStateName = findInitialPseudoStateName(pStateMachine);
   const lInitialStateName = findInitialStateName(

package/src/render/scjson/make-valid-xml-name.mjs

@@ -1,3 +1,4 @@
+// @ts-check
 /*
  * In the XML spec we read: https://www.w3.org/TR/xml/#NT-Name:
  *
@@ -18,6 +19,11 @@ const NAME_CHAR_FORBIDDEN_RE =
 const START_NAME_CHAR_FORBIDDEN_EXTRA_RE =
   /[-|.|0-9|\u00B7|\u0300-\u036F|\u203F-\u2040]/g;
 
+/**
+ *
+ * @param {string} pCandidateNameTail
+ * @returns {string}
+ */
 function makeValidNameChars(pCandidateNameTail) {
   return pCandidateNameTail.replace(NAME_CHAR_FORBIDDEN_RE, "_");
 }
@@ -25,7 +31,7 @@ function makeValidNameChars(pCandidateNameTail) {
 /**
  * if it's an invalid NameStartChar but a valid NameChar smack a '_' in front of it
  * if it's an invalid NameChar as well - run it through the makeValidNameChars replacer
- * @param {char} pCandidateChar - start char
+ * @param {string} pCandidateChar - start char
  * @returns {string} valid start string
  */
 function makeValidNameStartChar(pCandidateChar) {

package/src/render/scxml/index.mjs

@@ -1,6 +1,8 @@
+// @ts-check
 import ast2scjson from "../scjson/index.mjs";
 import renderFomSCJSON from "./render-from-scjson.js";
 
+/** @type {import("../../..").StringRenderFunctionType} */
 export default function renderSCXML(pStateMachine) {
   return renderFomSCJSON(ast2scjson(pStateMachine));
 }

package/src/render/smcat/index.js

@@ -1,13 +1,25 @@
+// @ts-check
+/** @type {any} - the type definitions for Handlebars don't match what we're actually using - hence this override*/
 const Handlebars = require("handlebars/dist/handlebars.runtime.js");
 const cloneDeep = require("lodash/cloneDeep.js");
 
 // eslint-disable-next-line import/no-unassigned-import
 require("./smcat.template.js");
 
+/**
+ * @typedef {{hasExtendedAttributes?: boolean} & import("../../../types/state-machine-cat.js").IState} IExtendedState
+ * @typedef {{actions: string;} & Omit<IExtendedState, "actions">} IFlattenedActionsState
+ */
+
 const NAME_QUOTABLE = /;|,|{| |\[/;
 const ACTIONS_QUOTABLE = /;|,|{/;
 const LABEL_QUOTABLE = /;|{/;
 
+/**
+ * @param {RegExp} pRegExp
+ * @param {string} pString
+ * @returns {string}
+ */
 function quoteIfNecessary(pRegExp, pString) {
   return pRegExp.test(pString) ? `"${pString}"` : pString;
 }
@@ -17,20 +29,31 @@ Handlebars.registerPartial(
   Handlebars.templates["smcat.template.hbs"]
 );
 
+/**
+ * @param {string} pString
+ * @returns {string}
+ */
 function formatActionType(pString) {
   return pString === "activity" ? "" : `${pString}/ `;
 }
 
+/**
+ * @param {IExtendedState} pState
+ * @returns {IFlattenedActionsState}
+ */
 function flattenActions(pState) {
-  const lReturnValue = { ...pState };
-
-  lReturnValue.actions = (pState.actions || [])
-    .map((pAction) => `${formatActionType(pAction.type)}${pAction.body}`)
-    .join("\n    ");
-
-  return lReturnValue;
+  return {
+    ...pState,
+    actions: (pState.actions || [])
+      .map((pAction) => `${formatActionType(pAction.type)}${pAction.body}`)
+      .join("\n    "),
+  };
 }
 
+/**
+ * @param {IExtendedState} pState
+ * @returns {IExtendedState}
+ */
 /* eslint complexity:0 */
 function flagExtendedStateAttributes(pState) {
   if (
@@ -40,19 +63,27 @@ function flagExtendedStateAttributes(pState) {
     Object.prototype.hasOwnProperty.call(pState, "active") ||
     Object.prototype.hasOwnProperty.call(pState, "class")
   ) {
+    // note & fixme: mutating a parameter here
     pState.hasExtendedAttributes = true;
   }
   return pState;
 }
 
-function transformStates(pStates, pDirection) {
+/**
+ * @param {import("../../../types/state-machine-cat.js").IState[]} pStates
+ * @returns {IFlattenedActionsState[]}
+ */
+function transformStates(pStates) {
   pStates
     .map(flagExtendedStateAttributes)
     .filter((pState) => pState.statemachine)
     .forEach((pState) => {
+      // @ts-expect-error because of the filter above the statemachine is
+      // sure to exist, although TS currently doesn't detect this.
+      // also fixme: mutating a parameter here
       pState.statemachine.states = transformStates(
-        pState.statemachine.states,
-        pDirection
+        // @ts-expect-error - see above
+        pState.statemachine.states
       );
     });
 
@@ -86,10 +117,13 @@ Handlebars.registerHelper("quotifyActions", (pItem) =>
   quoteIfNecessary(ACTIONS_QUOTABLE, pItem)
 );
 
-module.exports = function renderSmcat(pAST) {
+/** @type {import("../../../types/state-machine-cat.js").StringRenderFunctionType} */
+module.exports = function renderSmcat(pStateMachine) {
   return Handlebars.templates["smcat.template.hbs"]({
-    ...pAST,
-    states: transformStates(cloneDeep(pAST.states)),
-    transitions: transformTransitions(cloneDeep(pAST.transitions || [])),
+    ...pStateMachine,
+    states: transformStates(cloneDeep(pStateMachine.states)),
+    transitions: transformTransitions(
+      cloneDeep(pStateMachine.transitions || [])
+    ),
   });
 };

package/src/render/vector/dot-to-vector-native.mjs

@@ -11,7 +11,7 @@ const DEFAULT_OPTIONS = {
  * the result
  *
  * @param  {string} pDot        The dot program as a string
- * @param  {object} pOptions
+ * @param  {{exec: string, format: import("../../../types/state-machine-cat").OutputType}} pOptions
  *         exec: the path to the executable to run. Default: 'dot'
  * @return {string} the dot program converted into an svg
  * @throws {Error} when something ontowards has happened (executable not found, erroneous dot program)

package/src/render/vector/vector-native-dot-with-fallback.mjs

@@ -10,8 +10,9 @@ const DEFAULT_INDENT = 2;
 const DOGMATIC_CONSOLE_WIDTH = 78;
 const VIZ_JS_UNSUPPORTED_OUTPUT_FORMATS = ["pdf", "png"];
 
-export default (pAST, pOptions) => {
-  const lDotProgram = ast2dot(pAST, pOptions);
+/** @type {import("../../../types/state-machine-cat.js").StringRenderFunctionType} */
+export default (pStateMachine, pOptions) => {
+  const lDotProgram = ast2dot(pStateMachine, pOptions);
   const lDotOptions = {
     engine: options.getOptionValue(pOptions, "engine"),
     format: options.getOptionValue(pOptions, "outputType"),

package/src/render/vector/vector-with-viz-js.mjs

@@ -8,8 +8,9 @@ const OUTPUT_TYPE2FORMAT = {
   oldeps: "eps",
 };
 
-export default (pAST, pOptions) =>
-  viz(ast2dot(pAST, pOptions), {
+/** @type {import("../../../types/state-machine-cat.js").StringRenderFunctionType} */
+export default (pStateMachine, pOptions) =>
+  viz(ast2dot(pStateMachine, pOptions), {
     engine: options.getOptionValue(pOptions, "engine"),
     format:
       OUTPUT_TYPE2FORMAT[options.getOptionValue(pOptions, "outputType")] ||