@netkitty/codec 1.0.0

package/dist/headers/cms/PerDecoder.js

@@ -0,0 +1,211 @@
+"use strict";
+var _a;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PerDecoder = void 0;
+const PerReader_1 = require("./PerReader");
+/**
+ * PerDecoder — a never-throwing ALIGNED BASIC-PER interpreter. It walks an {@link AsnType} descriptor,
+ * pulling from a {@link PerReader}, and returns a plain JS value tree for DISPLAY only (CMS keeps the raw
+ * service-data bytes as the authoritative encode form, so this decoder never affects output bytes). When it
+ * meets something it cannot safely decode — a fragmented length, an unknown `ref`, or an extensible type
+ * whose additions are present — it sets {@link bailed} so the caller can fall back to showing raw hex.
+ */
+class PerDecoder {
+    static #MAX_DEPTH = 64;
+    #reader;
+    #table;
+    #bailed;
+    #depth;
+    constructor(buf, table = {}) {
+        this.#reader = new PerReader_1.PerReader(buf);
+        this.#table = table;
+        this.#bailed = false;
+        this.#depth = 0;
+    }
+    /** True once the decoder hit a construct it could not safely decode; the result is then incomplete. */
+    get bailed() {
+        return this.#bailed;
+    }
+    /** Bytes consumed so far (rounded down) — lets the caller show any trailing bytes as raw. */
+    get bytePos() {
+        return this.#reader.bytePos();
+    }
+    decode(type) {
+        return this.#decode(type);
+    }
+    #decode(type) {
+        if (this.#depth >= _a.#MAX_DEPTH) {
+            //Runaway recursion (a malformed/pathological descriptor): stop rather than overflow the stack.
+            this.#bailed = true;
+            return undefined;
+        }
+        this.#depth++;
+        try {
+            return this.#dispatch(type);
+        }
+        finally {
+            this.#depth--;
+        }
+    }
+    #dispatch(type) {
+        switch (type.k) {
+            case 'bool':
+                return this.#reader.readBit() === 1;
+            case 'int':
+                return this.#decodeInt(type);
+            case 'enum':
+                return this.#decodeEnum(type);
+            case 'bitstr':
+            case 'octstr':
+                return this.#decodeString(type);
+            case 'vstr':
+                return this.#decodeVisibleString(type);
+            case 'seq':
+                return this.#decodeSequence(type);
+            case 'seqof':
+                return this.#decodeSequenceOf(type);
+            case 'choice':
+                return this.#decodeChoice(type);
+            case 'ref':
+                return this.#decodeRef(type);
+        }
+    }
+    #decodeInt(type) {
+        if (type.lb !== undefined && type.ub !== undefined)
+            return this.#reader.readConstrainedInt(type.lb, type.ub);
+        //Unconstrained / semi-constrained: a length determinant then that many octets, octet-aligned.
+        const length = this.#reader.readLengthDeterminant();
+        if (length.fragmented) {
+            this.#bailed = true;
+            return 0;
+        }
+        const octets = this.#reader.readOctets(length.value);
+        if (octets.length === 0)
+            return type.lb ?? 0;
+        //Accumulate with BigInt so any width (up to INT64) is exact — a JS number loses precision past 2^53.
+        let value = 0n;
+        for (let i = 0; i < octets.length; i++)
+            value = (value << 8n) | BigInt(octets[i]);
+        if (type.lb !== undefined) {
+            //Semi-constrained (lb..MAX): the octets are the unsigned value offset by the lower bound.
+            value += BigInt(type.lb);
+        }
+        else if (octets[0] & 0x80) {
+            //Fully unconstrained INTEGER: the octets are a two's-complement signed value.
+            value -= 1n << BigInt(octets.length * 8);
+        }
+        return _a.#bigToJson(value);
+    }
+    /** Return a BigInt as a plain number when it fits exactly in a JS number, else a decimal string, so the
+     *  display tree stays JSON-serializable and never loses precision on 64-bit values. */
+    static #bigToJson(value) {
+        if (value >= BigInt(Number.MIN_SAFE_INTEGER) && value <= BigInt(Number.MAX_SAFE_INTEGER))
+            return Number(value);
+        return value.toString();
+    }
+    #decodeEnum(type) {
+        if (type.ext && this.#reader.readBit() === 1) {
+            //An extension addition: index is a normally-small-non-negative number we do not decode.
+            this.#bailed = true;
+            return '';
+        }
+        const idx = this.#reader.readConstrainedInt(0, type.values.length - 1);
+        return type.values[idx] ?? idx;
+    }
+    #decodeString(type) {
+        //Fixed-size BIT STRING: `size` is a bit count. Its content octet-aligns unless the whole string is
+        //≤ 16 bits (X.691 small-string exception — Quality SIZE(13), Dbpos/Tcmd/Check SIZE(2) pack unaligned).
+        if (type.k === 'bitstr' && type.size !== undefined) {
+            return this.#reader.readBitString(type.size, type.size > 16);
+        }
+        let count;
+        if (type.size !== undefined) {
+            //Fixed-size OCTET STRING: `size` is a byte count.
+            count = type.size;
+        }
+        else {
+            const length = this.#reader.readLengthDeterminant();
+            if (length.fragmented) {
+                this.#bailed = true;
+                return '';
+            }
+            count = type.k === 'bitstr' ? Math.ceil(length.value / 8) : length.value;
+        }
+        return this.#reader.readOctets(count).toString('hex');
+    }
+    #decodeVisibleString(type) {
+        if (type.min !== undefined && type.max !== undefined) {
+            //Fixed size: no length field. Content octet-aligns unless the whole string is ≤ 16 bits
+            //(X.691 small-string exception — 8 bits/char, so a 1- or 2-char fixed string packs unaligned).
+            if (type.max === type.min)
+                return this.#reader.readCharString(type.min, type.min * 8 > 16);
+            const count = this.#reader.readConstrainedInt(type.min, type.max);
+            return this.#reader.readOctets(count).toString('latin1');
+        }
+        return this.#reader.readLengthPrefixedString();
+    }
+    #decodeSequence(type) {
+        //Leading extension bit (extensible SEQUENCE): if additions are present we decode the root fields
+        //then stop, leaving the additions for the raw-hex fallback.
+        let extensions = false;
+        if (type.ext)
+            extensions = this.#reader.readBit() === 1;
+        //Preamble bitmap: one present/absent bit per OPTIONAL / DEFAULT component, in order.
+        const optionals = type.fields.filter((f) => !!f.optional || f.default !== undefined);
+        const present = {};
+        for (const field of optionals)
+            present[field.name] = this.#reader.readBit() === 1;
+        const out = {};
+        for (const field of type.fields) {
+            const isOptional = !!field.optional || field.default !== undefined;
+            if (isOptional && !present[field.name]) {
+                if (field.default !== undefined)
+                    out[field.name] = field.default;
+                continue;
+            }
+            out[field.name] = this.#decode(field.type);
+        }
+        if (extensions)
+            this.#bailed = true;
+        return out;
+    }
+    #decodeSequenceOf(type) {
+        const length = this.#reader.readLengthDeterminant();
+        if (length.fragmented) {
+            this.#bailed = true;
+            return [];
+        }
+        const out = [];
+        for (let i = 0; i < length.value; i++) {
+            if (this.#reader.bitsRemaining() <= 0) {
+                this.#bailed = true;
+                break;
+            }
+            out.push(this.#decode(type.element));
+        }
+        return out;
+    }
+    #decodeChoice(type) {
+        if (type.ext && this.#reader.readBit() === 1) {
+            this.#bailed = true;
+            return {};
+        }
+        const idx = this.#reader.readConstrainedInt(0, type.alts.length - 1);
+        const alt = type.alts[idx];
+        if (!alt) {
+            this.#bailed = true;
+            return {};
+        }
+        return { [alt.name]: this.#decode(alt.type) };
+    }
+    #decodeRef(type) {
+        const resolved = this.#table[type.name];
+        if (!resolved) {
+            this.#bailed = true;
+            return undefined;
+        }
+        return this.#decode(resolved);
+    }
+}
+exports.PerDecoder = PerDecoder;
+_a = PerDecoder;

package/dist/headers/cms/PerReader.d.ts

@@ -0,0 +1,64 @@
+/**
+ * PerReader — a clamping, never-throwing bit cursor for ASN.1 ALIGNED BASIC-PER (ITU-T X.691 / GB/T
+ * 16263.2), used to decode the CMS (DL/T 2811-2024) service data area for DISPLAY. It reads from a
+ * Buffer with a bit position and octet-aligns on demand. Past the end of the buffer every read returns
+ * zero/empty rather than throwing, so a truncated or mis-typed frame degrades gracefully (the CMS layer
+ * keeps the raw bytes verbatim as the authoritative encode form regardless).
+ *
+ * ALIGNED-PER rules implemented here (the parts CMS ACSI needs):
+ *  - a constrained INTEGER whose range ≤ 255 packs in ceil(log2(range)) bits with NO alignment;
+ *  - a constrained INTEGER whose range is larger, and every length determinant, OCTET/BIT STRING and
+ *    character-string content, octet-aligns first;
+ *  - a length determinant is 1 octet when < 128, else 2 octets (top bits 10) up to 16383 (fragmentation
+ *    for larger values is reported so the caller can bail to verbatim).
+ */
+export declare class PerReader {
+    #private;
+    constructor(buf: Buffer);
+    /** Current byte position (rounded down). */
+    bytePos(): number;
+    /** Bits still available. */
+    bitsRemaining(): number;
+    /** Read one bit (0 past the end). */
+    readBit(): number;
+    /** Read n bits as an unsigned number (n ≤ 32; 0 past the end). */
+    readBits(n: number): number;
+    /** Advance to the next octet boundary. */
+    align(): void;
+    /** Read n whole octets (octet-aligns first). Clamps the returned slice to the buffer; the cursor still
+     *  advances the full n octets so repeated past-the-end reads stay monotonic (never rewind). */
+    readOctets(n: number): Buffer;
+    /**
+     * A constrained INTEGER in [lb, ub], ALIGNED-PER (X.691 §11.5.7): range==1 → 0 bits (the value is lb);
+     * range ≤ 255 → the minimal bit-field, no alignment; range == 256 → one octet-aligned octet; range in
+     * 257..65536 → two octet-aligned octets; range > 65536 → a length determinant (octet count) then that
+     * many octet-aligned octets (§11.5.7.4). Multiplication is used for the octet accumulation so 32-bit
+     * values do not overflow a shift.
+     */
+    readConstrainedInt(lb: number, ub: number): number;
+    /**
+     * A general length determinant (X.691 §10.9). Octet-aligns first. Returns {value, fragmented}: 1 octet
+     * for 0..127, 2 octets for 128..16383, otherwise the fragmented form (16k-block count) which the
+     * caller should treat as "bail to verbatim".
+     */
+    readLengthDeterminant(): {
+        value: number;
+        fragmented: boolean;
+    };
+    /** A VisibleString / character string with a length determinant then octet-aligned content. */
+    readLengthPrefixedString(): string;
+    /**
+     * Read n characters of a known-multiplier character string (8 bits/char in ALIGNED-PER, e.g.
+     * VisibleString). Aligned-PER octet-aligns the content, EXCEPT a fixed string whose whole size is ≤ 16
+     * bits packs its 8-bit chars contiguously with no alignment (X.691 small-string exception). Pass
+     * aligned=false for that case.
+     */
+    readCharString(n: number, aligned: boolean): string;
+    /**
+     * Read a fixed-size BIT STRING of `nBits` bits, returning it as hex, the bits left-aligned (MSB first)
+     * into ceil(nBits/8) octets with trailing zero padding — the usual BIT STRING display form. Pass
+     * aligned=true (octet-align the content first) for strings wider than 16 bits; ≤16-bit fixed strings
+     * pack unaligned (X.691 small-string exception).
+     */
+    readBitString(nBits: number, aligned: boolean): string;
+}

package/dist/headers/cms/PerReader.js

@@ -0,0 +1,155 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PerReader = void 0;
+/**
+ * PerReader — a clamping, never-throwing bit cursor for ASN.1 ALIGNED BASIC-PER (ITU-T X.691 / GB/T
+ * 16263.2), used to decode the CMS (DL/T 2811-2024) service data area for DISPLAY. It reads from a
+ * Buffer with a bit position and octet-aligns on demand. Past the end of the buffer every read returns
+ * zero/empty rather than throwing, so a truncated or mis-typed frame degrades gracefully (the CMS layer
+ * keeps the raw bytes verbatim as the authoritative encode form regardless).
+ *
+ * ALIGNED-PER rules implemented here (the parts CMS ACSI needs):
+ *  - a constrained INTEGER whose range ≤ 255 packs in ceil(log2(range)) bits with NO alignment;
+ *  - a constrained INTEGER whose range is larger, and every length determinant, OCTET/BIT STRING and
+ *    character-string content, octet-aligns first;
+ *  - a length determinant is 1 octet when < 128, else 2 octets (top bits 10) up to 16383 (fragmentation
+ *    for larger values is reported so the caller can bail to verbatim).
+ */
+class PerReader {
+    #buf;
+    #bit;
+    constructor(buf) {
+        this.#buf = buf;
+        this.#bit = 0;
+    }
+    /** Current byte position (rounded down). */
+    bytePos() {
+        return this.#bit >> 3;
+    }
+    /** Bits still available. */
+    bitsRemaining() {
+        return this.#buf.length * 8 - this.#bit;
+    }
+    /** Read one bit (0 past the end). */
+    readBit() {
+        if (this.#bit >= this.#buf.length * 8) {
+            this.#bit++;
+            return 0;
+        }
+        const byte = this.#buf[this.#bit >> 3];
+        const bit = (byte >> (7 - (this.#bit & 7))) & 1;
+        this.#bit++;
+        return bit;
+    }
+    /** Read n bits as an unsigned number (n ≤ 32; 0 past the end). */
+    readBits(n) {
+        let value = 0;
+        for (let i = 0; i < n; i++)
+            value = (value << 1) | this.readBit();
+        return value >>> 0;
+    }
+    /** Advance to the next octet boundary. */
+    align() {
+        if (this.#bit & 7)
+            this.#bit = (this.#bit + 7) & ~7;
+    }
+    /** Read n whole octets (octet-aligns first). Clamps the returned slice to the buffer; the cursor still
+     *  advances the full n octets so repeated past-the-end reads stay monotonic (never rewind). */
+    readOctets(n) {
+        this.align();
+        const start = this.#bit >> 3;
+        const end = start + n;
+        this.#bit = end * 8;
+        const sliceStart = start > this.#buf.length ? this.#buf.length : start;
+        const sliceEnd = end > this.#buf.length ? this.#buf.length : end;
+        return this.#buf.subarray(sliceStart, sliceEnd < sliceStart ? sliceStart : sliceEnd);
+    }
+    /**
+     * A constrained INTEGER in [lb, ub], ALIGNED-PER (X.691 §11.5.7): range==1 → 0 bits (the value is lb);
+     * range ≤ 255 → the minimal bit-field, no alignment; range == 256 → one octet-aligned octet; range in
+     * 257..65536 → two octet-aligned octets; range > 65536 → a length determinant (octet count) then that
+     * many octet-aligned octets (§11.5.7.4). Multiplication is used for the octet accumulation so 32-bit
+     * values do not overflow a shift.
+     */
+    readConstrainedInt(lb, ub) {
+        const range = ub - lb + 1;
+        if (range <= 1)
+            return lb;
+        if (range < 256) {
+            let bits = 0;
+            while ((1 << bits) < range)
+                bits++;
+            return lb + this.readBits(bits);
+        }
+        if (range === 256)
+            return lb + (this.readOctets(1)[0] ?? 0);
+        if (range <= 65536) {
+            const two = this.readOctets(2);
+            return lb + (((two[0] ?? 0) << 8) | (two[1] ?? 0));
+        }
+        //range > 65536: length-determinant-prefixed minimal-octet form, octet-aligned.
+        const length = this.readLengthDeterminant();
+        if (length.fragmented)
+            return lb;
+        const buf = this.readOctets(length.value);
+        let value = 0;
+        for (let i = 0; i < buf.length; i++)
+            value = (value * 256) + buf[i];
+        return lb + value;
+    }
+    /**
+     * A general length determinant (X.691 §10.9). Octet-aligns first. Returns {value, fragmented}: 1 octet
+     * for 0..127, 2 octets for 128..16383, otherwise the fragmented form (16k-block count) which the
+     * caller should treat as "bail to verbatim".
+     */
+    readLengthDeterminant() {
+        this.align();
+        const first = this.readOctets(1)[0] ?? 0;
+        if ((first & 0x80) === 0)
+            return { value: first & 0x7f, fragmented: false };
+        if ((first & 0xc0) === 0x80) {
+            const second = this.readOctets(1)[0] ?? 0;
+            return { value: ((first & 0x3f) << 8) | second, fragmented: false };
+        }
+        //Fragmented (top bits 11): the low 6 bits × 16384 is the first block size; not fully decoded here.
+        return { value: (first & 0x3f) * 16384, fragmented: true };
+    }
+    /** A VisibleString / character string with a length determinant then octet-aligned content. */
+    readLengthPrefixedString() {
+        const length = this.readLengthDeterminant();
+        if (length.fragmented)
+            return '';
+        return this.readOctets(length.value).toString('latin1');
+    }
+    /**
+     * Read n characters of a known-multiplier character string (8 bits/char in ALIGNED-PER, e.g.
+     * VisibleString). Aligned-PER octet-aligns the content, EXCEPT a fixed string whose whole size is ≤ 16
+     * bits packs its 8-bit chars contiguously with no alignment (X.691 small-string exception). Pass
+     * aligned=false for that case.
+     */
+    readCharString(n, aligned) {
+        if (aligned)
+            return this.readOctets(n).toString('latin1');
+        let out = '';
+        for (let i = 0; i < n; i++)
+            out += String.fromCharCode(this.readBits(8));
+        return out;
+    }
+    /**
+     * Read a fixed-size BIT STRING of `nBits` bits, returning it as hex, the bits left-aligned (MSB first)
+     * into ceil(nBits/8) octets with trailing zero padding — the usual BIT STRING display form. Pass
+     * aligned=true (octet-align the content first) for strings wider than 16 bits; ≤16-bit fixed strings
+     * pack unaligned (X.691 small-string exception).
+     */
+    readBitString(nBits, aligned) {
+        if (aligned)
+            this.align();
+        const out = Buffer.alloc(Math.ceil(nBits / 8));
+        for (let i = 0; i < nBits; i++) {
+            if (this.readBit())
+                out[i >> 3] |= 0x80 >> (i & 7);
+        }
+        return out.toString('hex');
+    }
+}
+exports.PerReader = PerReader;

package/dist/helper/BufferToHex.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Convert a buffer to a lower-case hex string (two hex chars per byte, zero-padded).
+ * @param buffer
+ */
+export declare function BufferToHex(buffer: Buffer): string;

package/dist/helper/BufferToHex.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BufferToHex = BufferToHex;
+/**
+ * Convert a buffer to a lower-case hex string (two hex chars per byte, zero-padded).
+ * @param buffer
+ */
+function BufferToHex(buffer) {
+    return buffer.toString('hex').padStart(buffer.length * 2, '0');
+}

package/dist/helper/BufferToIP.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Convert Buffer to IPv4 string
+ * @param buffer
+ * @constructor
+ */
+export declare function BufferToIPv4(buffer: Buffer): string;
+/**
+ * Convert Buffer to IPv6 string
+ * @param buffer
+ * @constructor
+ */
+export declare function BufferToIPv6(buffer: Buffer): string;

package/dist/helper/BufferToIP.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BufferToIPv4 = BufferToIPv4;
+exports.BufferToIPv6 = BufferToIPv6;
+const ip_address_1 = require("ip-address");
+/**
+ * Convert Buffer to IPv4 string
+ * @param buffer
+ * @constructor
+ */
+function BufferToIPv4(buffer) {
+    //Direct dotted-quad formatting; the old ip-address-library + BigInt + hex path micro-benchmarked
+    //~20x slower per address. Missing bytes read as 0, matching the previous zero-padded behaviour.
+    return `${buffer.length > 0 ? buffer[0] : 0}.${buffer.length > 1 ? buffer[1] : 0}.${buffer.length > 2 ? buffer[2] : 0}.${buffer.length > 3 ? buffer[3] : 0}`;
+}
+/**
+ * Convert Buffer to IPv6 string
+ * @param buffer
+ * @constructor
+ */
+function BufferToIPv6(buffer) {
+    return ip_address_1.Address6.fromBigInt(BigInt(`0x${Buffer.concat([buffer.subarray(0, 16), Buffer.alloc(16)]).subarray(0, 16).toString('hex').padStart(32, '0')}`)).address;
+}

package/dist/helper/BufferToNumber.d.ts

@@ -0,0 +1,18 @@
+/** Read a signed 8-bit integer from the start of `buffer` (0 when empty). */
+export declare const BufferToInt8: (buffer: Buffer) => number;
+/** Read a big-endian signed 16-bit integer from the start of `buffer` (short buffers read their available low bytes unsigned). */
+export declare const BufferToInt16: (buffer: Buffer) => number;
+/** Read a big-endian signed 32-bit integer from the start of `buffer` (short buffers read their available low bytes unsigned). */
+export declare const BufferToInt32: (buffer: Buffer) => number;
+/** Read a big-endian signed 64-bit integer from `buffer` as a bigint (clamped to the int64 range on overflow). */
+export declare const BufferToInt64: (buffer: Buffer) => bigint;
+/** Read an unsigned 8-bit integer from the start of `buffer` (0 when empty). */
+export declare const BufferToUInt8: (buffer: Buffer) => number;
+/** Read a big-endian unsigned 16-bit integer from the start of `buffer` (short buffers read their available low bytes). */
+export declare const BufferToUInt16: (buffer: Buffer) => number;
+/** Read a big-endian unsigned 32-bit integer from the start of `buffer` (short buffers read their available low bytes). */
+export declare const BufferToUInt32: (buffer: Buffer) => number;
+/** Read a big-endian unsigned 64-bit integer from `buffer` as a bigint (clamped to the uint64 range on overflow). */
+export declare const BufferToUInt64: (buffer: Buffer) => bigint;
+/** Read a big-endian IEEE-754 32-bit float from `buffer`. */
+export declare const BufferToFloat32: (buffer: Buffer) => number;

package/dist/helper/BufferToNumber.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BufferToFloat32 = exports.BufferToUInt64 = exports.BufferToUInt32 = exports.BufferToUInt16 = exports.BufferToUInt8 = exports.BufferToInt64 = exports.BufferToInt32 = exports.BufferToInt16 = exports.BufferToInt8 = void 0;
+const HexToNumber_1 = require("./HexToNumber");
+//8/16/32-bit reads use native Buffer accessors instead of the old hex-string roundtrip
+//(buffer.toString('hex') → parseInt → TypedArray), which micro-benchmarked ~27x slower per call and
+//runs on every scalar field of every packet. Behaviour is preserved bit-for-bit, including the
+//best-effort handling of short/truncated buffers: missing high bytes read as 0, so a partial buffer
+//yields the value of its available low bytes (verified equivalent across full/short/empty/signed/edge
+//cases). Signed reads fall back to an unsigned low-byte read when the buffer is shorter than the type
+//width — at less than full width the high (sign) byte is absent, so the value is always non-negative,
+//exactly as the hex path produced it. 64-bit and float paths keep their existing implementations
+//(64-bit carries clamping semantics; both are comparatively rare).
+//
+//ONE deliberate semantic change vs the old hex path: for a buffer LONGER than the type width, the
+//native readers take the big-endian high bytes (readUInt16BE reads the first 2 octets), whereas the
+//old parseInt→TypedArray path wrapped to the low bytes. Big-endian is the correct network-byte-order
+//reading. This is only reachable via variable-length callers (SV's BER-TLV getValue('buffer')); the
+//fixed-width readBytes(offset,N) callers can never produce an over-wide buffer. Not a round-trip
+//regression (over-wide TLVs are re-normalised on encode); affects only a malformed packet's shown value.
+/** Read a signed 8-bit integer from the start of `buffer` (0 when empty). */
+const BufferToInt8 = (buffer) => buffer.length ? buffer.readInt8(0) : 0;
+exports.BufferToInt8 = BufferToInt8;
+/** Read a big-endian signed 16-bit integer from the start of `buffer` (short buffers read their available low bytes unsigned). */
+const BufferToInt16 = (buffer) => buffer.length >= 2 ? buffer.readInt16BE(0) : (buffer.length ? buffer.readUIntBE(0, buffer.length) : 0);
+exports.BufferToInt16 = BufferToInt16;
+/** Read a big-endian signed 32-bit integer from the start of `buffer` (short buffers read their available low bytes unsigned). */
+const BufferToInt32 = (buffer) => buffer.length >= 4 ? buffer.readInt32BE(0) : (buffer.length ? buffer.readUIntBE(0, buffer.length) : 0);
+exports.BufferToInt32 = BufferToInt32;
+/** Read a big-endian signed 64-bit integer from `buffer` as a bigint (clamped to the int64 range on overflow). */
+const BufferToInt64 = (buffer) => (0, HexToNumber_1.HexToInt64)(buffer.toString('hex'));
+exports.BufferToInt64 = BufferToInt64;
+/** Read an unsigned 8-bit integer from the start of `buffer` (0 when empty). */
+const BufferToUInt8 = (buffer) => buffer.length ? buffer.readUInt8(0) : 0;
+exports.BufferToUInt8 = BufferToUInt8;
+/** Read a big-endian unsigned 16-bit integer from the start of `buffer` (short buffers read their available low bytes). */
+const BufferToUInt16 = (buffer) => buffer.length >= 2 ? buffer.readUInt16BE(0) : (buffer.length ? buffer.readUIntBE(0, buffer.length) : 0);
+exports.BufferToUInt16 = BufferToUInt16;
+/** Read a big-endian unsigned 32-bit integer from the start of `buffer` (short buffers read their available low bytes). */
+const BufferToUInt32 = (buffer) => buffer.length >= 4 ? buffer.readUInt32BE(0) : (buffer.length ? buffer.readUIntBE(0, buffer.length) : 0);
+exports.BufferToUInt32 = BufferToUInt32;
+/** Read a big-endian unsigned 64-bit integer from `buffer` as a bigint (clamped to the uint64 range on overflow). */
+const BufferToUInt64 = (buffer) => (0, HexToNumber_1.HexToUInt64)(buffer.toString('hex'));
+exports.BufferToUInt64 = BufferToUInt64;
+/** Read a big-endian IEEE-754 32-bit float from `buffer`. */
+const BufferToFloat32 = (buffer) => (0, HexToNumber_1.HexToFloat32)(buffer.toString('hex'));
+exports.BufferToFloat32 = BufferToFloat32;

package/dist/helper/HexToBuffer.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Convert hex to buffer
+ * @param hex
+ * @param bufferLength
+ * @constructor
+ */
+export declare function HexToBuffer(hex: string, bufferLength?: number): Buffer;

package/dist/helper/HexToBuffer.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HexToBuffer = HexToBuffer;
+/**
+ * Convert hex to buffer
+ * @param hex
+ * @param bufferLength
+ * @constructor
+ */
+function HexToBuffer(hex, bufferLength) {
+    if (!hex)
+        return Buffer.alloc(0);
+    const inputHex = hex.length % 2 ? hex.padStart(hex.length + 1, '0') : hex;
+    const outputBufferLength = bufferLength ? bufferLength : inputHex.length / 2;
+    let buffer = Buffer.from(inputHex, 'hex');
+    if (buffer.length > outputBufferLength) {
+        buffer.subarray(0, outputBufferLength);
+    }
+    else if (buffer.length < outputBufferLength) {
+        const paddingLength = outputBufferLength - buffer.length;
+        buffer = Buffer.concat([
+            Buffer.alloc(paddingLength, 0x00),
+            buffer
+        ]);
+    }
+    return buffer;
+}

package/dist/helper/HexToNumber.d.ts

@@ -0,0 +1,18 @@
+/** Parse a hex string as a signed 8-bit integer (two's complement). */
+export declare const HexToInt8: (hex: string) => number;
+/** Parse a big-endian hex string as a signed 16-bit integer (two's complement). */
+export declare const HexToInt16: (hex: string) => number;
+/** Parse a big-endian hex string as a signed 32-bit integer (two's complement). */
+export declare const HexToInt32: (hex: string) => number;
+/** Parse a big-endian hex string as a signed 64-bit bigint (clamped to the int64 range on overflow). */
+export declare const HexToInt64: (hex: string) => bigint;
+/** Parse a hex string as an unsigned 8-bit integer. */
+export declare const HexToUInt8: (hex: string) => number;
+/** Parse a big-endian hex string as an unsigned 16-bit integer. */
+export declare const HexToUInt16: (hex: string) => number;
+/** Parse a big-endian hex string as an unsigned 32-bit integer. */
+export declare const HexToUInt32: (hex: string) => number;
+/** Parse a big-endian hex string as an unsigned 64-bit bigint (clamped to the uint64 range on overflow). */
+export declare const HexToUInt64: (hex: string) => bigint;
+/** Parse a big-endian hex string as an IEEE-754 32-bit float. */
+export declare const HexToFloat32: (hex: string) => number;

package/dist/helper/HexToNumber.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HexToFloat32 = exports.HexToUInt64 = exports.HexToUInt32 = exports.HexToUInt16 = exports.HexToUInt8 = exports.HexToInt64 = exports.HexToInt32 = exports.HexToInt16 = exports.HexToInt8 = void 0;
+/** Parse a hex string as a signed 8-bit integer (two's complement). */
+const HexToInt8 = (hex) => Int8Array.from([parseInt(hex, 16)])[0];
+exports.HexToInt8 = HexToInt8;
+/** Parse a big-endian hex string as a signed 16-bit integer (two's complement). */
+const HexToInt16 = (hex) => Int16Array.from([parseInt(hex, 16)])[0];
+exports.HexToInt16 = HexToInt16;
+/** Parse a big-endian hex string as a signed 32-bit integer (two's complement). */
+const HexToInt32 = (hex) => Int32Array.from([parseInt(hex, 16)])[0];
+exports.HexToInt32 = HexToInt32;
+/** Parse a big-endian hex string as a signed 64-bit bigint (clamped to the int64 range on overflow). */
+const HexToInt64 = (hex) => {
+    const INT64_MAX = BigInt('9223372036854775807');
+    const INT64_MIN = BigInt('-9223372036854775808');
+    const bigIntValue = BigInt(`0x${hex}`);
+    if (bigIntValue < INT64_MIN || bigIntValue > INT64_MAX)
+        return INT64_MAX;
+    return bigIntValue;
+};
+exports.HexToInt64 = HexToInt64;
+/** Parse a hex string as an unsigned 8-bit integer. */
+const HexToUInt8 = (hex) => Uint8Array.from([parseInt(hex, 16)])[0];
+exports.HexToUInt8 = HexToUInt8;
+/** Parse a big-endian hex string as an unsigned 16-bit integer. */
+const HexToUInt16 = (hex) => Uint16Array.from([parseInt(hex, 16)])[0];
+exports.HexToUInt16 = HexToUInt16;
+/** Parse a big-endian hex string as an unsigned 32-bit integer. */
+const HexToUInt32 = (hex) => Uint32Array.from([parseInt(hex, 16)])[0];
+exports.HexToUInt32 = HexToUInt32;
+/** Parse a big-endian hex string as an unsigned 64-bit bigint (clamped to the uint64 range on overflow). */
+const HexToUInt64 = (hex) => {
+    const INT64_MAX = BigInt('18446744073709551615');
+    const bigIntValue = BigInt(`0x${hex}`);
+    if (bigIntValue < 0n || bigIntValue > INT64_MAX)
+        return INT64_MAX;
+    return bigIntValue;
+};
+exports.HexToUInt64 = HexToUInt64;
+/** Parse a big-endian hex string as an IEEE-754 32-bit float. */
+const HexToFloat32 = (hex) => {
+    const buffer = new ArrayBuffer(4);
+    const dataView = new DataView(buffer);
+    dataView.setUint32(0, parseInt(hex, 16), false);
+    return dataView.getFloat32(0, false);
+};
+exports.HexToFloat32 = HexToFloat32;