@bcts/dcbor 1.0.0-alpha.17 → 1.0.0-alpha.18

package/dist/index.iife.js

@@ -8047,6 +8047,268 @@ var import_byte_data = /* @__PURE__ */ __toESM(require_byte_data(), 1);
 		}
 	};
 
+//#endregion
+//#region src/bignum.ts
+/**
+	* CBOR bignum (tags 2 and 3) support.
+	*
+	* This module provides conversion between CBOR and JavaScript BigInt types,
+	* implementing RFC 8949 §3.4.3 (Bignums) with dCBOR/CDE canonical encoding rules.
+	*
+	* Encoding:
+	* - `biguintToCbor` always encodes as tag 2 (positive bignum) with a byte
+	*   string content.
+	* - `bigintToCbor` encodes as tag 2 for non-negative values or tag 3
+	*   (negative bignum) for negative values.
+	* - No numeric reduction is performed: values are always encoded as bignums,
+	*   even if they would fit in normal CBOR integers.
+	*
+	* Decoding:
+	* - Accepts CBOR integers (major types 0 and 1) and converts them to bigints.
+	* - Accepts tag 2 (positive bignum) and tag 3 (negative bignum) with byte
+	*   string content.
+	* - Enforces shortest-form canonical representation for bignum magnitudes.
+	* - Rejects floating-point values.
+	*
+	* @module bignum
+	*/
+	const TAG_2_POSITIVE_BIGNUM = 2;
+	const TAG_3_NEGATIVE_BIGNUM = 3;
+	/**
+	* Validates that a bignum magnitude byte string is in shortest canonical form.
+	*
+	* Matches Rust's `validate_bignum_magnitude()`.
+	*
+	* Rules:
+	* - For positive bignums (tag 2): empty byte string represents zero;
+	*   non-empty must not have leading zero bytes.
+	* - For negative bignums (tag 3): byte string must not be empty
+	*   (magnitude zero is encoded as `0x00`); must not have leading zero bytes
+	*   except when the magnitude is zero (single `0x00`).
+	*
+	* @param bytes - The magnitude byte string to validate
+	* @param isNegative - Whether this is for a negative bignum (tag 3)
+	* @throws CborError with type NonCanonicalNumeric on validation failure
+	*/
+	function validateBignumMagnitude(bytes, isNegative) {
+		if (isNegative) {
+			if (bytes.length === 0) throw new CborError({ type: "NonCanonicalNumeric" });
+			if (bytes.length > 1 && bytes[0] === 0) throw new CborError({ type: "NonCanonicalNumeric" });
+		} else if (bytes.length > 0 && bytes[0] === 0) throw new CborError({ type: "NonCanonicalNumeric" });
+	}
+	/**
+	* Strips leading zero bytes from a byte array, returning the minimal
+	* representation.
+	*
+	* Matches Rust's `strip_leading_zeros()`.
+	*
+	* @param bytes - The byte array to strip
+	* @returns A subarray with leading zeros removed
+	*/
+	function stripLeadingZeros(bytes) {
+		let start = 0;
+		while (start < bytes.length && bytes[start] === 0) start++;
+		return bytes.subarray(start);
+	}
+	/**
+	* Convert a non-negative bigint to a big-endian byte array.
+	*
+	* Zero returns an empty Uint8Array.
+	*
+	* @param value - A non-negative bigint value
+	* @returns Big-endian byte representation
+	*/
+	function bigintToBytes(value) {
+		if (value === 0n) return new Uint8Array(0);
+		const hex = value.toString(16);
+		const padded = hex.length % 2 !== 0 ? `0${hex}` : hex;
+		const bytes = new Uint8Array(padded.length / 2);
+		for (let i = 0; i < bytes.length; i++) bytes[i] = parseInt(padded.substring(i * 2, i * 2 + 2), 16);
+		return bytes;
+	}
+	/**
+	* Convert a big-endian byte array to a bigint.
+	*
+	* Empty array returns 0n.
+	*
+	* @param bytes - Big-endian byte representation
+	* @returns The bigint value
+	*/
+	function bytesToBigint(bytes) {
+		if (bytes.length === 0) return 0n;
+		let result = 0n;
+		for (const byte of bytes) result = result << 8n | BigInt(byte);
+		return result;
+	}
+	/**
+	* Encode a non-negative bigint as a CBOR tag 2 (positive bignum).
+	*
+	* Matches Rust's `From<BigUint> for CBOR`.
+	*
+	* The value is always encoded as a bignum regardless of size.
+	* Zero is encoded as tag 2 with an empty byte string.
+	*
+	* @param value - A non-negative bigint (must be >= 0n)
+	* @returns CBOR tagged value
+	* @throws CborError with type OutOfRange if value is negative
+	*/
+	function biguintToCbor(value) {
+		if (value < 0n) throw new CborError({ type: "OutOfRange" });
+		return toTaggedValue(TAG_2_POSITIVE_BIGNUM, stripLeadingZeros(bigintToBytes(value)));
+	}
+	/**
+	* Encode a bigint as a CBOR tag 2 or tag 3 bignum.
+	*
+	* Matches Rust's `From<BigInt> for CBOR`.
+	*
+	* - Non-negative values use tag 2 (positive bignum).
+	* - Negative values use tag 3 (negative bignum), where the encoded
+	*   magnitude is `|value| - 1` per RFC 8949.
+	*
+	* @param value - Any bigint value
+	* @returns CBOR tagged value
+	*/
+	function bigintToCbor(value) {
+		if (value >= 0n) return biguintToCbor(value);
+		const stripped = stripLeadingZeros(bigintToBytes(-value - 1n));
+		return toTaggedValue(TAG_3_NEGATIVE_BIGNUM, stripped.length === 0 ? new Uint8Array([0]) : stripped);
+	}
+	/**
+	* Decode a BigUint from an untagged CBOR byte string.
+	*
+	* Matches Rust's `biguint_from_untagged_cbor()`.
+	*
+	* This function is intended for use in tag summarizers where the tag has
+	* already been stripped. It expects a CBOR byte string representing the
+	* big-endian magnitude of a positive bignum (tag 2 content).
+	*
+	* Enforces canonical encoding: no leading zero bytes (except empty for zero).
+	*
+	* @param cbor - A CBOR value that should be a byte string
+	* @returns Non-negative bigint
+	* @throws CborError with type WrongType if not a byte string
+	* @throws CborError with type NonCanonicalNumeric if encoding is non-canonical
+	*/
+	function biguintFromUntaggedCbor(cbor) {
+		if (cbor.type !== MajorType.ByteString) throw new CborError({ type: "WrongType" });
+		const bytes = cbor.value;
+		validateBignumMagnitude(bytes, false);
+		return bytesToBigint(bytes);
+	}
+	/**
+	* Decode a BigInt from an untagged CBOR byte string for a negative bignum.
+	*
+	* Matches Rust's `bigint_from_negative_untagged_cbor()`.
+	*
+	* This function is intended for use in tag summarizers where the tag has
+	* already been stripped. It expects a CBOR byte string representing `n` where
+	* the actual value is `-1 - n` (tag 3 content per RFC 8949).
+	*
+	* Enforces canonical encoding: no leading zero bytes (except single `0x00`
+	* for -1).
+	*
+	* @param cbor - A CBOR value that should be a byte string
+	* @returns Negative bigint
+	* @throws CborError with type WrongType if not a byte string
+	* @throws CborError with type NonCanonicalNumeric if encoding is non-canonical
+	*/
+	function bigintFromNegativeUntaggedCbor(cbor) {
+		if (cbor.type !== MajorType.ByteString) throw new CborError({ type: "WrongType" });
+		const bytes = cbor.value;
+		validateBignumMagnitude(bytes, true);
+		return -(bytesToBigint(bytes) + 1n);
+	}
+	/**
+	* Convert CBOR to a non-negative bigint.
+	*
+	* Matches Rust's `TryFrom<CBOR> for BigUint`.
+	*
+	* Accepts:
+	* - Major type 0 (unsigned integer)
+	* - Tag 2 (positive bignum) with canonical byte string
+	*
+	* Rejects:
+	* - Major type 1 (negative integer) -> OutOfRange
+	* - Tag 3 (negative bignum) -> OutOfRange
+	* - Floating-point values -> WrongType
+	* - Non-canonical bignum encodings -> NonCanonicalNumeric
+	*
+	* @param cbor - The CBOR value to convert
+	* @returns Non-negative bigint
+	* @throws CborError
+	*/
+	function cborToBiguint(cbor) {
+		switch (cbor.type) {
+			case MajorType.Unsigned: return BigInt(cbor.value);
+			case MajorType.Negative: throw new CborError({ type: "OutOfRange" });
+			case MajorType.Tagged: {
+				const tagValue = Number(cbor.tag);
+				if (tagValue === TAG_2_POSITIVE_BIGNUM) {
+					const inner = cbor.value;
+					if (inner.type !== MajorType.ByteString) throw new CborError({ type: "WrongType" });
+					const bytes = inner.value;
+					validateBignumMagnitude(bytes, false);
+					return bytesToBigint(bytes);
+				} else if (tagValue === TAG_3_NEGATIVE_BIGNUM) throw new CborError({ type: "OutOfRange" });
+				throw new CborError({ type: "WrongType" });
+			}
+			case MajorType.ByteString:
+			case MajorType.Text:
+			case MajorType.Array:
+			case MajorType.Map:
+			case MajorType.Simple: throw new CborError({ type: "WrongType" });
+		}
+	}
+	/**
+	* Convert CBOR to a bigint (any sign).
+	*
+	* Matches Rust's `TryFrom<CBOR> for BigInt`.
+	*
+	* Accepts:
+	* - Major type 0 (unsigned integer)
+	* - Major type 1 (negative integer)
+	* - Tag 2 (positive bignum) with canonical byte string
+	* - Tag 3 (negative bignum) with canonical byte string
+	*
+	* Rejects:
+	* - Floating-point values -> WrongType
+	* - Non-canonical bignum encodings -> NonCanonicalNumeric
+	*
+	* @param cbor - The CBOR value to convert
+	* @returns A bigint value
+	* @throws CborError
+	*/
+	function cborToBigint(cbor) {
+		switch (cbor.type) {
+			case MajorType.Unsigned: return BigInt(cbor.value);
+			case MajorType.Negative: return -(BigInt(cbor.value) + 1n);
+			case MajorType.Tagged: {
+				const tagValue = Number(cbor.tag);
+				if (tagValue === TAG_2_POSITIVE_BIGNUM) {
+					const inner = cbor.value;
+					if (inner.type !== MajorType.ByteString) throw new CborError({ type: "WrongType" });
+					const bytes = inner.value;
+					validateBignumMagnitude(bytes, false);
+					const mag = bytesToBigint(bytes);
+					if (mag === 0n) return 0n;
+					return mag;
+				} else if (tagValue === TAG_3_NEGATIVE_BIGNUM) {
+					const inner = cbor.value;
+					if (inner.type !== MajorType.ByteString) throw new CborError({ type: "WrongType" });
+					const bytes = inner.value;
+					validateBignumMagnitude(bytes, true);
+					return -(bytesToBigint(bytes) + 1n);
+				}
+				throw new CborError({ type: "WrongType" });
+			}
+			case MajorType.ByteString:
+			case MajorType.Text:
+			case MajorType.Array:
+			case MajorType.Map:
+			case MajorType.Simple: throw new CborError({ type: "WrongType" });
+		}
+	}
+
 //#endregion
 //#region src/tags.ts
 /**
@@ -8076,6 +8338,16 @@ var import_byte_data = /* @__PURE__ */ __toESM(require_byte_data(), 1);
 	*/
 	const TAG_NEGATIVE_BIGNUM = 3;
 	/**
+	* Name for tag 2 (positive bignum).
+	* Matches Rust's `TAG_NAME_POSITIVE_BIGNUM`.
+	*/
+	const TAG_NAME_POSITIVE_BIGNUM = "positive-bignum";
+	/**
+	* Name for tag 3 (negative bignum).
+	* Matches Rust's `TAG_NAME_NEGATIVE_BIGNUM`.
+	*/
+	const TAG_NAME_NEGATIVE_BIGNUM = "negative-bignum";
+	/**
 	* Tag 4: Decimal fraction [exponent, mantissa]
 	*/
 	const TAG_DECIMAL_FRACTION = 4;
@@ -8166,6 +8438,41 @@ var import_byte_data = /* @__PURE__ */ __toESM(require_byte_data(), 1);
 				};
 			}
 		});
+		const biguintTag = createTag(TAG_POSITIVE_BIGNUM, TAG_NAME_POSITIVE_BIGNUM);
+		const bigintTag = createTag(TAG_NEGATIVE_BIGNUM, TAG_NAME_NEGATIVE_BIGNUM);
+		tagsStore.insertAll([biguintTag, bigintTag]);
+		tagsStore.setSummarizer(TAG_POSITIVE_BIGNUM, (untaggedCbor, _flat) => {
+			try {
+				return {
+					ok: true,
+					value: `bignum(${biguintFromUntaggedCbor(untaggedCbor)})`
+				};
+			} catch (e) {
+				return {
+					ok: false,
+					error: {
+						type: "Custom",
+						message: e instanceof Error ? e.message : String(e)
+					}
+				};
+			}
+		});
+		tagsStore.setSummarizer(TAG_NEGATIVE_BIGNUM, (untaggedCbor, _flat) => {
+			try {
+				return {
+					ok: true,
+					value: `bignum(${bigintFromNegativeUntaggedCbor(untaggedCbor)})`
+				};
+			} catch (e) {
+				return {
+					ok: false,
+					error: {
+						type: "Custom",
+						message: e instanceof Error ? e.message : String(e)
+					}
+				};
+			}
+		});
 	};
 	/**
 	* Register standard tags in the global tags store.
@@ -8916,6 +9223,8 @@ exports.TAG_EPOCH_DATE = TAG_EPOCH_DATE;
 exports.TAG_EPOCH_DATE_TIME = TAG_EPOCH_DATE_TIME;
 exports.TAG_MIME_MESSAGE = TAG_MIME_MESSAGE;
 exports.TAG_NAME_DATE = TAG_NAME_DATE;
+exports.TAG_NAME_NEGATIVE_BIGNUM = TAG_NAME_NEGATIVE_BIGNUM;
+exports.TAG_NAME_POSITIVE_BIGNUM = TAG_NAME_POSITIVE_BIGNUM;
 exports.TAG_NEGATIVE_BIGNUM = TAG_NEGATIVE_BIGNUM;
 exports.TAG_POSITIVE_BIGNUM = TAG_POSITIVE_BIGNUM;
 exports.TAG_REGEXP = TAG_REGEXP;
@@ -8944,9 +9253,15 @@ exports.asSingle = asSingle;
 exports.asTaggedValue = asTaggedValue;
 exports.asText = asText;
 exports.asUnsigned = asUnsigned;
+exports.bigintFromNegativeUntaggedCbor = bigintFromNegativeUntaggedCbor;
+exports.bigintToCbor = bigintToCbor;
+exports.biguintFromUntaggedCbor = biguintFromUntaggedCbor;
+exports.biguintToCbor = biguintToCbor;
 exports.bytesToHex = bytesToHex;
 exports.cbor = cbor;
 exports.cborData = cborData;
+exports.cborToBigint = cborToBigint;
+exports.cborToBiguint = cborToBiguint;
 exports.createTag = createTag;
 exports.createTaggedCbor = createTaggedCbor;
 exports.decodeCbor = decodeCbor;