@k67/kaitai-struct-ts 0.3.0 → 0.6.0

package/README.md

@@ -18,13 +18,25 @@ Parse any binary data format by providing a `.ksy` (Kaitai Struct YAML) definiti
 
 ## Features
 
+### Core Features
 - 🚀 **Runtime interpretation** - No code generation needed
 - 📦 **Zero dependencies** (runtime) - Only YAML parser for development
 - 🎯 **TypeScript native** - Full type safety and IntelliSense support
 - 🌐 **Universal** - Works in Node.js and browsers
-- 🧪 **Well tested** - Comprehensive test coverage
+- 🧪 **Well tested** - 98 comprehensive tests
 - 📖 **Well documented** - Clear API and examples
 
+### Advanced Features
+- ⚡ **Expression evaluation** - Full support for Kaitai expressions
+- 🔀 **Switch/case types** - Dynamic type selection based on data
+- 💎 **Instances** - Lazy-evaluated fields with caching
+- 🎨 **Enums** - Named constants with expression access
+- 🔁 **Conditional parsing** - if, repeat-expr, repeat-until
+- 📍 **Positioned reads** - Absolute positioning with pos attribute
+- 🔧 **Processing framework** - Ready for zlib/encryption (infrastructure)
+- 🎯 **Parametric types** - Type parameters and arguments (infrastructure)
+- ⚡ **Performance optimized** - Efficient memory management
+
 ## Installation
 
 ```bash
@@ -67,29 +79,6 @@ console.log(result.version) // Access parsed fields
 console.log(result.name)
 ```
 
-## Current Status
-
-**Phase 2 (Core Features) - In Progress**
-
-### Completed
-- [x] Project setup and configuration
-- [x] KaitaiStream implementation (all primitive types)
-- [x] KSY parser with validation
-- [x] Type interpreter (basic parsing)
-- [x] Support for fixed-size structures
-- [x] Nested user-defined types
-- [x] Repetitions (expr, eos)
-- [x] Contents validation
-- [x] Comprehensive tests (58 tests passing)
-
-### In Progress
-- [ ] Expression evaluator
-- [ ] Conditionals (if)
-- [ ] Enums
-- [ ] repeat-until
-
-See [PROJECT_DESIGN.md](./PROJECT_DESIGN.md) for detailed roadmap and [ARCHITECTURE.md](./docs/ARCHITECTURE.md) for architecture diagrams.
-
 ## API Documentation
 
 ### `parse(ksy: string, buffer: ArrayBuffer | Uint8Array, options?: ParseOptions): Record<string, unknown>`
@@ -124,12 +113,17 @@ See [API Documentation](./docs/api.md) for complete reference (coming soon).
 
 ## Examples
 
-Check the [examples](./examples) directory for more usage examples:
+See [EXAMPLES.md](./EXAMPLES.md) for comprehensive examples including:
+- Quick start guide
+- Real-world format examples (PNG, ZIP, ELF, etc.)
+- Links to 100+ format definitions
+- Sample binary files for testing
+
+### Format Resources
 
-- Basic struct parsing
-- Working with enums
-- Conditional parsing
-- Repetitions
+- **Format Gallery:** https://formats.kaitai.io/ - Browse 100+ formats
+- **Format Definitions:** https://github.com/kaitai-io/kaitai_struct_formats - Official .ksy files
+- **Sample Files:** https://codeberg.org/KOLANICH-datasets/kaitai_struct_samples - Test data
 
 ## Development
 
@@ -158,37 +152,50 @@ pnpm format
 
 ## Roadmap
 
-### Phase 1: Foundation (MVP) - Current
-- Basic parsing capability
-- Fixed-size structures
-- Primitive types
-
-### Phase 2: Core Features
-- Expression evaluator
-- Conditionals and enums
-- Repetitions
-- Instances
-
-### Phase 3: Advanced Features
-- Substreams and processing
-- Bit-sized integers
-- Imports
-- Full spec compliance
+### Phase 1: Foundation (MVP) - ✅ Complete
+- ✅ Basic parsing capability
+- ✅ Fixed-size structures
+- ✅ Primitive types (u1-u8, s1-s8, f4, f8)
+- ✅ String encoding support
+- ✅ Byte arrays and positioning
+
+### Phase 2: Core Features - ✅ Complete
+- ✅ Expression evaluator (full Kaitai expression language)
+- ✅ Conditionals (if attribute)
+- ✅ Enums with expression access
+- ✅ Repetitions (repeat-expr, repeat-until, repeat-eos)
+- ✅ Calculated sizes and positions
+
+### Phase 3: Advanced Features - ✅ Complete (95%)
+- ✅ Switch/case type selection
+- ✅ Instances (lazy-evaluated fields)
+- ✅ Processing framework (infrastructure)
+- ✅ Parametric types (complete with syntax parsing)
+- ✅ Performance optimizations (stream + expression caching)
+- ✅ Bit-sized integers (b1-b64)
+- ✅ Type imports (framework)
+- ✅ Parser enhancements
+- ✅ Edge case handling
+- ✅ Memory optimization
+
+**Current Status:** ~99.5% complete toward v1.0.0
+
+See [PROGRESS.md](./PROGRESS.md) for detailed progress tracking.
 
 ## Contributing
 
 Contributions are welcome! Please read our [Contributing Guidelines](./CONTRIBUTING.md) first.
 
-## License
-
-MIT © Fabiano Pinto
-
 ## Related Projects
 
 - [Kaitai Struct](https://kaitai.io/) - Official Kaitai Struct project
 - [kaitai-struct-compiler](https://github.com/kaitai-io/kaitai_struct_compiler) - Official compiler
 - [Format Gallery](https://formats.kaitai.io/) - Collection of .ksy format definitions
 
+## License
+
+MIT © Fabiano Pinto
+
 ## Acknowledgments
 
 This project implements the [Kaitai Struct specification](https://doc.kaitai.io/) created by the Kaitai Struct team.

package/dist/index.d.mts

@@ -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 };