# OFexios
*a fork of [fexios](https://github.com/dragon-fish/fexios)*
类 Axios 语法的原生 unjs/ofetch API 请求封装库
unjs/ofetch based HTTP client with similar API to axios for browser and Node.js
~~ofetch + axios = ofexios~~ (Just a joke)
## 特色功能 Features
- [x] 🤯 auto-polyfills native fetch API (supports the Promise API)
- [x] 🤫 Method shortcuts (`fexios.post()`)
- [x] 🔗 Hooks (intercept request and response)
- [x] 😏 Automatic transform request and response data
- [x] 😏 Automatic transforms for JSON data
- [x] 🤩 Instances with custom defaults
- [x] 🫡 Instance extendable
- [x] 😍 Fricking tiny size: `index.mjs 9.52 kB │ gzip: 3.8 KB │ map: 38 KB`
## 安装 Installation
**包管理器 Using package manager**
```sh
# bun
bun add ofexios
# Deno
deno add ofexios
# npm
npm install ofexios
# Why not yarn
yarn add ofexios
# Or pnpm
pnpm add ofexios
```
Then import the library and enjoy:
```ts
import fexios, { createFexios, Fexios } from 'ofexios'
// Using directly
fexios.get('https://zh.moegirl.org.cn/api.php')
// With options
const fexios = createFexios(/* options */)
const fexios = new Fexios(/* options */)
const fexios = Fexios.create(/* options */)
```
**在浏览器中直接使用 Use directly in the browser**
- JS Module
```ts
import('https://unpkg.com/ofexios?module').then(({ createFexios }) => {
const fexios = createFexios(/* options */)
})
```
- Global variables
```html
```
## 兼容性 Compatibility
### Browser
Refer: https://developer.mozilla.org/docs/Web/API/Fetch_API
| Chrome | Edge | Firefox | Opera | Safari | Node.js |
| ------ | ---- | ------- | ----- | --------------- | ---------------------- |
| 42 | 14 | 39 | 29 | 10.1 (iOS 10.3) | ^16.15.0 \|\| >=18.0.0 |
\* Abort signal requires higher version.
Use [unfetch](https://github.com/developit/unfetch) for older browsers.
### Node.JS
See [unjs/node-fetch-native](https://github.com/unjs/node-fetch-native)
## 使用方法 Usage
You can find some sample code snippets [here](test/).
### new Fexios(configs: Partial\)
FexiosConfigs
```ts
export type FexiosConfigs = {
baseURL: string
query: Record | URLSearchParams
headers: Record | Headers
credentials: 'omit' | 'same-origin' | 'include'
responseType: 'json' | 'blob' | 'text'
}
```
Defaults
```ts
const DEFAULT_CONFIGS = {
baseURL: '',
credentials: 'same-origin',
headers: {
'content-type': 'application/json; charset=UTF-8',
},
query: {},
responseType: 'json',
}
```
### Fexios#request(config: FexiosRequestOptions)
`fexios.request(config): Promise>`
FexiosRequestOptions
```ts
export interface FexiosRequestOptions {
baseURL?: string
method?: FexiosMethods
credentials?: 'omit' | 'same-origin' | 'include'
headers?: Record | Headers
query?: Record | URLSearchParams
body?: Record | string | FormData | URLSearchParams
responseType?: 'json' | 'blob' | 'text'
}
```
**returns {FexiosFinalContext}**
```ts
export type FexiosFinalContext = Omit<
FexiosContext,
'rawResponse' | 'response' | 'data' | 'headers'
> & {
rawResponse: Response
response: FexiosResponse
headers: Headers
data: T
}
export type FexiosResponse = {
rawResponse: Response
ok: boolean
status: number
statusText: string
headers: Headers
isGood: boolean
data: T
}
```
And common request methods aliases:
- fexios.get(url[, config])
- fexios.delete(url[, config])
- fexios.head(url[, config])
- fexios.options(url[, config])
- fexios.post(url[, data[, config]])
- fexios.put(url[, data[, config]])
- fexios.patch(url[, data[, config]])
## 钩子 Hooks
You can modify context in hooks' callback then return it as a brand new context™.
Return `false` to abort request immediately.
```ts
export type FexiosHook = (context: C) => AwaitAble
export interface FexiosContext extends FexiosRequestOptions {
url: string // may changes after beforeInit
rawRequest?: Request // provide in beforeRequest
rawResponse?: Response // provide in afterRequest
response?: FexiosResponse // provide in afterRequest
data?: T // provide in afterRequest
}
```
Hooks example
```ts
const fexios = new Fexios()
fexios.on('beforeRequest', async (ctx) => {
const url = new URL(ctx.url)
if (url.searchParams.has('foo')) {
return false
} else {
url.searchParams.set('foo', 'bar')
ctx.url = '' + url
return ctx
}
})
```
### beforeInit
All context passed as is. You can do custom conversions here.
### beforeRequest
Pre-converted done.
At this time, `ctx.url` has been converted to final URL string. You cannot modify the `ctx.query` or `ctx.baseURL` to change `ctx.url`. Please modify `ctx.url` directly.
- `ctx.url` `{string}` full URL string converted from url, baseURL and ctx.query
- `ctx.query` `{Record}` merged from url, requestOptions, baseOptions
- `ctx.headers` `{Record}` merged from requestOptions, baseOptions
### afterBodyTransformed
JSON body has been transformed to JSON string. `Content-Type` header has been set to body's type.
- `ctx.body` `{string|URLSearchParams|FormData|Blob}`
### beforeActualFetch
The Request instance has been generated.
At this time, you cannot modify the `ctx.url`, `ctx.query`, `ctx.headers` or `ctx.body` (etc.) anymore. Unless you pass a brand new `Request` to replace `ctx.rawRequest`.
- `ctx.rawRequest` `{Request}`
### afterResponse
The `FexiosFinalContext` will be passed
### interceptors
Oh, this is mimicked from axios. Just sweet sugar.
```ts
// They are the same
fexios.on('beforeRequest', async (ctx) => {})
fexios.interceptors.request.use((ctx) => {})
// Bro, they're just the same
fexios.on('afterResponse', async (ctx) => {})
fexios.interceptors.response.use((ctx) => {})
```
---
> MIT License
>
> Copyright (c) 2025 Cyan Changes
>
> Originally created by:
> Copyright (c) 2023 机智的小鱼君 (A.K.A. Dragon-Fish)