devalue

Gets the job done when JSON.stringify can't

JSONRegular expression
Rich-Harris/devaluesvelte.dev/repl/138d70def7a748ce9eda736ef1c71239?version=3.49.0devalue

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
- BigInt
- custom types via replacers, reducers and revivers

Try it out here.

Goals:


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

Non-goals:


- Human-readable output
- Stringifying functions

Usage


There are two ways to use devalue:

uneval


This function takes a JavaScript value and returns the JavaScript code to create an equivalent value — sort of like eval in reverse:

  1. ```js
  2. import * as devalue from 'devalue';

  4. let obj = { message: 'hello' };
  5. devalue.uneval(obj); // '{message:"hello"}'

  7. obj.self = obj;
  8. devalue.uneval(obj); // '(function(a){a.message="hello";a.self=a;return a}({}))'
  9. ```

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 parse


These two functions are analogous to JSON.stringify and JSON.parse:

  1. ```js
  2. import * as devalue from 'devalue';

  4. let obj = { message: 'hello' };

  6. let stringified = devalue.stringify(obj); // '[{"message":1},"hello"]'
  7. devalue.parse(stringified); // { message: 'hello' }

  9. obj.self = obj;

  11. stringified = devalue.stringify(obj); // '[{"message":1,"self":0},"hello"]'
  12. devalue.parse(stringified); // { message: 'hello', self: [Circular] }
  13. ```

Use stringify and parse when evaluating JavaScript isn't an option.

unflatten


In the case where devalued data is one part of a larger JSON string, unflatten allows you to revive just the bit you need:

  1. ```js
  2. import * as devalue from 'devalue';

  4. const json = `{
  5.   "type": "data",
  6.   "data": ${devalue.stringify(data)}
  7. }`;

  9. const data = devalue.unflatten(JSON.parse(json).data);
  10. ```

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_:

  1. ```js
  2. class Vector {
  3. constructor(x, y) {
  4.   this.x = x;
  5.   this.y = y;
  6. }

  8. magnitude() {
  9.   return Math.sqrt(this.x * this.x + this.y * this.y);
  10. }
  11. }

  13. const stringified = devalue.stringify(new Vector(30, 40), {
  14. Vector: (value) => value instanceof Vector && [value.x, value.y]
  15. });

  17. console.log(stringified); // [["Vector",1],[2,3],30,40]

  19. const vector = devalue.parse(stringified, {
  20. Vector: ([x, y]) => new Vector(x, y)
  21. });

  23. console.log(vector.magnitude()); // 50
  24. ```

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:

  1. ```js
  2. devalue.uneval(vector, (value, uneval) => {
  3. if (value instanceof Vector) {
  4.   return `new Vector(${value.x},${value.y})`;
  5. }
  6. }); // `new Vector(30,40)`
  7. ```

Note that any variables referenced in the resulting JavaScript (like Vector in the example above) must be in scope when it runs.

Error handling


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:

  1. ```js
  2. try {
  3. const map = new Map();
  4. map.set('key', function invalid() {});

  6. uneval({
  7.   object: {
  8.    array: [map]
  9.   }
  10. });
  11. } catch (e) {
  12. console.log(e.path); // '.object.array[0].get("key")'
  13. }
  14. ```

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:

  1. ```js
  2. const state = {
  3. userinput: `</script>