API reference › @evolu/common › Buffer › Buffer

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

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. 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

import {
  createBuffer,
  createIdFromString,
  IdBytes,
  idBytesToId,
  idBytesTypeValueLength,
  idToIdBytes,
  NonNegativeInt,
} from "@evolu/common";
import {
  decodeNonNegativeInt,
  encodeNonNegativeInt,
} from "@evolu/common/local-first";

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

const decoder = createBuffer(buffer.unwrap());
expect(decodeNonNegativeInt(decoder)).toBe(300);
const decodedId = idBytesToId(
  IdBytes.orThrow(decoder.shiftN(idBytesTypeValueLength)),
);
expect(decodedId).toBe(id);
expect(() => decodeNonNegativeInt(decoder)).toThrow(
  "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/Buffer.ts:98

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

getCapacity

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

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

Returns the current capacity of the buffer.

getLength

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

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

Returns the current number of bytes stored in the buffer.

reset

reset: () => void;

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

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/Buffer.ts:104

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/Buffer.ts:110

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/Buffer.ts:116

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/Buffer.ts:132

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