read-excel-file 5.3.3 → 5.4.0

package/CHANGELOG.md

@@ -1,3 +1,18 @@
+5.4.0 / 04.07.2022
+==================
+
+* [Fixed](https://gitlab.com/catamphetamine/read-excel-file/-/issues/54) non-ASCII character encoding by forcing Node.js version of the library to read zipped contents of an XLSX file in UTF-8 character encoding. I suppose it won't break the existing code.
+
+5.3.5 / 26.06.2022
+==================
+
+* Added `includeNullValues: true` option when parsing spreadsheet data using a `schema`. By default, it ignores all `null` values (ignores all empty cells).
+
+5.3.4 / 11.06.2022
+==================
+
+* Added an optional `reason?: string` property of a with-schema parsing error.
+
 5.3.3 / 24.05.2022
 ==================
 

package/README.md

@@ -93,7 +93,29 @@ onmessage = function(event) {
 
 ## JSON
 
-To convert table rows to JSON objects, pass a `schema` option to `readXlsxFile()`. It will return `{ rows, errors }` object instead of just `rows`.
+To read spreadsheet data and then convert it to an array of JSON objects, pass a `schema` option when calling `readXlsxFile()`. In that case, instead of returning an array of rows of cells, it will return an object of shape `{ rows, errors }` where `rows` is gonna be an array of JSON objects created from the spreadsheet data according to the `schema`, and `errors` is gonna be an array of errors encountered while converting spreadsheet data to JSON objects.
+
+Each property of a JSON object should be described by an "entry" in the `schema`. The key of the entry should be the column's title in the spreadsheet. The value of the entry should be an object with properties:
+
+* `property` — The name of the object's property.
+* `required` — (optional) Required properties can be marked as `required: true`.
+* `validate(value)` — (optional) Cell value validation function. Is only called on non-empty cells. If the cell value is invalid, it should throw an error with the error message set to the error code.
+* `type` — (optional) The type of the value. Defines how the cell value will be parsed. If no `type` is specified then the cell value is returned "as is": as a string, number, date or boolean. A `type` could be a:
+  * Built-in type:
+    * `String`
+    * `Number`
+    * `Boolean`
+    * `Date`
+  * "Utility" type exported from the library:
+    * `Integer`
+    * `Email`
+    * `URL`
+  * Custom type:
+    * A function that receives a cell value and returns a parsed value. If the value is invalid, it should throw an error with the error message set to the error code.
+
+Sidenote: When converting cell values to object properties, by default, it skips all `null` values (skips all empty cells). That's for simplicity. In some edge cases though, it may be required to keep all `null` values for all the empty cells. For example, that's the case when updating data in an SQL database from an XLSX spreadsheet using Sequelize ORM library that requires a property to explicitly be `null` in order to clear it during an `UPDATE` operation. To keep all `null` values, pass `includeNullValues: true` option when calling `readXlsxFile()`.
+
+#### An example of using a `schema`
 
 ```js
 // An example *.xlsx document:
@@ -157,7 +179,7 @@ const schema = {
 }
 
 readXlsxFile(file, { schema }).then(({ rows, errors }) => {
-  // `errors` list items have shape: `{ row, column, error, value }`.
+  // `errors` list items have shape: `{ row, column, error, reason?, value?, type? }`.
   errors.length === 0
 
   rows === [{
@@ -173,32 +195,36 @@ readXlsxFile(file, { schema }).then(({ rows, errors }) => {
 })
 ```
 
-If no `type` is specified then the cell value is returned "as is": as a string, number, date or boolean.
+<!-- If no `type` is specified then the cell value is returned "as is": as a string, number, date or boolean. -->
 
-There are also some additional exported `type`s available:
+<!-- There are also some additional exported `type`s available: -->
 
-* `Integer` for parsing integer `Number`s.
-* `URL` for parsing URLs.
-* `Email` for parsing email addresses.
+<details>
+<summary><strong>Custom <code>type</code></strong> example.</summary>
 
-A custom `type` can be defined as a simple function:
+#####
 
 ```js
-// This function will only be called for a non-empty cell.
-type: (value) => {
-  try {
-    return parseValue(value)
-  } catch (error) {
-    console.error(error)
-    throw new Error('invalid')
+{
+  'COLUMN_TITLE': {
+    // This function will only be called for a non-empty cell.
+    type: (value) => {
+      try {
+        return parseValue(value)
+      } catch (error) {
+        console.error(error)
+        throw new Error('invalid')
+      }
+    }
   }
 }
 ```
+</details>
 
-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. The `validate(value)` function is only called when `value` is not empty (not `null` / `undefined`).
+<!-- 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. The `validate(value)` function is only called when `value` is not empty (not `null` / `undefined`). -->
 
 <details>
-<summary>Fixing spreadsheet structure for <code>schema</code> parsing. For example, how to <strong>ignore empty rows</strong>.</summary>
+<summary>How to fix spreadsheet data before <code>schema</code> parsing. For example, <strong>how to ignore empty rows</strong>.</summary>
 
 #####
 
@@ -219,7 +245,7 @@ readXlsxFile(file, {
 
 <details>
 <summary>
-The <strong>schema conversion function</strong> can also be imported standalone, if anyone wants it.
+The <strong>function for converting data to JSON objects using a schema</strong> is exported from this library too, if anyone wants it.
 </summary>
 
 #####
@@ -234,34 +260,41 @@ const { rows, errors } = convertToJson(data, schema)
 </details>
 
 <details>
-<summary>A <strong>React component</strong> for displaying schema parsing/validation <strong>errors</strong>.</summary>
+<summary>A <strong>React component for displaying errors</strong> that occured during schema parsing/validation.</summary>
 
 #####
 
 ```js
 import { parseExcelDate } from 'read-excel-file'
 
-function ParseExcelError({ children: error }) {
-  // Get a human-readable value.
-  let value = error.value
-  if (error.type === Date) {
-    value = parseExcelDate(value).toString()
-  }
-  // Render error summary.
+function ParseExcelError({ children }) {
+  const { type, value, error, reason, row, column } = children
+
+  // Error summary.
   return (
     <div>
-      <code>"{error.error}"</code>
+      <code>"{error}"</code>
+      {reason && ' '}
+      {reason && <code>("{reason}")</code>}
       {' for value '}
-      <code>"{value}"</code>
+      <code>{stringifyValue(value)}</code>
       {' in column '}
-      <code>"{error.column}"</code>
-      {error.type && ' of type '}
-      {error.type && <code>"{error.type.name}"</code>}
+      <code>"{column}"</code>
+      {type && type.name && ' of type '}
+      {type && type.name && <code>"{type.name}"</code>}
       {' in row '}
-      <code>"{error.row}"</code>
+      <code>{row}</code>
     </div>
   )
 }
+
+function stringifyValue(value) {
+  // Wrap strings in quotes.
+  if (typeof value === 'string') {
+    return '"' + value + '"'
+  }
+  return String(value)
+}
 ```
 </details>