diff --git a/docz/docs/02-getting-started/01-installation/02-frameworks.md b/docz/docs/02-getting-started/01-installation/02-frameworks.md index 7459135..ec6c3d1 100644 --- a/docz/docs/02-getting-started/01-installation/02-frameworks.md +++ b/docz/docs/02-getting-started/01-installation/02-frameworks.md @@ -57,6 +57,25 @@ new versions are released! ::: +:::caution Snyk Bugs + +Snyk security tooling may report errors involving "Prototype Pollution": + +``` +Prototype Pollution [Medium Severity][https://security.snyk.io/vuln/SNYK-JS-XLSX-5457926] +``` + +As noted in the [Snyk report](https://security.snyk.io/vuln/SNYK-JS-XLSX-5457926): + +> The issue is resolved in version 0.19.3 + +**Snyk is falsely reporting vulnerabilities. It is a bug in the Snyk tooling.** + +Until Snyk fixes the bugs, the official recommendation is to +[suppress the warning](https://snyk.io/blog/ignoring-vulnerabilities-with-snyk/). + +::: + ### Legacy Endpoints :::warning pass diff --git a/docz/docs/02-getting-started/01-installation/03-nodejs.md b/docz/docs/02-getting-started/01-installation/03-nodejs.md index af34f1a..ab1cc8d 100644 --- a/docz/docs/02-getting-started/01-installation/03-nodejs.md +++ b/docz/docs/02-getting-started/01-installation/03-nodejs.md @@ -47,6 +47,25 @@ new versions are released! ::: +:::caution Snyk Bugs + +Snyk security tooling may report errors involving "Prototype Pollution": + +``` +Prototype Pollution [Medium Severity][https://security.snyk.io/vuln/SNYK-JS-XLSX-5457926] +``` + +As noted in the [Snyk report](https://security.snyk.io/vuln/SNYK-JS-XLSX-5457926): + +> The issue is resolved in version 0.19.3 + +**Snyk is falsely reporting vulnerabilities. It is a bug in the Snyk tooling.** + +Until Snyk fixes the bugs, the official recommendation is to +[suppress the warning](https://snyk.io/blog/ignoring-vulnerabilities-with-snyk/). + +::: + ### Legacy Endpoints :::warning pass diff --git a/docz/docs/07-csf/02-cell.md b/docz/docs/07-csf/02-cell.md index 08f61d9..8289d06 100644 --- a/docz/docs/07-csf/02-cell.md +++ b/docz/docs/07-csf/02-cell.md @@ -7,9 +7,9 @@ Cell objects are plain JS objects with keys and values following the convention: | Key | Description | | --- | ---------------------------------------------------------------------- | -| | **Core Cell Properties** ([More Info](#data-types)) | -| `t` | type: `b` Boolean, `e` Error, `n` Number, `d` Date, `s` Text, `z` Stub | -| `v` | raw value (number, string, Date object, boolean) | +| | **Core Cell Properties** | +| `t` | cell type ([more info](#cell-types)) | +| `v` | underlying value ([more info](#underlying-values)) | | | **Number Formats** ([More Info](/docs/csf/features/nf)) | | `z` | number format string associated with the cell (if requested) | | `w` | formatted text (if applicable) | @@ -24,21 +24,50 @@ Cell objects are plain JS objects with keys and values following the convention: | `h` | HTML rendering of the rich text (if applicable) | | `s` | the style/theme of the cell (if applicable) | -Cell objects are expected to have a type (`t` property). +Cell objects are expected to have a type (`t` property). Cells with values are +expected to store the values in the `v` property. The cell type influences the +interpretation of cell values. -Built-in utilities that use formatted text (such as the CSV exporter) will use -the `w` text if available. When programmatically changing values, the `w` text -should be deleted before attempting to export. Utilities will regenerate the `w` -text from the number format (`cell.z`) and the raw value if possible. +## Content and Presentation -The actual array formula is stored in the `f` field of the first cell in the -array range. Other cells in the range will omit the `f` field. +Spreadsheets typically separate "content" from "presentation". A cell with a +value of `$3.50` is typically stored as a numeric cell with an underlying value +of `3.5` and a number format such as `$0.00` -### Data Types +The cell type is stored in the `t` property of the cell. -The raw value is stored in the `v` value property, interpreted based on the `t` -type property. This separation allows for representation of numbers as well as -numeric text. There are 6 valid cell types: +The underlying value, representing a JavaScript equivalent of the spreadsheet +"content", is stored in the `v` property of the cell. + +The number format string is stored in the `z` property of the cell. + +The SheetJS number formatting library will generate formatted text. It will be +stored in the `w` property of the cell. + +For this example, the SheetJS cell representation will be + +```js +var cell = { + t: "n", // numeric cell + v: 3.5, // underlying value 3.5 + z: "$0.00", // number format $0.00 + w: "$3.50" // formatted text +}; +``` + +Parsers for most common formats will typically generate formatted text at parse +time and skip the original number formats. There are options to preserve the +number formats and skip formatted text generation. + +:::info pass + +["Number Formats"](/docs/csf/features/nf) discusses formatting in more detail. + +::: + +## Cell Types + +There are 6 SheetJS cell types: | Type | Description | | :--: | :-------------------------------------------------------------------- | @@ -75,15 +104,146 @@ the core library data processing utility functions. By default these cells are not generated; the parser `sheetStubs` option must be set to `true`. Type `e` is the Error type. The `v` field holds numeric error codes, while `w` -holds the error message. Acceptable values are listed below: +holds the error message. Valid values are listed [in the "Error" table](#error). -| Value | Error Meaning | -| -----: | :-------------- | -| `0x00` | `#NULL!` | -| `0x07` | `#DIV/0!` | -| `0x0F` | `#VALUE!` | -| `0x17` | `#REF!` | -| `0x1D` | `#NAME?` | -| `0x24` | `#NUM!` | -| `0x2A` | `#N/A` | -| `0x2B` | `#GETTING_DATA` | +## Underlying Values + +Spreadsheet conventions do not always line up with JavaScript conventions. The +library attempts to translate between Excel values and JavaScript primitives. + +### Excel Values + +Each value in Excel has a type which can be displayed with the `TYPE` function. +There are four scalar types: + +| Description | Example | Formula Expression | Result | +|:-----------------------|:----------|:--------------------|-------:| +| Number / Date / Blank | `54337` | `=TYPE(54337)` | `1` | +| Text | `SheetJS` | `=TYPE("SheetJS")` | `2` | +| Boolean (Logical) | `TRUE` | `=TYPE(TRUE)` | `4` | +| Error | `#VALUE!` | `=TYPE(#VALUE!)` | `16` | + +:::info pass + +Lotus 1-2-3, Excel, and other spreadsheet software typically store dates as +numbers and use the number format to determine if values represent dates. +See ["Dates and Times"](/docs/csf/features/dates) for more info. + +::: + +#### Number + +Each valid Excel number can be represented as a JavaScript number primitive.[^1] + +SheetJS libraries normally generate JavaScript numbers. For cells with date-like +number formats[^2], there are options to generate JavaScript `Date` objects. + +:::info pass + +Excel displays exponential numbers with an uppercase `E` while JavaScript +numbers are traditionally displayed with a lowercase `e`. Even though the +underlying values may appear different, they are functionally identical. + +::: + +#### Text + +Each valid Excel string can be represented as a JavaScript string primitive. +SheetJS libraries generate JavaScript strings. + +#### Boolean + +There are two Boolean values: "true" and "false". + +Excel renders the Boolean values in uppercase: `TRUE` and `FALSE` + +JavaScript renders Boolean literals in lowercase: `true` and `false` + +SheetJS libraries generate the JavaScript form. The formatted text will be the +uppercase `TRUE` or `FALSE`, matching Excel rendering. + +#### Error + +The underlying value for an Excel error is a number. The supported error types +and numeric values are listed below: + +| Excel Error | Value | +| :-------------- | -----: | +| `#NULL!` | `0x00` | +| `#DIV/0!` | `0x07` | +| `#VALUE!` | `0x0F` | +| `#REF!` | `0x17` | +| `#NAME?` | `0x1D` | +| `#NUM!` | `0x24` | +| `#N/A` | `0x2A` | +| `#GETTING_DATA` | `0x2B` | + +SheetJS parsers mark the cell type of error cells and store the listed numeric +value. The formatted text will be the error string shown in Excel. + +:::note pass + +`#SPILL!`, `#CONNECT!`, and `#BLOCKED!` errors are saved to files as `#VALUE!`. + +::: + +### JavaScript Values + +Each primitive value in JavaScript has a type which can be displayed with the +`typeof` operator. There are 5 types in the ECMAScript 5 dialect of JavaScript: + +| Type | Example | `typeof` | +|:----------|:------------|:--------------| +| Undefined | `undefined` | `"undefined"` | +| Null | `null` | `"null"` | +| Boolean | `true` | `"boolean"` | +| String | `"SheetJS"` | `"string"` | +| Number | `5433795` | `"number"` | + +#### Null and Undefined + +`undefined` in JavaScript is spiritually equivalent to a blank cell value in +Excel. By default, SheetJS methods that generate worksheets skip `undefined`. + +`null` in JavaScript typically is used to represent no data. The `#NULL!` error +in Excel is intended to break formula expressions that reference the cells[^3]. +By default, SheetJS methods that generate worksheets skip `null`. Some methods +include options to generate `#NULL!` error cells. + +#### Boolean + +There are two Boolean values: "true" and "false". + +SheetJS libraries map JavaScript `true` / `false` literals to Excel `TRUE` / +`FALSE` Boolean values. + +#### String + +The underlying value of a JavaScript string is always the original string. + +SheetJS export methods will shorten or re-encode strings as necessary to export +valid strings for the requested file formats. + +#### Number + +The underlying value of a JavaScript number is always the original number. + +SheetJS export methods will translate supported numbers to numeric cells. `NaN` +values will be translated to Excel `#NUM!` errors. Infinities and subnormal +values are translated to `#DIV/0!`. + +#### Dates + +:::note pass + +JavaScript `Date` objects are Objects. They can be distinguished from other +Objects with the `instanceof` operator. + +::: + +SheetJS date cells can hold Date objects. When exporting workbooks to formats +that do not have native Date types, the values will be translated to date codes. + +[^1]: Each valid Excel number can be represented as an IEEE754 double. Excel does not support denormalized numbers, the `NaN` family, `Infinity`, or `-Infinity`. See ["Floating-point arithmetic may give inaccurate results in Excel"](https://learn.microsoft.com/en-us/office/troubleshoot/excel/floating-point-arithmetic-inaccurate-result) in the Excel documentation for more information. +[^2]: The table in ["Dates and Times" section of "Number Formats"](/docs/csf/features/nf#dates-and-times) lists the tokens that SheetJS uses to determine if a cell value should be treated as a Date. +[^3]: [`NULL` function](https://support.microsoft.com/en-us/office/null-function-c7fb4579-e8aa-4883-a8e3-2b8055100e39) in the Excel documentation explains the intended use case. \ No newline at end of file diff --git a/docz/docs/07-csf/07-features/06-nf.md b/docz/docs/07-csf/07-features/06-nf.md index 220d447..4561da7 100644 --- a/docz/docs/07-csf/07-features/06-nf.md +++ b/docz/docs/07-csf/07-features/06-nf.md @@ -362,4 +362,11 @@ desired format and testing with [the Number Format Strings demo](#number-format- [**This feature is discussed in the HTML utilities section**](/docs/api/utilities/html#value-override) +### Plaintext Export + +Built-in utilities that use formatted text (such as the CSV exporter) will use +the `w` text if available. When programmatically changing values, the `w` text +should be deleted before attempting to export. Utilities will regenerate the `w` +text from the number format (`cell.z`) and the raw value if possible. + [^1]: On 2023 September 14, [the "Review guidelines for customizing a number format" page](https://support.microsoft.com/en-us/office/review-guidelines-for-customizing-a-number-format-c0a1d1fa-d3f4-4018-96b7-9c9354dd99f5) in the Excel documentation covered custom number format minutiae. \ No newline at end of file