state-machine-cat 10.1.2 → 10.1.3

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("../../../types/state-machine-cat").IStateMachine} pStateMachine
+ * @param {import("../../../types/state-machine-cat").IRenderOptions?} _pOptions
+ * @param {import("../../../types/state-machine-cat").ITransition[]?} pTransitions
+ * @returns {any}
+ */
 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("../../../types/state-machine-cat.js").StringRenderFunctionType} */
 export default function renderSCXML(pStateMachine) {
-  return renderFomSCJSON(ast2scjson(pStateMachine));
+  return renderFomSCJSON(ast2scjson(pStateMachine, null));
 }

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")] ||

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|undefined} pEvent
+ * @param {string|undefined} pCond
+ * @param {string|undefined} 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.3";

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.