@unikvs/memcached

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

Overview

@unikvs/memcached is a storage plugin that stores byte sequences in Memcached. Node.js only Use it for caches shared across nodes.

• name is "Memcached", and isOpen reports whether it is open.
• open() verifies the connection, and close() releases it when done.
• This storage prefixes keys with "unikvs:" by default.
• When servers are omitted, the MEMCACHED_SERVERS (or MEMCACHIER_SERVERS, MEMCACHE_SERVERS) environment variable is used, falling back to "127.0.0.1:11211" when unset.

Install it with the following command:

npm install @unikvs/memcached

pnpm add @unikvs/memcached

yarn add @unikvs/memcached

bun add @unikvs/memcached

nub add @unikvs/memcached

aube add @unikvs/memcached

A Memcached server is required separately.

Usage

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

import { Memcached } from "@unikvs/memcached";

Memcached

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

The constructor arguments are as follows:

MemcachedStorageOptions

The constructor options for Memcached.

MemcachedClientLike

The minimal shape of an injectable Memcached client. The memjs Client satisfies this shape.

MemcachedServers

The shape accepted as the servers argument. A string ("host:port,host:port") or an array of them.

MemcachedGetResult

The shape accepted as the return value of get.

MemcachedGetResultValue

The shape accepted as the value in the return value of get. memjs returns { value: Buffer | null, flags }.

The following example saves a value and reads it back:

import { Memcached } from "@unikvs/memcached";
import * as unikvs from "unikvs";

const kvs = new unikvs.Builder<{ file: unikvs.PlainValue<Uint8Array> }>()
  .persist(new Memcached("127.0.0.1:11211"))
  .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>).
• Values are stored as Base64-encoded strings.
• Streamed reading and writing are not supported.
• clear() deletes all keys on the server because there is no way to list keys.

Errors

This package throws the following errors.

InvalidTtlSecondsError

Thrown when the constructor ttlSeconds is not a finite number greater than or equal to 0.

Meaning

ttlSeconds was given something other than a finite number greater than or equal to 0.

How to fix

Specify a finite number greater than or equal to 0 (in seconds) for ttlSeconds.

InvalidConnectTimeoutError

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

Meaning

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

How to fix

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

ConnectTimeoutError

Thrown when the connection check in open() times out.

Meaning

The connection check to Memcached did not finish within connectTimeout (default 5000 ms).

How to fix

Check that the server is running and the servers are correct, and extend connectTimeout if needed.

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

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