@k67/kaitai-struct-ts 0.5.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
@@ -505,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
@@ -534,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.
      *
@@ -742,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.
      *
@@ -973,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.
@@ -1029,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 };

package/dist/index.js

@@ -193,6 +193,7 @@ var KaitaiStream = class _KaitaiStream {
     if (buffer instanceof ArrayBuffer) {
       this.buffer = new Uint8Array(buffer);
       this.view = new DataView(buffer);
+      this._size = buffer.byteLength;
     } else {
       this.buffer = buffer;
       this.view = new DataView(
@@ -200,6 +201,7 @@ var KaitaiStream = class _KaitaiStream {
         buffer.byteOffset,
         buffer.byteLength
       );
+      this._size = buffer.byteLength;
     }
   }
   /**
@@ -216,13 +218,13 @@ var KaitaiStream = class _KaitaiStream {
    * Total size of the stream in bytes
    */
   get size() {
-    return this.buffer.length;
+    return this._size;
   }
   /**
    * Check if we've reached the end of the stream
    */
   isEof() {
-    return this._pos >= this.buffer.length;
+    return this._pos >= this._size;
   }
   /**
    * Seek to a specific position in the stream
@@ -642,6 +644,7 @@ var KsyParser = class {
       throw new ParseError("KSY file must contain an object");
     }
     const schema = parsed;
+    this.processParametricTypes(schema);
     if (validate) {
       const result = this.validate(schema, { strict });
       if (!result.valid) {
@@ -659,6 +662,65 @@ var KsyParser = class {
     }
     return schema;
   }
+  /**
+   * Process parametric type syntax in schema.
+   * Converts "type_name(arg1, arg2)" to structured format.
+   *
+   * @param schema - Schema to process
+   * @private
+   */
+  processParametricTypes(schema) {
+    if (schema.seq) {
+      for (const attr of schema.seq) {
+        if (typeof attr.type === "string") {
+          this.parseParametricType(attr);
+        }
+      }
+    }
+    if (schema.instances) {
+      for (const instance of Object.values(schema.instances)) {
+        if (typeof instance.type === "string") {
+          this.parseParametricType(instance);
+        }
+      }
+    }
+    if (schema.types) {
+      for (const type of Object.values(schema.types)) {
+        this.processParametricTypes(type);
+      }
+    }
+  }
+  /**
+   * Parse parametric type syntax from a type string.
+   * Converts "type_name(arg1, arg2)" to type + type-args.
+   *
+   * @param attr - Attribute to process
+   * @private
+   */
+  parseParametricType(attr) {
+    if (typeof attr.type !== "string") return;
+    const match = attr.type.match(/^([a-z_][a-z0-9_]*)\((.*)\)$/i);
+    if (!match) return;
+    const [, typeName, argsStr] = match;
+    const args = [];
+    if (argsStr.trim()) {
+      const argParts = argsStr.split(",").map((s) => s.trim());
+      for (const arg of argParts) {
+        const num = Number(arg);
+        if (!isNaN(num)) {
+          args.push(num);
+        } else if (arg === "true") {
+          args.push(true);
+        } else if (arg === "false") {
+          args.push(false);
+        } else {
+          args.push(arg);
+        }
+      }
+    }
+    attr.type = typeName;
+    attr["type-args"] = args;
+  }
   /**
    * Validate a schema object.
    *
@@ -1954,6 +2016,10 @@ var TypeInterpreter = class _TypeInterpreter {
   constructor(schema, parentMeta) {
     this.schema = schema;
     this.parentMeta = parentMeta;
+    // Performance optimization: cache for constant expressions
+    // Limited size to prevent memory leaks
+    this.expressionCache = /* @__PURE__ */ new Map();
+    this.MAX_CACHE_SIZE = 1e3;
     if (!schema.meta && !parentMeta) {
       throw new ParseError("Schema must have meta section");
     }
@@ -2058,7 +2124,10 @@ var TypeInterpreter = class _TypeInterpreter {
           );
         }
       }
-      const value = this.parseAttribute(instance, context);
+      const value = this.parseAttribute(
+        instance,
+        context
+      );
       return value;
     } finally {
       if (instance.pos !== void 0) {
@@ -2095,6 +2164,11 @@ var TypeInterpreter = class _TypeInterpreter {
     if (attr.io) {
       throw new NotImplementedError("Custom I/O streams");
     }
+    if (!attr.type && !attr.size && !attr["size-eos"] && !attr.contents) {
+      throw new ParseError(
+        `Attribute "${attr.id || "unknown"}" must have type, size, size-eos, or contents`
+      );
+    }
     if (attr.repeat) {
       return this.parseRepeated(attr, context);
     }
@@ -2144,7 +2218,13 @@ var TypeInterpreter = class _TypeInterpreter {
           throw new ParseError("repeat-until expression is required");
         }
         let index = 0;
+        const maxIterations = 1e6;
         while (true) {
+          if (index >= maxIterations) {
+            throw new ParseError(
+              `repeat-until exceeded maximum iterations (${maxIterations}). Possible infinite loop.`
+            );
+          }
           context.set("_index", index);
           const value = this.parseAttribute(
             { ...attr, repeat: void 0, "repeat-until": void 0 },
@@ -2219,6 +2299,11 @@ var TypeInterpreter = class _TypeInterpreter {
       if (size < 0) {
         throw new ParseError(`size must be non-negative, got ${size}`);
       }
+      if (stream.pos + size > stream.size) {
+        throw new ParseError(
+          `Not enough data: need ${size} bytes at position ${stream.pos}, but only ${stream.size - stream.pos} bytes available`
+        );
+      }
       if (type === "str" || !type) {
         const encoding = attr.encoding || this.schema.meta.encoding || "UTF-8";
         let data;
@@ -2340,6 +2425,13 @@ var TypeInterpreter = class _TypeInterpreter {
     const meta = this.schema.meta || this.parentMeta;
     const metaEndian = meta?.endian;
     const endian = typeEndian || (typeof metaEndian === "string" ? metaEndian : "le");
+    if (type.startsWith("b") && type.length > 1) {
+      const bits = parseInt(type.substring(1), 10);
+      if (!isNaN(bits) && bits >= 1 && bits <= 64) {
+        const value = endian === "be" ? stream.readBitsIntBe(bits) : stream.readBitsIntLe(bits);
+        return bits <= 32 ? Number(value) : value;
+      }
+    }
     if (isIntegerType(type)) {
       return this.readInteger(base, endian, stream);
     }
@@ -2435,8 +2527,21 @@ var TypeInterpreter = class _TypeInterpreter {
       return value;
     }
     if (typeof value === "string") {
+      if (!value.includes("_") && !value.includes(".")) {
+        const cached = this.expressionCache.get(value);
+        if (cached !== void 0) {
+          return cached;
+        }
+      }
       try {
-        return evaluateExpression(value, context);
+        const result = evaluateExpression(value, context);
+        if (!value.includes("_") && !value.includes(".")) {
+          if (this.expressionCache.size >= this.MAX_CACHE_SIZE) {
+            this.expressionCache.clear();
+          }
+          this.expressionCache.set(value, result);
+        }
+        return result;
       } catch (error) {
         throw new ParseError(
           `Failed to evaluate expression "${value}": ${error instanceof Error ? error.message : String(error)}`
@@ -2577,7 +2682,7 @@ function parse(ksyYaml, buffer, options = {}) {
  * @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.