https://github.com/cordiverse/http
Fetch-based axios-style HTTP client.
https://github.com/cordiverse/http
axios fetch http-client proxy-agent socks undici
Last synced: 8 months ago
JSON representation
Fetch-based axios-style HTTP client.
- Host: GitHub
- URL: https://github.com/cordiverse/http
- Owner: cordiverse
- License: mit
- Created: 2023-12-08T06:24:27.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2024-06-06T19:15:50.000Z (about 1 year ago)
- Last Synced: 2024-06-18T09:53:21.970Z (about 1 year ago)
- Topics: axios, fetch, http-client, proxy-agent, socks, undici
- Language: TypeScript
- Homepage:
- Size: 1.01 MB
- Stars: 9
- Watchers: 2
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 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
```ts
import Undios from '@cordisjs/plugin-http'
const http = new Undios()
const data = await http.get('https://example.com')
const data = await http.post('https://example.com', body)
const { status, data } = await http('https://example.com', { method: 'GET' })
```
## API
### Instance Methods
#### http(url, config?)
```ts
interface HTTP {
(url: string, config: Config & { responseType: K }): Promise>
(url: string | URL, config?: Config): Promise>
}
```
Send a request.
#### http.[get|delete|head](url, config?)
```ts
interface HTTP {
get: Request1
delete: Request1
head(url: string, config?: Config): Promise
}
interface Request1 {
(url: string, config: Config & { responseType: K }): Promise
(url: string, config?: Config): Promise
}
```
Send a GET / DELETE / HEAD request.
#### http.[post|put|patch](url, data, config?)
```ts
interface HTTP {
patch: Request2
post: Request2
put: Request2
}
interface Request2 {
(url: string, data: any, config: Config & { responseType: K }): Promise
(url: string, data?: any, config?: Config): Promise
}
```
#### http.ws(url, config?)
```ts
interface HTTP {
ws(url: string | URL, config?: Config): WebSocket
}
```
Open a WebSocket connection.
> [!NOTE]
>
> Currently we will use [`ws`](https://github.com/websockets/ws) package to polyfill [`WebSocket`](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket) in Node.js.
>
> Once Node.js has a stable WebSocket API, we will switch to it.
### Config
```ts
interface Config {
baseURL?: string
method?: Method
headers?: Record
redirect?: RequestRedirect
keepAlive?: boolean
params?: Record
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](https://developer.mozilla.org/en-US/docs/Web/API/URL/URL#base).
#### config.method
See [fetch#method](https://developer.mozilla.org/en-US/docs/Web/API/fetch#method).
#### config.headers
See [fetch#headers](https://developer.mozilla.org/en-US/docs/Web/API/fetch#headers).
#### config.redirect
See [fetch#redirect](https://developer.mozilla.org/en-US/docs/Web/API/fetch#redirect).
#### config.keepAlive
See [fetch#keepalive](https://developer.mozilla.org/en-US/docs/Web/API/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:
```ts
interface ResponseTypes {
json: any
text: string
stream: ReadableStream
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
```ts
interface Response {
status: number
statusText: string
headers: Headers
data: T
}
```
#### response.status
See [Response#status](https://developer.mozilla.org/en-US/docs/Web/API/Response/status).
#### response.statusText
See [Response#statusText](https://developer.mozilla.org/en-US/docs/Web/API/Response/statusText).
#### response.headers
See [Response#headers](https://developer.mozilla.org/en-US/docs/Web/API/Response/headers).
#### response.data
The decoded response body.
### Static Methods
```ts
class Undios {
constructor(config?: Config)
}
```
#### Undios.Error.is(error)
```ts
function is(error: any): error is Undios.Error
```