@unikvs/core

Shared types and error foundation for all packages: role, installation, exported values, and guide to each document.

Overview

@unikvs/core Shared is the shared foundation for all packages and plugins. It provides the interfaces plugins implement (IStorage / IMiddleware), the per-operation contexts, and the shared error foundation.

Its key trait: the only runtime values are error classes; everything else is types. It adds no extra runtime code to bundles and pins plugin contracts in types.

Installation

npm install @unikvs/core

pnpm add @unikvs/core

yarn add @unikvs/core

bun add @unikvs/core

nub add @unikvs/core

aube add @unikvs/core

valibot is used for language switching. Install it separately only when you use message localization. See Errors › Language switching.

ESM only (sideEffects: false). Dependencies are just i18n-error-base and maypromise, both tiny.

Exports and types

Only 9 runtime values are exported from the @unikvs/core entry point.

Runtime value	Kind	Description	Details
`ErrorBase`	class	Base of all shared errors	Errors
`InvalidUsageErrorBase`	class	Base of usage-mistake errors	Errors
`KeyNotFoundError`	class	Key not found	Errors
`UnsupportedRuntimeError`	class	Used outside a supported runtime	Errors
`InvalidPartSizeError`	class	Invalid part size	Errors
`StorageAbortedError`	class	Abort signal already fired before start	Errors
`RepairNotAllowedError`	class	Repair write denied	Errors
`ReadonlyVariableError`	class	Write to a readonly variable	Errors
`setErrorMessage`	function	Registers per-language messages	Errors

Everything else is types only. Sources are split by file:

Source	Contents	Runtime values	Details
`errors.ts`	Error classes and `setErrorMessage`	yes	Errors
`pipeline-context.types.ts`	Per-operation contexts	no	Pipeline contexts
`storage.types.ts`	Destination plugin interface	no	Storage
`middleware.types.ts`	Transform plugin interface	no	Middleware
`stream.types.ts`	Web-standard stream aliases	no	Streams

import {
  type ErrorMeta,
  type IStorage,
  type IMiddleware,
  type IPipelineContext,
  type IGetContext,
  type ISetContext,
  type IReadableStream,
  KeyNotFoundError,
} from "@unikvs/core";

Guide

Read by purpose.

Errors

The error foundation, the 6 shared errors, and language switching.

Pipeline contexts

Runtime variables and the per-operation context list.

Storage

IStorage, the interface destination plugins implement.

Middleware

IMiddleware, the interface transform plugins implement.

Streams

Web-standard stream aliases and chunk-type handling.

When authoring a plugin, start from the storage or middleware examples for the big picture.