Complex JSON reports made easy
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.

Report Builder

Greenkeeper badge

A simple tool for helping your programs generate complex JSON documents. It provides a nice developer experience providing simple but powerful chainable methods.

Create complex JSON reports easily

NPM David Travis Coverage Status npm


Install via yarn

yarn add report-builder (--dev)

or npm

npm install report-builder (--save-dev)

If you don't use a package manager, you can access report-builder via unpkg (CDN), download the source, or point your package manager to the url.

report-builder is compiled as a collection of CommonJS modules & ES2015 modules for bundlers that support the jsnext:main or module field in package.json (Rollup, Webpack 2)

The report-builder package includes precompiled production and development UMD builds in the dist folder. They can be used directly without a bundler and are thus compatible with many popular JavaScript module loaders and environments. You can drop a UMD build as a <script> tag on your page. The UMD builds make report-builder available as a window.reportBuilder global variable.



import reportBuilder from 'report-builder';


See example folder or the runkit example.

Basic usage example

You have to require the report constructor, then you instantiate a report, and then you can start using it:

const Report = require('report-builder');
const report = new Report('Super report','counting api calls');


Each call to .section('name') will return a section object pointing to that area of the report. You can save this reference and use it later, for example:

const mySection = report.section('results').section('APICalls');
/* do some fancy stuff*/

After running all that example code, we can generate a JSON representation of our report using JSON.stringify. Let's output it to the console:

console.log(JSON.stringify(report, null, 2));
/** And here is our report on the console:
  "summary": {
    "total": {
      "count": 100,
      "label": "counting api calls"
    "timestamp": 1482604936983,
    "notes": "Super report"
  "results": {
    "APICalls": {
      "count": 10,
        "count": 10
      "Failed": {

Report structure

A report in it's simpler has a summary and a results sections. Check the format below:

    summary: {
        total: {
            count: 0,
            label: "What does the total mean, what we are counting"
        timestamp: 1482604172152,
        notes: "Why we are generating a report"

    results: { /* This section is empty when the report is first created*/
        APICalls: {
            count: 10


The code is available under the MIT license.


We are open to contributions, see for more info.


For a more complete description of the api please check the documentation


This module was created using generator-module-boilerplate.


This is a work in progress, and may be a bit oppinionated. It was build to suit my needs, so it makes sense.