はじめに

UniKVS のインストールから基本操作までの最短手順を説明します。

インストール

unikvs 本体に加えて、利用するストレージやトランスフォーマーのパッケージをインストールします。

npm install unikvs @unikvs/memory

pnpm add unikvs @unikvs/memory

yarn add unikvs @unikvs/memory

bun add unikvs @unikvs/memory

nub add unikvs @unikvs/memory

aube add unikvs @unikvs/memory

npm install unikvs @unikvs/fs.node @unikvs/compression

pnpm add unikvs @unikvs/fs.node @unikvs/compression

yarn add unikvs @unikvs/fs.node @unikvs/compression

bun add unikvs @unikvs/fs.node @unikvs/compression

nub add unikvs @unikvs/fs.node @unikvs/compression

aube add unikvs @unikvs/fs.node @unikvs/compression

基本的な使い方

メモリーストレージを使った最小例です。設定して作成し、開いて操作し、閉じます。

import { UniKvs, type Value } from "unikvs";

const builder = UniKvs.config<{
  foo: Value<Uint8Array>;
}>();

import { Memory } from "@unikvs/memory";

const kvs = builder.appendStorage(new Memory()).create();

await kvs.open();

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

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

console.log(await kvs.has("foo"));

await kvs.delete("foo");

await kvs.close();

トランスフォーマーを足す

圧縮を透過的に行う例です。

import { Compression } from "@unikvs/compression";
import { Memory } from "@unikvs/memory";
import { UniKvs, type Value } from "unikvs";

const kvs = UniKvs.config<{
  foo: Value<Uint8Array>;
}>()
  .appendTransformer(new Compression("gzip"))
  .appendStorage(new Memory())
  .create();

利用側の set・get は変えずに、保存時の圧縮と取得時の展開を自動で行います。

入力値を検証する

UniKvs.config({ schema }) に Valibot スキーマを渡すと、型推論と実行時検証が有効になります。Valibot スキーマを使う場合は valibot を別途インストールします。

import { Memory } from "@unikvs/memory";
import { PlainValue, UniKvs } from "unikvs";
import * as v from "valibot";

const kvs = UniKvs.config({
  schema: {
    foo: PlainValue(v.instance(Uint8Array)),
  },
})
  .appendStorage(new Memory())
  .create();

set の入力検証に失敗すると InvalidInputError を投げ、get の出力検証に失敗すると InvalidOutputError を投げます。動的キーには配列形式も使えます。詳しくは基本概念のスキーマ定義と検証のタイミングを参照してください。

次の手順