@unikvs/cloudflare-r2

How to use @unikvs/cloudflare-r2, which stores byte sequences in a Cloudflare R2 binding.

Overview

@unikvs/cloudflare-r2 is storage that stores byte sequences in a Cloudflare Workers R2 binding.

It applies a prefix to logical keys to form real keys and calls put / get / head / delete / list. Callers pass the real binding directly with no wrangler dependency.

• name is CloudflareR2.
• isOpen becomes true on open() and returns to false on close().
• delete is idempotent; missing keys are treated as success.
• Supports streamed reading and writing.

Install it with the following command:

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

Usage

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

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

CloudflareR2

Storage that stores byte sequences in a Workers R2 binding.

The constructor arguments are as follows:

The following example saves a value and reads it back:

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

Data types

• Only byte sequences can be stored. Convert strings or objects with middleware before passing them.
• Values are copied on write so that reusing the caller’s view does not change the stored value.
• The stream from getWritable accumulates chunks and stores them at once on close.
• The stream from getReadable materializes the stored value and emits it as a single chunk.
• clear lists the objects under the prefix and deletes them in batches of 1000.

Errors

This package throws the following errors.

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-r2";

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

StorageAbortedError

Meaning

Thrown when acquisition is rejected before getWritable because the signal is already aborted at call time. A shared @unikvs/core error.

How to fix

Pass a signal that is not aborted, or check the signal state before requesting.