Init

Author: papb

.editorconfig

@@ -0,0 +1,8 @@
+root = true
+
+[*]
+indent_style = tab
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true

.gitattributes

@@ -0,0 +1 @@
+* text=auto eol=lf

.gitignore

@@ -0,0 +1,2 @@
+node_modules
+dist

.npmrc

@@ -0,0 +1 @@
+package-lock=false

.travis.yml

@@ -0,0 +1,3 @@
+language: node_js
+node_js:
+  - '12'

license

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) Pedro Augusto de Paula Barbosa <[email protected]>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package.json

@@ -0,0 +1,89 @@
+{
+	"name": "json-excel",
+	"version": "0.0.0",
+	"description": "Create a pretty Excel table from JSON data with a very simple API",
+	"license": "MIT",
+	"repository": "papb/json-excel",
+	"author": {
+		"name": "Pedro Augusto de Paula Barbosa",
+		"email": "[email protected]"
+	},
+	"keywords": [
+		"excel",
+		"json",
+		"table",
+		"json to excel",
+		"json-to-excel",
+		"convert",
+		"xlsx",
+		"generate",
+		"sheet",
+		"worksheet",
+		"workbook",
+		"tabular",
+		"data",
+		"xls"
+	],
+	"engines": {
+		"node": ">=10"
+	},
+	"scripts": {
+		"build": "del-cli dist && tsc",
+		"release": "npm run build && np --no-2fa && npm pack && echo Please put the generated .tgz as a release asset on GitHub",
+		"test": "npm run build && xo && ava",
+		"lint": "tsc --noEmit && xo",
+		"ava": "npm run build && ava"
+	},
+	"main": "dist/source",
+	"types": "dist/source",
+	"files": [
+		"dist/source"
+	],
+	"dependencies": {
+		"exceljs": "^4.0.1",
+		"fs-jetpack": "^2.4.0"
+	},
+	"devDependencies": {
+		"@ava/typescript": "^1.1.1",
+		"@types/node": "^13.13.12",
+		"ava": "^3.9.0",
+		"del-cli": "^3.0.1",
+		"np": "https://github.com/pixelastic/np/tarball/c3ab2e3b053c7da0ce40a572ca1616273ac080f8",
+		"source-map-support": "^0.5.19",
+		"tempy": "^0.5.0",
+		"typescript": "~3.9.5",
+		"xo": "^0.32.0"
+	},
+	"ava": {
+		"verbose": true,
+		"timeout": "60m",
+		"require": [
+			"source-map-support/register"
+		],
+		"typescript": {
+			"rewritePaths": {
+				"source/": "dist/source/",
+				"test/": "dist/test/"
+			}
+		}
+	},
+	"xo": {
+		"ignore": [
+			"**/*.js"
+		],
+		"rules": {
+			"@typescript-eslint/prefer-readonly-parameter-types": "off",
+			"unicorn/prevent-abbreviations": "off",
+			"unicorn/no-for-loop": "off",
+			"ava/no-ignored-test-files": "off",
+			"linebreak-style": [
+				"error",
+				"unix"
+			],
+			"object-curly-spacing": [
+				"error",
+				"always"
+			]
+		}
+	}
+}

readme-example.png

@@ -0,0 +1,129 @@
+# json-excel [![Build Status](https://travis-ci.com/papb/json-excel.svg?branch=master)](https://travis-ci.com/papb/json-excel)
+
+> Create a pretty Excel table from JSON data with a very simple API
+
+
+## Highlights
+
+* Pretty output
+* Intelligently auto-fits cell sizes by default
+* Checks for [Excel limitations](https://support.microsoft.com/en-ie/office/excel-specifications-and-limits-1672b34d-7043-467e-8e27-269d656771c3) automatically (such as maximum cell length) and throws helpful errors if any limit is exceeded
+* Get the *Format as Table* Excel styling, with filterable headers, by simply enabling an option
+* Written in TypeScript (you get autocomplete suggestions in your IDE!)
+
+
+## Install
+
+```
+$ npm install json-excel
+```
+
+
+## Usage
+
+```js
+const jsonToExcel = require('json-excel');
+
+(async () => {
+	await jsonToExcel([
+		{
+			sheetName: 'Hello World',
+			data: [
+				['Foo', 'Bar', 'Baz'],
+				['A large string here but with\none line break', 'Hi', 'Test'],
+				[
+					'\'starting single quote\nis rendered normally',
+					'Lots\nof\nline\nbreaks',
+					'Auto-fits cells with a little extra margin'
+				],
+				['Nice!', '', 'Quick and to the point!']
+			],
+			formatAsTable: true
+		}
+	], 'example.xlsx', { overwrite: true });
+})();
+```
+
+Output is an excel file called `example.xlsx` with a single sheet (called `Hello World`) and the following content:
+
+![](readme-example.png)
+
+
+## API
+
+<!-- Ensure this part is consistent with ./types.ts and ./defaults.ts -->
+
+### jsonToExcel(jsonSheets, destinationPath, options?)
+
+Async function that creates a xlsx file with the provided data.
+
+#### jsonSheets
+
+Type: `object[]`
+
+An array of objects, each representing one sheet, with:
+
+* `sheetName` (`string`, required): The name of the Worksheet (shown in the sheet tab in the bottom in Excel).
+* `data` (`string[][]`, required): The data to be populated in the Worksheet.
+* `formatAsTable` (`boolean`, optional, default `false`): Whether or not to enable the *"Format as Table"* styling, like in the above example. This will enable striped rows and filter arrows on all headers.
+* `tableTheme` (`string`, optional, default `'TableStyleMedium9'`): Which theme to use when formatting as table. This option is ignored if `formatAsTable` is `false`. The default value corresponds to the one from the screenshot above (medium blue). The list of supported themes is shown right in your IDE via autocomplete suggestions to this option. The autocomplete works even if you are not using TypeScript!
+* `autoTrimWhitespace` (`boolean`, optional, default `true`): Whether or not to automatically remove leading and trailing whitespace from each cell. Having this enabled is great to make the cell content alignment be consistent with what is visible.
+* `autoFitCellSizes` (`boolean`, optional, default `true`): Whether or not to automatically calculate best widths for every column and best heights for every row.
+* `autoFitCellSizesOptions` (`object`, optional): Extra options for configuring the behavior of the auto-fitting of cell sizes:
+	* `minHeight` (`number`, optional, default `15`): The minimum height (in *"excel points"*) for every row.
+	* `maxHeight` (`number`, optional, default `408`): The maximum height (in *"excel points"*) for every row. Cannot be greater than 408 (this is an Excel limitation).
+	* `minWidth` (`number`, optional, default `6`): The minimum width (in *"excel points"*) for every column.
+	* `maxWidth` (`number`, optional, default `170`): The maximum width (in *"excel points"*) for every column. Cannot be greater than 254 (this is an Excel limitation).
+	* `horizontalPadding` (`number`, optional, default `3`): Extra horizontal padding (in *"excel points"*) for every column. This amount will be added to the auto-calculated minimal width in which the contents fit.
+	* `verticalPadding` (`number`, optional, default `2`): Extra vertical padding (in *"excel points"*) for every cell. This amount will be added to the auto-calculated minimal height in which the contents fit.
+
+#### destinationPath
+
+Type: `string`
+
+The path (absolute, or relative to `process.cwd()`) in which the new xlsx file should be created. In windows, both `/` and `\` are accepted as path separators.
+
+#### options
+
+Type: `object`
+
+##### overwrite
+
+Type: `boolean`
+Default: `false`
+
+Whether or not to overwrite the destination file if it already exists.
+
+
+## Tip: usage with `object[]` instead of `string[][]`
+
+If, instead of directly tabular data, you have a list of objects such as...
+
+```js
+const data = [
+	{ name: 'Grape', size: 'small' },
+	{ name: 'Watermelon', size: 'big' },
+	{ name: 'Apple', size: 'medium' }
+];
+```
+
+...you can use `jsonToExcel` by simply converting that to a `string[][]` first, with a simple loop. Example:
+
+```js
+const headers = ['Name', 'Size'];
+const dataAs2DArray = data.map(fruit => [fruit.name, fruit.size]);
+
+jsonToExcel([{
+	sheetName: 'Fruits',
+	data: [
+		headers,
+		...dataAs2DArray
+	],
+	formatAsTable: true
+}], 'fruits.xlsx');
+```
+
+
+## License
+
+MIT © [Pedro Augusto de Paula Barbosa](https://github.com/papb)

readme.md

@@ -0,0 +1,14 @@
+export function assertDimensionsAcceptable(rows: number, columns: number): void {
+	// https://support.microsoft.com/en-ie/office/excel-specifications-and-limits-1672b34d-7043-467e-8e27-269d656771c3
+
+	const MAX_ROWS = 1048576;
+	const MAX_COLUMNS = 16384;
+
+	if (rows > MAX_ROWS) {
+		throw new TypeError(`Expected at most ${MAX_ROWS} rows, got ${rows}`);
+	}
+
+	if (columns > MAX_COLUMNS) {
+		throw new TypeError(`Expected at most ${MAX_COLUMNS} columns, got ${columns}`);
+	}
+}

source/assert-dimensions-acceptable.ts

@@ -0,0 +1,16 @@
+export function assertValidCellContent(string: string): void {
+	// https://support.microsoft.com/en-ie/office/excel-specifications-and-limits-1672b34d-7043-467e-8e27-269d656771c3
+
+	const MAX_CHARS = 32767;
+	const MAX_LINEFEEDS = 253;
+
+	if (string.length > MAX_CHARS) {
+		throw new TypeError(`Expected at most ${MAX_CHARS} characters, got ${string.length}`);
+	}
+
+	const amountOfLinefeeds = string.split('\n').length - 1;
+
+	if (amountOfLinefeeds > MAX_LINEFEEDS) {
+		throw new TypeError(`Expected at most ${MAX_LINEFEEDS} linefeeds (\`\\n\`), got ${amountOfLinefeeds}`);
+	}
+}

source/assert-valid-cell-content.ts

@@ -0,0 +1,23 @@
+function assertValidSheetName(name: string): void {
+	if (name === '') {
+		throw new TypeError('Sheet name cannot be empty.');
+	}
+
+	if (name.length > 31) {
+		throw new TypeError('Sheet name cannot exceed 31 characters.');
+	}
+
+	if (/[':\\/?*[\]]/.test(name)) {
+		throw new TypeError('Sheet name cannot include any of the following characters: []\':\\/?*');
+	}
+}
+
+export function assertValidSheetNames(names: string[]): void {
+	for (const name of names) {
+		assertValidSheetName(name);
+	}
+
+	if (names.length !== [...new Set(names.map(name => name.toLowerCase()))].length) {
+		throw new TypeError('Two sheets cannot have the same name (case-insensitive).');
+	}
+}

source/assert-valid-sheet-names.ts

@@ -0,0 +1,76 @@
+import { getMax, getSum, clamp } from './numeric-helpers';
+import { getStringVisualWidth, predictAmountOfLineWraps } from './visual-string-width';
+import type { ExpandedAutoFitCellSizesOptions } from './types';
+
+export function getStringHeight(string: string, maxVisualWidth?: number): number {
+	const lines = string.split(/\r?\n/);
+
+	if (!maxVisualWidth) {
+		return lines.length;
+	}
+
+	return lines.length + getSum(
+		lines.map(line => predictAmountOfLineWraps(line, maxVisualWidth))
+	);
+}
+
+function getMinimalFittingColumnWidth(cellsInColumn: string[]): number {
+	return getMax(
+		cellsInColumn.map(cell => getStringVisualWidth(cell))
+	);
+}
+
+function getMinimalFittingRowHeight(cellsInRow: string[], realColumnWidths: number[]): number {
+	// Since the actual applied column width may be different from the minimal fitting
+	// column width, in a few edge cases the minimal fitting height might be actually
+	// greater than 1 + the number of explicit linebreaks in the string, due to auto-applied
+	// line wraps in long lines.
+
+	const maxAmountOfLines = getMax(
+		cellsInRow.map((cell, index) => getStringHeight(cell, realColumnWidths[index]))
+	);
+
+	return 15 * maxAmountOfLines;
+}
+
+export type AutoFitSizesResult = {
+	columnWidths: number[];
+	rowHeights: number[];
+};
+
+export function getAutoFitCellSizes(
+	data: string[][],
+	considerExtraRoomForHeaderFilterArrow: boolean,
+	options: ExpandedAutoFitCellSizesOptions
+): AutoFitSizesResult {
+	const result: AutoFitSizesResult = {
+		columnWidths: [],
+		rowHeights: []
+	};
+
+	const rowCount = data.length;
+	const columnCount = data[0].length;
+
+	for (let ci = 0; ci < columnCount; ci++) {
+		let width = getMinimalFittingColumnWidth(data.map(row => row[ci]));
+
+		if (considerExtraRoomForHeaderFilterArrow) {
+			width = Math.max(width, 4 + getStringVisualWidth(data[0][ci]));
+		}
+
+		width += options.horizontalPadding;
+		width = clamp(width, options.minWidth, options.maxWidth);
+
+		result.columnWidths.push(width);
+	}
+
+	for (let ri = 0; ri < rowCount; ri++) {
+		let height = getMinimalFittingRowHeight(data[ri], result.columnWidths);
+		height += options.verticalPadding;
+		height = clamp(height, options.minHeight, options.maxHeight);
+
+		result.rowHeights.push(height);
+	}
+
+	return result;
+}