support custom types

Author: Rich-Harris

README.md

@@ -78,6 +78,37 @@ const json = `{
 const data = devalue.unflatten(JSON.parse(json).data);
 ```
 
+## Custom types
+
+You can serialize and serialize custom types by passing a second argument to `stringify` containing an object of types and their _reducers_, and a second argument to `parse` or `unflatten` containing an object of types and their _revivers_:
+
+```js
+class Vector {
+	constructor(x, y) {
+		this.x = x;
+		this.y = y;
+	}
+
+	magnitude() {
+		return Math.sqrt(this.x * this.x + this.y * this.y);
+	}
+}
+
+const stringified = devalue.stringify(new Vector(30, 40), {
+	Vector: (value) => value instanceof Vector && [value.x, value.y]
+});
+
+console.log(stringified); // [["Vector",1],[2,3],30,40]
+
+const vector = devalue.parse(stringified, {
+	Vector: ([x, y]) => new Vector(x, y)
+});
+
+console.log(vector.magnitude()); // 50
+```
+
+If a function passed to `stringify` returns a truthy value, it's treated as a match.
+
 ## Error handling
 
 If `uneval` or `stringify` encounters a function or a non-POJO, it will throw an error. You can find where in the input data the offending value lives by inspecting `error.path`:

src/parse.js

@@ -10,16 +10,18 @@ import {
 /**
  * Revive a value serialized with `devalue.stringify`
  * @param {string} serialized
+ * @param {Record<string, (value: any) => any>} revivers
  */
-export function parse(serialized) {
-	return unflatten(JSON.parse(serialized));
+export function parse(serialized, revivers) {
+	return unflatten(JSON.parse(serialized), revivers);
 }
 
 /**
- * Revive a value flattened with `devalue.flatten`
+ * Revive a value flattened with `devalue.stringify`
  * @param {number | any[]} parsed
+ * @param {Record<string, (value: any) => any>} revivers
  */
-export function unflatten(parsed) {
+export function unflatten(parsed, revivers) {
 	if (typeof parsed === 'number') return hydrate(parsed, true);
 
 	if (!Array.isArray(parsed) || parsed.length === 0) {
@@ -30,7 +32,10 @@ export function unflatten(parsed) {
 
 	const hydrated = Array(values.length);
 
-	/** @param {number} index */
+	/**
+	 * @param {number} index
+	 * @returns {any}
+	 */
 	function hydrate(index, standalone = false) {
 		if (index === UNDEFINED) return undefined;
 		if (index === NAN) return NaN;
@@ -50,6 +55,11 @@ export function unflatten(parsed) {
 			if (typeof value[0] === 'string') {
 				const type = value[0];
 
+				const reviver = revivers?.[type];
+				if (reviver) {
+					return (hydrated[index] = reviver(hydrate(value[1])));
+				}
+
 				switch (type) {
 					case 'Date':
 						hydrated[index] = new Date(value[1]);
@@ -90,6 +100,9 @@ export function unflatten(parsed) {
 							obj[value[i]] = hydrate(value[i + 1]);
 						}
 						break;
+
+					default:
+						throw new Error(`Unknown type ${type}`);
 				}
 			} else {
 				const array = new Array(value.length);

src/stringify.js

@@ -17,14 +17,21 @@ import {
 /**
  * Turn a value into a JSON string that can be parsed with `devalue.parse`
  * @param {any} value
+ * @param {Record<string, (value: any) => any>} reducers
  */
-export function stringify(value) {
+export function stringify(value, reducers) {
 	/** @type {any[]} */
 	const stringified = [];
 
 	/** @type {Map<any, number>} */
 	const indexes = new Map();
 
+	/** @type {Array<{ key: string, fn: (value: any) => any }>} */
+	const custom = [];
+	for (const key in reducers) {
+		custom.push({ key, fn: reducers[key] });
+	}
+
 	/** @type {string[]} */
 	const keys = [];
 
@@ -47,6 +54,14 @@ export function stringify(value) {
 		const index = p++;
 		indexes.set(thing, index);
 
+		for (const { key, fn } of custom) {
+			const value = fn(thing);
+			if (value) {
+				stringified[index] = `["${key}",${flatten(value)}]`;
+				return index;
+			}
+		}
+
 		let str = '';
 
 		if (is_primitive(thing)) {

test/test.js

@@ -3,6 +3,12 @@ import * as assert from 'uvu/assert';
 import * as uvu from 'uvu';
 import { uneval, unflatten, parse, stringify } from '../index.js';
 
+class Custom {
+	constructor(value) {
+		this.value = value;
+	}
+}
+
 const fixtures = {
 	basics: [
 		{
@@ -374,12 +380,32 @@ const fixtures = {
 				assert.equal(Object.keys(value).length, 0);
 			}
 		}
+	],
+
+	custom: [
+		{
+			name: 'Custom type',
+			value: new Custom({ answer: 42 }),
+			js: null,
+			json: '[["Custom",1],{"answer":2},42]',
+			reducers: {
+				Custom: (value) => value instanceof Custom && value.value
+			},
+			revivers: {
+				Custom: (value) => new Custom(value)
+			},
+			validate: (obj) => {
+				assert.ok(obj instanceof Custom);
+				assert.equal(obj.value.answer, 42);
+			}
+		}
 	]
 };
 
 for (const [name, tests] of Object.entries(fixtures)) {
 	const test = uvu.suite(`uneval: ${name}`);
 	for (const t of tests) {
+		if (t.reducers) continue;
 		test(t.name, () => {
 			const actual = uneval(t.value);
 			const expected = t.js;
@@ -393,7 +419,7 @@ for (const [name, tests] of Object.entries(fixtures)) {
 	const test = uvu.suite(`stringify: ${name}`);
 	for (const t of tests) {
 		test(t.name, () => {
-			const actual = stringify(t.value);
+			const actual = stringify(t.value, t.reducers);
 			const expected = t.json;
 			assert.equal(actual, expected);
 		});
@@ -405,7 +431,7 @@ for (const [name, tests] of Object.entries(fixtures)) {
 	const test = uvu.suite(`parse: ${name}`);
 	for (const t of tests) {
 		test(t.name, () => {
-			const actual = parse(t.json);
+			const actual = parse(t.json, t.revivers);
 			const expected = t.value;
 
 			if (t.validate) {
@@ -421,6 +447,7 @@ for (const [name, tests] of Object.entries(fixtures)) {
 for (const [name, tests] of Object.entries(fixtures)) {
 	const test = uvu.suite(`unflatten: ${name}`);
 	for (const t of tests) {
+		if (t.reducers) continue;
 		test(t.name, () => {
 			const actual = unflatten(JSON.parse(t.json));
 			const expected = t.value;