dumpster

Dump any JS object to valid human-readable JSON

Usage no npm install needed!

<script type="module">
  import dumpster from 'https://cdn.skypack.dev/dumpster';
</script>

README

dumpster

Serializes any JS object to valid JSON, which is useful for debugging purposes (i.e. logs). This JSON may then be passed to various log processing systems, etc.

Features

  • Supports circular objects (like a = {}; a.a = a;)
  • Keeps information about object methods (functions), some special types (regexps, errors, etc)
  • Supports pretty printing and serialization depth limit
  • Provides good serialization speed (see benchmarks)

Usage

const dump = require('dumpster').dump;
let obj = {
  sample: {
    object: 1
  }
}
console.log(dump(obj));
// {"sample":{"object":1}}

let req = new (require('http').ClientRequest)();
console.log(dump(req, {pretty: true}));
// Pretty printed http.ClientRequest object goes here

API

  • dumpster.dump(obj, [options]) - serialize JS object to JSON. Valid options are:
    • options.pretty (default: false) - may be either boolean, number or string, enables pretty printing and sets corresponding indentation. Number and string works exactly as third argument of JSON.stringify and true means to use 4 space identation.
    • options.depth (default: 2) - sets serialization depth. If obj have nested objects with depth more then options.depth, these objects are replaced with string __Object__ in final JSON. To disable this feature you may set options.depth to Infinity.

TODO:

  • Pre-ES6 environment support (now you need Object.assign polyfill and const keyword support)
  • Browser builds
  • Memory usage benchmark

Similar tools

There are plenty of tools that solves similar tasks, but all of them have their own pros and cons.

  • JSON.stringify
      • is part of JS standard
      • is much faster than dumpster
      • fails on circular objects
      • doesn't support serialization depth limit
      • throws away information about functions, RegExps, etc, useful for debug
  • util.inspect (Node.js)
      • is included into nodejs
      • supports custom inspect and rich colorful output
      • does not produce valid JSON
  • util.format('%j') (Node.js)
    • it is actually the same as JSON.stringify, but it does not fail on Circular objects. It returns useless string instead
  • json-stringify-safe
      • doesn't support serialization depth limit
      • throws away information about functions, RegExps, etc
      • project seems to be abandoned, with open issues
  • circular-json
      • provides ability to deserialize circular objects
      • slightly faster than dumpster on small objects
      • doesn't support serialization depth limit
      • throws away information about functions, RegExps, etc
      • is dramatically slow on large JSON datasets

Benchmark

Benchmarks are implemented using benchmark module. See the source code here. Data from http://mtgjson.com is used as an example of large JSON dataset.

I got the following benchmark results on my laptop and nodejs v4:

Benchmarking with tiny JS object
dumpster (depth: 2) x 65,318 ops/sec ±1.40% (85 runs sampled)
dumpster (depth: Infinity) x 39,443 ops/sec ±1.71% (87 runs sampled)
dumpster (pretty) x 34,469 ops/sec ±1.13% (87 runs sampled)
JSON.stringify x 237,355 ops/sec ±1.32% (89 runs sampled)
JSON.stringify (pretty) x 59,712 ops/sec ±1.02% (89 runs sampled)
util.inspect (depth: 2) x 15,146 ops/sec ±1.32% (89 runs sampled)
util.inspect (depth: Infinity) x 8,434 ops/sec ±1.34% (90 runs sampled)
util.format (%j) x 210,131 ops/sec ±1.41% (90 runs sampled)
json-stringify-safe x 25,030 ops/sec ±3.06% (83 runs sampled)
json-stringify-safe (pretty) x 22,264 ops/sec ±2.12% (83 runs sampled)
circular-json x 37,935 ops/sec ±3.73% (79 runs sampled)
circular-json (pretty) x 26,561 ops/sec ±2.11% (82 runs sampled)

Benchmarking with circular JS object
dumpster (depth: 2) x 55,658 ops/sec ±1.55% (85 runs sampled)
dumpster (depth: Infinity) x 33,038 ops/sec ±2.04% (82 runs sampled)
dumpster (pretty) x 25,904 ops/sec ±2.90% (79 runs sampled)
util.inspect (depth: 2) x 12,770 ops/sec ±1.72% (82 runs sampled)
util.inspect (depth: Infinity) x 6,931 ops/sec ±2.16% (80 runs sampled)
json-stringify-safe x 17,769 ops/sec ±2.59% (73 runs sampled)
json-stringify-safe (pretty) x 14,756 ops/sec ±1.97% (79 runs sampled)
circular-json x 25,914 ops/sec ±1.86% (80 runs sampled)
circular-json (pretty) x 22,910 ops/sec ±1.92% (84 runs sampled)

Benchmarking with http.ClientRequest
dumpster (depth: 2) x 12,127 ops/sec ±2.79% (82 runs sampled)
dumpster (depth: Infinity) x 5,172 ops/sec ±3.62% (76 runs sampled)
dumpster (pretty) x 5,421 ops/sec ±1.96% (84 runs sampled)
util.inspect (depth: 2) x 5,326 ops/sec ±2.11% (83 runs sampled)
util.inspect (depth: Infinity) x 1,376 ops/sec ±1.73% (85 runs sampled)
json-stringify-safe x 2,867 ops/sec ±2.32% (82 runs sampled)
json-stringify-safe (pretty) x 2,749 ops/sec ±1.92% (81 runs sampled)
circular-json x 5,255 ops/sec ±2.09% (82 runs sampled)
circular-json (pretty) x 4,976 ops/sec ±2.36% (82 runs sampled)

Benchmarking with large JSON dataset
dumpster (depth: 2) x 58.45 ops/sec ±1.66% (60 runs sampled)
dumpster (depth: Infinity) x 1.74 ops/sec ±5.42% (9 runs sampled)
dumpster (pretty) x 1.42 ops/sec ±5.54% (8 runs sampled)
JSON.stringify x 8.20 ops/sec ±8.18% (25 runs sampled)
JSON.stringify (pretty) x 1.55 ops/sec ±10.81% (9 runs sampled)
util.inspect (depth: 2) x 6.09 ops/sec ±3.05% (19 runs sampled)
util.inspect (depth: Infinity) x 0.35 ops/sec ±2.57% (5 runs sampled)
util.format (%j) x 8.17 ops/sec ±5.54% (24 runs sampled)
json-stringify-safe x 0.54 ops/sec ±11.63% (6 runs sampled)
json-stringify-safe (pretty) x 0.51 ops/sec ±5.88% (6 runs sampled)
circular-json@0.3.0 couldn't pass this benchmark in reasonable time. Looks like
it takes about a minute for this library to dump provided example.