scjson

scjson logo

scjson JavaScript Package

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.

The package includes typescript types for the functions and default functions to return each.

Installation

npm install scjson

You can also install from a checkout of this repository:

cd js && npm install

Source Code - Multi-Language Support

[https://github.com/SoftOboros/scjson/]

Command Line Usage

After installation the scjson command is available:

# Convert a single file
scjson json path/to/machine.scxml

# Convert back to SCXML
scjson xml path/to/machine.scjson

# Validate recursively
scjson validate path/to/dir -r

Harness CLI (SCION)

The package also ships a harness CLI that executes SCXML using the SCION engine and emits JSONL traces compatible with compare tooling.

Install peer dependency:

npm i scion-core

Usage:

npx scjson-scion-trace -I path/to/chart.(scxml|scjson) -e path/to/events.jsonl [--xml]

Quick check (from this repo):

cd js
npm ci
npm run harness:sample

Flags:

Notes:

Conversion Functions

/**
 * xmlToJson
 * Convert an SCXML string to scjson.
 *
 * @param {string} xmlStr - XML input.
 * @param {boolean} [omitEmpty=true] - Remove empty values when true.
 * @returns {string} JSON representation.
 */

/**
 * jsonToXml
 * Convert a scjson string to SCXML.
 *
 * @param {string} jsonStr - JSON input.
 * @returns {string} XML output.
 */

Common JS Translate Usage

const { xmlToJson, jsonToXml } = require('scjson');

ESR translate usage

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.

import { xmlToJson, jsonToXml } from 'scjson/converters';

Axios Endpoint Example

import axios from "axios"
import * as scjson from "scjson/props"

// A function to creat a new doc with three states and transitions.
const newScxml = (): scjson.ScxmlProps => {
  const doc: scjson.ScxmlProps = scjson.defaultScxml();
  let state: scjson.StateProps = scjson.defaultState();
  let transition: scjson.TransitionProps = scjson.defaultTransition();
  doc.name = 'New State Machine';
  doc.exmode = scjson.ExmodeDatatypeProps.Lax;
  doc.binding = scjson.BindingDatatypeProps.Early;
  doc.initial.push('Start');
  state.id = 'Start';
  transition.target.push('Process');
  state.transition.push(transition);
  doc.state.push(state);
  state = scjson.defaultState();
  state.id = 'Process';
  transition = scjson.defaultTransition();
  transition.target.push('End');
  state.transition.push(transition);
  doc.state.push(state);
  state = scjson.defaultState();
  state.id = 'End';
  transition = scjson.defaultTransition();
  transition.target.push('Start');
  state.transition.push(transition);
  doc.state.push(state);
  return doc;
}

// Create Axios instance
const ax = axios.create({
  baseURL: "https://api.example.com/scxml",
  headers: { "Content-Type": "application/json" },
  withCredentials: true,
});

// Export a function to send the doc
export const sendNewScxml = () => {
  const doc = newScxml();
  ax.post('/newDoc', doc);
}

Known Issues

None at this time.

Operational conformance testing is performed via uber_test.py

/py# python uber_test.py -l javascript 2>&1 | tee test.log

Note: uber_test.py applies all scxml files in Zhornyak’s 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.

export const BooleanDatatypeProps = {
    False: "false",
    True: "true",
} as const;

export type BooleanDatatypeProps = typeof BooleanDatatypeProps[keyof typeof BooleanDatatypeProps];

Common Types

Several generated classes share generic helper fields:

Document / Object Types

Plain typescript types without runtime validation.

Object Management

Other Resources

github: [https://github.com/SoftOboros/scjson]

git clone https://github.com/SoftOboros/scjson.git

git clone git@github.com:SoftOboros/scjson.git

gh repo clone SoftOboros/scjson

pypi: [https://pypi.org/project/scjson/]

pip install scjson

cargo: [https://crates.io/crates/scjson]

cargo install scjson

dockerhub: [https://hub.docker.com/r/iraa/scjson] (Full development environment for all supported languages)

docker pull iraa/scjson:latest

All source code in this directory is released under the BSD 1-Clause license. See LICENSE and LEGAL.md for details.

This site is open source. Improve this page.