unjs/ofetch
github.com/unjs/ofetch ↗ · 32 files · 352 KB
ofetch A better fetch API. Works on node, browser, and workers.
Overview
ofetch is a TypeScript HTTP client library for applications using native fetch in Node.js, browsers, and workers. At commit 1dbc37fd1ceab832fc7c90cad81b1091c95ba563, its v2 alpha implementation adds response decoding, request serialization, lifecycle hooks, configurable retries, timeouts, and reusable defaults. Its central abstraction is a callable client with raw, native, and create variants; transport remains delegated to the host runtime or an injected fetch implementation.
System map
The system is a library consumed through an ESM package entrypoint. Seven source modules divide client creation, request execution, helpers, errors, and public types. State lives in factory closures and per-request contexts, while network behavior belongs to native or injected fetch. Build and CI configuration describe npm distribution and Node validation.
- The package identifies version 2.0.0-alpha.3, exports dist/index.mjs with dist/index.d.mts types, publishes only dist, and declares sideEffects false.
- src/index.ts re-exports runtime APIs through base.ts and public types, creates ofetch with its fetch wrapper, and exports $fetch as the same client.
- The entrypoint wrapper allows later global fetch patching when fetch existed at import time; otherwise it installs a rejecting fallback.
- createFetch captures the transport, owns nested error/raw functions, and attaches raw, native, and create methods to the callable client.
- fetch.ts orchestrates transport, utils.ts handles option resolution and hooks, utils.url.ts handles string URLs, and error.ts constructs contextual failures.
- The inspected request pipeline stores transient state in FetchContext and response._data; transport is the external output boundary rather than a repository persistence layer.
- pnpm 10.20.0 drives obuild, Vitest, ESLint, and Prettier scripts; release additionally invokes changelogen with alpha publishing and push flags.
- CI declares Ubuntu jobs across Node 20, 22, and 24; autofix separately runs lint:fix with read-only contents permission and a pinned autofix action.
Feature catalog
The user-facing surface is an HTTP client API with typed options and results. Automatic serialization and decoding remove common fetch boilerplate. Factories and hooks support shared application behavior, while retry and timeout options control failures. Raw responses, streams, and transport dispatchers expose lower-level capabilities.
- $fetch returns decoded _data, raw returns the augmented Response, and native delegates directly to the captured fetch transport.
- Response decoding supports JSON, text, blob, arrayBuffer, and stream; parseResponse supplies a custom synchronous parser of response text.
- Payload handling serializes eligible objects, preserves strings, selects URL-encoded serialization for the exact form content type, and supplies missing JSON headers.
- FormData and URLSearchParams bypass JSON classification, while web and Node stream bodies automatically receive duplex half unless explicitly configured.
- String requests support baseURL and query parameters; params remains a deprecated alias, with values merged from defaults and individual calls.
- Users can configure retry count, eligible status codes, fixed or contextual delay, timeout milliseconds, and suppression of HTTP status errors.
- Four lifecycle hooks accept functions or arrays, and create builds reusable clients with shared options and optional custom transport.
- Node transport customization includes an undici dispatcher option; documentation demonstrates ProxyAgent, SSE stream consumption, and FetchOptions augmentation.
Data flow
Inputs enter as FetchRequest and FetchOptions, then become a mutable FetchContext. Resolution merges shared defaults with call-specific headers and query values before hooks and normalization. Fetch produces a Response whose body becomes _data, which hooks can inspect before return or rejection. Retries carry transformed context back through the same pipeline.
- Each raw call allocates a context containing the original request, resolved options, and initially undefined response and error fields.
- Header resolution chooses explicit input headers over Request headers, then overlays them on defaults using Headers.set; it does not merge Request headers when explicit headers are supplied.
- Query precedence is default params, default query, input params, then input query; other options use shallow defaults/input spread.
- Method capitalization precedes onRequest; that hook can change the request or options before string URL transformation and body serialization.
- withQuery omits undefined values in new queries; in existing queries it deletes undefined keys, appends array elements, and replaces scalar values.
- Query normalization turns null into an empty string, numbers and booleans into strings, and objects into JSON; serialization uses URLSearchParams.
- Truthy timeout adds a generated AbortSignal, optionally combined with the caller signal, before resolved options cross the fetch boundary as RequestInit.
- Decoded data belongs to response._data; the normal client returns that value, while FetchError getters retain access to context and parsed error data.
Behavior traces
Source reading followed initialization, a JSON POST, and HTTP failure with retry through their complete call chains. Additional branches cover custom clients, streaming, and transport rejection. The same raw function owns preprocessing, fetch, decoding, hooks, and status handling. These are static execution traces rather than observed runs.
- Initialization proceeds index.ts → base.ts exports → entrypoint fetch wrapper → createFetch({ fetch }) → ofetch/$fetch aliases; unsupported global fetch uses the rejecting wrapper.
- A JSON POST proceeds $fetch → $fetchRaw → resolveFetchOptions → uppercase method → onRequest → withBase/withQuery → isJSONSerializable → JSON.stringify and default headers.
- After POST preparation, fetch runs → response type is selected → response text is parsed into _data → onResponse runs → status is checked → $fetch returns _data.
- A qualifying 408 response is decoded first → onResponse → onResponseError → onError → retry budget/status check → optional retryDelay → recursive $fetchRaw with retry decremented.
- When retry is unavailable or exhausted, onError calls createFetchError, optionally trims the V8 stack, and throws an error exposing URL, status, context, and decoded body.
- A transport rejection sets context.error → awaits onRequestError → enters onError; AbortError suppresses automatic retry only when timeout is absent.
- Client creation proceeds $fetch.create → shallow global/default merging → createFetch; later calls independently merge headers and query through resolveFetchOptions.
- An SSE response follows content-type detection → stream branch → response.body or _bodyInit assigned to _data → caller receives the stream and reads chunks itself.
Testing signals
Tests and CI were inspected, not executed; no passing result or measured coverage is established. The inspected Vitest suite primarily exercises native fetch against a local H3 server. Coverage spans serialization, decoding, headers, errors, hooks, retries, and timeout behavior, with some assertions narrower than their titles imply. This is a bounded inventory rather than exhaustive behavioral assurance.
- test/index.test.ts uses Vitest, a global fetch spy, and an H3 server bound to an ephemeral localhost port, with lifecycle setup and teardown.
- Decoding tests cover custom parseResponse, explicit JSON/blob/text/arrayBuffer selection, binary Blob detection, 204, and HEAD.
- Payload tests cover object/array serialization, header representations, string and Buffer bodies, web/Node streams, FormData, and URLSearchParams.
- Error/default tests assert 404 error context and parsed body, ignoreResponseError, header/query precedence, and Request header overrides.
- Retry-delay tests compare competing requests by Promise.race; abort tests assert rejection, and timeout tests assert relative completion and timeout cause fields rather than exact retry counts.
- Hook tests assert propagation of exceptions from all four hooks and callback counts for successful/error responses with single hooks and arrays.
- The inspected suite's final options test contacts jsonplaceholder; it does not establish SSE, proxy/TLS, malformed-JSON, fragment handling, or streamed-body replay coverage.
- Inspected configuration enables V8 coverage with src inclusion and text/clover/json reporters; CI declares Node 20/22/24 lint, build, coverage, and Codecov without a browser or worker job.
Risk map
The main review hotspots are URL rewriting, retry replay, abort composition, and error exposure. Several observable boundaries bypass normalized FetchError handling. Documentation also contains compatibility descriptions that differ from this alpha implementation. The following are source observations or explicitly marked hypotheses, not confirmed vulnerabilities.
- FetchError messages include the full request URL, and getters expose request/options/response; logging these objects can expose sensitive query or header data supplied by callers. (inferred)
- withBase uses a string prefix check and slash joining rather than origin-aware URL resolution; withQuery splits only at '?', with no explicit fragment handling.
- Explicit numeric retries can replay payload methods and reuse transformed bodies; consumed streams and non-idempotent operations therefore need targeted replay validation. (inferred)
- Retries retain context.options.signal, then compose another timeout signal; AbortError retry suppression is disabled whenever a timeout option is present.
- Serialization, timeout construction, JSON parsing, and most hooks lie outside the fetch try/catch, so their exceptions can bypass onRequestError and normalized retry/error handling.
- isJSONSerializable accesses value.buffer after checking typeof object; its earlier 't === null' condition cannot recognize null, although top-level falsy bodies skip the caller's payload branch.
- README names ufo for URL handling and describes response.ok-based failures, while current source uses local URL helpers and specifically rejects statuses 400–599.
- Network-sensitive examples include GH_TOKEN authentication and public gist creation; README demonstrates disabling TLS verification, and the release script publishes and pushes.
Extension points
Extension primarily happens through factories, typed options, and lifecycle hooks. Transport injection permits alternative fetch implementations without changing the request pipeline. Parsers and response mappings offer decoding customization, while dispatchers expose runtime-specific networking. Source-level helper tables define the narrower places where core behavior can be extended.
- CreateFetchOptions.fetch injects a fetch-compatible transport into createFetch, allowing tests or adapters to replace network execution.
- $fetch.create accepts shared defaults and custom global options, preserving inherited globals while new defaultOptions have final shallow precedence.
- FetchHooks defines four typed lifecycle interfaces; callHooks awaits array members sequentially using the same mutable context.
- parseResponse replaces JSON.parse after text consumption and takes precedence over responseType by selecting the JSON branch.
- ResponseMap and MappedResponseType centralize compile-time result mapping; adding response types requires coordinating these types with runtime decoding.
- retryStatusCodes and retryDelay permit application-specific retry selection and contextual delay calculation without modifying the built-in status set.
- FetchOptions can be augmented through TypeScript module declaration merging, with custom fields available to shared onRequest hooks.
- dispatcher and legacy agent options expose transport configuration; core payload-method and content-type sets are localized in utils.ts for source-level extensions.
Contributor handoff
Start with the public factory and raw pipeline, then follow the helper or type implicated by the task. Preserve option precedence and lifecycle ordering, which affect every client call. Tests and CI were inspected, not executed; their existence supplies investigation targets rather than passing evidence. The report inspected 17 source/example/test files plus documentation and configuration, but remains bounded rather than exhaustive.
- Read index.ts, base.ts, fetch.ts, and types.ts first to distinguish exported client aliases, runtime factories, and generic response contracts.
- Preserve explicit header replacement and query precedence when editing resolution; the defaults test exercises specialized merging rather than arbitrary recursive deep merging.
- Treat fetch.ts as a broad-impact edit boundary: onRequest precedes normalization, decoding precedes onResponse, and onResponse precedes status failure handling.
- Use local URL helper behavior as authority despite README's ufo references; query array append/delete rules and base prefix logic deserve explicit regression cases.
- Keep .ts import extensions and explicit public declarations consistent with strict NodeNext, isolatedDeclarations, and noEmit configuration.
- Preserve pnpm and repository lint conventions: ESLint extends unjs, Prettier specifies es5 trailing commas, and Renovate extends the shared unjs configuration.
- Tests and CI were inspected, not executed. In a future execution-authorized task, use focused Vitest cases first, then pnpm test/build as appropriate; account for the suite's external jsonplaceholder calls.
- Avoid running examples or release as routine validation: headers.mjs reads GH_TOKEN and posts a public gist, playground contacts httpstat.us, and release publishes an alpha package and pushes.
Languages
| Language | Files | Share of source |
|---|---|---|
| TypeScript | 11 | 58% |
| JavaScript | 8 | 42% |
| JSON | 3 | docs/config |
| Markdown | 3 | docs/config |
| YAML | 2 | docs/config |
Start reading here
Probable source entrypoint: src/index.ts — inferred from the directory tree and manifest, not the upstream docs.
Source roots
src/ (7 files)
Source layout — src/
| Path | Files |
|---|---|
src/base.ts | 1 |
src/error.ts | 1 |
src/fetch.ts | 1 |
src/index.ts | 1 |
src/types.ts | 1 |
src/utils.ts | 1 |
src/utils.url.ts | 1 |
Repository structure
| Top-level path | Files |
|---|---|
examples/ | 9 |
src/ | 7 |
.github/ | 3 |
test/ | 2 |
Docs found: README.md
Package
package.json — ofetch v2.0.0-alpha.3, 12 declared dependencies.
@types/node@vitest/coverage-v8automdchangelogeneslinteslint-config-unjsh3obuildprettiertypescriptundicivitest
CI & config entrypoints
README.md— Repository readmesrc/index.ts— TS entrypoint.github/workflows/autofix.yml— GitHub Actions workflow.github/workflows/ci.yml— GitHub Actions workflowpackage.json— npm scripts: build, dev, lint, lint:fix, prepack, release, test
Structural health signals
Average score 8.9/10 across 10 analyzed source files; 1 hotspot surfaced.
src/fetch.ts— 280 lines, score 5.9 (Deep nesting, Long function/block)src/types.ts— 166 lines, score 8.6 (Moderate churn, No adjacent test signal)src/utils.ts— 153 lines, score 8.6 (Moderate churn, No adjacent test signal)
These are deterministic review leads — size, churn, and structural signals — not proof of a bug in this project.
Recent history
1dbc37fd1cea2026-07-08 — chore: fix typos in readme (#608)9102908aeeca2026-06-28 — docs: fix license link in readme (#601)dfbe3ca4ef8a2026-03-11 — chore(deps): update autofix-ci/action digest to 7a166d7 (#540)d50a2047d4312026-02-04 — docs: add proxy configuration for Bun and Deno (#539)d61b2fcf77552025-10-31 — chore(deps): update all non-major dependencies (#509)