-
Notifications
You must be signed in to change notification settings - Fork 43
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
feat: convert to ESM (breaking change) #856
Conversation
this probably won't work with node 14 at all ugh
most of them are now .cjs with the exception of bin/rdme.js
can we move off jest? all my homies hate jest
Update: while I made substantial progress on this, we've hit a pretty massive blocker 😵💫 we rely on Jon's work in #857 should make this transition a lot easier, but until we figure out a different strategy for building an executable (or if EDIT (9/2): Might think about https://deno.com/blog/build-cross-platform-cli Ran into the following error when trying to build an executable with Deno locally:
Deno version info:
I also tried following Node's guidelines for building a single executable in Node v20. I haven't troubleshooted this further but I ran into the following error when following the steps above and trying to run the generated executable:
Here's my { "main": "bin/rdme.js", "output": "sea-prep.blob" } It's weird because running
|
deno needs this
formData.append('spec', { | ||
type: 'application/json', | ||
name: 'openapi.json', | ||
[Symbol.toStringTag]: 'File', | ||
stream() { | ||
return stream; | ||
}, | ||
}); |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@erunion I'd like your blessing with these changes now that we're using formdata-node
— does our API care what we name the file? I just set it to openapi.json
but let me know if you feel otherwise.
also our API mocks inspect this payload so we should be in good shape.
- 14 | ||
- 16 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
with this PR, we're technically requiring Node 18 and above but I'll make that official in a separate PR.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
made it look easy
@@ -24,7 +24,14 @@ export default async function streamSpecToRegistry(spec: string) { | |||
|
|||
debug('file and stream created, streaming into form data payload'); | |||
const formData = new FormData(); | |||
formData.append('spec', stream); | |||
formData.append('spec', { |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This work seems fine but formdata-node
is still pretty shitty. Recommend moving off it and node-fetch
as soon as we can. Left a diff in #801 (comment) with the work you can do to this file to move it over to all native APIs.
@@ -220,7 +220,9 @@ async function handleRes(res: Response, rejectOnJsonError = true) { | |||
const contentType = res.headers.get('content-type'); | |||
const extension = mime.extension(contentType); | |||
if (extension === 'json') { | |||
const body = await res.json(); | |||
// TODO: type this better |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Leaving this as any
is probably fine imo. You aren't going to have full documented types for these responses without utilizing our API SDK or anything like that (and even then the types are nonexistent for API v1).
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
yeah node-fetch
is remarkably bad about typing responses
# [8.7.0-next.3](v8.7.0-next.2...v8.7.0-next.3) (2023-09-14) ### Features * convert to ESM (breaking change) ([#856](#856)) ([84b8571](84b8571)), closes [/www.stefanjudis.com/snippets/how-to-import-json-files-in-es-modules-node-js/#option-1](https://github.com//www.stefanjudis.com/snippets/how-to-import-json-files-in-es-modules-node-js//issues/option-1) [1#L228](https://github.com/1/issues/L228) [skip ci]
# [9.0.0](v8.6.6...v9.0.0) (2024-12-06) * feat!: deprecation notices for non-readme-refactored commands ([#1099](#1099)) ([732e32b](732e32b)) * feat!: drop node 18 ([#1085](#1085)) ([ebc2ac0](ebc2ac0)) * feat!: final v9 touchups ([#1106](#1106)) ([15447c5](15447c5)), closes [#1107](#1107) * feat!: oclif (take 2) ([#1068](#1068)) ([5e05f93](5e05f93)), closes [#962](#962) [#1067](#1067) [/github.com/readmeio/rdme/blob/d01d76fe3c2e4a98b4f5c415be03e589fbe3b56e/.releaserc.yml#L30](https://github.com//github.com/readmeio/rdme/blob/d01d76fe3c2e4a98b4f5c415be03e589fbe3b56e/.releaserc.yml/issues/L30) [#1067](#1067) * feat!: remove `validate`, deprecate/hide `open` ([#1072](#1072)) ([f1b46f6](f1b46f6)) * feat!: switch topic separator to space ([#1100](#1100)) ([13eb8ab](13eb8ab)) ### Bug Fixes * add better debugging for fetch failures ([a17f8da](a17f8da)) * add GITHUB_TOKEN ([e106e10](e106e10)) * attempt to use semantic-release/github instead of `gh` ([331d28b](331d28b)) * build `dist-gha/` files with every release ([f42392b](f42392b)) * bump semantic-release versions ([21efc66](21efc66)) * debug properly ([#1078](#1078)) ([5de0a4f](5de0a4f)) * **deps:** bump more deps ([#1042](#1042)) ([786a000](786a000)) * empty commit to trigger build ([51c1566](51c1566)) * empty commit to trigger build ([76efb7e](76efb7e)) * empty commit to trigger release ([3604f2a](3604f2a)) * fixed debug script ([#908](#908)) ([82c3541](82c3541)) * hide `ExperimentalWarning` ([#901](#901)) ([f9b5679](f9b5679)) * **npm:** tweak npm lifecycle scripts ([#1073](#1073)) ([35534db](35534db)) * oclif-friendly error logging ([#1080](#1080)) ([73c5f4c](73c5f4c)) * **openapi:** add spinner catch statement ([#961](#961)) ([4669b29](4669b29)) * **release:** track `dist-gha` assets properly ([b0934cb](b0934cb)) * **release:** track changes to commands doc directory ([78b6554](78b6554)) * swap out ts-node for tsx ([16f64b3](16f64b3)) * Update LICENSE for 2024 ([#963](#963)) ([23cf44b](23cf44b)) * use newest import attributes syntax ([#993](#993)) ([d76c0ae](d76c0ae)), closes [/github.com/nodejs/node/blob/main/doc/changelogs/CHANGELOG_V20.md#2023-11-22-version-20100](https://github.com//github.com/nodejs/node/blob/main/doc/changelogs/CHANGELOG_V20.md/issues/2023-11-22-version-20100) * **versions/update:** various edge cases ([#965](#965)) ([580e307](580e307)) ### chore * type fixes for tests ([#903](#903)) ([d423b4c](d423b4c)) ### Code Refactoring * remove `oas`, `swagger`, `docs:edit` ([#902](#902)) ([9107d15](9107d15)) ### Features * add `@oclif/plugin-not-found`, other cleanups ([#1074](#1074)) ([6529b03](6529b03)) * add `title` flag to `openapi:convert` ([#1071](#1071)) ([1d71f3f](1d71f3f)), closes [#1068](#1068) * convert to ESM (breaking change) ([#856](#856)) ([84b8571](84b8571)), closes [/www.stefanjudis.com/snippets/how-to-import-json-files-in-es-modules-node-js/#option-1](https://github.com//www.stefanjudis.com/snippets/how-to-import-json-files-in-es-modules-node-js//issues/option-1) [1#L228](https://github.com/1/issues/L228) * **fetch:** use undici + `ProxyAgent` ([#1000](#1000)) ([9da7132](9da7132)), closes [#999](#999) * **openapi/convert:** support openapi in convert command ([#941](#941)) ([a33bbeb](a33bbeb)) * revamped `oclif`-powered docs ([#1081](#1081)) ([8a2833b](8a2833b)) * sort when syncing by parent ([#973](#973)) ([9795840](9795840)) * support `README_API_KEY` env var ([#950](#950)) ([bcf3f18](bcf3f18)) * support node 18 and up ([#900](#900)) ([a217904](a217904)) * **test:** moving unit tests over to vitest ([#857](#857)) ([36d561b](36d561b)), closes [#870](#870) * use `actions/checkout@v4` everywhere ([#895](#895)) ([d30b71c](d30b71c)) * **versions:** flag parity with API, copy fixes ([#906](#906)) ([d424d9f](d424d9f)) ### BREAKING CHANGES * `rdme openapi` is deprecated and will be replaced in `rdme@10` by a command with a simpler flag setup based on community feedback. * deprecates commands that are not supported in ReadMe Refactored. For more information, please visit our migration guide: https://github.com/readmeio/rdme/tree/v9/documentation/migration-guide.md ## 🧬 QA & Testing Does the copy in these deprecation warnings make sense to you? Note that the links will be broken for now since we haven't tagged a proper v9 release yet, but that will be fixed once this release is out! * the topic separator (i.e., what separates a command from its subcommand) has changed from a colon to a space by default. For example, `rdme openapi:validate` is now `rdme openapi validate`. The colon topic separator will continue to be supported so there is no need to change any existing commands, but all documentation and help screens will reflect the space topic separator. ## 🧬 QA & Testing Do tests still pass? * dropping support for Node.js v18. The minimum required Node.js version is v20.10.0. * `rdme validate` has been removed, use `rdme openapi:validate` instead. * `rdme open` is now deprecated also updates our docs accordingly * the `rdme` GitHub Actions is now a [the `node20` JavaScript action](https://docs.github.com/en/actions/sharing-automations/creating-actions/metadata-syntax-for-github-actions#runs-for-javascript-actions) rather than [a Docker container action](https://docs.github.com/en/actions/sharing-automations/creating-actions/metadata-syntax-for-github-actions#runs-for-docker-container-actions). * `rdme` is now powered by [`oclif`](https://oclif.io/). The formatting and content of certain error messages and outputs may have changed. Please continue to only utilize exit codes to determine command successes/failures. completed tasks: - [x] a handful of tests are still failing, hoping that oclif/test#652 gets merged in) - [x] github actions dry runs are failing (but i got them working in * **versions:** this flips the `isPublic` flag to `hidden`. * removes several deprecated commands * chore: knip cleanup * chore: type fixes for tests * removes several deprecated commands * Node.js >= 18 required [skip ci]
🎉 This PR is included in version 9.0.0 🎉 The release is available on: Your semantic-release bot 📦🚀 |
🧰 Changes
This PR refactors the entire repository over to full ESM. This entailed a few different refactors:
.js
file extensions for relative imports (really wish I had done this after discoveringeslint-plugin-require-extensions
) 😭ora
, see the outstanding issues below)fetch
so a test or two had to be updated accordingly. Eventually we'll want to migrate away fromnock
entirely.module: NodeNext
in ourtsconfig.json
andtype: module
in ourpackage.json
pkg
😵💫 (see ES modules not supported vercel/pkg#1291)pkg
handles a lot of the madness of compiling into single-file executables better than anything else I've tried (see here for more context)Outstanding tasks/issues
Below is a running list of outstanding work — the
ora
issue is mostly out of our hands, but I'll look into theExperimentalWarning
in a follow-up PR.ora
due to segmentation faults at runtime, see ora@7 dependency causes seg fault (was seg fault on mac m1 arm) sindresorhus/ora#229 for more informationoas
(see fix: get exports working in TSnodeNext
oas#796)oas-normalize
(see fix: get exports working in TSnodeNext
oas-normalize#294)tsconfig
cleanup (e.g., do we needdownlevelIteration
?) (edit: nah let's do this further down the line, we're already introducing a lot of new breaking changes as is).cjs
files over to.js
🧬 QA & Testing
Our existing end-to-end tests GitHub Actions tests are passing, meaning this should work, but I'll do some more QA once we tag a beta release.
You can confirm this all works locally by doing the following: