{"id":16731416,"url":"https://github.com/skratchdot/binary-format","last_synced_at":"2025-04-10T11:23:52.743Z","repository":{"id":65707063,"uuid":"387265060","full_name":"skratchdot/binary-format","owner":"skratchdot","description":"a typescript library for reading and writing binary files to and from plain javascript objects","archived":false,"fork":false,"pushed_at":"2023-07-09T18:59:37.000Z","size":682,"stargazers_count":6,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-24T10:11:16.046Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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/skratchdot.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":"2021-07-18T20:39:51.000Z","updated_at":"2025-02-12T19:02:04.000Z","dependencies_parsed_at":"2024-10-19T03:45:43.929Z","dependency_job_id":null,"html_url":"https://github.com/skratchdot/binary-format","commit_stats":{"total_commits":18,"total_committers":1,"mean_commits":18.0,"dds":0.0,"last_synced_commit":"a21ada4911e15e29b7e75da10e221119d4013d6e"},"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/skratchdot%2Fbinary-format","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/skratchdot%2Fbinary-format/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/skratchdot%2Fbinary-format/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/skratchdot%2Fbinary-format/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/skratchdot","download_url":"https://codeload.github.com/skratchdot/binary-format/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248208612,"owners_count":21065203,"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":[],"created_at":"2024-10-12T23:37:02.024Z","updated_at":"2025-04-10T11:23:52.725Z","avatar_url":"https://github.com/skratchdot.png","language":"TypeScript","readme":"# binary-format\n\na typescript library for reading and writing binary files to and from plain javascript objects.\n\nthere is a plethora of exiting libraries that accomplish the same goal, but all come with tradeoffs.\n\ni am trading some speed in favor or using \"plain\" javascript objects that immer supports because i wanted\nto use immutable data structures while working on an online editor that supports the editing of various\nfile formats.\n\n## quick start\n\n```typescript\nimport BinaryFormat from '@skratchdot/binary-format';\nconst helloWorldParser = new BinaryFormat\u003c{\n  hello: string;\n  asciiSpace: number;\n  world: string;\n  asciiExclaimation: number;\n}\u003e()\n  .string('hello', 5)\n  .uint8('asciiSpace')\n  .string('world', 5)\n  .uint8('asciiExclaimation')\n  .done();\nconst buffer = Buffer.from('hello world!');\nconst readResult = helloWorldParser.read(buffer);\nconst writeResult = helloWorldParser.write(readResult);\nconsole.log({ readResult, writeResult });\n/*\n{\n  readResult: {\n    hello: 'hello',\n    asciiSpace: 32,\n    world: 'world',\n    asciiExclaimation: 33\n  },\n  writeResult: \u003cBuffer 68 65 6c 6c 6f 20 77 6f 72 6c 64 21\u003e\n}\n*/\n```\n\n## features\n\n- written in typescript\n- supports both reading and writing of binary files\n- supports formatting to/from \"plain\" javascript objects (that are serializable and supported via immutability libs like `immer`)\n- supports formatting to/from \"complex\" javascript objects like typed arrays and buffers\n\n## documentation\n\ncoming soon. for now check out the examples folder or the unit tests\n\n#### Custom\n\n```typescript\nexport const stringWithLength = (length: number): ReadAndWrite =\u003e ({\n  read: (r: SmartBuffer) =\u003e r.readString(length),\n  write: (w: SmartBuffer, v: unknown) =\u003e w.writeString(String(v), length),\n});\n```\n\n## see also\n\n#### parsing libs\n\n- https://github.com/keichi/binary-parser\n- https://github.com/anfema/bin-grammar\n- https://github.com/substack/node-binary\n- https://github.com/reklatsmasters/binary-data\n- https://github.com/foliojs/restructure\n- https://kaitai.io/\n- https://github.com/lammas/bin-format\n- https://github.com/RobertBorg/node-BinaryFormat\n- https://www.npmjs.com/package/memory-efficient-object\n- https://www.npmjs.com/package/@astronautlabs/bitstream?activeTab=readme\n\n#### buffer libs:\n\n- https://github.com/inolen/bit-buffer\n- https://github.com/feross/buffer\n- https://github.com/JoshGlazebrook/smart-buffer\n- https://github.com/fredricrylander/bits\n- https://github.com/uupaa/Bit.js/\n- https://github.com/FlorianWendelborn/bitwise\n- https://github.com/steinwurf/bitter (c library)\n- https://www.npmjs.com/package/node-bit-stream\n- https://github.com/thi-ng/umbrella/tree/develop/packages/bitstream\n- https://github.com/conekt/bitsandbytes\n- https://www.npmjs.com/package/bits-bytes (pack and unpack)\n- https://github.com/francisrstokes/construct-js\n- https://github.com/rochars/byte-data\n\n## todos\n\n- detect cycles\n- add streaming support\n- add example parsers\n- remove all dependencies\n  - update BinaryBuffer so it supports all the functionality of bit-buffer and smart-buffer (with bit/byte offset logic)\n- consider \"export parser\" so endusers don't need to include unneeded generator code in their project\n- generate api documentation and add better comments\n- support signed/unsigned and big/little endian for _everything_ (right now i'm assuming unsigned for bits)\n- add library comparison chart\n- add benchmarks and make performance improvements\n- add \"assertion\" logic\n  - assert at EOF after reading (optional)\n  - add `.assert(data =\u003e data.foo === 'must be this value')` to api\n- add seek/pointer logic\n- let `toArray()` take a funtion instead of a number as the only parameter (potentially other objects that take a length: `string()` and `buffer()` etc)\n- add `typedarray` logic (maybe things like `uint8array()`)\n- can we ever support `toArray()` being called on `bits()`?\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fskratchdot%2Fbinary-format","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fskratchdot%2Fbinary-format","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fskratchdot%2Fbinary-format/lists"}