[feature request] Column name customization / mapping

[jacobq]

This isn't a big deal since I can achieve the same result by suppressing the header field from the output and writing it myself, it would be nice if there were a configuration option to map a custom name to a given field, e.g.

const opts = {
  // these are used to grab the associated data from the JSON
  fields: ['id', 'name', 'item.color'],

  // these are used to generate custom names in the header row
  fieldNames: {
    // id not specified, defaults to 'id' as per current behavior
    name: 'Custom name',
    'item.color': 'Color',
  }
};

At the same time it might be worth thinking about allow other types of field/column configuration options, such as those mentioned in #195 e.g.

const opts = {
  // these are used to grab the associated data from the JSON
  fields: ['id', 'name', 'item.color'],

  // these are used to specify/override configuration options for fields/columns
  fieldOptions: {
    // id not specified, use defaults / current behavior
    name: {
      label: 'Custom name',
      quote: 'always', // 'never', 'auto', ...
    }
    'item.color': {
      label: 'Pretty color'
      // other options not specified -- use defaults
    },
  }
};

Requested info (though not really relevant here):

$ yarn why json2csv
yarn why v1.12.3
[1/4] Why do we have the module "json2csv"...?
[2/4] Initialising dependency graph...
[3/4] Finding dependency...
[4/4] Calculating file sizes...
=> Found "[email protected]"
info Has been hoisted to "json2csv"
info This module exists because it's specified in "dependencies".
info Disk size without dependencies: "612KB"
info Disk size with unique dependencies: "864KB"
info Disk size with transitive dependencies: "864KB"
info Number of shared dependencies: 4
Done in 0.86s.

$ node -v; npm -v; uname -a;
v11.5.0
6.5.0
Linux fractal 4.9.0-8-amd64 #1 SMP Debian 4.9.110-3+deb9u6 (2018-10-08) x86_64 GNU/Linux

[jacobq]

Ha, just noticed this already happened in v3.x
https://github.com/zemirco/json2csv/blob/v3.11.5/README.md#example-fields-option
Also there seems to be some more work coming soon in #338

[jacobq]

Maybe this really just means the examples should be updated to demonstrate this capability as I did not see it until just now :)

[juanjoDiaz]

Example 3 in the documentation shows it:
http://www.mircozeiss.com/json2csv/#example-3
https://github.com/zemirco/json2csv#example-3

How would you like to see it in the docs?

[jacobq]

How would you like to see it in the docs?

The example is OK, but in my opinion there are two major opportunities for improvement:

1. The readme is like 700 lines long and feels cluttered / unorganized. Splitting CLI & programmatic usage into separate files may help. Using <details>/<summary> (collapsibles) may help. Using a "table of contents" with links may help (example). I don't have "the answer" for you, just trying to explain something that I think makes the documentation less helpful for people.

2. In general, API docs are even better than examples. I realize that it's a little tricky here because there's basically one big function being documented, but perhaps there is a way to break things down logically instead of just enumerating use cases.

[knownasilya]

The docs are also deployed as a website with a TOC: http://www.mircozeiss.com/json2csv/

I do agree that it might be time to add API docs.