@cordisjs/plugin-http

@cordisjs/http

Fetch-based HTTP client for Cordis.

Features

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

Usage

import { Context } from 'cordis'
import HTTP from '@cordisjs/plugin-http'

const ctx = new Context()
ctx.plugin(HTTP)

const data = await ctx.http.get('https://example.com')
const data = await ctx.http.post('https://example.com', body)
const { status, data } = await ctx.http('https://example.com', { method: 'GET' })

API

Instance Methods

http(url, config?)

interface HTTP {
  <T = any>(url: string | URL, config?: Config): Promise<Response<T>>
}

Send a request.

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

interface HTTP {
  get: Request1
  delete: Request1
  head(url: string, config?: Config): Promise<Headers>
}

interface Request1 {
  <K extends keyof ResponseTypes>(url: string, config: Config & { responseType: K }): Promise<ResponseTypes[K]>
  <T = any>(url: string, config?: Config): Promise<T>
}

Send a GET / DELETE / HEAD request.

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

interface HTTP {
  patch: Request2
  post: Request2
  put: Request2
}

interface Request2 {
  <K extends keyof ResponseTypes>(url: string, data: any, config: Config & { responseType: K }): Promise<ResponseTypes[K]>
  <T = any>(url: string, data?: any, config?: Config): Promise<T>
}

http.ws(url, config?)

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

Open a WebSocket connection.

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.

http.Error.is(error)

function is(error: any): error is Http.Error

Config

interface Config {
  baseUrl?: string
  method?: Method
  headers?: Record<string, string>
  redirect?: RequestRedirect
  keepAlive?: boolean
  params?: Record<string, any>
  data?: any
  responseType?: keyof ResponseTypes
  timeout?: number
}

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:

interface ResponseTypes {
  json: any
  text: string
  stream: ReadableStream<Uint8Array>
  blob: Blob
  formdata: FormData
  arraybuffer: ArrayBuffer
}

config.timeout

The request timeout in milliseconds.

config.proxyAgent

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

Response

interface Response<T> {
  status: number
  statusText: string
  headers: Headers
  data: T
}

response.status

See Response#status.

response.statusText

See Response#statusText.

response.headers

See Response#headers.

response.data

The decoded response body.