From 3d661faddb57a945aecde009e85c4c03f81c69d0 Mon Sep 17 00:00:00 2001 From: SheetJS Date: Mon, 23 Sep 2024 11:39:01 -0400 Subject: [PATCH] vendoring --- .../01-installation/01-standalone.mdx | 4 +- .../01-installation/02-frameworks.md | 26 +++++- .../01-installation/03-nodejs.md | 91 ++++++++++++++++++- .../01-installation/07-bun.md | 3 +- docz/docs/03-demos/12-static/12-astro.md | 2 +- docz/docs/07-csf/07-features/12-props.md | 2 +- docz/docs/09-miscellany/05-contributing.md | 56 +++++++++--- 7 files changed, 157 insertions(+), 27 deletions(-) diff --git a/docz/docs/02-getting-started/01-installation/01-standalone.mdx b/docz/docs/02-getting-started/01-installation/01-standalone.mdx index f9e6697..2720673 100644 --- a/docz/docs/02-getting-started/01-installation/01-standalone.mdx +++ b/docz/docs/02-getting-started/01-installation/01-standalone.mdx @@ -121,8 +121,8 @@ importScripts("https://cdn.sheetjs.com/xlsx-${current}/package/dist/xlsx.full.mi :::danger VSCode Telemetry and Data Exfiltration -The official Microsoft builds of Visual Studio Code embed telemetry and send -information to external servers. +The official Microsoft builds of Visual Studio Code ("VSCode") embed telemetry +and send information to external servers. **[VSCodium](https://vscodium.com/) is a telemetry-free fork of VSCode.** 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 7e4b352..f4ac8fe 100644 --- a/docz/docs/02-getting-started/01-installation/02-frameworks.md +++ b/docz/docs/02-getting-started/01-installation/02-frameworks.md @@ -174,10 +174,30 @@ yarn remove xlsx`}

  1. Download the tarball (xlsx-{current}.tgz) for the desired version. The current version is available at {"https://cdn.sheetjs.com/xlsx-" + current + "/xlsx-" + current + ".tgz"}

-2) Create a `vendor` subfolder at the root of your project and move the tarball - to that folder. Add it to your project repository. +{`\ +curl -o https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz`} + -3) Install the tarball using a package manager: +2) Create a `vendor` subfolder at the root of your project: + +```bash +mkdir -p vendor +``` + +3) Move the tarball from step (1) to the `vendor` folder: + +{`\ +mv xlsx-${current}.tgz vendor`} + + +4) If the project is managed with a version control system, add the tarball to +the source repository. The Git VCS supports the `add` subcommand: + +{`\ +git add vendor/xlsx-${current}.tgz`} + + +5) Install the tarball using a package manager: 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 422f379..d029f5f 100644 --- a/docz/docs/02-getting-started/01-installation/03-nodejs.md +++ b/docz/docs/02-getting-started/01-installation/03-nodejs.md @@ -161,12 +161,33 @@ yarn remove xlsx`} -

  1. Download the tarball (xlsx-{current}.tgz) for the desired version. The current version is available at {"https://cdn.sheetjs.com/xlsx-" + current + "/xlsx-" + current + ".tgz"}

+

  1. Download the tarball (xlsx-{current}.tgz) for the desired version. The current + version is available at {"https://cdn.sheetjs.com/xlsx-" + current + "/xlsx-" + current + ".tgz"}

-2) Create a `vendor` subfolder at the root of your project and move the tarball - to that folder. Add it to your project repository. +{`\ +curl -o https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz`} + -3) Install the tarball using a package manager: +2) Create a `vendor` subfolder at the root of your project: + +```bash +mkdir -p vendor +``` + +3) Move the tarball from step (1) to the `vendor` folder: + +{`\ +mv xlsx-${current}.tgz vendor`} + + +4) If the project is managed with a version control system, add the tarball to +the source repository. The Git VCS supports the `add` subcommand: + +{`\ +git add vendor/xlsx-${current}.tgz`} + + +5) Install the tarball using a package manager: @@ -230,6 +251,66 @@ The package also ships with `xlsx.mjs`, a script compatible with the ECMAScript module system. When using the ESM build in NodeJS, some dependencies must be loaded manually. +:::danger ECMAScript Module Limitations + +The original ECMAScript module specification only supported top-level imports: + +```js +import { Readable } from 'stream'; +``` + +If a module is unavailable, there is no way for scripts to gracefully fail or +ignore the error. This presents an insurmountable challenge for libraries. + +To contrast, the SheetJS CommonJS modules gracefully handle missing dependencies +since `require` failures are errors that the library can catch and handle. + +--- + +Patches to the specification added two different solutions to the problem: + +- "dynamic imports" will throw errors that can be handled by libraries. Dynamic +imports will taint APIs that do not use Promise-based methods. + +```js +/* Readable will be undefined if stream cannot be imported */ +const Readable = await (async() => { + try { + return (await import("stream"))?.Readable; + } catch(e) { /* silently ignore error */ } +})(); +``` + +- "import maps" control module resolution, allowing library users to manually +shunt unsupported modules. + +**These patches were released after browsers adopted ESM!** A number of browsers +and other platforms support top-level imports but do not support the patches. + +--- + +For the ESM build, there were four unpalatable options: + +A) Generate a module script for browsers, a module script for ViteJS, a module +script for [Deno](/docs/getting-started/installation/deno), and a module script +for NodeJS and [BunJS](/docs/getting-started/installation/bun). + +B) Remove all optional features, including support for non-English legacy files. + +C) Add all optional features, effectively making the features mandatory. + +D) Introduce special methods for optional dependency injection. + +The SheetJS team chose option (D). NodeJS native modules are still automatically +loaded in the CommonJS build, but NodeJS ESM scripts must now load and pass the +dependencies to the library using special methods. + +--- + +**It is strongly recommended to use CommonJS in NodeJS scripts!** + +::: + #### Filesystem Operations The `set_fs` method accepts a `fs` instance for reading and writing files using @@ -285,6 +366,8 @@ import * as fs from 'fs'; // this import will fail set_fs(fs); ``` +**This is a design flaw in NextJS!** + ::: For server-side file processing, `fs` should be loaded with a dynamic import diff --git a/docz/docs/02-getting-started/01-installation/07-bun.md b/docz/docs/02-getting-started/01-installation/07-bun.md index 3351fba..b8b6065 100644 --- a/docz/docs/02-getting-started/01-installation/07-bun.md +++ b/docz/docs/02-getting-started/01-installation/07-bun.md @@ -122,6 +122,7 @@ This demo was last tested in the following deployments: | Architecture | BunJS | Date | |:-------------|:---------|:-----------| | `darwin-x64` | `1.1.4` | 2024-04-19 | +| `darwin-arm` | `1.1.10` | 2024-09-22 | | `win10-x64` | `1.1.4` | 2024-04-19 | | `win11-x64` | `1.1.22` | 2024-08-11 | | `linux-x64` | `1.1.4` | 2024-04-25 | @@ -136,7 +137,7 @@ cd sheetjs-bun-dle echo "{}" > package.json ``` -:::caution pass +:::caution PowerShell Encoding Errors The PowerShell file redirect will use the `UTF-16 LE` encoding. Bun does not support the encoding and will fail to install the package: diff --git a/docz/docs/03-demos/12-static/12-astro.md b/docz/docs/03-demos/12-static/12-astro.md index e2de28e..92613f8 100644 --- a/docz/docs/03-demos/12-static/12-astro.md +++ b/docz/docs/03-demos/12-static/12-astro.md @@ -110,7 +110,7 @@ export default defineConfig({ #### Types -For VSCode and VSCodium integration, types can be specified in `src/env.d.ts`. +For VSCodium integration, types can be specified in `src/env.d.ts`. This data loader returns Base64 strings: diff --git a/docz/docs/07-csf/07-features/12-props.md b/docz/docs/07-csf/07-features/12-props.md index 8a12507..699f69e 100644 --- a/docz/docs/07-csf/07-features/12-props.md +++ b/docz/docs/07-csf/07-features/12-props.md @@ -130,7 +130,7 @@ wb.Custprops["Custom Quip"] = "Get Sheet Done"; ## Export Override -The SheetJS `write` and `writeFile` methods[^2] accept options. The `Props` +The SheetJS `write` and `writeFile` methods[^1] accept options. The `Props` option instructs the writer to override properties from the workbook object. In the following example, the workbook object sets the "Title" and "Keywords" diff --git a/docz/docs/09-miscellany/05-contributing.md b/docz/docs/09-miscellany/05-contributing.md index f75203e..b3b3c59 100644 --- a/docz/docs/09-miscellany/05-contributing.md +++ b/docz/docs/09-miscellany/05-contributing.md @@ -529,7 +529,7 @@ Date: Fri Jul 12 11:47:14 2024 -0400 git checkout 8a7cfd47bde8258c0d91df6a737bf0136699cdf8 ``` -7) Run the full build sequence +7) Run the full build sequence: ```bash make clean; make @@ -538,9 +538,10 @@ make make dist ``` -8) To verify that the files are intact, use `md5sum` (`md5` on MacOS). +8) Verify the scripts by computing the MD5 checksum. -The local checksum for the browser script can be computed with: +The checksum for the generated `xlsx.full.min.js` script can be computed using +the `md5` command on macOS or the `md5sum` command on WSL and Linux. @@ -567,13 +568,25 @@ md5sum dist/xlsx.full.min.js -The checksum for the CDN version can be computed with: +The checksum for the equivalent script on the SheetJS CDN can be computed with: ```bash curl -L https://cdn.sheetjs.com/xlsx-0.20.3/package/dist/xlsx.full.min.js | md5sum - +``` + +The following output was captured in `win11-arm` for SheetJS version `0.20.3`: + +> +```bash +$ md5sum dist/xlsx.full.min.js +# highlight-next-line +6b3130af1ceadf07caa0ec08af7addff dist/xlsx.full.min.js +$ curl -L https://cdn.sheetjs.com/xlsx-0.20.3/package/dist/xlsx.full.min.js | md5sum - +# highlight-next-line +6b3130af1ceadf07caa0ec08af7addff - ``` @@ -583,17 +596,7 @@ curl -L https://cdn.sheetjs.com/xlsx-0.20.3/package/dist/xlsx.full.min.js | md5s curl -k -L https://cdn.sheetjs.com/xlsx-0.20.3/package/dist/xlsx.full.min.js | md5 ``` - - - -```bash -curl -L https://cdn.sheetjs.com/xlsx-0.20.3/package/dist/xlsx.full.min.js | md5sum - -``` - - - - -When the demo was last tested on macOS, against version `0.20.3`: +The following output was captured in `darwin-arm` for SheetJS version `0.20.3`: > ```bash @@ -605,6 +608,29 @@ $ curl -k -L https://cdn.sheetjs.com/xlsx-0.20.3/package/dist/xlsx.full.min.js | 6b3130af1ceadf07caa0ec08af7addff ``` + + + +```bash +curl -L https://cdn.sheetjs.com/xlsx-0.20.3/package/dist/xlsx.full.min.js | md5sum - +``` + + +The following output was captured in `linux-arm` for SheetJS version `0.20.3`: + +> +```bash +$ md5sum dist/xlsx.full.min.js +# highlight-next-line +6b3130af1ceadf07caa0ec08af7addff dist/xlsx.full.min.js +$ curl -L https://cdn.sheetjs.com/xlsx-0.20.3/package/dist/xlsx.full.min.js | md5sum - +# highlight-next-line +6b3130af1ceadf07caa0ec08af7addff - +``` + + + + The two hashes should match. 9) Return to the `HEAD` commit: