@unikvs/cloudflare-r2

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

概要

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

論理キーに接頭辞を付与した実キーで put・get・head・delete・list します。利用者は wrangler への依存なしに実バインディングをそのまま渡せます。

• name は CloudflareR2 です。
• isOpen は open() で true になり、close() で false に戻ります。
• delete は冪等で、存在しないキーも成功扱いにします。
• ストリームの読み書きに対応しています。

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

npm install @unikvs/cloudflare-r2

pnpm add @unikvs/cloudflare-r2

yarn add @unikvs/cloudflare-r2

bun add @unikvs/cloudflare-r2

nub add @unikvs/cloudflare-r2

aube add @unikvs/cloudflare-r2

使い方

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

import { CloudflareR2 } from "@unikvs/cloudflare-r2";

CloudflareR2

Workers の R2 バインディングにバイト列を保存するストレージです。

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

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

import { CloudflareR2 } from "@unikvs/cloudflare-r2";
import * as unikvs from "unikvs";

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

データ型

• バイト列のみを保存できます。文字列やオブジェクトはミドルウェアで変換してから渡してください。
• 呼び出し側がビューを再利用しても保存値が変わらないよう、書き込み時に複製します。
• getWritable で取得したストリームは、チャンクを蓄積し、close 時に一括して保存します。
• getReadable で取得したストリームは、保存値を実体化して単一チャンクで送出します。
• clear は接頭辞配下のオブジェクトを列挙し、1000 件ずつまとめて削除します。

エラー

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

InvalidChunkTypeError

意味

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

対処方法

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

KeyNotFoundError

意味

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

対処方法

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

例

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

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

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

StorageAbortedError

意味

getWritable の呼び出し時点でシグナルが既に中断済みのため、取得前に拒否されたときに投げます。@unikvs/core の共通エラーです。

対処方法

中断されていないシグナルを渡すか、要求前にシグナルの状態を確認します。