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

## 概要 [#overview]

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

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

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

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

```package-install
npm install @unikvs/cloudflare-cache
```

## 使い方 [#usage]

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

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

### `CloudflareCache` [#cloudflare-cache]

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

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

| Prop | Type | Default | Description |
| - | - | - | - |
| `cache?` | `[#cloudflare-cache-cache] CacheLike` | - | 使用する Cache binding です。省略したときは caches.default を使います。 |
| `origin?` | `[#cloudflare-cache-origin] string` | `"https://unikvs.cloudflare-cache"` | キーを要求 URL に変換するときの起点 URL です。クエリー・フラグメントなしの絶対 URL を指定します。 |

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

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

## データ型 [#data-types]

| 操作                                    | 対応するデータ型                     |
| --------------------------------------- | ------------------------------------ |
| `write`・`read`                         | バイト列 (`Uint8Array<ArrayBuffer>`) |
| `getWritable`・`getReadable` のチャンク | `Uint8Array<ArrayBuffer>`            |

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

## エラー [#errors]

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

### InvalidOriginError [#error-invalid-origin]

#### 意味

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

#### 対処方法

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

### InvalidKeyError [#error-invalid-key]

#### 意味

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

#### 対処方法

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

### CacheBindingNotFoundError [#error-cache-binding-not-found]

#### 意味

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

#### 対処方法

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

### CacheOperationError [#error-cache-operation]

#### 意味

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

#### 対処方法

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

### ClearNotSupportedError [#error-clear-not-supported]

#### 意味

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

#### 対処方法

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

### InvalidChunkTypeError [#error-invalid-chunk-type]

#### 意味

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

#### 対処方法

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

### KeyNotFoundError [#error-key-not-found]

#### 意味

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

#### 対処方法

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

#### 例

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

```ts
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;
  }
}
```