state-machine-cat 12.0.3 → 12.0.5

package/LICENSE

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2016-2023 Sander Verweij
+Copyright (c) 2016-2024 Sander Verweij
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -403,7 +403,12 @@ the tape player is on:
 ```
 initial,
 "tape player off",
-"tape player on" {
+"tape player on":
+  entry/ LED on
+  exit/ LED off
+{
+  stopped, playing, paused;
+
   stopped => playing : play;
   playing => stopped : stop;
   playing => paused  : pause;
@@ -414,8 +419,13 @@ initial,
 initial           => "tape player off";
 "tape player off" => stopped           : power;
 "tape player on"  => "tape player off" : power;
+
 ```
 
+As you can see in this sample you can use activities (like entry and exit
+triggers) in the composite state declaration, just as you'd do for state that
+does not contain a state machine.
+
 <img width="653" alt="tape player rendition" src="https://raw.githubusercontent.com/sverweij/state-machine-cat/main/docs/pics/05tape_player.png">
 
 #### parallel states
@@ -630,7 +640,8 @@ The values you can use for the `type` of a state:
 #### grammar
 
 I made the parser with peggy - you can find it at
-[src/parse/peg/smcat-parser.peggy](src/parse/smcat/peg/smcat-parser.peggy)
+[src/parse/peg/smcat-parser.peggy](src/parse/smcat/peg/smcat-parser.peggy), and
+railroad diagrams generated from these on [state-machine-cat.js.org/grammar.html](https://state-machine-cat.js.org/grammar.html)
 
 ## Status
 

package/dist/cli/actions.mjs

@@ -5,7 +5,7 @@ const LICENSE = `
 
 The MIT License (MIT)
 
-Copyright (c) 2016-2023 Sander Verweij
+Copyright (c) 2016-2024 Sander Verweij
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

package/dist/version.mjs

@@ -1 +1 @@
-export const version = "12.0.3";
+export const version = "12.0.5";

package/package.json

@@ -1,16 +1,18 @@
 {
   "name": "state-machine-cat",
-  "version": "12.0.3",
+  "version": "12.0.5",
   "description": "write beautiful state charts",
   "main": "./dist/index.mjs",
   "module": "./dist/index.mjs",
   "exports": {
     ".": [
       {
+        "types": "./types/state-machine-cat.d.mts",
         "import": "./dist/index.mjs"
       }
     ]
   },
+  "types": "types/state-machine-cat.d.mts",
   "imports": {
     "#*": "./src/*"
   },
@@ -48,10 +50,10 @@
     "state-machine-cat": "bin/smcat.mjs"
   },
   "dependencies": {
-    "@hpcc-js/wasm": "2.15.1",
+    "@hpcc-js/wasm": "2.15.3",
     "ajv": "8.12.0",
-    "commander": "11.1.0",
-    "fast-xml-parser": "4.3.2",
+    "commander": "12.0.0",
+    "fast-xml-parser": "4.3.4",
     "handlebars": "4.7.8",
     "he": "1.2.0",
     "semver": "^7.5.4",
@@ -60,7 +62,6 @@
   "engines": {
     "node": "^18.17||>=20"
   },
-  "types": "types/state-machine-cat.d.ts",
   "homepage": "https://state-machine-cat.js.org",
   "repository": {
     "type": "git",
@@ -68,5 +69,8 @@
   },
   "bugs": {
     "url": "https://github.com/sverweij/state-machine-cat/issues"
+  },
+  "scripts": {
+    "test": "echo for test, build and static analysis scripts: see the github repository"
   }
-}
+}

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

@@ -0,0 +1,296 @@
+export type StateType =
+  | "regular"
+  | "initial"
+  | "final"
+  | "parallel"
+  | "choice"
+  | "fork"
+  | "forkjoin"
+  | "history"
+  | "deephistory"
+  | "join"
+  | "junction"
+  | "terminate";
+
+export type TransitionType = "external" | "internal";
+
+export type ActionTypeType = "activity" | "entry" | "exit";
+
+export interface IActionType {
+  body: string;
+  type: ActionTypeType;
+}
+
+export interface IState {
+  /**
+   * The name and identifier of the state. Unique within the root state machine.
+   */
+  name: string;
+  /**
+   * What kind of state (or pseudo state) this state is. E.g. 'regular'
+   * for normal states or 'initial', 'final', 'choice' etc for pseudo states
+   */
+  type: StateType;
+  /**
+   * The display label of the state. If it's not present, most renderers
+   * will use the states' name in stead
+   */
+  label?: string;
+  /**
+   * A series of actions and their types. The type describe when the action
+   * takes place (on entry, exit, or otherwise ('activity'))
+   */
+  actions?: IActionType[];
+  /**
+   * State machine nested within the state.
+   */
+  // eslint-disable-next-line no-use-before-define
+  statemachine?: IStateMachine;
+  /**
+   * If true the state is considered to be active and rendered as such.
+   */
+  active?: boolean;
+  /**
+   * Color to use for rendering the state. Accepts all css color names
+   * (\"blue\") and hex notation - with (\"#0000FF77\") or without
+   * (\"#0000FF\") transparency.
+   */
+  color?: string;
+  /**
+   * Class name to give the state in dot and svg output.
+   */
+  class?: string;
+  /**
+   * Comments related to this state. Some renderers will use the note
+   * attribute to render a note (i.e. as a post-it) attached to the
+   * state.
+   */
+  note?: string[];
+  /**
+   * convenience, derived attribute - set to true if there's a state
+   * machine inside the state; false in all other cases. For internal
+   * use - @deprecated
+   */
+  isComposite?: boolean;
+  /**
+   * The default parser derives the `type` from the `name` with inband
+   * signaling. The user can override that behavior by explicitly setting
+   * the `type`. This attribute is there to express that (and make sure
+   * that on next parses & processing it doesn't get accidentily
+   * re-derived from the name again)
+   */
+  typeExplicitlySet?: boolean;
+}
+
+export interface ITransition {
+  /**
+   * The name of the IState the transition is from
+   */
+  from: string;
+  /**
+   * The name of the IState the transition is to
+   */
+  to: string;
+  /**
+   * A display label to represent this transition. Parsers can parse this
+   * label into events conditions and actions.
+   */
+  label?: string;
+  /**
+   * Event triggering the transition
+   */
+  event?: string;
+  /**
+   * Condition for the transition to occur.
+   */
+  cond?: string;
+  /**
+   * Action to execute when the transition occurs.
+   */
+  action?: string;
+  /**
+   * Comments related to this transition. Some renderers will use the note
+   * attribute to render a note attached to the transition.
+   */
+  note?: string[];
+  /**
+   * Color to use for rendering the transition. Accepts all css color
+   * names (\"blue\") and hex notation - with (\"#0000FF77\") or without
+   * (\"#0000FF\") transparency.
+   */
+  color?: string;
+  /**
+   * The line width to use for rendering the transition
+   */
+  width?: number;
+  /**
+   * Class name to give the transition in dot and svg output.
+   */
+  class?: string;
+  /**
+   * Whether the transition is "external" (the default) or "internal".
+   * See https://www.w3.org/TR/scxml/#transition for details.
+   */
+  type?: TransitionType;
+}
+
+export interface IStateMachine {
+  states: IState[];
+  transitions?: ITransition[];
+}
+
+/**
+ * The current (semver compliant) version number string of
+ * state machine cat
+ *
+ * @type {string}
+ */
+// eslint-disable-next-line init-declarations
+export const version: string;
+
+export interface IAllowedValue {
+  default: string;
+  values: {
+    name: string;
+  }[];
+}
+
+export interface IAllowedBooleanValue {
+  default: boolean;
+  values: {
+    name: boolean;
+  }[];
+}
+export interface IAllowedValues {
+  inputType: IAllowedValue;
+  outputType: IAllowedValue;
+  engine: IAllowedValue;
+  direction: IAllowedValue;
+  desugar: IAllowedBooleanValue;
+}
+
+/**
+ * @returns An object with for each of the options you can pass to
+ *          the render function:
+ *          - the default value
+ *          - the possible values in an array of objects, each of which
+ *            has the properties:
+ *          - name: the value
+ *
+ */
+export function getAllowedValues(): IAllowedValues;
+
+export type InputType = "smcat" | "json" | "scxml";
+
+export type OutputType =
+  | "ast"
+  | "dot"
+  | "eps"
+  | "json"
+  | "oldeps"
+  | "oldps"
+  | "oldps2"
+  | "oldsvg"
+  | "pdf"
+  | "png"
+  | "ps"
+  | "ps2"
+  | "scjson"
+  | "scxml"
+  | "smcat"
+  | "svg";
+
+export type EngineType = "dot" | "circo" | "fdp" | "neato" | "osage" | "twopi";
+
+export type DirectionType =
+  | "top-down"
+  | "bottom-top"
+  | "left-right"
+  | "right-left";
+
+export type dotAttributesType = {
+  name: string;
+  value: string;
+}[];
+
+export interface IBaseRenderOptions {
+  /**
+   * How to interpret the input (defaults to 'smcat')
+   */
+  inputType?: InputType;
+  /**
+   * What renderer to use (defaults to 'svg')
+   */
+  outputType?: OutputType;
+  /**
+   * For the 'dot' renderer: what engine to use (defaults to 'dot')
+   */
+  engine?: EngineType;
+  /**
+   * For the 'dot' renderer: in what direction to plot the states
+   * (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/main/docs/desugar.md
+   */
+  desugar?: boolean;
+}
+
+export interface IRenderOptions extends IBaseRenderOptions {
+  /**
+   * For the 'dot' renderer: Graph attributes to the engine
+   */
+  dotGraphAttrs?: dotAttributesType;
+  /**
+   * For the 'dot' renderer: Node attributes to the engine
+   */
+  dotNodeAttrs?: dotAttributesType;
+  /**
+   * For the 'dot' renderer: Edge attributes to the engine
+   */
+  dotEdgeAttrs?: dotAttributesType;
+  /**
+   * On nodejs don't display the warning that GraphViz 'dot'
+   * can't be found and we're falling back to wasm
+   */
+  noDotNativeWarning?: boolean;
+}
+
+export type StringRenderFunctionType = (
+  pStateMachine: IStateMachine,
+  pOptions?: IRenderOptions,
+) => string;
+
+export type WhateverRenderFunctionType = (
+  pStateMachine: IStateMachine,
+  pOptions?: IRenderOptions,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+) => any;
+
+export type RenderFunctionType =
+  | StringRenderFunctionType
+  | WhateverRenderFunctionType;
+
+/**
+ * Translates the input script to an output script.
+ *
+ * @param pScript     The script to translate
+ * @param pOptions    options influencing parsing & rendering.
+ *                    See below for the complete list.
+ * @return            the string with the rendered content if
+ *                    no error was found
+ * @throws {Error}    If an error occurred and no callback
+ *                    function was passed: the error
+ *
+ * Options: see https://github.com/sverweij/state-machine-cat/docs/api.md
+ *
+ */
+export function render(
+  pScript: IStateMachine | string,
+  pOptions: IRenderOptions,
+): string;