# @platformatic/dynamic-buffer > A small utility class to work with logically contiguous binary data split across multiple Buffer chunks. Latest version **0.4.0** (published 2026-06-19) · Apache-2.0 license · 0 weekly downloads ## Install ```sh npm install @platformatic/dynamic-buffer pnpm add @platformatic/dynamic-buffer yarn add @platformatic/dynamic-buffer bun add @platformatic/dynamic-buffer ``` ## Health **Score 75/100 (B)** — status: active. Positive: has types; esm support; no vulnerabilities; has provenance; recently updated; high maintenance score; high quality score. Warnings: low downloads; pre 1.0. ## Facts | | | |---|---| | Version | 0.4.0 | | Published | 2026-06-19 | | First published | 2026-02-19 | | Weekly downloads | 0 | | License | Apache-2.0 | | TypeScript types | bundled | | Module format | ESM | | Node | >= 22.19.0 | | Dependencies | 0 | | Unpacked size | 43 KB | | Known vulnerabilities | 0 | | Install scripts | no | | Provenance | attested (GitHub Actions) | | GitHub stars | 17 | | Author | Platformatic Inc. (https://platformatic.dev) | | Maintainers | mzugm, ivan-tymoshenko, marcopiraccini, leorossi, shogun_panda, matteo.collina, qard, lucamaraschi | ## Links - npm: https://www.npmjs.com/package/@platformatic/dynamic-buffer - Repository: https://github.com/platformatic/dynamic-buffer - Issues: https://github.com/platformatic/dynamic-buffer/issues - npm.io page: https://npm.io/package/@platformatic/dynamic-buffer ## Recent versions - 0.4.0 (latest) — 2026-06-19 - 0.3.1 — 2026-02-28 - 0.3.0 — 2026-02-19 - 0.0.1 — 2026-02-19 ## README # @platformatic/dynamic-buffer A fast, efficient list of `Buffer` objects optimized for reading and writing across multiple binary chunks without unnecessary copying. `DynamicBuffer` lets you append/prepend chunks, read values across chunk boundaries, and encode/decode varints without manually concatenating buffers every time. ## Installation ```bash npm i @platformatic/dynamic-buffer ``` ## Features - **Zero-copy operations**: read and write across buffer boundaries without eagerly concatenating - **Buffer-compatible API**: familiar methods mirroring Node.js `Buffer` - **Variable-length integers**: built-in unsigned varint and zig-zag varint support - **Memory efficient**: internal chunks are only concatenated when explicitly requested - **TypeScript ready**: exports type definitions ## Quick start ```ts import { DynamicBuffer } from '@platformatic/dynamic-buffer' const db = new DynamicBuffer([Buffer.from([1, 2]), Buffer.from([3, 4, 5])]) // Read across boundaries console.log(db.readUInt16BE(1)) // bytes [2, 3] // Append data db.append(Buffer.from([6, 7, 8])) // Contiguous buffer view (concatenates on access) console.log(db.buffer) // ``` ## API reference ### Exports - `DynamicBuffer` - `DynamicBufferReadable` - `OutOfBoundsError` ### Constructor #### `new DynamicBuffer([buffers])` Creates a new `DynamicBuffer` instance. - `buffers` (`Buffer | Buffer[]`): optional initial buffer(s) ```ts const db1 = new DynamicBuffer() const db2 = new DynamicBuffer(Buffer.from([1, 2, 3])) const db3 = new DynamicBuffer([Buffer.from([1]), Buffer.from([2, 3])]) ``` ### Properties #### `length` Total length (in bytes) across all internal buffers. #### `buffer` Returns a contiguous `Buffer` of all internal chunks. - Returns the original chunk when there is only one buffer - Concatenates only when there are multiple chunks #### `buffers` Direct access to internal chunks (`Buffer[]`). Use with caution. ### Static methods #### `DynamicBuffer.isDynamicBuffer(obj)` Checks whether a value is a `DynamicBuffer` instance. ```ts DynamicBuffer.isDynamicBuffer(new DynamicBuffer()) // true DynamicBuffer.isDynamicBuffer(Buffer.from([1, 2])) // false ``` ### Buffer management #### `append(buffer)` Appends a chunk. Returns `this`. #### `prepend(buffer)` Prepends a chunk. Returns `this`. #### `appendFrom(dynamicBuffer)` Appends chunks from another `DynamicBuffer`. Returns `this`. #### `prependFrom(dynamicBuffer)` Prepends chunks from another `DynamicBuffer`. Returns `this`. #### `asReadable()` Returns a `DynamicBufferReadable` stream over the current chunks. - Streams chunks without concatenating them - Snapshots the chunk list when called, so later `append` or `prepend` calls do not affect the stream ### Data access #### `get(offset)` Returns the byte at `offset`. #### `slice(start, end)` Returns a `Buffer` for the selected range. #### `subarray(start, end)` Returns a new `DynamicBuffer` for the selected range. #### `toString(encoding, start, end)` Converts a selected range to string. ### Buffer operations #### `clone(deep = false)` Creates a copy of the `DynamicBuffer`. - `deep = false`: copies the chunk list only (shared chunk references) - `deep = true`: clones each chunk via `Buffer.slice()` #### `consume(offset)` Consumes bytes from the front up to `offset`. Returns `this`. ### Reading methods All read methods support an optional `offset` (default `0`, except varints where offset is required). #### Integer reading - `readUInt8`, `readUInt16BE`, `readUInt16LE`, `readUInt32BE`, `readUInt32LE` - `readInt8`, `readInt16BE`, `readInt16LE`, `readInt32BE`, `readInt32LE` - `readBigUInt64BE`, `readBigUInt64LE` - `readBigInt64BE`, `readBigInt64LE` #### Floating-point reading - `readFloatBE`, `readFloatLE` - `readDoubleBE`, `readDoubleLE` #### Variable-length integer reading Returns a tuple: `[value, bytesRead]` - `readUnsignedVarInt(offset): [number, number]` - `readUnsignedVarInt64(offset): [bigint, number]` - `readVarInt(offset): [number, number]` (zig-zag decoded) - `readVarInt64(offset): [bigint, number]` (zig-zag decoded) ### Writing methods Most write methods accept `append = true` (when `false`, data is prepended) and return `this`. #### Integer writing - `writeUInt8`, `writeUInt16BE`, `writeUInt16LE`, `writeUInt32BE`, `writeUInt32LE` - `writeInt8`, `writeInt16BE`, `writeInt16LE`, `writeInt32BE`, `writeInt32LE` - `writeBigUInt64BE`, `writeBigUInt64LE` - `writeBigInt64BE`, `writeBigInt64LE` #### Floating-point writing - `writeFloatBE`, `writeFloatLE` - `writeDoubleBE`, `writeDoubleLE` #### Variable-length integer writing - `writeUnsignedVarInt(value, append)` - `writeUnsignedVarInt64(value, append)` - `writeVarInt(value, append)` (zig-zag encoded) - `writeVarInt64(value, append)` (zig-zag encoded) > Note: varint write methods append/prepend encoded bytes but do not return `this`. ## Examples ### Building a protocol message ```ts import { DynamicBuffer } from '@platformatic/dynamic-buffer' const payload = Buffer.from('hello') const message = new DynamicBuffer() message.writeUInt32BE(0x12345678) // magic message.writeUInt16BE(1) // version message.writeVarInt(payload.length) // payload size message.append(payload) socket.write(message.buffer) ``` ### Streaming a dynamic buffer ```ts import { pipeline } from 'node:stream/promises' import { DynamicBuffer } from '@platformatic/dynamic-buffer' const body = new DynamicBuffer([Buffer.from('hello'), Buffer.from(' world')]) await pipeline(body.asReadable(), destination) ``` ### Parsing streaming data ```ts import { DynamicBuffer } from '@platformatic/dynamic-buffer' const parser = new DynamicBuffer() socket.on('data', chunk => { parser.append(chunk) while (parser.length >= 4) { const messageLength = parser.readUInt32BE(0) if (parser.length >= 4 + messageLength) { const message = parser.slice(4, 4 + messageLength) processMessage(message) parser.consume(4 + messageLength) } else { break } } }) ``` ### Working with varints ```ts import { DynamicBuffer } from '@platformatic/dynamic-buffer' const db = new DynamicBuffer() db.writeVarInt(42) db.writeVarInt(-42) db.writeVarInt64(123456789012345n) let offset = 0 const [v1, b1] = db.readVarInt(offset) offset += b1 const [v2, b2] = db.readVarInt(offset) offset += b2 const [v3] = db.readVarInt64(offset) ``` ## Error handling Out-of-range access throws `OutOfBoundsError` with `code: 'OUT_OF_BOUNDS'`. ## License Apache-2.0. See [LICENSE](LICENSE). --- _Source: https://npm.io/package/@platformatic/dynamic-buffer · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._