Export to plain text, css, html, json, csv, tsv, xls, xml files from JSON.

Installation

yarn add export-from-json

or

npm i --save export-from-json

or

pnpm i --save export-from-json

Usage

exportFromJSON supports CommonJS, EcmaScript Module, UMD importing.

exportFromJSON receives the option as the Types Chapter demonstrated, and it uses a front-end downloader as the default processor. In browser environment, there is a content size limitation on the default processor, consider using the server side solution.

In module system

import exportFromJSON from 'export-from-json'

const data = [{ foo: 'foo'}, { bar: 'bar' }]
const fileName = 'download'
const exportType =  exportFromJSON.types.csv

exportFromJSON({ data, fileName, exportType })

In browser

Check the codepen example

<script src="https://unpkg.com/export-from-json/dist/umd/index.min.js"></script>
<script>
    const data = [{ foo: 'foo'}, { bar: 'bar' }]
    const fileName = 'download'
    const exportType = 'csv'

    window.exportFromJSON({ data, fileName, exportType })
</script>

In Node.js server

exportFromJSON returns what the option processor returns, we can use it on server side for providing a converting/downloading service:

const http = require('http')
const exportFromJSON = require('export-from-json')

http.createServer(function (request, response){
    // exportFromJSON actually supports passing JSON as the data option. It's very common that reading it from http request directly.
    const data = '[{"foo":"foo"},{"bar":"bar"}]'
    const fileName = 'download'
    const exportType = 'txt'

    const result = exportFromJSON({
        data,
        fileName,
        exportType,
        processor (content, type, fileName) {
            switch (type) {
                case 'txt':
                    response.setHeader('Content-Type', 'text/plain')
                    break
                case 'css':
                    response.setHeader('Content-Type', 'text/css')
                    break
                case 'html':
                    response.setHeader('Content-Type', 'text/html')
                    break
                case 'json':
                    response.setHeader('Content-Type', 'text/plain')
                    break
                case 'csv':
                    response.setHeader('Content-Type', 'text/csv')
                    break
                case 'tsv':
                    response.setHeader('Content-Type', 'text/tab-separated-values')
                    break
                case 'xls':
                    response.setHeader('Content-Type', 'application/vnd.ms-excel')
                    break
            }
            response.setHeader('Content-disposition', 'attachment;filename=' + fileName)
            return content
        }
    })

    response.write(result)
    response.end()
}).listen(8080, '127.0.0.1')

Types

Note: JSON refers to a parsable JSON string or a serializable JavaScript object. For json, csv, tsv, xls, and xml exports, string input is parsed as JSON. For txt, css, and html exports, string input is exported as-is.

For csv, tsv, and xls exports, parsed input must be an array of plain objects (each row must be a non-null, non-array object). Primitives, null values, arrays, and class instances in row positions are rejected.

TSV exports always use a tab delimiter, the .tsv extension, and the text/tab-separated-values media type. For compatibility with common spreadsheet tools, fields containing tabs are encoded with the same double-quote extension used by the CSV encoder. Strict IANA TSV consumers may reject embedded tabs even when quoted.

The legacy xls export contains an HTML table that spreadsheet applications can open; it is not a binary BIFF workbook or an XLSX archive. Consumers that require a native workbook format should convert the exported table with a dedicated spreadsheet library.

XML exports do not include a DOCTYPE. When a source field name must be normalized into a valid XML element name, the original key is preserved in an escaped name attribute. Circular references are rejected with the path at which the cycle was found.

| Option name | Required | Type | Description | ----------- | -------- | ---- | ---- | data | true | Array<JSON>, JSON or string | If the exportType is 'json', data can be any JSON value. If the exportType is 'csv', 'tsv', or 'xls', data can only be an array of parsable JSON. If the exportType is 'txt', 'css', or 'html', the data must be a string type. | fileName | false | string | filename without extension, default to 'download' | extension | false | string | filename extension, by default it takes the exportType | fileNameFormatter | false | (name: string) => string | Filename formatter. By default, every run of whitespace is replaced with _. | fields | false | string[] or field name mapper type Record<string, string> | Select and optionally rename fields. Declaration order determines output column order; every selected column is retained even when all values are missing. Output field names must be unique. | exportType | false | Enum ExportType | 'txt'(default), 'css', 'html', 'json', 'csv', 'tsv', 'xls', 'xml' | processor | false | (content: string, type: ExportType, fileName: string) => any | default to a front-end downloader | withBOM | false | boolean | Add BOM(byte order mark) metadata to CSV or TSV files. BOM is expected by Excel when reading UTF-8 files. It defaults to false. | beforeTableEncode | false | (entries: TableEntries) => TableEntries | Alter columns before encoding CSV, TSV, or XLS data. Field names must be unique and every string-value column must retain the original row count. | delimiter | false | ',' \| ';' | Specify the CSV delimiter. It defaults to , and does not override TSV's fixed tab delimiter. | escapeFormulae | false | boolean | Prefix formula-like CSV or TSV cell values with a single quote to reduce spreadsheet formula injection risk. Field names are not modified. It defaults to false.

Tips

• TypeScript consumers can import ExportType, IOption, TableRow, TableEntry, and TableEntries directly from the package.

• CSV and TSV exports render rows directly by default to reduce intermediate memory. Supplying beforeTableEncode uses the column-oriented transform path because the callback operates on complete columns.

• You can reference these exported types through a mounted static field types, e.g.

exportFromJSON({ data: jsonData, fileName: 'data', exportType: exportFromJSON.types.csv })

• You can transform the data before exporting by beforeTableEncode, e.g.

exportFromJSON({
    data: jsonData,
    fileName: 'data',
    exportType: exportFromJSON.types.csv,
    beforeTableEncode: rows => rows.sort((p, c) => p.fieldName.localeCompare(c.fieldName)),
})

Contributing

See CONTRIBUTING.md for development, verification, and release instructions.