Concepts

How UniKVS combines Transformers and Storages, Value types, and variables.

Architecture

UniKVS uses the builder pattern. Input passes through Transformers to Storages.

There are two roles:

• Transformers transparently encode/decode data.
• Storages are persistence destinations. With multiple Storages, writes go to all of them in parallel.

Each Storage uses the Transformers added up to its registration. On reads, the upstream pipeline of the found Storage is applied in reverse to decode the data.

Config builder

Create a builder with UniKvs.config() in the following order. Passing schema enables input and output validation with Valibot schemas, and also infers the key-to-value mapping type automatically.

import { PlainValue, StreamValue, UniKvs } from "unikvs";
import * as v from "valibot";

const kvs = UniKvs.config({
  schema: {
    message: PlainValue(v.string()),
    logs: StreamValue(v.instance(Uint8Array)),
  },
})
  .appendStorage(storage)
  .create();

Install valibot separately when using Valibot schemas. Omitting schema falls back to specifying the mapping with a type parameter. In that case only type checking applies, with no runtime validation.

Client operations

All operations support cancellation via AbortSignal and passing of runtime variables.

Value types

Value, PlainValue, and StreamValue are both types and functions. Used as types, they decide the available methods per key at the type level; used as functions, they infer types from Valibot schemas and validate values at runtime.

Value<T> is sugar for both, equivalent to PlainValue<T> | StreamValue<T>.

import { UniKvs, type PlainValue } from "unikvs";

const kvs = UniKvs.config<{
  message: PlainValue<string>;
}>()
  .appendStorage(storage)
  .create();

await kvs.set("message", "hello");
const msg = await kvs.get("message");

import { UniKvs, type StreamValue } from "unikvs";

const kvs = UniKvs.config<{
  logs: StreamValue<Uint8Array>;
}>()
  .appendStorage(storage)
  .create();

await kvs.set("logs", new Uint8Array([0x01]));
const valueStream = await kvs.stream("logs");

import { UniKvs, type Value } from "unikvs";

const kvs = UniKvs.config<{
  blob: Value<Uint8Array>;
}>()
  .appendStorage(storage)
  .create();

await kvs.set("blob", new Uint8Array([1, 2, 3]));
const all = await kvs.get("blob");
const valueStream = await kvs.stream("blob");

Schema definition

Passing schemas to UniKvs.config({ schema }) infers the mapping type from Valibot schemas and validates input and output values at runtime.

import { PlainValue, StreamValue, UniKvs } from "unikvs";
import * as v from "valibot";

const kvs = UniKvs.config({
  schema: {
    message: PlainValue(v.pipe(v.string(), v.minLength(1))),
    logs: StreamValue(v.instance(Uint8Array)),
  },
})
  .appendStorage(storage)
  .create();

await kvs.set("message", "hello");
const msg = await kvs.get("message");
// msg is typed as string

import { PlainValue, StreamValue, UniKvs } from "unikvs";
import * as v from "valibot";

const kvs = UniKvs.config({
  schema: [
    [v.pipe(v.string(), v.regex(/^msg-.+/)), PlainValue(v.string())],
    [v.pipe(v.string(), v.regex(/^img-.+/)), StreamValue(v.instance(Uint8Array))],
  ],
})
  .appendStorage(storage)
  .create();

await kvs.set("msg-1", "hello");

Validation timing

Runtime variables

Variables are a runtime context that switches operation behavior. Set initial values with setVariables(), and override them per operation with vars.

const kvs = UniKvs.config<{ foo: Value<Uint8Array> }>()
  .setVariables({ region: "ap-northeast-1" })
  .appendStorage(storage)
  .create();

await kvs.set("foo", new Uint8Array([1]), {
  vars: { region: "us-east-1" },
});

Plugin kinds