{"id":40904257,"url":"https://github.com/fabianopinto/kaitai-struct-ts","last_synced_at":"2026-01-22T02:36:39.344Z","repository":{"id":317597771,"uuid":"1068056679","full_name":"fabianopinto/kaitai-struct-ts","owner":"fabianopinto","description":"Runtime interpreter for Kaitai Struct binary format definitions in TypeScript","archived":false,"fork":false,"pushed_at":"2025-10-28T10:37:47.000Z","size":2293,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-28T12:22:04.687Z","etag":null,"topics":["binary-format","binary-parser","kaitai-struct","ksy","parser","runtime-interpreter","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fabianopinto.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-01T19:39:01.000Z","updated_at":"2025-10-28T10:37:51.000Z","dependencies_parsed_at":"2025-10-01T22:20:56.296Z","dependency_job_id":"79e68c8c-8d67-4141-ad3d-e77c51988107","html_url":"https://github.com/fabianopinto/kaitai-struct-ts","commit_stats":null,"previous_names":["fabianopinto/kaitai-struct-ts"],"tags_count":19,"template":false,"template_full_name":null,"purl":"pkg:github/fabianopinto/kaitai-struct-ts","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fabianopinto%2Fkaitai-struct-ts","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fabianopinto%2Fkaitai-struct-ts/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fabianopinto%2Fkaitai-struct-ts/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fabianopinto%2Fkaitai-struct-ts/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fabianopinto","download_url":"https://codeload.github.com/fabianopinto/kaitai-struct-ts/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fabianopinto%2Fkaitai-struct-ts/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28651809,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-22T01:17:37.254Z","status":"online","status_checked_at":"2026-01-22T02:00:07.137Z","response_time":144,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["binary-format","binary-parser","kaitai-struct","ksy","parser","runtime-interpreter","typescript"],"created_at":"2026-01-22T02:36:39.276Z","updated_at":"2026-01-22T02:36:39.339Z","avatar_url":"https://github.com/fabianopinto.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\".github/logo.png\" alt=\"kaitai-struct-ts\" width=\"200\"/\u003e\n\n# kaitai-struct-ts\n\n[![npm version](https://badge.fury.io/js/%40fabianopinto%2Fkaitai-struct.svg)](https://www.npmjs.com/package/@fabianopinto/kaitai-struct)\n[![CI](https://github.com/fabianopinto/kaitai-struct-ts/workflows/CI/badge.svg)](https://github.com/fabianopinto/kaitai-struct-ts/actions)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue.svg)](https://www.typescriptlang.org/)\n[![Node.js](https://img.shields.io/badge/Node.js-18%2B-green.svg)](https://nodejs.org/)\n\n**A runtime interpreter for [Kaitai Struct](https://kaitai.io/) binary format definitions in TypeScript.**\n\n\u003c/div\u003e\n\n---\n\nParse any binary data format by providing a `.ksy` (Kaitai Struct YAML) definition file - no compilation step required!\n\n## Features\n\n### Core Features\n\n- **Runtime interpretation** - No code generation needed\n- **Zero dependencies** (runtime) - Only YAML parser for development\n- **TypeScript native** - Full type safety and IntelliSense support\n- **Universal** - Works in Node.js and browsers\n- **Well tested** - 283 comprehensive tests\n- **Well documented** - Clear API and examples\n\n### Advanced Features\n\n- **Expression evaluation** - Full support for Kaitai expressions\n- **Switch/case types** - Dynamic type selection based on data\n- **Instances** - Lazy-evaluated fields with caching\n- **Enums** - Named constants with expression access\n- **Conditional parsing** - if, repeat-expr, repeat-until\n- **Positioned reads** - Absolute positioning with pos attribute\n- **Streaming API** - Parse large files progressively (v0.10.0)\n\n### Visual Debugger\n\n**[Launch Debugger](https://fabianopinto.github.io/kaitai-struct-ts/)** | **[Documentation](./debugger/README.md)**\n\nInteractive web-based debugger for visualizing and stepping through binary parsing:\n\n- **Hex Viewer** - Editable hex view with virtual scrolling, and field highlighting\n- **Parse Tree** - Interactive tree view with expandable nodes\n- **Schema Editor** - Monaco-based .ksy editor with syntax highlighting\n- **Step Debugger** - Play/pause/step controls with breakpoints\n- **Expression Console** - REPL for evaluating expressions against parsed data\n  - Context variables: `root`, `_` (selected field), `data` (binary)\n  - Helper functions: `hex()`, `bin()`, `bytes()`, `sizeof()`, `offsetof()`\n  - Command history with ↑↓ navigation\n- **Built-in Examples** - GIF, PNG, WAV, EDID formats ready to test\n- **Keyboard Shortcuts** - F5 (run), F9 (breakpoint), F10 (step), F11 (step in)\n\n## Installation\n\n```bash\nnpm install @fabianopinto/kaitai-struct\n# or\npnpm add @fabianopinto/kaitai-struct\n# or\nyarn add @fabianopinto/kaitai-struct\n```\n\n## Quick Start\n\n### CLI Usage\n\nParse binary files directly from the command line:\n\n```bash\n# Using npx (no installation needed)\nnpx @fabianopinto/kaitai-struct format.ksy data.bin\n\n# Or with pnpm\npnpx @fabianopinto/kaitai-struct format.ksy data.bin\n\n# After installing globally\nnpm install -g @fabianopinto/kaitai-struct\nkaitai format.ksy data.bin\n\n# Save output to file\nkaitai format.ksy data.bin -o output.json\n\n# Extract specific field\nkaitai format.ksy data.bin --field header.version\n\n# Get help\nkaitai --help\n```\n\n### Library Usage\n\n```typescript\nimport { parse } from '@fabianopinto/kaitai-struct'\nimport { readFileSync } from 'fs'\n\n// Load your .ksy definition\nconst ksyDefinition = `\nmeta:\n  id: my_format\n  endian: le\nseq:\n  - id: magic\n    contents: [0x4D, 0x59, 0x46, 0x4D]\n  - id: version\n    type: u2\n  - id: name\n    type: str\n    size: 32\n    encoding: UTF-8\n`\n\n// Load your binary data\nconst binaryData = readFileSync('data.bin')\n\n// Parse!\nconst result = parse(ksyDefinition, binaryData)\n\nconsole.log(result.version) // Access parsed fields\nconsole.log(result.name)\n```\n\n### Performance Optimization\n\nFor optimal performance when parsing multiple files with the same schema, pre-compile the schema once and reuse it:\n\n```typescript\nimport { compileSchema, parseWithSchema } from '@fabianopinto/kaitai-struct'\nimport { readFileSync } from 'fs'\n\n// Compile schema once\nconst compiled = compileSchema(ksyDefinition, { validate: true })\n\n// Reuse for multiple files (50-70% faster for small files)\nconst result1 = parseWithSchema(compiled, readFileSync('file1.bin'))\nconst result2 = parseWithSchema(compiled, readFileSync('file2.bin'))\nconst result3 = parseWithSchema(compiled, readFileSync('file3.bin'))\n\n// Or use the unified parse() function\nconst result = parse(compiled, binaryData)\n```\n\n**Benefits:**\n\n- Eliminates redundant YAML parsing (1-5ms per parse)\n- Skips schema validation overhead (0.5-2ms per parse)\n- Ideal for batch processing or server applications\n- Backward compatible - existing code works unchanged\n\n## Current Status\n\n**Version:** 0.14.0\n**Status:** Production Ready\n**Latest:** Schema Compilation API for performance optimization\n\n### Fully Implemented\n\n- **Core Runtime** - Complete binary stream reader with all primitive types\n- **Streaming API** - Parse files larger than RAM with progressive results (NEW in v0.10.0)\n- **KSY Parser** - Full YAML parser with schema validation\n- **Type Interpreter** - Execute schemas against binary data\n- **Expression Evaluator** - Complete Kaitai expression language support\n- **Advanced Features** - Conditionals, enums, repetitions, instances, switch/case\n- **CLI Tool** - Command-line utility for parsing binary files\n- **Testing** - 283 comprehensive tests, all passing\n- **Documentation** - Complete user and developer documentation\n\n### What's New in v0.14.0\n\n- **Schema Compilation API** - Pre-compile schemas for optimal performance (NEW)\n  - `compileSchema()` - Compile .ksy schemas once for reuse\n  - `parseWithSchema()` - Parse with pre-compiled schemas\n  - `parse()` - Now accepts both YAML strings and compiled schemas\n  - 50-70% performance improvement for batch processing\n  - Zero breaking changes - fully backward compatible\n\n### What's New in v0.12.0\n\n- **Visual Debugger** - Interactive debugger with hex viewer, parse tree, and step debugging\n  - **Expression Console/REPL** - Interactive JavaScript console in the debugger\n  - **Unified Console** - Parse events and expressions in single chronological view\n  - **Enhanced Debugger** - Better error display, execution timing, improved UX\n  - Try [Visual Debugger](https://fabianopinto.github.io/kaitai-struct-ts/) in your browser\n  - See [debugger/README.md](./debugger/README.md)\n\n### What's New in v0.10.0\n\n- **Streaming API** - Parse large files without loading everything into memory\n  - `StreamingKaitaiStream` - Forward-only stream reader\n  - `parseStreaming()` - Event-based progressive parsing\n  - Memory-efficient for files larger than RAM\n  - See [docs/STREAMING.md](./docs/STREAMING.md)\n\n### Remaining for v1.0.0\n\n- Processing implementations (zlib, encryption)\n- Type imports across files\n- Additional performance optimizations\n\nSee [docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md) for architecture details.\n\n## API Documentation\n\n### `parse(ksy: string, buffer: ArrayBuffer | Uint8Array, options?: ParseOptions): Record\u003cstring, unknown\u003e`\n\nParse binary data using a Kaitai Struct definition.\n\n**Parameters:**\n\n- `ksy` - YAML string containing the .ksy definition\n- `buffer` - Binary data to parse\n- `options` - Optional parsing options (validate, strict)\n\n**Returns:** Parsed object with fields defined in the .ksy file\n\n**Example:**\n\n```typescript\nimport { parse } from '@fabianopinto/kaitai-struct'\n\nconst result = parse(ksyYaml, binaryData, { validate: true })\nconsole.log(result.fieldName)\n```\n\n### `KaitaiStream`\n\nLow-level binary stream reader.\n\n```typescript\nimport { KaitaiStream } from '@fabianopinto/kaitai-struct'\n\nconst stream = new KaitaiStream(buffer)\nconst value = stream.readU4le() // Read 4-byte unsigned little-endian integer\n```\n\nSee [API Documentation](./docs/API.md) for complete reference.\n\n## CLI Reference\n\nThe `kaitai` command-line tool allows you to parse binary files without writing code.\n\n```bash\n# Basic usage\nkaitai \u003cksy-file\u003e \u003cbinary-file\u003e [options]\n\n# Examples\nkaitai format.ksy data.bin                    # Parse and display\nkaitai format.ksy data.bin -o result.json     # Save to file\nkaitai format.ksy data.bin --field version    # Extract field\nkaitai format.ksy data.bin --quiet            # Quiet mode\n```\n\n**📖 Full CLI Documentation:** [docs/CLI.md](./docs/CLI.md)\n\n**Quick Reference:**\n\n- `-o, --output \u003cfile\u003e` - Write to file\n- `--field \u003cpath\u003e` - Extract specific field\n- `-q, --quiet` - Suppress progress messages\n- `-h, --help` - Show help\n- See [docs/CLI.md](./docs/CLI.md) for all options and examples\n\n## Examples\n\nCheck the [examples](./examples) directory for more usage examples:\n\n- Basic struct parsing\n- Working with enums\n- Conditional parsing\n- Repetitions\n\n## Development\n\n```bash\n# Install dependencies\npnpm install\n\n# Build\npnpm build\n\n# Run tests\npnpm test\n\n# Run tests with UI\npnpm test:ui\n\n# Test coverage\npnpm test:coverage\n\n# Lint\npnpm lint\n\n# Format\npnpm format\n```\n\n## Current Status\n\n**Version:** 0.12.0\n**Debugger Version:** 0.8.0\n**Status:** Production-ready, actively maintained\n\nThe library is feature-complete for most use cases with comprehensive test coverage (283 tests). The visual debugger provides an interactive development experience with real-time parsing visualization, expression evaluation, and step-by-step debugging capabilities.\n\n## Roadmap\n\n### ✅ Completed\n\n- **v0.1.0-v0.4.0** - Core runtime, KSY parser, type interpreter, expressions\n- **v0.5.0-v0.6.0** - Advanced features (switch/case, instances, parametric types)\n- **v0.7.0-v0.9.0** - CLI tool, production polish, expression-based endianness\n- **v0.10.0** - Streaming API for large files\n- **v0.11.0** - Visual debugger with hex viewer, parse tree, and step debugging\n- **v0.12.0** - Expression console/REPL, unified console, debugger enhancements\n\n### 🔄 In Progress (v1.0.0)\n\n- Processing implementations (zlib, encryption)\n- Additional performance optimizations\n- Extended format testing\n- Debugger improvements (performance, UX enhancements)\n\n## Contributing\n\nContributions are welcome! Please read our [Contributing Guidelines](./CONTRIBUTING.md) first.\n\n## License\n\nMIT © Fabiano Pinto\n\n## Related Projects\n\n- [Kaitai Struct](https://kaitai.io/) - Official Kaitai Struct project\n- [kaitai-struct-compiler](https://github.com/kaitai-io/kaitai_struct_compiler) - Official compiler\n- [Format Gallery](https://formats.kaitai.io/) - Collection of .ksy format definitions\n\n## Acknowledgments\n\nThis project implements the [Kaitai Struct specification](https://doc.kaitai.io/) created by the Kaitai Struct team.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffabianopinto%2Fkaitai-struct-ts","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffabianopinto%2Fkaitai-struct-ts","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffabianopinto%2Fkaitai-struct-ts/lists"}