scjson 0.2.0 → 0.3.0

package/README.md

@@ -2,6 +2,8 @@
 
 This directory contains the JavaScript implementation of **scjson**, a format for representing SCXML state machines in JSON. The package provides a command line interface to convert between `.scxml` and `.scjson` files and to validate documents against the project's schema.
 
+For details on how SCXML elements are inferred during conversion see [INFERENCE.md](https://github.com/SoftOboros/scjson/blob/main/INFERENCE.md).
+
 The package includes typescript types for the functions and default functions to return each.
 
 ## Installation
@@ -74,6 +76,14 @@ const { xmlToJson, jsonToXml } = require('scjson');
 import { xmlToJson, jsonToXml }from "scjson/browser"
 ```
 
+## Shared Converters
+Both the Node and browser builds use the same conversion logic exposed in
+`scjson/converters`. You can import these helpers directly if you need access to
+the utility functions used by the CLI and browser modules.
+```js
+import { xmlToJson, jsonToXml } from 'scjson/converters';
+```
+
 ## Axios Endpoint Example
 ```typescript
 import axios from "axios"
@@ -122,6 +132,177 @@ export const sendNewScxml = () => {
 
 ```
 
+## Known Issues
+None at this time.
+
+Operational conformance testing is performed via [uber_test.py](https://github.com/SoftOboros/scjson/blob/engine/py/uber_test.py)
+```bash
+/py# python uber_test.py -l javascript 2>&1 | tee test.log
+```
+Note: [uber_test.py](https://github.com/SoftOboros/scjson/blob/main/py/uber_test.py) applies all scxml files in [Zhornyak's ScxmlEditor-Tutorial](https://alexzhornyak.github.io/ScxmlEditor-Tutorial/) which provides a robest set of scxml test vectors useful for standard compliance verification.  This is the only file in the test suite which fails to verify round-trip.
+
+
+### `scjson/props`
+
+### Enums
+
+Each enumeration represents a restricted string set used by SCXML. The values
+shown below mirror those defined in the SCJSON schema.
+
+enums use this pattern to all static and dynamic portions to be treated separately,
+but mapped to the same name.
+```typescript
+export const BooleanDatatypeProps = {
+    False: "false",
+    True: "true",
+} as const;
+
+export type BooleanDatatypeProps = typeof BooleanDatatypeProps[keyof typeof BooleanDatatypeProps];
+```
+
+- `AssignTypeDatatypeProps` – how the `<assign>` element manipulates the datamodel.
+  Values: `replacechildren`, `firstchild`, `lastchild`, `previoussibling`,
+  `nextsibling`, `replace`, `delete`, `addattribute`.
+- `BindingDatatypeProps` – determines if datamodel variables are bound `early` or
+  `late` during execution.
+- `BooleanDatatypeProps` – boolean attribute values `true` or `false`.
+- `ExmodeDatatypeProps` – processor execution mode, either `lax` or `strict`.
+- `HistoryTypeDatatypeProps` – type of `<history>` state: `shallow` or `deep`.
+- `TransitionTypeDatatypeProps` – whether a `<transition>` is `internal` or
+  `external`.
+
+### Common Types
+
+Several generated classes share generic helper fields:
+
+- `other_attributes`: `Record<str, str>` capturing additional XML attributes from
+  foreign namespaces.
+- `other_element`: `list[object]` allowing untyped child nodes from other
+  namespaces to be preserved.
+- `content`: `list[object]` used when elements permit mixed or wildcard
+  content.
+
+
+### Document / Object Types
+Plain typescript types without runtime validation.
+
+- `AssignProps` `AssignArray` – update a datamodel location with an expression or value.
+- `CancelProps` `CancelArray` – cancel a pending `<send>` operation.
+- `ContentProps` `ContentArray` – inline payload used by `<send>` and `<invoke>`.
+- `DataProps` `DataArray` – represents a single datamodel variable.
+- `DatamodelProps` `DatamodelArray` – container for one or more `<data>` elements.
+- `DonedataProps` `DonedataArray`  – payload returned when a `<final>` state is reached.
+- `ElseProps` – fallback branch for `<if>` conditions.
+- `ElseifProps` – conditional branch following an `<if>`.
+- `FinalProps` `FinalArray` – marks a terminal state in the machine.
+- `FinalizeProps` `FinalizeArray` – executed after an `<invoke>` completes.
+- `ForeachProps` `ForeachArray` – iterate over items within executable content.
+- `HistoryProps` `HistoryArray` – pseudostate remembering previous active children.
+- `IfProps` `IfArray` – conditional execution block.
+- `InitialProps` `InitialArray` – starting state within a compound state.
+- `InvokeProps` `InvokeArray` – run an external process or machine.
+- `LogProps` `LogArray` – diagnostic output statement.
+- `OnentryProps` `OnentryArray` – actions performed when entering a state.
+- `OnexitProps` `OnexitArray` – actions performed when leaving a state.
+- `ParallelProps` `ParallelArray` – coordinates concurrent regions.
+- `ParamProps` `ParamArray` – parameter passed to `<invoke>` or `<send>`.
+- `RaiseProps` `RaiseArray` – raise an internal event.
+- `ScriptProps` `ScriptArray` – inline executable script.
+- `ScxmlProps` – root element of an SCJSON document.
+- `SendProps` `SendArray` – dispatch an external event.
+- `StateProps` `StateArray` – basic state node.
+- `TransitionProps` `TransitionArray` – edge between states triggered by events.
+
+### Object Management
+- Kind - unique marker for each of the types.
+```typescript
+export type Kind = "number" | "string" | "record<string, object>" | "number[]" | "string[]"
+                   | "record<string, object>[]" | "assign" | "assigntypedatatype" | "bindingdatatype" | "booleandatatype"
+                   | "cancel" | "content" | "data" | "datamodel" | "donedata" | "else" | "elseif"
+                   | "exmodedatatype" | "final" | "finalize" | "foreach" | "history" | "historytypedatatype" | "if"
+                   | "initial" | "invoke" | "log" | "onentry" | "onexit" | "parallel" | "param" | "raise"
+                   | "script" | "scxml" | "send" | "state" | "transition" | "transitiontypedatatype"
+                   | "assignarray" | "cancelarray" | "contentarray" | "dataarray" | "datamodelarray"
+                   | "donedataarray" | "finalarray" | "finalizearray" | "foreacharray" | "historyarray" | "ifarray"
+                   | "initialarray" | "invokearray" | "logarray" | "onentryarray" | "onexitarray" | "parallelarray"
+                   | "paramarray" | "raisearray" | "scriptarray" | "sendarray" | "statearray" | "transitionarray";
+```
+- PropsUnion - a union of the types used in the scxml data model
+```typescript
+export type PropsUnion = null | string | number | Record<string, object> | string[] | number[]
+                         | Record<string, object>[] | AssignProps | AssignTypeDatatypeProps | BindingDatatypeProps
+                         | BooleanDatatypeProps | CancelProps | ContentProps | DataProps | DatamodelProps | DonedataProps
+                         | ElseProps | ElseifProps | ExmodeDatatypeProps | FinalProps | FinalizeProps | ForeachProps
+                         | HistoryProps | HistoryTypeDatatypeProps | IfProps | InitialProps | InvokeProps | LogProps
+                         | OnentryProps | OnexitProps | ParallelProps | ParamProps | RaiseProps | ScriptProps
+                         | ScxmlProps | SendProps | StateProps | TransitionProps | TransitionTypeDatatypeProps
+                         | AssignArray | CancelArray | ContentArray | DataArray | DatamodelArray | DonedataArray
+                         | FinalArray | FinalizeArray | ForeachArray | HistoryArray | IfArray | InitialArray
+                         | InvokeArray | LogArray | OnentryArray | OnexitArray | ParallelArray | ParamArray
+                         | RaiseArray | ScriptArray | SendArray | StateArray | TransitionArray;
+```
+- KindMap - maps string name to type for the objects used in the scxml data model
+```typescript
+export type KindMap = {
+    assign: AssignProps
+    assignarray: AssignArray
+    assigntypedatatype: AssignTypeDatatypeProps
+    bindingdatatype: BindingDatatypeProps
+    booleandatatype: BooleanDatatypeProps
+    cancel: CancelProps
+    cancelarray: CancelArray
+    content: ContentProps
+    contentarray: ContentArray
+    data: DataProps
+    dataarray: DataArray
+    datamodel: DatamodelProps
+    datamodelarray: DatamodelArray
+    donedata: DonedataProps
+    donedataarray: DonedataArray
+    else: ElseProps
+    elseif: ElseifProps
+    exmodedatatype: ExmodeDatatypeProps
+    final: FinalProps
+    finalarray: FinalArray
+    finalize: FinalizeProps
+    finalizearray: FinalizeArray
+    foreach: ForeachProps
+    foreacharray: ForeachArray
+    history: HistoryProps
+    historyarray: HistoryArray
+    historytypedatatype: HistoryTypeDatatypeProps
+    if: IfProps
+    ifarray: IfArray
+    initial: InitialProps
+    initialarray: InitialArray
+    invoke: InvokeProps
+    invokearray: InvokeArray
+    log: LogProps
+    logarray: LogArray
+    onentry: OnentryProps
+    onentryarray: OnentryArray
+    onexit: OnexitProps
+    onexitarray: OnexitArray
+    parallel: ParallelProps
+    parallelarray: ParallelArray
+    param: ParamProps
+    paramarray: ParamArray
+    raise: RaiseProps
+    raisearray: RaiseArray
+    script: ScriptProps
+    scriptarray: ScriptArray
+    scxml: ScxmlProps
+    send: SendProps
+    sendarray: SendArray
+    state: StateProps
+    statearray: StateArray
+    transition: TransitionProps
+    transitionarray: TransitionArray
+    transitiontypedatatype: TransitionTypeDatatypeProps
+}
+```
+
+
 ### Other Resources
 github: [https://github.com/SoftOboros/scjson]
 ```bash
@@ -132,9 +313,14 @@ git clone git@github.com:SoftOboros/scjson.git
 gh repo clone SoftOboros/scjson
 ```
 
-pypi: [https://www.npmjs.com/package/scjson]
+pypi: [https://pypi.org/project/scjson/]
 ```bash
-npm install scjson
+pip install scjson
+```
+
+cargo: [https://crates.io/crates/scjson]
+```bash
+cargo install scjson
 ```
 
 dockerhub: [https://hub.docker.com/r/iraa/scjson]
@@ -144,4 +330,4 @@ docker pull iraa/scjson:latest
 ```
 
 
-All source code in this directory is released under the BSD\u00A01-Clause license. See `LICENSE` and `LEGAL.md` for details.
+All source code in this directory is released under the BSD\u00A01-Clause license. See [LICENSE](./LICENSE) and [LEGAL.md](./LEGAL.md) for details.

package/bin/scjson.js

@@ -7,5 +7,5 @@
  * Licensed under the BSD 1-Clause License.
  */
 
-const { program } = require('../index.js');
+const { program } = require('../dist/index.js');
 program.parse(process.argv);

package/dist/browser.cjs

@@ -0,0 +1,12 @@
+"use strict";
+/**
+ * Agent Name: js-browser-cjs
+ *
+ * Part of the scjson project.
+ * Developed by Softoboros Technology Inc.
+ * Licensed under the BSD 1-Clause License.
+ */
+/**
+ * @file CommonJS wrapper exporting the core converters.
+ */
+module.exports = require('./converters.js');

package/dist/browser.d.cts

@@ -0,0 +1,2 @@
+declare const _exports: typeof import("./converters.js");
+export = _exports;

package/dist/browser.d.mts

@@ -0,0 +1,6 @@
+export const xmlToJson: typeof core.xmlToJson;
+export const jsonToXml: typeof core.jsonToXml;
+export const removeEmpty: typeof core.removeEmpty;
+export const normaliseKeys: typeof core.normaliseKeys;
+export const ensureArrays: typeof core.ensureArrays;
+import core from './converters.js';

package/dist/browser.mjs

@@ -0,0 +1,12 @@
+/**
+ * Agent Name: js-browser
+ *
+ * Part of the scjson project.
+ * Developed by Softoboros Technology Inc.
+ * Licensed under the BSD 1-Clause License.
+ */
+/**
+ * @file Browser friendly utilities re-exporting the core converters.
+ */
+import core from './converters.js';
+export const { xmlToJson, jsonToXml, removeEmpty, normaliseKeys, ensureArrays } = core;

package/dist/converters.d.ts

@@ -0,0 +1,191 @@
+/**
+ * Convert an SCXML string to scjson.
+ *
+ * @param {string} xmlStr - XML input.
+ * @param {boolean} [omitEmpty=true] - Remove empty values when true.
+ * @returns {{result: string, valid: boolean, errors: object[]|null}} Conversion outcome.
+ *
+ * Removes the XML namespace attribute and injects default values
+ * expected by the schema.
+ */
+export function xmlToJson(xmlStr: string, omitEmpty?: boolean): {
+    result: string;
+    valid: boolean;
+    errors: object[] | null;
+};
+/**
+ * Convert a scjson string to SCXML.
+ *
+ * Removes empty objects so that the generated XML does not include spurious
+ * `<content/>` elements. Nested SCXML documents are also normalised after
+ * restoring attribute names to ensure no stray wrapper nodes remain. The
+ * function validates the input against the SCJSON schema before conversion.
+ *
+ * @param {string} jsonStr - JSON input.
+ * @returns {{result: string, valid: boolean, errors: object[]|null}} Conversion outcome.
+ */
+export function jsonToXml(jsonStr: string): {
+    result: string;
+    valid: boolean;
+    errors: object[] | null;
+};
+/**
+ * Remove nulls and empty containers from values recursively.
+ *
+ * Certain keys like ``final`` must always be preserved even when they
+ * would otherwise be considered empty. The caller provides the key so we
+ * can decide whether to keep an empty object.
+ *
+ * @param {*} value - Candidate value.
+ * @param {string} [key] - Key name associated with ``value`` in the parent.
+ * @returns {*} Sanitised value.
+ */
+export function removeEmpty(value: any, key?: string): any;
+/**
+ * Recursively rename XML parser keys to match the scjson schema.
+ *
+ * - Attribute names prefixed with ``@_`` are stripped of the prefix.
+ * - Text content keys ``#text`` are converted to a ``content`` array.
+ *
+ * @param {object|Array} value - Parsed value to normalise.
+ * @returns {object|Array} Normalised value.
+ */
+export function normaliseKeys(value: object | any[]): object | any[];
+/**
+ * Recursively normalise values that should be arrays.
+ *
+ * @param {object} obj - Parsed object to adjust in place.
+ */
+export function ensureArrays(obj: object, parent: any): void;
+/**
+ * Normalise script elements after parsing.
+ *
+ * Ensures that each ``script`` entry is an object with a ``content`` array
+ * as required by the schema.
+ *
+ * @param {object|Array} value - Parsed object to adjust in place.
+ */
+export function fixScripts(value: object | any[]): void;
+/**
+ * Normalise nested SCXML documents within invoke content.
+ *
+ * XML parser output represents nested ``<scxml>`` elements as a key
+ * named ``scxml`` inside the ``content`` element. The reference
+ * Python implementation instead stores the nested machine under a
+ * ``content`` array. This helper replicates that behaviour.
+ *
+ * @param {object|Array} value - Parsed object to adjust in place.
+ */
+export function fixNestedScxml(value: object | any[]): void;
+/**
+ * Apply default values for assign elements.
+ *
+ * The scjson schema expects ``assign`` elements to include a
+ * ``type_value`` attribute with a default of ``replacechildren``.
+ * This helper ensures the attribute is present when not specified in
+ * the original XML.
+ *
+ * @param {object|Array} value - Parsed object to adjust in place.
+ */
+export function fixAssignDefaults(value: object | any[]): void;
+/**
+ * Apply default values for send elements.
+ *
+ * The SCXML specification defines ``type="scxml"`` and ``delay="0s"``
+ * as defaults. This mirrors the behaviour of the Python converter so
+ * round-trip conversions remain consistent.
+ *
+ * @param {object|Array} value - Parsed object to adjust in place.
+ */
+export function fixSendDefaults(value: object | any[]): void;
+/**
+ * Normalise inline content elements under ``send``.
+ *
+ * ``<content>`` children inside ``<send>`` should always be objects with a
+ * ``content`` array according to the scjson schema. The fast-xml-parser library
+ * collapses simple text nodes to strings which leads to mismatches when
+ * compared with the Python implementation. This helper wraps such strings in an
+ * object structure.
+ *
+ * @param {object|Array} value - Parsed object to adjust in place.
+ */
+export function fixSendContent(value: object | any[]): void;
+/**
+ * Normalise inline content elements under ``donedata``.
+ *
+ * ``<content>`` children inside ``<donedata>`` should always be objects with a
+ * ``content`` array so that round-trips match the reference Python
+ * implementation. Strings are wrapped in an object accordingly.
+ *
+ * @param {object|Array} value - Parsed object to adjust in place.
+ */
+export function fixDonedataContent(value: object | any[]): void;
+/**
+ * Convert a canonical content object back into XML element format.
+ *
+ * ``jsonToXml`` relies on this helper to rebuild inline XML stored under
+ * ``<data>`` elements. Objects with ``qname``, ``attributes``, and ``children``
+ * fields are translated to the structure expected by ``fast-xml-parser``.
+ *
+ * @param {object} node - Canonical content object.
+ * @returns {object} XML builder structure keyed by element name.
+ */
+export function restoreDataNode(node: object): object;
+/**
+ * Collapse nested ``content`` wrappers created during parsing.
+ *
+ * A ``content`` array may contain a single object with its own
+ * ``content`` array when the original XML element only held text.
+ * This helper flattens that structure so that round-tripping through
+ * XML does not introduce spurious elements.
+ *
+ * @param {object|Array} value - Parsed object to adjust in place.
+ */
+export function flattenContent(value: object | any[]): void;
+/**
+ * Split whitespace-separated token attributes.
+ *
+ * Attributes such as ``initial`` and ``target`` can contain multiple
+ * identifiers separated by spaces. This function mirrors the Python
+ * implementation by splitting those values into arrays before further
+ * normalisation.
+ *
+ * @param {object|Array} value - Parsed value to adjust in place.
+ */
+export function splitTokenAttrs(value: object | any[], parent: any): void;
+/**
+ * Convert ``else`` elements to the ``else_value`` schema key.
+ *
+ * Empty ``<else/>`` tags become an object literal so they survive
+ * subsequent calls to :func:`removeEmpty`.
+ *
+ * @param {object|Array} value - Parsed object to adjust in place.
+ */
+export function fixEmptyElse(value: object | any[]): void;
+/**
+ * Remove transition elements directly under the <scxml> root.
+ *
+ * The reference Python implementation ignores these top level
+ * transitions entirely. To maintain parity we drop them during
+ * conversion.
+ *
+ * @param {object} obj - Parsed SCXML object.
+ */
+export function stripRootTransitions(obj: object): void;
+/**
+ * Remove namespace URIs from ``qname`` fields.
+ *
+ * @param {object|Array} value - Parsed object to adjust in place.
+ */
+export function stripQnameNs(value: object | any[]): void;
+/**
+ * Reorder SCXML object keys to match canonical output.
+ *
+ * ``datamodel`` elements and the attributes ``version`` and
+ * ``datamodel_attribute`` are appended to the end of their
+ * respective objects so that JSON generated by this converter
+ * matches the reference Python implementation.
+ *
+ * @param {object|Array} value - Parsed object to adjust in place.
+ */
+export function reorderScxml(value: object | any[]): void;