Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/skratchdot/binary-format
a typescript library for reading and writing binary files to and from plain javascript objects
https://github.com/skratchdot/binary-format
Last synced: 3 months ago
JSON representation
a typescript library for reading and writing binary files to and from plain javascript objects
- Host: GitHub
- URL: https://github.com/skratchdot/binary-format
- Owner: skratchdot
- License: mit
- Created: 2021-07-18T20:39:51.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2023-07-09T18:59:37.000Z (over 1 year ago)
- Last Synced: 2024-10-13T01:38:03.515Z (3 months ago)
- Language: TypeScript
- Size: 666 KB
- Stars: 5
- Watchers: 3
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# binary-format
a typescript library for reading and writing binary files to and from plain javascript objects.
there is a plethora of exiting libraries that accomplish the same goal, but all come with tradeoffs.
i am trading some speed in favor or using "plain" javascript objects that immer supports because i wanted
to use immutable data structures while working on an online editor that supports the editing of various
file formats.
## quick start
```typescript
import BinaryFormat from '@skratchdot/binary-format';
const helloWorldParser = new BinaryFormat<{
hello: string;
asciiSpace: number;
world: string;
asciiExclaimation: number;
}>()
.string('hello', 5)
.uint8('asciiSpace')
.string('world', 5)
.uint8('asciiExclaimation')
.done();
const buffer = Buffer.from('hello world!');
const readResult = helloWorldParser.read(buffer);
const writeResult = helloWorldParser.write(readResult);
console.log({ readResult, writeResult });
/*
{
readResult: {
hello: 'hello',
asciiSpace: 32,
world: 'world',
asciiExclaimation: 33
},
writeResult:
}
*/
```
## features
- written in typescript
- supports both reading and writing of binary files
- supports formatting to/from "plain" javascript objects (that are serializable and supported via immutability libs like `immer`)
- supports formatting to/from "complex" javascript objects like typed arrays and buffers
## documentation
coming soon. for now check out the examples folder or the unit tests
#### Custom
```typescript
export const stringWithLength = (length: number): ReadAndWrite => ({
read: (r: SmartBuffer) => r.readString(length),
write: (w: SmartBuffer, v: unknown) => w.writeString(String(v), length),
});
```
## see also
#### parsing libs
- https://github.com/keichi/binary-parser
- https://github.com/anfema/bin-grammar
- https://github.com/substack/node-binary
- https://github.com/reklatsmasters/binary-data
- https://github.com/foliojs/restructure
- https://kaitai.io/
- https://github.com/lammas/bin-format
- https://github.com/RobertBorg/node-BinaryFormat
- https://www.npmjs.com/package/memory-efficient-object
- https://www.npmjs.com/package/@astronautlabs/bitstream?activeTab=readme
#### buffer libs:
- https://github.com/inolen/bit-buffer
- https://github.com/feross/buffer
- https://github.com/JoshGlazebrook/smart-buffer
- https://github.com/fredricrylander/bits
- https://github.com/uupaa/Bit.js/
- https://github.com/FlorianWendelborn/bitwise
- https://github.com/steinwurf/bitter (c library)
- https://www.npmjs.com/package/node-bit-stream
- https://github.com/thi-ng/umbrella/tree/develop/packages/bitstream
- https://github.com/conekt/bitsandbytes
- https://www.npmjs.com/package/bits-bytes (pack and unpack)
- https://github.com/francisrstokes/construct-js
- https://github.com/rochars/byte-data
## todos
- detect cycles
- add streaming support
- add example parsers
- remove all dependencies
- update BinaryBuffer so it supports all the functionality of bit-buffer and smart-buffer (with bit/byte offset logic)
- consider "export parser" so endusers don't need to include unneeded generator code in their project
- generate api documentation and add better comments
- support signed/unsigned and big/little endian for _everything_ (right now i'm assuming unsigned for bits)
- add library comparison chart
- add benchmarks and make performance improvements
- add "assertion" logic
- assert at EOF after reading (optional)
- add `.assert(data => data.foo === 'must be this value')` to api
- add seek/pointer logic
- let `toArray()` take a funtion instead of a number as the only parameter (potentially other objects that take a length: `string()` and `buffer()` etc)
- add `typedarray` logic (maybe things like `uint8array()`)
- can we ever support `toArray()` being called on `bits()`?