@unikvs/json

Explains how to use the Transformer plugin that serializes values with JSON and JSON Lines (JSONL).

Overview

@unikvs/json is a Transformer plugin that serializes values with the standard JSON.stringify and JSON.parse. Transformer Single-value conversion treats one value as one JSON string, while streams treat one value per line as JSON Lines (JSONL / NDJSON).

It has no additional dependencies and runs only on the runtime’s TextEncoder, TextDecoder, and JSON APIs. Because it is plain JSON without type information, values such as Date, BigInt, Map, and Set cannot round-trip while preserving their kind.

It is always open. No explicit open or close is needed; isOpen always returns true and name is always "Json".

Install

Install it as follows.

npm install @unikvs/json

pnpm add @unikvs/json

yarn add @unikvs/json

bun add @unikvs/json

nub add @unikvs/json

aube add @unikvs/json

Supported Values

Any value JSON can represent round-trips as is. The handling per type is as follows.

Usage

The Json constructor takes no arguments.

import { Json } from "@unikvs/json";

const json = new Json();

Its main members are as follows.

Register it with UniKvs via appendTransformer. It becomes the upstream of subsequently registered storages.

import { Json } from "@unikvs/json";
import UniKvs from "unikvs";

const kvs = UniKvs.config()
  .appendTransformer(new Json())
  .appendStorage(storage)
  .create();

await kvs.open();

await kvs.set("profile", { name: "tai-kun", tags: ["json"] });

const profile = await kvs.get("profile");

set serializes and stores the value, and get deserializes it automatically.

Streams

getEncodable and getDecodable handle JSON Lines (JSONL / NDJSON). JSONL is a format where each line holds one JSON value.

Encoding works as follows.

• Each input chunk is treated as one value, serialized with JSON.stringify, terminated with \n, and output as UTF-8.
• Newlines and \r inside strings are escaped by JSON.stringify, so they never collide with the line terminators.

Decoding works as follows.

• Input is split on \n and each line is parsed with JSON.parse. Line boundaries may fall at any byte boundary; multi-byte characters split across chunks are restored correctly.
• One trailing \r is stripped from each line, so CRLF line endings are accepted as well.
• Completely empty lines are skipped.
• The final line is decoded even without a trailing newline. An empty stream produces zero values and no error.
• A line that is not valid JSON rejects the stream with a native SyntaxError.

import { Json } from "@unikvs/json";

const json = new Json();

const source = new ReadableStream({
  start(controller) {
    controller.enqueue({ id: 1 });
    controller.enqueue({ id: 2 });
    controller.close();
  },
});

const decoded = source.pipeThrough(json.getEncodable()).pipeThrough(json.getDecodable());

The one-shot encode and decode handle exactly one JSON value. Passing multiple concatenated values to decode throws a SyntaxError as trailing content after the JSON value. To handle multiple values together, use the streams.

Errors

The errors this package throws are as follows.

JSON.stringify throws a native TypeError for BigInt. Decode failures also propagate as native errors.

• Invalid JSON, empty bytes, and trailing content after a JSON value are SyntaxError.
• Invalid UTF-8 bytes are TypeError.
• In streams, encoding an unsupported value rejects with JsonUnsupportedValueError, and decoding an invalid line rejects with SyntaxError.

import { JsonUnsupportedValueError } from "@unikvs/json";

try {
  json.encode({ data: undefined });
} catch (error) {
  if (error instanceof JsonUnsupportedValueError) {
    console.log(error.meta.type);
  } else {
    throw error;
  }
}

Examples

A minimal example with Memory storage. Written values are stored as JSON strings and automatically deserialized on reads.

import { Json } from "@unikvs/json";
import { Memory } from "@unikvs/memory";
import UniKvs, { type PlainValue } from "unikvs";

type Profile = {
  name: string;
  tags: string[];
};

const kvs = UniKvs.config<{ profile: PlainValue<Profile> }>()
  .appendTransformer(new Json())
  .appendStorage(new Memory())
  .create();

await kvs.open();

await kvs.set("profile", { name: "tai-kun", tags: ["json", "transformer"] });

const profile = await kvs.get("profile");
console.log(profile.name);

await kvs.close();