---
title: "@unikvs/lru-cache"
description: "@unikvs/lru-cache の LruCache。上限付きで任意の値を保持する LRU ストレージの使い方を説明します。"
---

## 概要 [#overview]

`@unikvs/lru-cache` は上限付きで任意の値をメモリーに保持する LRU ストレージです。直近に使った値を残して古いものから追い出すため、キャッシュに使います。

- `name` は `LruCache` です。
- `open`・`close` が必要です。`close` は保存値をすべて破棄します。
- `maxEntries`・`maxBytes` で上限を指定します。どちらも省略できます。
- `size` で件数を、`bytes` でバイト数（`maxBytes` 設定時）を確認できます。

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

```package-install
npm install @unikvs/lru-cache
```

## 使い方 [#usage]

LruCache は IStorage を実装しています。UniKvs には persist() で渡します。

```ts
import { LruCache } from "@unikvs/lru-cache";
```

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

| Prop | Type | Default | Description |
| - | - | - | - |
| `clone?` | `[#clone] (<T>(value: T) => T) \| undefined` | `structuredClone` | データの複製に使う関数です。省略した場合は structuredClone を使います。 |
| `maxEntries?` | `[#max-entries] number \| undefined` | - | 保持する最大件数です。0 以上の整数を指定します。 |
| `maxBytes?` | `[#max-bytes] number \| undefined` | - | 保持する最大バイト数です。0 以上の有限数を指定します。 |
| `sizeOf?` | `[#size-of] ((value: any, key: string) => number) \| undefined` | - | キーごとのバイト数を決める関数です。省略した場合は Uint8Array で byteLength、それ以外で 1 を使います。 |

以下は、件数に上限を付けて値を保存する例です。

```ts
import { LruCache } from "@unikvs/lru-cache";
import * as unikvs from "unikvs";

const kvs = new unikvs.Builder<{
  greeting: unikvs.PlainValue<string>;
}>()
  .persist(new LruCache({ maxEntries: 100 }))
  .build();

await kvs.open();
await kvs.set("greeting", "hello");

const value = await kvs.get("greeting");
console.log(value); // "hello"

await kvs.close();
```

## データ型 [#data-types]

| 操作                                    | 対応するデータ型                     |
| --------------------------------------- | ------------------------------------ |
| `write`・`read`                         | 任意の値（文字列・オブジェクトなど） |
| `getWritable`・`getReadable` のチャンク | `Uint8Array<ArrayBuffer>`            |

- 任意の値を保存できます。文字列やオブジェクトなど、`structuredClone` で複製できる値を扱います。
- 読み書きする値は既定では `structuredClone` で複製します。複製方法はコンストラクターの `clone` で変更できます。
- `maxEntries` を超えたときは、直近に使っていないキーから追い出します。`maxEntries` が `0` の場合は何も保存しません。
- `maxBytes` を設定した場合は、合計バイト数が上限を超えないよう古いキーから追い出します。
- ストリームのチャンクは `Uint8Array<ArrayBuffer>` のみに対応します。
- `getWritable` で取得したストリームは、書き込まれたチャンクを結合し、`close` 時に保存します。
- `getReadable` で取得したストリームは、保存値を単一チャンクとして送出します。保存値が `Uint8Array` でない場合は `InvalidChunkTypeError` を投げます。

## エラー [#errors]

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

### KeyNotFoundError [#key-not-found-error]

#### 意味

指定したキーが存在しない場合に投げます。`@unikvs/core` の共通エラーです。

#### 対処方法

`exists` で確認してから読み出してください。

#### 例

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

```ts
import { KeyNotFoundError } from "@unikvs/lru-cache";

try {
  await kvs.get("missing-key");
} catch (ex) {
  if (ex instanceof KeyNotFoundError) {
    console.log("キーが見つかりません");
  } else {
    throw ex;
  }
}
```

### InvalidChunkTypeError [#invalid-chunk-type-error]

| Prop | Type | Default | Description |
| - | - | - | - |
| `key` | `[#invalid-chunk-type-key] string` | - | 操作対象のキーです。 |
| `chunk` | `[#invalid-chunk-type-chunk] unknown` | - | 受け取ったチャンクの値です。 |
| `chunkType` | `[#invalid-chunk-type-chunk-type] string` | - | 受け取ったチャンクの型名です。 |

#### 意味

ストリームに `Uint8Array<ArrayBuffer>` 以外のチャンクを書き込んだ場合や、保存値が `Uint8Array` でないのに `getReadable` を呼んだ場合に投げます。

#### 対処方法

ストリームには `Uint8Array` のチャンクを書き込んでください。`getReadable` を使う値はバイト列で保存してください。

### InvalidMaxEntriesError [#invalid-max-entries-error]

| Prop | Type | Default | Description |
| - | - | - | - |
| `actual` | `[#invalid-max-entries-actual] unknown` | - | 指定された maxEntries の値です。 |

#### 意味

コンストラクターの `maxEntries` が 0 以上の整数でない場合に投げます。

#### 対処方法

`maxEntries` に 0 以上の整数を指定してください。

### InvalidMaxBytesError [#invalid-max-bytes-error]

| Prop | Type | Default | Description |
| - | - | - | - |
| `actual` | `[#invalid-max-bytes-actual] unknown` | - | 指定された maxBytes の値です。 |

#### 意味

コンストラクターの `maxBytes` が 0 以上の有限数でない場合に投げます。

#### 対処方法

`maxBytes` に 0 以上の有限数を指定してください。

### InvalidSizeOfResultError [#invalid-size-of-result-error]

| Prop | Type | Default | Description |
| - | - | - | - |
| `key` | `[#invalid-size-of-result-key] string` | - | 操作対象のキーです。 |
| `actual` | `[#invalid-size-of-result-actual] unknown` | - | sizeOf が返した値です。 |

#### 意味

`sizeOf` の戻り値が 0 以上の有限数でない場合に投げます。

#### 対処方法

`sizeOf` が 0 以上の有限数を返すように修正してください。