@unikvs/debug

Middleware that logs debug information about operations and data being read or written.

Overview

@unikvs/debug is a plugin that logs the kind and size of data being read or written.Middleware

It passes data through unchanged while recording the operation name, key, and direction. Use it to observe data flow through storage.

• name is Debug.
• isOpen is always true. open() is unnecessary.
• Logging uses @logtape/logtape. Recording is controlled by keyFilter and actionFilter.

Install with:

npm install @unikvs/debug @logtape/logtape

pnpm add @unikvs/debug @logtape/logtape

yarn add @unikvs/debug @logtape/logtape

bun add @unikvs/debug @logtape/logtape

nub add @unikvs/debug @logtape/logtape

aube add @unikvs/debug @logtape/logtape

Usage

Debug implements IMiddleware. Pass it to UniKvs with use().

import { Debug } from "@unikvs/debug";

DebugOptions

Constructor arguments:

DebugDirection

DebugDirection is the data direction: write or read. It is write for encode on writes and read for decode on reads.

The following records writes and reads of a specific key:

import { configureSync } from "@logtape/logtape";
import { Debug } from "@unikvs/debug";
import { Memory } from "@unikvs/memory";
import * as unikvs from "unikvs";

configureSync({
  sinks: { console: (record) => console.log(record.message) },
  loggers: [{ category: ["@unikvs/debug"], sinks: ["console"], lowestLevel: "debug" }],
});

const kvs = new unikvs.Builder<{ foo: unikvs.Value<string> }>()
  .use(
    new Debug({
      keyFilter: (key) => key.startsWith("foo"),
      actionFilter: (action) => action === "set" || action === "get",
    }),
  )
  .persist(new Memory())
  .build();

await kvs.open();
await kvs.set("foo", "hello");

const value = await kvs.get("foo");
console.log(value); // "hello"

await kvs.close();

Data types

• encode outputs input data unchanged and logs it as a write.
• decode outputs input data unchanged and logs it as a read.
• encodeStream outputs each chunk unchanged and logs each one as a write.
• decodeStream outputs each chunk unchanged and logs each one as a read.
• Operations rejected by filters are not logged.

Errors

This package has no package-specific errors.

Errors thrown by getDebugInfo propagate as-is.