API reference › @evolu/common › Bytes › Buffer

Defined in: packages/common/src/Bytes.ts:259

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.

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.

Example

import {
  assertEqual,
  assertErr,
  assertInstanceOf,
  createBuffer,
  createIdFromString,
  IdBytes,
  idBytesToId,
  idBytesTypeValueLength,
  idToIdBytes,
  NonNegativeInt,
  trySync,
  decodeNonNegativeInt,
  encodeNonNegativeInt,
} from "@evolu/common";

const buffer = createBuffer();
const id = createIdFromString("buffer-example");
encodeNonNegativeInt(buffer, NonNegativeInt.orThrow(300));
buffer.extend(idToIdBytes(id));

const decoder = createBuffer(buffer.unwrap());
assertEqual(decodeNonNegativeInt(decoder), 300);
const decodedId = idBytesToId(
  IdBytes.orThrow(decoder.shiftN(idBytesTypeValueLength)),
);
assertEqual(decodedId, id);
const result = trySync(() => decodeNonNegativeInt(decoder));
assertErr(result);
assertInstanceOf(result.error, Error);
assertEqual(result.error.message, "Buffer parse ended prematurely");

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

Properties

extend

readonly extend: (arg: Uint8Array<ArrayBufferLike> | ArrayLike<number>) => void;

Defined in: packages/common/src/Bytes.ts:270

Appends binary data to the buffer, resizing if necessary. Throws if arg.length is not a non-negative safe integer.

getCapacity

readonly getCapacity: () => number & Brand<"NonNaN"> & Brand<"Finite"> & Brand<"Int"> & Brand<"NonNegative">;

Defined in: packages/common/src/Bytes.ts:261

Returns the current capacity of the buffer.

getLength

readonly getLength: () => number & Brand<"NonNaN"> & Brand<"Finite"> & Brand<"Int"> & Brand<"NonNegative">;

Defined in: packages/common/src/Bytes.ts:264

Returns the current number of bytes stored in the buffer.

reset

readonly reset: () => void;

Defined in: packages/common/src/Bytes.ts:297

Resets the buffer to its initial empty state, preserving its capacity.

This allows efficient buffer reuse without reallocating memory. Use this when you want to clear the buffer and write new data, avoiding unnecessary allocations.

shift

readonly shift: () => number & Brand<"NonNaN"> & Brand<"Finite"> & Brand<"Int"> & Brand<"NonNegative">;

Defined in: packages/common/src/Bytes.ts:276

Removes and returns the first byte. Throws an Error with message "Buffer parse ended prematurely" if the buffer is empty.

shiftN

readonly shiftN: (n: number & Brand<"NonNaN"> & Brand<"Finite"> & Brand<"Int"> & Brand<"NonNegative">) => Uint8Array;

Defined in: packages/common/src/Bytes.ts:282

Removes and returns the first n bytes. Throws an Error with message "Buffer parse ended prematurely" if fewer than n bytes remain.

truncate

readonly truncate: (length: number & Brand<"NonNaN"> & Brand<"Finite"> & Brand<"Int"> & Brand<"NonNegative">) => void;

Defined in: packages/common/src/Bytes.ts:288

Truncates the buffer to the specified length, discarding data from the end. Throws if the new length is greater than the current length.

unwrap

readonly unwrap: () => Uint8Array;

Defined in: packages/common/src/Bytes.ts:304

Returns a view of the buffer’s current data. Do not modify this array, as it directly alters the buffer’s internal state, potentially breaking subsequent operations.

Markdown for LLMs