@unikvs/lru-cache

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

概要

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

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

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

npm install @unikvs/lru-cache

pnpm add @unikvs/lru-cache

yarn add @unikvs/lru-cache

bun add @unikvs/lru-cache

nub add @unikvs/lru-cache

aube add @unikvs/lru-cache

使い方

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

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

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

プロパティ型

clone?(<T>(value: T) => T) | undefined

データの複製に使う関数です。省略した場合は structuredClone を使います。

型(<T>(value: T) => T) | undefined

デフォルトstructuredClone

maxEntries?number | undefined

保持する最大件数です。0 以上の整数を指定します。

型number | undefined

maxBytes?number | undefined

保持する最大バイト数です。0 以上の有限数を指定します。

型number | undefined

sizeOf?((value: any, key: string) => number) | undefined

キーごとのバイト数を決める関数です。省略した場合は Uint8Array で byteLength、それ以外で 1 を使います。

型((value: any, key: string) => number) | undefined

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

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();

データ型

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

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

エラー

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

KeyNotFoundError

意味

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

対処方法

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

例

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

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

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