@k67/kaitai-struct-ts 0.2.0 → 0.5.0

package/README.md

@@ -1,24 +1,39 @@
-# kaitai-struct-ts
+<div align="center">
+  <img src="assets/logo.png" alt="kaitai-struct-ts" width="200"/>
+  
+  # kaitai-struct-ts
 
-[![npm version](https://badge.fury.io/js/%40k67%2Fkaitai-struct-ts.svg)](https://www.npmjs.com/package/@k67/kaitai-struct-ts)
-[![CI](https://github.com/fabianopinto/kaitai-struct-ts/workflows/CI/badge.svg)](https://github.com/fabianopinto/kaitai-struct-ts/actions)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue.svg)](https://www.typescriptlang.org/)
-[![Node.js](https://img.shields.io/badge/Node.js-18%2B-green.svg)](https://nodejs.org/)
+  [![npm version](https://badge.fury.io/js/%40k67%2Fkaitai-struct-ts.svg)](https://www.npmjs.com/package/@k67/kaitai-struct-ts)
+  [![CI](https://github.com/fabianopinto/kaitai-struct-ts/workflows/CI/badge.svg)](https://github.com/fabianopinto/kaitai-struct-ts/actions)
+  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+  [![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue.svg)](https://www.typescriptlang.org/)
+  [![Node.js](https://img.shields.io/badge/Node.js-18%2B-green.svg)](https://nodejs.org/)
 
-A **runtime interpreter** for [Kaitai Struct](https://kaitai.io/) binary format definitions in TypeScript.
+  **A runtime interpreter for [Kaitai Struct](https://kaitai.io/) binary format definitions in TypeScript.**
+</div>
+
+---
 
 Parse any binary data format by providing a `.ksy` (Kaitai Struct YAML) definition file - no compilation step required!
 
 ## 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
+
 ## Installation
 
 ```bash
@@ -152,22 +167,30 @@ 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 - 🔄 In Progress (30% Complete)
+- ✅ Switch/case type selection
+- ✅ Instances (lazy-evaluated fields)
+- ⏳ Substreams and processing
+- ⏳ Parametric types
+- ⏳ Bit-sized integers
+- ⏳ Type imports
+- ⏳ Performance optimizations
+
+**Current Status:** ~85% complete toward v1.0.0
 
 ## Contributing
 

package/dist/index.d.mts

@@ -299,6 +299,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 */
@@ -611,14 +613,17 @@ declare class Context {
     private parentStack;
     /** Current object being parsed */
     private _current;
+    /** Enum definitions from schema */
+    private _enums;
     /**
      * Create a new execution context.
      *
      * @param _io - Binary stream being read
      * @param _root - Root object of the parse tree
      * @param _parent - Parent object (optional)
+     * @param enums - Enum definitions from schema (optional)
      */
-    constructor(_io: KaitaiStream, _root?: unknown, _parent?: unknown);
+    constructor(_io: KaitaiStream, _root?: unknown, _parent?: unknown, enums?: Record<string, EnumSpec>);
     /**
      * Get the current I/O stream.
      * Accessible in expressions as `_io`.
@@ -682,6 +687,22 @@ declare class Context {
      * @param value - Value to set
      */
     set(name: string, value: unknown): void;
+    /**
+     * Get enum value by name.
+     * Used for enum access in expressions (EnumName::value).
+     *
+     * @param enumName - Name of the enum
+     * @param valueName - Name of the enum value
+     * @returns Enum value (number) or undefined
+     */
+    getEnumValue(enumName: string, valueName: string): unknown;
+    /**
+     * Check if an enum exists.
+     *
+     * @param enumName - Name of the enum
+     * @returns True if enum exists
+     */
+    hasEnum(enumName: string): boolean;
     /**
      * Create a child context for nested parsing.
      * The current object becomes the parent in the child context.
@@ -737,9 +758,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.
      *
@@ -782,10 +824,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.
      *
@@ -816,6 +869,25 @@ declare class TypeInterpreter {
      * @private
      */
     private readFloat;
+    /**
+     * Apply processing transformation to data.
+     * Supports basic transformations like zlib decompression.
+     *
+     * @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
+     */
+    private evaluateValue;
 }
 
 /**

package/dist/index.d.ts

@@ -299,6 +299,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 */
@@ -611,14 +613,17 @@ declare class Context {
     private parentStack;
     /** Current object being parsed */
     private _current;
+    /** Enum definitions from schema */
+    private _enums;
     /**
      * Create a new execution context.
      *
      * @param _io - Binary stream being read
      * @param _root - Root object of the parse tree
      * @param _parent - Parent object (optional)
+     * @param enums - Enum definitions from schema (optional)
      */
-    constructor(_io: KaitaiStream, _root?: unknown, _parent?: unknown);
+    constructor(_io: KaitaiStream, _root?: unknown, _parent?: unknown, enums?: Record<string, EnumSpec>);
     /**
      * Get the current I/O stream.
      * Accessible in expressions as `_io`.
@@ -682,6 +687,22 @@ declare class Context {
      * @param value - Value to set
      */
     set(name: string, value: unknown): void;
+    /**
+     * Get enum value by name.
+     * Used for enum access in expressions (EnumName::value).
+     *
+     * @param enumName - Name of the enum
+     * @param valueName - Name of the enum value
+     * @returns Enum value (number) or undefined
+     */
+    getEnumValue(enumName: string, valueName: string): unknown;
+    /**
+     * Check if an enum exists.
+     *
+     * @param enumName - Name of the enum
+     * @returns True if enum exists
+     */
+    hasEnum(enumName: string): boolean;
     /**
      * Create a child context for nested parsing.
      * The current object becomes the parent in the child context.
@@ -737,9 +758,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.
      *
@@ -782,10 +824,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.
      *
@@ -816,6 +869,25 @@ declare class TypeInterpreter {
      * @private
      */
     private readFloat;
+    /**
+     * Apply processing transformation to data.
+     * Supports basic transformations like zlib decompression.
+     *
+     * @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
+     */
+    private evaluateValue;
 }
 
 /**