@unikvs/valkey

How to use @unikvs/valkey, which stores byte sequences in Valkey from Node.js.

Overview

@unikvs/valkey is a storage plugin that stores byte sequences in Valkey. Node.js only Use it for caches or temporary data shared across nodes.

• name is "Valkey", and isOpen reports whether it is open.
• open() connects, and close() disconnects when done.
• This storage prefixes keys with "unikvs:" by default, limiting the scope of clear() deletions.
• When the connection URL is omitted, the VALKEY_URL (or REDIS_URL) environment variable is used.
• When ttl is specified, written keys get an expiration (in milliseconds).

Install it with the following command:

npm install @unikvs/valkey

pnpm add @unikvs/valkey

yarn add @unikvs/valkey

bun add @unikvs/valkey

nub add @unikvs/valkey

aube add @unikvs/valkey

A Valkey server is required separately.

Usage

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

import { Valkey } from "@unikvs/valkey";

Valkey

Storage that saves to Valkey. Callers open it with open() and close it with close() when done.

The constructor arguments are as follows:

ValkeyStorageOptions

ioredis RedisOptions plus this package’s own fields. ioredis fields are passed through as-is.

ValkeyClusterSpec

The type specifying cluster endpoints. Unsupported in v1, so specifying it is an error.

ValkeyClient

The minimal client shape used to communicate with Valkey. Since Valkey is compatible with the Redis protocol, the ioredis Redis client can be used as-is. In tests, a fake satisfying this shape can be passed via the client option.

The following example saves a value and reads it back:

import { Valkey } from "@unikvs/valkey";
import * as unikvs from "unikvs";

const kvs = new unikvs.Builder<{ file: unikvs.Value<Uint8Array> }>()
  .persist(new Valkey("redis://127.0.0.1:6379"))
  .build();

await kvs.open();

await kvs.set("file", new Uint8Array([0, 1, 2]));

const data = await kvs.get("file");
console.log(data); // Uint8Array(3) [0, 1, 2]

await kvs.close();

Data types

• write / read use byte sequences (Uint8Array<ArrayBuffer>).
• Supports streamed reading and writing with Uint8Array<ArrayBuffer> chunks.
• Write streams append to a temporary key and atomically replace it with a rename on completion. With ttl, the expiration is attached after finalization.
• Read streams emit the fetched bytes as a single chunk.

Errors

This package throws the following errors.

ClusterNotSupportedError

Thrown when the constructor cluster option is specified.

Meaning

v1 only supports standalone mode; the cluster option is not supported.

How to fix

Omit the cluster option and connect to a standalone Valkey.

InvalidCloseTimeoutError

Thrown when the constructor closeTimeout is not a finite positive number.

Meaning

closeTimeout was given something other than a finite positive number (in milliseconds).

How to fix

Specify a finite positive number (in milliseconds) for closeTimeout.

InvalidTtlError

Thrown when the constructor ttl is not a finite positive number.

Meaning

ttl was given something other than a finite positive number (in milliseconds).

How to fix

Specify a finite positive number (in milliseconds) for ttl.

ConnectTimeoutError

Thrown when the connection in open() times out.

Meaning

The connection to Valkey was not established within connectTimeout (default 5000 ms).

How to fix

Check that the server is running and the connection URL is correct, and extend connectTimeout if needed.

CloseTimeoutError

Thrown when disconnection in close() times out.

Meaning

Disconnection from Valkey did not finish within closeTimeout. The connection is disconnected and cleaned up.

How to fix

Check the server state, and extend closeTimeout if it keeps happening.

KeyNotFoundError

A shared @unikvs/core error. Thrown when reading a missing key.

Meaning

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/valkey";

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