@unikvs/v8-serde

How to use @unikvs/v8-serde, Node.js-only middleware that serializes values with node:v8.

Overview

Middleware that serializes values with the node:v8 serializer. Middleware Node.js only

Single reads/writes serialize a value directly, while streams convert values to concatenated frames of a 4-byte big-endian length plus payload.

• name is "V8Serde".
• isOpen becomes true after open() completes.
• open() fails in environments without node:v8.

Install with:

npm install @unikvs/v8-serde

pnpm add @unikvs/v8-serde

yarn add @unikvs/v8-serde

bun add @unikvs/v8-serde

nub add @unikvs/v8-serde

aube add @unikvs/v8-serde

Usage

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

import { V8Serde } from "@unikvs/v8-serde";

The following example serializes an object for storage and restores its original shape on read.

import { V8Serde } from "@unikvs/v8-serde";
import { Memory } from "@unikvs/memory";
import * as unikvs from "unikvs";

const kvs = new unikvs.Builder<{ item: unikvs.Value<{ readonly id: number }> }>()
  .use(new V8Serde())
  .persist(new Memory())
  .build();

await kvs.open();
await kvs.set("item", { id: 1 });
const item = await kvs.get("item");
await kvs.close();

Data types

• encode serializes a value with v8.serialize. Call open() first.
• decode restores bytes to a value with v8.deserialize. Call open() first.
• encodeStream emits one length-prefixed frame per input item (4-byte big-endian length plus payload), concatenated in order.
• decodeStream accumulates received bytes and emits values as frames complete.
• Truncated frames wait for the next chunk; leftover bytes at the end throw an error.
• Empty chunks do not affect decoding, so this middleware ignores them.

Errors

Errors thrown by this package:

V8SerdeEncodeError

Meaning

Thrown when v8.serialize encoding of a value fails. The cause is preserved in cause.

How to fix

Check cause and pass a value supported by v8.serialize.

V8SerdeDecodeError

Meaning

Thrown when v8.deserialize decoding fails. This covers corrupted input and incomplete frames left at the end of a stream. The cause is preserved in cause.

How to fix

Make sure the input was produced by v8.serialize and the stream was not cut off midway.

UnsupportedRuntimeError

Meaning

Thrown by open() in environments without node:v8. This is a shared error from @unikvs/core.

How to fix

Use it in a Node.js environment.