read-excel-file 8.0.1 → 8.0.2

package/README.md

@@ -1,6 +1,6 @@
 # `read-excel-file`
 
-Read `.xlsx` files in a browser or in Node.js.
+Read `.xlsx` files in a browser or Node.js.
 
 It also supports parsing spreadsheet rows into JSON objects using a [schema](#schema).
 
@@ -59,33 +59,42 @@ Also check out [`write-excel-file`](https://www.npmjs.com/package/write-excel-fi
   * `ParsedObjectsResult` → `ParseDataResult`
 </details>
 
-## Performance
-
-Here're the results of reading [sample `.xlsx` files](https://examplefile.com/document/xlsx) of different size:
-
-|File Size| Browser |  Node.js  |
-|---------|---------|-----------|
-|   1 MB  | 0.2 sec.| 0.25 sec. |
-|  10 MB  | 1.5 sec.|    2 sec. |
-|  50 MB  | 8.5 sec.|   14 sec. |
-
 ## Install
 
 ```js
 npm install read-excel-file --save
 ```
 
-Alternatively, one could include it on a web page [directly](#cdn) via a `<script/>` tag.
+Alternatively, it could be included on a web page [directly](#cdn) via a `<script/>` tag.
 
 ## Use
 
-The default exported function — let's call it `readExcelFile()` — reads an `.xslx` file and returns a `Promise` that resolves to an array of "sheets". At least one "sheet" always exists. Each "sheet" is an object with properties:
-* `sheet` — Sheet name.
-  * Example: `"Sheet1"`
-* `data` — Sheet data. An array of rows. Each row is an array of values — `string`, `number`, `boolean` or `Date`.
-  * Example: `[ ['John Smith',35,true,...], ['Kate Brown',28,false,...], ... ]`
+If your `.xlsx` file only has a single "sheet", or if you only care for a single "sheet", or if you don't know or care what a "sheet" is, use `readSheet()` function.
+
+```js
+import { readSheet } from 'read-excel-file/node'
+
+await readSheet(file)
+
+// Returns
+[
+  ['John Smith',35,true,...],
+  ['Kate Brown',28,false,...],
+  ...
+]
+```
+
+It resolves to an array of rows. Each row is an array of values — `string`, `number`, `boolean` or `Date`.
+
+<!-- It's same as the default exported function shown above with the only difference that it returns just `data` instead of `[{ name: 'Sheet1', data }]`, so it's just a bit simpler to use. It has an optional second argument — `sheet` — which could be a sheet number (starting from `1`) or a sheet name. By default, it reads the first sheet. -->
+
+And it has an optional second argument — `sheet` — which could be a sheet number (starting from `1`) or a sheet name. By default, it reads the first sheet.
+
+But if you need to read all "sheets" for some reason, use the default exported function which resolves to an array of "sheets".
 
 ```js
+import readExcelFile from 'read-excel-file/node'
+
 await readExcelFile(file)
 
 // Returns
@@ -102,20 +111,13 @@ await readExcelFile(file)
 }]
 ```
 
-In simple cases when there're no multiple sheets in an `.xlsx` file, or if only one sheet in an `.xlsx` file is of any interest, use a named exported function `readSheet()`. It's same as the default exported function shown above with the only difference that it returns just `data` instead of `[{ name: 'Sheet1', data }]`, so it's just a bit simpler to use. It has an optional second argument — `sheet` — which could be a sheet number (starting from `1`) or a sheet name. By default, it reads the first sheet.
-
-```js
-await readSheet(file)
-
-// Returns
-[
-  ['John Smith',35,true,...],
-  ['Kate Brown',28,false,...],
-  ...
-]
-```
+At least one "sheet" always exists. Each "sheet" is an object with properties:
+* `sheet` — Sheet name.
+  * Example: `"Sheet1"`
+* `data` — Sheet data. An array of rows. Each row is an array of values — `string`, `number`, `boolean` or `Date`.
+  * Example: `[ ['John Smith',35,true,...], ['Kate Brown',28,false,...], ... ]`
 
-As for where to `import` those two functions from, the package provides a separate `import` path for each different environment, as described below.
+This package provides a separate `import` path for each different environment, as described below.
 
 ### Browser
 
@@ -259,6 +261,16 @@ readExcelFile(file, {
 
 This package doesn't support reading cells that use formulas to calculate the value: `SUM`, `AVERAGE`, etc.
 
+## Performance
+
+Here're the results of reading [sample `.xlsx` files](https://examplefile.com/document/xlsx) of different size:
+
+|File Size| Browser |  Node.js  |
+|---------|---------|-----------|
+|   1 MB  | 0.2 sec.| 0.25 sec. |
+|  10 MB  | 1.5 sec.|    2 sec. |
+|  50 MB  | 8.5 sec.|   14 sec. |
+
 ## Schema
 
 Oftentimes, the task is not just to read the "raw" spreadsheet data but also to convert each row of that data to a JSON object having a certain structure. Because it's such a common task, this package exports a named function `parseData(data, schema)` which does exactly that. It parses sheet data into an array of JSON objects according to a pre-defined `schema` which describes how should a row of data be converted to a JSON object.
@@ -372,8 +384,8 @@ const schema = {
   contact: {
     column: 'CONTACT',
     required: true,
-    // A custom `type` transformation function can be specified.
-    // It will transform the cell value if it's not empty.
+    // A custom `type` parsing function can be specified.
+    // It will parse the cell value if it's not empty.
     type: (value) => {
       const number = parsePhoneNumber(value)
       if (!number) {
@@ -395,12 +407,14 @@ const schema = {
 
 const data = await readSheet(file)
 
-const { rows, errors } = parseData(data, schema)
+const results = parseData(data, schema)
 
-// `errors` list items have shape: `{ row, column, error, reason?, value?, type? }`.
-errors.length === 0
+results.length === 1
 
-rows === [{
+// `errors` items have shape: `{ column, error, reason?, value?, type? }`.
+results[0].errors === undefined
+
+results[0].object === {
   date: new Date(2018, 3 - 1, 24),
   numberOfStudents: 10,
   course: {
@@ -409,7 +423,7 @@ rows === [{
   },
   contact: '+11234567890',
   status: 'SCHEDULED'
-}]
+}
 ```
 
 <!-- #### Schema: Tips and Features -->

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "read-excel-file",
-  "version": "8.0.1",
+  "version": "8.0.2",
   "description": "Read `.xlsx` files in a web browser or in Node.js",
   "type": "module",
   "exports": {