up-fetch

library2.6.0jsnpmunverified

Advanced fetch client builder for TypeScript with standard schema validation (Zod, Valibot, ArkType), automatic response parsing, retry, timeout, streaming, progress tracking, and lifecycle hooks. Version 2.6.0 (stable), actively maintained. Lightweight (1.6kB gzipped, no dependencies) and fully type-safe. Requires Node >=18 and ES2020. Differentiator: combines schema validation with familiar fetch API, supports multiple schema libraries via standard-schema, and offers comprehensive features like retry and progress without additional dependencies.

devops

npm install up-fetch

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · UP-FETCH

up-fetch

devopsjavascriptv2.6.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

✓ import { up } from 'up-fetch'

✗ const up = require('up-fetch')

ESM-only (no CommonJS) due to standard-schema dependency; use dynamic import if needed from CJS. Named export only (not default).

upFetch

✓ import { upFetch } from 'up-fetch'

✗ import upFetch from 'up-fetch'

Default import does not exist; must use named import. upFetch is the default export alias if you prefer, but it's the same as `up`.

type UpFetch

✓ import type { UpFetch } from 'up-fetch'

✗ import { UpFetch } from 'up-fetch'

Type import for TypeScript; avoid runtime usage.

Creates a fetch client with base URL and headers, fetches a user with Zod schema validation, returns parsed and typed response.

import { up } from 'up-fetch'; import { z } from 'zod'; const upfetch = up(fetch, { baseUrl: 'https://api.example.com', headers: { 'Content-Type': 'application/json' }, }); const UserSchema = z.object({ id: z.number(), name: z.string(), email: z.string().email(), }); async function getUser(id: number) { const user = await upfetch(`/users/${id}`, { schema: UserSchema, }); return user; // typed as { id: number; name: string; email: string } }

Debug

Known issues

breakingIn v2, the 'up' function signature changed. It now requires a fetch implementation as first argument (e.g., `up(fetch)`) instead of being pre-bound.

fix

Update code to pass `fetch` or a polyfill as the first argument: `up(fetch, options)` instead of `up(options)`.

affects: >=2.0.0

breakingThe 'schema' option no longer accepts raw Zod schemas directly in v2; it now requires a standard-schema compliant validator (Zod, Valibot, ArkType).

fix

Wrap Zod schemas as usual (they are compatible), but ensure you're using the correct import: `import { z } from 'zod'`. No change for Zod v3 users.

affects: >=2.0.0

deprecatedThe 'timeout' option in milliseconds has been deprecated in favor of 'signal' (AbortSignal.timeout) since v2.3.

fix

Use `signal: AbortSignal.timeout(5000)` instead of `timeout: 5000`.

affects: >=2.3.0

gotchaWhen using 'retry', the request body is not re-sent if the body is a stream or FormData. Only JSON-serializable bodies are retried.

fix

Avoid using retry with non-cloneable bodies like streams; pass a plain object or string instead.

affects: >=1.0.0

gotchaThe 'params' option automatically serializes objects into query string parameters, but nested objects are not deeply serialized (only top-level keys).

fix

Use a custom param serializer via `paramsSerializer` option for nested structures, or manually serialize with URLSearchParams.

affects: >=1.0.0

gotchaTypeScript type inference requires the exact 'schema' to be a known standard-schema validator; using 'as const' or 'z.infer' may lose type resolution.

fix

Pass the schema object directly (e.g., `schema: UserSchema`) without wrapping; avoid `as const` if not needed.

affects: >=2.0.0

Errors

Common errors & fixes

Error: fetch is not defined

Using up-fetch in an environment without native fetch (e.g., Node <18, older browsers, or when fetch polyfill is not imported).

fix

Install a fetch polyfill (e.g., 'undici' or 'cross-fetch') and pass it as first argument: `up(require('undici').fetch, ...)`.

TypeError: Cannot read properties of undefined (reading 'parse')

The 'schema' option is invalid or undefined; up-fetch attempts to parse response with unknown schema type.

fix

Ensure schema is a valid standard-schema validator (Zod, Valibot, ArkType) and imported correctly. Example: `import { z } from 'zod'; const schema = z.object({...})`.

Request failed with status code 4xx/5xx and response data is not returned

By default, up-fetch throws on non-2xx responses. No schema validation is applied on error responses.

fix

Use the 'errorAsValue' option or 'onError' hook to handle errors. For expected errors, set `errorAsValue: true` and check the result type.

TimeoutError: The operation was aborted

AbortSignal.timeout triggered before request completed. Node 18+ or browser AbortSignal.timeout is required.

fix

Use `signal: AbortSignal.timeout(ms)` on the request. Ensure environment supports AbortSignal.timeout (Node <18 may need polyfill).

ERR_REQUIRE_ESM: require() of ES Module not supported

Using require() to import up-fetch in a CommonJS context; up-fetch is ESM-only due to standard-schema dependency.

fix

Use dynamic import: `const { up } = await import('up-fetch')` or switch to ESM file (add 'type': 'module' to package.json).

Upgrade

Version history

2.6.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

9 hits · last 30 days

node

Amazon

Resources

githubhttps://github.com/L-Blondy/up-fetch ↗

packageup-fetch ↗

homepagehttps://github.com/L-Blondy/up-fetch#readme ↗