noone99999 / cloudflare-kv-storage

An implementation of the StorageArea 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.

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.

---

This module is part of the Worker Tools collection
⁕

Worker Tools are a collection of TypeScript libraries for writing web servers in Worker Runtimes such as Cloudflare Workers, Deno Deploy and Service Workers in the browser.

If you liked this module, you might also like:

• 🧭 Worker Router --- Complete routing solution that works across CF Workers, Deno and Service Workers
• 🔋 Worker Middleware --- A suite of standalone HTTP server-side middleware with TypeScript support
• 📄 Worker HTML --- HTML templating and streaming response library
• 📦 Storage Area --- Key-value store abstraction across Cloudflare KV, Deno and browsers.
• 🆗 Response Creators --- Factory functions for responses with pre-filled status and status text
• 🎏 Stream Response --- Use async generators to build streaming responses for SSE, etc...
• 🥏 JSON Fetch --- Drop-in replacements for Fetch API classes with first class support for JSON.
• 🦑 JSON Stream --- Streaming JSON parser/stingifier with first class support for web streams.

Worker Tools also includes a number of polyfills that help bridge the gap between Worker Runtimes:

• ✏️ HTML Rewriter --- Cloudflare's HTML Rewriter for use in Deno, browsers, etc...
• 📍 Location Polyfill --- A Location polyfill for Cloudflare Workers.
• 🦕 Deno Fetch Event Adapter --- Dispatches global fetch events using Deno’s native HTTP server.

Fore more visit workers.tools.