Confusing behavior when options.columns length doesn't match input key length

[griffin-rickle]

This is perhaps not a bug, but at least an opportunity to improve the documentation and user experience provided by the library. When using tablemark to print some data received from a database call where some bindings were optional, I stumbled across this behavior. Consider the following code snippet:

import { tablemark } from "tablemark"

const headers = ["column1", "column2", "mismatched_column"]
const data = [{"column1": "value1", "mismatched_column": "mismatched_value"}]
console.log(tablemark(data, { columns: headers }).toString());

At first blush I had expect the following markdown table to be printed:

| column1 | column2 | mismatched_column |
| :------ | :-----  | :---------------- |
| value1  |         | mismatched_value  |

The table without the column2 column would have also made sense.

However this is what is printed:

| column1 | column2          |
| :------ | :--------------- |
| value1  | mismatched_value |

I understand that there is a note in the tablemark README stating that "The keys of the first encountered object are used for the table's headers. By default, any other keys from successive objects will be ignored, excluding those columns from the table", but I do not believe that explanation sufficiently highlights the behavior displayed here. A more apparent warning about the strategy which tablemark uses to determine which columns it prints, how it retrieves the input values based on those columns, and how those two behaviors interact specifically with the columns option would be really helpful.

For completeness, I am able to work around this by creating a defaults object and merging it with each of my data objects, like so:

import { tablemark } from "tablemark"

const headers = ["column1", "column2", "mismatched_column"]
const defaultValues = headers.reduce((acc, header) => {
  return {
    ...acc,
    [header]: ""
  }}, 
  {});
const data = [{"column1": "value1", "mismatched_column": "mismatched_value"}]
const defaultedData = data.map((entry) => { return { ...defaultValues, ...entry } });
console.log(tablemark(defaultedData, { caseHeaders: false }).toString());

This code snippet prints what I would expect:

| column1 | column2 | mismatched_column |
| :------ | :------ | :---------------- |
| value1  |         | mismatched_value  |

I'm just not sure if this is highlighted enough in the documentation.

[haltcase]

Hey @griffin-rickle

What you're doing by setting options.columns to that array of strings is providing the names that should be used for columns 1..N, not setting which columns to display.

options.columns
Describe the columns of the table. Each column can be a simple string to rename the column or an object with properties to further customize the column's behavior.

I see how the output could be confusing, though. What would be your expectation here? I don't know if it would be preferable for tablemark to throw an error when options.columns.length !== Object.keys(data[0]).length.

If you think we can solve this purely through documentation, I'm happy to accept a PR where you add something you think clears it up.

[griffin-rickle]

Hey @haltcase -- sorry for posting on a Friday afternoon and letting it sit :) I think we're both tracking what the other is saying here, and I agree that it can be fixed with a documentation update. I've gone ahead and created a PR against the canary branch with some initial verbage. I am of course open to suggestions and edits. Thanks!

[griffin-rickle]

Actually @haltcase the more I think about this the more I think the library should either be exerting more authority over this issue. I think there are a couple of paths to take based on what your vision of the library is.

1. Like you mentioned, throw an error on this condition options.columns.length !== Object.keys(data[0]).length
   a. This doesn't really address tablemark's assumption that the data is normalized, though.
2. Instead of just taking the keys of the first data object, resolve a set of the keys contained in each of the objects in the data array.
   a. This has a performance tradeoff (having to iterate the entire data array before iterating again to construct the table) with the advantage of more options when it comes to interactions between the keys of the data objects and the options.columns configuration.

Ultimately it's up to you; I have this working in my codebase by subbing in default values for each of the column headers I expect to be in the data. I am not sure when I will have time to maybe do a more in depth analysis and possibly a code change to implement either of these changes.