@unikvs/brotli.bun

Middleware that compresses and decompresses with Bun Brotli support, falling back to node:zlib.

Overview

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

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

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

Install with:

npm install @unikvs/brotli.bun @logtape/logtape

pnpm add @unikvs/brotli.bun @logtape/logtape

yarn add @unikvs/brotli.bun @logtape/logtape

bun add @unikvs/brotli.bun @logtape/logtape

nub add @unikvs/brotli.bun @logtape/logtape

aube add @unikvs/brotli.bun @logtape/logtape

Usage

BrotliBun implements IMiddleware. Pass it to UniKvs with use().

import { BrotliBun } from "@unikvs/brotli.bun";

Constructor arguments:

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

import { BrotliBun } from "@unikvs/brotli.bun";
import { Memory } from "@unikvs/memory";
import * as unikvs from "unikvs";

const kvs = new unikvs.Builder<{ foo: unikvs.Value<Uint8Array> }>()
  .use(new BrotliBun({ level: 11 }))
  .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

• encode compresses input bytes with Brotli.
• decode decompresses input bytes with Brotli.
• 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 Brotli API, stream handling is batched rather than converted chunk by chunk.

Errors

Errors thrown by this package:

BrotliBunInvalidLevelError

Meaning

The constructor throws this error when level is not an integer from 0 to 11.

How to fix

Specify an integer from 0 to 11. It defaults to 11 when omitted.

Example

The following example catches BrotliBunInvalidLevelError.

import { BrotliBun, BrotliBunInvalidLevelError } from "@unikvs/brotli.bun";

try {
  new BrotliBun({ level: -1 });
} catch (ex) {
  if (ex instanceof BrotliBunInvalidLevelError) {
    console.log(ex.meta); // { actual: -1 }
  } else {
    throw ex;
  }
}

If open() fails to resolve the runtime, this middleware throws UnsupportedRuntimeError. Calling encode or similar before open() throws a TypeError. Decompression failures propagate the upstream error unchanged.