Pipeline contexts

@unikvs/core pipeline contexts: reading and writing runtime variables via IPipelineContext, and the per-operation context list.

Overview

Pipeline contexts are a gateway for reading and writing per-operation runtime variables (vars). Every context extends IPipelineContext, with key, signal, source, and similar info added per operation kind.

Plugin authors take keys and signals from the context passed as hook arguments, and read behavior settings from vars.

Reading and writing variables

Use the three methods get, set, and setReadonly. The set family returns this, so calls can chain.

import type { IPipelineContext } from "@unikvs/core";

declare const ctx: IPipelineContext<{ readonly count: number }>;

const count: number = ctx.get("count"); // typed read
const unknownValue: unknown = ctx.get("anything-else"); // undeclared keys are unknown

ctx.set("count", 1).setReadonly("count", 2); // returns this, so calls chain

Declaring type arguments like { count: number } types getting and setting that key. Undeclared keys are unknown, and assigning a wrong type is a type error.

// @ts-expect-error count is a number, so a string is rejected
ctx.set("count", "not a number");

Declaration merging

You can also add types via declaration merging on the global UniKvsPipelineContextTypes. Use it to define variable names shared by multiple plugins in one place.

declare global {
  interface UniKvsPipelineContextTypes {
    readonly "test:count": number;
  }
}

declare const ctx: IPipelineContext;

const count: number = ctx.get("test:count");
ctx.set("test:count", 1); // assigning a string is a type error

Type-argument declarations and UniKvsPipelineContextTypes merging combine: a key in either resolves with types. Keys in neither are unknown.

Context hierarchy

Contexts inherit in layers. Lower layers pin down the operation further and carry more info.

Context list

Each operation kind carries fixed info.

Keys and lifecycle

IMapKeyContext is key-mapping only and carries just key (used by middleware mapKey). It carries no signal.

IActionContext carries signal: AbortSignal and 10 kinds of action ("open" | "close" | "set" | "get" | "stream" | "has" | "delete" | "clear" | "copy" | "move"). ILifecycleContext narrows to "open" | "close", and IOpenContext / ICloseContext each pin to one kind.

Keyed operations

IKeyedActionContext adds key: string and narrows action to the 7 kinds "set" | "get" | "stream" | "has" | "delete" | "copy" | "move". The following ISetContext, IGetContext, IStreamContext, IHasContext, and IDeleteContext each pin action to one kind. ITransferContext narrows action to "copy" | "move" and adds the destination key in destinationKey. ICopyContext and IMoveContext pin action to "copy" and "move" respectively. IClearContext carries no key, so it extends IActionContext directly with action "clear".

The middleware use hook receives these 8 kinds (set / get / stream / has / delete / copy / move / clear) together. Narrowing by action gives type-safe access to each operation’s key, repair, and destinationKey.

import type { IMiddleware } from "@unikvs/core";

export function describe(use: IMiddleware.UseContext): string {
  switch (use.action) {
    case "set":
    case "get":
    case "stream":
    case "has":
    case "delete":
    case "copy":
    case "move": {
      return `${use.action}: ${use.key}`;
    }
    case "clear": {
      return "clear";
    }
  }
}

Conversion

ITransformContext carries pre/post-conversion values. source is the input, and the result is assigned to the optional destination.

Data conversion (ITransformDataContext family) source and destination are the values themselves. In stream conversion, on the other hand, (ITransformStreamContext family) source and destination are IReadableStream. Check type arguments for value vs. chunk. See Streams.

Repair

IGetContext and IStreamContext carry a read-time repair (repair) request. It holds whether a value found in a later storage should be written back to earlier ones.

import type { IGetContext } from "@unikvs/core";

declare const ctx: IGetContext;

if (ctx.repair.enabled) {
  console.log(ctx.repair.targets); // readonly [string, ...string[]] (one or more)
} else {
  console.log(ctx.repair.targets); // readonly [] (empty)
}

When enabled is false, targets is an empty array; when true, it is an array of one or more display names. Narrowing by enabled gives type-safe access to targets. When repair is denied, RepairNotAllowedError is used. Eligibility is controlled by @unikvs/allow-repair.

API reference

Per-symbol reference. Each member row is directly linkable.

IPipelineContext

Gateway for reading and writing runtime variables (vars). Every context extends it.

IMapKeyContext

Key-mapping-only context carrying just key.

IActionContext

signal with 10 kinds of action, shared by all operations.

ILifecycleContext

Lifecycle context with action narrowed to "open" | "close".

IOpenContext

Initialization context with action pinned to "open".

ICloseContext

Teardown context with action pinned to "close".

IKeyedActionContext

Context adding key and narrowing action to the 7 keyed operations.

ISetContext

Write context with action pinned to "set".

IGetContext

Read context with action pinned to "get", carrying a repair (repair) request.

IStreamContext

Stream-read context with action pinned to "stream", carrying a repair (repair) request.

IHasContext

Presence-check context with action pinned to "has".

IDeleteContext

Delete context with action pinned to "delete".

ITransferContext

Shared context for copy and move. action is "copy" | "move"; key is the source key, and destinationKey is the destination key.

ICopyContext

Copy context with action pinned to "copy". key and destinationKey are inherited from ITransferContext.

IMoveContext

Move context with action pinned to "move". key and destinationKey are inherited from ITransferContext.

IClearContext

Clear-all context with action pinned to "clear", carrying no key.

ITransformContext

Context carrying pre/post-conversion values. source is the input, and destination receives the conversion result.

ITransformDataContext

Data-conversion context converting the values themselves.

IEncodeContext

Encode context with action pinned to "set".

IDecodeContext

Decode context with action pinned to "get".

ITransformStreamContext

Stream-conversion context. source and destination are IReadableStream.

IEncodeStreamContext

Stream-encode context with action pinned to "set".

IDecodeStreamContext

Stream-decode context with action pinned to "stream".