Json-Spread

Description

A simple javascript library that flattens a json structured object and then creates duplicate objects off of each nested array elements.

Great for converting nested, multi-leveled json to single level json that can be used to create csv,tsv,excel or other row column structured data.

Installation

Node

npm install json-spread

Browser

include the jsonSpread.min.js file from the dist folder

Usage

var jsonSpread = require('json-spread');
var output = jsonSpread({
  "a": [
    {
      "index": 1
    },
    {
      "index": 2
    },
    {
      "index": 3
    }
  ]
})
/*
output = [
  {
    "a.index": 1
  },
  {
    "a.index": 2
  },
  {
    "a.index": 3
  }
]
*/

Examples

nested array

//input
{
  "a": [
    1,
    2,
    3
  ],
  "b": {
    "a": [
      1,
      2,
      3
    ]
  }
}
//output
[
  {
    "a":1
  },
  {
    "a":2
  },
  {
    "a":3
  },
  {
    "b.a":1
  },
  {
    "b.a":2
  },
  {
    "b.a":3
  }
]

nested arrays within nested objects

//input
{
  "a": {
    "b": {
      "c": {
        "d": {
          "e" : {
            "array": [
              1,
              2,
              3
            ]
          }
        }
      }
    }
  }
}
//output
[
  {
    "a.b.c.d.e.array": 1
  },
  {
    "a.b.c.d.e.array": 2
  },
  {
    "a.b.c.d.e.array": 3
  }
]

real life example

//input
[
  {
    "user_id" : 1,
    "email": "[e-mail]",
    "hobbies": [
      {
        "type": "sport",
        "name": "soccer",
        "dates": [
          "May 3rd",
          "May 4th",
          "May 5th"
        ]
      },
      {
        "type": "sport",
        "name": "basketball",
        "dates": [
          "June 3rd",
          "July 4th"
        ]
      }
    ]
  },
  {
    "user_id" : 2,
    "email": "[e-mail]"
  },
  {
    "user_id" : 3,
    "email": "[e-mail]",
    "hobbies": []
  }
]
//output
[{
    "user_id": 1,
    "email": "[e-mail]",
    "hobbies.type": "sport",
    "hobbies.name": "soccer",
    "hobbies.dates": "May 3rd"
}, {
    "user_id": 1,
    "email": "[e-mail]",
    "hobbies.type": "sport",
    "hobbies.name": "soccer",
    "hobbies.dates": "May 4th"
}, {
    "user_id": 1,
    "email": "[e-mail]",
    "hobbies.type": "sport",
    "hobbies.name": "soccer",
    "hobbies.dates": "May 5th"
}, {
    "user_id": 1,
    "email": "[e-mail]",
    "hobbies.type": "sport",
    "hobbies.name": "basketball",
    "hobbies.dates": "June 3rd"
}, {
    "user_id": 1,
    "email": "[e-mail]",
    "hobbies.type": "sport",
    "hobbies.name": "basketball",
    "hobbies.dates": "July 4th"
}, {
    "user_id": 2,
    "email": "[e-mail]"
}, {
    "user_id": 3,
    "email": "[e-mail]",
    "hobbies": null
}]

Options

Fields

delimiter

specify the delimiting value for nested objects.

var data = { "a": { "b" : "foo"} };
var options = {
  delimiter : "*" //default is '.'
}
var output = jsonSpread(data,options);
//output
{
  "a*b" : "foo"
}

removeEmptyArray

removes empty arrays

var data = { "a": "value_a" , "b": []};
var options = {
  removeEmptyArray: true //default is false
}
var output = jsonSpread(data,options);
//output
{
  "a" : "value_a"
}

emptyValue

you can define the value for empty arrays in options.
this is ignored if removeEmptyArray is true

var data = { "a": [] };
var options = {
  emptyValue: "EMPTY" //default is null
}
var output = jsonSpread(data,options);
//output
{
  "a" : "EMPTY"
}

Contributing

installation

Fork it, then do an npm install. everything should be in there

building

after writing in src folder, do:

npm run dist

to see if it builds

tests

I use mocha and chai to test.

npm test

write tests in /test folder.

Dependencies

This library currently depends on flat

License

MIT License