sheetjs/docs.sheetjs.com
1
Fork 4
Code Issues Pull Requests 1 Projects Releases Wiki Activity

error

Browse Source
This commit is contained in:
SheetJS 2023-09-21 03:45:39 -04:00
parent 8e39ab8f33
commit 871acac297
4 changed files with 230 additions and 25 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

19
docz/docs/02-getting-started/01-installation/02-frameworks.md
View File

@ -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

19
docz/docs/02-getting-started/01-installation/03-nodejs.md
View File

@ -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

210
docz/docs/07-csf/02-cell.md
View File

@ -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.

7
docz/docs/07-csf/07-features/06-nf.md
View File

@ -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.