read-excel-file 4.0.8 → 4.1.0

package/CHANGELOG.md

@@ -9,6 +9,17 @@
   * Removed undocumented `convertToJson()` export.
 -->
 
+4.1.0 / 09.11.2020
+==================
+
+* Renamed schema entry `parse()` function: now it's called `type`. This way, `type` could be both a built-in type and a custom type.
+
+* Changed the built-in `"Integer"`, `"URL"` and `"Email"` types: now they're exported functions again instead of strings. Strings still work.
+
+* Added `map` parameter: similar to `schema` but doesn't perform any parsing or validation. Can be used to map an Excel file to an array of objects that could be parsed/validated using [`yup`](https://github.com/jquense/yup).
+
+* `type` of a schema entry is no longer required: if no `type` is specified, then the cell value is returned "as is" (string, or number, or boolean, or `Date`).
+
 4.0.8 / 08.11.2020
 ==================
 

package/README.md

@@ -110,7 +110,7 @@ const schema = {
   'CONTACT': {
     prop: 'contact',
     required: true,
-    parse(value) {
+    type: (value) => {
       const number = parsePhoneNumber(value)
       if (!number) {
         throw new Error('invalid')
@@ -146,26 +146,69 @@ readXlsxFile(file, { schema }).then(({ rows, errors }) => {
 })
 ```
 
+If no `type` is specified then the cell value is returned "as is".
+
 There are also some additional exported `type`s:
 
-* `"Integer"` for parsing integer `Number`s.
-* `"URL"` for parsing URLs.
-* `"Email"` for parsing email addresses.
+* `Integer` for parsing integer `Number`s.
+* `URL` for parsing URLs.
+* `Email` for parsing email addresses.
+
+A schema entry for a column may also define an optional `validate(value)` function for validating the parsed value: in that case, it must `throw` an `Error` if the `value` is invalid.
+
+#### Map
+
+Sometimes, a developer might want to use some other (more advanced) solution for schema parsing and validation (like [`yup`](https://github.com/jquense/yup)). If a developer passes a `map` instead of a `schema` to `readXlsxFile()`, then it would just map each data row to a JSON object without doing any parsing or validation.
+
+```js
+// An example *.xlsx document:
+// -----------------------------------------------------------------------------------------
+// | START DATE | NUMBER OF STUDENTS | IS FREE | COURSE TITLE |    CONTACT     |  STATUS   |
+// -----------------------------------------------------------------------------------------
+// | 03/24/2018 |         123        |   true  |  Chemistry   | (123) 456-7890 | SCHEDULED |
+// -----------------------------------------------------------------------------------------
+
+const map = {
+  'START DATE': 'date',
+  'NUMBER OF STUDENTS': 'numberOfStudents',
+  'COURSE': {
+    'course': {
+      'IS FREE': 'isFree',
+      'COURSE TITLE': 'title'
+    }
+  },
+  'CONTACT': 'contact',
+  'STATUS': 'status'
+}
+
+readXlsxFile(file, { map }).then(({ rows }) => {
+  rows === [{
+    date: new Date(2018, 2, 24),
+    numberOfStudents: 123,
+    course: {
+      isFree: true,
+      title: 'Chemistry'
+    },
+    contact: '(123) 456-7890',
+    status: 'SCHEDULED'
+  }]
+})
+```
 
-A schema entry for a column can also have a `validate(value)` function for validating the parsed value. It must `throw` an `Error` if the value is invalid.
+#### Displaying schema errors
 
-A React component for displaying error info could look like this:
+A React component for displaying schema parsing/validation errors could look like this:
 
 ```js
 import { parseExcelDate } from 'read-excel-file'
 
 function ParseExcelError({ children: error }) {
-  // Human-readable value.
+  // Get a human-readable value.
   let value = error.value
   if (error.type === Date) {
     value = parseExcelDate(value).toString()
   }
-  // Error summary.
+  // Render error summary.
   return (
     <div>
       <code>"{error.error}"</code>
@@ -182,6 +225,8 @@ function ParseExcelError({ children: error }) {
 }
 ```
 
+#### Transforming rows/columns before schema is applied
+
 When using a `schema` there's also an optional `transformData(data)` parameter which can be used for the cases when the spreadsheet rows/columns aren't in the correct format. For example, the heading row may be missing, or there may be some purely presentational or empty rows. Example:
 
 ```js