Skip to content

Flatten complex JSON objects and convert to csv, tab delimited, or html

License

Notifications You must be signed in to change notification settings

mfsnow/tabular-json

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

14 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Tabular JSON

This node module helps manipulate tabular data found in a JSON object. Data with sub-objects, including arrays, can be flattened, converted into an array, an HTML table, or a delimited string. Many options are available to customize each function.

Install

npm install tabular-json

Usage

var tabular = require('tabular-json');

Functions

  • flatten(obj, options) - Convert to array. Each row is an object.
  • array(obj, options) - Convert to array. Each row is a sub-array.
  • delimit(obj, options) - Convert to delimited string (such as csv).
  • html(obj, options) - Convert to HTML table <table>.

Flatten

flatten(obj, options)

  • obj - Object to convert to array.
  • options - (Optional) A JSON object containing customizations
    • headers - Array - Headers to include in output array. Defaults to all properties found in object.
    • sort - Array or String - Header(s) to sort by.
      • Prefix a string with minus '-' to sort in descending order.
    • dot - String - The string that sub-objects in header strings. Defaults to '.'.

flatten(obj, options) Example

var obj = [
  {
    Name: "Jane",
    Age: 47,
    Address: {
      City: "Detroit",
      State: "Michigan"
    }
  },
  {
    Name: "John",
    Age: 35,
    Address: {
      City: "New York",
      State: "New York"
    }
  },
  {
    Name: "Steve",
    Age: 35,
    Address: {
      City: "Buffalo",
      State: "New York"
    }
  }
];

var opts = {
  dot: ' / ',
  headers: ["Name", "Age","Address / City"],
  sort: ["-Age", "Address / City"] // Sort first by 'Age', oldest first, then by 'Address / City'
};

var result = tabular.flatten(obj, opts);

The variable result contains the array:

[
  {Name: "Jane", Age: 47, "Address / City": "Detroit"},
  {Name: "Steve", Age: 35, "Address / City": "Buffalo"},
  {Name: "John", Age: 35, "Address / City": "New York"}
]

Array

array(obj, options)

  • obj - Object to convert to array.
  • options - (Optional) A JSON object containing customizations. All options in flatten(), plus:
    • includeHeaders - Boolean - If true, the first element in output will be an array of the headers. Defaults to true.

array(obj, options) Example

opts = {
  sort: "Name"
};

result = tabular.array(obj, opts);

The variable result contains the array:

[
  ["Name", "Age", "Address.City", "Address.State"],
  ["Jane", 47, "Detroit", "Michigan"],
  ["John", 35, "New York", "New York"],
  ["Steve", 35, "Buffalo", "New York"]
]

array(obj, options) Complex Example

Tabular can handle much more complex objects. If sub-array are contained in obj, the output will reflect the sub-arrays by containing a row for each element. There is no limit to the complexity of the object.

var customers = [
  {
    name: "Acme Ltd",
    address: {
      city: "Las Vegas",
      state: "Nevada"
    },
    orders: [
      {
        id: "SO1",
        shipments: [
          {id: "INV1"}, {id: "INV2"}
        ]
      },
      { id: "SO2", orderedAt: new Date("January 1, 2000")}
    ],
    contacts: [
      "Jim",
      "Johanna"
    ]
  }, {
    name: "ABC Co",
    address: {
      city: "Las Angeles"
    },
    orders: [
      {id: "SO3",
    shipments: [{id: "INV3"}]}
    ]
  }, {
    name: "XYZ Inc"
  }
];

result = tabular.array(customers);

The variable result contains the array:

[
  [ 'name', 'address.city', 'address.state', 'orders.id', 'orders.shipments.id', 'orders.orderedAt', 'contacts' ],
  [ 'XYZ Inc', null, null, null, null, null, null ],
  [ 'Acme Ltd','Las Vegas','Nevada','SO2',null,Sat Jan 01 2000 00:00:00 GMT-0500 (EST),null ],
  [ 'Acme Ltd', 'Las Vegas', 'Nevada', 'SO1', 'INV1', null, null ],
  [ 'Acme Ltd', 'Las Vegas', 'Nevada', 'SO1', 'INV2', null, null ],
  [ 'ABC Co', 'Las Angeles', null, 'SO3', 'INV3', null, null ],
  [ 'Acme Ltd', 'Las Vegas', 'Nevada', null, null, null, 'Jim' ],
  [ 'Acme Ltd', 'Las Vegas', 'Nevada', null, null, null, 'Johanna' ]
]

Delimit

delimit(obj, options)

  • obj - Object to convert to delmited string.
  • options - (Optional) A JSON object containing customizations. All options in array(), plus:
    • separator - String - Value separator. Defaults to ','.
    • stringWrap - String - Wrapper for string values. Defaults to '"'.
    • escape - String or Function - String values can be manipulated by this function, or prepended with the string. Defaults to a function that doubles any the stringWrap within the string value.
      • Example: The value 6' 2" would escape to 6' 2"" using the default value.
      • function(value, wrap) - Function - Should return the escaped value, escaped in the desired format.
        • value - String - The original value.
        • wrap - String - The stringWrap variable, provided in the function.
    • eol - String - string to append at the end of each line. Defaults to '\n'.
    • dateFormatter - Function - Function that formats any Date value. Defaults to converting dates using the Date function toLocaleDateString().

delimit(obj, options) Example

obj = {
  Name: "John",
  Height: "6' \"2",
  "Birth Day": new Date("June 12, 1994")
};

opts = {
  sort: "Name",
  separator: ';',
  stringWrap: "'",
  escape: function(str, wrap) {return str.replace(new RegExp("("+wrap+")", "g"), '\\$1');},
  dateFormatter: function(date) {return date.toISOString().substr(0,10);}
};

result = tabular.delimit(obj, opts);

The variable result contains the string:

'Name';'Height';'Birth Day'
'John';'6\' "2';1994-06-12

Html

html(obj, options)

  • obj - Object to convert to an html string.
  • options - (Optional) A JSON object containing customizations. All options in array(), plus:
    • separator - String - Separates html elements. Defaults to '\t'.
    • eol - String - End of line string. Defaults to '\n'.
    • escapeInnerHTML - Boolean - Determines if values that contain HTML elements should be escaped so they would not be included in the DOM. Defaults to true.
    • convertLinks - Boolean - Determines if values that look like web links should be converted to link anchors. Defaults to false.
    • classes - Object - Add class values by including the properties (all optional): {table, thead, tr, th, tbody, td}.

html(obj, options) Example

opts = {
  dot: "/",
  separator: '  ',
  dateFormatter: function(date) {return date.toISOString().substr(0,10);},
  sort: ["name", "address/state", "address/city", "-contacts"],
  classes: {table: "table table-striped table-bordered"}
};

result = tabular.html(customers, opts);

The variable result contains the string:

<table class="table table-striped table-bordered">
  <thead>
    <tr>
      <th>name</th>
      <th>address/city</th>
      <th>address/state</th>
      <th>orders/id</th>
      <th>orders/shipments/id</th>
      <th>orders/orderedAt</th>
      <th>contacts</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>ABC Co</td>
      <td>Las Angeles</td>
      <td></td>
      <td>SO3</td>
      <td>INV3</td>
      <td></td>
      <td></td>
    </tr>
    <tr>
      <td>Acme Ltd</td>
      <td>Las Vegas</td>
      <td>Nevada</td>
      <td>SO2</td>
      <td></td>
      <td>2000-01-01</td>
      <td></td>
    </tr>
    <tr>
      <td>Acme Ltd</td>
      <td>Las Vegas</td>
      <td>Nevada</td>
      <td>SO1</td>
      <td>INV1</td>
      <td></td>
      <td></td>
    </tr>
    <tr>
      <td>Acme Ltd</td>
      <td>Las Vegas</td>
      <td>Nevada</td>
      <td>SO1</td>
      <td>INV2</td>
      <td></td>
      <td></td>
    </tr>
    <tr>
      <td>Acme Ltd</td>
      <td>Las Vegas</td>
      <td>Nevada</td>
      <td></td>
      <td></td>
      <td></td>
      <td>Johanna</td>
    </tr>
    <tr>
      <td>Acme Ltd</td>
      <td>Las Vegas</td>
      <td>Nevada</td>
      <td></td>
      <td></td>
      <td></td>
      <td>Jim</td>
    </tr>
    <tr>
      <td>XYZ Inc</td>
      <td></td>
      <td></td>
      <td></td>
      <td></td>
      <td></td>
      <td></td>
    </tr>
  </tbody>
</table>
name address/city address/state orders/id orders/shipments/id orders/orderedAt contacts
ABC Co Las Angeles SO3 INV3
Acme Ltd Las Vegas Nevada SO2 2000-01-01
Acme Ltd Las Vegas Nevada SO1 INV1
Acme Ltd Las Vegas Nevada SO1 INV2
Acme Ltd Las Vegas Nevada Jim
Acme Ltd Las Vegas Nevada Johanna
XYZ Inc

About

Flatten complex JSON objects and convert to csv, tab delimited, or html

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published