danson

danSON

Progressive JSON

About

danSON is a progressive JSON serializer and deserializer that can serialize and deserialize arbitrary objects into JSON.

Features

• Streaming of Promises, AsyncIterables, and ReadableStreams
• Custom serializers / deserializers
• De-duplication of objects (optional)
• Circular references
• Built-in serializers for common JavaScript types:
  • BigInt
  • Date
  • Headers
  • Map
  • Special numbers (-0, Infinity, -Infinity)
  • RegExp
  • Set
  • TypedArrays (Int8Array, Uint8Array, etc.)
  • undefined
  • URL
  • URLSearchParams

Installation

npm install danson

Examples

Try the example on StackBlitz

Serializing custom objects

import { Temporal } from "@js-temporal/polyfill";
import { parseSync, stringifySync } from "danson";

const source = {
	instant: Temporal.Now.instant(),
};

const stringified = stringifySync(source, {
	serializers: {
		"Temporal.Instant": (value) => value.toJSON(),
	},
	space: 2,
});
/*
{
	"json": {
		"instant": {
			"_": "$",
			"type": "Temporal.Instant",
			"value": "2025-06-13T15:24:51.30029128Z"
		}
	}
}
*/

const result = parseSync<typeof source>(stringified, {
	deserializers: {
		"Temporal.Instant": (value) => Temporal.Instant.from(value as string),
	},
});

Streaming Promises

Promise example input

const source = {
	foo: "bar",
	promise: (async () => {
		await sleep(1000);
		return "hello promise";
	})(),
};

const stringified = stringifySync(source, {
	space: 2,
});
for await (const chunk of stringified) {
	console.log(chunk);
}

Promise example output

{
	"json": {
		"foo": "bar",
		"promise": {
			"_": "$", // informs the deserializer that this is a special type
			"type": "Promise", // it is a Promise
			"value": 1, // index of the Promise that will come later
		},
	},
}

[
	1, // index of the Promise
	0, // Promise succeeded (0 = success, 1 = failure)
	{
		"json": "hello promise"
	}
]

Streaming AsyncIterables

AsyncIterable example input

const source = {
	asyncIterable: (async function* () {
		yield "hello";
		yield "world";

		return "done";
	})(),
};

const stringified = stringifySync(source, {
	space: 2,
});
for await (const chunk of stringified) {
	console.log(chunk);
}

AsyncIterable example output

{
	"json": {
		"foo": "bar",
		"asyncIterable": {
			"_": "$",
			"type": "AsyncIterable",
			"value": 0
		}
	}
}

[
	0,
	0,
	{
		"json": "world"
	}
]

[
	0, // index of the AsyncIterable
	2,
	{
		"json": "done"
	}
]

API Reference

stringifySync(value: unknown, options?: StringifyOptions): string

Serializes a value into a JSON string.

parseSync<T>(value: string, options?: ParseOptions): T

Deserializes a JSON string into a value.

serializeSync(value: unknown, options?: StringifyOptions): SerializeReturn

Serializes a value into a JSON.stringify-compatible format.

deserializeSync<T>(value: SerializeReturn, options?: ParseOptions): T

Deserializes from a SerializeReturn object into a value.

stringifyAsync(value: unknown, options?: StringifyOptions): AsyncIterable<string, void>

Serializes a value into a stream of JSON strings asynchronously.

parseAsync<T>(value: AsyncIterable<string, void>, options?: ParseOptions): Promise<T>

Deserializes a stream of JSON strings into a value asynchronously.

serializeAsync(value: unknown, options?: StringifyOptions): AsyncIterable<unknown, void>

Serializes a value into a stream of intermediate objects asynchronously.

deserializeAsync<T>(value: AsyncIterable<unknown, void>, options?: ParseOptions): Promise<T>

Deserializes a stream of intermediate objects into a value asynchronously.

Using Built-in Serializers

The std