scjson 0.1.5 → 0.1.7

package/LEGAL.md

@@ -0,0 +1,7 @@
+# Legal Information
+
+This package is distributed as part of the **scjson** project. All original code in this directory is released under the BSD\u00A01-Clause license.
+
+The package references assets from the W3C SCXML specification and includes examples derived from Alex Zhornyak's *SCXML Editor Tutorial*. Those third-party materials remain under their respective licenses as documented in the repository's top-level `LEGAL.md` file.
+
+For complete license terms please consult that document.

package/LICENSE

@@ -0,0 +1,21 @@
+BSD 1-Clause License
+
+Copyright (c) 2025, Softoboros Technology Inc.
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice,
+   this list of conditions and the following disclaimer.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -0,0 +1,54 @@
+# 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.
+
+## Installation
+
+```bash
+npm install scjson
+```
+
+You can also install from a checkout of this repository:
+
+```bash
+cd js && npm install
+```
+
+## Command Line Usage
+
+After installation the `scjson` command is available:
+
+```bash
+# 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
+```
+
+### Other Resources
+github: [https://github.com/SoftOboros/scjson]
+```bash
+git clone https://github.com/SoftOboros/scjson.git
+
+git clone git@github.com:SoftOboros/scjson.git
+
+gh repo clone SoftOboros/scjson
+```
+
+pypi: [https://www.npmjs.com/package/scjson]
+```bash
+npm install scjson
+```
+
+dockerhub: [https://hub.docker.com/r/iraa/scjson]
+(Full development environment for all supported languages)
+```bash
+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.

package/browser.mjs

@@ -0,0 +1,92 @@
+/**
+ * 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' assert { type: '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 });
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "scjson",
-  "version": "0.1.5",
-  "description": "Convert SCXML to/from scjson (JSON-based representation of state machines)",
+  "version": "0.1.7",
+  "description": "A JSON-based serialization of SCXML (State Chart XML) for modern tooling, interoperability, and education.",
   "keywords": [
     "scjson",
     "scxml",
@@ -27,13 +27,31 @@
   "engines": {
     "node": ">=18"
   },
+  "main": "index.js",
+  "type": "commonjs",
+  "exports": {
+    ".": "./index.js",
+    "./browser": "./browser.mjs"
+  },
+  "typesVersions": {
+    "*": {
+      "browser": [
+        "/types/scjson-browser.d.ts"
+      ]
+    }
+  },
   "files": [
     "bin/",
     "index.js",
-    "tests/"
+    "browser.mjs",
+    "types/scjson-browser.d.ts",
+    "tests/",
+    "README.md",
+    "LEGAL.md",
+    "LICENSE"
   ],
-  "main": "index.js",
-  "type": "module",
+  "module": "./browser.mjs",
+  "browser": "./browser.mjs",
   "publishConfig": {
     "access": "public"
   },
@@ -48,6 +66,7 @@
     "fast-xml-parser": "^5.2.5"
   },
   "devDependencies": {
-    "jest": "^30.0.4"
+    "jest": "^30.0.4",
+    "typescript": "^5.8.3"
   }
 }

package/types/scjson-browser.d.ts

@@ -0,0 +1,25 @@
+declare module 'scjson/browser' {
+  /**
+   * Recursively removes nulls, empty arrays/objects, and empty strings from a value.
+   * @param value Any input value (array, object, scalar).
+   * @returns Sanitized value or `undefined`.
+   */
+  export function removeEmpty(value: any): any;
+
+  /**
+   * Converts SCXML (as XML string) to SCJSON (as JSON string).
+   * @param xmlStr SCXML input as string.
+   * @param omitEmpty Optional: if true, removes empty/null fields (default: true).
+   * @returns Validated SCJSON as pretty-printed JSON string.
+   * @throws Error if validation fails.
+   */
+  export function xmlToJson(xmlStr: string, omitEmpty?: boolean): string;
+
+  /**
+   * Converts SCJSON (as JSON string) to SCXML (as XML string).
+   * @param jsonStr SCJSON input as string.
+   * @returns Valid SCXML string.
+   * @throws Error if validation fails.
+   */
+  export function jsonToXml(jsonStr: string): string;
+}