Skip to content

docs: clarify ofetch.raw response body access #614

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.

Sign up for GitHub

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

Open
vittorioexp wants to merge 1 commit into
base: main
Choose a base branch
from
+16 −3
Open

docs: clarify ofetch.raw response body access #614

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 16 additions & 3 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -272,16 +272,29 @@ await ofetch("/movies", {

## 🍣 Access to Raw Response

If you need to access raw response (for headers, etc), you can use `ofetch.raw`:
If you need to access response headers or status while still using `ofetch` parsing, use `ofetch.raw`:

```js
const response = await ofetch.raw("/sushi");

// response._data
// response.status
// response.headers
// ...
// response._data
```

`ofetch.raw` returns the native `Response` object, but `ofetch` still reads and parses the body for you. The parsed result is available on `response._data` (the same value returned by `ofetch()`).

Because the body stream is consumed during parsing, calling `response.json()`, `response.blob()`, `response.text()`, or similar methods on the returned response will throw a "body stream already read" error. Read the parsed body from `response._data` instead:

```js
const response = await ofetch.raw("/favicon.png", { responseType: "blob" });

const blob = response._data; // Blob
// await response.blob() // throws: body already consumed
Comment on lines +287 to +293

@coderabbitai coderabbitai Bot Jul 22, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
set -euo pipefail

# Locate the relevant README section and implementation around response handling.
rg -n 'responseType|_data|body already read|stream' README.md src test . -g '!node_modules' -g '!dist' -g '!build' || true

# Show the README excerpt around the cited lines.
sed -n '270,310p' README.md

# Find the core implementation files that assign _data / handle stream responses.
fd -a 'ofetch' .
fd -a 'fetch' src . || true

Repository: unjs/ofetch

Length of output: 8563

🏁 Script executed:

#!/bin/bash
set -euo pipefail

# Narrow the implementation search to likely source files if present.
rg -n '_data|responseType|stream|body consumed|body already read' . \
  -g '!node_modules' -g '!dist' -g '!build' -g '!coverage' \
  -g '!*.md' || true

Repository: unjs/ofetch

Length of output: 1867

🏁 Script executed:

#!/bin/bash
set -euo pipefail

sed -n '200,240p' src/fetch.ts
printf '\n---\n'
sed -n '280,320p' README.md

Repository: unjs/ofetch

Length of output: 2843

🏁 Script executed:

#!/bin/bash
set -euo pipefail

# Inspect the responseType handling and any README mention of stream behavior.
sed -n '200,240p' src/fetch.ts
printf '\n---\n'
sed -n '280,320p' README.md

Repository: unjs/ofetch

Length of output: 2843

Mention the stream exception. responseType: "stream" leaves the body available on response._data without consuming it, so this warning should apply only to response types that actually read the body (json, blob, text, arrayBuffer, etc.).

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@README.md` around lines 287 - 293, Update the README warning to exclude
responseType: "stream": clarify that body-consuming response types such as json,
blob, text, and arrayBuffer consume the stream and require reading
response._data, while stream leaves the body available without consuming it.

```

In `onResponseError` hooks, use `error.data` to access the parsed error response body.

@coderabbitai coderabbitai Bot Jul 22, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
set -euo pipefail

printf '%s\n' '--- README excerpt around line 296 ---'
sed -n '280,310p' README.md

printf '\n%s\n' '--- search for onResponseError / FetchError.data / response._data ---'
rg -n "onResponseError|FetchError\.data|response\._data|_data" README.md . --glob '!**/node_modules/**' --glob '!**/dist/**' --glob '!**/build/**'

Repository: unjs/ofetch

Length of output: 5291

🏁 Script executed:

#!/bin/bash
set -euo pipefail

printf '%s\n' '--- src/fetch.ts relevant section ---'
sed -n '200,270p' src/fetch.ts

printf '\n%s\n' '--- src/error.ts relevant section ---'
sed -n '1,140p' src/error.ts

printf '\n%s\n' '--- README onResponseError section ---'
sed -n '205,225p' README.md

Repository: unjs/ofetch

Length of output: 4852

🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo '--- src/fetch.ts onResponseError and parsing order ---'
nl -ba src/fetch.ts | sed -n '210,265p'

echo
echo '--- src/error.ts data aliasing ---'
nl -ba src/error.ts | sed -n '1,120p'

echo
echo '--- src/types.ts onResponseError type ---'
nl -ba src/types.ts | sed -n '100,150p'

Repository: unjs/ofetch

Length of output: 244

Use response._data in onResponseError
onResponseError receives { request, response, options }, so error.data is out of scope here. Update the example to ({ response }) => response._data; keep error.data for the caught FetchError.

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@README.md` at line 296, Update the README onResponseError hook example to
destructure response and access its parsed body through response._data instead
of error.data. Preserve error.data usage in the separate caught FetchError
example.


## 🌿 Using Native Fetch

As a shortcut, you can use `ofetch.native` that provides native `fetch` API
Expand Down