@unikvs/superjson

値を SuperJSON でシリアライズするミドルウェア @unikvs/superjson の使い方を説明します。

概要

値を SuperJSON でシリアライズするミドルウェアです。Middleware

このミドルウェアは Date・Map・Set・BigInt・undefined など、JSON では失われる型情報を保持したまま変換します。ストリームでは 1 件ずつ JSON Lines 形式の行に区切って変換します。

• name は "Superjson" です。
• isOpen はつねに true です。

インストールは次のコマンドで行います。

npm install @unikvs/superjson

pnpm add @unikvs/superjson

yarn add @unikvs/superjson

bun add @unikvs/superjson

nub add @unikvs/superjson

aube add @unikvs/superjson

使い方

Superjson は IMiddleware を実装しています。UniKvs には use() で渡します。

import { Superjson } from "@unikvs/superjson";

以下は、日付を持つオブジェクトを型情報を保ったまま保存し、読み取り時に Date として戻す例です。

import { Memory } from "@unikvs/memory";
import { Superjson } from "@unikvs/superjson";
import * as unikvs from "unikvs";

const kvs = new unikvs.Builder<{ event: unikvs.Value<{ readonly at: Date }> }>()
  .use(new Superjson())
  .persist(new Memory())
  .build();

await kvs.open();
await kvs.set("event", { at: new Date("2026-01-01T00:00:00Z") });
const event = await kvs.get("event");
await kvs.close();

データ型

• encode は値を SuperJSON 文字列に変換し、UTF-8 でバイト列化します。
• decode はバイト列を UTF-8 文字列に戻し、SuperJSON として解析します。
• encodeStream は入力 1 件ごとに 1 行 (<SuperJSON>\n) を出力し、JSON Lines 形式に変換します。
• decodeStream は受信したバイト列を文字列バッファーにため、改行がそろった行から順に解析します。
• 行末の CR は 1 つ取り除き、空行は読み飛ばします。
• 末尾に改行がない場合は、残りのバッファーを最後の 1 行として処理します。
• 関数とシンボルは SuperJSON が "{}" に変換してしまうため、事前に拒否します。

エラー

このパッケージが投げるエラーは次のとおりです。

SuperjsonUnsupportedValueError

SuperJSON で扱えない型の値を渡すと、このエラーが投げられます。

意味

関数とシンボルは SuperJSON がエラーを出さず "{}" に変換するため、データの消失を防ぐために事前に拒否します。meta.type に対象の typeof が入ります。

対処方法

関数とシンボルを値に含めないでください。

なお、デコード時に不正な SuperJSON や UTF-8 を受け取った場合は、ネイティブエラーがそのまま伝播します。