json-as-xlsx 2.5.7 → 2.5.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +125 -19
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,13 +1,41 @@
1
1
  # json-as-xlsx
2
2
 
3
- This is a tool that helps to build an excel from a json and it depends only on `xlsx` library
3
+ [![npm version](https://img.shields.io/npm/v/json-as-xlsx.svg)](https://www.npmjs.com/package/json-as-xlsx)
4
+ [![npm downloads](https://img.shields.io/npm/dm/json-as-xlsx.svg)](https://www.npmjs.com/package/json-as-xlsx)
5
+ [![Test suites](https://github.com/LuisEnMarroquin/json-as-xlsx/actions/workflows/tests.yml/badge.svg)](https://github.com/LuisEnMarroquin/json-as-xlsx/actions/workflows/tests.yml)
6
+ [![license](https://img.shields.io/npm/l/json-as-xlsx.svg)](LICENSE)
4
7
 
5
- You can see a live example of it working on any of this sites (there are many just in case):
8
+ Build an Excel (`.xlsx`) file straight from JSON. It is a thin, typed wrapper
9
+ around the SheetJS-compatible [`@e965/xlsx`](https://www.npmjs.com/package/@e965/xlsx)
10
+ library, so it works both in the **browser** (downloads the file) and in
11
+ **Node.js** (can return a buffer when configured).
12
+
13
+ You can see a live demo on any of these sites (there are several, just in case):
6
14
 
7
15
  - [xlsx.pages.dev](https://xlsx.pages.dev)
8
16
  - [xlsx.marroquin.dev](https://xlsx.marroquin.dev)
9
17
  - [xlsx.luismarroquin.com](https://xlsx.luismarroquin.com)
10
18
 
19
+ ## Features
20
+
21
+ - 📊 Turn an array of JSON sheets into a multi-sheet workbook.
22
+ - 🧭 Read deeply nested values (`"more.phone"`) or compute them with a function.
23
+ - 🎨 Per-column number, date, currency and hyperlink formatting.
24
+ - 📐 Automatic column widths (tunable with `extraLength`).
25
+ - ↔️ Right-to-left (RTL) sheet support.
26
+ - 🌐 Works in the browser (file download) and in Node.js (file or buffer output).
27
+ - 🟦 Written in TypeScript — ships with type definitions.
28
+
29
+ ## Installation
30
+
31
+ ```shell
32
+ npm install json-as-xlsx
33
+ # or
34
+ yarn add json-as-xlsx
35
+ # or
36
+ pnpm add json-as-xlsx
37
+ ```
38
+
11
39
  ## Usage
12
40
 
13
41
  ```js
@@ -17,27 +45,27 @@ let xlsx = require("json-as-xlsx")
17
45
 
18
46
  let data = [
19
47
  {
20
- sheet: "Adults",
48
+ sheet: "Employees",
21
49
  columns: [
22
- { label: "User", value: "user" }, // Top level data
23
- { label: "Age", value: (row) => row.age + " years" }, // Custom format
24
- { label: "Phone", value: (row) => (row.more ? row.more.phone || "" : "") }, // Run functions
50
+ { label: "Name", value: "name" }, // Top level data
51
+ { label: "Salary", value: (row) => row.salary + " USD" }, // Custom format
52
+ { label: "Email", value: (row) => (row.contact ? row.contact.email || "" : "") }, // Run functions
25
53
  ],
26
54
  content: [
27
- { user: "Andrea", age: 20, more: { phone: "11111111" } },
28
- { user: "Luis", age: 21, more: { phone: "12345678" } },
55
+ { name: "Ada Lovelace", salary: 5000, contact: { email: "ada@example.com" } },
56
+ { name: "Grace Hopper", salary: 6200, contact: { email: "grace@example.com" } },
29
57
  ],
30
58
  },
31
59
  {
32
- sheet: "Children",
60
+ sheet: "Products",
33
61
  columns: [
34
- { label: "User", value: "user" }, // Top level data
35
- { label: "Age", value: "age", format: '# "years"' }, // Column format
36
- { label: "Phone", value: "more.phone", format: "(###) ###-####" }, // Deep props and column format
62
+ { label: "Product", value: "product" }, // Top level data
63
+ { label: "Price", value: "price", format: "$#,##0.00" }, // Column format
64
+ { label: "Stock", value: "inventory.stock", format: "#,##0" }, // Deep props and column format
37
65
  ],
38
66
  content: [
39
- { user: "Manuel", age: 16, more: { phone: 9999999900 } },
40
- { user: "Ana", age: 17, more: { phone: 8765432135 } },
67
+ { product: "Keyboard", price: 29.99, inventory: { stock: 1200 } },
68
+ { product: "Monitor", price: 199.5, inventory: { stock: 340 } },
41
69
  ],
42
70
  },
43
71
  ]
@@ -45,7 +73,7 @@ let data = [
45
73
  let settings = {
46
74
  fileName: "MySpreadsheet", // Name of the resulting spreadsheet
47
75
  extraLength: 3, // A bigger number means that columns will be wider
48
- writeMode: "writeFile", // The available parameters are 'WriteFile' and 'write'. This setting is optional. Useful in such cases https://docs.sheetjs.com/docs/solutions/output#example-remote-file
76
+ writeMode: "writeFile", // The available parameters are 'writeFile' and 'write'. This setting is optional. Useful in such cases https://docs.sheetjs.com/docs/solutions/output#example-remote-file
49
77
  writeOptions: {}, // Style options from https://docs.sheetjs.com/docs/api/write-options
50
78
  RTL: true, // Display the columns from right-to-left (the default value is false)
51
79
  }
@@ -53,16 +81,56 @@ let settings = {
53
81
  xlsx(data, settings) // Will download the excel file
54
82
  ```
55
83
 
56
- If you want to trigger something after the file is downloaded, you can use the `callback` parameter:
84
+ ### Settings
85
+
86
+ | Option | Type | Default | Description |
87
+ | -------------- | --------------------- | --------------- | --------------------------------------------------------------------------------------------- |
88
+ | `fileName` | `string` | `"Spreadsheet"` | Name of the resulting file (the `.xlsx` extension is added automatically). |
89
+ | `extraLength` | `number` | `1` | Extra characters added to every auto-calculated column width. |
90
+ | `writeMode` | `"writeFile"`/`"write"` | `"writeFile"` | `"writeFile"` downloads/writes the file; `"write"` returns the raw data (e.g. a Node buffer). |
91
+ | `writeOptions` | `object` | `{}` | Passed straight to SheetJS — see [write options](https://docs.sheetjs.com/docs/api/write-options). |
92
+ | `RTL` | `boolean` | `false` | Render every sheet right-to-left. |
93
+
94
+ ### Callback
95
+
96
+ If you want to inspect or post-process the workbook, pass a `callback` as the
97
+ third argument. It receives the generated [`WorkBook`](https://docs.sheetjs.com/docs/csf/book)
98
+ **right before** it is written, so you can read or mutate it:
57
99
 
58
100
  ```js
59
- let callback = function (sheet) {
60
- console.log("Download complete:", sheet)
101
+ let callback = function (workbook) {
102
+ console.log("Workbook ready:", workbook.SheetNames)
61
103
  }
62
104
 
63
105
  xlsx(data, settings, callback) // Will download the excel file
64
106
  ```
65
107
 
108
+ ### Use in Node.js (server-side)
109
+
110
+ Set `writeOptions.type` to `"buffer"` (or `writeMode: "write"`) to get the file
111
+ contents back instead of writing them to disk. This is handy for sending the
112
+ spreadsheet over HTTP:
113
+
114
+ ```js
115
+ import xlsx from "json-as-xlsx"
116
+
117
+ const settings = {
118
+ writeOptions: {
119
+ type: "buffer",
120
+ bookType: "xlsx",
121
+ },
122
+ }
123
+
124
+ app.get("/download", (_, res) => {
125
+ const buffer = xlsx(data, settings)
126
+ res.writeHead(200, {
127
+ "Content-Type": "application/octet-stream",
128
+ "Content-Disposition": "attachment; filename=MySheet.xlsx",
129
+ })
130
+ res.end(buffer)
131
+ })
132
+ ```
133
+
66
134
  ### Column formatting
67
135
 
68
136
  > **Note:** Cell formatting is type based, i.e. the format type and value type must match.
@@ -96,9 +164,47 @@ Examples
96
164
  "h:mm AM/PM" // 1:10 PM
97
165
  ```
98
166
 
167
+ #### Hyperlinks
168
+
169
+ Use the special `"hyperlink"` format to turn a column's text values into
170
+ clickable links:
171
+
172
+ ```js
173
+ columns: [{ label: "Website", value: "url", format: "hyperlink" }]
174
+ ```
175
+
176
+ ## TypeScript
177
+
178
+ The package is written in TypeScript and ships its own type definitions. The
179
+ public interfaces are exported for your convenience:
180
+
181
+ ```ts
182
+ import xlsx, { IJsonSheet, ISettings, IColumn, IContent } from "json-as-xlsx"
183
+
184
+ const data: IJsonSheet[] = [
185
+ /* ... */
186
+ ]
187
+ const settings: ISettings = {
188
+ /* ... */
189
+ }
190
+
191
+ xlsx(data, settings)
192
+ ```
193
+
99
194
  ## Examples
100
195
 
101
- This are files used for development, please change imports from `../../src/index` to `json-as-xlsx`
196
+ These are the files used during development — when copying them, change the
197
+ imports from `../../src/index` to `json-as-xlsx`.
102
198
 
103
199
  - [Express with TypeScript](https://github.com/LuisEnMarroquin/json-as-xlsx/blob/main/packages/demo-express)
104
200
  - [ReactJS with TypeScript](https://github.com/LuisEnMarroquin/json-as-xlsx/blob/main/packages/demo-reactjs)
201
+
202
+ ## Contributing
203
+
204
+ Contributions are welcome! Please read the [contributing guide](CONTRIBUTING.md)
205
+ and the [code of conduct](CODE_OF_CONDUCT.md) before opening a pull request. To
206
+ report a security issue, see the [security policy](SECURITY.md).
207
+
208
+ ## License
209
+
210
+ [MIT](LICENSE) © [LuisEnMarroquin](https://github.com/LuisEnMarroquin)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "json-as-xlsx",
3
- "version": "2.5.7",
3
+ "version": "2.5.9",
4
4
  "license": "MIT",
5
5
  "main": "dist/index.js",
6
6
  "types": "dist/index.d.ts",