@unikvs/vercel-runtime-cache

Vercel のランタイムキャッシュに値を保存する @unikvs/vercel-runtime-cache の使い方を説明します。

概要

@unikvs/vercel-runtime-cache は Vercel のランタイムキャッシュに値を保存するストレージです。

このストレージはランタイムキャッシュを自動検出して使い、見つからなければプロセス内の Map にフォールバックします。どちらの場合も TTL と最大件数による追い出しを行います。

name は VercelRuntimeCache です。
バックエンドを共有するときは namespace を指定してください。namespace を指定した場合、clear は現在のインスタンスが追跡しているキーだけを削除します。同じ名前空間で他のインスタンスやプロセスが書き込んだキーは削除されません。
maxEntries による追い出しと失効したキーの削除は、インスタンスごとの追跡に基づきます。そのため、共有バックエンドは maxEntries を超えるキーを保持することがあります。
バックエンドの追い出しは書き込みが古い順 (FIFO) で、フォールバックの追い出しは最も古く使われた順 (LRU) です。
namespace が空でバックエンドが clear を持つ場合は、clear はバックエンド全体を削除します。
isOpen は常に true です。open()・close() は中断の確認のみ行います。
delete は存在しないキーを指定した場合は KeyNotFoundError を投げます。
ストリームの読み書きに対応しています。

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

npm install @unikvs/vercel-runtime-cache

pnpm add @unikvs/vercel-runtime-cache

yarn add @unikvs/vercel-runtime-cache

bun add @unikvs/vercel-runtime-cache

nub add @unikvs/vercel-runtime-cache

aube add @unikvs/vercel-runtime-cache

使い方

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

import { VercelRuntimeCache } from "@unikvs/vercel-runtime-cache";

`VercelRuntimeCache`

Vercel Runtime Cache を使うストレージです。

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

プロパティ型

ttlSeconds?number

エントリの有効期限 (秒) です。

型number

デフォルト60

maxEntries?number

保持するエントリの最大数です。未指定なら無制限です。バックエンドでは書き込みが古い順 (FIFO)、フォールバックでは最終使用が古い順 (LRU) に追い出します。

型number

namespace?string

バックエンドのキーに付与する名前空間です。複数のストレージで同じバックエンドを共有するときに使います。

型string

デフォルト""

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

値の複製に使用する関数です。既定では structuredClone を使います。

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

backend?VercelRuntimeCacheBackend

使用するバックエンドです。未指定のときは自動検出し、見つからなければプロセス内の Map にフォールバックします。

型VercelRuntimeCacheBackend

now?() => number

現在時刻を返す関数です。テストで時刻を固定するときに使います。

型() => number

以下は、値を保存して読み戻す例です。

import { VercelRuntimeCache } from "@unikvs/vercel-runtime-cache";
import * as unikvs from "unikvs";

const kvs = new unikvs.Builder<{
  foo: unikvs.Value<string>;
}>()
  .persist(new VercelRuntimeCache())
  .build();

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

const data = await kvs.get("foo");
console.log(data); // "hello"

await kvs.close();

データ型

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

任意の値を保存できます。既定では structuredClone で複製するので、structuredClone で複製できる値を扱います。
期限切れのエントリは存在しないものとして扱い、読み取り時に掃除します。
getWritable で取得したストリームは、Uint8Array<ArrayBuffer> のチャンクを蓄積し、close 時にまとめて保存します。
getReadable は保存値が Uint8Array<ArrayBuffer> の場合のみ使えます。

対処方法

exists で確認してから読み出します。

例

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

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

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