Skip to content

Commit 29a6e29

Browse files
dragon-fishdragon-fish
committed
docs: update README to v6
1 parent cc04202 commit 29a6e29

2 files changed

Lines changed: 136 additions & 74 deletions

File tree

‎README.md‎

Lines changed: 68 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -124,7 +124,7 @@ export interface FexiosConfigs {
124124
credentials?: RequestInit['credentials']
125125
cache?: RequestInit['cache']
126126
mode?: RequestInit['mode']
127-
responseType?: 'json' | 'blob' | 'text' | 'stream' | 'arrayBuffer'
127+
responseType?: 'json' | 'text' | 'form' | 'blob' | 'arrayBuffer'
128128
fetch?: FetchLike
129129
}
130130
```
@@ -138,12 +138,14 @@ export interface FexiosConfigs {
138138
```ts
139139
const DEFAULT_CONFIGS = {
140140
baseURL: '',
141-
credentials: 'same-origin',
142-
headers: {
143-
'content-type': 'application/json; charset=UTF-8',
144-
},
141+
timeout: 0,
142+
credentials: undefined,
143+
headers: {},
145144
query: {},
146-
responseType: 'json',
145+
responseType: undefined,
146+
shouldThrow(response) {
147+
return !response.ok
148+
},
147149
fetch: globalThis.fetch,
148150
}
149151
```
@@ -179,14 +181,31 @@ export interface FexiosRequestOptions extends Omit<FexiosConfigs, 'headers'> {
179181
**returns {FexiosFinalContext}**
180182

181183
```ts
182-
export type FexiosFinalContext<T = any> = Omit<
183-
FexiosContext<T>,
184-
'rawResponse' | 'response' | 'data' | 'headers'
185-
> & {
186-
rawResponse: Response
184+
export type FexiosFinalContext<T = any> = {
185+
request: {
186+
url: string
187+
method?: string
188+
headers: Headers | Record<string, any>
189+
query: Record<string, any> | URLSearchParams
190+
body?: any
191+
rawRequest: Request
192+
// ... other request configs ...
193+
}
194+
runtime: {
195+
abortController?: AbortController
196+
onProgress?: (progress: number, buffer?: Uint8Array) => void
197+
customEnv?: any
198+
}
199+
/** Parsed response wrapper */
187200
response: IFexiosResponse<T>
188-
headers: Headers
189-
data: T
201+
/** Unread original Response */
202+
rawResponse: Response
203+
/** Shortcut getters */
204+
readonly headers: Headers
205+
readonly data: T
206+
readonly responseType: 'json' | 'text' | 'form' | 'blob' | 'arrayBuffer'
207+
readonly url: string
208+
readonly rawRequest: Request
190209
}
191210
export interface IFexiosResponse<T = any> {
192211
ok: boolean
@@ -195,6 +214,7 @@ export interface IFexiosResponse<T = any> {
195214
headers: Headers
196215
rawResponse: Response
197216
data: T
217+
responseType: 'json' | 'text' | 'form' | 'blob' | 'arrayBuffer'
198218
}
199219
```
200220

@@ -220,20 +240,20 @@ Fexios uses a simplified 2-stage merge strategy:
220240

221241
This happens only ONCE, immediately after the `beforeInit` hook.
222242

223-
- **URL**: `ctx.url` is resolved against `defaults.baseURL`.
224-
- Search params from `defaults.baseURL` are merged into `ctx.url`.
225-
- Priority: `ctx.url` search params > `defaults.baseURL` search params.
226-
- **Query**: `defaults.query` is merged into `ctx.query`.
227-
- Priority: `ctx.query` > `defaults.query`.
228-
- **Headers**: `defaults.headers` is merged into `ctx.headers`.
229-
- Priority: `ctx.headers` > `defaults.headers`.
243+
- **URL**: `ctx.request.url` is resolved against `defaults.baseURL`.
244+
- Search params from `defaults.baseURL` are merged into `ctx.request.url`.
245+
- Priority: `ctx.request.url` search params > `defaults.baseURL` search params.
246+
- **Query**: `defaults.query` is merged into `ctx.request.query`.
247+
- Priority: `ctx.request.query` > `defaults.query`.
248+
- **Headers**: `defaults.headers` is merged into `ctx.request.headers`.
249+
- Priority: `ctx.request.headers` > `defaults.headers`.
230250

231251
#### 2. Finalize Request (Before `beforeActualFetch`)
232252

233253
This happens when constructing the native `Request` object.
234254

235-
- **Query**: `ctx.query` is merged into the final URL's search params.
236-
- Priority: `ctx.query` > URL search params (from step 1 or modified by hooks).
255+
- **Query**: `ctx.request.query` is merged into the final URL's search params.
256+
- Priority: `ctx.request.query` > URL search params (from step 1 or modified by hooks).
237257
- **Headers**: Final headers are built.
238258

239259
### Merge Rules
@@ -244,9 +264,9 @@ This happens when constructing the native `Request` object.
244264

245265
### Note on Hooks
246266

247-
- Modifications to `ctx.url` in hooks (e.g. `beforeRequest`) will **NOT** be parsed into `ctx.query`. They are treated as separate entities until the final merge.
248-
- If you replace `ctx.url` in a hook, you lose the original URL search params unless you manually preserve them.
249-
- To modify query parameters reliably in hooks, prefer operating on `ctx.query`.
267+
- Modifications to `ctx.request.url` in hooks (e.g. `beforeRequest`) will **NOT** be parsed into `ctx.request.query`. They are treated as separate entities until the final merge.
268+
- If you replace `ctx.request.url` in a hook, you lose the original URL search params unless you manually preserve them.
269+
- To modify query parameters reliably in hooks, prefer operating on `ctx.request.query`.
250270

251271
## Hooks
252272

@@ -257,13 +277,23 @@ Return `false` to abort request immediately.
257277
```ts
258278
export type FexiosHook<C = unknown> = (
259279
context: C
260-
) => AwaitAble<C | void | false>
261-
export interface FexiosContext<T = any> extends FexiosRequestOptions {
262-
url: string // may changes after beforeInit
263-
rawRequest?: Request // provide in beforeRequest
264-
rawResponse?: Response // provide in afterRequest
265-
response?: IFexiosResponse // provide in afterRequest
266-
data?: T // provide in afterRequest
280+
) => AwaitAble<C | void | false | Response>
281+
export interface FexiosContext<T = any> {
282+
request: {
283+
url: string // may change after beforeInit
284+
query: Record<string, any> | URLSearchParams
285+
headers: Headers | Record<string, any>
286+
body?: any
287+
rawRequest?: Request // available in beforeActualFetch
288+
}
289+
runtime: {
290+
abortController?: AbortController
291+
onProgress?: (progress: number, buffer?: Uint8Array) => void
292+
customEnv?: any
293+
}
294+
rawResponse?: Response // available in afterRawResponse
295+
response?: IFexiosResponse<T> // available in afterResponse
296+
// NOTE: legacy aliases like ctx.url / ctx.query may exist but are deprecated.
267297
}
268298
```
269299

@@ -275,11 +305,12 @@ export interface FexiosContext<T = any> extends FexiosRequestOptions {
275305
const fexios = new Fexios()
276306

277307
fexios.on('beforeRequest', async (ctx) => {
278-
ctx.headers.authorization = localStorage.getItem('token')
279-
if (ctx.query.foo === 'bar') {
308+
;(ctx.request.headers as any).authorization = localStorage.getItem('token')
309+
const q = ctx.request.query as any
310+
if (q.foo === 'bar') {
280311
return false
281312
} else {
282-
ctx.query.foo = 'baz'
313+
q.foo = 'baz'
283314
return ctx
284315
}
285316
return ctx
@@ -304,11 +335,11 @@ JSON body has been transformed to JSON string. `Content-Type` header has been se
304335

305336
### beforeActualFetch
306337

307-
- `ctx.rawRequest`: `{Request}` now available.
338+
- `ctx.request.rawRequest`: `{Request}` now available.
308339

309340
The Request instance has been generated.
310341

311-
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`.
342+
At this time, you cannot modify `ctx.request.url`, `ctx.request.query`, `ctx.request.headers` or `ctx.request.body` (etc.) anymore, unless you pass a brand new `Request` to replace `ctx.request.rawRequest`.
312343

313344
### afterResponse
314345

‎README.zh_CN.md‎

Lines changed: 68 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -109,7 +109,7 @@ export interface FexiosConfigs {
109109
credentials?: RequestInit['credentials']
110110
cache?: RequestInit['cache']
111111
mode?: RequestInit['mode']
112-
responseType?: 'json' | 'blob' | 'text' | 'stream' | 'arrayBuffer'
112+
responseType?: 'json' | 'text' | 'form' | 'blob' | 'arrayBuffer'
113113
fetch?: FetchLike
114114
}
115115
```
@@ -123,12 +123,14 @@ export interface FexiosConfigs {
123123
```ts
124124
const DEFAULT_CONFIGS = {
125125
baseURL: '',
126-
credentials: 'same-origin',
127-
headers: {
128-
'content-type': 'application/json; charset=UTF-8',
129-
},
126+
timeout: 0,
127+
credentials: undefined,
128+
headers: {},
130129
query: {},
131-
responseType: 'json',
130+
responseType: undefined,
131+
shouldThrow(response) {
132+
return !response.ok
133+
},
132134
fetch: globalThis.fetch,
133135
}
134136
```
@@ -164,14 +166,31 @@ export interface FexiosRequestOptions extends Omit<FexiosConfigs, 'headers'> {
164166
**返回 {FexiosFinalContext}**
165167

166168
```ts
167-
export type FexiosFinalContext<T = any> = Omit<
168-
FexiosContext<T>,
169-
'rawResponse' | 'response' | 'data' | 'headers'
170-
> & {
171-
rawResponse: Response
169+
export type FexiosFinalContext<T = any> = {
170+
request: {
171+
url: string
172+
method?: string
173+
headers: Headers | Record<string, any>
174+
query: Record<string, any> | URLSearchParams
175+
body?: any
176+
rawRequest: Request
177+
// ... 其他请求配置 ...
178+
}
179+
runtime: {
180+
abortController?: AbortController
181+
onProgress?: (progress: number, buffer?: Uint8Array) => void
182+
customEnv?: any
183+
}
184+
/** 解析后的响应包装对象 */
172185
response: IFexiosResponse<T>
173-
headers: Headers
174-
data: T
186+
/** 未读取的原始 Response */
187+
rawResponse: Response
188+
/** 常用快捷 getter */
189+
readonly headers: Headers
190+
readonly data: T
191+
readonly responseType: 'json' | 'text' | 'form' | 'blob' | 'arrayBuffer'
192+
readonly url: string
193+
readonly rawRequest: Request
175194
}
176195
export interface IFexiosResponse<T = any> {
177196
ok: boolean
@@ -180,6 +199,7 @@ export interface IFexiosResponse<T = any> {
180199
headers: Headers
181200
rawResponse: Response
182201
data: T
202+
responseType: 'json' | 'text' | 'form' | 'blob' | 'arrayBuffer'
183203
}
184204
```
185205

@@ -205,20 +225,20 @@ Fexios 采用简化的两阶段合并策略：
205225

206226
此步骤仅在 `beforeInit` 钩子之后执行**一次**。
207227

208-
- **URL**: 将 `ctx.url` 基于 `defaults.baseURL` 解析为完整路径。
209-
- `defaults.baseURL` 中的 search params 会合并入 `ctx.url`。
210-
- 优先级：`ctx.url` search params > `defaults.baseURL` search params。
211-
- **Query**: `defaults.query` 合并入 `ctx.query`。
212-
- 优先级：`ctx.query` > `defaults.query`。
213-
- **Headers**: `defaults.headers` 合并入 `ctx.headers`。
214-
- 优先级：`ctx.headers` > `defaults.headers`。
228+
- **URL**: 将 `ctx.request.url` 基于 `defaults.baseURL` 解析为完整路径。
229+
- `defaults.baseURL` 中的 search params 会合并入 `ctx.request.url`。
230+
- 优先级：`ctx.request.url` search params > `defaults.baseURL` search params。
231+
- **Query**: `defaults.query` 合并入 `ctx.request.query`。
232+
- 优先级：`ctx.request.query` > `defaults.query`。
233+
- **Headers**: `defaults.headers` 合并入 `ctx.request.headers`。
234+
- 优先级：`ctx.request.headers` > `defaults.headers`。
215235

216236
#### 2. 生成最终请求（Finalize Request）
217237

218238
此步骤在构建原生 `Request` 对象前（即 `beforeActualFetch` 之前）执行。
219239

220-
- **Query**: 将 `ctx.query` 合并入最终 URL 的 search params。
221-
- 优先级：`ctx.query` > URL search params（来自第一步或被钩子修改后的 URL）。
240+
- **Query**: 将 `ctx.request.query` 合并入最终 URL 的 search params。
241+
- 优先级：`ctx.request.query` > URL search params（来自第一步或被钩子修改后的 URL）。
222242
- **Headers**: 构建最终的 Headers 对象。
223243

224244
### 合并规则
@@ -229,9 +249,9 @@ Fexios 采用简化的两阶段合并策略：
229249

230250
### 钩子注意事项
231251

232-
- 在钩子（如 `beforeRequest`）中修改 `ctx.url` **不会**被解析回 `ctx.query`。它们在最终合并前是相互独立的实体。
233-
- 如果你在钩子中替换了 `ctx.url`，除非你手动保留，否则原 URL 中的 search params 将会丢失。
234-
- 如需在钩子中修改查询参数，建议直接操作 `ctx.query`。
252+
- 在钩子（如 `beforeRequest`）中修改 `ctx.request.url` **不会**被解析回 `ctx.request.query`。它们在最终合并前是相互独立的实体。
253+
- 如果你在钩子中替换了 `ctx.request.url`，除非你手动保留，否则原 URL 中的 search params 将会丢失。
254+
- 如需在钩子中修改查询参数，建议直接操作 `ctx.request.query`。
235255

236256
## 钩子
237257

@@ -242,13 +262,23 @@ Fexios 采用简化的两阶段合并策略：
242262
```ts
243263
export type FexiosHook<C = unknown> = (
244264
context: C
245-
) => AwaitAble<C | void | false>
246-
export interface FexiosContext<T = any> extends FexiosRequestOptions {
247-
url: string // 可能在 beforeInit 后发生变化
248-
rawRequest?: Request // 在 beforeRequest 中提供
249-
rawResponse?: Response // 在 afterRequest 中提供
250-
response?: IFexiosResponse // 在 afterRequest 中提供
251-
data?: T // 在 afterRequest 中提供
265+
) => AwaitAble<C | void | false | Response>
266+
export interface FexiosContext<T = any> {
267+
request: {
268+
url: string // 可能在 beforeInit 后发生变化
269+
query: Record<string, any> | URLSearchParams
270+
headers: Headers | Record<string, any>
271+
body?: any
272+
rawRequest?: Request // 在 beforeActualFetch 中可用
273+
}
274+
runtime: {
275+
abortController?: AbortController
276+
onProgress?: (progress: number, buffer?: Uint8Array) => void
277+
customEnv?: any
278+
}
279+
rawResponse?: Response // 在 afterRawResponse 中可用
280+
response?: IFexiosResponse<T> // 在 afterResponse 中可用
281+
// NOTE: 旧字段如 ctx.url / ctx.query 可能仍存在，但已 deprecated。
252282
}
253283
```
254284

@@ -260,11 +290,12 @@ export interface FexiosContext<T = any> extends FexiosRequestOptions {
260290
const fexios = new Fexios()
261291

262292
fexios.on('beforeRequest', async (ctx) => {
263-
ctx.headers.authorization = localStorage.getItem('token')
264-
if (ctx.query.foo === 'bar') {
293+
;(ctx.request.headers as any).authorization = localStorage.getItem('token')
294+
const q = ctx.request.query as any
295+
if (q.foo === 'bar') {
265296
return false
266297
} else {
267-
ctx.query.foo = 'baz'
298+
q.foo = 'baz'
268299
return ctx
269300
}
270301
return ctx
@@ -289,11 +320,11 @@ JSON 主体已转换为 JSON 字符串。`Content-Type` 头已设置为主体的
289320

290321
### beforeActualFetch
291322

292-
- `ctx.rawRequest`: `{Request}` 现在可用。
323+
- `ctx.request.rawRequest`: `{Request}` 现在可用。
293324

294325
Request 实例已生成。
295326

296-
此时，你不能再修改 `ctx.url`、`ctx.query`、`ctx.headers` 或 `ctx.body`（等）。除非你传递一个全新的 `Request` 来替换 `ctx.rawRequest`。
327+
此时，你不能再修改 `ctx.request.url`、`ctx.request.query`、`ctx.request.headers` 或 `ctx.request.body`（等）。除非你传递一个全新的 `Request` 来替换 `ctx.request.rawRequest`。
297328

298329
### afterResponse
299330

0 commit comments

Comments
 (0)