Getting started

The shortest path from installing UniKVS to basic operations.

Installation

Install the unikvs package plus the Storage and Transformer packages you plan to use.

npm install unikvs @unikvs/memory

pnpm add unikvs @unikvs/memory

yarn add unikvs @unikvs/memory

bun add unikvs @unikvs/memory

nub add unikvs @unikvs/memory

aube add unikvs @unikvs/memory

npm install unikvs @unikvs/fs.node @unikvs/compression

pnpm add unikvs @unikvs/fs.node @unikvs/compression

yarn add unikvs @unikvs/fs.node @unikvs/compression

bun add unikvs @unikvs/fs.node @unikvs/compression

nub add unikvs @unikvs/fs.node @unikvs/compression

aube add unikvs @unikvs/fs.node @unikvs/compression

Basic usage

A minimal example using memory Storage. Configure and create, then open, operate, and close.

Create a builder

Create a builder with UniKvs.config(). Specify a key-to-value mapping in the type parameter.

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

const builder = UniKvs.config<{
  foo: Value<Uint8Array>;
}>();

Add a storage and create

Add a storage with appendStorage(), then create the client with create(). Omit Transformers if you don’t need them.

import { Memory } from "@unikvs/memory";

const kvs = builder.appendStorage(new Memory()).create();

Open and operate

Initialize with open(), then use operations such as set, get, has, and delete.

await kvs.open();

await kvs.set("foo", Uint8Array.from([0, 1, 2]));

const bytes = await kvs.get("foo");
console.log(bytes);

console.log(await kvs.has("foo"));

await kvs.delete("foo");

Call close() when you are done.

await kvs.close();

Add a Transformer

An example of transparent compression.

import { Compression } from "@unikvs/compression";
import { Memory } from "@unikvs/memory";
import { UniKvs, type Value } from "unikvs";

const kvs = UniKvs.config<{
  foo: Value<Uint8Array>;
}>()
  .appendTransformer(new Compression("gzip"))
  .appendStorage(new Memory())
  .create();

Keep set and get unchanged; compression on write and decompression on read happen automatically.

Validate values

Pass Valibot schemas via UniKvs.config({ schema }) to enable type inference and runtime validation. Install valibot separately when using Valibot schemas.

import { Memory } from "@unikvs/memory";
import { PlainValue, UniKvs } from "unikvs";
import * as v from "valibot";

const kvs = UniKvs.config({
  schema: {
    foo: PlainValue(v.instance(Uint8Array)),
  },
})
  .appendStorage(new Memory())
  .create();

Failing input validation on set throws InvalidInputError, and failing output validation on get throws InvalidOutputError. The array form is also available for dynamic keys. See schema definition and validation timing in concepts for details.

Next steps

Concepts

Understand the architecture and how Value types work.

Storage comparison

See how to choose a storage backend.