From 635eced4d347ee71f099040eb8da986fe220c75b Mon Sep 17 00:00:00 2001 From: shellscape Date: Mon, 7 Feb 2022 09:38:09 -0500 Subject: [PATCH 1/5] docs: expand mixins information, notate body reuse --- README.md | 18 +++++++++++++++++- 1 file changed, 17 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index f933f0d8f07..c7c9c128e38 100644 --- a/README.md +++ b/README.md @@ -65,7 +65,15 @@ for await (const data of body) { console.log('trailers', trailers) ``` -Using [the body mixin from the Fetch Standard](https://fetch.spec.whatwg.org/#body-mixin). +## Body Mixins + +The `body` mixins are the most common way to format the request/response body from a [`ReadableStream`](https://streams.spec.whatwg.org/#readablestream). Mixins include: + +- [`.formData()`](https://fetch.spec.whatwg.org/#dom-body-formdata) +- [`.json()`](https://fetch.spec.whatwg.org/#dom-body-json) +- [`.text()`](https://fetch.spec.whatwg.org/#dom-body-text) + +Example usage: ```js import { request } from 'undici' @@ -83,6 +91,14 @@ console.log('data', await body.json()) console.log('trailers', trailers) ``` +_Note: Once a mixin has been called, the `ReadableStream` the body represents cannot be reused, thus calling additional mixins on `.body`, e.g. `.body.json(); .body.text()` will result in an error `TypeError: unusable` being thrown and returned through the `Promise` rejection._ + +Should you need to access the `body` in plain-text after using a mixin, the best practice is to use the `.text()` mixin first, and manually parse the text to the desired format. + +If the scenario arises where you absolutely must have a copy of the result stream, [`.clone`](https://fetch.spec.whatwg.org/#dom-request-clone) can be used _before_ using a `body` mixin, or [`body.pipeThrough`](https://streams.spec.whatwg.org/#readablestream-pipe-through) with a user-defined stream [§](https://web.dev/fetch-upload-streaming), such as [`TransformS tream`]https://nodejs.org/api/stream.html#duplex-and-transform-streams. + +For more information about their behavior, please reference the body mixin from the [Fetch Standard](https://fetch.spec.whatwg.org/#body-mixin). + ## Common API Methods This section documents our most commonly used API methods. Additional APIs are documented in their own files within the [docs](./docs/) folder and are accessible via the navigation list on the left side of the docs site. From 37ac5e45bfdc6eabd1a228fec8ad6f400a293cac Mon Sep 17 00:00:00 2001 From: Andrew Powell Date: Mon, 7 Feb 2022 10:40:49 -0500 Subject: [PATCH 2/5] chore: apply suggestions from code review Co-authored-by: Robert Nagy --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index c7c9c128e38..6739a5a1862 100644 --- a/README.md +++ b/README.md @@ -95,7 +95,7 @@ _Note: Once a mixin has been called, the `ReadableStream` the body represents ca Should you need to access the `body` in plain-text after using a mixin, the best practice is to use the `.text()` mixin first, and manually parse the text to the desired format. -If the scenario arises where you absolutely must have a copy of the result stream, [`.clone`](https://fetch.spec.whatwg.org/#dom-request-clone) can be used _before_ using a `body` mixin, or [`body.pipeThrough`](https://streams.spec.whatwg.org/#readablestream-pipe-through) with a user-defined stream [§](https://web.dev/fetch-upload-streaming), such as [`TransformS tream`]https://nodejs.org/api/stream.html#duplex-and-transform-streams. +If the scenario arises where you absolutely must have a copy of the result stream, [`.clone`](https://fetch.spec.whatwg.org/#dom-request-clone) can be used _before_ using a `body` mixin, or [`body.pipeThrough`](https://streams.spec.whatwg.org/#readablestream-pipe-through) with a user-defined stream [§](https://web.dev/fetch-upload-streaming), such as [`TransformStream`]https://nodejs.org/api/stream.html#duplex-and-transform-streams. For more information about their behavior, please reference the body mixin from the [Fetch Standard](https://fetch.spec.whatwg.org/#body-mixin). From 54de134420d9320b20ae2db28e116e23c0f97236 Mon Sep 17 00:00:00 2001 From: Andrew Powell Date: Wed, 23 Mar 2022 12:54:00 -0400 Subject: [PATCH 3/5] docs: remove ref to web stream. Co-authored-by: Matteo Collina --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 6739a5a1862..09e6b837cf8 100644 --- a/README.md +++ b/README.md @@ -67,7 +67,7 @@ console.log('trailers', trailers) ## Body Mixins -The `body` mixins are the most common way to format the request/response body from a [`ReadableStream`](https://streams.spec.whatwg.org/#readablestream). Mixins include: +The `body` mixins are the most common way to format the request/response body. Mixins include: - [`.formData()`](https://fetch.spec.whatwg.org/#dom-body-formdata) - [`.json()`](https://fetch.spec.whatwg.org/#dom-body-json) From b2adeb4925cd58611e7123fd20103de3ffe7a030 Mon Sep 17 00:00:00 2001 From: Andrew Powell Date: Wed, 6 Apr 2022 12:12:33 -0400 Subject: [PATCH 4/5] docs: remove stream clone info --- README.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/README.md b/README.md index 09e6b837cf8..8de125f51e0 100644 --- a/README.md +++ b/README.md @@ -95,8 +95,6 @@ _Note: Once a mixin has been called, the `ReadableStream` the body represents ca Should you need to access the `body` in plain-text after using a mixin, the best practice is to use the `.text()` mixin first, and manually parse the text to the desired format. -If the scenario arises where you absolutely must have a copy of the result stream, [`.clone`](https://fetch.spec.whatwg.org/#dom-request-clone) can be used _before_ using a `body` mixin, or [`body.pipeThrough`](https://streams.spec.whatwg.org/#readablestream-pipe-through) with a user-defined stream [§](https://web.dev/fetch-upload-streaming), such as [`TransformStream`]https://nodejs.org/api/stream.html#duplex-and-transform-streams. - For more information about their behavior, please reference the body mixin from the [Fetch Standard](https://fetch.spec.whatwg.org/#body-mixin). ## Common API Methods From bf5cb3228d5e63369e79f2f6eb28abc7b2ff6bb9 Mon Sep 17 00:00:00 2001 From: Robert Nagy Date: Wed, 6 Apr 2022 18:54:26 +0200 Subject: [PATCH 5/5] Update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 8de125f51e0..6ece3459fb1 100644 --- a/README.md +++ b/README.md @@ -91,7 +91,7 @@ console.log('data', await body.json()) console.log('trailers', trailers) ``` -_Note: Once a mixin has been called, the `ReadableStream` the body represents cannot be reused, thus calling additional mixins on `.body`, e.g. `.body.json(); .body.text()` will result in an error `TypeError: unusable` being thrown and returned through the `Promise` rejection._ +_Note: Once a mixin has been called then the body cannot be reused, thus calling additional mixins on `.body`, e.g. `.body.json(); .body.text()` will result in an error `TypeError: unusable` being thrown and returned through the `Promise` rejection._ Should you need to access the `body` in plain-text after using a mixin, the best practice is to use the `.text()` mixin first, and manually parse the text to the desired format.