Skip to content

Latest commit

 

History

History
83 lines (62 loc) · 3.09 KB

cloudflare-kv-storage.md

File metadata and controls

83 lines (62 loc) · 3.09 KB
Raw
layout description
page
An implementation of the StorageArea (1,2,3) interface using Cloudflare Worker's KV storage as a backing store.

Cloudflare Storage Area

An implementation of the StorageArea (1,2,3) interface using Cloudflare Worker's KV storage as a backing store.

  • Table of Contents {:toc .large-only}

The goal of this class is ease of use and compatibility with other Storage Area implementations, such as kv-storage-polyfill.

While work on the specification itself has stopped, it's still a good interface for asynchronous data access that feels native to JavaScript.

Usage

import { StorageArea } from '@worker-tools/cloudflare-kv-storage';
const storage = new StorageArea('foobar');

You can now write cross-platform, cross-worker-env code:

async function myFunc(storage) {
  await storage.set(['foo', 1], ['bar', 2], { expirationTtl: 5 * 60 });
  await storage.get(['foo', 1]); // => ['bar', 2]
}

Note that some of the underlying features of Cloudflare KV, such as expirationTtl, are still exposed via the optional options parameter. If the underlying implementation isn't a CloudflareStorageArea, the setting simply won't have any effect.

Prerequisites

In your wrangler.toml, make sure to provide a kv namespace binding and a default namespace for the this implementation.

kv_namespaces = [ 
  { binding = "KV_NAMESPACE", id = "13c...", preview_id = "13c..." }
]

[vars]
  CF_STORAGE_AREA__DEFAULT_KV_NAMESPACE = "KV_NAMESPACE"

Features

Beyond the cross-worker-env aspects of using StorageArea, CloudflareStorageArea provides a number of quality of life improvements over using Cloudflare's KV directly:

  • Support for multiple storage areas within a single KV binding
  • Wrapping and Unwrapping of many built-in types, such as Map and Set (structured clone algorithm)
  • Support for non-string keys and complex keys
  • Abstraction over KV pagination when listing keys

Disclaimers

Note that efficiency is not a goal. Specifically, if you have sizable ArrayBuffers, it's much better to use Cloudflare's KV directly.

{:style="margin: 2rem 0"}

Links: GitHub | ghuc.cc · NPM | Browse Package · deno.land | Docs {:.faded}