[DO NOT MERGE!] Fix language files for Node+ESM

sequba commented 4 months ago

Context

changed babel configuration to produce the ESM build with .mjs extensions and adjust the import and export statements in the output (custom babel plugin)
added exports property to package.json that lists all valid ways of importing HyperFormula

Breaking change

This will be a breaking change for devs that use Webpack 3 or Parcel. They need to adjust their config and/or update the bundler.

TODO

[ ] QA approval by @magierg
[ ] add migration guide
[ ] validate by publint
[ ] CR by @evanSe

How did you test your changes?

Tested importing HF in scenarios:

[x] ESM in node project
[x] ESM in react project (with Typescript)
[x] ESM in webpack v4 project -> Works but only with legacy paths. Webpack 4 does not support "exports". And requires special configuration for handling mjs files
[x] ESM in webpack v5 project
[x] ESM in webpack v5 project with Typescript -> Works, but requires special configuration ("moduleResolution": "node16" in tsconfig)
[x] ESM in parcel v2.11 project -> parcel does not support "exports" by default, since v2.9 it can be configured to support it
[x] CJS in node project
[x] CJS in parcel v2.11 project
[x] UMD in browser

Demo projects are available in the hyperformula-demos repo.

Tested by @budnix:

Vite ^5.1.4 - OK Parcel2 ^2.0.0 - Does not support "exports" so the language file has to be imported with /es/ or /commonjs/ prefixes; Webpack5 ^5.8.0 - OK Webpack4 ^4.42.0 - I getting an error. Seems the webpack has the problem with importing values from "chevrotain".

Types of changes

[x] Breaking change (a fix or a feature because of which an existing functionality doesn't work as expected anymore)
[x] New feature or improvement (a non-breaking change that adds functionality)
[x] Bug fix (a non-breaking change that fixes an issue)
[ ] Additional language file, or a change to an existing language file (translations)
[ ] Change to the documentation

Related issues:

Fixes #1344

Checklist:

[x] I have reviewed the guidelines about Contributing to HyperFormula and I confirm that my code follows the code style of this project.
[ ] I have signed the Contributor License Agreement.
[x] My change is compliant with the OpenDocument standard.
[x] My change is compatible with Microsoft Excel.
[x] My change is compatible with Google Sheets.
[x] I described my changes in the CHANGELOG.md file.
[ ] My changes require a documentation update.
[x] My changes require a migration guide.

github-actions[bot] commented 4 months ago

Performance comparison of head (0cd4e056a5601c8aaae0c07a648de13332068897) vs base (e32e132ebcb2d51d5f5d9b4bfb1ae3d4c71a2aab)

                                     testName |   base |   head | change
------------------------------------------------------------------------
                                      Sheet A | 529.16 | 530.87 | +0.32%
                                      Sheet B | 171.97 |  170.4 | -0.91%
                                      Sheet T | 151.62 | 149.56 | -1.36%
                                Column ranges | 548.74 |  546.6 | -0.39%
Sheet A:  change value, add/remove row/column |  14.76 |  13.82 | -6.37%
 Sheet B: change value, add/remove row/column | 130.26 | 133.98 | +2.86%
                   Column ranges - add column | 157.07 | 153.52 | -2.26%
                Column ranges - without batch | 465.62 | 455.73 | -2.12%
                        Column ranges - batch |  121.1 | 119.48 | -1.34%

sequba commented 4 months ago

Webpack4 ^4.42.0 - I getting an error. Seems the webpack has the problem with importing values from "chevrotain".

// /node_modules/hyperformula/es/parser/FormulaParser.mjs
import { EmbeddedActionsParser, EMPTY_ALT, Lexer, tokenMatcher } from 'chevrotain';
// EmbeddedActionsParser, EMPTY_ALT and others are missing

ERROR in ./node_modules/hyperformula/es/parser/FormulaParser.mjs 689:125-137
Can't import the named export 'tokenMatcher' from non EcmaScript module (only default export is available)
 @ ./node_modules/hyperformula/es/parser/index.mjs
 @ ./node_modules/hyperformula/es/ArraySize.mjs
 @ ./node_modules/hyperformula/es/index.mjs
 @ ./src/index.js

ERROR in ./node_modules/hyperformula/es/parser/FormulaParser.mjs 708:29-41
Can't import the named export 'tokenMatcher' from non EcmaScript module (only default export is available)
 @ ./node_modules/hyperformula/es/parser/index.mjs
 @ ./node_modules/hyperformula/es/ArraySize.mjs
 @ ./node_modules/hyperformula/es/index.mjs
 @ ./src/index.js

I found out that webpack 4 does not support exports, and there seems to be no easy workaround for that. By tweaking the webpack configuration, I managed to make the project import HyperFormula correctly using the legacy paths. Working demo.

codecov[bot] commented 3 months ago

Codecov Report

All modified and coverable lines are covered by tests :white_check_mark:

Project coverage is 97.36%. Comparing base (e32e132) to head (0cd4e05).

Additional details and impacted files

[![Impacted file tree graph](https://app.codecov.io/gh/handsontable/hyperformula/pull/1377/graphs/tree.svg?width=650&height=150&src=pr&token=5k9ZQv8azO&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=handsontable)](https://app.codecov.io/gh/handsontable/hyperformula/pull/1377?src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=handsontable) ```diff @@ Coverage Diff @@ ## develop #1377 +/- ## ======================================== Coverage 97.36% 97.36% ======================================== Files 169 169 Lines 14421 14421 Branches 3021 3021 ======================================== Hits 14041 14041 Misses 380 380 ```

magierg commented 3 months ago

I have retested all the demos available on https://github.com/handsontable/hyperformula-demos/tree/import-demos

plus the bundlers mentioned by @budnix getting the same results.

On top of the above I have tested:

Webpack 5.9 + TS - tsconfig.js setting change required:
```
"module": "node16",
"moduleResolution": "node16",
```
React 18^ + TS - same tsconfig.js change required
Angular 16.0.2 + TS 4.4.3 - @sequba to investigate tsconfig changes required
Angular 17.3.1 + TS 5.2 - same issue with TS

Svelte 3.5.4 + vite 4 - getting this error - might be user error - @sequba to investigate

Error: Language already registered.
at HyperFormula.registerLanguage (/Users/magierg/repos/hyperformula-demos/svelte-demo/node_modules/hyperformula/commonjs/HyperFormula.js:287:13)
at Hyperformula.svelte:18:15
at Object.$$render (/node_modules/svelte/internal/index.mjs:1892:22)
at eval (/src/routes/+page.svelte:24:148)
at Object.$$render (/node_modules/svelte/internal/index.mjs:1892:22)
at Object.default (root.svelte:41:38)
at eval (/node_modules/@sveltejs/kit/src/runtime/components/layout.svelte:8:41)
at Object.$$render (/node_modules/svelte/internal/index.mjs:1892:22)
at root.svelte:40:37
at $$render (/node_modules/svelte/internal/index.mjs:1892:22)

Vue 3.3.4 + vite 4.4.9 - OK

sequba commented 2 months ago

TODO: verify it with the code example in issue https://github.com/handsontable/hyperformula/issues/1143

sequba commented 2 months ago

Svelte 3.5.4 + vite 4 - getting this error - might be user error - @sequba to investigate

It works correctly. The issue you reported was caused by running the setup code twice. I created a demo for svelte: https://github.com/handsontable/hyperformula-demos/tree/import-demos/import-demo-esm-svelte

Angular case is still to be verified.

handsontable / hyperformula