@k67/kaitai-struct-ts 0.3.0 → 0.6.0

package/dist/index.d.ts

@@ -1,199 +1,3 @@
-/**
- * @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
@@ -299,6 +103,8 @@ interface AttributeSpec {
     id?: string;
     /** Data type to read */
     type?: string | SwitchType;
+    /** Arguments for parametric types */
+    'type-args'?: Array<string | number | boolean>;
     /** Size of the field (in bytes or expression) */
     size?: number | string;
     /** Size until specific byte value */
@@ -503,6 +309,203 @@ declare function isFloatType(type: string): boolean;
  */
 declare function isStringType(type: string): boolean;
 
+/**
+ * @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;
+    private _size;
+    /**
+     * 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 Parser for Kaitai Struct YAML (.ksy) files
  * @module parser/KsyParser
@@ -532,6 +535,22 @@ declare class KsyParser {
      * @throws {ValidationError} If schema validation fails
      */
     parse(yaml: string, options?: ParseOptions$1): KsySchema;
+    /**
+     * Process parametric type syntax in schema.
+     * Converts "type_name(arg1, arg2)" to structured format.
+     *
+     * @param schema - Schema to process
+     * @private
+     */
+    private processParametricTypes;
+    /**
+     * Parse parametric type syntax from a type string.
+     * Converts "type_name(arg1, arg2)" to type + type-args.
+     *
+     * @param attr - Attribute to process
+     * @private
+     */
+    private parseParametricType;
     /**
      * Validate a schema object.
      *
@@ -740,6 +759,8 @@ declare class Context {
 declare class TypeInterpreter {
     private schema;
     private parentMeta?;
+    private expressionCache;
+    private readonly MAX_CACHE_SIZE;
     /**
      * Create a new type interpreter.
      *
@@ -756,9 +777,30 @@ declare class TypeInterpreter {
      *
      * @param stream - Binary stream to parse
      * @param parent - Parent object (for nested types)
+     * @param typeArgs - Arguments for parametric types
      * @returns Parsed object
      */
-    parse(stream: KaitaiStream, parent?: unknown): Record<string, unknown>;
+    parse(stream: KaitaiStream, parent?: unknown, typeArgs?: Array<string | number | boolean>): Record<string, unknown>;
+    /**
+     * Set up lazy-evaluated instance getters.
+     * Instances are computed on first access and cached.
+     *
+     * @param result - Result object to add getters to
+     * @param stream - Stream for parsing
+     * @param context - Execution context
+     * @private
+     */
+    private setupInstances;
+    /**
+     * Parse an instance (lazy-evaluated field).
+     *
+     * @param instance - Instance specification
+     * @param stream - Stream to read from
+     * @param context - Execution context
+     * @returns Parsed or calculated value
+     * @private
+     */
+    private parseInstance;
     /**
      * Parse a single attribute according to its specification.
      *
@@ -801,10 +843,21 @@ declare class TypeInterpreter {
      * @param type - Type name or switch specification
      * @param stream - Stream to read from
      * @param context - Execution context
+     * @param typeArgs - Arguments for parametric types
      * @returns Parsed value
      * @private
      */
     private parseType;
+    /**
+     * Parse a switch type (type selection based on expression).
+     *
+     * @param switchType - Switch type specification
+     * @param stream - Stream to read from
+     * @param context - Execution context
+     * @returns Parsed value
+     * @private
+     */
+    private parseSwitchType;
     /**
      * Parse a built-in type.
      *
@@ -836,11 +889,19 @@ declare class TypeInterpreter {
      */
     private readFloat;
     /**
-     * Evaluate an expression or return a literal value.
-     * If the value is a string, it's treated as an expression.
-     * If it's a number or boolean, it's returned as-is.
+     * Apply processing transformation to data.
+     * Supports basic transformations like zlib decompression.
      *
-     * @param value - Expression string or literal value
+     * @param data - Data to process
+     * @param process - Processing specification
+     * @returns Processed data
+     * @private
+     */
+    private applyProcessing;
+    /**
+     * Evaluate a value that can be an expression or literal.
+     *
+     * @param value - Value to evaluate (expression string, number, or boolean)
      * @param context - Execution context
      * @returns Evaluated result
      * @private
@@ -931,7 +992,7 @@ declare class NotImplementedError extends KaitaiError {
  * @module kaitai-struct-ts
  * @author Fabiano Pinto
  * @license MIT
- * @version 0.2.0
+ * @version 0.6.0
  *
  * @description
  * A runtime interpreter for Kaitai Struct binary format definitions in TypeScript.
@@ -987,6 +1048,19 @@ interface ParseOptions {
     validate?: boolean;
     /** Whether to treat warnings as errors (default: false) */
     strict?: boolean;
+    /**
+     * Imported schemas for type imports.
+     * Map of schema IDs to their parsed schemas.
+     * @example
+     * ```typescript
+     * const imports = {
+     *   'common_types': parsedCommonSchema,
+     *   'header': parsedHeaderSchema
+     * }
+     * parse(ksyYaml, buffer, { imports })
+     * ```
+     */
+    imports?: Record<string, KsySchema>;
 }
 
 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 };