@unikvs/cloudflare-kv

Cloudflare KV binding にバイト列を保存する @unikvs/cloudflare-kv の使い方を説明します。

概要

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

このストレージは、すべてのキーに接頭辞を付与し、値をバイナリーセーフな ArrayBuffer としてそのまま put・get します。

• name は CloudflareKv です。
• isOpen は常に true です。open()・close() は中断の確認のみ行います。
• delete は冪等で、存在しないキーも成功扱いにします。
• ストリームの読み書きには対応していません。

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

npm install @unikvs/cloudflare-kv

pnpm add @unikvs/cloudflare-kv

yarn add @unikvs/cloudflare-kv

bun add @unikvs/cloudflare-kv

nub add @unikvs/cloudflare-kv

aube add @unikvs/cloudflare-kv

使い方

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

import { CloudflareKv } from "@unikvs/cloudflare-kv";

CloudflareKv

Cloudflare KV binding 上で動作するストレージです。

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

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

import { CloudflareKv } from "@unikvs/cloudflare-kv";
import * as unikvs from "unikvs";

const kvs = new unikvs.Builder<{
  foo: unikvs.Value<Uint8Array>;
}>()
  .persist(new CloudflareKv({ binding }))
  .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();

データ型

• バイト列のみを保存できます。文字列やオブジェクトはミドルウェアで変換してから渡してください。
• 値は ArrayBuffer としてそのまま保存され、ビューの byteOffset は持ち越しません。
• clear は接頭辞配下のキーを list で列挙してから削除します。
• ストリームの読み書きには対応していません。

エラー

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

InvalidBindingError

意味

binding が get・put・delete・list を持つオブジェクトではないときに、構築時に投げます。

対処方法

KVNamespace binding か、同等の 4 メソッドを持つオブジェクトを渡します。

InvalidKeyPrefixError

意味

keyPrefix が文字列ではないときに、構築時に投げます。

対処方法

keyPrefix には文字列を指定します。

InvalidTtlSecondsError

意味

ttlSeconds が正の整数でも undefined でもないときに、構築時に投げます。

対処方法

ttlSeconds には正の整数を指定するか、未指定にします。

KeyNotFoundError

意味

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

対処方法

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

例

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

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

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