Add strict type checking via TypeScript

[mbland]

Adds Typescript to devDependencies and a jsconfig.json files to ensure Visual Studio Code performs more thorough type checking.

Description largely copied from:

• Bump to v1.0.4, add type files, fix type issues test-page-opener#22 mbland/test-page-opener@a63f274
• Bump to v1.0.5, update README, strict type checks test-page-opener#23 mbland/test-page-opener@01a79f6
• Bump to v1.0.5, strict type checks, generate types jsdoc-cli-wrapper#20 mbland/jsdoc-cli-wrapper@fafcd21
• Add strict type checking via TypeScript rollup-plugin-handlebars-precompiler#7 mbland/rollup-plugin-handlebars-precompiler@eb5b9a8
• Check rollup types, add jsdoc-plugin-typescript rollup-plugin-handlebars-precompiler#8 mbland/rollup-plugin-handlebars-precompiler@8b36b2a

The code is still JavaScript, but now we get strict type checking in Visual Studio Code and in continuous integration via tsc in pnpm typecheck.

The docs generated by 'jsdoc' are a little funky, and we don't get as much documentation in Visual Studio Code as I expected. I believe I can fix these issues at some point with this foundation in place.

The actual changes include:

• Added @types/chai, jsdoc, and typescript as devDependencies.

• Set .eslintrc to disable the no-undefined-types rule by extending "plugin:jsdoc/recommended-typescript-flavor-error". This is because the Handlebars types in lib/parser.js weren't trivial to replicate, and TypeScript finds those types just fine. This was based on advice from:

  ...the config plugin:jsdoc/recommended-typescript-error should
  disable the jsdoc/no-undefined-types rule because TypeScript itself
  is responsible for reporting errors about invalid JSDoc types.

  • no-undefined-types: false positives for built-in interface types in typescript mode gajus/eslint-plugin-jsdoc#888 (comment)

  And:

  If you are not using TypeScript syntax (your source files are still
  .js files) but you are using the TypeScript flavor within JSDoc
  (i.e., the default "typescript" mode in eslint-plugin-jsdoc) and you
  are perhaps using allowJs and checkJs options of TypeScript's
  tsconfig.json), you may use:

  {
    "extends": ["plugin:jsdoc/recommended-typescript-flavor"]
  }

  ...or to report with failing errors instead of mere warnings:

  More background:

  • https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/no-undefined-types.md
  • Way to feed no-undefined-types additional files or have it auto-detect them (and finding unused types within the same set of files); avoid defects of tampering with no-unused-vars gajus/eslint-plugin-jsdoc#99
  • no-undefined-types and TypeScript gajus/eslint-plugin-jsdoc#1098
  • Question: Import typedef from another file? jsdoc/jsdoc#1537

• Added settings.jsdoc.preferredTypes.Object = "object" to .eslintrc to enable "Object.<..., ...>" syntax in a JSDoc @typedef. Got rid of some extra whitespaces in .eslintrc, too.

  • https://github.com/gajus/eslint-plugin-jsdoc/blob/b60cbb027b03b4f6d509933b0dca8681dbe47206/docs/rules/check-types.md#why-not-capital-case-everything
  • https://github.com/gajus/eslint-plugin-jsdoc/blob/b60cbb027b03b4f6d509933b0dca8681dbe47206/docs/settings.md#settings-to-configure-check-types-and-no-undefined-types

• Added '.js' extension to all internal imports and added JSDoc comments everywhere reqired by pnpm typecheck.

• Added 'jsdoc-plugin-typescript' to the build to handle the TypeScript import().Type directives. This ended up pulling in the 'es-abstract' module, which blew up the pnpm-lock.yaml file. If I get an itch, I'll implement my own plugin one day and replace it.

• Updated pnpm test-ci to incorporate pnpm jsdoc and pnpm typecheck. Added 'jsdoc' to devDependencies to enable this.

• Added null checks everywhere reqired by pnpm typecheck. Added tests to cover all the null cases.

• Added globals.d.ts and a /* global STRCALC_BACKEND */ ESLint comment to calculators.js to properly type check globalThis.STRCALC_BACKEND. Ironically, this required just referencing it as STRCALC_BACKEND without globalThis.

• Added a temporary components/template.d.ts containing the Handlebars Template() type declaration. Once I properly export those types from rollup-plugin-handlebars-precompiler, I'll remove it. (That plugin currently contains lib/template.d.ts, not types/template.d.ts.)

• Added a test for the #missing app element case in main.js by adding a new test/main-missing-app-div.test.js. I need to port it to mbland/test-page-opener to solve the coverage problem encountered in:

  • Bump to v1.0.5, update README, strict type checks test-page-opener#23 mbland/test-page-opener@01a79f6

  • Added a new missing.html and "JsdomPageOpener > doesn't throw if
    missing app div" test case to cover new null check in
    test-modules/main.js.

    This did, however, throw off Istanbul coverage, but not V8
    coverage. Running just the "doesn't throw" test case shows 0%
    coverage of main.js, even though the test clearly passes. My
    suspicion is that Istanbul can't associate the
    ./main.js?version=missing import path from missing.html with the
    test-modules/main.js file.

    So now pnpm test:ci:jsdom will use the V8 provider, and pnpm test:ci:browser, which doesn't use missing.html, will continue to
    use Istanbul. Each task outputs its own separate .lcov file which
    then gets merged into Coveralls.

• Updated setupFetchStub() to detect the type of the body argument and call JSON.stringify() itself if it's an object. This eliminated the need for most callers to call JSON.stringify().

• Updated StringCalculatorPage with typing information and made it so that an empty object will stand in for null elements. This is playing loose with typing a bit, as any nulls will cause errors showing unknown property access. But that seemed better than burdening all callers to do their own null checks or workarounds.

Of special note:

• Added the instantiate() parameter to Calculator.init() to inject a Handlebars Template() function. This enabled testing that a missing #numbers element was logged by Calculator.init().

  Tests for this and Calculator.#submitRequest() set up a console.error spy along with a callback for Vitest's vi.waitFor().

  I need to write a document and/or blog post about this as part of the Handlebars Component Pattern. (I just came up with that name while writing it.)