{"id":24102747,"url":"https://github.com/tperale/binspector","last_synced_at":"2025-05-07T16:15:01.513Z","repository":{"id":240307962,"uuid":"629646940","full_name":"tperale/binspector","owner":"tperale","description":"A truly declarative library for binary file decoding and encoding written in typescript","archived":false,"fork":false,"pushed_at":"2025-04-03T20:59:27.000Z","size":1102,"stargazers_count":2,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-05-07T16:14:54.101Z","etag":null,"topics":["binary-encoder","binary-parser","declarative","encoder","parser","typescript"],"latest_commit_sha":null,"homepage":"https://tperale.github.io/binspector/","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/tperale.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"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}},"created_at":"2023-04-18T18:31:55.000Z","updated_at":"2025-04-03T20:59:03.000Z","dependencies_parsed_at":"2024-05-17T23:24:53.068Z","dependency_job_id":"a1617cec-1f16-42ce-a16c-27bc80b68e8d","html_url":"https://github.com/tperale/binspector","commit_stats":null,"previous_names":["tperale/binspector"],"tags_count":22,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tperale%2Fbinspector","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tperale%2Fbinspector/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tperale%2Fbinspector/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tperale%2Fbinspector/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tperale","download_url":"https://codeload.github.com/tperale/binspector/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252912996,"owners_count":21824066,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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-encoder","binary-parser","declarative","encoder","parser","typescript"],"created_at":"2025-01-10T18:15:54.090Z","updated_at":"2025-05-07T16:15:01.502Z","avatar_url":"https://github.com/tperale.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🕵️ binspector, your binary file assistant\n\nA _truly declarative_ TypeScript library to help you create binary file and\nprotocol definitions.\n\n- 🗣️  __Declarative__ – Define binary structures using __decorators__.\n- 🔄 __Read \u0026 Write Support__ – Seamlessly __parse \u0026 serialize__ binary data.\n- ⬆️  __Extensible__ - Write __custom__ decorators.\n- 🖋️ __Typed__ – Leverage TypeScript’s type system for validation.\n- 🌐 __Works in the Browser__ – Use Binspector for frontend or backend binary processing.\n- 📦 __Zero Dependencies__ – No external dependencies.\n\n## 📌 What does it looks like ?\n\nSee [examples](https://github.com/tperale/binspector/tree/main/example) for\nreal files formats.\n\n```typescript\nclass ProtocolHeader {\n  // Ensure the header starts with specific magic number\n  @Match(\".bin\")\n  @Count(4)\n  @Ascii\n  extension: string\n\n  @Uint32\n  len: number\n\n  @Uint32\n  string_map_offset: number\n\n  @Uint32\n  string_map_size: number\n}\n\nenum RecordTypes {\n  RecordStart = 0x01,\n  RecordMsg = 0x02,\n  RecordEnd = 0x03,\n}\n\nclass RecordMessage {\n  @Uint32\n  size: number\n\n  @Size('size')\n  @Utf8\n  message: string\n}\n\nclass Record {\n  @Uint32\n  id: number\n\n  // Supports TypesSript enums\n  @Enum(RecordTypes)\n  @Uint8\n  type: RecordTypes\n\n  // Dynamically select a subtype based on `type`\n  @Choice('type', {\n    [RecordTypes.RecordMsg]: RecordMessage,\n    [RecordTypes.RecordStart]: undefined,\n    [RecordTypes.RecordEnd]: undefined,\n  })\n  data: RecordMessage;\n}\n\nclass Protocol {\n  // Nested structure with a reference to another class\n  @Relation(ProtocolHeader)\n  header: ProtocolHeader\n\n  // Use values from previously read properties\n  @Count('header.len')\n  @Relation(Record)\n  records: Record\n\n  // Jump to an arbitrary offset and read data until size is reached\n  // to create an array of strings\n  @Offset('header.string_map_offset')  \n  @Size('header.string_map_size')  \n  @NullTerminatedString()\n  strings: string[]\n}\n```\n\n## 🚀 Features\n\n- Declarative Class-Based Approach – Define binary structures as TypeScript classes.\n- Leverages TypeScript's Type System – No need to write separate type definitions.\n- Fully Extensible – Unlike DSL-based libraries, Binspector is easily extensible to create custom decorators.\n- Supports Complex Binary Operations:\n  - Endianness\n  - Magic numbers and enums validation\n  - Conditional parsing\n  - Bitfields\n  - Nested Structure \u0026 recursive references\n  - Dynamic offset, variable length properties\n  - String encodings (UTF-8, UTF-16, UTF-32, ASCII)\n  - Shared context\n\n## 📦 Installation\n\nInstall __Binspector__ from [npm](https://www.npmjs.com/package/binspector):\n\n```text\n\u003e npm install binspector\n```\n\n## 📁 Usage\n\nHere’s a simple example of reading and writing a binary coordinate system.\n\n```typescript\nimport { Relation, Uint8, Count } from 'binspector'\n\nclass Coord {\n  @Uint8\n  x: number\n\n  @Uint8\n  y: number\n}\n\nclass Protocol {\n  @Uint8\n  len: number\n\n  @Count('len')\n  @Relation(Coord)\n  coords: Coord[]\n}\n```\n\n### 🔍 Reading an ArrayBuffer into Objects\n\n```typescript\nimport { binread } from 'binspector'\n\nconst buf = new Uint8Array([0x02, 0x01, 0x02, 0x03, 0x04])\n\nbinread(buf, Protocol)\n// =\u003e { len: 2, coords: [{ x: 1, y: 2 }, { x: 3, y: 4 }] }\n```\n\n### ✍️  Writing Objects to ArrayBuffer\n\n```typescript\nimport { binwrite, BinaryWriter } from 'binspector'\n\nconst obj = { len: 2, coords: [{ x: 1, y: 2 }, { x: 3, y: 4 }] }\n\nbinwrite(obj, Protocol)\n// =\u003e [0x02, 0x01, 0x02, 0x03, 0x04]\n```\n\n## 📖 Learn more\n\n- 📚 Documentation: [Getting Started](https://tperale.github.io/binspector/documents/Getting-Started-With-Binspector.html)\n- 📂 Examples: [/example](https://github.com/tperale/binspector/tree/main/example)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftperale%2Fbinspector","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftperale%2Fbinspector","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftperale%2Fbinspector/lists"}