state-machine-cat 10.1.2 → 10.1.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "state-machine-cat",
-  "version": "10.1.2",
+  "version": "10.1.3",
   "description": "write beautiful state charts",
   "main": "./dist/commonjs/index.js",
   "module": "./src/index.mjs",
@@ -90,11 +90,6 @@
         "policy": "wanted",
         "because": "fast-xml-parser 4 has some breaking changes we still need to grok (why? how?)"
       },
-      {
-        "package": "husky",
-        "policy": "pin",
-        "because": "(npm7 & husky don't play nice together - and it might be it's not going to be solved satisfactorily) https://github.com/typicode/husky/issues/822 "
-      },
       {
         "package": "viz.js",
         "policy": "pin",
@@ -244,13 +239,13 @@
       ]
     },
     "depcruise:graph:dev": {
-      "command": "depcruise-fmt node_modules/.cache/depcruise-cache.json --output-type dot --include-only '^(bin|src|package\\.json)' --prefix vscode://file/$(pwd)/ | dot -Tsvg | depcruise-wrap-stream-in-html | browser",
+      "command": "depcruise-fmt node_modules/.cache/depcruise-cache.json --output-type dot --include-only '^(bin|src|package\\.json)' --prefix vscode://file/$(pwd)/ --highlight \"$(watskeburt develop)\"| dot -Tsvg | depcruise-wrap-stream-in-html | browser",
       "dependencies": [
         "depcruise:json"
       ]
     },
     "depcruise:graph:dev:flat": {
-      "command": "depcruise-fmt node_modules/.cache/depcruise-cache.json --output-type flat --include-only '^(bin|src|package\\.json)' --prefix vscode://file/$(pwd)/ | twopi -Tsvg | depcruise-wrap-stream-in-html | browser",
+      "command": "depcruise-fmt node_modules/.cache/depcruise-cache.json --output-type flat --include-only '^(bin|src|package\\.json)' --prefix vscode://file/$(pwd)/ --highlight \"$(watskeburt develop)\"| twopi -Tsvg | depcruise-wrap-stream-in-html | browser",
       "dependencies": [
         "depcruise:json"
       ]
@@ -301,7 +296,7 @@
       ]
     },
     "lint:prettier": {
-      "command": "prettier --check \"bin/*.mjs\" \"{src,test}/**/*.{js,mjs}\" \"{config,test}/**/*.{js,json}\" \"tools/*.{js,mjs,json}\" \"types/*.ts\" \"*.{json,yml,md}\" \"docs/{smcat-online-interpreter.js,*.md}\"",
+      "command": "prettier --check \"bin/*.mjs\" \"{src,test}/**/*.{js,mjs}\" \"{config,test}/**/*.{js,json}\" \"tools/*.{js,mjs,json}\" \"{src,types}/**/*.{ts,mts}\" \"*.{json,yml,md}\" \"docs/{smcat-online-interpreter.js,*.md}\"",
       "files": [
         "bin/*.mjs",
         "{src,test}/**/*.{js,mjs}",
@@ -319,15 +314,15 @@
       ]
     },
     "lint:types:tsc": {
-      "command": "tsc --noEmit --strict --types --noUnusedLocals --noUnusedParameters --pretty types/*.d.ts",
+      "command": "tsc --noEmit --strict --types --noUnusedLocals --noUnusedParameters --pretty types/*.d.ts src/cli/*.d.mts src/cli/*.d.ts src/parse/scxml/*.d.ts",
       "files": [
         "types/*.d.ts"
       ]
     },
     "lint:types:eslint": {
-      "command": "eslint types/*.d.ts",
+      "command": "eslint types/*.d.ts src/cli/*.d.mts src/cli/*.d.ts src/parse/scxml/*.d.ts",
       "files": [
-        "types/*.d.ts",
+        "{src,types}/**/*.d.{ts,mts}",
         ".eslintrc.json"
       ]
     },
@@ -347,10 +342,10 @@
       ]
     },
     "lint:fix:prettier": {
-      "command": "prettier --loglevel warn --write \"bin/*.mjs\" \"{src,test}/**/*.{js,mjs}\" \"{config,test}/**/*.{js,json}\" \"tools/*.{js,mjs,json}\" \"types/*.ts\" \"*.{json,yml,md}\" \"docs/{smcat-online-interpreter.js,*.md}\"",
+      "command": "prettier --loglevel warn --write \"bin/*.mjs\" \"{src,test}/**/*.{js,mjs}\" \"{config,test}/**/*.{js,json}\" \"tools/*.{js,mjs,json}\" \"{src,types}/**/*.{ts,mts}\" \"*.{json,yml,md}\" \"docs/{smcat-online-interpreter.js,*.md}\"",
       "files": [
         "bin/*.mjs",
-        "{src,test}/**/*.{js,mjs}",
+        "{src,test}/**/*.{js,mjs,ts,mts}",
         "{config,test}/**/*.{js,json}",
         "tools/*.{js,mjs,json}",
         "types/*.ts",
@@ -359,9 +354,9 @@
       ]
     },
     "lint:fix:types": {
-      "command": "eslint --fix types/*.d.ts",
+      "command": "eslint --fix types/*.d.ts src/cli/*.d.mts src/cli/*.d.ts src/parse/scxml/*.d.ts",
       "files": [
-        "types/*.d.ts",
+        "{src,types}/**/*.d.{ts,mts}",
         ".eslintrc.json"
       ]
     },
@@ -372,7 +367,7 @@
       ]
     },
     "test:cover": {
-      "command": "c8 --all --check-coverage --statements 100 --branches 99.1 --functions 100 --lines 100 --exclude \"{bin/*,config/**/*,coverage/**/*,docs/**/*,public/**/*,test/**/*,tools/**/*,types/**/*,dist/commonjs/*,src/**/*{template,-parser}.{mjs,cjs,js},tmp*}\" --reporter text-summary --reporter html --reporter lcov mocha",
+      "command": "c8 --all --check-coverage --statements 100 --branches 99.1 --functions 100 --lines 100 --exclude \"{bin/*,config/**/*,coverage/**/*,docs/**/*,public/**/*,test/**/*,tools/**/*,types/**/*,dist/commonjs/*,src/**/*.d.{ts,mts},src/**/*{template,-parser}.{mjs,cjs,js},tmp*}\" --reporter text-summary --reporter html --reporter lcov mocha",
       "output": [
         "coverage/lcov.info"
       ],
@@ -414,16 +409,16 @@
     "wrap-ansi": "8.0.1"
   },
   "devDependencies": {
-    "@typescript-eslint/eslint-plugin": "5.40.1",
-    "@typescript-eslint/parser": "5.40.1",
+    "@typescript-eslint/eslint-plugin": "5.42.1",
+    "@typescript-eslint/parser": "5.42.1",
     "c8": "7.12.0",
-    "chai": "4.3.6",
+    "chai": "4.3.7",
     "chai-as-promised": "7.1.1",
     "chai-json-schema": "1.5.1",
     "chai-xml": "0.4.0",
-    "dependency-cruiser": "11.17.0",
-    "esbuild": "0.15.12",
-    "eslint": "8.26.0",
+    "dependency-cruiser": "11.18.0",
+    "esbuild": "0.15.13",
+    "eslint": "8.27.0",
     "eslint-config-moving-meadow": "4.0.2",
     "eslint-config-prettier": "8.5.0",
     "eslint-plugin-budapestian": "5.0.1",
@@ -433,7 +428,7 @@
     "eslint-plugin-node": "11.1.0",
     "eslint-plugin-security": "1.5.0",
     "eslint-plugin-unicorn": "44.0.2",
-    "husky": "8.0.1",
+    "husky": "8.0.2",
     "is-pdf": "1.0.0",
     "is-png": "3.0.1",
     "lint-staged": "13.0.3",
@@ -443,7 +438,7 @@
     "prettier": "2.7.1",
     "query-string": "7.1.1",
     "typescript": "4.8.4",
-    "upem": "7.3.0",
+    "upem": "7.3.1",
     "watskeburt": "0.8.1",
     "wireit": "0.7.2",
     "xml-name-validator": "4.0.0"

package/src/cli/actions.mjs

@@ -1,3 +1,4 @@
+// @ts-check
 import getStream from "get-stream";
 import smcat from "../index-node.mjs";
 import { getOutStream, getInStream } from "./file-name-to-stream.mjs";
@@ -31,7 +32,11 @@ WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 `;
 
 export default {
+  /** @type {string} */
   LICENSE,
+  /**
+   * @param {import("./cli").ICLIRenderOptions} pOptions
+   */
   transform(pOptions) {
     return getStream(getInStream(pOptions.inputFrom)).then((pInput) => {
       const lOutput = smcat.render(pInput, {
@@ -54,6 +59,10 @@ export default {
     });
   },
 
+  /**
+   * @param {any} pError
+   * @returns {string}
+   */
   formatError(pError) {
     if (Boolean(pError.location)) {
       return `\n  syntax error on line ${pError.location.start.line}, column ${pError.location.start.column}:\n  ${pError.message}\n\n`;

package/src/cli/file-name-to-stream.mjs

@@ -1,11 +1,10 @@
+// @ts-check
 /* eslint-disable security/detect-non-literal-fs-filename */
-
-import * as fs from "node:fs";
+import fs from "node:fs";
 
 /**
- *
  * @param {string} pOutputTo
- * @returns {import("node:fs").WriteStream}
+ * @returns {NodeJS.WritableStream}
  */
 export function getOutStream(pOutputTo) {
   if ("-" === pOutputTo) {
@@ -13,10 +12,10 @@ export function getOutStream(pOutputTo) {
   }
   return fs.createWriteStream(pOutputTo);
 }
+
 /**
- *
  * @param {string} pInputFrom
- * @returns {import("node:fs").ReadStream}
+ * @returns {NodeJS.ReadableStream}
  */
 export function getInStream(pInputFrom) {
   if ("-" === pInputFrom) {

package/src/cli/make-description.mjs

@@ -1,3 +1,4 @@
+// @ts-check
 // seems eslint-plugin-import and eslint-plugin-node can't handle exports
 // fields yet. No man overboard not checking against this, because dependency-cruiser
 // will also find them
@@ -7,6 +8,10 @@ import indentString from "indent-string";
 import wrapAnsi from "wrap-ansi";
 import dotToVectorNative from "../render/vector/dot-to-vector-native.mjs";
 
+/**
+ * @param {string} pString
+ * @returns {string}
+ */
 function wrapAndIndent(pString) {
   const lDogmaticMaxConsoleWidth = 78;
   const lDefaultIndent = 2;
@@ -16,6 +21,10 @@ function wrapAndIndent(pString) {
   return indentString(wrapAnsi(pString, lMaxWidth), lDefaultIndent);
 }
 
+/**
+ * @param {boolean} pDotIsAvailable
+ * @return {string}
+ */
 export default (pDotIsAvailable = dotToVectorNative.isAvailable({})) => {
   const lDescription =
     "Write beautiful state charts - https://github.com/sverweij/state-machine-cat";

package/src/cli/normalize.mjs

@@ -1,8 +1,13 @@
-/* eslint-disable security/detect-object-injection */
+// @ts-check
+/* eslint-disable security/detect-object-injection, no-inline-comments */
 import path from "node:path";
 import options from "../options.mjs";
 import { parse as parseAttributes } from "./attributes-parser.mjs";
 
+/**
+ * @typedef {{[extension: string]: string}} DictionaryType
+ */
+
 const INPUT_EXTENSIONS = {
   ".smcat": "smcat",
   ".scxml": "scxml",
@@ -11,16 +16,18 @@ const INPUT_EXTENSIONS = {
   ".ast": "json",
 };
 const OUTPUT_EXTENSIONS = {
-  ".smcat": "smcat",
+  ".ast": "json",
   ".dot": "dot",
+  ".eps": "eps",
   ".json": "json",
-  ".ast": "json",
+  ".pdf": "pdf",
+  ".png": "png",
+  ".ps": "ps",
+  ".ps2": "ps2",
   ".scjson": "scjson",
   ".scxml": "scxml",
+  ".smcat": "smcat",
   ".svg": "svg",
-  ".ps": "ps",
-  ".ps2": "ps2",
-  ".eps": "eps",
 };
 
 /**
@@ -31,7 +38,7 @@ const OUTPUT_EXTENSIONS = {
  * When in doubt returns pDefault
  *
  * @param {string} pString - filename
- * @param {object} pExtensionMap - a dictionary with
+ * @param {DictionaryType} pExtensionMap - a dictionary with
  *        extension : classification pairs
  * @param {string} pDefault - the default to return when the extension
  *        does not occur in the extension map
@@ -42,15 +49,26 @@ function classifyExtension(pString, pExtensionMap, pDefault) {
   return pExtensionMap[path.extname(pString)] || pDefault;
 }
 
+/**
+ * @param {import("../../types/state-machine-cat").OutputType} pOutputType
+ * @returns {import("../../types/state-machine-cat").OutputType}
+ */
 function outputType2Extension(pOutputType) {
   const lExceptions = {
-    oldsvg: "svg",
-    oldps2: "ps",
     oldeps: "eps",
+    oldps: "ps",
+    oldps2: "ps",
+    oldsvg: "svg",
     ps2: "ps",
   };
   return lExceptions[pOutputType] || pOutputType;
 }
+
+/**
+ * @param {string} pInputFrom
+ * @param {import("../../types/state-machine-cat").OutputType} pOutputType
+ * @returns {string}
+ */
 function deriveOutputFromInput(pInputFrom, pOutputType) {
   const lExtension = outputType2Extension(pOutputType);
 
@@ -66,16 +84,28 @@ function deriveOutputFromInput(pInputFrom, pOutputType) {
     .concat(lExtension);
 }
 
+/**
+ * @param {string|undefined} pOutputTo
+ * @param {string} pInputFrom
+ * @param {import("../../types/state-machine-cat").OutputType} pOutputType
+ * @returns {string}
+ */
 function determineOutputTo(pOutputTo, pInputFrom, pOutputType) {
-  return Boolean(pOutputTo)
-    ? pOutputTo
-    : deriveOutputFromInput(pInputFrom, pOutputType);
+  return pOutputTo ? pOutputTo : deriveOutputFromInput(pInputFrom, pOutputType);
 }
 
+/**
+ * @param {import("../../types/state-machine-cat").InputType|undefined} pInputType
+ * @param {string} pInputFrom
+ * @returns {import("../../types/state-machine-cat").InputType}
+ */
 function determineInputType(pInputType, pInputFrom) {
   if (pInputType) {
     return pInputType;
   }
+  // @ts-expect-error we can safely cast this to InputType. classifyExtension
+  // can probably use treatment with a generic, but with jsdoc annotations
+  // if at all possible would likely be awkward.
   return classifyExtension(
     pInputFrom,
     INPUT_EXTENSIONS,
@@ -103,9 +133,16 @@ function determineParameter(pOptions, pParameter) {
     : options.getAllowedValues()[pParameter].default;
 }
 
+/**
+ * @param {Partial<import("./cli").ILooseCLIRenderOptions>} pOptions
+ * @param {keyof import("./cli").ILooseCLIRenderOptions} pDotAttributes
+ * @returns {import("../../types/state-machine-cat").dotAttributesType}
+ */
 function determineDotAttributes(pOptions, pDotAttributes) {
-  return Object.prototype.hasOwnProperty.call(pOptions, pDotAttributes)
-    ? parseAttributes(pOptions[pDotAttributes])
+  return Boolean(pOptions?.[pDotAttributes]) &&
+    typeof pOptions[pDotAttributes] === "string"
+    ? // @ts-expect-error parseAttributes expects a string - which we can guarantee (see above) - but tsc can't/ doesn't see it
+      parseAttributes(pOptions[pDotAttributes])
     : [];
 }
 
@@ -114,38 +151,39 @@ function determineDotAttributes(pOptions, pDotAttributes) {
  *
  * - guesses the input type when not given
  * - guesses the output type when not given
- * - gueses the filename to output to when not given
+ * - guesses the filename to output to when not given
  * - translates parserOutput to a regular output type
  *
  * @param  {string} pArgument an argument (containing the filename to parse)
- * @param  {object} pOptions a commander options object
- * @return {object} a commander options object with options 'normalized'
+ * @param  {import("./cli").ILooseCLIRenderOptions} pLooseOptions
+ * @return {import("./cli").ICLIRenderOptions}
+ *          the passed options object, but normalized
  */
-export default function normalize(pArgument = "-", pOptions = {}) {
-  const lReturnValue = { ...pOptions };
-
-  lReturnValue.inputFrom = pArgument || "-";
-  lReturnValue.inputType = determineInputType(
-    pOptions.inputType,
-    lReturnValue.inputFrom
-  );
-  lReturnValue.outputType = determineOutputType(
-    pOptions.outputType,
-    pOptions.outputTo
+export default function normalize(pArgument = "-", pLooseOptions = {}) {
+  const lNormalizedInputFrom = pArgument || "-";
+  const lNormalizedInputType = determineInputType(
+    pLooseOptions.inputType,
+    lNormalizedInputFrom
   );
-  lReturnValue.outputTo = determineOutputTo(
-    pOptions.outputTo,
-    lReturnValue.inputFrom,
-    lReturnValue.outputType
+  const lNormalizedOutputType = determineOutputType(
+    pLooseOptions.outputType,
+    pLooseOptions.outputTo
   );
-  lReturnValue.engine = determineParameter(pOptions, "engine");
-  lReturnValue.direction = determineParameter(pOptions, "direction");
-  lReturnValue.dotGraphAttrs = determineDotAttributes(
-    pOptions,
-    "dotGraphAttrs"
-  );
-  lReturnValue.dotNodeAttrs = determineDotAttributes(pOptions, "dotNodeAttrs");
-  lReturnValue.dotEdgeAttrs = determineDotAttributes(pOptions, "dotEdgeAttrs");
 
-  return lReturnValue;
+  return {
+    inputFrom: lNormalizedInputFrom,
+    inputType: lNormalizedInputType,
+    outputType: lNormalizedOutputType,
+    outputTo: determineOutputTo(
+      pLooseOptions.outputTo,
+      lNormalizedInputFrom,
+      lNormalizedOutputType
+    ),
+    engine: determineParameter(pLooseOptions, "engine"),
+    direction: determineParameter(pLooseOptions, "direction"),
+    dotGraphAttrs: determineDotAttributes(pLooseOptions, "dotGraphAttrs"),
+    dotNodeAttrs: determineDotAttributes(pLooseOptions, "dotNodeAttrs"),
+    dotEdgeAttrs: determineDotAttributes(pLooseOptions, "dotEdgeAttrs"),
+    desugar: pLooseOptions?.desugar ?? false,
+  };
 }

package/src/cli/validations.mjs

@@ -1,9 +1,14 @@
+// @ts-check
 import fs from "node:fs";
 import smcat from "../index-node.mjs";
 import { parse as parseAttributes } from "./attributes-parser.mjs";
 
 const allowedValues = smcat.getAllowedValues();
 
+/**
+ * @param {{name: string}} pValue
+ * @returns {string}
+ */
 function getName(pValue) {
   return pValue.name;
 }
@@ -13,14 +18,22 @@ const VALID_INPUT_TYPES = allowedValues.inputType.values.map(getName);
 const VALID_ENGINES = allowedValues.engine.values.map(getName);
 const VALID_DIRECTIONS = allowedValues.direction.values.map(getName);
 
+/**
+ * @param {string} pFilename
+ * @returns {boolean}
+ */
 function isStdout(pFilename) {
   return "-" === pFilename;
 }
 
+/**
+ * @param {string} pFilename
+ * @returns {boolean}
+ */
 function fileExists(pFilename) {
   try {
     if (!isStdout(pFilename)) {
-      fs.accessSync(pFilename, fs.R_OK);
+      fs.accessSync(pFilename, fs.constants.R_OK);
     }
     return true;
   } catch (pError) {
@@ -28,6 +41,15 @@ function fileExists(pFilename) {
   }
 }
 
+/**
+ * This function is shaped so it can serve as a validation function in a
+ * commander option.
+ *
+ * @param {keyof import("../../types/state-machine-cat").IRenderOptions} pOption
+ * @param {string[]} pValidValues
+ * @param {string} pError
+ * @returns {never|keyof import("../../types/state-machine-cat").IRenderOptions}
+ */
 function validOption(pOption, pValidValues, pError) {
   if (pValidValues.includes(pOption)) {
     return pOption;
@@ -78,6 +100,10 @@ export default {
     }
   },
 
+  /**
+   * @param {import("./cli").ICLIRenderOptions} pOptions
+   * @returns {never|import("./cli").ICLIRenderOptions}
+   */
   validateArguments(pOptions) {
     if (!pOptions.inputFrom) {
       throw new Error(`\n  error: Please specify an input file.\n\n`);

package/src/index-node.mjs

@@ -1,52 +1,18 @@
+// @ts-check
 import options from "./options.mjs";
 import parse from "./parse/index.mjs";
 import desugar from "./transform/desugar.mjs";
 import getRenderFunction from "./render/index-node.mjs";
 import { version } from "./version.mjs";
 
-const KNOWN_OPTIONS = [
-  "outputType",
-  "inputType",
-  "engine",
-  "direction",
-  "dotNodeAttrs",
-  "dotEdgeAttrs",
-  "desugar",
-];
-
-function isKnownOption(pKnownOptions) {
-  return (pCandidateString) => pKnownOptions.includes(pCandidateString);
-}
-
-/**
- * Remove all attributes from the input object (which'd typically be
- * originating from commander) that are not known options options so
- * a clean object can be passed through.
- *
- * @param {any} pOptions - an options object e.g. as output from commander
- * @param {string[]} pKnownOptions - a list of known options
- * @return {any} - an options object that only contains stuff we care about
- */
-function ejectUnknownOptions(pOptions, pKnownOptions) {
-  return Object.keys(pOptions)
-    .filter(isKnownOption(pKnownOptions))
-    .reduce((pAll, pKey) => {
-      // eslint-disable-next-line security/detect-object-injection
-      pAll[pKey] = pOptions[pKey];
-      return pAll;
-    }, {});
-}
-
 export default {
   /**
-   * Translates the input script to an outputscript.
+   * Translates the input script to an output-script.
    *
-   * @param  {string} pScript     The script to translate
-   * @param  {object} pOptions    options influencing parsing & rendering.
-   *                              See below for the complete list.
-   * @return {string|void}        nothing if a callback was passed, the
-   *                              string with the rendered content if
-   *                              no callback was passed and no error was found
+   * @param  {string|import("../types/state-machine-cat").IStateMachine} pScript
+   *                              The script to translate
+   * @param  {import("../types/state-machine-cat").IRenderOptions} pOptions
+   *                              options influencing parsing & rendering.
    * @throws {Error}              if an error occurred and no callback
    *                              function was passed: the error
    *
@@ -54,13 +20,15 @@ export default {
    *
    */
   render(pScript, pOptions) {
-    const lOptions = ejectUnknownOptions(pOptions, KNOWN_OPTIONS);
-    const lAST = parse.getAST(pScript, lOptions);
-    const lDesugar = options.getOptionValue(lOptions, "desugar");
+    const lStateMachine = parse.getAST(pScript, pOptions);
+    const lDesugar = options.getOptionValue(pOptions, "desugar");
 
-    return getRenderFunction(options.getOptionValue(lOptions, "outputType"))(
-      lDesugar ? desugar(lAST) : lAST,
-      lOptions
+    // @ts-expect-error should be cast to OutputTypeType - or the getOptionValue
+    // function should be refactored to be more explicit in type it returns
+    // when we ask for outputType
+    return getRenderFunction(options.getOptionValue(pOptions, "outputType"))(
+      lDesugar ? desugar(lStateMachine) : lStateMachine,
+      pOptions
     );
   },
 
@@ -79,7 +47,7 @@ export default {
    * - the possible values in an array of objects, each of which
    *   has the properties:
    *   - name: the value
-   *
+   * @returns {import("../types/state-machine-cat").IAllowedValues}
    */
   getAllowedValues() {
     return options.getAllowedValues();

package/src/index.mjs

@@ -1,3 +1,4 @@
+// @ts-check
 /* eslint-disable budapestian/global-constant-pattern */
 import options from "./options.mjs";
 import parse from "./parse/index.mjs";
@@ -8,12 +9,11 @@ import { version as _version } from "./version.mjs";
 /**
  * Translates the input script to an output-script.
  *
- * @param  {string} pScript     The script to translate
- * @param  {object} pOptions    options influencing parsing & rendering.
- *                              See below for the complete list.
- * @return {string|void}        nothing if a callback was passed, the
- *                              string with the rendered content if
- *                              no callback was passed and no error was found
+ * @param  {string|import("../types/state-machine-cat").IStateMachine} pScript
+ *                              The script to translate
+ * @param  {import("../types/state-machine-cat").IRenderOptions} pOptions
+ *                              options influencing parsing & rendering.
+ * @return {string}
  * @throws {Error}              if an error occurred and no callback
  *                              function was passed: the error
  *
@@ -21,11 +21,11 @@ import { version as _version } from "./version.mjs";
  *
  */
 export function render(pScript, pOptions) {
-  const lAST = parse.getAST(pScript, pOptions);
+  const lStateMachine = parse.getAST(pScript, pOptions);
   const lDesugar = options.getOptionValue(pOptions, "desugar");
 
   return getRenderFunction(options.getOptionValue(pOptions, "outputType"))(
-    lDesugar ? desugar(lAST) : lAST,
+    lDesugar ? desugar(lStateMachine) : lStateMachine,
     pOptions
   );
 }
@@ -45,7 +45,7 @@ export const version = _version;
  * - the possible values in an array of objects, each of which
  *   has the properties:
  *   - name: the value
- *
+ * @returns {import("../types/state-machine-cat").IAllowedValues}
  */
 export function getAllowedValues() {
   return options.getAllowedValues();

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