@unikvs/redis.node

How to use @unikvs/redis.node, which stores byte sequences in Redis from Node.js.

Overview

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

• name is "Redis", 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 REDIS_URL (or VALKEY_URL) environment variable is used.

Install it with the following command:

npm install @unikvs/redis.node

pnpm add @unikvs/redis.node

yarn add @unikvs/redis.node

bun add @unikvs/redis.node

nub add @unikvs/redis.node

aube add @unikvs/redis.node

A Redis server is required separately.

Usage

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

import { Redis } from "@unikvs/redis.node";

Redis

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

The constructor arguments are as follows:

RedisStorageOptions

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

RedisClusterSpec

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

The following example saves a value and reads it back:

import { Redis } from "@unikvs/redis.node";
import * as unikvs from "unikvs";

const kvs = new unikvs.Builder<{ file: unikvs.Value<Uint8Array> }>()
  .persist(new Redis("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.
• 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 Redis.

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.

ConnectTimeoutError

Thrown when the connection in open() times out.

Meaning

The connection to Redis 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 Redis 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/redis.node";

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