@unikvs/etcd

How to use @unikvs/etcd, which stores byte sequences in etcd.

Overview

@unikvs/etcd is a storage plugin that stores byte sequences in etcd. Use it when distributed coordination is needed, such as sharing configuration or service discovery.

• name is "Etcd", and isOpen reports whether it is open.
• open() connects, and close() releases the connection when done.
• This storage applies a namespace and prefix (default "unikvs:") to keys, limiting the scope of clear() deletions.
• When endpoints are omitted, the ETCD_ENDPOINTS environment variable (comma-separated) is used, falling back to "http://127.0.0.1:2379" when unset.
• When leaseTtlSeconds is specified, written keys get a lease expiration (in seconds).

Install it with the following command:

npm install @unikvs/etcd

pnpm add @unikvs/etcd

yarn add @unikvs/etcd

bun add @unikvs/etcd

nub add @unikvs/etcd

aube add @unikvs/etcd

An etcd cluster is required separately.

Usage

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

import { Etcd } from "@unikvs/etcd";

Etcd

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

The constructor arguments are as follows:

EtcdStorageOptions

Options for the etcd storage.

EtcdPutOptions

etcd-specific options that can be passed to put.

EtcdGetAllResult

The key-value pair form returned by getAll. A record, map, or entry iterable.

EtcdClientLike

The minimal interface of an etcd client. In tests, inject a fake satisfying this interface; in production, use the etcd3 client built from endpoints.

NativeEtcdClientLike

The minimal portion of the etcd3 package client used by this package.

wrapNativeEtcdClient

Adapts a native etcd3 client to EtcdClientLike. Writes with a lease when leaseTtlSeconds is specified.

The following example saves a value and reads it back:

import { Etcd } from "@unikvs/etcd";
import * as unikvs from "unikvs";

const kvs = new unikvs.Builder<{ file: unikvs.Value<Uint8Array> }>()
  .persist(new Etcd({ endpoints: "http://127.0.0.1:2379" }))
  .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 accumulate chunks and store them with a single write on completion.
• Read streams emit the fetched bytes as a single chunk.

Errors

This package throws the following errors.

InvalidLeaseTtlError

Thrown when the constructor leaseTtlSeconds is not a positive integer.

Meaning

leaseTtlSeconds was given something other than a positive integer (in seconds).

How to fix

Specify a positive integer (in seconds) for leaseTtlSeconds.

InvalidEndpointsError

Thrown when the constructor endpoints is an empty string or an empty array.

Meaning

endpoints was given an empty string, an empty array, or an array containing empty strings.

How to fix

Specify a non-empty string for endpoints, or a non-empty array containing only non-empty strings.

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

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