@unikvs/zstd.wasm

Middleware that compresses and decompresses with a WebAssembly Zstandard implementation.

Overview

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

It lazily resolves @bokuweb/zstd-wasm via dynamic import and initializes it before use. Use it when you want Zstandard regardless of runtime.

• name is ZstdWasm.
• isOpen becomes true after open(). It is false initially.
• Streaming encodeStream and decodeStream are not provided. Only batched conversion is supported.

Install with:

npm install @unikvs/zstd.wasm @logtape/logtape

pnpm add @unikvs/zstd.wasm @logtape/logtape

yarn add @unikvs/zstd.wasm @logtape/logtape

bun add @unikvs/zstd.wasm @logtape/logtape

nub add @unikvs/zstd.wasm @logtape/logtape

aube add @unikvs/zstd.wasm @logtape/logtape

Usage

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

import { ZstdWasm } from "@unikvs/zstd.wasm";

Constructor arguments:

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

import { Memory } from "@unikvs/memory";
import * as unikvs from "unikvs";
import { ZstdWasm } from "@unikvs/zstd.wasm";

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

• encode compresses input bytes with Zstandard.
• decode decompresses input bytes with Zstandard.
• Streaming encodeStream and decodeStream are not provided.

Errors

Errors thrown by this package:

ZstdWasmInitError

Meaning

Thrown when open() fails to initialize the @bokuweb/zstd-wasm module.

How to fix

Check that @bokuweb/zstd-wasm is installed correctly and that the browser can fetch the WASM file.

Example

The following example catches ZstdWasmInitError.

import { Memory } from "@unikvs/memory";
import * as unikvs from "unikvs";
import { ZstdWasm, ZstdWasmInitError } from "@unikvs/zstd.wasm";

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

try {
  await kvs.open();
} catch (ex) {
  if (ex instanceof ZstdWasmInitError) {
    console.log("Failed to initialize");
  } else {
    throw ex;
  }
}

ZstdWasmInvalidLevelError

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

import { ZstdWasm, ZstdWasmInvalidLevelError } from "@unikvs/zstd.wasm";

try {
  new ZstdWasm({ level: 0 });
} catch (ex) {
  if (ex instanceof ZstdWasmInvalidLevelError) {
    console.log(ex.meta); // { actual: 0 }
  } else {
    throw ex;
  }
}

Calling encode or similar before open() throws a TypeError. Decompression failures propagate the upstream error unchanged.