@genrojs/tytx 0.16.1

package/js/src/decode.js

@@ -0,0 +1,128 @@
+// Copyright 2025 Softwell S.r.l. - Licensed under Apache License 2.0
+/**
+ * TYTX Decoding - TYTX format to JavaScript objects.
+ *
+ * Supports multiple transports: json, xml, msgpack.
+ */
+
+import { fromXml } from './xml.js';
+import { fromMsgpack } from './msgpack.js';
+import { walk, rawDecode } from './utils.js';
+
+const TYTX_MARKER = '::JS';
+
+/**
+ * Filter for string values.
+ * @param {any} v
+ * @returns {boolean}
+ */
+function isString(v) {
+    return typeof v === 'string';
+}
+
+/**
+ * Decode a TYTX JSON string to JavaScript objects (internal).
+ *
+ * @param {string} data - JSON string with ::JS suffix (struct) or ::T suffix (scalar)
+ * @returns {any} JavaScript object with typed values hydrated
+ */
+function _fromJson(data) {
+    // Try rawDecode first (scalar with type suffix)
+    const [decoded, value] = rawDecode(data);
+    if (decoded) {
+        return value;
+    }
+
+    let jsonData = data;
+    if (jsonData.endsWith('::JS')) {
+        jsonData = jsonData.slice(0, -4);
+    }
+
+    let parsed;
+    try {
+        parsed = JSON.parse(jsonData);
+    } catch {
+        return data;
+    }
+
+    return walk(parsed, _decodeItem, isString);
+}
+
+/**
+ * Decode a single item with TYTX suffix.
+ * @param {string} s
+ * @returns {any}
+ */
+function _decodeItem(s) {
+    if (!s.includes('::')) {
+        return s;
+    }
+    return rawDecode(s)[1];
+}
+
+/**
+ * Decode a TYTX XML string to JavaScript objects (internal).
+ * @param {string} data
+ * @returns {any}
+ */
+function _fromXml(data) {
+    const result = fromXml(data);
+    // If result is a string with TYTX suffix, hydrate it via JSON decoder
+    if (typeof result === 'string') {
+        return fromTytx(result);
+    }
+    return result;
+}
+
+/**
+ * Decode TYTX MessagePack bytes to JavaScript objects (internal).
+ * @param {Uint8Array} data
+ * @returns {any}
+ */
+function _fromMsgpack(data) {
+    return fromMsgpack(data);
+}
+
+/**
+ * Decode TYTX format to JavaScript objects.
+ *
+ * @param {string|Uint8Array|null} data - Encoded data (string for json/xml, Uint8Array for msgpack), or null
+ * @param {string|null} transport - Input format: "json", "xml", "msgpack", or null
+ * @returns {any} JavaScript object with typed values hydrated, or null if data is null
+ *
+ * @example
+ * fromTytx('{"price": "100.50::N"}::JS')
+ * // {"price": Decimal("100.50")}
+ *
+ * fromTytx('<root>100::N</root>', "xml")
+ * // {"root": {"attrs": {}, "value": Decimal("100")}}
+ */
+function fromTytx(data, transport = null) {
+    if (data === null) {
+        return null;
+    }
+
+    if (transport === null || transport === 'json') {
+        let jsonData = data;
+        if (transport === 'json' && data.startsWith('"') && data.endsWith('"')) {
+            jsonData = data.slice(1, -1);  // Remove surrounding quotes (TYTX-wrapped)
+        }
+        return _fromJson(jsonData);
+    } else if (transport === 'xml') {
+        return _fromXml(data);
+    } else if (transport === 'msgpack') {
+        return _fromMsgpack(data);
+    } else {
+        throw new Error(`Unknown transport: ${transport}`);
+    }
+}
+
+export {
+    fromTytx,
+    TYTX_MARKER,
+    isString,
+    _fromJson,
+    _fromXml,
+    _fromMsgpack,
+    _decodeItem,
+};

package/js/src/encode.js

@@ -0,0 +1,162 @@
+// Copyright 2025 Softwell S.r.l. - Licensed under Apache License 2.0
+/**
+ * TYTX Encoding - JavaScript objects to TYTX format.
+ *
+ * Supports multiple transports: json, xml, msgpack.
+ */
+
+import { toQs } from './qs.js';
+import { toXml } from './xml.js';
+import { toMsgpack } from './msgpack.js';
+import { rawEncode } from './utils.js';
+import { getTypeEntry } from './registry.js';
+import { msgpack } from './platform/dependencies.js';
+
+/**
+ * Pre-process a value recursively, converting typed values to TYTX strings.
+ * Returns [processedValue, hasSpecial].
+ *
+ * @param {any} value
+ * @returns {[any, boolean]}
+ */
+function _preprocessValue(value) {
+    // Check if value is a typed value that needs encoding
+    const entry = getTypeEntry(value);
+    if (entry !== null) {
+        const [suffix, serializer, jsonNative] = entry;
+        if (!jsonNative) {
+            return [`${serializer(value)}::${suffix}`, true];
+        }
+        // jsonNative types (bool, int, float) are kept as-is
+        return [value, false];
+    }
+
+    // Handle arrays
+    if (Array.isArray(value)) {
+        let hasSpecial = false;
+        const result = value.map(item => {
+            const [processed, special] = _preprocessValue(item);
+            if (special) hasSpecial = true;
+            return processed;
+        });
+        return [result, hasSpecial];
+    }
+
+    // Handle objects (but not null)
+    if (value !== null && typeof value === 'object') {
+        let hasSpecial = false;
+        const result = {};
+        for (const [k, v] of Object.entries(value)) {
+            const [processed, special] = _preprocessValue(v);
+            if (special) hasSpecial = true;
+            result[k] = processed;
+        }
+        return [result, hasSpecial];
+    }
+
+    // Primitive values (string, number, boolean, null)
+    return [value, false];
+}
+
+/**
+ * Encode a JavaScript value to TYTX JSON string (internal).
+ *
+ * @param {any} value - JavaScript object to encode
+ * @param {boolean} forceSuffix - If true, add suffix for all types (int/bool/float)
+ * @returns {string} JSON string. For dict/list with typed values: adds ::JS suffix.
+ */
+function _toJson(value, forceSuffix = false) {
+    const [encoded, result] = rawEncode(value, forceSuffix);
+    if (encoded) {
+        return result;
+    }
+
+    const [processed, hasSpecial] = _preprocessValue(value);
+    const jsonResult = JSON.stringify(processed);
+
+    if (hasSpecial) {
+        return `${jsonResult}::JS`;
+    }
+    return jsonResult;
+}
+
+/**
+ * Encode a JavaScript value to raw JSON string (no TYTX suffix).
+ * @param {any} value
+ * @returns {string}
+ */
+function _toRawJson(value) {
+    return JSON.stringify(value);
+}
+
+/**
+ * Encode a JavaScript value to raw MessagePack bytes (no TYTX processing).
+ * @param {any} value
+ * @returns {Uint8Array}
+ */
+function _toRawMsgpack(value) {
+    if (!msgpack) throw new Error('@msgpack/msgpack is required for MessagePack support');
+    return msgpack.encode(value);
+}
+
+/**
+ * Encode a JavaScript value to TYTX format.
+ *
+ * @param {any} value - JavaScript object to encode
+ * @param {string|null} transport - Output format: "json", "xml", "msgpack", or null
+ * @param {Object} options - Options object
+ * @param {boolean} options.raw - If true, output raw format without TYTX type suffixes
+ * @param {boolean} options.qs - If true, output as query string format (flat object or array only)
+ * @param {boolean} options._forceSuffix - Internal: force suffix for all types
+ * @returns {string|Uint8Array} Encoded data (string for json/xml, Uint8Array for msgpack)
+ *
+ * @example
+ * toTytx({"price": createDecimal("100.50")})
+ * // '{"price": "100.50::N"}::JS'
+ *
+ * toTytx({"price": 100.50}, null, { raw: true })
+ * // '{"price": 100.5}'
+ *
+ * toTytx({"alfa": 33, "date": new Date(Date.UTC(2025, 11, 14))}, null, { qs: true })
+ * // 'alfa=33::L&date=2025-12-14::D::QS'
+ *
+ * toTytx({"root": {"value": createDecimal("100")}}, "xml")
+ * // '<?xml version="1.0" ?><root>100::N</root>'
+ */
+function toTytx(value, transport = null, { raw = false, qs = false, _forceSuffix = false } = {}) {
+    if (qs) {
+        return `${toQs(value)}::QS`;
+    }
+
+    if (raw) {
+        if (transport === null || transport === 'json') {
+            return _toRawJson(value);
+        } else if (transport === 'msgpack') {
+            return _toRawMsgpack(value);
+        } else if (transport === 'xml') {
+            throw new Error('raw=true is not supported for XML transport');
+        } else {
+            throw new Error(`Unknown transport: ${transport}`);
+        }
+    }
+
+    if (transport === null || transport === 'json') {
+        const result = _toJson(value, _forceSuffix);
+        if (transport === 'json') {
+            return `"${result}"`;
+        }
+        return result;
+    } else if (transport === 'xml') {
+            const result = toXml(value);
+        return `<?xml version="1.0" ?><tytx_root>${result}</tytx_root>`;
+    } else if (transport === 'msgpack') {
+            return toMsgpack(value);
+    } else {
+        throw new Error(`Unknown transport: ${transport}`);
+    }
+}
+
+export {
+    toTytx,
+    _toJson,
+};

package/js/src/http.js

@@ -0,0 +1,101 @@
+// Copyright 2025 Softwell S.r.l. - Licensed under Apache License 2.0
+/**
+ * TYTX HTTP utilities.
+ *
+ * Client-side functions to make HTTP requests with TYTX serialization.
+ */
+
+import { toTytx } from './encode.js';
+import { fromTytx } from './decode.js';
+
+const CONTENT_TYPES = {
+    json: 'application/json',
+    xml: 'application/xml',
+    msgpack: 'application/msgpack',
+};
+
+/**
+ * Get transport from Content-Type header.
+ * @param {string} contentType
+ * @returns {'json'|'xml'|'msgpack'|null}
+ */
+function getTransport(contentType) {
+    if (!contentType) return null;
+    const ct = contentType.toLowerCase();
+    if (ct.includes('json')) return 'json';
+    if (ct.includes('xml')) return 'xml';
+    if (ct.includes('msgpack')) return 'msgpack';
+    return null;
+}
+
+/**
+ * Fetch with TYTX serialization/deserialization.
+ *
+ * @param {string} url - URL to fetch
+ * @param {Object} options - Fetch options
+ * @param {any} [options.body] - Data to send (will be serialized with toTytx)
+ * @param {'json'|'xml'|'msgpack'} [options.transport='json'] - Transport format
+ * @param {string} [options.method='GET'] - HTTP method
+ * @param {Object} [options.headers={}] - Additional headers
+ * @returns {Promise<any>} Deserialized response data
+ */
+async function fetchTytx(url, options = {}) {
+    const {
+        body,
+        transport = 'json',
+        method = body !== undefined ? 'POST' : 'GET',
+        headers = {},
+        ...fetchOptions
+    } = options;
+
+    const requestHeaders = {
+        'X-TYTX-Transport': transport,
+        ...headers,
+    };
+
+    // Serialize body if provided
+    let requestBody;
+    if (body !== undefined) {
+        requestHeaders['Content-Type'] = CONTENT_TYPES[transport];
+        const encoded = toTytx(body, transport);
+        if (transport === 'msgpack') {
+            requestBody = encoded;
+        } else {
+            requestBody = encoded;
+        }
+    }
+
+    // Make request
+    const response = await fetch(url, {
+        method,
+        headers: requestHeaders,
+        body: requestBody,
+        ...fetchOptions,
+    });
+
+    if (!response.ok) {
+        throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+    }
+
+    // Determine response transport from Content-Type
+    const responseContentType = response.headers.get('Content-Type') || '';
+    const responseTransport = getTransport(responseContentType) || transport;
+
+    // Read and deserialize response
+    let responseData;
+    if (responseTransport === 'msgpack') {
+        const buffer = await response.arrayBuffer();
+        responseData = fromTytx(Buffer.from(buffer), responseTransport);
+    } else {
+        const text = await response.text();
+        responseData = fromTytx(text, responseTransport);
+    }
+
+    return responseData;
+}
+
+export {
+    fetchTytx,
+    getTransport,
+    CONTENT_TYPES,
+};

package/js/src/index.d.ts

@@ -0,0 +1,38 @@
+// Copyright 2026 Softwell S.r.l. - SPDX-License-Identifier: Apache-2.0
+/** Supported wire transports; null selects suffix-encoded typed text. */
+export type Transport = 'json' | 'xml' | 'msgpack' | null;
+export type DecimalLibrary = 'decimal.js' | 'big.js' | 'number';
+export interface EncodeOptions { raw?: boolean; qs?: boolean; _forceSuffix?: boolean; }
+/** Serialize a value. MessagePack returns bytes; other transports return text. */
+export function toTytx(value: unknown, transport?: Transport, options?: EncodeOptions): string | Uint8Array;
+/** Decode typed text, XML or MessagePack. Registered decoders determine the result. */
+export function fromTytx(data: string | Uint8Array | null, transport?: Transport): unknown;
+export interface FetchOptions extends Omit<RequestInit, 'body' | 'headers'> {
+    body?: unknown;
+    transport?: Exclude<Transport, null>;
+    headers?: Record<string, string>;
+}
+export function fetchTytx(url: string, options?: FetchOptions): Promise<unknown>;
+export function getTransport(contentType: string | null | undefined): Transport;
+export const CONTENT_TYPES: { json: string; xml: string; msgpack: string };
+export function isDecimal(value: unknown): boolean;
+/** Returns an instance of the selected decimal library, or boxed Number. */
+export function createDecimal(value: string | number): { toString(): string; valueOf(): string | number };
+export function setDecimalLibrary(name: DecimalLibrary): void;
+export function getDecimalLibrary(): DecimalLibrary;
+export function registerType<T>(cls: new (...args: any[]) => T, suffix: string,
+    serializer: (value: T) => string, deserializer: (value: string) => T,
+    jsonNative?: boolean): void;
+export interface RegisteredClass<T extends { toTytx(): string }> {
+    new (...args: any[]): T;
+    tytxSuffix: string;
+    tytxJsonNative?: boolean;
+    fromTytx(value: string): T;
+}
+export function registerClass<T extends { toTytx(): string }, C extends RegisteredClass<T>>(cls: C): C;
+export function getRegisteredType(suffix: string): Function | null;
+/** Stores the subtype dictionary of a suffix, replacing the previous one. */
+export function setSubtypeDict(suffix: string, subtypes: Record<string, unknown>): void;
+/** Returns the subtype dictionary of a suffix, or {} if none was set. */
+export function getSubtypeDict(suffix: string): Record<string, unknown>;
+export const __version__: string;

package/js/src/index.js

@@ -0,0 +1,63 @@
+/* @ts-self-types="./index.d.ts" */
+// Copyright 2025 Softwell S.r.l. - Licensed under Apache License 2.0
+/**
+ * TYTX Base - Typed Text Protocol for Scalar Types
+ *
+ * Minimal implementation supporting:
+ * - Scalar types: Decimal, date, datetime, time, bool, int
+ * - Encoders/Decoders: JSON, XML, MessagePack
+ *
+ * Usage:
+ *     import { toTytx, fromTytx, fetchTytx } from '@genrojs/tytx';
+ *     import Big from 'big.js';
+ *
+ *     // Encode
+ *     const data = {"price": new Big("100.50"), "date": new Date(Date.UTC(2025, 0, 15))};
+ *     const jsonStr = toTytx(data);
+ *     // '{"price": "100.50::N", "date": "2025-01-15::D"}::JS'
+ *
+ *     // Decode
+ *     const result = fromTytx(jsonStr);
+ *     // {"price": Big("100.50"), "date": Date}
+ */
+
+import {
+    isDecimal,
+    createDecimal,
+    setDecimalLibrary,
+    getDecimalLibrary,
+    registerType,
+    registerClass,
+    getRegisteredType,
+    setSubtypeDict,
+    getSubtypeDict,
+} from './registry.js';
+
+import { toTytx } from './encode.js';
+import { fromTytx } from './decode.js';
+import { fetchTytx, getTransport, CONTENT_TYPES } from './http.js';
+
+const __version__ = '0.16.1';
+
+export {
+    // Core API
+    toTytx,
+    fromTytx,
+    // HTTP utilities
+    fetchTytx,
+    getTransport,
+    CONTENT_TYPES,
+    // Decimal utilities
+    isDecimal,
+    createDecimal,
+    setDecimalLibrary,
+    getDecimalLibrary,
+    // Custom type registration
+    registerType,
+    registerClass,
+    getRegisteredType,
+    setSubtypeDict,
+    getSubtypeDict,
+    // Version
+    __version__,
+};

package/js/src/msgpack.js

@@ -0,0 +1,185 @@
+// Copyright 2025 Softwell S.r.l. - Licensed under Apache License 2.0
+/**
+ * TYTX MessagePack Encoding/Decoding.
+ *
+ * Uses MessagePack extension types to carry TYTX type information directly in the protocol:
+ * - Ext -1: datetime (native Timestamp, handled by @msgpack/msgpack)
+ * - Ext  1: Decimal  (payload: UTF-8 string, e.g. "100.50")
+ * - Ext  2: date     (payload: ISO "YYYY-MM-DD")
+ * - Ext  3: time     (payload: ISO "HH:MM:SS.mmm")
+ * - Ext  4: registered custom type (payload: UTF-8 "SUFFIX:serialized",
+ *           split at the first ":"; unknown suffixes on the receiving side
+ *           degrade to the string "serialized::SUFFIX", like the json path)
+ */
+
+import {
+    getDateType,
+    createDecimal,
+    isDecimal,
+    getCustomTypeEntry,
+    SUFFIX_TO_TYPE,
+} from './registry.js';
+import { msgpack } from './platform/dependencies.js';
+
+// Check for @msgpack/msgpack availability
+const HAS_MSGPACK = msgpack !== null;
+
+function _checkMsgpack() {
+    if (!HAS_MSGPACK) {
+        throw new Error(
+            '@msgpack/msgpack is required for MessagePack support. ' +
+            'Install with: npm install @msgpack/msgpack'
+        );
+    }
+}
+
+// Build the ExtensionCodec once at module load (if msgpack is available).
+// The encode/decode functions close over isDecimal/createDecimal/getDateType
+// which read the current decimal library state at call time.
+const _extensionCodec = _buildCodec();
+
+function _buildCodec() {
+    if (!HAS_MSGPACK) {
+        return null;
+    }
+
+    const enc = new TextEncoder();
+    const dec = new TextDecoder();
+    const codec = new msgpack.ExtensionCodec();
+
+    // Override built-in Timestamp encoder (-1) to skip date-only and time-only
+    // Date objects so they can be handled by ext 2 and ext 3 below.
+    // DHZ datetimes fall through to the native Timestamp encoding.
+    codec.register({
+        type: -1,
+        encode: (v) => {
+            if (v instanceof Date) {
+                const dt = getDateType(v);
+                if (dt === 'D' || dt === 'H') {
+                    return null;  // let custom encoders (2, 3) handle these
+                }
+            }
+            return msgpack.encodeTimestampExtension(v);
+        },
+        decode: (data) => msgpack.decodeTimestampExtension(data),
+    });
+
+    // Ext 1: Decimal
+    codec.register({
+        type: 1,
+        encode: (v) => {
+            if (isDecimal(v)) {
+                return enc.encode(v.toString());
+            }
+            return null;
+        },
+        decode: (data) => createDecimal(dec.decode(data)),
+    });
+
+    // Ext 2: date-only (midnight UTC)
+    codec.register({
+        type: 2,
+        encode: (v) => {
+            if (v instanceof Date && getDateType(v) === 'D') {
+                const y = v.getUTCFullYear();
+                const m = String(v.getUTCMonth() + 1).padStart(2, '0');
+                const d = String(v.getUTCDate()).padStart(2, '0');
+                return enc.encode(`${y}-${m}-${d}`);
+            }
+            return null;
+        },
+        decode: (data) => new Date(dec.decode(data) + 'T00:00:00.000Z'),
+    });
+
+    // Ext 3: time-only (epoch-based Date)
+    codec.register({
+        type: 3,
+        encode: (v) => {
+            if (v instanceof Date && getDateType(v) === 'H') {
+                const h = String(v.getUTCHours()).padStart(2, '0');
+                const m = String(v.getUTCMinutes()).padStart(2, '0');
+                const s = String(v.getUTCSeconds()).padStart(2, '0');
+                const ms = String(v.getUTCMilliseconds()).padStart(3, '0');
+                return enc.encode(`${h}:${m}:${s}.${ms}`);
+            }
+            return null;
+        },
+        decode: (data) => {
+            const str = dec.decode(data);
+            // Accept "HH:MM:SS", "HH:MM:SS.mmm", or "HH:MM:SS.ffffff"
+            const dotIdx = str.indexOf('.');
+            const timePart = dotIdx >= 0 ? str.substring(0, dotIdx) : str;
+            const fracStr = dotIdx >= 0 ? str.substring(dotIdx + 1) : '0';
+            const [h, m, s] = timePart.split(':');
+            // Truncate fractional part to 3 digits (milliseconds)
+            const ms = Math.round(+fracStr.substring(0, 3));
+            return new Date(Date.UTC(1970, 0, 1, +h, +m, +s, ms));
+        },
+    });
+
+    // Ext 4: registered custom type ("SUFFIX:serialized", first-colon split)
+    codec.register({
+        type: 4,
+        encode: (v) => {
+            const entry = getCustomTypeEntry(v);
+            if (entry !== null) {
+                const [suffix, serializer] = entry;
+                return enc.encode(`${suffix}:${serializer(v)}`);
+            }
+            return null;
+        },
+        decode: (data) => {
+            const str = dec.decode(data);
+            const idx = str.indexOf(':');
+            const suffix = str.slice(0, idx);
+            const payload = str.slice(idx + 1);
+            const entry = SUFFIX_TO_TYPE[suffix];
+            if (entry !== undefined) {
+                const [, deserializer] = entry;
+                return deserializer(payload);
+            }
+            // Unknown suffix on the receiving side: degrade to the same
+            // pass-through string rawDecode gives on the json path.
+            return `${payload}::${suffix}`;
+        },
+    });
+
+    return codec;
+}
+
+/**
+ * Encode a JavaScript value to TYTX MessagePack bytes.
+ *
+ * @param {any} value - JavaScript object to encode
+ * @returns {Uint8Array} MessagePack bytes with TYTX types as extension types
+ *
+ * @example
+ * toMsgpack({"price": createDecimal("100.50")})
+ * // Uint8Array[...]  // MessagePack bytes
+ */
+function toMsgpack(value) {
+    _checkMsgpack();
+    return msgpack.encode(value, { extensionCodec: _extensionCodec });
+}
+
+/**
+ * Decode TYTX MessagePack bytes to JavaScript objects.
+ *
+ * @param {Uint8Array} data - MessagePack bytes
+ * @returns {any} JavaScript object with TYTX extension types hydrated
+ *
+ * @example
+ * fromMsgpack(packedBytes)
+ * // {"price": Decimal("100.50")}
+ */
+function fromMsgpack(data) {
+    _checkMsgpack();
+    return msgpack.decode(data, { extensionCodec: _extensionCodec });
+}
+
+export {
+    toMsgpack,
+    fromMsgpack,
+    HAS_MSGPACK,
+    _checkMsgpack,
+};

package/js/src/platform/dependencies.js

@@ -0,0 +1,12 @@
+// Copyright 2026 Softwell S.r.l. - SPDX-License-Identifier: Apache-2.0
+// One statically analyzable codec graph for Node, Bun and browser bundlers.
+import Decimal from 'decimal.js';
+import Big from 'big.js';
+import * as messagePack from '@msgpack/msgpack';
+import { DOMParser, XMLSerializer } from '@xmldom/xmldom';
+
+export const DecimalJS = Decimal;
+export const BigJS = Big;
+export const msgpack = messagePack;
+export const NodeDOMParser = DOMParser;
+export const NodeXMLSerializer = XMLSerializer;