@marcuspuchalla/nachos 0.1.0

package/src/encoder/composables/useCborStringEncoder.ts

@@ -0,0 +1,266 @@
+/**
+ * CBOR String Encoder Composable
+ * Handles Major Type 2 (Byte Strings) and Major Type 3 (Text Strings)
+ * Following RFC 8949 specification
+ */
+
+import type { EncodeResult, EncodeOptions, CborByteString, CborTextString } from '../types'
+import { DEFAULT_ENCODE_OPTIONS, INDEFINITE_SYMBOL } from '../types'
+import { bytesToHex, concatenateUint8Arrays, writeUint, writeBigUint } from '../utils'
+import { useCborByteString, useCborTextString } from '../../parser/composables/useCborStringTypes'
+
+interface StringEncodeOptions {
+  indefinite?: boolean
+}
+
+/**
+ * CBOR String Encoder Composable
+ *
+ * Provides functions to encode byte strings and text strings:
+ * - Major Type 2: Byte strings (Uint8Array)
+ * - Major Type 3: Text strings (UTF-8 encoded)
+ *
+ * Supports both definite-length and indefinite-length encoding.
+ *
+ * @param options - Global encoder options
+ *
+ * @example
+ * ```ts
+ * const { encodeByteString, encodeTextString } = useCborStringEncoder()
+ *
+ * // Encode byte string
+ * const bytes = new Uint8Array([0x01, 0x02, 0x03])
+ * const result1 = encodeByteString(bytes)
+ * // result1: { bytes: Uint8Array([0x43, 0x01, 0x02, 0x03]), hex: '43010203' }
+ *
+ * // Encode text string
+ * const result2 = encodeTextString('Hello')
+ * // result2: { bytes: Uint8Array([0x65, 0x48, 0x65, 0x6c, 0x6c, 0x6f]), hex: '6548656c6c6f' }
+ *
+ * // Indefinite-length encoding
+ * const chunks = [new Uint8Array([0xaa]), new Uint8Array([0xbb])]
+ * const result3 = encodeByteStringIndefinite(chunks)
+ * // result3: { bytes: Uint8Array([0x5f, 0x41, 0xaa, 0x41, 0xbb, 0xff]), hex: '5f41aa41bbff' }
+ * ```
+ */
+export function useCborStringEncoder(globalOptions?: Partial<EncodeOptions>) {
+  const options = { ...DEFAULT_ENCODE_OPTIONS, ...globalOptions }
+  const { isCborByteString } = useCborByteString()
+  const { isCborTextString } = useCborTextString()
+
+  /**
+   * Encode the length header for a string
+   *
+   * @param majorType - Major type (2 for bytes, 3 for text)
+   * @param length - Length of the string in bytes
+   * @returns Encoded length header
+   */
+  const encodeLengthHeader = (majorType: number, length: number): Uint8Array => {
+    const baseValue = majorType << 5
+
+    // Direct encoding (0-23)
+    if (length <= 23) {
+      return new Uint8Array([baseValue | length])
+    }
+    // 1-byte length (24-255)
+    else if (length <= 255) {
+      return new Uint8Array([baseValue | 24, length])
+    }
+    // 2-byte length (256-65535)
+    else if (length <= 65535) {
+      const lengthBytes = writeUint(length, 2)
+      return new Uint8Array([baseValue | 25, ...lengthBytes])
+    }
+    // 4-byte length (65536-4294967295)
+    else if (length <= 4294967295) {
+      const lengthBytes = writeUint(length, 4)
+      return new Uint8Array([baseValue | 26, ...lengthBytes])
+    }
+    // 8-byte length (> 4294967295)
+    else {
+      const lengthBytes = length > Number.MAX_SAFE_INTEGER
+        ? writeBigUint(BigInt(length), 8)
+        : writeUint(length, 8)
+      return new Uint8Array([baseValue | 27, ...lengthBytes])
+    }
+  }
+
+  /**
+   * Encode byte string (Major Type 2)
+   *
+   * Can encode either:
+   * - Definite-length: Single Uint8Array
+   * - Indefinite-length: Array of Uint8Array chunks (if indefinite option is set)
+   *
+   * @param data - Byte data or array of chunks
+   * @param encodeOptions - Encoding options
+   * @returns Encoded CBOR bytes and hex string
+   * @throws Error if indefinite encoding is used in canonical mode
+   */
+  const encodeByteString = (
+    data: Uint8Array | Uint8Array[] | CborByteString,
+    encodeOptions?: StringEncodeOptions
+  ): EncodeResult => {
+    // Check if it's a CborByteString with indefinite marker
+    const isIndefinite = isCborByteString(data) && (data as any)[INDEFINITE_SYMBOL] === true
+
+    // Handle indefinite-length encoding
+    if (encodeOptions?.indefinite || Array.isArray(data) || isIndefinite) {
+      if (options.canonical) {
+        throw new Error('Indefinite-length encoding not allowed in canonical mode')
+      }
+
+      // If it's a CborByteString with chunks, use the original chunks
+      if (isCborByteString(data) && data.chunks) {
+        return encodeByteStringIndefinite(data.chunks)
+      }
+
+      // Otherwise, get the actual bytes and encode as single chunk
+      const bytes = isCborByteString(data) ? data.bytes : (Array.isArray(data) ? data : [data])
+      return encodeByteStringIndefinite(Array.isArray(bytes) ? bytes : [bytes])
+    }
+
+    // Definite-length encoding - extract bytes from CborByteString if needed
+    const bytes = isCborByteString(data) ? data.bytes : (data as Uint8Array)
+    const header = encodeLengthHeader(2, bytes.length)
+    const result = concatenateUint8Arrays([header, bytes])
+
+    // Check output size limit
+    if (result.length > options.maxOutputSize) {
+      throw new Error('Encoded output exceeds maximum size')
+    }
+
+    return {
+      bytes: result,
+      hex: bytesToHex(result)
+    }
+  }
+
+  /**
+   * Encode byte string with indefinite length (Major Type 2)
+   *
+   * Format: 0x5f + chunk1 + chunk2 + ... + 0xff
+   * Each chunk is a definite-length byte string.
+   *
+   * @param chunks - Array of byte string chunks
+   * @returns Encoded CBOR bytes and hex string
+   */
+  const encodeByteStringIndefinite = (chunks: Uint8Array[]): EncodeResult => {
+    if (options.canonical) {
+      throw new Error('Indefinite-length encoding not allowed in canonical mode')
+    }
+
+    const parts: Uint8Array[] = [new Uint8Array([0x5f])]  // Start marker
+
+    // Encode each chunk as definite-length byte string
+    for (const chunk of chunks) {
+      const header = encodeLengthHeader(2, chunk.length)
+      parts.push(header)
+      parts.push(chunk)
+    }
+
+    parts.push(new Uint8Array([0xff]))  // Break marker
+
+    const result = concatenateUint8Arrays(parts)
+
+    return {
+      bytes: result,
+      hex: bytesToHex(result)
+    }
+  }
+
+  /**
+   * Encode text string (Major Type 3)
+   *
+   * Text strings are encoded as UTF-8 bytes.
+   *
+   * @param text - Text string to encode
+   * @param _encodeOptions - Encoding options (reserved for future use)
+   * @returns Encoded CBOR bytes and hex string
+   */
+  const encodeTextString = (
+    text: string | CborTextString,
+    encodeOptions?: StringEncodeOptions
+  ): EncodeResult => {
+    // Check if it's a CborTextString with indefinite marker
+    const isIndefinite = isCborTextString(text) && (text as any)[INDEFINITE_SYMBOL] === true
+
+    // Handle indefinite-length encoding
+    if (encodeOptions?.indefinite || isIndefinite) {
+      if (options.canonical) {
+        throw new Error('Indefinite-length encoding not allowed in canonical mode')
+      }
+
+      // If it's a CborTextString with chunks, use the original chunks
+      if (isCborTextString(text) && text.chunks) {
+        return encodeTextStringIndefinite(text.chunks)
+      }
+
+      // Otherwise, get the actual text and encode as single chunk
+      const textStr = isCborTextString(text) ? text.text : text
+      return encodeTextStringIndefinite([textStr])
+    }
+
+    // Definite-length encoding - extract text from CborTextString if needed
+    const textStr = isCborTextString(text) ? text.text : text
+
+    // Convert string to UTF-8 bytes
+    const encoder = new TextEncoder()
+    const utf8Bytes = encoder.encode(textStr)
+
+    const header = encodeLengthHeader(3, utf8Bytes.length)
+    const result = concatenateUint8Arrays([header, utf8Bytes])
+
+    // Check output size limit
+    if (result.length > options.maxOutputSize) {
+      throw new Error('Encoded output exceeds maximum size')
+    }
+
+    return {
+      bytes: result,
+      hex: bytesToHex(result)
+    }
+  }
+
+  /**
+   * Encode text string with indefinite length (Major Type 3)
+   *
+   * Format: 0x7f + chunk1 + chunk2 + ... + 0xff
+   * Each chunk is a definite-length text string.
+   *
+   * @param chunks - Array of text string chunks
+   * @returns Encoded CBOR bytes and hex string
+   */
+  const encodeTextStringIndefinite = (chunks: string[]): EncodeResult => {
+    if (options.canonical) {
+      throw new Error('Indefinite-length encoding not allowed in canonical mode')
+    }
+
+    const parts: Uint8Array[] = [new Uint8Array([0x7f])]  // Start marker
+
+    // Encode each chunk as definite-length text string
+    const encoder = new TextEncoder()
+    for (const chunk of chunks) {
+      const utf8Bytes = encoder.encode(chunk)
+      const header = encodeLengthHeader(3, utf8Bytes.length)
+      parts.push(header)
+      parts.push(utf8Bytes)
+    }
+
+    parts.push(new Uint8Array([0xff]))  // Break marker
+
+    const result = concatenateUint8Arrays(parts)
+
+    return {
+      bytes: result,
+      hex: bytesToHex(result)
+    }
+  }
+
+  return {
+    encodeByteString,
+    encodeByteStringIndefinite,
+    encodeTextString,
+    encodeTextStringIndefinite
+  }
+}

package/src/encoder/composables/useCborTagEncoder.ts

@@ -0,0 +1,158 @@
+/**
+ * CBOR Tag Encoder Composable
+ * Handles Major Type 6 (Semantic Tags)
+ * Following RFC 8949 specification
+ */
+
+import type { EncodeResult, TaggedValue, EncodableValue } from '../types'
+import { bytesToHex, writeUint, writeBigUint } from '../utils'
+
+/**
+ * CBOR Tag Encoder Composable
+ *
+ * Provides functions to encode tagged values to CBOR format:
+ * - Major Type 6: Semantic tags (0 to 2^64-1)
+ *
+ * Tags provide semantic meaning to CBOR values:
+ * - Tag 0: Date/time string (RFC 3339)
+ * - Tag 1: Epoch timestamp
+ * - Tag 2: Positive bignum
+ * - Tag 3: Negative bignum
+ * - Tag 258: Cardano set (CIP-0005)
+ * - And many more...
+ *
+ * @example
+ * ```ts
+ * const { encodeTag } = useCborTagEncoder()
+ *
+ * // Encode date/time string (tag 0)
+ * const result1 = encodeTag(0, '2013-03-21T20:04:00Z', encode)
+ * // result1.hex: 'c074323031332d30332d32315432303a30343a30305a'
+ *
+ * // Encode positive bignum (tag 2)
+ * const result2 = encodeTag(2, new Uint8Array([0x01, 0xff]), encode)
+ * // result2.hex: 'c24201ff'
+ *
+ * // Encode Cardano set (tag 258)
+ * const result3 = encodeTag(258, [1, 2, 3], encode)
+ * // result3.hex: 'd9010283010203'
+ * ```
+ */
+export function useCborTagEncoder() {
+  /**
+   * Encode tag number (Major Type 6 header)
+   *
+   * Tag numbers use the same encoding rules as unsigned integers:
+   * - 0-23: Direct encoding in initial byte (0xc0-0xd7)
+   * - 24-255: 0xd8 + 1 byte
+   * - 256-65535: 0xd9 + 2 bytes
+   * - 65536-4294967295: 0xda + 4 bytes
+   * - 4294967296-2^64-1: 0xdb + 8 bytes
+   *
+   * @param tagNumber - Tag number (0 to 2^64-1)
+   * @returns Encoded tag header bytes
+   * @throws Error if tag number is negative or >= 2^64
+   */
+  const encodeTagNumber = (tagNumber: number | bigint): Uint8Array => {
+    // Convert to BigInt for consistent handling
+    const bigTag = typeof tagNumber === 'bigint' ? tagNumber : BigInt(tagNumber)
+
+    // Validate tag is non-negative
+    if (bigTag < 0n) {
+      throw new Error('Tag number cannot be negative')
+    }
+
+    // Validate tag doesn't exceed 2^64-1
+    const MAX_UINT64 = 18446744073709551615n  // 2^64 - 1
+    if (bigTag > MAX_UINT64) {
+      throw new Error('Tag number exceeds maximum (2^64-1)')
+    }
+
+    let bytes: Uint8Array
+
+    // Direct encoding (0-23) - Major type 6 (0xc0) + tag number
+    if (bigTag <= 23n) {
+      bytes = new Uint8Array([0xc0 + Number(bigTag)])
+    }
+    // 1-byte encoding (24-255) - 0xd8 + 1 byte
+    else if (bigTag <= 255n) {
+      bytes = new Uint8Array([0xd8, Number(bigTag)])
+    }
+    // 2-byte encoding (256-65535) - 0xd9 + 2 bytes
+    else if (bigTag <= 65535n) {
+      const valueBytes = writeUint(Number(bigTag), 2)
+      bytes = new Uint8Array([0xd9, ...valueBytes])
+    }
+    // 4-byte encoding (65536-4294967295) - 0xda + 4 bytes
+    else if (bigTag <= 4294967295n) {
+      const valueBytes = writeUint(Number(bigTag), 4)
+      bytes = new Uint8Array([0xda, ...valueBytes])
+    }
+    // 8-byte encoding (> 4294967295) - 0xdb + 8 bytes
+    else {
+      const valueBytes = writeBigUint(bigTag, 8)
+      bytes = new Uint8Array([0xdb, ...valueBytes])
+    }
+
+    return bytes
+  }
+
+  /**
+   * Encode tagged value (tag + content)
+   *
+   * A tagged value consists of:
+   * 1. Tag number (Major Type 6 header)
+   * 2. Tagged content (recursively encoded value)
+   *
+   * The encode function is passed as a parameter to avoid circular dependencies.
+   *
+   * @param tagNumber - Tag number
+   * @param value - Value to tag
+   * @param encode - Encoder function for the tagged value
+   * @returns Encoded CBOR bytes and hex string
+   */
+  const encodeTag = (
+    tagNumber: number | bigint,
+    value: EncodableValue,
+    encode: (value: EncodableValue) => EncodeResult
+  ): EncodeResult => {
+    // Encode tag number
+    const tagBytes = encodeTagNumber(tagNumber)
+
+    // Recursively encode the tagged value
+    const valueResult = encode(value)
+
+    // Concatenate tag header + value bytes
+    const totalLength = tagBytes.length + valueResult.bytes.length
+    const bytes = new Uint8Array(totalLength)
+    bytes.set(tagBytes, 0)
+    bytes.set(valueResult.bytes, tagBytes.length)
+
+    return {
+      bytes,
+      hex: bytesToHex(bytes)
+    }
+  }
+
+  /**
+   * Encode TaggedValue object
+   *
+   * Convenience function for encoding { tag, value } objects.
+   *
+   * @param taggedValue - Object with tag and value properties
+   * @param encode - Encoder function for the tagged value
+   * @returns Encoded CBOR bytes and hex string
+   */
+  const encodeTaggedValue = (
+    taggedValue: TaggedValue,
+    encode: (value: EncodableValue) => EncodeResult
+  ): EncodeResult => {
+    return encodeTag(taggedValue.tag, taggedValue.value, encode)
+  }
+
+  return {
+    encodeTagNumber,
+    encodeTag,
+    encodeTaggedValue
+  }
+}

package/src/encoder/index.ts

@@ -0,0 +1,35 @@
+/**
+ * NACHOS Encoder Module
+ *
+ * @module @marcuspuchalla/nachos/encoder
+ */
+
+// Export encoder composables
+export { useCborEncoder } from './composables/useCborEncoder'
+export { useCborIntegerEncoder } from './composables/useCborIntegerEncoder'
+export { useCborStringEncoder } from './composables/useCborStringEncoder'
+export { useCborCollectionEncoder } from './composables/useCborCollectionEncoder'
+export { useCborSimpleEncoder } from './composables/useCborSimpleEncoder'
+export { useCborTagEncoder } from './composables/useCborTagEncoder'
+
+// Export types
+export type {
+  EncodeResult,
+  EncodeOptions,
+  EncodableValue,
+  EncodeContext
+} from './types'
+
+// Export constants
+export {
+  DEFAULT_ENCODE_OPTIONS
+} from './types'
+
+// Export utility functions
+export {
+  bytesToHex,
+  concatenateUint8Arrays,
+  compareBytes,
+  writeUint,
+  writeBigUint
+} from './utils'

package/src/encoder/types.ts

@@ -0,0 +1,88 @@
+/**
+ * CBOR Encoder Type Definitions
+ * Following RFC 8949 specification
+ */
+
+import type { PlutusConstr, CborByteString, CborTextString } from '../parser/types'
+import { INDEFINITE_SYMBOL, ALL_ENTRIES_SYMBOL } from '../parser/types'
+
+// Re-export symbols and types for use in encoder
+export { INDEFINITE_SYMBOL, ALL_ENTRIES_SYMBOL }
+export type { CborByteString, CborTextString }
+
+/**
+ * Encoder options for controlling behavior
+ */
+export interface EncodeOptions {
+  /** Enable canonical encoding (shortest form, sorted maps) */
+  canonical?: boolean
+  /** Allow indefinite-length encoding (false in canonical mode) */
+  allowIndefinite?: boolean
+  /** Reject duplicate map keys */
+  rejectDuplicateKeys?: boolean
+  /** Maximum nesting depth */
+  maxDepth?: number
+  /** Maximum output size in bytes */
+  maxOutputSize?: number
+}
+
+/**
+ * Default encode options
+ */
+export const DEFAULT_ENCODE_OPTIONS: Required<EncodeOptions> = {
+  canonical: false,
+  allowIndefinite: true,
+  rejectDuplicateKeys: false,
+  maxDepth: 64,
+  maxOutputSize: 100 * 1024 * 1024  // 100 MB
+}
+
+/**
+ * Result of encoding operation
+ */
+export interface EncodeResult {
+  /** Encoded CBOR bytes */
+  bytes: Uint8Array
+  /** Hex string representation */
+  hex: string
+}
+
+/**
+ * Values that can be encoded to CBOR
+ *
+ * Supports both plain objects (for convenience) and Maps (for type preservation).
+ * Map<any, any> is preferred for maps with non-string keys (integers, Uint8Arrays, etc.)
+ */
+export type EncodableValue =
+  | number
+  | bigint
+  | string
+  | boolean
+  | null
+  | undefined
+  | Uint8Array
+  | EncodableValue[]
+  | { [key: string]: EncodableValue }  // Plain object (legacy/convenience)
+  | Map<EncodableValue, EncodableValue>  // Map (preserves key types)
+  | TaggedValue
+
+/**
+ * Tagged CBOR value (Major Type 6)
+ */
+export interface TaggedValue {
+  tag: number
+  value: EncodableValue
+  plutus?: PlutusConstr
+}
+
+/**
+ * Encoding context that tracks state during CBOR encoding
+ */
+export interface EncodeContext {
+  /** Current nesting depth */
+  depth: number
+  /** Bytes written so far */
+  bytesWritten: number
+  /** Encoder options */
+  options: Required<EncodeOptions>
+}

package/src/encoder/utils.ts

@@ -0,0 +1,80 @@
+/**
+ * CBOR Encoder Utility Functions
+ */
+
+/**
+ * Convert Uint8Array to hex string
+ */
+export function bytesToHex(bytes: Uint8Array): string {
+  return Array.from(bytes)
+    .map(b => b.toString(16).padStart(2, '0'))
+    .join('')
+}
+
+/**
+ * Concatenate multiple Uint8Arrays
+ */
+export function concatenateUint8Arrays(arrays: Uint8Array[]): Uint8Array {
+  const totalLength = arrays.reduce((sum, arr) => sum + arr.length, 0)
+  const result = new Uint8Array(totalLength)
+
+  let offset = 0
+  for (const arr of arrays) {
+    result.set(arr, offset)
+    offset += arr.length
+  }
+
+  return result
+}
+
+/**
+ * Compare two Uint8Arrays bytewise (for canonical map sorting)
+ */
+export function compareBytes(a: Uint8Array, b: Uint8Array): number {
+  // First, compare lengths
+  if (a.length !== b.length) {
+    return a.length - b.length
+  }
+
+  // Then, compare bytewise
+  for (let i = 0; i < a.length; i++) {
+    const byteA = a[i]
+    const byteB = b[i]
+    if (byteA === undefined || byteB === undefined) {
+      throw new Error(`Unexpected undefined byte at index ${i}`)
+    }
+    if (byteA !== byteB) {
+      return byteA - byteB
+    }
+  }
+
+  return 0
+}
+
+/**
+ * Write unsigned integer to bytes (big-endian)
+ */
+export function writeUint(value: number, bytes: number): Uint8Array {
+  const result = new Uint8Array(bytes)
+
+  for (let i = bytes - 1; i >= 0; i--) {
+    result[i] = value & 0xff
+    value = value >>> 8
+  }
+
+  return result
+}
+
+/**
+ * Write BigInt to bytes (big-endian)
+ */
+export function writeBigUint(value: bigint, bytes: number): Uint8Array {
+  const result = new Uint8Array(bytes)
+
+  for (let i = bytes - 1; i >= 0; i--) {
+    result[i] = Number(value & 0xffn)
+    value = value >> 8n
+  }
+
+  return result
+}