gem-hunter

upfetch - advanced fetch client builder

Table of Contents

➡️ Highlights

➡️ Agent Skill

npx skills add L-Blondy/up-fetch

➡️ QuickStart

npm i up-fetch

import { up } from 'up-fetch'

export const upfetch = up(fetch)

import { upfetch } from './upfetch'
import { z } from 'zod'

const user = await upfetch('https://a.b.c/users/1', {
   schema: z.object({
      id: z.number(),
      name: z.string(),
      avatar: z.string().url(),
   }),
})

➡️ Key Features

✔️ Request Configuration

const upfetch = up(fetch, () => ({
   baseUrl: 'https://a.b.c',
   timeout: 30000,
}))

✔️ Simple Query Parameters

fetch(
   `https://api.example.com/todos?search=${search}&skip=${skip}&take=${take}`,
)

upfetch('/todos', {
   params: { search, skip, take },
})

✔️ Automatic Body Handling

fetch('https://api.example.com/todos', {
   method: 'POST',
   headers: { 'Content-Type': 'application/json' },
   body: JSON.stringify({ title: 'New Todo' }),
})

upfetch('/todos', {
   method: 'POST',
   body: { title: 'New Todo' },
})

✔️ Schema Validation

import { z } from 'zod'

const posts = await upfetch('/posts/1', {
   schema: z.object({
      id: z.number(),
      title: z.string(),
   }),
})

import { object, string, number } from 'valibot'

const posts = await upfetch('/posts/1', {
   schema: object({
      id: number(),
      title: string(),
   }),
})

✔️ Lifecycle Hooks

const upfetch = up(fetch, () => ({
   onRequest: (options) => {
      // Called before the request is made, options might be mutated here
   },
   onSuccess: (data, options) => {
      // Called when the request successfully completes
   },
   onError: (error, options) => {
      // Called when the request fails
   },
}))

✔️ Timeout

upfetch('/todos', {
   timeout: 3000,
})

const upfetch = up(fetch, () => ({
   timeout: 5000,
}))

✔️ Retry

const upfetch = up(fetch, () => ({
   retry: {
      attempts: 3,
      delay: 1000,
   },
}))

await upfetch('/api/data', {
   method: 'DELETE',
   retry: {
      attempts: 2,
   },
})

const upfetch = up(fetch, () => ({
   retry: {
      attempts: 3,
      delay: (ctx) => ctx.attempt ** 2 * 1000,
   },
}))

const upfetch = up(fetch, () => ({
   retry: {
      // One retry for GET requests, no retries for other methods:
      attempts: (ctx) => (ctx.request.method === 'GET' ? 1 : 0),
      delay: 1000,
   },
}))

const upfetch = up(fetch, () => ({
   retry: {
      when({ response }) {
         if (!response) return false
         return [408, 413, 429, 500, 502, 503, 504].includes(response.status)
      },
      attempts: 1,
      delay: 1000,
   },
}))

const upfetch = up(fetch, () => ({
   retry: {
      attempts: 2,
      delay: 1000,
      when: (ctx) => {
         // Retry on timeout errors
         if (ctx.error) return ctx.error.name === 'TimeoutError'
         // Retry on 429 server errors
         if (ctx.response) return ctx.response.status === 429
         return false
      },
   },
}))

✔️ Error Handling

👉 ResponseError

import { isResponseError } from 'up-fetch'

try {
   await upfetch('/todos/1')
} catch (error) {
   if (isResponseError(error)) {
      console.log(error.status)
   }
}

👉 ResponseValidationError

import { isResponseValidationError } from 'up-fetch'

try {
   await upfetch('/todos/1', { schema: todoSchema })
} catch (error) {
   if (isResponseValidationError(error)) {
      console.log(error.issues)
   }
}

➡️ Usage

✔️ Authentication

const upfetch = up(fetch, () => ({
   headers: { Authorization: localStorage.getItem('bearer-token') },
}))

const upfetch = up(fetch, async () => ({
   headers: { Authorization: await getToken() },
}))

✔️ Delete a default option

upfetch('/todos', {
   signal: undefined,
})

upfetch('/todos', {
   headers: { Authorization: undefined },
})

✔️ FormData

const form = document.querySelector('#my-form')

upfetch('/todos', {
   method: 'POST',
   body: new FormData(form),
})

import { serialize } from 'object-to-formdata'

const upfetch = up(fetch, () => ({
   serializeBody: (body) => serialize(body),
}))

upfetch('https://a.b.c', {
   method: 'POST',
   body: { file: new File(['foo'], 'foo.txt') },
})

✔️ Multiple fetch clients

const fetchMovie = up(fetch, () => ({
   baseUrl: 'https://api.themoviedb.org',
   headers: {
      accept: 'application/json',
      Authorization: `Bearer ${process.env.API_KEY}`,
   },
}))

const fetchFile = up(fetch, () => ({
   parseResponse: async (res) => {
      const name = res.url.split('/').at(-1) ?? ''
      const type = res.headers.get('content-type') ?? ''
      return new File([await res.blob()], name, { type })
   },
}))

✔️ Streaming

const decoder = new TextDecoder()

upfetch('/ai-chatbot', {
   onResponseStreaming: ({ chunk }) => {
      const text = decoder.decode(chunk, { stream: true })
      console.log(text)
   },
})

✔️ Progress

👉 Upload progress:

upfetch('/upload', {
   method: 'POST',
   body: new File(['large file'], 'foo.txt'),
   onRequestStreaming: ({ transferredBytes, totalBytes }) => {
      console.log(`Progress: ${transferredBytes} / ${totalBytes}`)
   },
})

👉 Download progress:

upfetch('/download', {
   onResponseStreaming: ({
      transferredBytes,
      totalBytes = transferredBytes,
   }) => {
      console.log(`Progress: ${transferredBytes} / ${totalBytes}`)
   },
})

➡️ Advanced Usage

✔️ Error as value

const upfetch = up(fetch, () => ({
   reject: () => false,
   parseResponse: async (response) => {
      const json = await response.json()
      return response.ok
         ? { data: json, error: null }
         : { data: null, error: json }
   },
}))

const { data, error } = await upfetch('/users/1')

✔️ Custom response parsing

const upfetch = up(fetch, () => ({
   parseResponse: (response) => response.blob(),
}))

✔️ Custom response errors

const upfetch = up(fetch, () => ({
   parseRejected: async (response) => {
      const data = await response.json()
      const status = response.status
      // custom error message
      const message = `Request failed with status ${status}: ${JSON.stringify(data)}`
      // you can return a custom error class as well
      return new ResponseError({ message, status, data })
   },
}))

✔️ Custom params serialization

import queryString from 'query-string'

const upfetch = up(fetch, () => ({
   serializeParams: (params) => queryString.stringify(params),
}))

✔️ Custom body serialization

// Restrict the body type to Record<string, any> and serialize it
const upfetch = up(fetch, () => ({
   serializeBody: (body: Record<string, any>) => JSON.stringify(body),
}))

// ❌ type error: the body is not a Record<string, any>
upfetch('https://a.b.c/todos', {
   method: 'POST',
   body: [['title', 'New Todo']],
})

// ✅ works fine with Record<string, any>
upfetch('https://a.b.c/todos', {
   method: 'POST',
   body: { title: 'New Todo' },
})

import SuperJSON from 'superjson'

const upfetch = up(fetch, () => ({
   serializeBody: SuperJSON.stringify,
}))

✔️ Defaults based on the request

const upfetch = up(fetch, (input, options) => ({
   baseUrl: 'https://example.com/',
   // Add authentication only for protected routes
   headers: {
      Authorization:
         typeof input === 'string' && input.startsWith('/api/protected/')
            ? `Bearer ${getToken()}`
            : undefined,
   },
   // Add tracking params only for public endpoints
   params: {
      trackingId:
         typeof input === 'string' && input.startsWith('/public/')
            ? crypto.randomUUID()
            : undefined,
   },
   // Increase timeout for long-running operations
   timeout:
      typeof input === 'string' && input.startsWith('/export/') ? 30000 : 5000,
}))

➡️ API Reference

up(fetch, getDefaultOptions?)

function up(
   fetchFn: typeof globalThis.fetch,
   getDefaultOptions?: (
      input: RequestInit,
      options: FetcherOptions,
   ) => DefaultOptions | Promise<DefaultOptions>,
): UpFetch

upfetch(url, options?)

function upfetch(
   url: string | URL | Request,
   options?: FetcherOptions,
): Promise<any>

RetryOptions

isResponseError(error)

isResponseValidationError(error)

isJsonifiable(value)

➡️ Feature Comparison

➡️ Environment Support