[API reference](https://evolu.dev/docs/api-reference) › [@evolu/common](https://evolu.dev/docs/api-reference/common) › [Buffer](https://evolu.dev/docs/api-reference/common/Buffer) › Buffer

Defined in: [packages/common/src/Buffer.ts:97](https://github.com/evoluhq/evolu/blob/f9257a718488bcc2c10afa2edb761c0eee5f5410/packages/common/src/Buffer.ts#L97)

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.

### Example

```ts
import {
  assert,
  assertEqual,
  assertErr,
  createBuffer,
  createIdFromString,
  IdBytes,
  idBytesToId,
  idBytesTypeValueLength,
  idToIdBytes,
  NonNegativeInt,
  trySync,
} 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());
assertEqual(decodeNonNegativeInt(decoder), 300);
const decodedId = idBytesToId(
  IdBytes.orThrow(decoder.shiftN(idBytesTypeValueLength)),
);
assertEqual(decodedId, id);
const result = trySync(() => decodeNonNegativeInt(decoder));
assertErr(result);
assert(
  result.error instanceof Error &&
    result.error.message === "Buffer parse ended prematurely",
  "Expected the premature-buffer-end error.",
);
```

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

## Properties

<a id="extend"></a>

### extend

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

Defined in: [packages/common/src/Buffer.ts:108](https://github.com/evoluhq/evolu/blob/f9257a718488bcc2c10afa2edb761c0eee5f5410/packages/common/src/Buffer.ts#L108)

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

### getCapacity

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

Defined in: [packages/common/src/Buffer.ts:99](https://github.com/evoluhq/evolu/blob/f9257a718488bcc2c10afa2edb761c0eee5f5410/packages/common/src/Buffer.ts#L99)

Returns the current capacity of the buffer.

### getLength

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

Defined in: [packages/common/src/Buffer.ts:102](https://github.com/evoluhq/evolu/blob/f9257a718488bcc2c10afa2edb761c0eee5f5410/packages/common/src/Buffer.ts#L102)

Returns the current number of bytes stored in the buffer.

### reset

```ts
reset: () => void;
```

Defined in: [packages/common/src/Buffer.ts:135](https://github.com/evoluhq/evolu/blob/f9257a718488bcc2c10afa2edb761c0eee5f5410/packages/common/src/Buffer.ts#L135)

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

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

Defined in: [packages/common/src/Buffer.ts:114](https://github.com/evoluhq/evolu/blob/f9257a718488bcc2c10afa2edb761c0eee5f5410/packages/common/src/Buffer.ts#L114)

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

### shiftN

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

Defined in: [packages/common/src/Buffer.ts:120](https://github.com/evoluhq/evolu/blob/f9257a718488bcc2c10afa2edb761c0eee5f5410/packages/common/src/Buffer.ts#L120)

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

### truncate

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

Defined in: [packages/common/src/Buffer.ts:126](https://github.com/evoluhq/evolu/blob/f9257a718488bcc2c10afa2edb761c0eee5f5410/packages/common/src/Buffer.ts#L126)

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

### unwrap

```ts
unwrap: () => Uint8Array;
```

Defined in: [packages/common/src/Buffer.ts:142](https://github.com/evoluhq/evolu/blob/f9257a718488bcc2c10afa2edb761c0eee5f5410/packages/common/src/Buffer.ts#L142)

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.