@unikvs/cloudflare-cache

How to use @unikvs/cloudflare-cache, which stores byte sequences in the Workers Cache API binding.

Overview

@unikvs/cloudflare-cache is storage that stores byte sequences in the Workers Cache API binding.

This storage converts keys to request URLs and processes them with put / match / delete as responses with a binary body. When the constructor cache is omitted, caches.default is used.

• name is CloudflareCache.
• isOpen is always true. open() / close() only check for interruption.
• clear is not supported because the Cache API has no key enumeration.
• Supports streamed reading and writing.

Install it with the following command:

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

Usage

CloudflareCache implements IStorage. Pass it to UniKvs via persist().

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

CloudflareCache

Storage that stores byte sequences in the Workers Cache API binding.

The constructor arguments are as follows:

The following example saves a value and reads it back:

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

• Only byte sequences can be stored. Convert strings or objects with middleware before passing them.
• Keys are converted to request URLs of the form ${origin}/<encoded key>.
• The stream from getWritable accumulates chunks and stores them at once on close.
• The stream from getReadable returns the body of the stored response.
• clear is not supported. Delete keys one at a time.

Errors

This package throws the following errors.

InvalidOriginError

Meaning

Thrown at construction when origin is not an absolute URL without query or fragment.

How to fix

Specify an absolute URL with no surrounding whitespace, query, or fragment.

InvalidKeyError

Meaning

Thrown when a key cannot be encoded as a URL path segment.

How to fix

Use encodable strings as keys. Avoid keys containing lone surrogates, for example.

CacheBindingNotFoundError

Meaning

Thrown at construction when no cache is given and caches.default does not exist either.

How to fix

Pass a Cache binding in cache, or run on a runtime where caches.default exists.

CacheOperationError

Meaning

Thrown when any of put / match / delete is rejected.

How to fix

Check the failed operation in meta.operation and investigate the cause in cause.

ClearNotSupportedError

Meaning

Thrown when clear() is called. Bulk deletion is not supported because the Cache API has no key enumeration.

How to fix

Delete keys one at a time with delete.

InvalidChunkTypeError

Meaning

Thrown when a chunk other than Uint8Array<ArrayBuffer> is written to the stream obtained from getWritable.

How to fix

Pass Uint8Array<ArrayBuffer> as chunks.

KeyNotFoundError

Meaning

Thrown by read / getReadable when the specified key does not exist. A shared @unikvs/core error.

How to fix

Check with exists before reading.

Example

The following example catches KeyNotFoundError.

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

try {
  const data = await kvs.get("missing-key");
} catch (ex) {
  if (ex instanceof KeyNotFoundError) {
    console.log("Key not found");
  } else {
    throw ex;
  }
}