@k67/kaitai-struct-ts 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,962 @@
+/**
+ * @fileoverview Binary stream reader for Kaitai Struct
+ * @module stream/KaitaiStream
+ * @author Fabiano Pinto
+ * @license MIT
+ */
+/**
+ * KaitaiStream provides methods for reading binary data with proper type handling
+ * and endianness support. It's the core class for parsing binary formats.
+ *
+ * Supports reading:
+ * - Unsigned integers (u1, u2, u4, u8) in both little and big endian
+ * - Signed integers (s1, s2, s4, s8) in both little and big endian
+ * - Floating point numbers (f4, f8) in both little and big endian
+ * - Byte arrays (fixed length, until terminator, or all remaining)
+ * - Strings with various encodings
+ * - Bit-level data
+ *
+ * @class KaitaiStream
+ * @example
+ * ```typescript
+ * const buffer = new Uint8Array([0x01, 0x02, 0x03, 0x04])
+ * const stream = new KaitaiStream(buffer)
+ *
+ * const byte = stream.readU1()           // Read 1 byte
+ * const word = stream.readU2le()         // Read 2 bytes little-endian
+ * const str = stream.readStr(5, 'UTF-8') // Read 5-byte string
+ * ```
+ */
+declare class KaitaiStream {
+    private buffer;
+    private view;
+    private _pos;
+    private _bits;
+    private _bitsLeft;
+    /**
+     * Create a new KaitaiStream from a buffer
+     * @param buffer - ArrayBuffer or Uint8Array containing the binary data
+     */
+    constructor(buffer: ArrayBuffer | Uint8Array);
+    /**
+     * Current position in the stream
+     */
+    get pos(): number;
+    set pos(value: number);
+    /**
+     * Total size of the stream in bytes
+     */
+    get size(): number;
+    /**
+     * Check if we've reached the end of the stream
+     */
+    isEof(): boolean;
+    /**
+     * Seek to a specific position in the stream
+     * @param pos - Position to seek to
+     */
+    seek(pos: number): void;
+    /**
+     * Ensure we have enough bytes available
+     * @param count - Number of bytes needed
+     */
+    private ensureBytes;
+    /**
+     * Read 1-byte unsigned integer (0 to 255)
+     */
+    readU1(): number;
+    /**
+     * Read 2-byte unsigned integer, little-endian
+     */
+    readU2le(): number;
+    /**
+     * Read 2-byte unsigned integer, big-endian
+     */
+    readU2be(): number;
+    /**
+     * Read 4-byte unsigned integer, little-endian
+     */
+    readU4le(): number;
+    /**
+     * Read 4-byte unsigned integer, big-endian
+     */
+    readU4be(): number;
+    /**
+     * Read 8-byte unsigned integer, little-endian
+     * Returns BigInt for values > Number.MAX_SAFE_INTEGER
+     */
+    readU8le(): bigint;
+    /**
+     * Read 8-byte unsigned integer, big-endian
+     * Returns BigInt for values > Number.MAX_SAFE_INTEGER
+     */
+    readU8be(): bigint;
+    /**
+     * Read 1-byte signed integer (-128 to 127)
+     */
+    readS1(): number;
+    /**
+     * Read 2-byte signed integer, little-endian
+     */
+    readS2le(): number;
+    /**
+     * Read 2-byte signed integer, big-endian
+     */
+    readS2be(): number;
+    /**
+     * Read 4-byte signed integer, little-endian
+     */
+    readS4le(): number;
+    /**
+     * Read 4-byte signed integer, big-endian
+     */
+    readS4be(): number;
+    /**
+     * Read 8-byte signed integer, little-endian
+     * Returns BigInt for values outside Number.MAX_SAFE_INTEGER range
+     */
+    readS8le(): bigint;
+    /**
+     * Read 8-byte signed integer, big-endian
+     * Returns BigInt for values outside Number.MAX_SAFE_INTEGER range
+     */
+    readS8be(): bigint;
+    /**
+     * Read 4-byte IEEE 754 single-precision float, little-endian
+     */
+    readF4le(): number;
+    /**
+     * Read 4-byte IEEE 754 single-precision float, big-endian
+     */
+    readF4be(): number;
+    /**
+     * Read 8-byte IEEE 754 double-precision float, little-endian
+     */
+    readF8le(): number;
+    /**
+     * Read 8-byte IEEE 754 double-precision float, big-endian
+     */
+    readF8be(): number;
+    /**
+     * Read a fixed number of bytes
+     * @param length - Number of bytes to read
+     */
+    readBytes(length: number): Uint8Array;
+    /**
+     * Read all remaining bytes until end of stream
+     */
+    readBytesFull(): Uint8Array;
+    /**
+     * Read bytes until a terminator byte is found
+     * @param term - Terminator byte value
+     * @param include - Include terminator in result
+     * @param consume - Consume terminator from stream
+     * @param eosError - Throw error if EOS reached before terminator
+     */
+    readBytesterm(term: number, include?: boolean, consume?: boolean, eosError?: boolean): Uint8Array;
+    /**
+     * Read a fixed-length string
+     * @param length - Number of bytes to read
+     * @param encoding - Character encoding (default: UTF-8)
+     */
+    readStr(length: number, encoding?: string): string;
+    /**
+     * Read a null-terminated string
+     * @param encoding - Character encoding (default: UTF-8)
+     * @param term - Terminator byte (default: 0)
+     * @param include - Include terminator in result
+     * @param consume - Consume terminator from stream
+     * @param eosError - Throw error if EOS reached before terminator
+     */
+    readStrz(encoding?: string, term?: number, include?: boolean, consume?: boolean, eosError?: boolean): string;
+    /**
+     * Align bit reading to byte boundary
+     */
+    alignToByte(): void;
+    /**
+     * Read specified number of bits as unsigned integer (big-endian)
+     * @param n - Number of bits to read (1-64)
+     */
+    readBitsIntBe(n: number): bigint;
+    /**
+     * Read specified number of bits as unsigned integer (little-endian)
+     * @param n - Number of bits to read (1-64)
+     */
+    readBitsIntLe(n: number): bigint;
+    /**
+     * Get the underlying buffer
+     */
+    getBuffer(): Uint8Array;
+    /**
+     * Create a substream from current position with specified size
+     * @param size - Size of the substream in bytes
+     */
+    substream(size: number): KaitaiStream;
+}
+
+/**
+ * @fileoverview Type definitions for Kaitai Struct YAML schema (.ksy files)
+ * @module parser/schema
+ * @author Fabiano Pinto
+ * @license MIT
+ */
+/**
+ * Root schema definition for a Kaitai Struct format.
+ * Represents a complete .ksy file structure.
+ *
+ * @interface KsySchema
+ * @example
+ * ```typescript
+ * const schema: KsySchema = {
+ *   meta: {
+ *     id: 'my_format',
+ *     endian: 'le'
+ *   },
+ *   seq: [
+ *     { id: 'magic', contents: [0x4D, 0x5A] },
+ *     { id: 'version', type: 'u2' }
+ *   ]
+ * }
+ * ```
+ */
+interface KsySchema {
+    /** Metadata about the format */
+    meta: MetaSpec;
+    /** Sequential attributes (fields read in order) */
+    seq?: AttributeSpec[];
+    /** Named instances (lazy-evaluated fields) */
+    instances?: Record<string, InstanceSpec>;
+    /** Nested type definitions */
+    types?: Record<string, KsySchema>;
+    /** Enum definitions (named integer constants) */
+    enums?: Record<string, EnumSpec>;
+    /** Documentation for this type */
+    doc?: string;
+    /** Reference to documentation */
+    'doc-ref'?: string | string[];
+    /** Parameters for parametric types */
+    params?: ParamSpec[];
+}
+/**
+ * Metadata section of a Kaitai Struct schema.
+ * Contains information about the format itself.
+ *
+ * @interface MetaSpec
+ */
+interface MetaSpec {
+    /** Identifier for this format (required) */
+    id: string;
+    /** Title/name of the format */
+    title?: string;
+    /** Application that uses this format */
+    application?: string | string[];
+    /** File extension(s) for this format */
+    'file-extension'?: string | string[];
+    /** MIME type(s) for this format */
+    xref?: Record<string, string | string[]>;
+    /** License for the format specification */
+    license?: string;
+    /** KS compatibility version */
+    'ks-version'?: string | number;
+    /** Debug mode flag */
+    'ks-debug'?: boolean;
+    /** Opaque types flag */
+    'ks-opaque-types'?: boolean;
+    /** Default endianness for the format */
+    endian?: Endianness | EndianExpression;
+    /** Default encoding for strings */
+    encoding?: string;
+    /** Imported type definitions */
+    imports?: string[];
+    /** Documentation */
+    doc?: string;
+    /** Reference to documentation */
+    'doc-ref'?: string | string[];
+}
+/**
+ * Endianness specification.
+ */
+type Endianness = 'le' | 'be';
+/**
+ * Expression-based endianness (switch on expression).
+ *
+ * @interface EndianExpression
+ */
+interface EndianExpression {
+    /** Expression to evaluate */
+    'switch-on': string;
+    /** Cases mapping values to endianness */
+    cases: Record<string, Endianness>;
+}
+/**
+ * Attribute specification for sequential fields.
+ * Describes how to read a single field from the stream.
+ *
+ * @interface AttributeSpec
+ */
+interface AttributeSpec {
+    /** Field identifier (name) */
+    id?: string;
+    /** Data type to read */
+    type?: string | SwitchType;
+    /** Size of the field (in bytes or expression) */
+    size?: number | string;
+    /** Size until specific byte value */
+    'size-eos'?: boolean;
+    /** Repeat specification */
+    repeat?: RepeatSpec;
+    /** Number of repetitions (for repeat: expr) */
+    'repeat-expr'?: string | number;
+    /** Condition for repetition (for repeat: until) */
+    'repeat-until'?: string;
+    /** Conditional parsing */
+    if?: string;
+    /** Expected contents (validation) */
+    contents?: number[] | string;
+    /** String encoding */
+    encoding?: string;
+    /** Pad right to alignment */
+    'pad-right'?: number;
+    /** Terminator byte for strings/arrays */
+    terminator?: number;
+    /** Include terminator in result */
+    include?: boolean;
+    /** Consume terminator from stream */
+    consume?: boolean;
+    /** Throw error if terminator not found */
+    'eos-error'?: boolean;
+    /** Enum type name */
+    enum?: string;
+    /** Absolute position to seek to */
+    pos?: number | string;
+    /** Custom I/O stream */
+    io?: string;
+    /** Processing directive (compression, encryption, etc.) */
+    process?: string | ProcessSpec;
+    /** Documentation */
+    doc?: string;
+    /** Reference to documentation */
+    'doc-ref'?: string | string[];
+    /** Original field ID (for reference) */
+    '-orig-id'?: string;
+}
+/**
+ * Instance specification for lazy-evaluated fields.
+ * Similar to AttributeSpec but for instances section.
+ *
+ * @interface InstanceSpec
+ */
+interface InstanceSpec extends Omit<AttributeSpec, 'id'> {
+    /** Value instance (calculated field) */
+    value?: string | number | boolean;
+    /** Position in stream (for pos instances) */
+    pos?: number | string;
+    /** Custom I/O stream */
+    io?: string;
+}
+/**
+ * Repeat specification types.
+ */
+type RepeatSpec = 'expr' | 'eos' | 'until';
+/**
+ * Switch-based type selection.
+ * Allows different types based on an expression value.
+ *
+ * @interface SwitchType
+ */
+interface SwitchType {
+    /** Expression to evaluate for switching */
+    'switch-on': string;
+    /** Cases mapping values to types */
+    cases: Record<string, string>;
+    /** Default type if no case matches */
+    default?: string;
+}
+/**
+ * Processing specification for data transformation.
+ *
+ * @type ProcessSpec
+ */
+type ProcessSpec = string | ProcessObject;
+/**
+ * Processing object with algorithm and parameters.
+ *
+ * @interface ProcessObject
+ */
+interface ProcessObject {
+    /** Processing algorithm */
+    algorithm: string;
+    /** Algorithm parameters */
+    [key: string]: unknown;
+}
+/**
+ * Enum specification (named integer constants).
+ *
+ * @type EnumSpec
+ */
+type EnumSpec = Record<string | number, string | number>;
+/**
+ * Parameter specification for parametric types.
+ *
+ * @interface ParamSpec
+ */
+interface ParamSpec {
+    /** Parameter identifier */
+    id: string;
+    /** Parameter type */
+    type?: string;
+    /** Documentation */
+    doc?: string;
+    /** Reference to documentation */
+    'doc-ref'?: string | string[];
+}
+/**
+ * Validation result for schema validation.
+ *
+ * @interface ValidationResult
+ */
+interface ValidationResult {
+    /** Whether the schema is valid */
+    valid: boolean;
+    /** Validation errors */
+    errors: ValidationError$1[];
+    /** Validation warnings */
+    warnings: ValidationWarning[];
+}
+/**
+ * Validation error.
+ *
+ * @interface ValidationError
+ */
+interface ValidationError$1 {
+    /** Error message */
+    message: string;
+    /** Path to the error in the schema */
+    path: string[];
+    /** Error code */
+    code: string;
+}
+/**
+ * Validation warning.
+ *
+ * @interface ValidationWarning
+ */
+interface ValidationWarning {
+    /** Warning message */
+    message: string;
+    /** Path to the warning in the schema */
+    path: string[];
+    /** Warning code */
+    code: string;
+}
+/**
+ * Built-in Kaitai Struct types.
+ */
+declare const BUILTIN_TYPES: readonly ["u1", "u2", "u2le", "u2be", "u4", "u4le", "u4be", "u8", "u8le", "u8be", "s1", "s2", "s2le", "s2be", "s4", "s4le", "s4be", "s8", "s8le", "s8be", "f4", "f4le", "f4be", "f8", "f8le", "f8be", "str", "strz"];
+/**
+ * Type guard to check if a type is a built-in type.
+ *
+ * @param type - Type name to check
+ * @returns True if the type is built-in
+ */
+declare function isBuiltinType(type: string): boolean;
+/**
+ * Get the default endianness for a type.
+ * Returns the endianness suffix if present, otherwise undefined.
+ *
+ * @param type - Type name
+ * @returns Endianness ('le', 'be', or undefined for default)
+ */
+declare function getTypeEndianness(type: string): Endianness | undefined;
+/**
+ * Get the base type without endianness suffix.
+ *
+ * @param type - Type name
+ * @returns Base type name
+ * @example
+ * ```typescript
+ * getBaseType('u4le') // returns 'u4'
+ * getBaseType('s2be') // returns 's2'
+ * getBaseType('str')  // returns 'str'
+ * ```
+ */
+declare function getBaseType(type: string): string;
+/**
+ * Check if a type is an integer type.
+ *
+ * @param type - Type name
+ * @returns True if the type is an integer
+ */
+declare function isIntegerType(type: string): boolean;
+/**
+ * Check if a type is a floating point type.
+ *
+ * @param type - Type name
+ * @returns True if the type is a float
+ */
+declare function isFloatType(type: string): boolean;
+/**
+ * Check if a type is a string type.
+ *
+ * @param type - Type name
+ * @returns True if the type is a string
+ */
+declare function isStringType(type: string): boolean;
+
+/**
+ * @fileoverview Parser for Kaitai Struct YAML (.ksy) files
+ * @module parser/KsyParser
+ * @author Fabiano Pinto
+ * @license MIT
+ */
+
+/**
+ * Parser for Kaitai Struct YAML (.ksy) format definitions.
+ * Converts YAML text into typed schema objects and validates them.
+ *
+ * @class KsyParser
+ * @example
+ * ```typescript
+ * const parser = new KsyParser()
+ * const schema = parser.parse(ksyYamlString)
+ * ```
+ */
+declare class KsyParser {
+    /**
+     * Parse a .ksy YAML string into a typed schema object.
+     *
+     * @param yaml - YAML string containing the .ksy definition
+     * @param options - Parsing options
+     * @returns Parsed and validated schema
+     * @throws {ParseError} If YAML parsing fails
+     * @throws {ValidationError} If schema validation fails
+     */
+    parse(yaml: string, options?: ParseOptions$1): KsySchema;
+    /**
+     * Validate a schema object.
+     *
+     * @param schema - Schema to validate
+     * @param options - Validation options
+     * @returns Validation result with errors and warnings
+     */
+    validate(schema: KsySchema, options?: ValidationOptions): ValidationResult;
+    /**
+     * Validate an attribute specification.
+     *
+     * @param attr - Attribute to validate
+     * @param path - Path to this attribute in the schema
+     * @param errors - Array to collect errors
+     * @param warnings - Array to collect warnings
+     * @param strict - Whether to be strict about warnings
+     * @private
+     */
+    private validateAttribute;
+    /**
+     * Parse multiple .ksy files and resolve imports.
+     *
+     * @param mainYaml - Main .ksy file content
+     * @param imports - Map of import names to their YAML content
+     * @param options - Parsing options
+     * @returns Parsed schema with resolved imports
+     */
+    parseWithImports(mainYaml: string, _imports: Map<string, string>, options?: ParseOptions$1): KsySchema;
+}
+/**
+ * Options for parsing .ksy files.
+ *
+ * @interface ParseOptions
+ */
+interface ParseOptions$1 {
+    /** Whether to validate the schema (default: true) */
+    validate?: boolean;
+    /** Whether to treat warnings as errors (default: false) */
+    strict?: boolean;
+}
+/**
+ * Options for schema validation.
+ *
+ * @interface ValidationOptions
+ */
+interface ValidationOptions {
+    /** Whether to treat warnings as errors (default: false) */
+    strict?: boolean;
+    /** Whether this is a nested type (meta section optional) (default: false) */
+    isNested?: boolean;
+}
+
+/**
+ * @fileoverview Execution context for Kaitai Struct parsing
+ * @module interpreter/Context
+ * @author Fabiano Pinto
+ * @license MIT
+ */
+
+/**
+ * Execution context for parsing operations.
+ * Provides access to the current object, parent, root, and stream.
+ *
+ * @class Context
+ * @example
+ * ```typescript
+ * const context = new Context(stream, root)
+ * context.pushParent(currentObject)
+ * const value = evaluator.evaluate(expression, context)
+ * context.popParent()
+ * ```
+ */
+declare class Context {
+    private _io;
+    private _root;
+    /** Stack of parent objects */
+    private parentStack;
+    /** Current object being parsed */
+    private _current;
+    /**
+     * Create a new execution context.
+     *
+     * @param _io - Binary stream being read
+     * @param _root - Root object of the parse tree
+     * @param _parent - Parent object (optional)
+     */
+    constructor(_io: KaitaiStream, _root?: unknown, _parent?: unknown);
+    /**
+     * Get the current I/O stream.
+     * Accessible in expressions as `_io`.
+     *
+     * @returns Current stream
+     */
+    get io(): KaitaiStream;
+    /**
+     * Get the root object.
+     * Accessible in expressions as `_root`.
+     *
+     * @returns Root object
+     */
+    get root(): unknown;
+    /**
+     * Get the parent object.
+     * Accessible in expressions as `_parent`.
+     *
+     * @returns Parent object or null if at root
+     */
+    get parent(): unknown;
+    /**
+     * Get the current object being parsed.
+     * Used to access fields defined earlier in the sequence.
+     *
+     * @returns Current object
+     */
+    get current(): Record<string, unknown>;
+    /**
+     * Set the current object.
+     *
+     * @param obj - Object to set as current
+     */
+    set current(obj: Record<string, unknown>);
+    /**
+     * Push a new parent onto the stack.
+     * Used when entering a nested type.
+     *
+     * @param parent - Parent object to push
+     */
+    pushParent(parent: unknown): void;
+    /**
+     * Pop the current parent from the stack.
+     * Used when exiting a nested type.
+     *
+     * @returns The popped parent object
+     */
+    popParent(): unknown;
+    /**
+     * Get a value from the context by path.
+     * Supports special names: _io, _root, _parent, _index.
+     *
+     * @param name - Name or path to resolve
+     * @returns Resolved value
+     */
+    resolve(name: string): unknown;
+    /**
+     * Set a value in the current object.
+     *
+     * @param name - Field name
+     * @param value - Value to set
+     */
+    set(name: string, value: unknown): void;
+    /**
+     * Create a child context for nested parsing.
+     * The current object becomes the parent in the child context.
+     *
+     * @param stream - Stream for the child context (defaults to current stream)
+     * @returns New child context
+     */
+    createChild(stream?: KaitaiStream): Context;
+    /**
+     * Clone this context.
+     * Creates a shallow copy with the same stream, root, and parent.
+     *
+     * @returns Cloned context
+     */
+    clone(): Context;
+}
+
+/**
+ * @fileoverview Type interpreter for executing Kaitai Struct schemas
+ * @module interpreter/TypeInterpreter
+ * @author Fabiano Pinto
+ * @license MIT
+ */
+
+/**
+ * Interprets Kaitai Struct schemas and parses binary data.
+ * Executes schema definitions against binary streams to produce structured objects.
+ *
+ * @class TypeInterpreter
+ * @example
+ * ```typescript
+ * const interpreter = new TypeInterpreter(schema)
+ * const stream = new KaitaiStream(buffer)
+ * const result = interpreter.parse(stream)
+ * ```
+ */
+declare class TypeInterpreter {
+    private schema;
+    private parentMeta?;
+    /**
+     * Create a new type interpreter.
+     *
+     * @param schema - Kaitai Struct schema to interpret
+     * @param parentMeta - Parent schema's meta (for nested types)
+     */
+    constructor(schema: KsySchema, parentMeta?: {
+        id: string;
+        endian?: Endianness | object;
+        encoding?: string;
+    } | undefined);
+    /**
+     * Parse binary data according to the schema.
+     *
+     * @param stream - Binary stream to parse
+     * @param parent - Parent object (for nested types)
+     * @returns Parsed object
+     */
+    parse(stream: KaitaiStream, parent?: unknown): Record<string, unknown>;
+    /**
+     * Parse a single attribute according to its specification.
+     *
+     * @param attr - Attribute specification
+     * @param context - Execution context
+     * @returns Parsed value
+     * @private
+     */
+    private parseAttribute;
+    /**
+     * Parse a repeated attribute.
+     *
+     * @param attr - Attribute specification with repeat
+     * @param context - Execution context
+     * @returns Array of parsed values
+     * @private
+     */
+    private parseRepeated;
+    /**
+     * Parse and validate contents.
+     *
+     * @param attr - Attribute specification with contents
+     * @param context - Execution context
+     * @returns The validated contents
+     * @private
+     */
+    private parseContents;
+    /**
+     * Parse a single value according to its type.
+     *
+     * @param attr - Attribute specification
+     * @param context - Execution context
+     * @returns Parsed value
+     * @private
+     */
+    private parseValue;
+    /**
+     * Parse a value of a specific type.
+     *
+     * @param type - Type name or switch specification
+     * @param stream - Stream to read from
+     * @param context - Execution context
+     * @returns Parsed value
+     * @private
+     */
+    private parseType;
+    /**
+     * Parse a built-in type.
+     *
+     * @param type - Built-in type name
+     * @param stream - Stream to read from
+     * @param context - Execution context
+     * @returns Parsed value
+     * @private
+     */
+    private parseBuiltinType;
+    /**
+     * Read an integer value.
+     *
+     * @param type - Integer type (u1, u2, u4, u8, s1, s2, s4, s8)
+     * @param endian - Endianness
+     * @param stream - Stream to read from
+     * @returns Integer value
+     * @private
+     */
+    private readInteger;
+    /**
+     * Read a floating point value.
+     *
+     * @param type - Float type (f4, f8)
+     * @param endian - Endianness
+     * @param stream - Stream to read from
+     * @returns Float value
+     * @private
+     */
+    private readFloat;
+}
+
+/**
+ * @fileoverview Custom error classes for Kaitai Struct parsing and validation
+ * @module utils/errors
+ * @author Fabiano Pinto
+ * @license MIT
+ */
+/**
+ * Base error class for all Kaitai Struct errors.
+ * All custom errors in this library extend from this class.
+ *
+ * @class KaitaiError
+ * @extends Error
+ * @example
+ * ```typescript
+ * throw new KaitaiError('Something went wrong', 42)
+ * ```
+ */
+declare class KaitaiError extends Error {
+    position?: number | undefined;
+    constructor(message: string, position?: number | undefined);
+}
+/**
+ * Error thrown when validation fails.
+ * Used when parsed data doesn't match expected constraints.
+ *
+ * @class ValidationError
+ * @extends KaitaiError
+ * @example
+ * ```typescript
+ * throw new ValidationError('Magic bytes mismatch', 0)
+ * ```
+ */
+declare class ValidationError extends KaitaiError {
+    constructor(message: string, position?: number);
+}
+/**
+ * Error thrown when parsing fails.
+ * Used for general parsing errors that don't fit other categories.
+ *
+ * @class ParseError
+ * @extends KaitaiError
+ * @example
+ * ```typescript
+ * throw new ParseError('Invalid format structure', 100)
+ * ```
+ */
+declare class ParseError extends KaitaiError {
+    constructor(message: string, position?: number);
+}
+/**
+ * Error thrown when end of stream is reached unexpectedly.
+ * Indicates an attempt to read beyond available data.
+ *
+ * @class EOFError
+ * @extends KaitaiError
+ * @example
+ * ```typescript
+ * throw new EOFError('Unexpected end of stream', 1024)
+ * ```
+ */
+declare class EOFError extends KaitaiError {
+    constructor(message?: string, position?: number);
+}
+/**
+ * Error thrown when a required feature is not yet implemented.
+ * Used during development to mark incomplete functionality.
+ *
+ * @class NotImplementedError
+ * @extends KaitaiError
+ * @example
+ * ```typescript
+ * throw new NotImplementedError('Custom processing')
+ * ```
+ */
+declare class NotImplementedError extends KaitaiError {
+    constructor(feature: string);
+}
+
+/**
+ * @fileoverview Main entry point for kaitai-struct-ts library
+ * @module kaitai-struct-ts
+ * @author Fabiano Pinto
+ * @license MIT
+ * @version 0.2.0
+ *
+ * @description
+ * A runtime interpreter for Kaitai Struct binary format definitions in TypeScript.
+ * Parse any binary data format by providing a .ksy (Kaitai Struct YAML) definition file.
+ *
+ * @example
+ * ```typescript
+ * import { parse } from 'kaitai-struct-ts'
+ *
+ * const ksyDefinition = `
+ * meta:
+ *   id: my_format
+ *   endian: le
+ * seq:
+ *   - id: magic
+ *     contents: [0x4D, 0x5A]
+ *   - id: version
+ *     type: u2
+ * `
+ *
+ * const buffer = new Uint8Array([0x4D, 0x5A, 0x01, 0x00])
+ * const result = parse(ksyDefinition, buffer)
+ * console.log(result.version) // 1
+ * ```
+ */
+
+/**
+ * Parse binary data using a Kaitai Struct definition.
+ * This is the main convenience function for parsing.
+ *
+ * @param ksyYaml - YAML string containing the .ksy definition
+ * @param buffer - Binary data to parse (ArrayBuffer or Uint8Array)
+ * @param options - Parsing options
+ * @returns Parsed object with fields defined in the .ksy file
+ * @throws {ParseError} If YAML parsing fails
+ * @throws {ValidationError} If schema validation fails
+ * @throws {EOFError} If unexpected end of stream is reached
+ *
+ * @example
+ * ```typescript
+ * const result = parse(ksyYaml, binaryData)
+ * console.log(result.fieldName)
+ * ```
+ */
+declare function parse(ksyYaml: string, buffer: ArrayBuffer | Uint8Array, options?: ParseOptions): Record<string, unknown>;
+/**
+ * Options for the parse function.
+ *
+ * @interface ParseOptions
+ */
+interface ParseOptions {
+    /** Whether to validate the schema (default: true) */
+    validate?: boolean;
+    /** Whether to treat warnings as errors (default: false) */
+    strict?: boolean;
+}
+
+export { type AttributeSpec, BUILTIN_TYPES, Context, EOFError, type EndianExpression, type Endianness, type EnumSpec, type InstanceSpec, KaitaiError, KaitaiStream, KsyParser, type KsySchema, type MetaSpec, NotImplementedError, type ParamSpec, ParseError, type ParseOptions, type ProcessObject, type ProcessSpec, type RepeatSpec, type ValidationError$1 as SchemaValidationError, type SwitchType, TypeInterpreter, ValidationError, type ValidationResult, type ValidationWarning, getBaseType, getTypeEndianness, isBuiltinType, isFloatType, isIntegerType, isStringType, parse };