npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@json2csv/transforms

v7.0.6

Published

json2csv built-in transforms. A transform is a function that receives a data recod and returns a transformed record. Transforms are executed in order before converting the data record into a CSV row.

Downloads

126,495

Readme

@json2csv/transforms

npm version npm monthly downloads Node.js CI Coverage Status license

A transform is a function to preprocess data before it is converted into CSV by json2csv (in any of its flavours). Each transform receives each data record, performs some processing and returns a transformed record.

json2csv ecosystem

There are multiple flavours of json2csv where you can use transforms:

  • Plainjs: Includes the Parser API and a new StreamParser API which doesn't the conversion in a streaming fashion in pure js.
  • Node: Includes the Node Transform and Node Async Parser APIs for Node users.
  • WHATWG: Includes the WHATWG Transform Stream and WHATWG Async Parser APIs for users of WHATWG streams (browser, Node or Deno).
  • CLI: Includes the CLI interface.

Built-in transforms

There is a number of built-in transform provided by this package.

import { unwind, flatten } from '@json2csv/transforms';

Unwind

The unwind transform deconstructs an array field from the input item to output a row for each element. It's similar to MongoDB's $unwind aggregation.

The transform needs to be instantiated and takes an options object as arguments containing:

  • paths <String[]> List of the paths to the fields to be unwound. It's mandatory and should not be empty.
  • blankOut <Boolean> Flag indicating whether to unwind using blank values instead of repeating data or not. Defaults to false.

Examples

Simple unwind
Programmatic APIs
import { Parser } from '@json2csv/plainjs';
import { unwind } from '@json2csv/transforms';

const data = [
  { "carModel": "Audi", "price": 0, "colors": ["blue","green","yellow"] },
  { "carModel": "BMW", "price": 15000, "colors": ["red","blue"] },
  { "carModel": "Mercedes", "price": 20000, "colors": "yellow" },
  { "carModel": "Porsche", "price": 30000, "colors": ["green","teal","aqua"] },
  { "carModel": "Tesla", "price": 50000, "colors": []}
];

try {
  const opts = {
    transforms: [
      unwind({ paths: ['colors'] })
    ]
  };
  const parser = new Parser(opts);
  const csv = parser.parse(data);
  console.log(csv);
} catch (err) {
  console.error(err);
}
CLI

At the moment, only built-in transforms are supported by the CLI interface.

$ json2csv -i data.json --unwind "color"

Flatten

Flatten nested JavaScript objects into a single level object.

The transform needs to be instantiated and takes an options object as arguments containing:

  • objects <Boolean> Flag indicating whether to flatten JSON objects or not. Defaults to true.
  • arrays<Boolean> Flag indicating whether to flatten Arrays or not. Defaults to false.
  • separator <String> Separator to use between the keys of the nested JSON properties being flattened. Defaults to ..
// Default
flatten();

// Custom separator '__'
flatten({ separator: '_' });

// Flatten only arrays
flatten({ objects: false, arrays: true });

Custom transforms

Users can create their own transforms as simple functions.

function doNothing(item) {
  // apply tranformations or create new object
  return transformedItem;
}

or using ES6

const doNothing = (item) => {
  // apply tranformations or create new object
  return transformedItem;
};

For example, let's add a line counter to our CSV, capitalize the car field and change the price to be in Ks (1000s).

function addCounter() {
  let counter = 1;
  return (item) => ({
    counter: counter++,
    ...item,
    car: item.car.toUpperCase(),
    price: item.price / 1000,
  });
}

The reason to wrap the actual transform in a factory function is so the counter always starts from one and you can reuse it. But it's not strictly necessary.

How to use transforms

Transforms are added to the transforms option when creating a parser. They are applied in the order in which they are declared.

Programmatic APIs

import { Parser } from '@json2csv/plainjs';
import { unwind, flatten } from '@json2csv/transforms';
import { addCounter } from './custom-transforms';

try {
  const opts = {
    transforms: [
      unwind({ paths: ['fieldToUnwind','fieldToUnwind.subfieldToUnwind'], blankOut: true }),
      flatten({ object: true, array: true, separator: '_'}),
      addCounter()
    ]
  };
  const parser = new Parser(opts);
  const csv = parser.parse(myData);
  console.log(csv);
} catch (err) {
  console.error(err);
}

CLI

At the moment, only built-in transforms are supported by the CLI interface.

$ json2csv -i input.json \
  --unwind "fieldToUnwind","fieldToUnwind.subfieldToUnwind" \
  --unwind-blank \
  --flatten-objects \
  --flatten-arrays \
  --flatten-separator "_"

Complete Documentation

See https://juanjodiaz.github.io/json2csv/#/advanced-options/transforms.

License

See LICENSE.md.