@unikvs/cloudflare-cache

Workers の Cache API binding にバイト列を保存する @unikvs/cloudflare-cache の使い方を説明します。

概要

@unikvs/cloudflare-cache は Workers の Cache API binding にバイト列を保存するストレージです。

このストレージはキーを要求 URL に変換し、バイナリーのボディーを持つ応答として put・match・delete で処理します。コンストラクターの cache を省略した場合は caches.default を使います。

• name は CloudflareCache です。
• isOpen は常に true です。open()・close() は中断の確認のみ行います。
• clear には対応していません。Cache API にキーの列挙がないためです。
• ストリームの読み書きに対応しています。

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

npm install @unikvs/cloudflare-cache

pnpm add @unikvs/cloudflare-cache

yarn add @unikvs/cloudflare-cache

bun add @unikvs/cloudflare-cache

nub add @unikvs/cloudflare-cache

aube add @unikvs/cloudflare-cache

使い方

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

import { CloudflareCache } from "@unikvs/cloudflare-cache";

CloudflareCache

Workers の Cache API binding にバイト列を保存するストレージです。

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

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

import { CloudflareCache } from "@unikvs/cloudflare-cache";
import * as unikvs from "unikvs";

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

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

const data = await kvs.get("foo");
console.log(data); // Uint8Array(3) [0, 1, 2]

await kvs.close();

データ型

• バイト列のみを保存できます。文字列やオブジェクトはミドルウェアで変換してから渡してください。
• キーは ${origin}/<符号化キー> の要求 URL に変換されます。
• getWritable で取得したストリームは、チャンクを蓄積し、close 時に一括して保存します。
• getReadable で取得したストリームは、保存した応答のボディーを返します。
• clear には対応していません。キーを 1 件ずつ削除してください。

エラー

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

InvalidOriginError

意味

origin がクエリー・フラグメントなしの絶対 URL ではないときに、構築時に投げます。

対処方法

前後の空白やクエリー・フラグメントを含まない絶対 URL を指定します。

InvalidKeyError

意味

キーを URL パスセグメントとして符号化できないときに投げます。

対処方法

符号化できる文字列をキーに使います。孤立サロゲートを含むキーなどは避けます。

CacheBindingNotFoundError

意味

cache の指定がなく caches.default も存在しないときに、構築時に投げます。

対処方法

cache に Cache binding を渡すか、caches.default があるランタイムで実行します。

CacheOperationError

意味

put・match・delete のいずれかが拒否されたときに投げます。

対処方法

meta.operation で失敗した操作を確認し、cause で原因を調べます。

ClearNotSupportedError

意味

clear() が呼ばれたときに投げます。Cache API にキーの列挙がないため、一括削除には対応していません。

対処方法

キーを 1 件ずつ delete で削除します。

InvalidChunkTypeError

意味

getWritable で取得したストリームに Uint8Array<ArrayBuffer> 以外のチャンクを書き込んだときに投げます。

対処方法

チャンクには Uint8Array<ArrayBuffer> を渡します。

KeyNotFoundError

意味

指定したキーが存在しないときに read・getReadable が投げます。@unikvs/core の共通エラーです。

対処方法

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

例

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

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

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