Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Support node >= v18, update JSDoc, add npm badge #8

Merged
merged 1 commit into from
Dec 29, 2023
Merged

Conversation

mbland
Copy link
Owner

@mbland mbland commented Dec 29, 2023

Many of these changes are JSDoc updates. Adds a npm badge to the README in advance. This also removes the technically unnecessary and technically incorrect copyright declaration at the top of LICENSE.txt.

The most important change was adding "node": ">=18.0.0" to the "engines" field of package.json. Doing this required moving the existing test/fixtures/jsdocStub/jsdoc script to jsdoc.js and adding a new jsdoc shell wrapper.

The following explanation for this is from the file comment of the new wrapper script.


[This wrapper] is necessary to support older Node versions as package.json engines without removing the "type": "module" specifier. Without this shim, running pnpm test under many older verions caused runJsdoc.test.js and main.test.js to fail on the spawn(jsdocPath) call within runJsdoc().

These older versions couldn't grok that the previous jsdoc stub was really written in ECMAScript Module style without a file extension:

  TypeError [ERR_UNKNOWN_FILE_EXTENSION]: Unknown file extension "" for
  .../jsdoc-cli-wrapper/test/fixtures/jsdocStub/jsdoc. Loading
  extensionless files is not supported inside of "type":"module"
  package.json contexts. The package.json file
  .../jsdoc-cli-wrapper/package.json caused this "type":"module"
  context. Try changing
  .../jsdoc-cli-wrapper/test/fixtures/jsdocStub/jsdoc to have a file
  extension. Note the "bin" field of package.json can point to a file
  with an extension, for example
  {"type":"module","bin":{"jsdoc":"./test/fixtures/jsdocStub/jsdoc.js"}}

I tried adding the --experimental-default-type=module flag to the shebang line of the former jsdoc stub. Only after trying that did I realize that #!/usr/bin/env style shebangs don't support passing command line arguments to the specified interpreter.

Hence moving the original jsdoc stub to jsdoc.js and invoking it via this one-line wrapper.

Many of these changes are JSDoc updates. Adds a npm badge to the README
in advance. This also removes the technically unnecessary and
technically incorrect copyright declaration at the top of LICENSE.txt.

The most important change was adding `"node": ">=18.0.0"` to the
"engines" field of package.json. Doing this required moving the existing
test/fixtures/jsdocStub/jsdoc script to jsdoc.js and adding a new
`jsdoc` shell wrapper.

The following explanation for this is from the file comment of the new
wrapper script.

---

[This wrapper] is necessary to support older Node versions as
package.json engines without removing the `"type": "module"` specifier.
Without this shim, running `pnpm test` under many older verions caused
runJsdoc.test.js and main.test.js to fail on the spawn(jsdocPath) call
within runJsdoc().

These older versions couldn't grok that the previous `jsdoc` stub was
really written in ECMAScript Module style without a file extension:

  TypeError [ERR_UNKNOWN_FILE_EXTENSION]: Unknown file extension "" for
  .../jsdoc-cli-wrapper/test/fixtures/jsdocStub/jsdoc. Loading
  extensionless files is not supported inside of "type":"module"
  package.json contexts. The package.json file
  .../jsdoc-cli-wrapper/package.json caused this "type":"module"
  context. Try changing
  .../jsdoc-cli-wrapper/test/fixtures/jsdocStub/jsdoc to have a file
  extension. Note the "bin" field of package.json can point to a file
  with an extension, for example
  {"type":"module","bin":{"jsdoc":"./test/fixtures/jsdocStub/jsdoc.js"}}

I tried adding the `--experimental-default-type=module` flag to the
shebang line of the former `jsdoc` stub. Only after trying that did I
realize that `#!/usr/bin/env` style shebangs don't support passing
command line arguments to the specified interpreter.

Hence moving the original `jsdoc` stub to `jsdoc.js` and invoking it via
this one-line wrapper.
@mbland mbland self-assigned this Dec 29, 2023
@mbland mbland merged commit 5cf437d into main Dec 29, 2023
3 checks passed
@mbland mbland deleted the support-node-v18 branch December 29, 2023 17:50
mbland added a commit that referenced this pull request Dec 29, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

1 participant