@marcuspuchalla/nachos 0.1.3 → 0.1.4

package/src/index.ts

@@ -96,9 +96,14 @@ import type { ParseResult, ParseResultWithMap, ParseOptions } from './parser/typ
 import type { EncodeResult, EncodeOptions, EncodableValue } from './encoder/types'
 
 /**
- * Decode CBOR hex string to JavaScript value
+ * Decode CBOR data to JavaScript value
  *
- * @param hexString - CBOR data as hex string (e.g., "1864" for integer 100)
+ * Accepts either a hex string or a Uint8Array of raw CBOR bytes.
+ * When passing a Uint8Array, the bytes are used directly without
+ * hex conversion, which is more efficient for binary sources
+ * (WebSocket, fetch, file I/O, etc.).
+ *
+ * @param input - CBOR data as hex string (e.g., "1864") or Uint8Array
  * @param options - Optional parser configuration
  * @returns Decoded value and number of bytes consumed
  *
@@ -106,9 +111,12 @@ import type { EncodeResult, EncodeOptions, EncodableValue } from './encoder/type
  *
  * @example
  * ```typescript
- * // Decode integer
+ * // Decode from hex string
  * decode('1864')  // { value: 100, bytesRead: 2 }
  *
+ * // Decode from Uint8Array (zero-copy, no hex conversion)
+ * decode(new Uint8Array([0x18, 0x64]))  // { value: 100, bytesRead: 2 }
+ *
  * // Decode string
  * decode('6449455446')  // { value: "IETF", bytesRead: 5 }
  *
@@ -124,18 +132,20 @@ import type { EncodeResult, EncodeOptions, EncodableValue } from './encoder/type
  *
  * @see {@link https://datatracker.ietf.org/doc/html/rfc8949 | RFC 8949}
  */
-export function decode(hexString: string, options?: ParseOptions): ParseResult {
+export function decode(input: string | Uint8Array, options?: ParseOptions): ParseResult {
   const { parse } = useCborParser()
-  return parse(hexString, options)
+  return parse(input, options)
 }
 
 /**
- * Decode CBOR hex string with source map generation
+ * Decode CBOR data with source map generation
  *
  * Source maps provide bidirectional linking between hex bytes and decoded values,
  * enabling interactive debugging visualizations.
  *
- * @param hexString - CBOR data as hex string
+ * Accepts either a hex string or a Uint8Array of raw CBOR bytes.
+ *
+ * @param input - CBOR data as hex string or Uint8Array
  * @param options - Optional parser configuration
  * @returns Decoded value, byte count, and source map
  *
@@ -148,14 +158,13 @@ export function decode(hexString: string, options?: ParseOptions): ParseResult {
  * //   { path: '.value', start: 2, end: 3, majorType: 4, type: 'Array', parent: '' }
  * // ]
  *
- * // Use source map for hex-to-JSON linking
- * const entry = sourceMap.find(e => e.path === '.value')
- * console.log(`Value is at bytes ${entry.start}-${entry.end}`)
+ * // From Uint8Array
+ * const { value, sourceMap } = decodeWithSourceMap(new Uint8Array([0xd8, 0x79, 0x80]))
  * ```
  */
-export function decodeWithSourceMap(hexString: string, options?: ParseOptions): ParseResultWithMap {
+export function decodeWithSourceMap(input: string | Uint8Array, options?: ParseOptions): ParseResultWithMap {
   const { parseWithSourceMap } = useCborParser()
-  return parseWithSourceMap(hexString, options)
+  return parseWithSourceMap(input, options)
 }
 
 /**
@@ -287,23 +296,23 @@ export class CborDecoder {
   }
 
   /**
-   * Decode CBOR hex string
+   * Decode CBOR data
    *
-   * @param hexString - CBOR data as hex string
+   * @param input - CBOR data as hex string or Uint8Array
    * @returns Decoded value and byte count
    */
-  decode(hexString: string): ParseResult {
-    return decode(hexString, this.options)
+  decode(input: string | Uint8Array): ParseResult {
+    return decode(input, this.options)
   }
 
   /**
-   * Decode CBOR hex string with source map
+   * Decode CBOR data with source map
    *
-   * @param hexString - CBOR data as hex string
+   * @param input - CBOR data as hex string or Uint8Array
    * @returns Decoded value, byte count, and source map
    */
-  decodeWithSourceMap(hexString: string): ParseResultWithMap {
-    return decodeWithSourceMap(hexString, this.options)
+  decodeWithSourceMap(input: string | Uint8Array): ParseResultWithMap {
+    return decodeWithSourceMap(input, this.options)
   }
 }
 

package/src/parser/__tests__/buffer-native-parsing.test.ts

@@ -0,0 +1,338 @@
+/**
+ * Tests for buffer-native parsing optimization (Task 2-A)
+ * Validates that buffer-based parsers produce identical results to hex-string parsers
+ * and that O(N^2) hex conversion is eliminated.
+ */
+
+import { describe, it, expect } from 'vitest'
+import { useCborInteger } from '../composables/useCborInteger'
+import { useCborFloat } from '../composables/useCborFloat'
+import { useCborTag } from '../composables/useCborTag'
+import { useCborCollection } from '../composables/useCborCollection'
+import { hexToBytes } from '../utils'
+
+describe('Buffer-native parsing - parseIntegerFromBuffer', () => {
+  const { parseInteger, parseIntegerFromBuffer } = useCborInteger()
+
+  it('should export parseIntegerFromBuffer from useCborInteger', () => {
+    expect(typeof parseIntegerFromBuffer).toBe('function')
+  })
+
+  it('should parse unsigned integer 0 from buffer', () => {
+    const buffer = hexToBytes('00')
+    const result = parseIntegerFromBuffer(buffer, 0)
+    expect(result.value).toBe(0)
+    expect(result.bytesRead).toBe(1)
+  })
+
+  it('should parse unsigned integer 23 from buffer', () => {
+    const buffer = hexToBytes('17')
+    const result = parseIntegerFromBuffer(buffer, 0)
+    expect(result.value).toBe(23)
+    expect(result.bytesRead).toBe(1)
+  })
+
+  it('should parse unsigned integer 24 from buffer (1-byte follows)', () => {
+    const buffer = hexToBytes('1818')
+    const result = parseIntegerFromBuffer(buffer, 0)
+    expect(result.value).toBe(24)
+    expect(result.bytesRead).toBe(2)
+  })
+
+  it('should parse unsigned integer 100 from buffer (1-byte follows)', () => {
+    const buffer = hexToBytes('1864')
+    const result = parseIntegerFromBuffer(buffer, 0)
+    expect(result.value).toBe(100)
+    expect(result.bytesRead).toBe(2)
+  })
+
+  it('should parse unsigned integer 1000 from buffer (2-byte follows)', () => {
+    const buffer = hexToBytes('1903e8')
+    const result = parseIntegerFromBuffer(buffer, 0)
+    expect(result.value).toBe(1000)
+    expect(result.bytesRead).toBe(3)
+  })
+
+  it('should parse unsigned integer 1000000 from buffer (4-byte follows)', () => {
+    const buffer = hexToBytes('1a000f4240')
+    const result = parseIntegerFromBuffer(buffer, 0)
+    expect(result.value).toBe(1000000)
+    expect(result.bytesRead).toBe(5)
+  })
+
+  it('should parse large unsigned integer from buffer (8-byte follows)', () => {
+    const buffer = hexToBytes('1b000000e8d4a51000')
+    const result = parseIntegerFromBuffer(buffer, 0)
+    expect(result.value).toBe(1000000000000)
+    expect(result.bytesRead).toBe(9)
+  })
+
+  it('should parse negative integer -1 from buffer', () => {
+    const buffer = hexToBytes('20')
+    const result = parseIntegerFromBuffer(buffer, 0)
+    expect(result.value).toBe(-1)
+    expect(result.bytesRead).toBe(1)
+  })
+
+  it('should parse negative integer -100 from buffer', () => {
+    const buffer = hexToBytes('3863')
+    const result = parseIntegerFromBuffer(buffer, 0)
+    expect(result.value).toBe(-100)
+    expect(result.bytesRead).toBe(2)
+  })
+
+  it('should parse BigInt unsigned from buffer', () => {
+    // 18446744073709551615 (max uint64)
+    const buffer = hexToBytes('1bffffffffffffffff')
+    const result = parseIntegerFromBuffer(buffer, 0)
+    expect(result.value).toBe(18446744073709551615n)
+    expect(result.bytesRead).toBe(9)
+  })
+
+  it('should parse BigInt negative from buffer', () => {
+    // -18446744073709551616
+    const buffer = hexToBytes('3bffffffffffffffff')
+    const result = parseIntegerFromBuffer(buffer, 0)
+    expect(result.value).toBe(-18446744073709551616n)
+    expect(result.bytesRead).toBe(9)
+  })
+
+  it('should parse integer at non-zero offset', () => {
+    // Buffer: [0x83, 0x01, 0x02, 0x03] - array(3) then integers 1, 2, 3
+    // Parsing integer at offset 1 should get value 1
+    const buffer = hexToBytes('83010203')
+    const result = parseIntegerFromBuffer(buffer, 1)
+    expect(result.value).toBe(1)
+    expect(result.bytesRead).toBe(1)
+  })
+
+  it('should parse integer at offset with trailing data', () => {
+    // Buffer with integer 100 at offset 2, followed by other data
+    const buffer = hexToBytes('0000186400')
+    const result = parseIntegerFromBuffer(buffer, 2)
+    expect(result.value).toBe(100)
+    expect(result.bytesRead).toBe(2)
+  })
+
+  it('should produce identical results to parseInteger for all test vectors', () => {
+    const testVectors = [
+      '00', '01', '0a', '17', '1818', '1864', '18ff',
+      '190100', '1903e8', '19ffff',
+      '1a00010000', '1a000f4240', '1affffffff',
+      '1b0000000100000000', '1b000000e8d4a51000', '1bffffffffffffffff',
+      '20', '37', '3863', '38ff',
+      '390100', '3903e7', '39ffff',
+      '3a00010000', '3affffffff',
+      '3b0000000100000000', '3bffffffffffffffff',
+    ]
+
+    for (const hex of testVectors) {
+      const hexResult = parseInteger(hex)
+      const buffer = hexToBytes(hex)
+      const bufferResult = parseIntegerFromBuffer(buffer, 0)
+
+      expect(bufferResult.value).toEqual(hexResult.value)
+      expect(bufferResult.bytesRead).toEqual(hexResult.bytesRead)
+    }
+  })
+
+  it('should validate canonical encoding when options are passed', () => {
+    // Non-canonical: value 0 encoded with 1-byte AI
+    const buffer = hexToBytes('1800')
+    expect(() => parseIntegerFromBuffer(buffer, 0, { validateCanonical: true }))
+      .toThrow(/[Nn]on-canonical/)
+  })
+})
+
+describe('Buffer-native parsing - parseFromBuffer (float/simple)', () => {
+  const { parseFromBuffer } = useCborFloat()
+
+  it('should export parseFromBuffer from useCborFloat', () => {
+    expect(typeof parseFromBuffer).toBe('function')
+  })
+
+  it('should parse false from buffer', () => {
+    const buffer = hexToBytes('f4')
+    const result = parseFromBuffer(buffer, 0)
+    expect(result.value).toBe(false)
+    expect(result.bytesRead).toBe(1)
+  })
+
+  it('should parse true from buffer', () => {
+    const buffer = hexToBytes('f5')
+    const result = parseFromBuffer(buffer, 0)
+    expect(result.value).toBe(true)
+    expect(result.bytesRead).toBe(1)
+  })
+
+  it('should parse null from buffer', () => {
+    const buffer = hexToBytes('f6')
+    const result = parseFromBuffer(buffer, 0)
+    expect(result.value).toBe(null)
+    expect(result.bytesRead).toBe(1)
+  })
+
+  it('should parse undefined from buffer', () => {
+    const buffer = hexToBytes('f7')
+    const result = parseFromBuffer(buffer, 0)
+    expect(result.value).toBe(undefined)
+    expect(result.bytesRead).toBe(1)
+  })
+
+  it('should parse float16 0.0 from buffer', () => {
+    const buffer = hexToBytes('f90000')
+    const result = parseFromBuffer(buffer, 0)
+    expect(result.value).toBe(0.0)
+    expect(result.bytesRead).toBe(3)
+  })
+
+  it('should parse float16 1.0 from buffer', () => {
+    const buffer = hexToBytes('f93c00')
+    const result = parseFromBuffer(buffer, 0)
+    expect(result.value).toBe(1.0)
+    expect(result.bytesRead).toBe(3)
+  })
+
+  it('should parse float32 from buffer', () => {
+    const buffer = hexToBytes('fa47c35000')
+    const result = parseFromBuffer(buffer, 0)
+    expect(result.value).toBe(100000.0)
+    expect(result.bytesRead).toBe(5)
+  })
+
+  it('should parse float64 from buffer', () => {
+    const buffer = hexToBytes('fb3ff199999999999a')
+    const result = parseFromBuffer(buffer, 0)
+    expect(result.value).toBeCloseTo(1.1, 10)
+    expect(result.bytesRead).toBe(9)
+  })
+
+  it('should parse Infinity from buffer', () => {
+    const buffer = hexToBytes('f97c00')
+    const result = parseFromBuffer(buffer, 0)
+    expect(result.value).toBe(Infinity)
+    expect(result.bytesRead).toBe(3)
+  })
+
+  it('should parse NaN from buffer', () => {
+    const buffer = hexToBytes('f97e00')
+    const result = parseFromBuffer(buffer, 0)
+    expect(result.value).toBeNaN()
+    expect(result.bytesRead).toBe(3)
+  })
+
+  it('should parse at non-zero offset', () => {
+    const buffer = hexToBytes('00f5')
+    const result = parseFromBuffer(buffer, 1)
+    expect(result.value).toBe(true)
+    expect(result.bytesRead).toBe(1)
+  })
+})
+
+describe('Buffer-native parsing - parseTagFromBuffer', () => {
+  const { parseTagFromBuffer } = useCborTag()
+
+  it('should export parseTagFromBuffer from useCborTag', () => {
+    expect(typeof parseTagFromBuffer).toBe('function')
+  })
+
+  it('should parse tag 1 (epoch time) from buffer', () => {
+    // c11a514b67b0 = tag(1, 1363896240)
+    const buffer = hexToBytes('c11a514b67b0')
+    const result = parseTagFromBuffer(buffer, 0)
+    expect(result.value).toEqual({
+      tag: 1,
+      value: 1363896240
+    })
+    expect(result.bytesRead).toBe(6)
+  })
+
+  it('should parse self-describe tag 55799 from buffer', () => {
+    // d9d9f7 01 = tag(55799, 1)
+    const buffer = hexToBytes('d9d9f701')
+    const result = parseTagFromBuffer(buffer, 0)
+    expect(result.value).toEqual({
+      tag: 55799,
+      value: 1
+    })
+    expect(result.bytesRead).toBe(4)
+  })
+
+  it('should parse tag at non-zero offset', () => {
+    // Prefix with 0x01, then tag 1 with value 0
+    const buffer = hexToBytes('01c100')
+    const result = parseTagFromBuffer(buffer, 1)
+    expect(result.value).toEqual({
+      tag: 1,
+      value: 0
+    })
+    expect(result.bytesRead).toBe(2)
+  })
+})
+
+describe('Buffer-native parsing - collection integration', () => {
+  const { parseArray, parseMap } = useCborCollection()
+
+  it('should parse array of integers without O(N^2) hex conversion', () => {
+    // 83 01 02 03 = [1, 2, 3]
+    const result = parseArray('83010203')
+    expect(result.value).toEqual([1, 2, 3])
+    expect(result.bytesRead).toBe(4)
+  })
+
+  it('should parse array with mixed types including floats', () => {
+    // 83 01 f5 f6 = [1, true, null]
+    const result = parseArray('8301f5f6')
+    expect(result.value).toEqual([1, true, null])
+    expect(result.bytesRead).toBe(4)
+  })
+
+  it('should parse nested array with tags', () => {
+    // 82 c1 1a514b67b0 01 = [tag(1, 1363896240), 1]
+    const result = parseArray('82c11a514b67b001')
+    expect(result.value).toHaveLength(2)
+    expect((result.value as any[])[0]).toEqual({
+      tag: 1,
+      value: 1363896240
+    })
+    expect((result.value as any[])[1]).toBe(1)
+    expect(result.bytesRead).toBe(8)
+  })
+
+  it('should parse map with integer keys', () => {
+    // a2 01 02 03 04 = {1: 2, 3: 4}
+    const result = parseMap('a201020304')
+    const map = result.value as Map<any, any>
+    expect(map.get(1)).toBe(2)
+    expect(map.get(3)).toBe(4)
+    expect(result.bytesRead).toBe(5)
+  })
+
+  it('should parse map with float value', () => {
+    // a1 01 f93c00 = {1: 1.0}
+    const result = parseMap('a101f93c00')
+    const map = result.value as Map<any, any>
+    expect(map.get(1)).toBe(1.0)
+    expect(result.bytesRead).toBe(5)
+  })
+
+  it('should parse large array correctly', () => {
+    // Build array of 100 integers 0-99
+    let hex = '9864' // array(100)... but that needs proper length encoding
+    // Actually: 0x98 = array with 1-byte length, 0x64 = 100
+    hex = '9864'
+    for (let i = 0; i < 100; i++) {
+      if (i < 24) {
+        hex += i.toString(16).padStart(2, '0')
+      } else {
+        hex += '18' + i.toString(16).padStart(2, '0')
+      }
+    }
+    const result = parseArray(hex)
+    const arr = result.value as number[]
+    expect(arr).toHaveLength(100)
+    for (let i = 0; i < 100; i++) {
+      expect(arr[i]).toBe(i)
+    }
+  })
+})

package/src/parser/__tests__/cbor-map-duplicate-keys.test.ts

@@ -14,6 +14,7 @@
 import { describe, it, expect } from 'vitest'
 import { useCborParser } from '../composables/useCborParser'
 import { useCborCollection } from '../composables/useCborCollection'
+import type { CborMap } from '../types'
 
 describe('CBOR Map Duplicate Key Detection', () => {
   describe('String Keys - Duplicate Detection', () => {
@@ -154,7 +155,7 @@ describe('CBOR Map Duplicate Key Detection', () => {
 
       const result = parseMap(uniqueBytes, { dupMapKeyMode: 'reject' })
       // Byte strings as keys become comma-separated strings in JS
-      expect(result.value.size).toBe(3)
+      expect((result.value as CborMap).size).toBe(3)
     })
 
     it('should reject duplicate empty byte strings', () => {
@@ -169,17 +170,16 @@ describe('CBOR Map Duplicate Key Detection', () => {
   })
 
   describe('Mixed Type Keys - Duplicate Detection', () => {
-    it('should reject keys that collide in JavaScript object model', () => {
+    it('should allow distinct CBOR keys even if they stringify similarly', () => {
       const { parseMap } = useCborCollection()
 
       // Map: {1: 10, "1": 20} - different types in CBOR (int vs string)
       // a2 (map of 2) + 01 (key:1 integer) + 0a (val:10) + 6131 (key:"1" string) + 14 (val:20)
-      // SECURITY: Both convert to string "1" in JavaScript, causing collision
-      // This is correctly rejected to prevent unexpected behavior in Cardano applications
+      // Keys are distinct at the CBOR level and should not be treated as duplicates
       const mixedTypes = 'a2010a613114'
 
-      expect(() => parseMap(mixedTypes, { dupMapKeyMode: 'reject' }))
-        .toThrow(/duplicate.*key/i)
+      const result = parseMap(mixedTypes, { dupMapKeyMode: 'reject' })
+      expect((result.value as CborMap).size).toBe(2)
     })
 
     it('should detect duplicates when both are strings', () => {
@@ -333,7 +333,7 @@ describe('CBOR Map Duplicate Key Detection', () => {
         limits: { maxMapSize: 100 }
       })
 
-      expect(result.value.size).toBe(30)
+      expect((result.value as CborMap).size).toBe(30)
     })
   })
 
@@ -377,6 +377,96 @@ describe('CBOR Map Duplicate Key Detection', () => {
     })
   })
 
+  describe('Semantic Duplicate Detection (RFC 8949 Section 5.6)', () => {
+    it('should reject integer 1 encoded as 0x01 and 0x1801 as duplicate keys', () => {
+      const { parseMap } = useCborCollection()
+
+      // Map with 2 entries, key 1 (0x01) -> value 10 (0x0a), key 1 (0x1801) -> value 20 (0x14)
+      // 0x01 encodes integer 1 directly (AI=1)
+      // 0x1801 encodes integer 1 with 1-byte payload (AI=24, payload=0x01)
+      // Both represent semantic value 1 -- must be detected as duplicate
+      // a2 = map(2), 01 = int(1), 0a = int(10), 1801 = int(1), 14 = int(20)
+      const duplicateHex = 'a2010a180114'
+
+      expect(() => parseMap(duplicateHex, { dupMapKeyMode: 'reject' }))
+        .toThrow(/duplicate/i)
+    })
+
+    it('should reject integer 1 encoded as 0x01 and 0x190001 as duplicate keys', () => {
+      const { parseMap } = useCborCollection()
+
+      // 0x01 encodes integer 1 directly (AI=1)
+      // 0x190001 encodes integer 1 with 2-byte payload (AI=25, payload=0x0001)
+      // Both represent semantic value 1
+      // a2 = map(2), 01 = int(1), 0a = int(10), 190001 = int(1), 14 = int(20)
+      const duplicateHex = 'a2010a19000114'
+
+      expect(() => parseMap(duplicateHex, { dupMapKeyMode: 'reject' }))
+        .toThrow(/duplicate/i)
+    })
+
+    it('should reject integer 1 encoded as 0x1801 and 0x190001 as duplicate keys', () => {
+      const { parseMap } = useCborCollection()
+
+      // 0x1801 encodes integer 1 with 1-byte payload (AI=24, payload=0x01)
+      // 0x190001 encodes integer 1 with 2-byte payload (AI=25, payload=0x0001)
+      // Both represent semantic value 1
+      // a2 = map(2), 1801 = int(1), 0a = int(10), 190001 = int(1), 14 = int(20)
+      const duplicateHex = 'a218010a19000114'
+
+      expect(() => parseMap(duplicateHex, { dupMapKeyMode: 'reject' }))
+        .toThrow(/duplicate/i)
+    })
+
+    it('should reject integer 0 encoded with different byte widths as duplicate keys', () => {
+      const { parseMap } = useCborCollection()
+
+      // 0x00 encodes integer 0 directly (AI=0)
+      // 0x1800 encodes integer 0 with 1-byte payload (AI=24, payload=0x00)
+      // Both represent semantic value 0
+      // a2 = map(2), 00 = int(0), 01 = int(1), 1800 = int(0), 02 = int(2)
+      const duplicateHex = 'a200011800 02'
+
+      expect(() => parseMap(duplicateHex, { dupMapKeyMode: 'reject' }))
+        .toThrow(/duplicate/i)
+    })
+
+    it('should still allow semantically different integer keys', () => {
+      const { parseMap } = useCborCollection()
+
+      // Map: {1: 10, 2: 20} - different semantic values, even if both use non-canonical encoding
+      // a2 = map(2), 1801 = int(1), 0a = int(10), 1802 = int(2), 14 = int(20)
+      const uniqueHex = 'a218010a180214'
+
+      const result = parseMap(uniqueHex, { dupMapKeyMode: 'reject' })
+      expect((result.value as CborMap).size).toBe(2)
+    })
+
+    it('should detect semantic duplicates via parseWithSourceMap path', () => {
+      const { parseWithSourceMap } = useCborParser()
+
+      // Map with key 1 (0x01) and key 1 (0x1801) -- semantic duplicate
+      // a2 = map(2), 01 = int(1), 0a = int(10), 1801 = int(1), 14 = int(20)
+      const duplicateHex = 'a2010a180114'
+
+      expect(() => parseWithSourceMap(duplicateHex, { dupMapKeyMode: 'reject' }))
+        .toThrow(/duplicate/i)
+    })
+
+    it('should detect semantic duplicates in indefinite-length maps', () => {
+      const { parseMap } = useCborCollection()
+
+      // Indefinite map: {_ 1: 10, 1(non-canonical): 20 }
+      // bf = map(indefinite), 01 = int(1), 0a = int(10), 1801 = int(1), 14 = int(20), ff = break
+      const duplicateHex = 'bf010a180114ff'
+
+      expect(() => parseMap(duplicateHex, {
+        dupMapKeyMode: 'reject',
+        allowIndefinite: true
+      })).toThrow(/duplicate/i)
+    })
+  })
+
   describe('Default Behavior', () => {
     it('should NOT reject duplicates by default (lenient mode)', () => {
       const { parseMap } = useCborCollection()