@genrojs/tytx 0.16.1

package/js/src/utils.js

@@ -0,0 +1,164 @@
+// Copyright 2025 Softwell S.r.l. - Licensed under Apache License 2.0
+/**
+ * TYTX Utilities.
+ *
+ * Provides:
+ * - walk: recursive data structure transformation
+ * - tytxEquivalent: semantic equivalence for roundtrip testing
+ */
+
+import { getTypeEntry, SUFFIX_TO_TYPE } from './registry.js';
+
+/**
+ * Encode a scalar value to TYTX string with suffix.
+ *
+ * @param {any} value - JavaScript scalar value (Decimal, Date, boolean, number)
+ * @param {boolean} forceSuffix - If true, force suffix for all types (including int/bool/float)
+ * @returns {[boolean, string]} [encoded, result]
+ *   - (true, "serialized::SUFFIX") if type is registered and needs suffix
+ *   - (false, String(value)) if type not registered or jsonNative without force
+ */
+function rawEncode(value, forceSuffix = false) {
+    const entry = getTypeEntry(value);
+    if (entry === null) {
+        return [false, String(value)];
+    }
+    const [suffix, serializer, jsonNative] = entry;
+    if (jsonNative && !forceSuffix) {
+        return [false, String(value)];
+    }
+    return [true, `${serializer(value)}::${suffix}`];
+}
+
+/**
+ * Decode a string with TYTX suffix.
+ *
+ * @param {string} s - String possibly ending with ::XX where XX is a registered suffix
+ * @returns {[boolean, any]} [decoded, value]
+ *   - (true, decodedValue) if suffix found and decoded
+ *   - (false, originalValue) if no valid suffix
+ */
+function rawDecode(s) {
+    if (!s.includes('::')) {
+        return [false, s];
+    }
+    const lastIndex = s.lastIndexOf('::');
+    const value = s.slice(0, lastIndex);
+    const suffix = s.slice(lastIndex + 2);
+    const entry = SUFFIX_TO_TYPE[suffix];
+    if (entry === undefined) {
+        return [false, s];
+    }
+    const [, decoder] = entry;
+    return [true, decoder(value)];
+}
+
+/**
+ * Walk a data structure and apply callback to values matching filtercb.
+ *
+ * @param {any} data - Data structure to walk
+ * @param {function} callback - Function to apply to matching values
+ * @param {function} filtercb - Filter function. Applies callback when filtercb(value) is true.
+ * @returns {any} Transformed data
+ */
+function walk(data, callback, filtercb) {
+    if (data !== null && typeof data === 'object' && !Array.isArray(data)) {
+        const result = {};
+        for (const [k, v] of Object.entries(data)) {
+            result[k] = walk(v, callback, filtercb);
+        }
+        return result;
+    }
+    if (Array.isArray(data)) {
+        return data.map(item => walk(item, callback, filtercb));
+    }
+    if (filtercb(data)) {
+        return callback(data);
+    }
+    return data;
+}
+
+/**
+ * Truncate Date to milliseconds (TYTX precision).
+ * @param {Date} dt
+ * @returns {Date}
+ */
+function _truncateToMillis(dt) {
+    // JavaScript Date already has millisecond precision, no truncation needed
+    return dt;
+}
+
+/**
+ * Check if two Dates represent the same instant in time.
+ *
+ * TYTX serializes all datetimes as UTC (DHZ) with millisecond precision.
+ * This function handles the semantic equivalence for roundtrip comparison.
+ *
+ * @param {Date} a - Original Date (before roundtrip)
+ * @param {Date} b - Decoded Date (after roundtrip)
+ * @returns {boolean} True if both represent the same instant in time
+ */
+function datetimeEquivalent(a, b) {
+    // JavaScript Dates are always comparable directly in milliseconds
+    return a.getTime() === b.getTime();
+}
+
+/**
+ * Check if two values are semantically equivalent after TYTX roundtrip.
+ *
+ * Handles special cases:
+ * - Date: timestamp equivalence
+ * - dict/list: recursive comparison
+ * - other types: standard equality
+ *
+ * @param {any} a - Original value (before roundtrip)
+ * @param {any} b - Decoded value (after roundtrip)
+ * @returns {boolean} True if values are semantically equivalent
+ */
+function tytxEquivalent(a, b) {
+    // Fast path: identical values
+    if (a === b) {
+        return true;
+    }
+
+    // Date special case
+    if (a instanceof Date && b instanceof Date) {
+        return datetimeEquivalent(a, b);
+    }
+
+    // dict: recursive comparison (needed to find nested Dates)
+    if (a !== null && typeof a === 'object' && !Array.isArray(a) &&
+        b !== null && typeof b === 'object' && !Array.isArray(b)) {
+        const keysA = Object.keys(a);
+        const keysB = Object.keys(b);
+        if (keysA.length !== keysB.length) {
+            return false;
+        }
+        const keysSetB = new Set(keysB);
+        for (const k of keysA) {
+            if (!keysSetB.has(k)) {
+                return false;
+            }
+        }
+        return keysA.every(k => tytxEquivalent(a[k], b[k]));
+    }
+
+    // list: recursive comparison (needed to find nested Dates)
+    if (Array.isArray(a) && Array.isArray(b)) {
+        if (a.length !== b.length) {
+            return false;
+        }
+        return a.every((ai, i) => tytxEquivalent(ai, b[i]));
+    }
+
+    return false;
+}
+
+export {
+    rawEncode,
+    rawDecode,
+    walk,
+    datetimeEquivalent,
+    tytxEquivalent,
+    _truncateToMillis,
+};

package/js/src/xml.js

@@ -0,0 +1,228 @@
+// Copyright 2025 Softwell S.r.l. - Licensed under Apache License 2.0
+/**
+ * TYTX XML Encoding/Decoding.
+ *
+ * XML format follows the structure:
+ *     {"tag": {"attrs": {...}, "value": ...}}
+ *
+ * Where:
+ * - attrs: dict of attributes (hydrated with type suffixes)
+ * - value: scalar, dict of children, list, or null
+ *
+ * Type suffixes are used in both text content and attributes:
+ *     <price>100.50::N</price>
+ *     <order id="123::L" created="2025-01-15::D">...</order>
+ */
+
+import { toTytx } from './encode.js';
+import { fromTytx } from './decode.js';
+import { NodeDOMParser, NodeXMLSerializer } from './platform/dependencies.js';
+
+// XML DOM support - use @xmldom/xmldom for Node.js
+let DOMParser, XMLSerializer;
+if (typeof window !== 'undefined' && window.DOMParser) {
+    // Browser environment
+    DOMParser = window.DOMParser;
+    XMLSerializer = window.XMLSerializer;
+} else {
+    DOMParser = NodeDOMParser;
+    XMLSerializer = NodeXMLSerializer;
+}
+
+/**
+ * Check if item is a valid XML element format: {tag: {"value": ...}}
+ *
+ * A valid XML element is a dict with exactly one key (the tag),
+ * whose value is a dict containing at least a "value" key.
+ *
+ * @param {any} item
+ * @returns {boolean}
+ */
+function _isXmlElement(item) {
+    if (item === null || typeof item !== 'object' || Array.isArray(item)) {
+        return false;
+    }
+    const keys = Object.keys(item);
+    if (keys.length !== 1) {
+        return false;
+    }
+    const itemData = item[keys[0]];
+    return itemData !== null && typeof itemData === 'object' && 'value' in itemData;
+}
+
+/**
+ * Serialize a dict with 'value' key (and optional 'attrs') to XML element.
+ *
+ * @param {Document} doc - XML Document
+ * @param {string} tag - Element tag name
+ * @param {Object} data - Dict with 'value' key and optional 'attrs' key
+ * @returns {Element} XML Element
+ */
+function _serializeElement(doc, tag, data) {
+
+    const element = doc.createElement(tag);
+
+    const attrs = data.attrs || {};
+    const value = data.value;
+
+    // Set attributes
+    for (const [attrName, attrValue] of Object.entries(attrs)) {
+        element.setAttribute(attrName, toTytx(attrValue, null, { _forceSuffix: true }));
+    }
+
+    // Set value
+    if (Array.isArray(value)) {
+        // List of children
+        for (const item of value) {
+            if (_isXmlElement(item)) {
+                const [itemTag] = Object.keys(item);
+                const itemData = item[itemTag];
+                const childElement = _serializeElement(doc, itemTag, itemData);
+                element.appendChild(childElement);
+            } else {
+                element.textContent = toTytx(value);
+                break;
+            }
+        }
+    } else {
+        element.textContent = toTytx(value);
+    }
+
+    return element;
+}
+
+/**
+ * Encode a JavaScript value to TYTX XML string.
+ *
+ * @param {any} value - Data to encode
+ * @returns {string} XML string with typed values marked
+ */
+function toXml(value) {
+    if (!DOMParser) {
+        throw new Error('XML support requires @xmldom/xmldom package in Node.js');
+    }
+
+
+    // Check if value is valid XML element format
+    if (_isXmlElement(value)) {
+        // Valid XML format: {tag: {"value": ...}}
+        const [rootTag] = Object.keys(value);
+        const rootData = value[rootTag];
+
+        const doc = new DOMParser().parseFromString('<root/>', 'text/xml');
+        const element = _serializeElement(doc, rootTag, rootData);
+
+        const serializer = new XMLSerializer();
+        return serializer.serializeToString(element);
+    } else {
+        // Not valid XML format: serialize as JSON
+        return toTytx(value);
+    }
+}
+
+/**
+ * Deserialize XML element to dict with 'attrs' and 'value' keys.
+ *
+ * @param {Element} element
+ * @returns {Object} Dict with 'attrs' and 'value' keys
+ */
+function fromXmlnode(element) {
+
+    // Hydrate attributes
+    const attrs = {};
+    for (let i = 0; i < element.attributes.length; i++) {
+        const attr = element.attributes[i];
+        attrs[attr.name] = fromTytx(attr.value);
+    }
+
+    // Process children
+    const children = [];
+    for (let i = 0; i < element.childNodes.length; i++) {
+        const node = element.childNodes[i];
+        if (node.nodeType === 1) {  // ELEMENT_NODE
+            children.push(node);
+        }
+    }
+
+    if (children.length > 0) {
+        if (children.length === 1) {
+            // Single child: return as dict {tag: {...}}
+            const child = children[0];
+            const childData = fromXmlnode(child);
+            return { attrs, value: { [child.tagName]: childData } };
+        } else {
+            // Multiple children: return as list [{tag: {...}}, ...]
+            const valueList = [];
+            for (const child of children) {
+                const childData = fromXmlnode(child);
+                valueList.push({ [child.tagName]: childData });
+            }
+            return { attrs, value: valueList };
+        }
+    }
+
+    // Leaf node
+    return { attrs, value: fromTytx(element.textContent) };
+}
+
+/**
+ * Decode a TYTX XML string to JavaScript value.
+ *
+ * If the root element is 'tytx_root', it is automatically unwrapped
+ * and the inner value is returned directly.
+ *
+ * @param {string} data - XML string with typed values
+ * @returns {Object|any} If root is 'tytx_root': the unwrapped value.
+ *                       Otherwise: Dict in format {"tag": {"attrs": {...}, "value": ...}}
+ *
+ * @example
+ * fromXml('<order id="123::L"><total>100.50::N</total></order>')
+ * // {
+ * //     "order": {
+ * //         "attrs": {"id": 123},
+ * //         "value": {"total": {"attrs": {}, "value": Decimal("100.50")}}
+ * //     }
+ * // }
+ *
+ * fromXml('<tytx_root><price>100.50::N</price></tytx_root>')
+ * // {"price": {"attrs": {}, "value": Decimal("100.50")}}
+ */
+function fromXml(data) {
+    if (!DOMParser) {
+        throw new Error('XML support requires @xmldom/xmldom package in Node.js');
+    }
+
+
+    const parser = new DOMParser();
+    const doc = parser.parseFromString(data, 'text/xml');
+    let root = doc.documentElement;
+
+    // Unwrap tytx_root: work on inner content
+    if (root.tagName === 'tytx_root') {
+        // Get first element child
+        let firstElementChild = null;
+        for (let i = 0; i < root.childNodes.length; i++) {
+            if (root.childNodes[i].nodeType === 1) {
+                firstElementChild = root.childNodes[i];
+                break;
+            }
+        }
+
+        if (!firstElementChild) {
+            return fromTytx(root.textContent);
+        }
+        root = firstElementChild;
+    }
+
+    // From here: root is the real node
+    const result = fromXmlnode(root);
+    return { [root.tagName]: result };
+}
+
+export {
+    toXml,
+    fromXml,
+    fromXmlnode,
+    _isXmlElement,
+    _serializeElement,
+};

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@genrojs/tytx",
+  "version": "0.16.1",
+  "description": "Typed data interchange between Python and JavaScript over JSON, XML and MessagePack: Decimal, dates and custom types arrive with their type.",
+  "main": "js/src/index.js",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./js/src/index.d.ts",
+      "default": "./js/src/index.js"
+    }
+  },
+  "scripts": {
+    "test": "node --test js/test/test_extended.js js/test/test_registry.js js/test/test_registry_lookup.js",
+    "test:all": "node --test js/test/test_*.js",
+    "test:browser": "node --test js/test/test_browser_bundle.js"
+  },
+  "keywords": [
+    "tytx",
+    "typed",
+    "serialization",
+    "json",
+    "xml",
+    "msgpack"
+  ],
+  "author": "Genropy Team",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/genro-org/genro-tytx"
+  },
+  "devDependencies": {
+    "esbuild": "^0.27.2"
+  },
+  "types": "./js/src/index.d.ts",
+  "dependencies": {
+    "@xmldom/xmldom": "^0.9.12",
+    "big.js": "^6.2.1",
+    "decimal.js": "^10.4.3",
+    "@msgpack/msgpack": "^3.1.3"
+  },
+  "files": [
+    "js/src/**/*.js",
+    "js/src/**/*.d.ts",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}