API reference / @evolu/common / Buffer / Buffer

Interface: Buffer

Defined in: packages/common/src/Buffer.ts:65

A Buffer is a dynamic, resizable container for binary data, optimized for scenarios where the final size is unknown. It grows exponentially (doubling its capacity) to minimize memory reallocations and uses subarray for efficient, copy-free data access in methods like unwrap and shift.

Recommended Usage

Create as few Buffers as possible—typically one main Buffer for the final output. Temporary Buffers are allowed when necessary (e.g., for variable-length headers), but avoid excessive allocations. Buffers can be reused within functions by leveraging reset to clear contents while preserving capacity, or truncate to adjust the length to a specific size, reducing the need for new allocations. Pass Buffers to encode* functions to append serialized data and use decode* functions to extract data. Both shift and shiftN throw an BufferError with message "Buffer parse ended prematurely" on failure, as do higher-level decode* functions, providing stack traces for debugging instead of using Result. This avoids allocation overhead in success cases and leverages exceptions' diagnostic benefits.

Example

const buffer = createBuffer();
encodeNonNegativeInt(buffer, someInt);
encodeId(buffer, someId);
const result = buffer.unwrap(); // Final serialized data

// Decoding example (throws on error)
try {
  const num = decodeNonNegativeInt(buffer);
  const id = decodeId(buffer);
} catch (e) {
  console.error(e.stack); // Stack trace for debugging
}

For more on exponential growth, see: https://blog.mozilla.org/nnethercote/2014/11/04/please-grow-your-buffers-exponentially

Properties