@unikvs/vercel-runtime-cache

How to use @unikvs/vercel-runtime-cache, which stores values in the Vercel runtime cache.

Overview

@unikvs/vercel-runtime-cache is storage that stores values in the Vercel runtime cache.

This storage auto-detects the runtime cache and falls back to an in-process Map when none is found. In both cases entries are evicted by TTL and maximum count.

name is VercelRuntimeCache.
When you share a backend, set a namespace. When namespace is set, clear deletes only the keys tracked by the current instance; keys written by other instances or processes in the same namespace are not removed.
maxEntries eviction and expired-key removal rely on per-instance tracking. A shared backend may therefore hold more than maxEntries keys.
Backend eviction is oldest-written (FIFO), while fallback eviction is least-recently-used (LRU).
When namespace is empty and the backend provides clear, clear deletes the entire backend.
isOpen is always true. open() / close() only check for interruption.
delete throws KeyNotFoundError for a missing key.
Supports streamed reading and writing.

Install it with the following command:

npm install @unikvs/vercel-runtime-cache

pnpm add @unikvs/vercel-runtime-cache

yarn add @unikvs/vercel-runtime-cache

bun add @unikvs/vercel-runtime-cache

nub add @unikvs/vercel-runtime-cache

aube add @unikvs/vercel-runtime-cache

Usage

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

import { VercelRuntimeCache } from "@unikvs/vercel-runtime-cache";

`VercelRuntimeCache`

Storage that uses the Vercel Runtime Cache.

The constructor arguments are as follows:

PropType

ttlSeconds?number

The entry lifetime (in seconds).

Typenumber

Default60

maxEntries?number

The maximum number of entries to keep. Unlimited when omitted. Evicts oldest-written entries (FIFO) on the backend and least-recently-used entries (LRU) on the fallback.

Typenumber

namespace?string

The namespace prepended to backend keys. Use it when multiple storages share the same backend.

Typestring

Default""

clone?<T>(value: T) => T

The function used to clone values. Uses structuredClone by default.

Type<T>(value: T) => T

backend?VercelRuntimeCacheBackend

The backend to use. When omitted, it is auto-detected and falls back to an in-process Map when none is found.

TypeVercelRuntimeCacheBackend

now?() => number

The function returning the current time. Use it to fix the time in tests.

Type() => number

The following example saves a value and reads it back:

import { VercelRuntimeCache } from "@unikvs/vercel-runtime-cache";
import * as unikvs from "unikvs";

const kvs = new unikvs.Builder<{
  foo: unikvs.Value<string>;
}>()
  .persist(new VercelRuntimeCache())
  .build();

await kvs.open();
await kvs.set("foo", "hello");

const data = await kvs.get("foo");
console.log(data); // "hello"

await kvs.close();

Data types

Operation	Data type
`write` / `read`	Any value (strings, objects, etc.)
`getWritable` / `getReadable` chunks	`Uint8Array<ArrayBuffer>`

Any value can be stored. By default values are cloned with structuredClone, so handle values that structuredClone can clone.
Expired entries are treated as missing and swept on read.
The stream from getWritable accumulates Uint8Array<ArrayBuffer> chunks and stores them together on close.
getReadable can only be used when the stored value is a Uint8Array<ArrayBuffer>.

How to fix

Check with exists before reading.

Example

The following example catches KeyNotFoundError.

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

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