@marcuspuchalla/nachos 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,494 @@
+export { c as useCborCollection, d as useCborFloat, a as useCborInteger, u as useCborParser, b as useCborString, e as useCborTag } from './useCborTag-B_iaShG6.js';
+import { E as EncodableValue, a as EncodeOptions, b as EncodeResult } from './useCborSimpleEncoder-TVxzNJ_9.js';
+export { D as DEFAULT_ENCODE_OPTIONS, g as EncodeContext, e as useCborCollectionEncoder, u as useCborEncoder, c as useCborIntegerEncoder, f as useCborSimpleEncoder, d as useCborStringEncoder } from './useCborSimpleEncoder-TVxzNJ_9.js';
+import { P as ParseOptions, a as ParseResult, b as ParseResultWithMap } from './types-DvNlfbKB.js';
+export { o as CborAdditionalInfo, C as CborContext, n as CborMajorType, f as CborMap, p as CborSimpleValue, q as CborTag, e as CborValue, m as DEFAULT_LIMITS, D as DEFAULT_OPTIONS, c as ParseError, d as ParserLimits, l as PlutusBytes, h as PlutusConstr, g as PlutusData, k as PlutusInt, j as PlutusList, i as PlutusMap, R as Result, S as SourceMapEntry, T as TaggedValue } from './types-DvNlfbKB.js';
+
+/**
+ * useCborDiagnostic - RFC 8949 Appendix B Diagnostic Notation
+ *
+ * Converts CBOR values to human-readable diagnostic notation as defined
+ * in RFC 8949 (Concise Binary Object Representation).
+ *
+ * @example
+ * ```typescript
+ * const { toDiagnostic } = useCborDiagnostic()
+ *
+ * toDiagnostic(100)                    // "100"
+ * toDiagnostic(new Uint8Array([1,2]))  // "h'0102'"
+ * toDiagnostic([1, 2, 3])              // "[1, 2, 3]"
+ * toDiagnostic({a: 1})                 // '{"a": 1}'
+ * ```
+ */
+/**
+ * Options for diagnostic notation output
+ */
+interface DiagnosticOptions {
+    /** Pretty print with indentation (default: false) */
+    pretty?: boolean;
+    /** Indentation string for pretty printing (default: '  ') */
+    indent?: string;
+    /** Maximum depth for nested structures (default: 100) */
+    maxDepth?: number;
+    /** Mark as indefinite-length (default: false) */
+    indefinite?: boolean;
+    /** Show byte offsets as comments (default: false) */
+    showOffsets?: boolean;
+}
+/**
+ * Composable for CBOR diagnostic notation
+ */
+declare function useCborDiagnostic(): {
+    toDiagnostic: (value: unknown, options?: DiagnosticOptions) => string;
+    fromDiagnostic: (diag: string) => unknown;
+    toDiagnosticWithType: (value: unknown, majorType: number, options?: DiagnosticOptions) => string;
+};
+
+/**
+ * PathBuilder - Utilities for creating and manipulating source map paths
+ *
+ * Path format follows JSON Pointer (RFC 6901) with CBOR-specific extensions:
+ * - Array indices: [0], [1], [2]
+ * - Object/Map keys: .key, .nested.key
+ * - Special markers: [#header], [#content], [#value]
+ *
+ * @example
+ * ```typescript
+ * import { PathBuilder } from './pathBuilder'
+ *
+ * const path = PathBuilder.arrayIndex('', 0)        // "[0]"
+ * const nested = PathBuilder.arrayIndex(path, 1)   // "[0][1]"
+ * const key = PathBuilder.mapKey(nested, 'amount') // "[0][1].amount"
+ * const header = PathBuilder.header(key)           // "[0][1].amount[#header]"
+ * ```
+ */
+/**
+ * PathBuilder utility object with methods for creating and manipulating paths
+ */
+declare const PathBuilder: {
+    /**
+     * Create root path (empty string)
+     */
+    root: () => string;
+    /**
+     * Create path for array index
+     * @param parent - Parent path
+     * @param index - Array index (0-based)
+     * @returns Path string like "[0]" or "[0][1]"
+     */
+    arrayIndex: (parent: string, index: number) => string;
+    /**
+     * Create path for map/object key
+     * @param parent - Parent path
+     * @param key - Key name (string or number)
+     * @returns Path string like ".key" or "[0].key"
+     */
+    mapKey: (parent: string, key: string | number) => string;
+    /**
+     * Create path for map key by index (for non-string keys)
+     * @param parent - Parent path
+     * @param index - Key index in map
+     * @returns Path string like "[#key:0]"
+     */
+    mapKeyIndex: (parent: string, index: number) => string;
+    /**
+     * Create path for header portion of a value
+     * Used for byte strings, text strings, arrays, maps, tags
+     * @param parent - Parent path
+     * @returns Path string like "[0][#header]"
+     */
+    header: (parent: string) => string;
+    /**
+     * Create path for content portion of a value
+     * Used for byte strings and text strings
+     * @param parent - Parent path
+     * @returns Path string like "[0][#content]"
+     */
+    content: (parent: string) => string;
+    /**
+     * Create path for tagged value
+     * @param parent - Parent path
+     * @returns Path string like "[0][#value]"
+     */
+    tagValue: (parent: string) => string;
+    /**
+     * Normalize a path by removing special markers (#header, #content, #value)
+     * Used for matching paths across different representations
+     * @param path - Path to normalize
+     * @returns Normalized path without special markers
+     */
+    normalize: (path: string) => string;
+    /**
+     * Check if path is a header path
+     * @param path - Path to check
+     * @returns True if path ends with [#header]
+     */
+    isHeader: (path: string) => boolean;
+    /**
+     * Check if path is a content path
+     * @param path - Path to check
+     * @returns True if path ends with [#content]
+     */
+    isContent: (path: string) => boolean;
+    /**
+     * Check if path is a tag value path
+     * @param path - Path to check
+     * @returns True if path ends with [#value]
+     */
+    isTagValue: (path: string) => boolean;
+    /**
+     * Check if path has any special marker
+     * @param path - Path to check
+     * @returns True if path ends with any special marker
+     */
+    hasMarker: (path: string) => boolean;
+    /**
+     * Get parent path (one level up)
+     * @param path - Path to get parent of
+     * @returns Parent path or null if already at root
+     */
+    getParent: (path: string) => string | null;
+    /**
+     * Get the depth (nesting level) of a path
+     * @param path - Path to measure
+     * @returns Number indicating nesting depth (0 for root)
+     */
+    getDepth: (path: string) => number;
+    /**
+     * Parse a path into its components
+     * @param path - Path to parse
+     * @returns Array of path segments
+     */
+    parse: (path: string) => Array<{
+        type: "index" | "key" | "marker";
+        value: string | number;
+    }>;
+    /**
+     * Build a path from segments
+     * @param segments - Array of path segments
+     * @returns Path string
+     */
+    build: (segments: Array<{
+        type: "index" | "key" | "marker";
+        value: string | number;
+    }>) => string;
+    /**
+     * Join multiple path segments
+     * @param paths - Path segments to join
+     * @returns Combined path
+     */
+    join: (...paths: string[]) => string;
+    /**
+     * Check if a path is a descendant of another path
+     * @param path - Path to check
+     * @param ancestor - Potential ancestor path
+     * @returns True if path is a descendant of ancestor
+     */
+    isDescendantOf: (path: string, ancestor: string) => boolean;
+};
+
+/**
+ * NACHOS - Not Another CBOR Handling Object System
+ *
+ * RFC 8949 CBOR (Concise Binary Object Representation) encoder and decoder
+ * with full source map support for interactive debugging.
+ *
+ * @module @marcuspuchalla/nachos
+ * @see https://datatracker.ietf.org/doc/html/rfc8949
+ *
+ * @example
+ * ```typescript
+ * // Simple decoding
+ * import { decode } from '@marcuspuchalla/nachos'
+ * const result = decode('1864')  // { value: 100, bytesRead: 2 }
+ *
+ * // Simple encoding
+ * import { encode } from '@marcuspuchalla/nachos'
+ * const { hex, bytes } = encode(100)  // hex: "1864"
+ *
+ * // With source maps for debugging
+ * import { decodeWithSourceMap } from '@marcuspuchalla/nachos'
+ * const { value, sourceMap } = decodeWithSourceMap('d87980')
+ * // sourceMap links hex bytes to decoded values
+ * ```
+ */
+
+/**
+ * Decode CBOR hex string to JavaScript value
+ *
+ * @param hexString - CBOR data as hex string (e.g., "1864" for integer 100)
+ * @param options - Optional parser configuration
+ * @returns Decoded value and number of bytes consumed
+ *
+ * @throws {Error} If input is invalid or malformed CBOR
+ *
+ * @example
+ * ```typescript
+ * // Decode integer
+ * decode('1864')  // { value: 100, bytesRead: 2 }
+ *
+ * // Decode string
+ * decode('6449455446')  // { value: "IETF", bytesRead: 5 }
+ *
+ * // Decode array
+ * decode('83010203')  // { value: [1, 2, 3], bytesRead: 4 }
+ *
+ * // With strict validation
+ * decode('1864', { strict: true })
+ *
+ * // With canonical validation
+ * decode('a16161 01', { validateCanonical: true })
+ * ```
+ *
+ * @see {@link https://datatracker.ietf.org/doc/html/rfc8949 | RFC 8949}
+ */
+declare function decode(hexString: string, options?: ParseOptions): ParseResult;
+/**
+ * Decode CBOR hex string 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
+ * @param options - Optional parser configuration
+ * @returns Decoded value, byte count, and source map
+ *
+ * @example
+ * ```typescript
+ * const { value, sourceMap } = decodeWithSourceMap('d87980')
+ * // value: { tag: 121, value: [] }
+ * // sourceMap: [
+ * //   { path: '', start: 0, end: 3, majorType: 6, type: 'Tag 121', children: ['.value'] },
+ * //   { 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}`)
+ * ```
+ */
+declare function decodeWithSourceMap(hexString: string, options?: ParseOptions): ParseResultWithMap;
+/**
+ * Encode JavaScript value to CBOR
+ *
+ * Automatically detects value type and uses appropriate CBOR encoding.
+ * Supports: numbers, bigints, strings, booleans, null, undefined, Uint8Arrays, arrays, objects, and tagged values.
+ *
+ * @param value - JavaScript value to encode
+ * @param options - Optional encoder configuration
+ * @returns CBOR bytes and hex string
+ *
+ * @throws {Error} If value type is unsupported or encoding fails
+ *
+ * @example
+ * ```typescript
+ * // Encode number
+ * encode(100)  // { hex: "1864", bytes: Uint8Array[0x18, 0x64] }
+ *
+ * // Encode string
+ * encode("IETF")  // { hex: "6449455446", bytes: ... }
+ *
+ * // Encode array
+ * encode([1, 2, 3])  // { hex: "83010203", bytes: ... }
+ *
+ * // Encode map (canonical - sorted keys)
+ * encode({ z: 1, a: 2 }, { canonical: true })
+ * // Keys will be sorted: { a: 2, z: 1 }
+ *
+ * // Encode tagged value
+ * encode({ tag: 121, value: [] })  // { hex: "d87980", bytes: ... }
+ * ```
+ */
+declare function encode(value: EncodableValue, options?: Partial<EncodeOptions>): EncodeResult;
+/**
+ * Encode JavaScript value to CBOR hex string
+ *
+ * Convenience function that returns only the hex string (not the bytes).
+ *
+ * @param value - JavaScript value to encode
+ * @param options - Optional encoder configuration
+ * @returns CBOR hex string
+ *
+ * @example
+ * ```typescript
+ * encodeToHex(100)  // "1864"
+ * encodeToHex([1, 2, 3])  // "83010203"
+ * encodeToHex({ a: 1 }, { canonical: true })  // "a16161 01"
+ * ```
+ */
+declare function encodeToHex(value: EncodableValue, options?: Partial<EncodeOptions>): string;
+/**
+ * Encode JavaScript value to CBOR bytes
+ *
+ * Convenience function that returns only the bytes (not the hex string).
+ *
+ * @param value - JavaScript value to encode
+ * @param options - Optional encoder configuration
+ * @returns CBOR bytes as Uint8Array
+ *
+ * @example
+ * ```typescript
+ * const bytes = encodeToBytes(100)  // Uint8Array[0x18, 0x64]
+ * const bytes = encodeToBytes([1, 2, 3])  // Uint8Array[0x83, 0x01, 0x02, 0x03]
+ * ```
+ */
+declare function encodeToBytes(value: EncodableValue, options?: Partial<EncodeOptions>): Uint8Array;
+/**
+ * Encode multiple values as CBOR sequence
+ *
+ * Creates a CBOR sequence (RFC 8742) by concatenating multiple encoded values.
+ * Useful for streaming or batch encoding.
+ *
+ * @param values - Array of values to encode
+ * @param options - Optional encoder configuration
+ * @returns Concatenated CBOR bytes and hex string
+ *
+ * @example
+ * ```typescript
+ * encodeSequence([1, "hello", [2, 3]])
+ * // Returns concatenated encoding: 0x01 + 0x6568656c6c6f + 0x820203
+ * ```
+ *
+ * @see {@link https://datatracker.ietf.org/doc/html/rfc8742 | RFC 8742 - CBOR Sequences}
+ */
+declare function encodeSequence(values: EncodableValue[], options?: Partial<EncodeOptions>): EncodeResult;
+/**
+ * Class-based CBOR decoder
+ *
+ * Provides an object-oriented interface for CBOR decoding.
+ * Useful when you need to maintain decoder state or configuration.
+ *
+ * @example
+ * ```typescript
+ * const decoder = new CborDecoder({ strict: true })
+ *
+ * const result1 = decoder.decode('1864')
+ * const result2 = decoder.decode('6449455446')
+ *
+ * const withMap = decoder.decodeWithSourceMap('d87980')
+ * ```
+ */
+declare class CborDecoder {
+    private options;
+    /**
+     * Create a new CBOR decoder
+     *
+     * @param options - Parser configuration
+     */
+    constructor(options?: ParseOptions);
+    /**
+     * Decode CBOR hex string
+     *
+     * @param hexString - CBOR data as hex string
+     * @returns Decoded value and byte count
+     */
+    decode(hexString: string): ParseResult;
+    /**
+     * Decode CBOR hex string with source map
+     *
+     * @param hexString - CBOR data as hex string
+     * @returns Decoded value, byte count, and source map
+     */
+    decodeWithSourceMap(hexString: string): ParseResultWithMap;
+}
+/**
+ * Class-based CBOR encoder
+ *
+ * Provides an object-oriented interface for CBOR encoding.
+ * Useful when you need to maintain encoder state or configuration.
+ *
+ * @example
+ * ```typescript
+ * const encoder = new CborEncoder({ canonical: true })
+ *
+ * const result1 = encoder.encode(100)
+ * const result2 = encoder.encode([1, 2, 3])
+ *
+ * const hex = encoder.encodeToHex({ a: 1 })  // Keys will be sorted
+ * ```
+ */
+declare class CborEncoder {
+    private options;
+    /**
+     * Create a new CBOR encoder
+     *
+     * @param options - Encoder configuration
+     */
+    constructor(options?: Partial<EncodeOptions>);
+    /**
+     * Encode value to CBOR
+     *
+     * @param value - JavaScript value to encode
+     * @returns CBOR bytes and hex string
+     */
+    encode(value: EncodableValue): EncodeResult;
+    /**
+     * Encode value to CBOR hex string
+     *
+     * @param value - JavaScript value to encode
+     * @returns CBOR hex string
+     */
+    encodeToHex(value: EncodableValue): string;
+    /**
+     * Encode value to CBOR bytes
+     *
+     * @param value - JavaScript value to encode
+     * @returns CBOR bytes
+     */
+    encodeToBytes(value: EncodableValue): Uint8Array;
+    /**
+     * Encode multiple values as CBOR sequence
+     *
+     * @param values - Array of values to encode
+     * @returns Concatenated CBOR encoding
+     */
+    encodeSequence(values: EncodableValue[]): EncodeResult;
+}
+
+/**
+ * Convert a JavaScript value to RFC 8949 diagnostic notation
+ *
+ * Diagnostic notation is a human-readable representation of CBOR data
+ * as defined in RFC 8949 Appendix B.
+ *
+ * @param value - JavaScript value to convert
+ * @param options - Optional formatting options
+ * @returns Diagnostic notation string
+ *
+ * @example
+ * ```typescript
+ * toDiagnostic(100)                    // "100"
+ * toDiagnostic(new Uint8Array([1,2]))  // "h'0102'"
+ * toDiagnostic([1, 2, 3])              // "[1, 2, 3]"
+ * toDiagnostic({a: 1})                 // '{"a": 1}'
+ * toDiagnostic({tag: 1, value: 123})   // "1(123)"
+ *
+ * // Pretty print
+ * toDiagnostic([1, 2], { pretty: true })
+ * // "[\n  1,\n  2\n]"
+ *
+ * // Indefinite length
+ * toDiagnostic([1, 2], { indefinite: true })
+ * // "[_ 1, 2]"
+ * ```
+ */
+declare function toDiagnostic(value: unknown, options?: DiagnosticOptions): string;
+/**
+ * Decode CBOR and return diagnostic notation
+ *
+ * Combines decoding and diagnostic conversion in one step.
+ *
+ * @param hexString - CBOR data as hex string
+ * @param options - Optional formatting options
+ * @returns Diagnostic notation string
+ *
+ * @example
+ * ```typescript
+ * decodeToDiagnostic('1864')           // "100"
+ * decodeToDiagnostic('83010203')       // "[1, 2, 3]"
+ * decodeToDiagnostic('d87980')         // "121([])"
+ * ```
+ */
+declare function decodeToDiagnostic(hexString: string, options?: DiagnosticOptions): string;
+
+export { CborDecoder, CborEncoder, type DiagnosticOptions, EncodableValue, EncodeOptions, EncodeResult, ParseOptions, ParseResult, ParseResultWithMap, PathBuilder, decode, decodeToDiagnostic, decodeWithSourceMap, encode, encodeSequence, encodeToBytes, encodeToHex, toDiagnostic, useCborDiagnostic };