Response Types

Type definitions for responses and response handling

Overview

ofetch provides several type definitions for handling different response formats and type-safe response parsing.

ResponseType

The available response types that ofetch can parse.

export type ResponseType = keyof ResponseMap | "json";

Available Types:

• "json" - Parse response as JSON (default)
• "text" - Return response as text string
• "blob" - Return response as Blob
• "arrayBuffer" - Return response as ArrayBuffer
• "stream" - Return response as ReadableStream

Example:

const text = await ofetch<string>('/file.txt', {
  responseType: 'text'
})

const blob = await ofetch<Blob>('/image.png', {
  responseType: 'blob'
})

const buffer = await ofetch<ArrayBuffer>('/data.bin', {
  responseType: 'arrayBuffer'
})

const stream = await ofetch<ReadableStream>('/large-file', {
  responseType: 'stream'
})

ResponseMap

Maps response type strings to their corresponding TypeScript types.

export interface ResponseMap {
  blob: Blob;
  text: string;
  arrayBuffer: ArrayBuffer;
  stream: ReadableStream<Uint8Array>;
}

This interface is used internally for type inference when you specify a responseType.

MappedResponseType

Utility type that maps a response type string to its corresponding TypeScript type.

export type MappedResponseType<
  R extends ResponseType,
  JsonType = any,
> = R extends keyof ResponseMap ? ResponseMap[R] : JsonType;

Type Parameters:

R · ResponseType · required

The response type string

JsonType · any · default: "any"

The TypeScript type to use for JSON responses

Example:

// MappedResponseType<"text"> = string
// MappedResponseType<"blob"> = Blob
// MappedResponseType<"json", User> = User

const user = await ofetch<User, 'json'>('/api/user')
// Type of user: User

const text = await ofetch<string, 'text'>('/file.txt', {
  responseType: 'text'
})
// Type of text: string

FetchResponse

Extends the standard Response interface with an additional _data property containing the parsed response data.

export interface FetchResponse<T> extends Response {
  _data?: T;
}

Properties:

Inherits all properties from the standard Response interface:

status · number

HTTP status code (e.g., 200, 404)

statusText · string

HTTP status message (e.g., “OK”, “Not Found”)

ok · boolean

True if status is in the range 200-299

headers · Headers

Response headers

url · string

Final URL of the response (after redirects)

redirected · boolean

True if the response is the result of a redirect

type · ResponseType

Type of response (basic, cors, error, etc.)

body · ReadableStream | null

Response body stream

Additional Property:

_data · T | undefined

Parsed response data. The type depends on the responseType option.

Example:

const response = await ofetch.raw<User[]>('/api/users')

console.log(response.status) // 200
console.log(response.ok) // true
console.log(response._data) // User[] - parsed JSON data
console.log(response.headers.get('content-type')) // application/json

FetchContext

Context object passed to lifecycle hooks containing request, options, response, and error information.

export interface FetchContext<T = any, R extends ResponseType = ResponseType> {
  request: FetchRequest;
  options: ResolvedFetchOptions<R>;
  response?: FetchResponse<T>;
  error?: Error;
}

Properties:

request · FetchRequest · required

The request URL string or Request object

options · ResolvedFetchOptions<R> · required

Resolved fetch options with headers as a Headers object. See FetchOptions.

response · FetchResponse<T> | undefined

The response object if available. Present in onResponse and onResponseError hooks.

error · Error | undefined

Error object if an error occurred. Present in onRequestError hook.

Example:

await ofetch('/api/users', {
  onRequest({ request, options }) {
    console.log('Request:', request)
    console.log('Headers:', options.headers)
  },
  onResponse({ response }) {
    console.log('Status:', response?.status)
    console.log('Data:', response?._data)
  },
  onRequestError({ error }) {
    console.error('Error:', error?.message)
  }
})

ResolvedFetchOptions

FetchOptions with headers guaranteed to be a Headers object.

export interface ResolvedFetchOptions<
  R extends ResponseType = ResponseType,
  T = any,
> extends FetchOptions<R, T> {
  headers: Headers;
}

This is the type used in the FetchContext’s options property, ensuring headers are always in a consistent format.

Type Parameters

T · any · default: "any"

The expected type of the response data

R · ResponseType · default: "ResponseType"

The response type: "json", "text", "blob", "arrayBuffer", or "stream"

Related

• FetchOptions - Request configuration options
• FetchHooks - Lifecycle hooks that use FetchContext
• ofetch.raw() - Returns FetchResponse