API reference › @evolu/common › Bytes › Buffer

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

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

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

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

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

getCapacity

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

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

Returns the current capacity of the buffer.

getLength

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

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

Returns the current number of bytes stored in the buffer.

reset

reset: () => void;

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

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

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

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

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

shiftN

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

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

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

truncate

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

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

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

unwrap

unwrap: () => Uint8Array;

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

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