Package Exports

@cordisjs/plugin-http
@cordisjs/plugin-http/lib/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@cordisjs/plugin-http) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

@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.

[!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.

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.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

[!NOTE]

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.

@cordisjs/plugin-http