@unikvs/tap

Middleware that passes data through while invoking a callback with the context.

Overview

@unikvs/tap is middleware that passes data through unchanged while invoking a callback with the context for each data hook.Middleware

Like @unikvs/passthrough, it never changes stored content. Use the callback for logging, validation, runtime-variable updates, and similar side effects.

• name is Tap.
• isOpen is always true. open() is unnecessary.
• The callback runs before encode, decode, encodeStream, and decodeStream.
• The callback’s return value is ignored, and data always passes through as input.
• When the callback returns a Promise, the middleware waits for it before continuing.
• Exceptions or rejections thrown by the callback propagate as operation failures.

Install with:

npm install @unikvs/tap

pnpm add @unikvs/tap

yarn add @unikvs/tap

bun add @unikvs/tap

nub add @unikvs/tap

aube add @unikvs/tap

Usage

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

import { Tap } from "@unikvs/tap";

Constructor arguments:

The following records the action and key for each read and write:

import { Memory } from "@unikvs/memory";
import { Tap } from "@unikvs/tap";
import * as unikvs from "unikvs";

const events: string[] = [];

const kvs = new unikvs.Builder<{ k1: unikvs.PlainValue<string> }>()
  .use(
    new Tap((c) => {
      events.push(`${c.action}:${c.key}`);
    }),
  )
  .persist(new Memory())
  .build();

await kvs.open();
await kvs.set("k1", "hello");
console.log(await kvs.get("k1")); // "hello"
console.log(events); // e.g. ["set:k1", "get:k1"]
await kvs.close();

The callback receives a TapContext, so it can read source, key, and action, and also get and set runtime variables with get, set, and setReadonly.

API reference

Tap

Middleware that invokes a callback before each data hook without transforming data.

• name is "Tap".
• isOpen is always true.
• callback is the callback passed to the constructor.

TapCallback

Callback passed to the Tap constructor.

type TapCallback = (c: TapContext) => void | Promise<void>;

When the callback returns a Promise, the middleware waits for it before sending data downstream. Exceptions or rejections thrown by the callback propagate to the caller as operation failures.

TapContext

Context received by the callback. It is one of:

• IMiddleware.EncodeContext
• IMiddleware.DecodeContext
• IMiddleware.EncodeStreamContext
• IMiddleware.DecodeStreamContext

Data types

• encode and decode output the input data unchanged.
• encodeStream and decodeStream output the input stream unchanged. Chunk order and references are preserved.
• For streams, the callback runs once before the stream is constructed. It does not run per chunk.
• Even if the callback changes destination, the input overwrites it and data passes through unchanged.

Errors

This package has no package-specific errors.

Exceptions or rejections thrown by the callback propagate unchanged as operation failures.