@transia/ripple-binary-codec 1.4.6-alpha.9 → 2.5.2-alpha.0

package/dist/src/types/json.d.ts

@@ -0,0 +1,169 @@
+import { BinaryParser } from '../serdes/binary-parser';
+import { JsonObject, SerializedType, SerializedTypeID } from './serialized-type';
+import { BinarySerializer } from '../serdes/binary-serializer';
+/**
+ * STJson: Serialized Type for JSON-like structures (objects or arrays).
+ *
+ * Supports two modes:
+ * - Object: Key-value pairs where keys are VL-encoded strings
+ * - Array: Ordered list of values
+ *
+ * Values are [SType marker][VL-encoded SType serialization].
+ * Values can be any SType, including nested STJson.
+ *
+ * Serialization format: [type_byte][VL_length][data...]
+ * - type_byte: 0x00 = Object, 0x01 = Array
+ *
+ * Depth constraint: Maximum nesting depth of 1 level
+ */
+declare class STJson extends SerializedType {
+    private static readonly JsonType;
+    private data;
+    private jsonType;
+    private default_;
+    /**
+     * Construct STJson from bytes
+     * @param bytes - Uint8Array containing serialized JSON
+     */
+    constructor(bytes: Uint8Array);
+    /**
+     * Parse STJson from BinaryParser
+     *
+     * @param parser - BinaryParser positioned at the start of STJson
+     * @returns STJson instance
+     */
+    static fromParser(parser: BinaryParser): STJson;
+    /**
+     * Parse a single key-value pair from the parser
+     */
+    private static parsePair;
+    /**
+     * Factory for SType value from VL blob (with SType marker)
+     */
+    private static makeValueFromVLWithType;
+    /**
+     * Check if this is an array type
+     */
+    isArray(): boolean;
+    /**
+     * Check if this is an object type
+     */
+    isObject(): boolean;
+    /**
+     * Get the JSON type
+     */
+    getType(): number;
+    /**
+     * Get nesting depth (0 = no nesting, 1 = one level of nesting)
+     */
+    getDepth(): number;
+    /**
+     * Validate nesting depth (max 1 level)
+     */
+    private validateDepth;
+    /**
+     * Set a field in an object
+     */
+    setObjectField(key: string, value: SerializedType | null): void;
+    /**
+     * Get a field from an object
+     */
+    getObjectField(key: string): SerializedType | null | undefined;
+    /**
+     * Set a nested object field (one level deep)
+     */
+    setNestedObjectField(key: string, nestedKey: string, value: SerializedType | null): void;
+    /**
+     * Get a nested object field
+     */
+    getNestedObjectField(key: string, nestedKey: string): SerializedType | null | undefined;
+    /**
+     * Get the inner data as a Map (for objects)
+     */
+    getMap(): Map<string, SerializedType | null>;
+    /**
+     * Get the inner data as an array
+     */
+    getArray(): (SerializedType | null)[];
+    /**
+     * Push an element to an array
+     */
+    pushArrayElement(value: SerializedType | null): void;
+    /**
+     * Get an array element by index
+     */
+    getArrayElement(index: number): SerializedType | null | undefined;
+    /**
+     * Set an array element by index
+     */
+    setArrayElement(index: number, value: SerializedType | null): void;
+    /**
+     * Set a field within an array element (element must be an object)
+     */
+    setArrayElementField(index: number, key: string, value: SerializedType | null): void;
+    /**
+     * Get a field within an array element
+     */
+    getArrayElementField(index: number, key: string): SerializedType | null | undefined;
+    /**
+     * Get the size of the array
+     */
+    arraySize(): number;
+    /**
+     * Set a nested array element (array stored in object field)
+     */
+    setNestedArrayElement(key: string, index: number, value: SerializedType | null): void;
+    /**
+     * Set a field within a nested array element
+     */
+    setNestedArrayElementField(key: string, index: number, nestedKey: string, value: SerializedType | null): void;
+    /**
+     * Get a nested array element
+     */
+    getNestedArrayElement(key: string, index: number): SerializedType | null | undefined;
+    /**
+     * Get a field within a nested array element
+     */
+    getNestedArrayElementField(key: string, index: number, nestedKey: string): SerializedType | null | undefined;
+    /**
+     * Serialize to binary
+     */
+    add(s: BinarySerializer): void;
+    /**
+     * Encode a key as VL
+     */
+    private static addVLKey;
+    /**
+     * Encode a value as [SType marker][VL]
+     */
+    private static addVLValue;
+    /**
+     * Convert to JSON representation
+     */
+    toJSON(): JsonObject | JsonObject[];
+    /**
+     * Compare with another STJson for equivalence
+     */
+    isEquivalent(t: SerializedType): boolean;
+    /**
+     * Check if this is the default value
+     */
+    isDefault(): boolean;
+    /**
+     * Get blob representation
+     */
+    toBlob(): Uint8Array;
+    /**
+     * Get the size (number of bytes in serialized form)
+     */
+    size(): number;
+    /**
+     * Set the value from another STJson
+     */
+    setValue(v: STJson): void;
+    /**
+     * Get serialized type ID
+     */
+    getSType(): SerializedTypeID;
+}
+export { STJson };

package/dist/src/types/json.js

@@ -0,0 +1,529 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.STJson = void 0;
+/* eslint-disable max-lines */
+/* eslint-disable complexity */
+const binary_parser_1 = require("../serdes/binary-parser");
+const serialized_type_1 = require("./serialized-type");
+const utils_1 = require("@transia/isomorphic/utils");
+const binary_serializer_1 = require("../serdes/binary-serializer");
+/**
+ * STJson: Serialized Type for JSON-like structures (objects or arrays).
+ *
+ * Supports two modes:
+ * - Object: Key-value pairs where keys are VL-encoded strings
+ * - Array: Ordered list of values
+ *
+ * Values are [SType marker][VL-encoded SType serialization].
+ * Values can be any SType, including nested STJson.
+ *
+ * Serialization format: [type_byte][VL_length][data...]
+ * - type_byte: 0x00 = Object, 0x01 = Array
+ *
+ * Depth constraint: Maximum nesting depth of 1 level
+ */
+class STJson extends serialized_type_1.SerializedType {
+    /**
+     * Construct STJson from bytes
+     * @param bytes - Uint8Array containing serialized JSON
+     */
+    constructor(bytes) {
+        super(bytes);
+        this.default_ = false;
+        this.data = new Map();
+        this.jsonType = STJson.JsonType.Object;
+    }
+    /**
+     * Parse STJson from BinaryParser
+     *
+     * @param parser - BinaryParser positioned at the start of STJson
+     * @returns STJson instance
+     */
+    static fromParser(parser) {
+        const dataLength = parser.readVariableLengthLength();
+        if (dataLength < 0) {
+            throw new Error('Invalid STJson length');
+        }
+        if (dataLength === 0) {
+            const json = new STJson(new Uint8Array());
+            json.data = new Map();
+            return json;
+        }
+        // Read type byte
+        const typeByte = parser.read(1)[0];
+        const type = typeByte;
+        const initialBytesLeft = parser.size();
+        if (type === STJson.JsonType.Array) {
+            const array = [];
+            while (parser.size() > 0 &&
+                initialBytesLeft - parser.size() < dataLength) {
+                const valueVL = parser.readVariableLength();
+                if (valueVL.length > 0) {
+                    const valueSit = new binary_parser_1.BinaryParser((0, utils_1.bytesToHex)(valueVL));
+                    const value = STJson.makeValueFromVLWithType(valueSit);
+                    array.push(value);
+                }
+                else {
+                    array.push(null);
+                }
+            }
+            const json = new STJson(new Uint8Array());
+            json.data = array;
+            json.jsonType = STJson.JsonType.Array;
+            return json;
+        }
+        else {
+            // JsonType.Object
+            const map = new Map();
+            while (parser.size() > 0 &&
+                initialBytesLeft - parser.size() < dataLength) {
+                const [key, value] = STJson.parsePair(parser);
+                map.set(key, value);
+            }
+            const json = new STJson(new Uint8Array());
+            json.data = map;
+            json.jsonType = STJson.JsonType.Object;
+            return json;
+        }
+    }
+    /**
+     * Parse a single key-value pair from the parser
+     */
+    static parsePair(parser) {
+        const keyVL = parser.readVariableLength();
+        const key = new TextDecoder().decode(keyVL);
+        const valueVL = parser.readVariableLength();
+        let value = null;
+        if (valueVL.length > 0) {
+            const valueSit = new binary_parser_1.BinaryParser((0, utils_1.bytesToHex)(valueVL));
+            value = STJson.makeValueFromVLWithType(valueSit);
+        }
+        return [key, value];
+    }
+    /**
+     * Factory for SType value from VL blob (with SType marker)
+     */
+    static makeValueFromVLWithType(parser) {
+        if (parser.size() === 0) {
+            throw new Error('Empty data when parsing STJson value');
+        }
+        const typeId = parser.read(1)[0];
+        // Delegate to appropriate type's fromParser
+        // This is a placeholder - actual implementation would dispatch to concrete types
+        // For now, we create an STJson if type is Object or Array
+        if (typeId === STJson.JsonType.Object || typeId === STJson.JsonType.Array) {
+            return STJson.fromParser(parser);
+        }
+        throw new Error(`Unsupported type ID in STJson: ${typeId}`);
+    }
+    /**
+     * Check if this is an array type
+     */
+    isArray() {
+        return this.jsonType === STJson.JsonType.Array;
+    }
+    /**
+     * Check if this is an object type
+     */
+    isObject() {
+        return this.jsonType === STJson.JsonType.Object;
+    }
+    /**
+     * Get the JSON type
+     */
+    getType() {
+        return this.jsonType;
+    }
+    /**
+     * Get nesting depth (0 = no nesting, 1 = one level of nesting)
+     */
+    getDepth() {
+        if (this.isArray()) {
+            const array = this.data;
+            for (const value of array) {
+                if (value && value instanceof STJson) {
+                    return 1 + value.getDepth();
+                }
+            }
+            return 0;
+        }
+        else {
+            // isObject()
+            const map = this.data;
+            for (const value of map.values()) {
+                if (value && value instanceof STJson) {
+                    return 1 + value.getDepth();
+                }
+            }
+            return 0;
+        }
+    }
+    /**
+     * Validate nesting depth (max 1 level)
+     */
+    validateDepth(value, currentDepth) {
+        if (!value) {
+            return;
+        }
+        if (!(value instanceof STJson)) {
+            return;
+        }
+        const valueDepth = value.getDepth();
+        if (currentDepth + valueDepth > 1) {
+            throw new Error('STJson nesting depth exceeds maximum of 1');
+        }
+    }
+    /**
+     * Set a field in an object
+     */
+    setObjectField(key, value) {
+        if (!this.isObject()) {
+            throw new Error('STJson::setObjectField called on non-object');
+        }
+        this.validateDepth(value, 0);
+        this.data.set(key, value);
+    }
+    /**
+     * Get a field from an object
+     */
+    getObjectField(key) {
+        if (!this.isObject()) {
+            return undefined;
+        }
+        return this.data.get(key);
+    }
+    /**
+     * Set a nested object field (one level deep)
+     */
+    setNestedObjectField(key, nestedKey, value) {
+        if (!this.isObject()) {
+            throw new Error('STJson::setNestedObjectField called on non-object');
+        }
+        const map = this.data;
+        let nestedObj = map.get(key);
+        if (!nestedObj || !(nestedObj instanceof STJson) || !nestedObj.isObject()) {
+            const newNested = new STJson(new Uint8Array());
+            newNested.data = new Map();
+            newNested.jsonType = STJson.JsonType.Object;
+            map.set(key, newNested);
+            nestedObj = newNested;
+        }
+        if (nestedObj instanceof STJson) {
+            nestedObj.setObjectField(nestedKey, value);
+        }
+    }
+    /**
+     * Get a nested object field
+     */
+    getNestedObjectField(key, nestedKey) {
+        if (!this.isObject()) {
+            return undefined;
+        }
+        const nestedObj = this.data.get(key);
+        if (nestedObj instanceof STJson && nestedObj.isObject()) {
+            return nestedObj.getObjectField(nestedKey);
+        }
+        return undefined;
+    }
+    /**
+     * Get the inner data as a Map (for objects)
+     */
+    getMap() {
+        if (!this.isObject()) {
+            throw new Error('STJson is not an object type');
+        }
+        return this.data;
+    }
+    /**
+     * Get the inner data as an array
+     */
+    getArray() {
+        if (!this.isArray()) {
+            throw new Error('STJson is not an array type');
+        }
+        return this.data;
+    }
+    /**
+     * Push an element to an array
+     */
+    pushArrayElement(value) {
+        if (!this.isArray()) {
+            throw new Error('STJson::pushArrayElement called on non-array');
+        }
+        this.validateDepth(value, 0);
+        this.data.push(value);
+    }
+    /**
+     * Get an array element by index
+     */
+    getArrayElement(index) {
+        if (!this.isArray()) {
+            return undefined;
+        }
+        const array = this.data;
+        return array[index];
+    }
+    /**
+     * Set an array element by index
+     */
+    setArrayElement(index, value) {
+        if (!this.isArray()) {
+            throw new Error('STJson::setArrayElement called on non-array');
+        }
+        this.validateDepth(value, 0);
+        const array = this.data;
+        // Auto-resize with nulls if needed
+        if (index >= array.length) {
+            array.length = index + 1;
+            array.fill(null);
+        }
+        array[index] = value;
+    }
+    /**
+     * Set a field within an array element (element must be an object)
+     */
+    setArrayElementField(index, key, value) {
+        if (!this.isArray()) {
+            throw new Error('STJson::setArrayElementField called on non-array');
+        }
+        this.validateDepth(value, 1);
+        const array = this.data;
+        // Auto-resize with nulls if needed
+        if (index >= array.length) {
+            array.length = index + 1;
+            array.fill(null);
+        }
+        let element = array[index];
+        if (!element || !(element instanceof STJson) || !element.isObject()) {
+            const newElement = new STJson(new Uint8Array());
+            newElement.data = new Map();
+            newElement.jsonType = STJson.JsonType.Object;
+            array[index] = newElement;
+            element = newElement;
+        }
+        if (element instanceof STJson) {
+            element.setObjectField(key, value);
+        }
+    }
+    /**
+     * Get a field within an array element
+     */
+    getArrayElementField(index, key) {
+        if (!this.isArray()) {
+            return undefined;
+        }
+        const array = this.data;
+        if (index >= array.length) {
+            return undefined;
+        }
+        const element = array[index];
+        if (element instanceof STJson && element.isObject()) {
+            return element.getObjectField(key);
+        }
+        return undefined;
+    }
+    /**
+     * Get the size of the array
+     */
+    arraySize() {
+        if (!this.isArray()) {
+            return 0;
+        }
+        return this.data.length;
+    }
+    /**
+     * Set a nested array element (array stored in object field)
+     */
+    setNestedArrayElement(key, index, value) {
+        if (!this.isObject()) {
+            throw new Error('STJson::setNestedArrayElement called on non-object');
+        }
+        this.validateDepth(value, 1);
+        const map = this.data;
+        let arrayJson = map.get(key);
+        if (!arrayJson || !(arrayJson instanceof STJson) || !arrayJson.isArray()) {
+            const newArray = new STJson(new Uint8Array());
+            newArray.data = [];
+            newArray.jsonType = STJson.JsonType.Array;
+            map.set(key, newArray);
+            arrayJson = newArray;
+        }
+        if (arrayJson instanceof STJson) {
+            arrayJson.setArrayElement(index, value);
+        }
+    }
+    /**
+     * Set a field within a nested array element
+     */
+    setNestedArrayElementField(key, index, nestedKey, value) {
+        if (!this.isObject()) {
+            throw new Error('STJson::setNestedArrayElementField called on non-object');
+        }
+        this.validateDepth(value, 1);
+        const map = this.data;
+        let arrayJson = map.get(key);
+        if (!arrayJson || !(arrayJson instanceof STJson) || !arrayJson.isArray()) {
+            const newArray = new STJson(new Uint8Array());
+            newArray.data = [];
+            newArray.jsonType = STJson.JsonType.Array;
+            map.set(key, newArray);
+            arrayJson = newArray;
+        }
+        if (arrayJson instanceof STJson) {
+            arrayJson.setArrayElementField(index, nestedKey, value);
+        }
+    }
+    /**
+     * Get a nested array element
+     */
+    getNestedArrayElement(key, index) {
+        if (!this.isObject()) {
+            return undefined;
+        }
+        const arrayJson = this.data.get(key);
+        if (arrayJson instanceof STJson && arrayJson.isArray()) {
+            return arrayJson.getArrayElement(index);
+        }
+        return undefined;
+    }
+    /**
+     * Get a field within a nested array element
+     */
+    getNestedArrayElementField(key, index, nestedKey) {
+        if (!this.isObject()) {
+            return undefined;
+        }
+        const arrayJson = this.data.get(key);
+        if (arrayJson instanceof STJson && arrayJson.isArray()) {
+            return arrayJson.getArrayElementField(index, nestedKey);
+        }
+        return undefined;
+    }
+    /**
+     * Serialize to binary
+     */
+    add(s) {
+        const bytesList = new binary_serializer_1.BytesList();
+        const tmp = new binary_serializer_1.BinarySerializer(bytesList);
+        // Add type byte
+        tmp.put(new Uint8Array([this.jsonType]));
+        if (this.isArray()) {
+            const array = this.data;
+            for (const value of array) {
+                STJson.addVLValue(tmp, value);
+            }
+        }
+        else {
+            // isObject()
+            const map = this.data;
+            for (const [key, value] of map.entries()) {
+                STJson.addVLKey(tmp, key);
+                STJson.addVLValue(tmp, value);
+            }
+        }
+        const innerBytes = bytesList.toBytes();
+        const lengthBytes = binary_serializer_1.BinarySerializer.encodeVariableLength(innerBytes.length);
+        s.put(lengthBytes);
+        s.put(innerBytes);
+    }
+    /**
+     * Encode a key as VL
+     */
+    static addVLKey(s, str) {
+        const keyBytes = new TextEncoder().encode(str);
+        const lengthBytes = binary_serializer_1.BinarySerializer.encodeVariableLength(keyBytes.length);
+        s.put(lengthBytes);
+        s.put(keyBytes);
+    }
+    /**
+     * Encode a value as [SType marker][VL]
+     */
+    static addVLValue(s, value) {
+        if (!value) {
+            s.put(binary_serializer_1.BinarySerializer.encodeVariableLength(0));
+            return;
+        }
+        const bytesList = new binary_serializer_1.BytesList();
+        const tmp = new binary_serializer_1.BinarySerializer(bytesList);
+        tmp.put(new Uint8Array([value.getSType()]));
+        value.toBytesSink(bytesList);
+        const innerBytes = bytesList.toBytes();
+        const lengthBytes = binary_serializer_1.BinarySerializer.encodeVariableLength(innerBytes.length);
+        s.put(lengthBytes);
+        s.put(innerBytes);
+    }
+    /**
+     * Convert to JSON representation
+     */
+    toJSON() {
+        if (this.isArray()) {
+            const array = this.data;
+            return array.map((item) => (item ? item.toJSON() : null));
+        }
+        else {
+            // isObject()
+            const map = this.data;
+            const result = {};
+            for (const [key, value] of map.entries()) {
+                result[key] = value ? value.toJSON() : null;
+            }
+            return result;
+        }
+    }
+    /**
+     * Compare with another STJson for equivalence
+     */
+    isEquivalent(t) {
+        if (!(t instanceof STJson)) {
+            return false;
+        }
+        return (0, utils_1.bytesToHex)(this.bytes) === (0, utils_1.bytesToHex)(t.bytes);
+    }
+    /**
+     * Check if this is the default value
+     */
+    isDefault() {
+        return this.default_;
+    }
+    /**
+     * Get blob representation
+     */
+    toBlob() {
+        const bytesList = new binary_serializer_1.BytesList();
+        const s = new binary_serializer_1.BinarySerializer(bytesList);
+        this.add(s);
+        return bytesList.toBytes();
+    }
+    /**
+     * Get the size (number of bytes in serialized form)
+     */
+    size() {
+        const bytesList = new binary_serializer_1.BytesList();
+        const s = new binary_serializer_1.BinarySerializer(bytesList);
+        this.add(s);
+        return bytesList.getLength();
+    }
+    /**
+     * Set the value from another STJson
+     */
+    setValue(v) {
+        if (!(v instanceof STJson)) {
+            throw new Error('setValue: value must be STJson');
+        }
+        ;
+        this.data = v.data;
+        this.jsonType = v.jsonType;
+    }
+    /**
+     * Get serialized type ID
+     */
+    getSType() {
+        return serialized_type_1.SerializedTypeID.STI_JSON;
+    }
+}
+exports.STJson = STJson;
+STJson.JsonType = {
+    Object: 0x00,
+    Array: 0x01,
+};
+//# sourceMappingURL=json.js.map