Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/obusk/walkable-buffer
🚶🛡️ A class for easily reading data from binary Buffers
https://github.com/obusk/walkable-buffer
binary binary-buffers buffer node
Last synced: about 1 month ago
JSON representation
🚶🛡️ A class for easily reading data from binary Buffers
- Host: GitHub
- URL: https://github.com/obusk/walkable-buffer
- Owner: oBusk
- License: mit
- Created: 2018-06-28T20:37:08.000Z (over 6 years ago)
- Default Branch: main
- Last Pushed: 2024-07-23T11:35:48.000Z (5 months ago)
- Last Synced: 2024-11-07T09:30:40.240Z (about 2 months ago)
- Topics: binary, binary-buffers, buffer, node
- Language: TypeScript
- Homepage:
- Size: 1.49 MB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Walkable Buffer
[](https://www.npmjs.com/package/walkable-buffer)
[](https://github.com/oBusk/walkable-buffer/actions?query=workflow%3A%22Node.js+CI%22)
[](https://github.com/oBusk/walkable-buffer/actions?query=workflow%3ACodeQL)
[](https://github.com/oBusk/walkable-buffer/network/updates)
[](https://codecov.io/gh/oBusk/walkable-buffer)
[](https://bundlephobia.com/result?p=walkable-buffer)
[](https://bundlewatch.io)
[](https://github.com/prettier/prettier)
> 🚶🛡️ A class for easily reading data from binary Buffers
## Install
```bash
npm install walkable-buffer
```
- [Supported Node versions](./package.json#L20) aim to be
[Latest current and LTS](https://nodejs.org/en/download/releases/) as well as trying to keep up to date
with the latest supported node in
[Google cloud functions](https://cloud.google.com/functions/docs/concepts/nodejs-runtime).
## Usage
- [Instance defaults](#instance-defaults)
- [Defaults in Constructor](#defaults-in-constructor)
- [Set/get defaults on existing instance](#setget-defaults-on-existing-instance)
- [Cursor](#cursor)
- [`initialCursor` in constructor](#initialcursor-in-constructor)
- [Manipulage Cursor](#manipulate-cursor)
- [Read Integers](#read-integers)
- [Read Strings](#read-strings)
- [Buffer](#buffer)
- [Size](#size)
```js
import fs from "fs";
import WalkableBuffer from "walkable-buffer";
const buffer = fs.readFileSync("./temp");
const wb = new WalkableBuffer({
buffer,
// Set instance defaults for `endianness`, `encoding` and `signed`
// The instance default can be overridden for each operation
endianness: "LE",
encoding: "utf8",
signed: true,
});
const v = wb.get(
6 /* byteLength */,
"BE" /* endianness - Override instance default for this operation */,
); // => 140 737 488 355 327
const s = wb.getString(
16 /* byteLength */,
"utf16le" /* encoding - overrides instance default */,
); // => "Hellö höw åre yö"
const b = wb.getBigInt(
null /* endianness - null/undefined to use instance default */,
false /* signed - override isntance default */,
); // 18_446_744_073_709_551_615n
```
### Instance defaults
The instance defaults include `endianness`, `encoding` and `signed` controlling how to read the binary
data into integers and text.
The effect of this is that the operations `get`/`peek` - `BigInt`/`String`/`SizedString` will use the
configured settings if none is provided.
| Config | Default Value |
| :----------: | :----------------------: |
| `endianness` | `"LE"` |
| `encoding` | `"utf8"` |
| `signed` | `true` (Signed integers) |
#### Defaults in Constructor
You can set the instance defaults when creating the instance by configuring it in the
[`WalkableBufferOptions`](src/WalkableBufferOptions.ts) provided to the constructor.
```js
import WalkableBuffer from "walkable-buffer";
const wb = new WalkableBuffer({
buffer,
endianness: "LE",
encoding: "utf8",
signed: true,
});
```
#### Set/get defaults on existing instance
You can also use `set`/`get` - `Endianness`/`Encoding`/`Signed`.
```js
import WalkableBuffer from "walkable-buffer";
const wb = new WalkableBuffer({ buffer });
wb.getEndianness(); // => "LE" (the default)
wb.setEndianness("BE");
wb.getEndianness(); // => "BE"
wb.getEncoding(); // "utf8" (the default)
wb.setEncoding("ascii");
wb.getEncoding(); // => "ascii"
wb.getSigned(); // true (for signed integers, the default)
wb.setSigned(false);
wb.getSigned(); // false (for unsigned integers)
```
### Cursor
The "cursor" is the byteOffset that the walkable buffer has currently "walked". It is the default
position to read data from, and it advances whenever a `get` operation is completed successfully.
By default, the WalkableBuffer will start with the cursor at `0`.
#### `initialCursor` in constructor
```js
import WalkableBuffer from "walkable-buffer";
const wb = new WalkableBuffer({
buffer,
initialCursor: 8, // First `get` operation will start at byteOffset 8
});
```
#### Manipulate Cursor
The following "walking" operations will advance the cursor to the first byte after data is read:
- `get()`
- `getBigInt()`
- `getString()`
- `getSizedString()`
The following operations will read data _without_ manipulating the cursor:
- `peek()`
- `peekBigInt()`
- `peekString()`
- `peekSizedString()`
To manipulate the position of the cursor you can also
- `skip(byteLength)` to skip `byteLength` of bytes.
- `goTo(byteOffset)` to move cursor to a specific offset of the buffer.
And to get the current position of the cursor, use `getCurrentPos()`.
### Read Integers
- `get(byteLength, endianness, signed)` - Read `byteLength` as a signed/unsigned integer,
reading with `endianness`, and advancing cursor `byteLength`.
- `peek(byteLength, byteOffset, endianness, signed)` - Read `byteLength` at cursor + `byteOffset` as a
signed/unsigned integer, _without_ manipulating the cursor.
- `getBigInt(endianness, signed)` - Read the next 8 bytes as a signed/unsigned
[BigInt](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt)
, reading with `endianness`, and advancing cursor 8 steps.
- `peekBigInt(byteOffset, endianness, signed)` - Read 8 bytes at `byteOffset` as a signed/unsigned
[BigInt](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt)
, reading with `endianness`, _without_ manipulating the cursor.
### Read Strings
- `getString(byteLength, encoding)` - Read the next `byteLength` bytes as a string, using `encoding`,
and advances cursor `byteLength`.
- `peekString(byteLength, byteOffset, encoding)` - Read the `byteLength` bytes at
cursor - `byteOffset` as a string, using `encoding`, _without_ manipulating the cursor.
- `getSizedString(sizeOfSize, endianness, encoding)` - Read the next `sizeOfSize` as an _unsigned_
integer with `endianness` to get byte-length, then reads that many bytes as a string with `encoding`.
### Buffer
You can get the entire Buffer of WalkableBuffer back by running `getSourceBuffer()`.
You can also get Buffer of a specific `byteLength` from current cursor by running
`getBuffer(byteLength)`. If called without `byteLength`, returns a buffer being a split from
current cursor position to end of buffer.
### Size
You can get the size of the Buffer with `size()`, and get the number of bytes from current cursor
position to the end of the buffer, `sizeRemainingBuffer()`.
## License
MIT © Oscar Busk