---
title: "はじめに"
description: "UniKVS のインストールから基本操作までの最短手順を説明します。"
---

## インストール [#install]

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

**メモリーで試す**

```package-install
npm i unikvs @unikvs/memory
```

**ファイルに保存する**

```package-install
npm i unikvs @unikvs/fs.node @unikvs/compression
```

## 基本的な使い方 [#basic-usage]

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

1. **ビルダーを作る**

    `UniKvs.config()` でビルダーを作ります。型パラメーターにキーと値のマッピングを指定します。

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

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

2. **保存先を追加して作る**

    `appendStorage()` で保存先を追加し、`create()` でクライアントを作ります。トランスフォーマーが不要なら省略できます。

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

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

3. **開いて操作する**

    `open()` で初期化し、`set`・`get`・`has`・`delete` などを操作します。

    ```ts
    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");
    ```

4. **閉じる**

    使い終わったら `close()` で終了します。

    ```ts
    await kvs.close();
    ```

:::tip
`appendTransformer()` は `appendStorage()` の前後どちらにも追加できます。ストレージ登録後に追加した分は、その後に登録するストレージにだけ適用します。詳しくは基本概念のパイプラインを参照してください。
:::

## トランスフォーマーを足す [#add-transformer]

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

```ts
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` は変えずに、保存時の圧縮と取得時の展開を自動で行います。

:::warning
`appendStorage()` なしで `create()` すると `MissingStorageError` を投げます。ストレージ登録は必須です。
:::

## 入力値を検証する [#validate-values]

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

```ts
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` を投げます。動的キーには配列形式も使えます。詳しくは基本概念のスキーマ定義と検証のタイミングを参照してください。

## 次の手順 [#next-steps]

**[基本概念](/unikvs/ja/concepts)**

アーキテクチャーと値の型の仕組みを理解します。

**[ストレージ比較](/unikvs/ja/reference/comparison)**

保存先の選び方を確認します。