@unikvs/cloudflare-kv

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

Overview

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

This storage prepends a prefix to every key and put / get values as-is as binary-safe ArrayBuffers.

• name is CloudflareKv.
• isOpen is always true. open() / close() only check for interruption.
• delete is idempotent; missing keys are treated as success.
• Streamed reading and writing are not supported.

Install it with the following command:

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

Usage

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

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

CloudflareKv

Storage that runs on a Cloudflare KV binding.

The constructor arguments are as follows:

The following example saves a value and reads it back:

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

Data types

• Only byte sequences can be stored. Convert strings or objects with middleware before passing them.
• Values are stored as-is as ArrayBuffer; the view’s byteOffset is not carried over.
• clear lists the keys under the prefix with list and then deletes them.
• Streamed reading and writing are not supported.

Errors

This package throws the following errors.

InvalidBindingError

Meaning

Thrown at construction when binding is not an object with get, put, delete, and list.

How to fix

Pass a KVNamespace binding or an equivalent object with the four methods.

InvalidKeyPrefixError

Meaning

Thrown at construction when keyPrefix is not a string.

How to fix

Specify a string for keyPrefix.

InvalidTtlSecondsError

Meaning

Thrown at construction when ttlSeconds is neither a positive integer nor undefined.

How to fix

Specify a positive integer for ttlSeconds, or omit it.

KeyNotFoundError

Meaning

Thrown by read 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-kv";

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