From afcfdc33f27f996d1558707e22fc70cba9714ec5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jimmy=20Wa=CC=88rting?= Date: Fri, 6 Aug 2021 10:38:21 +0200 Subject: [PATCH 01/14] Documented other ways to load ESM --- README.md | 9 +++++++++ docs/v3-UPGRADE-GUIDE.md | 10 ++++++++++ 2 files changed, 19 insertions(+) diff --git a/README.md b/README.md index 08dfbf840..808cee69b 100644 --- a/README.md +++ b/README.md @@ -124,6 +124,15 @@ if (!globalThis.fetch) { } ``` +Stuck with commonjs and can't use ESM imports? +This is a ESM-only module. Using require to load an ES module is not supported because ES modules have asynchronous execution. Instead, use `import()` to lazy load an ES module from a CommonJS module only when needed. +It can improve startup performance + +```js +// mod.cjs +const fetch = (...args) => import('node-fetch').then(mod => mod.default(...args)); +``` + ## Upgrading Using an old version of node-fetch? Check out the following files: diff --git a/docs/v3-UPGRADE-GUIDE.md b/docs/v3-UPGRADE-GUIDE.md index 70120adc6..9e4e53ea4 100644 --- a/docs/v3-UPGRADE-GUIDE.md +++ b/docs/v3-UPGRADE-GUIDE.md @@ -23,6 +23,16 @@ other comparatively minor modifications. Since Node.js will deprecate version 8 at the end of 2019, we decided that node-fetch v3.x will not only drop support for Node.js 4 and 6 (which were supported in v2.x), but also for Node.js 8. We strongly encourage you to upgrade, if you still haven't done so. Check out Node.js' official [LTS plan] for more information on Node.js' support lifetime. +## Converted to ES Module + +This module was converted to be a ESM only package in version `@3.0.0-beta.10` +Using require to load an ES module is not supported because ES modules have asynchronous execution. Instead, use import() to load an ES module from a CommonJS module. + +```js +// mod.cjs +const fetch = (...args) => import('node-fetch').then(mod => mod.default(...args)); +``` + ## The `timeout` option was removed. Since this was never part of the fetch specification, it was removed. AbortSignal offers a more finegrained control of request timeouts, and is standardized in the Fetch spec. For convenience, you can use [timeout-signal](https://github.com/Richienb/timeout-signal) as a workaround: From 14bf429b6529e43be18f5e2849e735fb63e92c99 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jimmy=20Wa=CC=88rting?= Date: Fri, 6 Aug 2021 10:39:09 +0200 Subject: [PATCH 02/14] finegraned -> fine graned --- docs/v3-UPGRADE-GUIDE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/v3-UPGRADE-GUIDE.md b/docs/v3-UPGRADE-GUIDE.md index 9e4e53ea4..ab4bbe251 100644 --- a/docs/v3-UPGRADE-GUIDE.md +++ b/docs/v3-UPGRADE-GUIDE.md @@ -35,7 +35,7 @@ const fetch = (...args) => import('node-fetch').then(mod => mod.default(...args) ## The `timeout` option was removed. -Since this was never part of the fetch specification, it was removed. AbortSignal offers a more finegrained control of request timeouts, and is standardized in the Fetch spec. For convenience, you can use [timeout-signal](https://github.com/Richienb/timeout-signal) as a workaround: +Since this was never part of the fetch specification, it was removed. AbortSignal offers a more fine grained control of request timeouts, and is standardized in the Fetch spec. For convenience, you can use [timeout-signal](https://github.com/Richienb/timeout-signal) as a workaround: ```js const timeoutSignal = require('timeout-signal'); From a6ec12cd5b09997ea2710f2bf03348ed2205eb9c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jimmy=20Wa=CC=88rting?= Date: Fri, 6 Aug 2021 10:39:49 +0200 Subject: [PATCH 03/14] change require to import --- docs/v3-UPGRADE-GUIDE.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/v3-UPGRADE-GUIDE.md b/docs/v3-UPGRADE-GUIDE.md index ab4bbe251..13a515fbc 100644 --- a/docs/v3-UPGRADE-GUIDE.md +++ b/docs/v3-UPGRADE-GUIDE.md @@ -38,8 +38,8 @@ const fetch = (...args) => import('node-fetch').then(mod => mod.default(...args) Since this was never part of the fetch specification, it was removed. AbortSignal offers a more fine grained control of request timeouts, and is standardized in the Fetch spec. For convenience, you can use [timeout-signal](https://github.com/Richienb/timeout-signal) as a workaround: ```js -const timeoutSignal = require('timeout-signal'); -const fetch = require('node-fetch'); +import timeoutSignal from 'timeout-signal'; +import fetch from 'node-fetch'; const {AbortError} = fetch @@ -67,8 +67,8 @@ Prior to v3.x, we included a `browser` field in the package.json file. Since nod If you want charset encoding detection, please use the [fetch-charset-detection] package ([documentation][fetch-charset-detection-docs]). ```js -const fetch = require('node-fetch'); -const convertBody = require('fetch-charset-detection'); +import fetch from 'node-fetch'; +import convertBody from 'fetch-charset-detection'; fetch('https://somewebsite.com').then(res => { const text = convertBody(res.buffer(), res.headers); @@ -80,7 +80,7 @@ fetch('https://somewebsite.com').then(res => { When attempting to parse invalid json via `res.json()`, a `SyntaxError` will now be thrown instead of a `FetchError` to align better with the spec. ```js -const fetch = require('node-fetch'); +import fetch from 'node-fetch'; fetch('https://somewebsitereturninginvalidjson.com').then(res => res.json()) // Throws 'Uncaught SyntaxError: Unexpected end of JSON input' or similar. From d7951fa8efc029ba7f46cdb20b30c1b76a91fceb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jimmy=20Wa=CC=88rting?= Date: Fri, 6 Aug 2021 10:40:41 +0200 Subject: [PATCH 04/14] await response and discourage res.buffer() --- docs/v3-UPGRADE-GUIDE.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/v3-UPGRADE-GUIDE.md b/docs/v3-UPGRADE-GUIDE.md index 13a515fbc..54919c3d0 100644 --- a/docs/v3-UPGRADE-GUIDE.md +++ b/docs/v3-UPGRADE-GUIDE.md @@ -70,8 +70,9 @@ If you want charset encoding detection, please use the [fetch-charset-detection] import fetch from 'node-fetch'; import convertBody from 'fetch-charset-detection'; -fetch('https://somewebsite.com').then(res => { - const text = convertBody(res.buffer(), res.headers); +fetch('https://somewebsite.com').then(async res => { + const buf = Buffer.from(await res.arrayBuffer()); + const text = convertBody(buf, res.headers); }); ``` From d92edfe83199ff09396f5b4ef64f1735764b4a2f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jimmy=20Wa=CC=88rting?= Date: Fri, 6 Aug 2021 10:41:17 +0200 Subject: [PATCH 05/14] corrected minimum node version required --- docs/CHANGELOG.md | 2 +- docs/v3-UPGRADE-GUIDE.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md index 10d38927f..553d09f3e 100644 --- a/docs/CHANGELOG.md +++ b/docs/CHANGELOG.md @@ -5,7 +5,7 @@ Changelog ## v3.0.0-beta.10 -- **Breaking:** minimum supported Node.js version is now 12.8. +- **Breaking:** minimum supported Node.js version is now 12.20. - **Breaking:** node-fetch is now a pure ESM module. - Other: update readme to inform users about ESM. - Other: update dependencies. diff --git a/docs/v3-UPGRADE-GUIDE.md b/docs/v3-UPGRADE-GUIDE.md index 54919c3d0..be472c583 100644 --- a/docs/v3-UPGRADE-GUIDE.md +++ b/docs/v3-UPGRADE-GUIDE.md @@ -19,7 +19,7 @@ other comparatively minor modifications. # Breaking Changes -## Minimum supported Node.js version is now 10.16 +## Minimum supported Node.js version is now 12.20 Since Node.js will deprecate version 8 at the end of 2019, we decided that node-fetch v3.x will not only drop support for Node.js 4 and 6 (which were supported in v2.x), but also for Node.js 8. We strongly encourage you to upgrade, if you still haven't done so. Check out Node.js' official [LTS plan] for more information on Node.js' support lifetime. From 880bc5e141daea7fdf7a09b6c4f3f0352e1dbeae Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jimmy=20Wa=CC=88rting?= Date: Fri, 6 Aug 2021 11:15:40 +0200 Subject: [PATCH 06/14] updated changelog --- docs/CHANGELOG.md | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md index 553d09f3e..f7488d663 100644 --- a/docs/CHANGELOG.md +++ b/docs/CHANGELOG.md @@ -1,7 +1,12 @@ -Changelog -========= +# Changelog +All notable changes to this project will be documented in this file. -# 3.x release +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## [Unreleased] yyyy-mm-dd + +- Other: Updated README & v3-upgrade docs (#1236) ## v3.0.0-beta.10 @@ -374,3 +379,5 @@ See [changelog on 1.x branch](https://github.com/node-fetch/node-fetch/blob/1.x/ ## v0.1 - Major: initial public release + +[Unreleased]: https://github.com/node-fetch/node-fetch/compare/v3.0.0-beta.10...HEAD From 0eac430f3bd510842aa9d2a9ea9a04be870e5aac Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jimmy=20Wa=CC=88rting?= Date: Sat, 7 Aug 2021 16:59:34 +0200 Subject: [PATCH 07/14] updated async import desc --- README.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/README.md b/README.md index 808cee69b..6e371fe78 100644 --- a/README.md +++ b/README.md @@ -124,9 +124,7 @@ if (!globalThis.fetch) { } ``` -Stuck with commonjs and can't use ESM imports? -This is a ESM-only module. Using require to load an ES module is not supported because ES modules have asynchronous execution. Instead, use `import()` to lazy load an ES module from a CommonJS module only when needed. -It can improve startup performance +`node-fetch` is an ESM-only module - you are not able to import it with `require`. If you are unable to use ESM in your project you can use the async `import()` from CommonJS to load `node-fetch` asynchronously: ```js // mod.cjs From cb69e021811dbe6bf6872ae2335b0eaa1e02f0a1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jimmy=20Wa=CC=88rting?= Date: Sun, 8 Aug 2021 01:04:25 +0200 Subject: [PATCH 08/14] destruct --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 6e371fe78..e6d55795e 100644 --- a/README.md +++ b/README.md @@ -128,7 +128,7 @@ if (!globalThis.fetch) { ```js // mod.cjs -const fetch = (...args) => import('node-fetch').then(mod => mod.default(...args)); +const fetch = (...args) => import('node-fetch').then(({default: fetch}) => fetch(...args)); ``` ## Upgrading From 01b989c29146d425295cd118676a72124a203617 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jimmy=20Wa=CC=88rting?= Date: Tue, 10 Aug 2021 10:18:21 +0200 Subject: [PATCH 09/14] fetch-charset-detection support for ArrayBuffer now --- docs/v3-UPGRADE-GUIDE.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/v3-UPGRADE-GUIDE.md b/docs/v3-UPGRADE-GUIDE.md index be472c583..b59363586 100644 --- a/docs/v3-UPGRADE-GUIDE.md +++ b/docs/v3-UPGRADE-GUIDE.md @@ -71,8 +71,8 @@ import fetch from 'node-fetch'; import convertBody from 'fetch-charset-detection'; fetch('https://somewebsite.com').then(async res => { - const buf = Buffer.from(await res.arrayBuffer()); - const text = convertBody(buf, res.headers); + const buf = await res.arrayBuffer(); + const text = convertBody(buf, res.headers); }); ``` From 13b4a3c680b3c0ee749be113aae69c9e514e1a93 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jimmy=20Wa=CC=88rting?= Date: Sat, 21 Aug 2021 13:34:27 +0200 Subject: [PATCH 10/14] v2 alternative --- README.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/README.md b/README.md index e6d55795e..84f1df0ca 100644 --- a/README.md +++ b/README.md @@ -131,6 +131,9 @@ if (!globalThis.fetch) { const fetch = (...args) => import('node-fetch').then(({default: fetch}) => fetch(...args)); ``` +The alternative is to stick with the `@2.x` branch that is built with cjs +`npm install node-fetch@2` + ## Upgrading Using an old version of node-fetch? Check out the following files: From 4017472cff10aa1e097cbdc9e405da9b723dfe50 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jimmy=20Wa=CC=88rting?= Date: Sat, 21 Aug 2021 15:34:13 +0200 Subject: [PATCH 11/14] suggested change --- docs/v3-UPGRADE-GUIDE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/v3-UPGRADE-GUIDE.md b/docs/v3-UPGRADE-GUIDE.md index b59363586..d7833d589 100644 --- a/docs/v3-UPGRADE-GUIDE.md +++ b/docs/v3-UPGRADE-GUIDE.md @@ -21,7 +21,7 @@ other comparatively minor modifications. ## Minimum supported Node.js version is now 12.20 -Since Node.js will deprecate version 8 at the end of 2019, we decided that node-fetch v3.x will not only drop support for Node.js 4 and 6 (which were supported in v2.x), but also for Node.js 8. We strongly encourage you to upgrade, if you still haven't done so. Check out Node.js' official [LTS plan] for more information on Node.js' support lifetime. +Since Node.js deprecated version 10 in May 2020, we decided that node-fetch v3.x will drop support for Node.js 4, 6, 8, and 10 (which were supported in v2.x). We strongly encourage you to upgrade, if you still haven't done so. Check out Node.js' official [LTS plan] for more information on Node.js' support lifetime. ## Converted to ES Module From 65f3baaf3154adab25587744833b9d89c645c5fc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jimmy=20Wa=CC=88rting?= Date: Sat, 21 Aug 2021 19:23:12 +0200 Subject: [PATCH 12/14] docs: Fix spelling --- README.md | 5 ++--- docs/CHANGELOG.md | 4 ++-- docs/v3-UPGRADE-GUIDE.md | 8 ++++---- 3 files changed, 8 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 84f1df0ca..2ae3fa5c8 100644 --- a/README.md +++ b/README.md @@ -124,15 +124,14 @@ if (!globalThis.fetch) { } ``` -`node-fetch` is an ESM-only module - you are not able to import it with `require`. If you are unable to use ESM in your project you can use the async `import()` from CommonJS to load `node-fetch` asynchronously: +`node-fetch` is an ESM-only module - you are not able to import it with `require`. If you are unable to use ESM in your project you can use the async `import()` function from CommonJS to load `node-fetch` asynchronously: ```js // mod.cjs const fetch = (...args) => import('node-fetch').then(({default: fetch}) => fetch(...args)); ``` -The alternative is to stick with the `@2.x` branch that is built with cjs -`npm install node-fetch@2` +Alternatively, you can stay on v2 which is built with CommonJS. ## Upgrading diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md index f7488d663..efa2e1b4e 100644 --- a/docs/CHANGELOG.md +++ b/docs/CHANGELOG.md @@ -1,12 +1,12 @@ # Changelog -All notable changes to this project will be documented in this file. +All notable changes will be recorded here. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). ## [Unreleased] yyyy-mm-dd -- Other: Updated README & v3-upgrade docs (#1236) +- docs: Add example for loading ESM from CommonJS (#1236) ## v3.0.0-beta.10 diff --git a/docs/v3-UPGRADE-GUIDE.md b/docs/v3-UPGRADE-GUIDE.md index d7833d589..26df53a1b 100644 --- a/docs/v3-UPGRADE-GUIDE.md +++ b/docs/v3-UPGRADE-GUIDE.md @@ -21,21 +21,21 @@ other comparatively minor modifications. ## Minimum supported Node.js version is now 12.20 -Since Node.js deprecated version 10 in May 2020, we decided that node-fetch v3.x will drop support for Node.js 4, 6, 8, and 10 (which were supported in v2.x). We strongly encourage you to upgrade, if you still haven't done so. Check out Node.js' official [LTS plan] for more information on Node.js' support lifetime. +Since Node.js 10 has been deprecated since May 2020, we have decided that node-fetch v3 will drop support for Node.js 4, 6, 8, and 10 (which were previously supported). We strongly encourage you to upgrade if you still haven't done so. Check out the Node.js official [LTS plan] for more information. ## Converted to ES Module -This module was converted to be a ESM only package in version `@3.0.0-beta.10` +This module was converted to be a ESM only package in version `3.0.0-beta.10`. Using require to load an ES module is not supported because ES modules have asynchronous execution. Instead, use import() to load an ES module from a CommonJS module. ```js // mod.cjs -const fetch = (...args) => import('node-fetch').then(mod => mod.default(...args)); +const fetch = (...args) => import('node-fetch').then(({default: fetch}) => fetch(...args)); ``` ## The `timeout` option was removed. -Since this was never part of the fetch specification, it was removed. AbortSignal offers a more fine grained control of request timeouts, and is standardized in the Fetch spec. For convenience, you can use [timeout-signal](https://github.com/Richienb/timeout-signal) as a workaround: +Since this was never part of the fetch specification, it was removed. AbortSignal offers more fine grained control of request timeouts, and is standardized in the Fetch spec. For convenience, you can use [timeout-signal](https://github.com/node-fetch/timeout-signal) as a workaround: ```js import timeoutSignal from 'timeout-signal'; From 9ccfa4008157ac4604c6663dd28a214657e890fd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jimmy=20Wa=CC=88rting?= Date: Sat, 28 Aug 2021 02:06:44 +0200 Subject: [PATCH 13/14] encourage v2 from cjs --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 2ae3fa5c8..d4c88af53 100644 --- a/README.md +++ b/README.md @@ -124,15 +124,15 @@ if (!globalThis.fetch) { } ``` -`node-fetch` is an ESM-only module - you are not able to import it with `require`. If you are unable to use ESM in your project you can use the async `import()` function from CommonJS to load `node-fetch` asynchronously: +`node-fetch` is an ESM-only module - you are not able to import it with `require`. We recommend you stay on v2 which is built with CommonJS unless you use ESM yourself. We will continue to publish critical bug fixes for it. + +Alternatively, you can use the async `import()` function from CommonJS to load `node-fetch` asynchronously: ```js // mod.cjs const fetch = (...args) => import('node-fetch').then(({default: fetch}) => fetch(...args)); ``` -Alternatively, you can stay on v2 which is built with CommonJS. - ## Upgrading Using an old version of node-fetch? Check out the following files: From 7ee3e12ef587b54239d63bd0c796c2540a89d391 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jimmy=20Wa=CC=88rting?= Date: Sat, 28 Aug 2021 02:07:46 +0200 Subject: [PATCH 14/14] encourage v2 from cjs --- docs/v3-UPGRADE-GUIDE.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/v3-UPGRADE-GUIDE.md b/docs/v3-UPGRADE-GUIDE.md index 26df53a1b..4e9eada0f 100644 --- a/docs/v3-UPGRADE-GUIDE.md +++ b/docs/v3-UPGRADE-GUIDE.md @@ -26,7 +26,9 @@ Since Node.js 10 has been deprecated since May 2020, we have decided that node-f ## Converted to ES Module This module was converted to be a ESM only package in version `3.0.0-beta.10`. -Using require to load an ES module is not supported because ES modules have asynchronous execution. Instead, use import() to load an ES module from a CommonJS module. +`node-fetch` is an ESM-only module - you are not able to import it with `require`. We recommend you stay on v2 which is built with CommonJS unless you use ESM yourself. We will continue to publish critical bug fixes for it. + +Alternatively, you can use the async `import()` function from CommonJS to load `node-fetch` asynchronously: ```js // mod.cjs