@marcuspuchalla/nachos 0.1.0

package/dist/types-DvNlfbKB.d.ts

@@ -0,0 +1,301 @@
+/**
+ * CBOR Parser Type Definitions
+ * Following RFC 8949 specification
+ */
+/**
+ * Parser resource limits for DoS protection
+ */
+interface ParserLimits {
+    /** Maximum input size in bytes (default: 10 MB) */
+    maxInputSize?: number;
+    /** Maximum output size in bytes (default: 100 MB) */
+    maxOutputSize?: number;
+    /** Maximum string length in bytes (default: 1 MB) */
+    maxStringLength?: number;
+    /** Maximum array length (default: 10,000) */
+    maxArrayLength?: number;
+    /** Maximum map size (default: 10,000) */
+    maxMapSize?: number;
+    /** Maximum nesting depth for arrays/maps (default: 100) */
+    maxDepth?: number;
+    /** Maximum tag nesting depth (default: 100) - Prevents RUSTSEC-2019-0025 */
+    maxTagDepth?: number;
+    /** Maximum bignum size in bytes for tags 2/3 (default: 1024 bytes = 8192 bits) - Prevents CVE-2020-28491 */
+    maxBignumBytes?: number;
+    /** Maximum parse time in milliseconds (default: 1000) */
+    maxParseTime?: number;
+}
+/**
+ * Duplicate map key handling modes
+ * Following RFC 8949 Section 5.6 guidance
+ */
+type DupMapKeyMode = 'allow' | 'warn' | 'reject';
+/**
+ * Parser options for controlling behavior
+ */
+interface ParseOptions {
+    /** Enable strict Cardano mode (all validations) */
+    strict?: boolean;
+    /** Validate canonical encoding (shortest form, sorted maps) */
+    validateCanonical?: boolean;
+    /** Allow indefinite-length encoding (false in strict mode) */
+    allowIndefinite?: boolean;
+    /**
+     * Duplicate map key handling (RFC 8949 Section 5.6)
+     * - 'allow': Allow duplicates (default, permissive)
+     * - 'warn': Warn on duplicates but continue parsing
+     * - 'reject': Throw error on duplicate keys (strict mode)
+     */
+    dupMapKeyMode?: DupMapKeyMode;
+    /** Validate UTF-8 strictly (reject overlongs) */
+    validateUtf8Strict?: boolean;
+    /** Validate set uniqueness (Tag 258 - reject duplicates) */
+    validateSetUniqueness?: boolean;
+    /** Validate semantic tag constraints (Tag 4, Tag 5 array structure) */
+    validateTagSemantics?: boolean;
+    /** Validate Plutus constructor semantics (Tags 102, 121-127, 1280-1400) */
+    validatePlutusSemantics?: boolean;
+    /** Resource limits */
+    limits?: ParserLimits;
+}
+/**
+ * Default resource limits for parser
+ */
+declare const DEFAULT_LIMITS: Required<ParserLimits>;
+/**
+ * Default parse options
+ */
+declare const DEFAULT_OPTIONS: Required<ParseOptions>;
+/**
+ * Parsing context that tracks state during CBOR decoding
+ */
+interface CborContext {
+    /** Raw byte buffer */
+    buffer: Uint8Array;
+    /** Current byte offset */
+    offset: number;
+    /** Source map entries for visualization */
+    sourceMap: SourceMapEntry[];
+    /** Current nesting depth for arrays/maps (for limit checking) */
+    currentDepth?: number;
+    /** Current tag nesting depth (for tag limit checking) */
+    currentTagDepth?: number;
+    /** Parse start time (for timeout checking) */
+    startTime?: number;
+    /** Bytes allocated (for output size tracking) */
+    bytesAllocated?: number;
+    /** Parser options */
+    options?: ParseOptions;
+}
+/**
+ * Result of parsing a CBOR value
+ */
+interface ParseResult {
+    /** Decoded CBOR value */
+    value: CborValue;
+    /** Number of bytes consumed */
+    bytesRead: number;
+}
+/**
+ * Parse result with source mapping information
+ */
+interface ParseResultWithMap extends ParseResult {
+    /** Source map for hex/JSON linking */
+    sourceMap: SourceMapEntry[];
+}
+/**
+ * Source map entry for bi-directional visualization
+ */
+interface SourceMapEntry {
+    /** JSON Pointer path (RFC 6901) */
+    path: string;
+    /** Starting byte offset */
+    start: number;
+    /** Ending byte offset (exclusive) */
+    end: number;
+    /** CBOR major type (0-7) */
+    majorType: number;
+    /** Human-readable type description */
+    type: string;
+    /** Parent entry path (for nested structures like tags) */
+    parent?: string;
+    /** Child entry paths (for container types) */
+    children?: string[];
+    /** Whether this entry represents a header (initial byte + length info) */
+    isHeader?: boolean;
+    /** Whether this entry represents content (payload data) */
+    isContent?: boolean;
+    /** Byte offset where header ends and content begins */
+    headerEnd?: number;
+    /** JSON Pointer path to the content portion (for split header/content entries) */
+    contentPath?: string;
+}
+/**
+ * CBOR byte string (can be definite or indefinite length)
+ */
+interface CborByteString {
+    readonly type: 'cbor-byte-string';
+    readonly bytes: Uint8Array;
+    readonly chunks?: Uint8Array[];
+    [INDEFINITE_SYMBOL]?: boolean;
+}
+/**
+ * CBOR text string (can be definite or indefinite length)
+ */
+interface CborTextString {
+    readonly type: 'cbor-text-string';
+    readonly text: string;
+    readonly chunks?: string[];
+    [INDEFINITE_SYMBOL]?: boolean;
+}
+/**
+ * All possible CBOR values
+ */
+type CborValue = number | bigint | string | boolean | null | undefined | Uint8Array | CborByteString | CborTextString | CborValue[] | CborMap | TaggedValue | SimpleValue;
+/**
+ * Symbol to mark arrays/maps as indefinite-length encoded
+ * This allows round-trip preservation of encoding style
+ */
+declare const INDEFINITE_SYMBOL: unique symbol;
+/**
+ * CBOR map type (Map with any CBOR value as keys)
+ *
+ * Uses JavaScript Map to preserve key types (integers, Uint8Arrays, etc.)
+ * This is essential for:
+ * - Cardano transactions (use integer keys 0-18)
+ * - Round-trip encoding (must preserve exact key types)
+ * - CBOR specification compliance (maps can have any type as keys)
+ *
+ * @example
+ * ```typescript
+ * // Cardano transaction body
+ * new Map([
+ *   [0, inputs],      // Integer key
+ *   [1, outputs],     // Integer key
+ *   [2, 1000000]      // Integer key (fee)
+ * ])
+ * ```
+ */
+type CborMap = Map<CborValue, CborValue> & {
+    [INDEFINITE_SYMBOL]?: boolean;
+};
+/**
+ * Tagged CBOR value (Major Type 6)
+ */
+interface TaggedValue {
+    tag: number;
+    value: CborValue;
+    plutus?: PlutusConstr;
+}
+/**
+ * Simple CBOR value (Major Type 7, unassigned simple values)
+ */
+interface SimpleValue {
+    simpleValue: number;
+}
+/**
+ * Plutus Data types for Cardano smart contracts
+ */
+type PlutusData = PlutusConstr | PlutusMap | PlutusList | PlutusInt | PlutusBytes;
+/**
+ * Plutus Constructor (algebraic data type)
+ */
+interface PlutusConstr {
+    constructor: number;
+    fields: PlutusData[];
+}
+/**
+ * Plutus Map (key-value pairs)
+ */
+interface PlutusMap {
+    entries: Array<[PlutusData, PlutusData]>;
+}
+/**
+ * Plutus List (sequential collection)
+ */
+type PlutusList = PlutusData[];
+/**
+ * Plutus Integer (arbitrary precision)
+ */
+type PlutusInt = number | bigint;
+/**
+ * Plutus Bytes (bounded byte string, max 64 bytes)
+ */
+type PlutusBytes = Uint8Array;
+/**
+ * CBOR Major Types (0-7)
+ */
+declare enum CborMajorType {
+    UNSIGNED_INT = 0,
+    NEGATIVE_INT = 1,
+    BYTE_STRING = 2,
+    TEXT_STRING = 3,
+    ARRAY = 4,
+    MAP = 5,
+    TAG = 6,
+    SIMPLE = 7
+}
+/**
+ * Additional Information values
+ */
+declare enum CborAdditionalInfo {
+    DIRECT = 23,// Values 0-23
+    ONE_BYTE = 24,// 1 byte follows
+    TWO_BYTES = 25,// 2 bytes follow
+    FOUR_BYTES = 26,// 4 bytes follow
+    EIGHT_BYTES = 27,// 8 bytes follow
+    INDEFINITE = 31
+}
+/**
+ * Simple values (Major Type 7)
+ */
+declare enum CborSimpleValue {
+    FALSE = 20,
+    TRUE = 21,
+    NULL = 22,
+    UNDEFINED = 23,
+    FLOAT16 = 25,
+    FLOAT32 = 26,
+    FLOAT64 = 27,
+    BREAK = 31
+}
+/**
+ * Common semantic tags
+ */
+declare enum CborTag {
+    DATE_TIME_STRING = 0,
+    EPOCH_DATE_TIME = 1,
+    POSITIVE_BIGNUM = 2,
+    NEGATIVE_BIGNUM = 3,
+    DECIMAL_FRACTION = 4,
+    BIGFLOAT = 5,
+    BASE64URL = 21,
+    BASE64 = 22,
+    BASE16 = 23,
+    CBOR_ENCODED = 24,
+    URI = 32,
+    BASE64URL_NO_PAD = 33,
+    BASE64_NO_PAD = 34,
+    REGEXP = 35,
+    MIME_MESSAGE = 36
+}
+/**
+ * Parse error types
+ */
+interface ParseError {
+    type: 'INVALID_HEX' | 'UNEXPECTED_EOF' | 'INVALID_CBOR' | 'UNSUPPORTED_TYPE';
+    message: string;
+    offset?: number;
+}
+/**
+ * Result type for operations that can fail
+ */
+type Result<T, E> = {
+    success: true;
+    value: T;
+} | {
+    success: false;
+    error: E;
+};
+
+export { type CborContext as C, DEFAULT_OPTIONS as D, type ParseOptions as P, type Result as R, type SourceMapEntry as S, type TaggedValue as T, type ParseResult as a, type ParseResultWithMap as b, type ParseError as c, type ParserLimits as d, type CborValue as e, type CborMap as f, type PlutusData as g, type PlutusConstr as h, type PlutusMap as i, type PlutusList as j, type PlutusInt as k, type PlutusBytes as l, DEFAULT_LIMITS as m, CborMajorType as n, CborAdditionalInfo as o, CborSimpleValue as p, CborTag as q, type DupMapKeyMode as r, type CborByteString as s, type CborTextString as t };

package/dist/useCborSimpleEncoder-ButVU988.d.cts

@@ -0,0 +1,268 @@
+import { h as PlutusConstr, s as CborByteString, t as CborTextString } from './types-DvNlfbKB.cjs';
+
+/**
+ * CBOR Encoder Type Definitions
+ * Following RFC 8949 specification
+ */
+
+/**
+ * Encoder options for controlling behavior
+ */
+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
+ */
+declare const DEFAULT_ENCODE_OPTIONS: Required<EncodeOptions>;
+/**
+ * Result of encoding operation
+ */
+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.)
+ */
+type EncodableValue = number | bigint | string | boolean | null | undefined | Uint8Array | EncodableValue[] | {
+    [key: string]: EncodableValue;
+} | Map<EncodableValue, EncodableValue> | TaggedValue;
+/**
+ * Tagged CBOR value (Major Type 6)
+ */
+interface TaggedValue {
+    tag: number;
+    value: EncodableValue;
+    plutus?: PlutusConstr;
+}
+/**
+ * Encoding context that tracks state during CBOR encoding
+ */
+interface EncodeContext {
+    /** Current nesting depth */
+    depth: number;
+    /** Bytes written so far */
+    bytesWritten: number;
+    /** Encoder options */
+    options: Required<EncodeOptions>;
+}
+
+/**
+ * Main CBOR Encoder Composable
+ * High-level API for encoding JavaScript values to CBOR
+ * Following RFC 8949 specification
+ */
+
+/**
+ * Main CBOR Encoder Composable
+ *
+ * Provides a unified interface for encoding any JavaScript value to CBOR.
+ * Automatically selects the appropriate encoder based on value type.
+ *
+ * @param options - Global encoder options
+ *
+ * @example
+ * ```ts
+ * const { encode } = useCborEncoder()
+ *
+ * // Encode various types
+ * encode(42)           // Integer
+ * encode("hello")      // Text string
+ * encode([1, 2, 3])    // Array
+ * encode({ a: 1 })     // Map
+ * encode(true)         // Boolean
+ * encode(3.14)         // Float
+ * encode(new Uint8Array([0xff]))  // Byte string
+ *
+ * // With options
+ * const { encode: encodeCanonical } = useCborEncoder({ canonical: true })
+ * encodeCanonical({ z: 1, a: 2 })  // Keys will be sorted
+ * ```
+ */
+declare function useCborEncoder(globalOptions?: Partial<EncodeOptions>): {
+    encode: (value: EncodableValue) => EncodeResult;
+    encodeToHex: (value: EncodableValue) => string;
+    encodeToBytes: (value: EncodableValue) => Uint8Array;
+    encodeSequence: (values: EncodableValue[]) => EncodeResult;
+};
+
+/**
+ * CBOR Integer Encoder Composable
+ * Handles Major Type 0 (Unsigned) and Major Type 1 (Negative)
+ * Following RFC 8949 specification
+ */
+
+/**
+ * CBOR Integer Encoder Composable
+ *
+ * Provides functions to encode integers to CBOR format:
+ * - Major Type 0: Unsigned integers (0 to 2^64-1)
+ * - Major Type 1: Negative integers (-1 to -2^64)
+ *
+ * @example
+ * ```ts
+ * const { encodeUnsignedInt, encodeNegativeInt, encodeInteger } = useCborIntegerEncoder()
+ *
+ * // Encode unsigned integer
+ * const result1 = encodeUnsignedInt(100)
+ * // result1: { bytes: Uint8Array([0x18, 0x64]), hex: '1864' }
+ *
+ * // Encode negative integer
+ * const result2 = encodeNegativeInt(-100)
+ * // result2: { bytes: Uint8Array([0x38, 0x63]), hex: '3863' }
+ *
+ * // Auto-detect integer type
+ * const result3 = encodeInteger(-100)
+ * // result3: { bytes: Uint8Array([0x38, 0x63]), hex: '3863' }
+ * ```
+ */
+declare function useCborIntegerEncoder(): {
+    encodeUnsignedInt: (value: number | bigint) => EncodeResult;
+    encodeNegativeInt: (value: number | bigint) => EncodeResult;
+    encodeInteger: (value: number | bigint) => EncodeResult;
+};
+
+/**
+ * CBOR String Encoder Composable
+ * Handles Major Type 2 (Byte Strings) and Major Type 3 (Text Strings)
+ * Following RFC 8949 specification
+ */
+
+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' }
+ * ```
+ */
+declare function useCborStringEncoder(globalOptions?: Partial<EncodeOptions>): {
+    encodeByteString: (data: Uint8Array | Uint8Array[] | CborByteString, encodeOptions?: StringEncodeOptions) => EncodeResult;
+    encodeByteStringIndefinite: (chunks: Uint8Array[]) => EncodeResult;
+    encodeTextString: (text: string | CborTextString, encodeOptions?: StringEncodeOptions) => EncodeResult;
+    encodeTextStringIndefinite: (chunks: string[]) => EncodeResult;
+};
+
+/**
+ * CBOR Collection Encoder Composable
+ * Handles Major Type 4 (Arrays) and Major Type 5 (Maps)
+ * Following RFC 8949 specification
+ */
+
+interface CollectionEncodeOptions {
+    indefinite?: boolean;
+}
+/**
+ * CBOR Collection Encoder Composable
+ *
+ * Provides functions to encode arrays and maps:
+ * - Major Type 4: Arrays
+ * - Major Type 5: Maps (objects or Map instances)
+ *
+ * Supports both definite-length and indefinite-length encoding.
+ * Handles canonical encoding with sorted map keys.
+ * Enforces depth and size limits.
+ *
+ * @param options - Global encoder options
+ *
+ * @example
+ * ```ts
+ * const { encodeArray, encodeMap } = useCborCollectionEncoder()
+ *
+ * // Encode array
+ * const arr = [1, 2, 3]
+ * const result1 = encodeArray(arr)
+ * // result1: { bytes: Uint8Array([0x83, 0x01, 0x02, 0x03]), hex: '83010203' }
+ *
+ * // Encode map
+ * const map = { amount: 1000000 }
+ * const result2 = encodeMap(map)
+ * // result2: { bytes: ..., hex: 'a166616d6f756e741a000f4240' }
+ * ```
+ */
+declare function useCborCollectionEncoder(globalOptions?: Partial<EncodeOptions>): {
+    encodeArray: (array: EncodableValue[], encodeOptions?: CollectionEncodeOptions) => EncodeResult;
+    encodeArrayIndefinite: (array: EncodableValue[]) => EncodeResult;
+    encodeMap: (map: Map<EncodableValue, EncodableValue> | {
+        [key: string]: EncodableValue;
+    }, encodeOptions?: CollectionEncodeOptions) => EncodeResult;
+    encodeMapIndefinite: (map: Map<EncodableValue, EncodableValue> | {
+        [key: string]: EncodableValue;
+    }) => EncodeResult;
+    setMainEncode: (encodeFn: (value: EncodableValue) => EncodeResult) => void;
+};
+
+/**
+ * CBOR Simple Values and Floats Encoder Composable
+ * Handles Major Type 7 (Floats and Simple Values)
+ * Following RFC 8949 specification
+ */
+
+/**
+ * CBOR Simple Values and Floats Encoder Composable
+ *
+ * Provides functions to encode:
+ * - Simple values: false, true, null, undefined
+ * - Floating-point numbers: float16, float32, float64
+ *
+ * @param options - Global encoder options
+ *
+ * @example
+ * ```ts
+ * const { encodeSimple, encodeFloat } = useCborSimpleEncoder()
+ *
+ * // Encode simple values
+ * const result1 = encodeSimple(true)
+ * // result1: { bytes: Uint8Array([0xf5]), hex: 'f5' }
+ *
+ * // Encode float
+ * const result2 = encodeFloat(1.1)
+ * // result2: { bytes: Uint8Array([0xfb, ...]), hex: 'fb...' }
+ * ```
+ */
+declare function useCborSimpleEncoder(_globalOptions?: Partial<EncodeOptions>): {
+    encodeSimple: (value: boolean | null | undefined) => EncodeResult;
+    encodeFloat: (value: number, precision?: 16 | 32 | 64) => EncodeResult;
+};
+
+export { DEFAULT_ENCODE_OPTIONS as D, type EncodableValue as E, type TaggedValue as T, type EncodeOptions as a, type EncodeResult as b, useCborIntegerEncoder as c, useCborStringEncoder as d, useCborCollectionEncoder as e, useCborSimpleEncoder as f, type EncodeContext as g, useCborEncoder as u };