@unikvs/zstd.node

Node.js の node:zlib で Zstandard 圧縮と展開を行うミドルウェアです。

概要

@unikvs/zstd.node はバイト列を Zstandard で圧縮して保存し、読み取り時に展開するプラグインです。Middleware Node.js 専用

node:zlib の Zstandard 機能へ委譲するため、このミドルウェアは Node.js ランタイム専用です。書き込んだ値を小さく保ちつつ高速に処理したい場合に使います。

• name は ZstdNode です。
• isOpen は open() 後に true になります。初期状態では false です。
• Node.js ランタイム専用です。このミドルウェアは open() で node:util と node:zlib と node:stream を遅延解決します。

インストールは次のコマンドで行います。

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

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

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

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

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

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

使い方

ZstdNode は IMiddleware を実装しています。UniKvs には use() で渡します。

import { ZstdNode } from "@unikvs/zstd.node";

コンストラクターの引数は次のとおりです。

以下は、書き込んだ値を Zstandard で圧縮して保存し、読み取り時に展開する例です。

import { Memory } from "@unikvs/memory";
import { ZstdNode } from "@unikvs/zstd.node";
import * as unikvs from "unikvs";

const kvs = new unikvs.Builder<{ foo: unikvs.Value<Uint8Array> }>()
  .use(new ZstdNode({ 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); // 展開されたバイト列になります

await kvs.close();

データ型

• encode では入力バイト列を Zstandard で圧縮します。
• decode では入力バイト列を Zstandard で展開します。
• encodeStream では入力ストリームを Zstandard 圧縮ストリームへ接続します。
• decodeStream では入力ストリームを Zstandard 展開ストリームへ接続します。
• node:zlib のストリームが生成したチャンクをそのまま出力し、1 チャンクにはまとめません。

エラー

このパッケージが投げるエラーは次のとおりです。

ZstdNodeInvalidLevelError

意味

コンストラクターは level が 1 から 22 までの整数ではないときに、このエラーを投げます。

対処方法

1 から 22 までの整数を指定してください。省略した場合は 3 になります。

例

以下は、ZstdNodeInvalidLevelError を捕捉する例です。

import { ZstdNode, ZstdNodeInvalidLevelError } from "@unikvs/zstd.node";

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

このミドルウェアは open() で実行環境の解決に失敗した場合は UnsupportedRuntimeError を投げます。open() 前に encode などを呼ぶと TypeError を投げます。展開に失敗した場合は上流のエラーをそのまま伝播します。