Undios

Fetch-based axios-style HTTP client.

"und" comes from undici, an HTTP/1.1 client officially supported by Node.js team.

"ios" comes from axios, a popular HTTP client for browser and Node.js.

Features

• Browser and Node.js support
• Proxy agents (HTTP / HTTPS / SOCKS)
• WebSocket

Basic Usage

1import Undios from '@cordisjs/plugin-http'
2
3const http = new Undios()
4
5const data = await http.get('https://example.com')
6const data = await http.post('https://example.com', body)
7const { status, data } = await http('https://example.com', { method: 'GET' })

API

Instance Methods

http(url, config?)

1interface HTTP {
2  <K extends keyof ResponseTypes>(url: string, config: Config & { responseType: K }): Promise<Response<ResponseTypes[K]>>
3  <T = any>(url: string | URL, config?: Config): Promise<Response<T>>
4}

Send a request.

http.[get|delete|head](url, config?)

1interface HTTP {
2  get: Request1
3  delete: Request1
4  head(url: string, config?: Config): Promise<Headers>
5}
6
7interface Request1 {
8  <K extends keyof ResponseTypes>(url: string, config: Config & { responseType: K }): Promise<ResponseTypes[K]>
9  <T = any>(url: string, config?: Config): Promise<T>
10}

Send a GET / DELETE / HEAD request.

http.[post|put|patch](url, data, config?)

1interface HTTP {
2  patch: Request2
3  post: Request2
4  put: Request2
5}
6
7interface Request2 {
8  <K extends keyof ResponseTypes>(url: string, data: any, config: Config & { responseType: K }): Promise<ResponseTypes[K]>
9  <T = any>(url: string, data?: any, config?: Config): Promise<T>
10}

http.ws(url, config?)

1interface HTTP {
2  ws(url: string | URL, config?: Config): WebSocket
3}

Open a WebSocket connection.

[!NOTE]

Currently we will use ws package to polyfill WebSocket in Node.js.

Once Node.js has a stable WebSocket API, we will switch to it.

Config

1interface Config {
2  baseURL?: string
3  method?: Method
4  headers?: Record<string, string>
5  redirect?: RequestRedirect
6  keepAlive?: boolean
7  params?: Record<string, any>
8  data?: any
9  responseType?: keyof ResponseTypes
10  timeout?: number
11}

config.baseURL

The base URL of the request. If it is set, the url will be resolved against it.

See URL#base.

config.method

See fetch#method.

config.headers

See fetch#headers.

config.redirect

See fetch#redirect.

config.keepAlive

See fetch#keepalive.

config.params

Additional query parameters. They will be appended to the URL.

config.data

The request body. Currently support below types:

• string
• URLSearchParams
• ArrayBuffer / ArrayBufferView
• Blob
• FormData
• Object (will be serialized to JSON)

config.responseType

Supported response types:

1interface ResponseTypes {
2  json: any
3  text: string
4  stream: ReadableStream<Uint8Array>
5  blob: Blob
6  formdata: FormData
7  arraybuffer: ArrayBuffer
8}

config.timeout

The request timeout in milliseconds.

config.proxyAgent

[!NOTE]

In order to use a proxy agent, you need to install @cordisjs/plugin-proxy-agent.

Response

1interface Response<T> {
2  status: number
3  statusText: string
4  headers: Headers
5  data: T
6}

response.status

See Response#status.

response.statusText

See Response#statusText.

response.headers

See Response#headers.

response.data

The decoded response body.

Static Methods

1class Undios {
2  constructor(config?: Config)
3}

Undios.Error.is(error)

1function is(error: any): error is Undios.Error