@k67/kaitai-struct-ts 0.8.0 → 0.10.0

package/dist/index.d.mts

@@ -560,8 +560,26 @@ declare class KsyParser {
      * @param imports - Map of import names to their YAML content
      * @param options - Parsing options
      * @returns Parsed schema with resolved imports
+     * @throws {ParseError} If import resolution fails
+     * @example
+     * ```typescript
+     * const parser = new KsyParser()
+     * const imports = new Map([
+     *   ['/common/riff', riffYamlContent]
+     * ])
+     * const schema = parser.parseWithImports(wavYaml, imports)
+     * ```
+     */
+    parseWithImports(mainYaml: string, imports: Map<string, string>, options?: ParseOptions$1): KsySchema;
+    /**
+     * Extract namespace from import path.
+     * Converts paths like '/common/riff' or 'common/riff' to 'riff'.
+     *
+     * @param importPath - Import path from meta.imports
+     * @returns Namespace identifier
+     * @private
      */
-    parseWithImports(mainYaml: string, _imports: Map<string, string>, options?: ParseOptions$1): KsySchema;
+    private extractNamespace;
 }
 /**
  * Options for parsing .ksy files.
@@ -753,15 +771,21 @@ declare class TypeInterpreter {
         endian?: Endianness | object;
         encoding?: string;
     } | undefined);
+    /**
+     * Safely extract a KaitaiStream from an object that may expose `_io`.
+     * Avoids using `any` casts to satisfy linting.
+     */
+    private static getKaitaiIO;
     /**
      * Parse binary data according to the schema.
      *
      * @param stream - Binary stream to parse
      * @param parent - Parent object (for nested types)
      * @param typeArgs - Arguments for parametric types
+     * @param root - Root object of the parse tree (for nested types)
      * @returns Parsed object
      */
-    parse(stream: KaitaiStream, parent?: unknown, typeArgs?: Array<string | number | boolean>): Record<string, unknown>;
+    parse(stream: KaitaiStream, parent?: unknown, typeArgs?: Array<string | number | boolean>, root?: unknown): Record<string, unknown>;
     /**
      * Set up lazy-evaluated instance getters.
      * Instances are computed on first access and cached.
@@ -829,6 +853,25 @@ declare class TypeInterpreter {
      * @private
      */
     private parseType;
+    /**
+     * Parse parameterized type syntax and extract type name and arguments.
+     * Supports: type_name(arg1, arg2, ...) or just type_name
+     *
+     * @param typeSpec - Type specification string
+     * @param context - Execution context for evaluating argument expressions
+     * @returns Object with typeName and evaluated args
+     * @private
+     */
+    private parseParameterizedType;
+    /**
+     * Parse and evaluate a single type argument.
+     *
+     * @param arg - Argument string
+     * @param context - Execution context
+     * @returns Evaluated argument value
+     * @private
+     */
+    private parseArgument;
     /**
      * Parse a switch type (type selection based on expression).
      *
@@ -871,7 +914,7 @@ declare class TypeInterpreter {
     private readFloat;
     /**
      * Apply processing transformation to data.
-     * Supports basic transformations like zlib decompression.
+     * Delegates to the process utility module.
      *
      * @param data - Data to process
      * @param process - Processing specification
@@ -879,6 +922,15 @@ declare class TypeInterpreter {
      * @private
      */
     private applyProcessing;
+    /**
+     * Evaluate expression-based endianness (switch-on).
+     *
+     * @param endianExpr - Endianness expression with switch-on and cases
+     * @param context - Execution context
+     * @returns Resolved endianness ('le' or 'be')
+     * @private
+     */
+    private evaluateEndianExpression;
     /**
      * Evaluate a value that can be an expression or literal.
      *
@@ -909,7 +961,18 @@ declare class TypeInterpreter {
  */
 declare class KaitaiError extends Error {
     position?: number | undefined;
-    constructor(message: string, position?: number | undefined);
+    context?: Uint8Array | undefined;
+    constructor(message: string, position?: number | undefined, context?: Uint8Array | undefined);
+    /**
+     * Format error message with position and context.
+     * @private
+     */
+    private static formatMessage;
+    /**
+     * Format hex dump context around error position.
+     * @private
+     */
+    private static formatHexContext;
 }
 /**
  * Error thrown when validation fails.
@@ -923,7 +986,7 @@ declare class KaitaiError extends Error {
  * ```
  */
 declare class ValidationError extends KaitaiError {
-    constructor(message: string, position?: number);
+    constructor(message: string, position?: number, context?: Uint8Array);
 }
 /**
  * Error thrown when parsing fails.
@@ -937,7 +1000,7 @@ declare class ValidationError extends KaitaiError {
  * ```
  */
 declare class ParseError extends KaitaiError {
-    constructor(message: string, position?: number);
+    constructor(message: string, position?: number, context?: Uint8Array);
 }
 /**
  * Error thrown when end of stream is reached unexpectedly.
@@ -951,7 +1014,7 @@ declare class ParseError extends KaitaiError {
  * ```
  */
 declare class EOFError extends KaitaiError {
-    constructor(message?: string, position?: number);
+    constructor(message?: string, position?: number, context?: Uint8Array);
 }
 /**
  * Error thrown when a required feature is not yet implemented.

package/dist/index.d.ts

@@ -560,8 +560,26 @@ declare class KsyParser {
      * @param imports - Map of import names to their YAML content
      * @param options - Parsing options
      * @returns Parsed schema with resolved imports
+     * @throws {ParseError} If import resolution fails
+     * @example
+     * ```typescript
+     * const parser = new KsyParser()
+     * const imports = new Map([
+     *   ['/common/riff', riffYamlContent]
+     * ])
+     * const schema = parser.parseWithImports(wavYaml, imports)
+     * ```
+     */
+    parseWithImports(mainYaml: string, imports: Map<string, string>, options?: ParseOptions$1): KsySchema;
+    /**
+     * Extract namespace from import path.
+     * Converts paths like '/common/riff' or 'common/riff' to 'riff'.
+     *
+     * @param importPath - Import path from meta.imports
+     * @returns Namespace identifier
+     * @private
      */
-    parseWithImports(mainYaml: string, _imports: Map<string, string>, options?: ParseOptions$1): KsySchema;
+    private extractNamespace;
 }
 /**
  * Options for parsing .ksy files.
@@ -753,15 +771,21 @@ declare class TypeInterpreter {
         endian?: Endianness | object;
         encoding?: string;
     } | undefined);
+    /**
+     * Safely extract a KaitaiStream from an object that may expose `_io`.
+     * Avoids using `any` casts to satisfy linting.
+     */
+    private static getKaitaiIO;
     /**
      * Parse binary data according to the schema.
      *
      * @param stream - Binary stream to parse
      * @param parent - Parent object (for nested types)
      * @param typeArgs - Arguments for parametric types
+     * @param root - Root object of the parse tree (for nested types)
      * @returns Parsed object
      */
-    parse(stream: KaitaiStream, parent?: unknown, typeArgs?: Array<string | number | boolean>): Record<string, unknown>;
+    parse(stream: KaitaiStream, parent?: unknown, typeArgs?: Array<string | number | boolean>, root?: unknown): Record<string, unknown>;
     /**
      * Set up lazy-evaluated instance getters.
      * Instances are computed on first access and cached.
@@ -829,6 +853,25 @@ declare class TypeInterpreter {
      * @private
      */
     private parseType;
+    /**
+     * Parse parameterized type syntax and extract type name and arguments.
+     * Supports: type_name(arg1, arg2, ...) or just type_name
+     *
+     * @param typeSpec - Type specification string
+     * @param context - Execution context for evaluating argument expressions
+     * @returns Object with typeName and evaluated args
+     * @private
+     */
+    private parseParameterizedType;
+    /**
+     * Parse and evaluate a single type argument.
+     *
+     * @param arg - Argument string
+     * @param context - Execution context
+     * @returns Evaluated argument value
+     * @private
+     */
+    private parseArgument;
     /**
      * Parse a switch type (type selection based on expression).
      *
@@ -871,7 +914,7 @@ declare class TypeInterpreter {
     private readFloat;
     /**
      * Apply processing transformation to data.
-     * Supports basic transformations like zlib decompression.
+     * Delegates to the process utility module.
      *
      * @param data - Data to process
      * @param process - Processing specification
@@ -879,6 +922,15 @@ declare class TypeInterpreter {
      * @private
      */
     private applyProcessing;
+    /**
+     * Evaluate expression-based endianness (switch-on).
+     *
+     * @param endianExpr - Endianness expression with switch-on and cases
+     * @param context - Execution context
+     * @returns Resolved endianness ('le' or 'be')
+     * @private
+     */
+    private evaluateEndianExpression;
     /**
      * Evaluate a value that can be an expression or literal.
      *
@@ -909,7 +961,18 @@ declare class TypeInterpreter {
  */
 declare class KaitaiError extends Error {
     position?: number | undefined;
-    constructor(message: string, position?: number | undefined);
+    context?: Uint8Array | undefined;
+    constructor(message: string, position?: number | undefined, context?: Uint8Array | undefined);
+    /**
+     * Format error message with position and context.
+     * @private
+     */
+    private static formatMessage;
+    /**
+     * Format hex dump context around error position.
+     * @private
+     */
+    private static formatHexContext;
 }
 /**
  * Error thrown when validation fails.
@@ -923,7 +986,7 @@ declare class KaitaiError extends Error {
  * ```
  */
 declare class ValidationError extends KaitaiError {
-    constructor(message: string, position?: number);
+    constructor(message: string, position?: number, context?: Uint8Array);
 }
 /**
  * Error thrown when parsing fails.
@@ -937,7 +1000,7 @@ declare class ValidationError extends KaitaiError {
  * ```
  */
 declare class ParseError extends KaitaiError {
-    constructor(message: string, position?: number);
+    constructor(message: string, position?: number, context?: Uint8Array);
 }
 /**
  * Error thrown when end of stream is reached unexpectedly.
@@ -951,7 +1014,7 @@ declare class ParseError extends KaitaiError {
  * ```
  */
 declare class EOFError extends KaitaiError {
-    constructor(message?: string, position?: number);
+    constructor(message?: string, position?: number, context?: Uint8Array);
 }
 /**
  * Error thrown when a required feature is not yet implemented.