---
title: "@unikvs/zstd.bun"
description: "Middleware that compresses and decompresses with Bun Zstandard support, falling back to node:zlib."
---

## Overview [#overview]

`@unikvs/zstd.bun` is a plugin that compresses bytes with Zstandard for storage and decompresses them on read. Middleware

On the Bun runtime it uses `Bun.zstdCompressSync` and `Bun.zstdDecompressSync`, and falls back to `node:zlib` Zstandard support elsewhere. Use it when targeting Bun while keeping Node.js-compatible environments working.

- `name` is `ZstdBun`.
- `isOpen` becomes `true` after `open()`. It is `false` initially.
- `open()` lazily resolves the runtime, sharing the result across instances.

Install with:

```package-install
npm install @unikvs/zstd.bun @logtape/logtape
```

## Usage [#usage]

`ZstdBun` implements IMiddleware. Pass it to UniKvs with use().

```ts
import { ZstdBun } from "@unikvs/zstd.bun";
```

Constructor arguments:

| Prop | Type | Default | Description |
| - | - | - | - |
| `level?` | `[#level] number \| undefined` | - | Compression level. Specify an integer from 1 to 22. Higher values compress better but take longer. Defaults to 3 when omitted. |

The following example compresses written values with Zstandard for storage and decompresses them on read.

```ts
import { Memory } from "@unikvs/memory";
import * as unikvs from "unikvs";
import { ZstdBun } from "@unikvs/zstd.bun";

const kvs = new unikvs.Builder<{ foo: unikvs.Value<Uint8Array> }>()
  .use(new ZstdBun({ level: 3 }))
  .persist(new Memory())
  .build();

await kvs.open();
await kvs.set("foo", new Uint8Array([0, 1, 2]));

const bytes = await kvs.get("foo");
console.log(bytes); // Decompressed bytes

await kvs.close();
```

## Data types [#data-types]

| Method         | Input                     | Output                    |
| -------------- | ------------------------- | ------------------------- |
| `encode`       | `Uint8Array<ArrayBuffer>` | `Uint8Array<ArrayBuffer>` |
| `decode`       | `Uint8Array<ArrayBuffer>` | `Uint8Array<ArrayBuffer>` |
| `encodeStream` | `Uint8Array<ArrayBuffer>` | `Uint8Array<ArrayBuffer>` |
| `decodeStream` | `Uint8Array<ArrayBuffer>` | `Uint8Array<ArrayBuffer>` |

- `encode` compresses input bytes with Zstandard.
- `decode` decompresses input bytes with Zstandard.
- `encodeStream` accumulates input chunks and compresses them at once on `flush`, emitting one chunk.
- `decodeStream` accumulates input chunks and decompresses them at once on `flush`, emitting one chunk.
- Because there is no streaming Zstandard API, stream handling is batched rather than converted chunk by chunk.

## Errors [#errors]

Errors thrown by this package:

### `ZstdBunInvalidLevelError` [#error-zstd-bun-invalid-level]

| Prop | Type | Default | Description |
| - | - | - | - |
| `actual` | `[#zstd-bun-invalid-level-actual] unknown` | - | The specified compression level. |

#### Meaning

The constructor throws this error when `level` is not an integer from 1 to 22.

#### How to fix

Specify an integer from 1 to 22. It defaults to 3 when omitted.

#### Example

The following example catches `ZstdBunInvalidLevelError`.

```ts
import { ZstdBun, ZstdBunInvalidLevelError } from "@unikvs/zstd.bun";

try {
  new ZstdBun({ level: 23 });
} catch (ex) {
  if (ex instanceof ZstdBunInvalidLevelError) {
    console.log(ex.meta); // { actual: 23 }
  } else {
    throw ex;
  }
}
```

If `open()` fails to resolve the runtime, this middleware throws [`UnsupportedRuntimeError`](/unikvs/en/packages/core/errors#error-unsupported-runtime). Calling `encode` or similar before `open()` throws a `TypeError`. Decompression failures propagate the upstream error unchanged.