@bcts/dcbor 1.0.0-alpha.10

package/src/float.ts

@@ -0,0 +1,279 @@
+/**
+ * Float encoding and conversion utilities for dCBOR.
+ *
+ * # Floating Point Number Support in dCBOR
+ *
+ * dCBOR provides canonical encoding for floating point values.
+ *
+ * Per the dCBOR specification, the canonical encoding rules ensure
+ * deterministic representation:
+ *
+ * - Numeric reduction: Floating point values with zero fractional part in
+ *   range [-2^63, 2^64-1] are automatically encoded as integers (e.g., 42.0
+ *   becomes 42)
+ * - Values are encoded in the smallest possible representation that preserves
+ *   their value
+ * - All NaN values are canonicalized to a single representation: 0xf97e00
+ * - Positive/negative infinity are canonicalized to half-precision
+ *   representations
+ *
+ * @module float
+ */
+
+import * as byteData from "byte-data";
+import { encodeVarInt } from "./varint";
+import { MajorType } from "./cbor";
+import { ExactU64, ExactU32, ExactU16, ExactI128 } from "./exact";
+import { CborError } from "./error";
+
+/**
+ * Canonical NaN representation in CBOR: 0xf97e00
+ */
+export const CBOR_NAN = new Uint8Array([0xf9, 0x7e, 0x00]);
+
+/**
+ * Check if a number has a fractional part.
+ */
+export const hasFractionalPart = (n: number): boolean => n !== Math.floor(n);
+
+/**
+ * Convert 64-bit binary to number.
+ * @internal
+ */
+export const binary64ToNumber = (data: Uint8Array): number => {
+  return byteData.unpack(data, { bits: 64, fp: true, be: true });
+};
+
+/**
+ * Convert number to 32-bit float binary (big-endian).
+ */
+export const numberToBinary32 = (n: number): Uint8Array => {
+  const data = new Uint8Array(4);
+  byteData.packTo(n, { bits: 32, fp: true, be: true }, data);
+  return data;
+};
+
+/**
+ * Convert 32-bit binary to number.
+ */
+export const binary32ToNumber = (data: Uint8Array): number => {
+  return byteData.unpack(data, { bits: 32, fp: true, be: true });
+};
+
+/**
+ * Convert number to 16-bit float binary (big-endian).
+ */
+export const numberToBinary16 = (n: number): Uint8Array => {
+  const data = new Uint8Array(2);
+  byteData.packTo(n, { bits: 16, fp: true, be: true }, data);
+  return data;
+};
+
+/**
+ * Convert 16-bit binary to number.
+ */
+export const binary16ToNumber = (data: Uint8Array): number => {
+  return byteData.unpack(data, { bits: 16, fp: true, be: true });
+};
+
+/**
+ * Encode f64 value to CBOR data bytes.
+ * Implements numeric reduction and canonical encoding rules.
+ * Matches Rust's f64_cbor_data function.
+ * @internal
+ */
+export const f64CborData = (value: number): Uint8Array => {
+  const n = value;
+
+  // Try to reduce to f32 first
+  const f32Bytes = numberToBinary32(n);
+  const f = binary32ToNumber(f32Bytes);
+  if (f === n) {
+    return f32CborData(f);
+  }
+
+  // Try numeric reduction to negative integer
+  if (n < 0.0) {
+    const i128 = ExactI128.exactFromF64(n);
+    if (i128 !== undefined) {
+      const i = ExactU64.exactFromI128(-1n - i128);
+      if (i !== undefined) {
+        // Encode as a negative integer
+        const num = typeof i === "bigint" ? Number(i) : i;
+        return encodeVarInt(num, MajorType.Negative);
+      }
+    }
+  }
+
+  // Try numeric reduction to unsigned integer
+  const u = ExactU64.exactFromF64(n);
+  if (u !== undefined) {
+    const num = typeof u === "bigint" ? Number(u) : u;
+    return encodeVarInt(num, MajorType.Unsigned);
+  }
+
+  // Canonical NaN
+  if (Number.isNaN(value)) {
+    return CBOR_NAN;
+  }
+
+  // Encode as f64 - create binary manually (always 8 bytes with 0xfb prefix)
+  const buffer = new ArrayBuffer(8);
+  const view = new DataView(buffer);
+  view.setFloat64(0, n, false); // big-endian
+  const bytes = new Uint8Array(buffer);
+  const majorByte = 0xfb; // 0x1b | (MajorType.Simple << 5) = 0x1b | 0xe0 = 0xfb
+  return new Uint8Array([majorByte, ...bytes]);
+};
+
+/**
+ * Validate canonical encoding for f64.
+ * Matches Rust's validate_canonical_f64 function.
+ *
+ * TODO: Check if this is legacy code
+ */
+export const validateCanonicalF64 = (n: number): void => {
+  const f32Bytes = numberToBinary32(n);
+  const f32 = binary32ToNumber(f32Bytes);
+
+  if (n === f32 || n === Math.trunc(n) || Number.isNaN(n)) {
+    throw new CborError({ type: "NonCanonicalNumeric" });
+  }
+};
+
+/**
+ * Encode f32 value to CBOR data bytes.
+ * Implements numeric reduction and canonical encoding rules.
+ * Matches Rust's f32_cbor_data function.
+ * @internal
+ */
+export const f32CborData = (value: number): Uint8Array => {
+  const n = value;
+
+  // Try to reduce to f16
+  const f16Bytes = numberToBinary16(n);
+  const f = binary16ToNumber(f16Bytes);
+  if (f === n) {
+    return f16CborData(f);
+  }
+
+  // Try numeric reduction to negative integer
+  if (n < 0.0) {
+    const u = ExactU64.exactFromF32(-1.0 - n);
+    if (u !== undefined) {
+      const num = typeof u === "bigint" ? Number(u) : u;
+      return encodeVarInt(num, MajorType.Negative);
+    }
+  }
+
+  // Try numeric reduction to unsigned integer
+  const u = ExactU32.exactFromF32(n);
+  if (u !== undefined) {
+    return encodeVarInt(u, MajorType.Unsigned);
+  }
+
+  // Canonical NaN
+  if (Number.isNaN(value)) {
+    return CBOR_NAN;
+  }
+
+  // Encode as f32 - always use 0xfa prefix with 4 bytes
+  const bytes = numberToBinary32(n);
+  return new Uint8Array([0xfa, ...bytes]);
+};
+
+/**
+ * Validate canonical encoding for f32.
+ * Matches Rust's validate_canonical_f32 function.
+ *
+ * TODO: Check if this is legacy code
+ */
+export const validateCanonicalF32 = (n: number): void => {
+  const f16Bytes = numberToBinary16(n);
+  const f16 = binary16ToNumber(f16Bytes);
+
+  if (n === f16 || n === Math.trunc(n) || Number.isNaN(n)) {
+    throw new CborError({ type: "NonCanonicalNumeric" });
+  }
+};
+
+/**
+ * Encode f16 value to CBOR data bytes.
+ * Implements numeric reduction and canonical encoding rules.
+ * Matches Rust's f16_cbor_data function.
+ * @internal
+ */
+export const f16CborData = (value: number): Uint8Array => {
+  const n = value;
+
+  // Try numeric reduction to negative integer
+  if (n < 0.0) {
+    const u = ExactU64.exactFromF64(-1.0 - n);
+    if (u !== undefined) {
+      const num = typeof u === "bigint" ? Number(u) : u;
+      return encodeVarInt(num, MajorType.Negative);
+    }
+  }
+
+  // Try numeric reduction to unsigned integer
+  const u = ExactU16.exactFromF64(n);
+  if (u !== undefined) {
+    return encodeVarInt(u, MajorType.Unsigned);
+  }
+
+  // Canonical NaN
+  if (Number.isNaN(value)) {
+    return CBOR_NAN;
+  }
+
+  // Encode as f16 - always use 0xf9 prefix with 2 bytes
+  const bytes = numberToBinary16(value);
+  return new Uint8Array([0xf9, ...bytes]);
+};
+
+/**
+ * Validate canonical encoding for f16.
+ * Matches Rust's validate_canonical_f16 function.
+ *
+ * TODO: Check if this is legacy code
+ */
+export const validateCanonicalF16 = (value: number): void => {
+  const n = value;
+  const f = n;
+
+  const f16Bytes = numberToBinary16(value);
+  const bits = new DataView(f16Bytes.buffer).getUint16(0, false);
+
+  if (f === Math.trunc(f) || (Number.isNaN(value) && bits !== 0x7e00)) {
+    throw new CborError({ type: "NonCanonicalNumeric" });
+  }
+};
+
+/**
+ * Convert the smallest possible float binary representation to number.
+ * This is the canonical decoder - validates that larger representations
+ * are not reducible to smaller ones.
+ * @internal
+ */
+export const numberToBinary = (n: number): Uint8Array => {
+  if (Number.isNaN(n)) {
+    return new Uint8Array([0x7e, 0x00]);
+  }
+
+  const n32 = numberToBinary32(n);
+  const f32 = binary32ToNumber(n32);
+  if (f32 === n) {
+    const n16 = numberToBinary16(n);
+    const f16 = binary16ToNumber(n16);
+    if (f16 === n) {
+      return n16;
+    }
+    return n32;
+  }
+
+  // Create a 64-bit float binary inline
+  const buffer = new ArrayBuffer(8);
+  const view = new DataView(buffer);
+  view.setFloat64(0, n, false); // big-endian
+  return new Uint8Array(buffer);
+};

package/src/global.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Global type declarations for cross-platform APIs
+ */
+
+declare global {
+  /**
+   * TextEncoder encodes a string into a Uint8Array of UTF-8 bytes.
+   * Available in Node.js 11.0.0+ and all modern browsers.
+   */
+  interface TextEncoder {
+    encode(input: string): Uint8Array;
+  }
+
+  /**
+   * TextDecoder decodes a Uint8Array of UTF-8 bytes into a string.
+   * Available in Node.js 11.0.0+ and all modern browsers.
+   */
+  interface TextDecoder {
+    decode(input: Uint8Array | ArrayBuffer | null | undefined): string;
+  }
+
+  type TextEncoderConstructor = new () => TextEncoder;
+  type TextDecoderConstructor = new (label?: string, options?: TextDecoderOptions) => TextDecoder;
+
+  interface TextDecoderOptions {
+    fatal?: boolean;
+    ignoreBOM?: boolean;
+  }
+
+  const TextEncoder: TextEncoderConstructor;
+  const TextDecoder: TextDecoderConstructor;
+}
+
+export {};

package/src/index.ts

@@ -0,0 +1,180 @@
+/**
+ * BC-DCBOR TypeScript Library
+ *
+ * A TypeScript implementation of Blockchain Commons' Deterministic CBOR (dCBOR).
+ *
+ * @module bc-dcbor
+ */
+
+// Core CBOR types and encoding/decoding
+export {
+  Cbor,
+  type CborInput,
+  type CborNumber,
+  type CborMethods,
+  MajorType,
+  type CborUnsignedType,
+  type CborNegativeType,
+  type CborByteStringType,
+  type CborTextType,
+  type CborArrayType,
+  type CborMapType,
+  type CborTaggedType,
+  type CborSimpleType,
+} from "./cbor";
+
+// Simple value types
+export { type Simple, simpleName, isNaN } from "./simple";
+
+// Encoding/Decoding
+export { cbor, cborData } from "./cbor";
+export { decodeCbor } from "./decode";
+
+// Factory functions (static creators)
+export { toByteString, toByteStringFromHex, toTaggedValue } from "./cbor";
+
+// Map and Set
+export { CborMap, type MapEntry } from "./map";
+export { CborSet } from "./set";
+
+// Tags and Tagged values
+export { type Tag, createTag } from "./tag";
+export {
+  type CborTagged,
+  type CborTaggedEncodable,
+  type CborTaggedDecodable,
+  type CborTaggedCodable,
+  createTaggedCbor,
+  validateTag,
+  extractTaggedContent,
+} from "./cbor-tagged";
+export {
+  TagsStore,
+  type TagsStoreTrait,
+  type CborSummarizer,
+  getGlobalTagsStore,
+} from "./tags-store";
+export * from "./tags";
+export { registerTags, registerTagsIn, tagsForValues } from "./tags";
+
+// Date utilities
+export { CborDate } from "./date";
+
+// Diagnostic formatting
+export { diagnosticOpt, summary, type DiagFormatOpts } from "./diag";
+
+// Hex formatting
+export { hexOpt, hexToBytes, bytesToHex, type HexFormatOpts } from "./dump";
+
+// Walk/Traversal functionality
+export {
+  type EdgeType,
+  type EdgeTypeVariant,
+  type WalkElement,
+  type Visitor,
+  asSingle,
+  asKeyValue,
+  edgeLabel,
+  // Helper functions
+  countElements,
+  collectAtLevel,
+  findFirst,
+  collectAllText,
+  maxDepth,
+} from "./walk";
+
+// Codable interfaces
+export { type CborCodable, type CborEncodable, type CborDecodable } from "./cbor-codable";
+
+// Error types (matches Rust's Error enum)
+export { type Error, type Result, Ok, Err, errorMsg, errorToString, CborError } from "./error";
+
+// Note: conveniences.ts is an internal module (not exported in Rust either)
+// The main convenience functions are exported from cbor.ts above
+
+// Float utilities
+export { hasFractionalPart } from "./float";
+
+// Varint utilities
+export { encodeVarInt, decodeVarInt, decodeVarIntData } from "./varint";
+
+// Type utilities
+export { ByteString } from "./byte-string";
+
+// Convenience utilities - type guards
+export {
+  isUnsigned,
+  isNegative,
+  isInteger,
+  isBytes,
+  isText,
+  isArray,
+  isMap,
+  isTagged,
+  isSimple,
+  isBoolean,
+  isNull,
+  isFloat,
+} from "./conveniences";
+
+// Convenience utilities - safe extraction (returns undefined on type mismatch)
+export {
+  asUnsigned,
+  asNegative,
+  asInteger,
+  asBytes,
+  asText,
+  asArray,
+  asMap,
+  asBoolean,
+  asFloat,
+  asNumber,
+} from "./conveniences";
+
+// Convenience utilities - expectations (throw on type mismatch)
+export {
+  expectUnsigned,
+  expectNegative,
+  expectInteger,
+  expectBytes,
+  expectText,
+  expectArray,
+  expectMap,
+  expectBoolean,
+  expectFloat,
+  expectNumber,
+  // Aliases for envelope compatibility
+  expectText as tryIntoText,
+  expectBoolean as tryIntoBool,
+  expectBytes as tryIntoByteString,
+} from "./conveniences";
+
+// Convenience utilities - array operations
+export { arrayItem, arrayLength, arrayIsEmpty } from "./conveniences";
+
+// Convenience utilities - map operations
+export { mapValue, mapHas, mapKeys, mapValues, mapSize, mapIsEmpty } from "./conveniences";
+
+// Convenience utilities - tagged value operations
+export {
+  tagValue,
+  tagContent,
+  hasTag,
+  getTaggedContent,
+  expectTaggedContent,
+  // Alias for envelope compatibility
+  expectTaggedContent as tryExpectedTaggedValue,
+} from "./conveniences";
+
+// Extract native JavaScript value from CBOR
+export { extractCbor } from "./conveniences";
+
+// Envelope compatibility functions
+export {
+  asTaggedValue,
+  asByteString,
+  asCborArray,
+  type CborArrayWrapper,
+  asCborMap,
+  isNumber,
+} from "./conveniences";