ox 0.9.13 → 0.9.15

package/core/Cbor.ts

@@ -0,0 +1,912 @@
+import * as Bytes from './Bytes.js'
+import * as Errors from './Errors.js'
+import * as Hex from './Hex.js'
+import * as Cursor from './internal/cursor.js'
+
+/**
+ * Encodes a value into CBOR (Concise Binary Object Representation) format.
+ *
+ * @example
+ * ```ts twoslash
+ * import { Cbor } from 'ox'
+ *
+ * Cbor.encode([1, 2, 3])
+ * // @log: '0x83010203'
+ *
+ * Cbor.encode({ foo: 'bar', baz: [1, 2, 3] })
+ * // @log: '0xa263666f6f636261726362617a83010203'
+ *
+ * Cbor.encode('hello', { as: 'Bytes' })
+ * // @log: Uint8Array(6) [ 101, 104, 101, 108, 108, 111 ]
+ * ```
+ *
+ * @param data - The value to encode.
+ * @param options - Encoding options.
+ * @returns The CBOR-encoded value.
+ */
+export function encode<as extends 'Hex' | 'Bytes' = 'Hex'>(
+  data: unknown,
+  options: encode.Options<as> = {},
+): encode.ReturnType<as> {
+  const { as = 'Hex' } = options
+
+  const encodable = getEncodable(data)
+  const cursor = Cursor.create(new Uint8Array(encodable.length))
+  encodable.encode(cursor)
+
+  if (as === 'Hex') return Hex.fromBytes(cursor.bytes) as encode.ReturnType<as>
+  return cursor.bytes as encode.ReturnType<as>
+}
+
+export declare namespace encode {
+  type Options<as extends 'Hex' | 'Bytes' = 'Hex' | 'Bytes'> = {
+    /** The format to return the encoded value in. */
+    as?: as | 'Hex' | 'Bytes' | undefined
+  }
+
+  type ReturnType<as extends 'Hex' | 'Bytes' = 'Hex' | 'Bytes'> =
+    | (as extends 'Hex' ? Hex.Hex : never)
+    | (as extends 'Bytes' ? Bytes.Bytes : never)
+
+  type ErrorType =
+    | Cursor.create.ErrorType
+    | Hex.fromBytes.ErrorType
+    | UnsupportedBigIntError
+    | UnexpectedTokenError
+    | NumberTooLargeError
+    | StringTooLargeError
+    | ByteStringTooLargeError
+    | ArrayTooLargeError
+    | ObjectTooLargeError
+    | Errors.GlobalErrorType
+}
+
+/**
+ * Decodes CBOR (Concise Binary Object Representation) data into a JavaScript value.
+ *
+ * @example
+ * ```ts twoslash
+ * import { Cbor } from 'ox'
+ *
+ * Cbor.decode('0x83010203')
+ * // @log: [1, 2, 3]
+ *
+ * Cbor.decode('0xa263666f6f636261726362617a83010203')
+ * // @log: { foo: 'bar', baz: [1, 2, 3] }
+ *
+ * Cbor.decode(new Uint8Array([101, 104, 101, 108, 108, 111]))
+ * // @log: 'hello'
+ * ```
+ *
+ * @param data - The CBOR-encoded data to decode.
+ * @param options - Decoding options.
+ * @returns The decoded value.
+ */
+export function decode<type = unknown>(data: Hex.Hex | Bytes.Bytes): type {
+  const bytes = (() => {
+    if (typeof data === 'string') {
+      if (data.length > 3 && data.length % 2 !== 0)
+        throw new Hex.InvalidLengthError(data)
+      return Bytes.fromHex(data)
+    }
+    return data
+  })()
+
+  const cursor = Cursor.create(bytes)
+
+  return decodeCursor(cursor) as type
+}
+
+export declare namespace decode {
+  type ErrorType =
+    | Bytes.fromHex.ErrorType
+    | Cursor.create.ErrorType
+    | Hex.InvalidLengthError
+    | decodeCursor.ErrorType
+    | Errors.GlobalErrorType
+}
+
+export class InvalidMajorTypeError extends Errors.BaseError {
+  override readonly name = 'Cbor.InvalidMajorTypeError'
+
+  constructor({ majorType }: { majorType: number }) {
+    super(`Invalid CBOR major type: ${majorType}`)
+  }
+}
+
+export class InvalidAdditionalInfoError extends Errors.BaseError {
+  override readonly name = 'Cbor.InvalidAdditionalInfoError'
+
+  constructor({ additionalInfo }: { additionalInfo: number }) {
+    super(`Invalid CBOR additional info: ${additionalInfo}`)
+  }
+}
+
+export class Unsupported64BitIntegerError extends Errors.BaseError {
+  override readonly name = 'Cbor.Unsupported64BitIntegerError'
+
+  constructor() {
+    super('64-bit integers are not supported in CBOR decoding.')
+  }
+}
+
+export class UnsupportedTagError extends Errors.BaseError {
+  override readonly name = 'Cbor.UnsupportedTagError'
+
+  constructor({ tag }: { tag: number }) {
+    super(`CBOR tagged data (tag ${tag}) is not yet supported.`)
+  }
+}
+
+export class InvalidIndefiniteLengthChunkError extends Errors.BaseError {
+  override readonly name = 'Cbor.InvalidIndefiniteLengthChunkError'
+
+  constructor({ type }: { type: string }) {
+    super(`Invalid chunk type in indefinite-length ${type}`)
+  }
+}
+
+export class InvalidSimpleValueError extends Errors.BaseError {
+  override readonly name = 'Cbor.InvalidSimpleValueError'
+
+  constructor({ value }: { value: number }) {
+    super(`Invalid CBOR simple value: ${value}`)
+  }
+}
+
+export class UnsupportedBigIntError extends Errors.BaseError {
+  override readonly name = 'Cbor.UnsupportedBigIntError'
+
+  constructor() {
+    super('BigInt values are not supported in CBOR encoding.')
+  }
+}
+
+export class UnexpectedTokenError extends Errors.BaseError {
+  override readonly name = 'Cbor.UnexpectedTokenError'
+
+  constructor({ token }: { token: string }) {
+    super(`Unexpected token: ${token}`)
+  }
+}
+
+export class NumberTooLargeError extends Errors.BaseError {
+  override readonly name = 'Cbor.NumberTooLargeError'
+
+  constructor({ number }: { number: string }) {
+    super(
+      `Number exceeds maximum safe integer (${Number.MAX_SAFE_INTEGER}): ${number}`,
+    )
+  }
+}
+
+export class StringTooLargeError extends Errors.BaseError {
+  override readonly name = 'Cbor.StringTooLargeError'
+
+  constructor({ size }: { size: number }) {
+    super(`String length exceeds maximum (4294967295): ${size}`)
+  }
+}
+
+export class ArrayTooLargeError extends Errors.BaseError {
+  override readonly name = 'Cbor.ArrayTooLargeError'
+
+  constructor({ size }: { size: number }) {
+    super(`Array length exceeds maximum (4294967295): ${size}`)
+  }
+}
+
+export class ObjectTooLargeError extends Errors.BaseError {
+  override readonly name = 'Cbor.ObjectTooLargeError'
+
+  constructor({ size }: { size: number }) {
+    super(`Object size exceeds maximum (4294967295): ${size}`)
+  }
+}
+
+export class ByteStringTooLargeError extends Errors.BaseError {
+  override readonly name = 'Cbor.ByteStringTooLargeError'
+
+  constructor({ size }: { size: number }) {
+    super(`Byte string length exceeds maximum (4294967295): ${size}`)
+  }
+}
+
+/////////////////////////////////////////////////////////////////////////////////
+// Internal
+/////////////////////////////////////////////////////////////////////////////////
+
+type Encodable = {
+  length: number
+  encode(cursor: Cursor.Cursor): void
+}
+
+/** @internal */
+// biome-ignore lint/correctness/noUnusedVariables: _
+function getEncodable(value: unknown): Encodable {
+  if (typeof value === 'undefined')
+    return { length: 1, encode: (cursor) => cursor.pushUint8(0xf7) }
+
+  if (value === null)
+    return { length: 1, encode: (cursor) => cursor.pushUint8(0xf6) }
+
+  if (typeof value === 'boolean')
+    return {
+      length: 1,
+      encode: (cursor) => cursor.pushUint8(value ? 0xf5 : 0xf4),
+    }
+
+  if (typeof value === 'number') return getEncodable.number(value as number)
+
+  if (typeof value === 'bigint') throw new UnsupportedBigIntError()
+
+  if (typeof value === 'string') return getEncodable.string(value as string)
+
+  if (Array.isArray(value)) return getEncodable.array(value)
+
+  if (value instanceof Uint8Array) return getEncodable.byteString(value)
+
+  if (value instanceof ArrayBuffer)
+    return getEncodable.byteString(new Uint8Array(value))
+
+  if (ArrayBuffer.isView(value))
+    return getEncodable.byteString(
+      new Uint8Array(value.buffer, value.byteOffset, value.byteLength),
+    )
+
+  if (typeof value === 'object')
+    return getEncodable.object(value as Record<string, unknown>)
+
+  throw new UnexpectedTokenError({ token: String(value) })
+}
+
+/** @internal */
+namespace getEncodable {
+  /** @internal */
+  export function number(value: number): Encodable {
+    // Handle non-safe integers (floats, NaN, Infinity)
+    if (!Number.isSafeInteger(value)) {
+      // Use Float32 if the value can be represented without precision loss
+      // This creates smaller encodings when possible (5 bytes vs 9 bytes)
+      const float32 = Math.fround(value)
+      if (Number.isNaN(value) || value === float32)
+        return {
+          length: 5, // 1 byte prefix + 4 bytes float32
+          encode(cursor) {
+            cursor.pushUint8(0xfa)
+            cursor.dataView.setFloat32(cursor.position, value, false)
+            cursor.position += 4
+          },
+        }
+      return {
+        length: 9, // 1 byte prefix + 8 bytes float64
+        encode(cursor) {
+          cursor.pushUint8(0xfb)
+          cursor.dataView.setFloat64(cursor.position, value, false)
+          cursor.position += 8
+        },
+      }
+    }
+
+    // Handle positive integers
+    if (value >= 0) {
+      if (value <= 0x17)
+        return { length: 1, encode: (cursor) => cursor.pushUint8(value) }
+      if (value <= 0xff)
+        return {
+          length: 2, // 1 byte prefix + 1 byte uint8
+          encode: (cursor) => {
+            cursor.pushUint8(0x18)
+            cursor.pushUint8(value)
+          },
+        }
+      if (value <= 0xffff)
+        return {
+          length: 3, // 1 byte prefix + 2 bytes uint16
+          encode: (cursor) => {
+            cursor.pushUint8(0x19)
+            cursor.pushUint16(value)
+          },
+        }
+      if (value <= 0xffffffff)
+        return {
+          length: 5, // 1 byte prefix + 4 bytes uint32
+          encode: (cursor) => {
+            cursor.pushUint8(0x1a)
+            cursor.pushUint32(value)
+          },
+        }
+      throw new NumberTooLargeError({ number: value.toString(10) })
+    }
+
+    // Handle negative integers
+    // CBOR encodes -n as (n-1)
+    const positiveNumber = -1 - value
+
+    if (value >= -24)
+      return {
+        length: 1,
+        encode: (cursor) => cursor.pushUint8(0x20 + positiveNumber),
+      }
+    if (positiveNumber <= 0xff)
+      return {
+        length: 2, // 1 byte prefix + 1 byte uint8
+        encode: (cursor) => {
+          cursor.pushUint8(0x38)
+          cursor.pushUint8(positiveNumber)
+        },
+      }
+    if (positiveNumber <= 0xffff)
+      return {
+        length: 3, // 1 byte prefix + 2 bytes uint16
+        encode: (cursor) => {
+          cursor.pushUint8(0x39)
+          cursor.pushUint16(positiveNumber)
+        },
+      }
+    if (positiveNumber <= 0xffffffff)
+      return {
+        length: 5, // 1 byte prefix + 4 bytes uint32
+        encode: (cursor) => {
+          cursor.pushUint8(0x3a)
+          cursor.pushUint32(positiveNumber)
+        },
+      }
+    throw new NumberTooLargeError({ number: value.toString(10) })
+  }
+
+  /** @internal */
+  export function string(value: string): Encodable {
+    const encoded = Bytes.fromString(value)
+    const size = encoded.length
+
+    if (size <= 0x17)
+      return {
+        length: 1 + size, // 1 byte prefix + size bytes
+        encode(cursor) {
+          cursor.pushUint8(0x60 + size)
+          if (size > 0) cursor.pushBytes(encoded)
+        },
+      }
+    if (size <= 0xff)
+      return {
+        length: 2 + size, // 1 byte prefix + 1 byte uint8 + size bytes
+        encode(cursor) {
+          cursor.pushUint8(0x78)
+          cursor.pushUint8(size)
+          cursor.pushBytes(encoded)
+        },
+      }
+
+    if (size <= 0xffff)
+      return {
+        length: 3 + size, // 1 byte prefix + 2 bytes uint16 + size bytes
+        encode(cursor) {
+          cursor.pushUint8(0x79)
+          cursor.pushUint16(size)
+          cursor.pushBytes(encoded)
+        },
+      }
+
+    if (size <= 0xffffffff)
+      return {
+        length: 5 + size, // 1 byte prefix + 4 bytes uint32 + size bytes
+        encode(cursor) {
+          cursor.pushUint8(0x7a)
+          cursor.pushUint32(size)
+          cursor.pushBytes(encoded)
+        },
+      }
+
+    throw new StringTooLargeError({ size })
+  }
+
+  /** @internal */
+  export function array(value: unknown[]): Encodable {
+    const items = value.map((item) => getEncodable(item))
+    const bodyLength = items.reduce((acc, item) => acc + item.length, 0)
+    const size = value.length
+
+    if (size <= 0x17)
+      return {
+        length: 1 + bodyLength, // 1 byte prefix + body length
+        encode(cursor) {
+          cursor.pushUint8(0x80 + size)
+          for (const item of items) item.encode(cursor)
+        },
+      }
+    if (size <= 0xff)
+      return {
+        length: 2 + bodyLength, // 1 byte prefix + 1 byte uint8 + body length
+        encode(cursor) {
+          cursor.pushUint8(0x98)
+          cursor.pushUint8(size)
+          for (const item of items) item.encode(cursor)
+        },
+      }
+    if (size <= 0xffff)
+      return {
+        length: 3 + bodyLength, // 1 byte prefix + 2 bytes uint16 + body length
+        encode(cursor) {
+          cursor.pushUint8(0x99)
+          cursor.pushUint16(size)
+          for (const item of items) item.encode(cursor)
+        },
+      }
+    if (size <= 0xffffffff)
+      return {
+        length: 5 + bodyLength, // 1 byte prefix + 4 bytes uint32 + body length
+        encode(cursor) {
+          cursor.pushUint8(0x9a)
+          cursor.pushUint32(size)
+          for (const item of items) item.encode(cursor)
+        },
+      }
+    throw new ArrayTooLargeError({ size })
+  }
+
+  /** @internal */
+  export function byteString(value: Uint8Array): Encodable {
+    const size = value.byteLength
+
+    if (size <= 0x17)
+      return {
+        length: 1 + size, // 1 byte prefix + size bytes
+        encode(cursor) {
+          cursor.pushUint8(0x40 + size)
+          cursor.pushBytes(value)
+        },
+      }
+    if (size <= 0xff)
+      return {
+        length: 2 + size, // 1 byte prefix + 1 byte uint8 + size bytes
+        encode(cursor) {
+          cursor.pushUint8(0x58)
+          cursor.pushUint8(size)
+          cursor.pushBytes(value)
+        },
+      }
+    if (size <= 0xffff)
+      return {
+        length: 3 + size, // 1 byte prefix + 2 bytes uint16 + size bytes
+        encode(cursor) {
+          cursor.pushUint8(0x59)
+          cursor.pushUint16(size)
+          cursor.pushBytes(value)
+        },
+      }
+    if (size <= 0xffffffff)
+      return {
+        length: 5 + size, // 1 byte prefix + 4 bytes uint32 + size bytes
+        encode(cursor) {
+          cursor.pushUint8(0x5a)
+          cursor.pushUint32(size)
+          cursor.pushBytes(value)
+        },
+      }
+    throw new ByteStringTooLargeError({ size })
+  }
+
+  /** @internal */
+  export function object(value: Record<string, unknown>): Encodable {
+    const keys = Object.keys(value)
+    const entries = keys.map((key) => ({
+      key: getEncodable(key),
+      value: getEncodable(value[key]),
+    }))
+    const bodyLength = entries.reduce(
+      (acc, entry) => acc + entry.key.length + entry.value.length,
+      0,
+    )
+    const size = keys.length
+
+    if (size <= 0x17)
+      return {
+        length: 1 + bodyLength, // 1 byte prefix + body length
+        encode(cursor) {
+          cursor.pushUint8(0xa0 + size)
+          for (const entry of entries) {
+            entry.key.encode(cursor)
+            entry.value.encode(cursor)
+          }
+        },
+      }
+    if (size <= 0xff)
+      return {
+        length: 2 + bodyLength, // 1 byte prefix + 1 byte uint8 + body length
+        encode(cursor) {
+          cursor.pushUint8(0xb8)
+          cursor.pushUint8(size)
+          for (const entry of entries) {
+            entry.key.encode(cursor)
+            entry.value.encode(cursor)
+          }
+        },
+      }
+    if (size <= 0xffff)
+      return {
+        length: 3 + bodyLength, // 1 byte prefix + 2 bytes uint16 + body length
+        encode(cursor) {
+          cursor.pushUint8(0xb9)
+          cursor.pushUint16(size)
+          for (const entry of entries) {
+            entry.key.encode(cursor)
+            entry.value.encode(cursor)
+          }
+        },
+      }
+    if (size <= 0xffffffff)
+      return {
+        length: 5 + bodyLength, // 1 byte prefix + 4 bytes uint32 + body length
+        encode(cursor) {
+          cursor.pushUint8(0xba)
+          cursor.pushUint32(size)
+          for (const entry of entries) {
+            entry.key.encode(cursor)
+            entry.value.encode(cursor)
+          }
+        },
+      }
+    throw new ObjectTooLargeError({ size })
+  }
+}
+
+/** @internal */
+// biome-ignore lint/correctness/noUnusedVariables: _
+function decodeCursor(cursor: Cursor.Cursor): unknown {
+  const initialByte = cursor.readUint8()
+  const majorType = initialByte >> 5
+  const additionalInfo = initialByte & 0b00011111
+
+  switch (majorType) {
+    // Major type 0: Unsigned integer
+    case 0:
+      return decodeCursor.readUnsignedInteger(cursor, additionalInfo)
+
+    // Major type 1: Negative integer
+    case 1:
+      return decodeCursor.readNegativeInteger(cursor, additionalInfo)
+
+    // Major type 2: Byte string
+    case 2:
+      return decodeCursor.readByteString(cursor, additionalInfo)
+
+    // Major type 3: Text string
+    case 3:
+      return decodeCursor.readTextString(cursor, additionalInfo)
+
+    // Major type 4: Array
+    case 4:
+      return decodeCursor.readArray(cursor, additionalInfo)
+
+    // Major type 5: Map
+    case 5:
+      return decodeCursor.readMap(cursor, additionalInfo)
+
+    // Major type 6: Tagged data (not yet supported)
+    case 6:
+      throw new UnsupportedTagError({ tag: additionalInfo })
+
+    // Major type 7: Simple values and floats
+    case 7:
+      return decodeCursor.readSimpleOrFloat(cursor, additionalInfo)
+
+    default:
+      throw new InvalidMajorTypeError({ majorType })
+  }
+}
+
+/** @internal */
+namespace decodeCursor {
+  export type ErrorType =
+    | readUnsignedInteger.ErrorType
+    | readNegativeInteger.ErrorType
+    | readByteString.ErrorType
+    | readTextString.ErrorType
+    | readArray.ErrorType
+    | readMap.ErrorType
+    | readSimpleOrFloat.ErrorType
+    | UnsupportedTagError
+    | InvalidMajorTypeError
+    | Errors.GlobalErrorType
+
+  /** @internal */
+  // biome-ignore lint/correctness/noUnusedVariables: _
+  function readLength(cursor: Cursor.Cursor, additionalInfo: number): number {
+    if (additionalInfo < 24) return additionalInfo
+    if (additionalInfo === 24) return cursor.readUint8()
+    if (additionalInfo === 25) return cursor.readUint16()
+    if (additionalInfo === 26) return cursor.readUint32()
+    if (additionalInfo === 27) throw new Unsupported64BitIntegerError()
+    throw new InvalidAdditionalInfoError({ additionalInfo })
+  }
+
+  /** @internal */
+  export declare namespace readLength {
+    type ErrorType =
+      | Unsupported64BitIntegerError
+      | InvalidAdditionalInfoError
+      | Errors.GlobalErrorType
+  }
+
+  /** @internal */
+  export function readUnsignedInteger(
+    cursor: Cursor.Cursor,
+    additionalInfo: number,
+  ): number {
+    return readLength(cursor, additionalInfo)
+  }
+
+  /** @internal */
+  export declare namespace readUnsignedInteger {
+    type ErrorType = readLength.ErrorType | Errors.GlobalErrorType
+  }
+
+  /** @internal */
+  export function readNegativeInteger(
+    cursor: Cursor.Cursor,
+    additionalInfo: number,
+  ): number {
+    const value = readLength(cursor, additionalInfo)
+    return -1 - value
+  }
+
+  /** @internal */
+  export declare namespace readNegativeInteger {
+    type ErrorType = readLength.ErrorType | Errors.GlobalErrorType
+  }
+
+  /** @internal */
+  export function readByteString(
+    cursor: Cursor.Cursor,
+    additionalInfo: number,
+  ): Bytes.Bytes {
+    // Indefinite-length byte string
+    if (additionalInfo === 31) {
+      const chunks: Bytes.Bytes[] = []
+      let totalLength = 0
+
+      while (true) {
+        const byte = cursor.inspectUint8()
+        if (byte === 0xff) {
+          cursor.readUint8() // consume the break byte
+          break
+        }
+        const chunk = decodeCursor(cursor) as Bytes.Bytes
+        if (!(chunk instanceof Uint8Array))
+          throw new InvalidIndefiniteLengthChunkError({ type: 'byte string' })
+        chunks.push(chunk)
+        totalLength += chunk.length
+      }
+
+      // Concatenate chunks
+      const result = new Uint8Array(totalLength)
+      let offset = 0
+      for (const chunk of chunks) {
+        result.set(chunk, offset)
+        offset += chunk.length
+      }
+      return result
+    }
+
+    const length = readLength(cursor, additionalInfo)
+    return cursor.readBytes(length)
+  }
+
+  /** @internal */
+  export declare namespace readByteString {
+    type ErrorType =
+      | readLength.ErrorType
+      | InvalidIndefiniteLengthChunkError
+      | Errors.GlobalErrorType
+  }
+
+  /** @internal */
+  export function readTextString(
+    cursor: Cursor.Cursor,
+    additionalInfo: number,
+  ): string {
+    // Indefinite-length text string
+    if (additionalInfo === 31) {
+      const chunks: string[] = []
+
+      while (true) {
+        const byte = cursor.inspectUint8()
+        if (byte === 0xff) {
+          cursor.readUint8() // consume the break byte
+          break
+        }
+        const chunk = decodeCursor(cursor)
+        if (typeof chunk !== 'string')
+          throw new InvalidIndefiniteLengthChunkError({ type: 'text string' })
+        chunks.push(chunk)
+      }
+
+      return chunks.join('')
+    }
+
+    const length = readLength(cursor, additionalInfo)
+    const bytes = cursor.readBytes(length)
+    return Bytes.toString(bytes)
+  }
+
+  /** @internal */
+  export declare namespace readTextString {
+    type ErrorType =
+      | readLength.ErrorType
+      | Bytes.toString.ErrorType
+      | InvalidIndefiniteLengthChunkError
+      | Errors.GlobalErrorType
+  }
+
+  /** @internal */
+  export function readArray(
+    cursor: Cursor.Cursor,
+    additionalInfo: number,
+  ): unknown[] {
+    // Indefinite-length array
+    if (additionalInfo === 31) {
+      const result: unknown[] = []
+
+      while (true) {
+        const byte = cursor.inspectUint8()
+        if (byte === 0xff) {
+          cursor.readUint8() // consume the break byte
+          break
+        }
+        result.push(decodeCursor(cursor))
+      }
+
+      return result
+    }
+
+    const length = readLength(cursor, additionalInfo)
+    const result: unknown[] = []
+
+    for (let i = 0; i < length; i++) {
+      result.push(decodeCursor(cursor))
+    }
+
+    return result
+  }
+
+  /** @internal */
+  export declare namespace readArray {
+    type ErrorType = readLength.ErrorType | Errors.GlobalErrorType
+  }
+
+  /** @internal */
+  export function readMap(
+    cursor: Cursor.Cursor,
+    additionalInfo: number,
+  ): Record<string, unknown> {
+    // Indefinite-length map
+    if (additionalInfo === 31) {
+      const result: Record<string, unknown> = {}
+
+      while (true) {
+        const byte = cursor.inspectUint8()
+        if (byte === 0xff) {
+          cursor.readUint8() // consume the break byte
+          break
+        }
+        const key = decodeCursor(cursor)
+        // Support both string and number keys (for COSE_Key with integer keys)
+        const keyStr =
+          typeof key === 'string'
+            ? key
+            : typeof key === 'number'
+              ? String(key)
+              : String(key)
+        const value = decodeCursor(cursor)
+        result[keyStr] = value
+      }
+
+      return result
+    }
+
+    const length = readLength(cursor, additionalInfo)
+    const result: Record<string, unknown> = {}
+
+    for (let i = 0; i < length; i++) {
+      const key = decodeCursor(cursor)
+      // Support both string and number keys (for COSE_Key with integer keys)
+      const keyStr =
+        typeof key === 'string'
+          ? key
+          : typeof key === 'number'
+            ? String(key)
+            : String(key)
+      const value = decodeCursor(cursor)
+      result[keyStr] = value
+    }
+
+    return result
+  }
+
+  /** @internal */
+  export declare namespace readMap {
+    type ErrorType = readLength.ErrorType | Errors.GlobalErrorType
+  }
+
+  /** @internal */
+  export function readSimpleOrFloat(
+    cursor: Cursor.Cursor,
+    additionalInfo: number,
+  ): unknown {
+    // Simple values
+    if (additionalInfo === 20) return false
+    if (additionalInfo === 21) return true
+    if (additionalInfo === 22) return null
+    if (additionalInfo === 23) return undefined
+
+    // Float16 (half-precision)
+    if (additionalInfo === 25) {
+      const bits = cursor.readUint16()
+      return getFloat16(bits)
+    }
+
+    // Float32
+    if (additionalInfo === 26) {
+      const value = cursor.dataView.getFloat32(cursor.position, false)
+      cursor.position += 4
+      return value
+    }
+
+    // Float64
+    if (additionalInfo === 27) {
+      const value = cursor.dataView.getFloat64(cursor.position, false)
+      cursor.position += 8
+      return value
+    }
+
+    // Simple value (additional byte)
+    if (additionalInfo === 24) {
+      const simpleValue = cursor.readUint8()
+      // Simple values 0-19 are assigned, 20-23 are in the initial byte
+      // 24-31 are reserved, 32-255 are unassigned
+      if (simpleValue < 32)
+        throw new InvalidSimpleValueError({ value: simpleValue })
+      // For now, treat unassigned simple values as undefined
+      return undefined
+    }
+
+    throw new InvalidAdditionalInfoError({ additionalInfo })
+  }
+
+  /** @internal */
+  export declare namespace readSimpleOrFloat {
+    type ErrorType =
+      | InvalidSimpleValueError
+      | InvalidAdditionalInfoError
+      | Errors.GlobalErrorType
+  }
+
+  /** @internal */
+  function getFloat16(bits: number): number {
+    // IEEE 754 half-precision (16-bit) float decoding
+    // Format: 1 sign bit, 5 exponent bits, 10 fraction bits
+    const sign = (bits >> 15) & 0x1
+    const exponent = (bits >> 10) & 0x1f
+    const fraction = bits & 0x3ff
+
+    // Handle special cases
+    if (exponent === 0) {
+      // Subnormal numbers or zero
+      if (fraction === 0) return sign ? -0 : 0
+      // Subnormal: (-1)^sign × 2^(-14) × (0 + fraction/1024)
+      const value = 2 ** -14 * (fraction / 1024)
+      return sign ? -value : value
+    }
+
+    if (exponent === 0x1f) {
+      // Infinity or NaN
+      if (fraction === 0) return sign ? -Infinity : Infinity
+      return NaN
+    }
+
+    // Normal numbers: (-1)^sign × 2^(exponent-15) × (1 + fraction/1024)
+    const value = 2 ** (exponent - 15) * (1 + fraction / 1024)
+    return sign ? -value : value
+  }
+}