Idiomatic API

[dandv]

I've been toying around with this library for the past 24 hours, and while I appreciate the amazing effort that went into it, I wonder if the API could be made to be more similar to that of other libraries in the JavaScript ecosystem.

What do I mean? Imagine you don't know anything about SheetJS, and want to create a workbook with a worksheet in it. How would you name the methods to do that? Would you come up with this?

const XLSX = require('xlsx');

const workbook = XLSX.utils.book_new();

const ws = XLSX.utils.json_to_sheet([
  { Product: 'bananas', Qty: 10 },
  { Product: 'oranges', Qty: 5 },
]);

XLSX.utils.book_append_sheet(workbook, ws, 'Sheet name');

This API seems very peculiar to me. Nevermind that JS favors camelCase to underscore_case, calling static methods on XLSX is unwieldy. I would find something like this a lot more idiomatic:

const SheetJS = require('xlsx');  // this library handles ODS as well, not just "XLSX"
const workbook = new SheetJS();
const worksheet = workbook.addSheet('Sheet name');
worksheet.addRows([
  { Product: 'bananas', Qty: 10 },
  { Product: 'oranges', Qty: 5 },
]);
workbook.save('filename');

UPDATE: I've just discovered exceljs. The API is very similar to what I've proposed above: new to create a workbook, workbook.addWorksheet, worksheet.addRow.

[SheetJSDev]

There are three independent but related questions embedded here:

1. Why is the node module called xlsx?

When we first started, MIT license was popular in the JS community and we wanted to stick with that. The project leaned on ECMA-376, which was an open standard and had no encumbrances. XLS and other related specs are not; they are covered under the Microsoft "Open Specifications Promise", which is essentially a covenant not to sue. As a result, we kept them separate: xlsjs for XLS, harb for the plaintext formats. Other related libraries like ssf are shared with all spreadsheet formats, and over time it became a tangled web with a wrapper library j. To simplify, we eventually shifted everything over to Apache 2.0 and merged xLS and the other formats into XLSX.

If you're interested in the history of open source pertaining to spreadsheets, read https://github.com/kennethreitz/tablib/issues/114

2. Why is the API shaped in a non-idiomatic way (snake_case, for example)?

The API is more or less how you would design a C API, which reflects our personal histories. In most C styles snake_case is preferred, and C libraries generally follow the "bag of static functions" style.

3. Why are plain objects used instead of new prototypal objects?

When we first started, back when ES5 was the latest version of the language specification, there was no easy way to serialize and deserialize objects created with a constructor. Plain objects have the advantage of JSON stringification, which lets you do cool things like serialize the entire workbook object and send it from the main browser thread to a Web Worker in the web browser. The meteor demo uses this feature to send the workbook object from the server to the client. Other approaches make it exceedingly difficult to do the same.

If you're starting in 2018 and only planning to create basic files in node, there are definitely more idiomatic styles. Object-mode streams and generator functions make for even neater APIs. But for the varied use cases the most flexible approach is preferable.

[dandv]

Thank you for the detailed explanation!