feat(api): add pass-through support for data representation (#114)

* Add pass-through support for data representation

* Add pass-through code to helper
* Add and validate unit tests
* Update README with revised documentation

* Disable eslint errors for comment

README.md

@@ -79,6 +79,22 @@ var buffer = xlsx.build([{name: "myFirstSheet", data: dataSheet1}, {name: "mySec
 _Beware that if you try to merge several times the same cell, your xlsx file will be seen as corrupted._
 
 
+  * Using Primitive Object Notation
+Data values can also be specified in a non-abstracted representation.
+
+Examples:
+```js
+const rowAverage = [[{t:'n', z:10, f:'=AVERAGE(2:2)'}], [1,2,3];
+var buffer = xlsx.build([{name: "Average Formula", data: rowAverage}]);
+```
+
+Refer to [xlsx](https://sheetjs.gitbooks.io) documentation for valid structure and values:
+- Cell Object: https://sheetjs.gitbooks.io/docs/#cell-object
+- Data Types: https://sheetjs.gitbooks.io/docs/#data-types
+- Format: https://sheetjs.gitbooks.io/docs/#number-formats
+
+
+
 ### Troubleshooting
 
 This library requires at lease nodeJS v4. For legacy versions, you can use this workaround before using the lib.

src/helpers.js

@@ -40,6 +40,23 @@ const buildSheetFromMatrix = (data, options = {}) => {
         cell.t = 'n';
         cell.v = buildExcelDate(cell.v);
         cell.z = cell.z || XLSX.SSF._table[14]; // eslint-disable-line no-underscore-dangle
+
+      /* eslint-disable spaced-comment, no-trailing-spaces */
+      /***
+       * Allows for an non-abstracted representation of the data
+       * 
+       * example: {t:'n', z:10, f:'=AVERAGE(A:A)'}
+       * 
+       * Documentation:
+       * - Cell Object: https://sheetjs.gitbooks.io/docs/#cell-object
+       * - Data Types: https://sheetjs.gitbooks.io/docs/#data-types
+       * - Format: https://sheetjs.gitbooks.io/docs/#number-formats
+       **/
+      /* eslint-disable spaced-comment, no-trailing-spaces */
+      } else if (isObject(cell.v)) {
+        cell.t = cell.v.t;
+        cell.f = cell.v.f;
+        cell.z = cell.v.z;
       } else {
         cell.t = 's';
       }

test/specs/helper.spec.js

@@ -18,5 +18,28 @@ describe('node-xlsx helper', () => {
       expect(typeof buildSheetFromMatrix(notArrayData)).toBe('object');
     });
 
+    describe('with primitive data objects', () => {
+      it('should display data in percentage format with 2-decimal precision', () => {
+        const primitive = [
+          [{t:'n', z:10, f:'=AVERAGE(2:2)'}]
+        ];
+
+        let sheet = buildSheetFromMatrix(primitive);
+        expect(sheet.A1.t).toBe('n');
+        expect(sheet.A1.f).toBe('=AVERAGE(2:2)');
+        expect(sheet.A1.z).toBe('0.00%');
+      })
+
+      it('should display data in percentage format with 2-decimal precision', () => {
+        const primitive = [
+          [{t:'n', z:4, f:'=SUM(2:2)'}]
+        ];
+
+        let sheet = buildSheetFromMatrix(primitive);
+        expect(sheet.A1.t).toBe('n');
+        expect(sheet.A1.f).toBe('=SUM(2:2)');
+        expect(sheet.A1.z).toBe('#,##0.00');
+      })      
+    })
   });
 });