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

[sequba]

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:

• ESM in node project
• ESM in react project (with Typescript)
• 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
• ESM in webpack v5 project
• ESM in webpack v5 project with Typescript -> Works, but requires special configuration ("moduleResolution": "node16" in tsconfig)
• ESM in parcel v2.11 project -> parcel does not support "exports" by default, since v2.9 it can be configured to support it
• CJS in node project
• CJS in parcel v2.11 project
• 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

• Breaking change (a fix or a feature because of which an existing functionality doesn't work as expected anymore)
• New feature or improvement (a non-breaking change that adds functionality)
• 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:

• 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.
• My change is compliant with the OpenDocument standard.
• My change is compatible with Microsoft Excel.
• My change is compatible with Google Sheets.
• I described my changes in the CHANGELOG.md file.
• My changes require a documentation update.
• My changes require a migration guide.

[github-actions]

Performance comparison of head (0cd4e05) vs base (e32e132)

                                     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%

[budnix]

I tested the dist files in some more popular bundlers and here are the results:

• 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".

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

[sequba]

• 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]

Codecov Report

All modified and coverable lines are covered by tests ✅

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

Additional details and impacted files

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

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]

TODO: verify it with the code example in issue #1143

[sequba]

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.