scjson 0.2.0 → 0.3.0

package/scjson.schema.json

@@ -1,6 +1,7 @@
 {
     "$defs": {
         "Assign": {
+            "description": "update a datamodel location with an expression or value.",
             "properties": {
                 "location": {
                     "title": "Location",
@@ -87,6 +88,7 @@
             "type": "string"
         },
         "Cancel": {
+            "description": "cancel a pending `<send>` operation.",
             "properties": {
                 "other_element": {
                     "items": {},
@@ -129,13 +131,22 @@
             "type": "object"
         },
         "Content": {
+            "description": "inline payload used by `<send>` and `<invoke>`.",
             "properties": {
-                "other_attributes": {
-                    "additionalProperties": {
-                        "type": "string"
-                    },
-                    "title": "Other Attributes",
-                    "type": "object"
+                "content": {
+                    "anyOf": [
+                        {
+                            "items": {
+                                "$ref": "#/$defs/Scxml"
+                            },
+                            "type": "array"
+                        },
+                        {
+                            "type": "null"
+                        }
+                    ],
+                    "default": null,
+                    "title": "Content"
                 },
                 "expr": {
                     "anyOf": [
@@ -149,16 +160,19 @@
                     "default": null,
                     "title": "Expr"
                 },
-                "content": {
-                    "items": {},
-                    "title": "Content",
-                    "type": "array"
+                "other_attributes": {
+                    "additionalProperties": {
+                        "type": "string"
+                    },
+                    "title": "Other Attributes",
+                    "type": "object"
                 }
             },
             "title": "Content",
             "type": "object"
         },
         "Data": {
+            "description": "represents a single datamodel variable.",
             "properties": {
                 "id": {
                     "title": "Id",
@@ -208,6 +222,7 @@
             "type": "object"
         },
         "Datamodel": {
+            "description": "container for one or more `<data>` elements.",
             "properties": {
                 "data": {
                     "items": {
@@ -233,6 +248,7 @@
             "type": "object"
         },
         "Donedata": {
+            "description": "payload returned when a `<final>` state is reached.",
             "properties": {
                 "content": {
                     "anyOf": [
@@ -264,6 +280,7 @@
             "type": "object"
         },
         "Else": {
+            "description": "fallback branch for `<if>` conditions.",
             "properties": {
                 "other_attributes": {
                     "additionalProperties": {
@@ -277,6 +294,7 @@
             "type": "object"
         },
         "Elseif": {
+            "description": "conditional branch following an `<if>`.",
             "properties": {
                 "cond": {
                     "title": "Cond",
@@ -306,6 +324,7 @@
             "type": "string"
         },
         "Final": {
+            "description": "marks a terminal state in the machine.",
             "properties": {
                 "onentry": {
                     "items": {
@@ -357,6 +376,7 @@
             "type": "object"
         },
         "Finalize": {
+            "description": "executed after an `<invoke>` completes.",
             "properties": {
                 "other_element": {
                     "items": {},
@@ -431,6 +451,7 @@
             "type": "object"
         },
         "Foreach": {
+            "description": "iterate over items within executable content.",
             "properties": {
                 "other_element": {
                     "items": {},
@@ -529,6 +550,7 @@
             "type": "object"
         },
         "History": {
+            "description": "pseudostate remembering previous active children.",
             "properties": {
                 "other_element": {
                     "items": {},
@@ -576,6 +598,7 @@
             "type": "object"
         },
         "HistoryTypeDatatype": {
+            "description": "type of `<history>` state: `shallow` or `deep`.",
             "enum": [
                 "shallow",
                 "deep"
@@ -584,6 +607,7 @@
             "type": "string"
         },
         "If": {
+            "description": "conditional execution block.",
             "properties": {
                 "other_element": {
                     "items": {},
@@ -687,6 +711,7 @@
             "type": "object"
         },
         "Initial": {
+            "description": "starting state within a compound state.",
             "properties": {
                 "other_element": {
                     "items": {},
@@ -711,6 +736,7 @@
             "type": "object"
         },
         "Invoke": {
+            "description": "run an external process or machine.",
             "properties": {
                 "content": {
                     "items": {
@@ -831,6 +857,7 @@
             "type": "object"
         },
         "Log": {
+            "description": "diagnostic output statement.",
             "properties": {
                 "other_element": {
                     "items": {},
@@ -873,6 +900,7 @@
             "type": "object"
         },
         "Onentry": {
+            "description": "actions performed when entering a state.",
             "properties": {
                 "other_element": {
                     "items": {},
@@ -947,6 +975,7 @@
             "type": "object"
         },
         "Onexit": {
+            "description": "actions performed when leaving a state.",
             "properties": {
                 "other_element": {
                     "items": {},
@@ -1021,6 +1050,7 @@
             "type": "object"
         },
         "Parallel": {
+            "description": "coordinates concurrent regions.",
             "properties": {
                 "onentry": {
                     "items": {
@@ -1107,6 +1137,7 @@
             "type": "object"
         },
         "Param": {
+            "description": "parameter passed to `<invoke>` or `<send>`.",
             "properties": {
                 "other_element": {
                     "items": {},
@@ -1156,6 +1187,7 @@
             "type": "object"
         },
         "Raise": {
+            "description": "raise an internal event.",
             "properties": {
                 "event": {
                     "title": "Event",
@@ -1176,6 +1208,7 @@
             "type": "object"
         },
         "Script": {
+            "description": "inline executable script.",
             "properties": {
                 "src": {
                     "anyOf": [
@@ -1205,7 +1238,120 @@
             "title": "Script",
             "type": "object"
         },
+        "Scxml": {
+            "description": "root element of an SCJSON document.",
+            "properties": {
+                "state": {
+                    "items": {
+                        "$ref": "#/$defs/State"
+                    },
+                    "title": "State",
+                    "type": "array"
+                },
+                "parallel": {
+                    "items": {
+                        "$ref": "#/$defs/Parallel"
+                    },
+                    "title": "Parallel",
+                    "type": "array"
+                },
+                "final": {
+                    "items": {
+                        "$ref": "#/$defs/Final"
+                    },
+                    "title": "Final",
+                    "type": "array"
+                },
+                "datamodel": {
+                    "items": {
+                        "$ref": "#/$defs/Datamodel"
+                    },
+                    "title": "Datamodel",
+                    "type": "array"
+                },
+                "script": {
+                    "items": {
+                        "$ref": "#/$defs/Script"
+                    },
+                    "title": "Script",
+                    "type": "array"
+                },
+                "other_element": {
+                    "items": {},
+                    "title": "Other Element",
+                    "type": "array"
+                },
+                "initial": {
+                    "items": {
+                        "type": "string"
+                    },
+                    "title": "Initial",
+                    "type": "array"
+                },
+                "name": {
+                    "anyOf": [
+                        {
+                            "type": "string"
+                        },
+                        {
+                            "type": "null"
+                        }
+                    ],
+                    "default": null,
+                    "title": "Name"
+                },
+                "version": {
+                    "anyOf": [
+                        {
+                            "type": "number"
+                        },
+                        {
+                            "type": "string"
+                        }
+                    ],
+                    "default": "1.0",
+                    "title": "Version"
+                },
+                "datamodel_attribute": {
+                    "default": "null",
+                    "title": "Datamodel Attribute",
+                    "type": "string"
+                },
+                "binding": {
+                    "anyOf": [
+                        {
+                            "$ref": "#/$defs/BindingDatatype"
+                        },
+                        {
+                            "type": "null"
+                        }
+                    ],
+                    "default": null
+                },
+                "exmode": {
+                    "anyOf": [
+                        {
+                            "$ref": "#/$defs/ExmodeDatatype"
+                        },
+                        {
+                            "type": "null"
+                        }
+                    ],
+                    "default": null
+                },
+                "other_attributes": {
+                    "additionalProperties": {
+                        "type": "string"
+                    },
+                    "title": "Other Attributes",
+                    "type": "object"
+                }
+            },
+            "title": "Scxml",
+            "type": "object"
+        },
         "Send": {
+            "description": "dispatch an external event.",
             "properties": {
                 "content": {
                     "items": {
@@ -1356,6 +1502,7 @@
             "type": "object"
         },
         "State": {
+            "description": "basic state node.",
             "properties": {
                 "onentry": {
                     "items": {
@@ -1463,6 +1610,7 @@
             "type": "object"
         },
         "Transition": {
+            "description": "edge between states triggered by events.",
             "properties": {
                 "other_element": {
                     "items": {},
@@ -1588,6 +1736,7 @@
             "type": "string"
         }
     },
+    "$ref": "#/$defs/Scxml",
     "properties": {
         "state": {
             "items": {
@@ -1694,7 +1843,5 @@
             "title": "Other Attributes",
             "type": "object"
         }
-    },
-    "title": "Scxml",
-    "type": "object"
+    }
 }

package/browser.cjs

@@ -1,243 +0,0 @@
-/**
- * Agent Name: js-cli
- *
- * Part of the scjson project.
- * Developed by Softoboros Technology Inc.
- * Licensed under the BSD 1-Clause License.
- */
-
-const fs = require('fs');
-const path = require('path');
-const { Command } = require('commander');
-const { XMLParser, XMLBuilder } = require('fast-xml-parser');
-const Ajv = require('ajv');
-
-const program = new Command();
-const schema = require('./scjson.schema.json');
-
-/**
- * Remove nulls and empty containers from values recursively.
- *
- * @param {*} value - Candidate value.
- * @returns {*} Sanitised value.
- */
-function removeEmpty(value) {
-  if (Array.isArray(value)) {
-    const arr = value.map(removeEmpty).filter(v => v !== undefined);
-    return arr.length > 0 ? arr : undefined;
-  }
-  if (value && typeof value === 'object') {
-    const obj = {};
-    for (const [k, v] of Object.entries(value)) {
-      const r = removeEmpty(v);
-      if (r !== undefined) obj[k] = r;
-    }
-    return Object.keys(obj).length > 0 ? obj : undefined;
-  }
-  if (value === null) {
-    return undefined;
-  }
-  if (value === '') {
-    return undefined;
-  }
-  return value;
-}
-
-const ajv = new Ajv({ useDefaults: true, strict: false });
-const validate = ajv.compile(schema);
-
-/**
- * Convert an SCXML string to scjson.
- *
- * @param {string} xmlStr - XML input.
- * @param {boolean} [omitEmpty=true] - Remove empty values when true.
- * @returns {string} JSON representation.
- *
- * Removes the XML namespace attribute and injects default values
- * expected by the schema.
- */
-function xmlToJson(xmlStr, omitEmpty = true) {
-  const parser = new XMLParser({ ignoreAttributes: false });
-  let obj = parser.parse(xmlStr);
-  if (obj.scxml) {
-    obj = obj.scxml;
-  }
-  if (omitEmpty) {
-    obj = removeEmpty(obj) || {};
-  }
-  if (obj['@_xmlns']) {
-    delete obj['@_xmlns'];
-  }
-  if (obj.version === undefined) {
-    obj.version = 1.0;
-  }
-  if (obj.datamodel_attribute === undefined) {
-    obj.datamodel_attribute = 'null';
-  }
-  if (!validate(obj)) {
-    throw new Error('Invalid scjson');
-  }
-  if (omitEmpty) {
-    obj = removeEmpty(obj) || {};
-  }
-  return JSON.stringify(obj, null, 2);
-}
-
-/**
- * Convert a scjson string to SCXML.
- *
- * @param {string} jsonStr - JSON input.
- * @returns {string} XML output.
- */
-function jsonToXml(jsonStr) {
-  const builder = new XMLBuilder({ ignoreAttributes: false, format: true });
-  const obj = JSON.parse(jsonStr);
-  if (!validate(obj)) {
-    throw new Error('Invalid scjson');
-  }
-  return builder.build({ scxml: obj });
-}
-
-program
-  .name('scjson')
-  .description('SCXML <-> scjson converter and validator');
-
-program
-  .command('validate')
-  .description('validate a scjson or SCXML file by round-tripping it')
-  .argument('<file>', 'file path')
-  .option('-r, --recursive', 'recurse into directories')
-  .action((file, options) => {
-    const src = path.resolve(file);
-    let success = true;
-
-    function validateFile(p) {
-      const data = fs.readFileSync(p, 'utf8');
-      try {
-        if (p.endsWith('.scxml')) {
-          const json = xmlToJson(data);
-          jsonToXml(json);
-        } else if (p.endsWith('.scjson')) {
-          const xml = jsonToXml(data);
-          xmlToJson(xml);
-        } else {
-          return;
-        }
-      } catch (e) {
-        console.error(`Validation failed for ${p}: ${e.message}`);
-        success = false;
-      }
-    }
-
-    if (fs.statSync(src).isDirectory()) {
-      const pattern = options.recursive ? '**/*' : '*';
-      const files = require('glob').sync(pattern, { cwd: src, nodir: true });
-      files.forEach(f => validateFile(path.join(src, f)));
-    } else {
-      validateFile(src);
-    }
-
-    if (!success) {
-      process.exitCode = 1;
-    }
-  });
-
-function convertDirectoryJson(inputDir, outputDir, recursive, verify, keepEmpty) {
-  const pattern = recursive ? '**/*.scxml' : '*.scxml';
-  const files = require('glob').sync(pattern, { cwd: inputDir, nodir: true });
-  files.forEach(f => {
-    const src = path.join(inputDir, f);
-    const dest = path.join(outputDir, f.replace(/\.scxml$/, '.scjson'));
-    convertScxmlFile(src, dest, verify, keepEmpty);
-  });
-}
-
-function convertDirectoryXml(inputDir, outputDir, recursive, verify, keepEmpty) {
-  const pattern = recursive ? '**/*.scjson' : '*.scjson';
-  const files = require('glob').sync(pattern, { cwd: inputDir, nodir: true });
-  files.forEach(f => {
-    const src = path.join(inputDir, f);
-    const dest = path.join(outputDir, f.replace(/\.scjson$/, '.scxml'));
-    convertScjsonFile(src, dest, verify, keepEmpty);
-  });
-}
-
-function convertScxmlFile(src, dest, verify, keepEmpty) {
-  const xmlStr = fs.readFileSync(src, 'utf8');
-  try {
-    const jsonStr = xmlToJson(xmlStr, !keepEmpty);
-    if (verify) {
-      jsonToXml(jsonStr);
-    } else {
-      fs.mkdirSync(path.dirname(dest), { recursive: true });
-      fs.writeFileSync(dest, jsonStr);
-    }
-    if (verify) console.log(`Verified ${src}`);
-  } catch (e) {
-    console.error(`Failed to convert ${src}: ${e.message}`);
-  }
-}
-
-function convertScjsonFile(src, dest, verify) {
-  const jsonStr = fs.readFileSync(src, 'utf8');
-  try {
-    const xmlStr = jsonToXml(jsonStr);
-    if (verify) {
-      xmlToJson(xmlStr);
-    } else {
-      fs.mkdirSync(path.dirname(dest), { recursive: true });
-      fs.writeFileSync(dest, xmlStr);
-    }
-    if (verify) console.log(`Verified ${src}`);
-  } catch (e) {
-    console.error(`Failed to convert ${src}: ${e.message}`);
-  }
-}
-
-program
-  .command('json')
-  .argument('<path>', 'SCXML file or directory')
-  .option('-o, --output <path>', 'output file or directory')
-  .option('-r, --recursive', 'recurse into directories')
-  .option('-v, --verify', 'verify conversion without writing output')
-  .option('--keep-empty', 'keep null or empty items when producing JSON')
-  .action((p, opts) => {
-    const src = path.resolve(p);
-    const out = opts.output ? path.resolve(opts.output) : src;
-
-    if (fs.statSync(src).isDirectory()) {
-      convertDirectoryJson(src, out, opts.recursive, opts.verify, opts.keepEmpty);
-    } else {
-      const dest = opts.output && !opts.output.endsWith('.json') && !opts.output.endsWith('.scjson')
-        ? path.join(out, path.basename(src).replace(/\.scxml$/, '.scjson'))
-        : (opts.output || src.replace(/\.scxml$/, '.scjson'));
-      convertScxmlFile(src, dest, opts.verify, opts.keepEmpty);
-    }
-  });
-
-program
-  .command('xml')
-  .argument('<path>', 'scjson file or directory')
-  .option('-o, --output <path>', 'output file or directory')
-  .option('-r, --recursive', 'recurse into directories')
-  .option('-v, --verify', 'verify conversion without writing output')
-  .option('--keep-empty', 'keep null or empty items when producing JSON')
-  .action((p, opts) => {
-    const src = path.resolve(p);
-    const out = opts.output ? path.resolve(opts.output) : src;
-
-    if (fs.statSync(src).isDirectory()) {
-      convertDirectoryXml(src, out, opts.recursive, opts.verify, opts.keepEmpty);
-    } else {
-      const dest = opts.output && !opts.output.endsWith('.xml') && !opts.output.endsWith('.scxml')
-        ? path.join(out, path.basename(src).replace(/\.scjson$/, '.scxml'))
-        : (opts.output || src.replace(/\.scjson$/, '.scxml'));
-      convertScjsonFile(src, dest, opts.verify, opts.keepEmpty);
-    }
-  });
-
-if (require.main === module) {
-  program.parse(process.argv);
-}
-
-module.exports = { program, xmlToJson, jsonToXml };

package/browser.mjs

@@ -1,92 +0,0 @@
-/**
- * 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 for converting SCXML to scjson and back.
- */
-
-import { XMLParser, XMLBuilder } from 'fast-xml-parser';
-import Ajv from 'ajv';
-import schema from './scjson.schema.json';
-
-const ajv = new Ajv({ useDefaults: true, strict: false });
-const validate = ajv.compile(schema);
-
-/**
- * Remove nulls and empty containers from values recursively.
- *
- * @param {*} value - Candidate value.
- * @returns {*} Sanitised value.
- */
-export function removeEmpty(value) {
-  if (Array.isArray(value)) {
-    const arr = value.map(removeEmpty).filter(v => v !== undefined);
-    return arr.length > 0 ? arr : undefined;
-  }
-  if (value && typeof value === 'object') {
-    const obj = {};
-    for (const [k, v] of Object.entries(value)) {
-      const r = removeEmpty(v);
-      if (r !== undefined) obj[k] = r;
-    }
-    return Object.keys(obj).length > 0 ? obj : undefined;
-  }
-  if (value === null || value === '') {
-    return undefined;
-  }
-  return value;
-}
-
-/**
- * Convert an SCXML string to scjson.
- *
- * @param {string} xmlStr - XML input.
- * @param {boolean} [omitEmpty=true] - Remove empty values when true.
- * @returns {string} JSON representation.
- */
-export function xmlToJson(xmlStr, omitEmpty = true) {
-  const parser = new XMLParser({ ignoreAttributes: false });
-  let obj = parser.parse(xmlStr);
-  if (obj.scxml) {
-    obj = obj.scxml;
-  }
-  if (omitEmpty) {
-    obj = removeEmpty(obj) || {};
-  }
-  if (obj['@_xmlns']) {
-    delete obj['@_xmlns'];
-  }
-  if (obj.version === undefined) {
-    obj.version = 1.0;
-  }
-  if (obj.datamodel_attribute === undefined) {
-    obj.datamodel_attribute = 'null';
-  }
-  if (!validate(obj)) {
-    throw new Error('Invalid scjson');
-  }
-  if (omitEmpty) {
-    obj = removeEmpty(obj) || {};
-  }
-  return JSON.stringify(obj, null, 2);
-}
-
-/**
- * Convert a scjson string to SCXML.
- *
- * @param {string} jsonStr - JSON input.
- * @returns {string} XML output.
- */
-export function jsonToXml(jsonStr) {
-  const builder = new XMLBuilder({ ignoreAttributes: false, format: true });
-  const obj = JSON.parse(jsonStr);
-  if (!validate(obj)) {
-    throw new Error('Invalid scjson');
-  }
-  return builder.build({ scxml: obj });
-}