npm - soon-fetch - Versions diffs - 4.0.0-beta.5 → 4.0.1 - Mend

soon-fetch 4.0.0-beta.5 → 4.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (10) hide show

package/README.md CHANGED Viewed

@@ -36,9 +36,9 @@
 import { createSoon, soonFetch } from "soon-fetch";
 // 使用 soonFetch 作为基础请求函数
-const request = async <T>(url: string, options?: SoonOptions) => {
+const request = async <T>(url: string, options?: SoonOptions): Promise<T> => {
   const isGet = !options?.method || options?.method.toLocaleLowerCase() === "get";
-  const response = await soonFetch<T>({
+  const response = await soonFetch({
     url,
     options,
     baseURL: '/api',
@@ -51,7 +51,12 @@ const request = async <T>(url: string, options?: SoonOptions) => {
       staleTime: isGet ? 2 * 1000 : 0,
     },
   });
-  return response;
+  if (!response.ok) {
+    throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+  }
+  return response.json() as Promise<T>;
 };
 const soon = createSoon(request);
@@ -133,7 +138,7 @@ import { useEffect, useRef, useState } from "react";
 type User = { name: string; job: string };
 const api = soon.GET("/api/users").Query<{ page: number }>().Ok<User[]>();
 export default function App() {
-  const refAbort = useRef([]);
+  const refAbort = useRef<[AbortController] | []>([]);
   const [list, setList] = useState<User[]>([]);
   const [page, setPage] = useState(1);
   useEffect(() => {
@@ -156,13 +161,15 @@ export default function App() {
 ##### Rapid Define APIs
-```typescript
-//can be GET POST PATCH PUT DELETE
+```ts
+  //可以是 GET POST PATCH PUT DELETE
+  //GET 请求数据传递至query,其他方法请求数据传递至body
   soon.GET(url:string).Query<Query>().Ok<Response>()
   soon.POST(url:string).Body<Body>().Ok<Response>()
   soon.GET(url:string).Options({ timeout: 5000 }).Ok<Response>()
   soon.POST(url:string).Body<Body>().Options({ timeout: 5000 }).Ok<Response>()
-//define an api
+  //define an api
 export const getUserInfo = soon.GET("/user/:id").Ok();
 //then use in any where
 getUserInfo({ id: 2 }).then((res) => console.log(res));
@@ -180,6 +187,10 @@ export const login = soon
 login({ username: "admin", password: "123" }).then((res) => {
   localStorage.setItem("token", res.token);
 });
+//with Params for type safety
+export const getUserById = soon.GET("/user/:id").Params<{ id: number }>().Ok<{ id: number; name: string }>();
+getUserById({ id: 1 }).then((res) => console.log(res));
 ```
 ### API
@@ -223,25 +234,53 @@ Create a soon request instance.
 **Example:**
 ```typescript
-const soon = createSoon(
-  async <T>(url: string, options?: SoonOptions): Promise<T> => {
-    const response = await fetch(url, options);
-    return response.json();
+import { createSoon, soonFetch } from "soon-fetch";
+// Define custom request wrapper with business logic
+const request = async <T>(url: string, options?: SoonOptions): Promise<T> => {
+  const isGet = !options?.method || options?.method.toLowerCase() === "get";
+  const response = await soonFetch({
+    url,
+    options,
+    baseURL: '/api',
+    baseOptions: {
+      timeout: 20 * 1000,
+      headers: new Headers({
+        Authorization: "Bearer " + localStorage.getItem("token"),
+      }),
+      share: isGet,
+      staleTime: isGet ? 2 * 1000 : 0,
+    },
+  });
+  if (!response.ok) {
+    throw new Error(`HTTP ${response.status}: ${response.statusText}`);
   }
-);
+  return response.json() as Promise<T>;
+};
-// Usage example
-const data = await soon.get<{ id: number; name: string }[]> ("/api/users");
+// Create soon instance
+const soon = createSoon(request);
-// Define API with options
-export const login = soon
-  .POST("/user/login")
-  .Body<{ username: string; password: string }>()
-  .Ok<{ token: string }>();
+// Usage 1: Shortcut methods with generics
+const users = await soon.get<{ id: number; name: string }[]>("/api/users");
-login({ username: "admin", password: "123" }).then((res) => {
-  localStorage.setItem("token", res.token);
-});
+// Usage 2: Define typed APIs with chain calls
+export const getUserById = soon
+  .GET("/user/:id")
+  .Params<{ id: number }>()
+  .Ok<{ id: number; name: string }>();
+export const createUser = soon
+  .POST("/user")
+  .Body<{ name: string; email: string }>()
+  .Ok<{ id: number }>();
+// Usage 3: Use defined APIs
+const user = await getUserById({ id: 1 });
+const newUser = await createUser({ name: "John", email: "john@example.com" });
 ```
 #### createShortApi
@@ -270,6 +309,10 @@ const API = createShortApi(
 // Usage example
 const getUser = API.GET("/api/users/:id").Ok<{ id: number; name: string }>();
 const userData = await getUser({ id: 1 });
+// With Params for type safety
+const getUserById = API.GET("/api/users/:id").Params<{ id: number }>().Ok<{ id: number; name: string }>();
+const userData = await getUserById({ id: 1 });
 ```
 #### createShortMethods
@@ -295,7 +338,7 @@ const methods = createShortMethods(["get", "post"] as const, (method) => {
 // Usage: methods.get<{ id: number; name: string }[]>('/api/users')
 ```
-#### parseUrlOptions
+#### parseOptions
 Parse URL options.
@@ -303,17 +346,17 @@ Parse URL options.
 - `urlOptions`: Object containing url, options, baseURL and baseOptions
-**Returns:** Tuple of processed url and options
+**Returns:** Object containing parsed url, options, is_body_json, and abortController
 **Example:**
 ```typescript
-const [url, options] = parseUrlOptions({
+const parsed = parseOptions({
   url: "/api/users/:id",
   options: { params: { id: "123" } },
   baseURL: "https://api.example.com",
 });
-// Returns: ['https://api.example.com/api/users/123', options]
+// Returns: { url: 'https://api.example.com/api/users/123', options: {...}, is_body_json: false, abortController: AbortController }
 ```
 #### mergeHeaders
@@ -356,7 +399,7 @@ const mergedSignal = mergeSignals(
 );
 ```
-#### mergeUrl
+#### parseUrl
 Merge URL and its related parameters.
 Handle baseURL, path parameters and query parameters to generate complete URL.
@@ -443,24 +486,6 @@ const key = genRequestKey({
 });
 ```
-#### raceAbort
-Race condition handling function.
-Used to handle request race conditions, terminating previous requests.
-**Parameters:**
-- `abortController`: Controller of the current request
-- `controllers`: Array of existing controllers
-**Example:**
-```typescript
-const controller = new AbortController();
-const controllers: AbortController[] = [];
-// 注意：raceAbort 函数已不再直接导出，而是通过 createRequestStore 使用
-```
 #### createRequestStore
 Create request store instance.
@@ -551,12 +576,12 @@ A lightweight fetch wrapper with caching, sharing, and race condition handling.
   - `store`: Custom request store
   - `sortRequestKey`: Whether to sort request key
-**Returns:** Promise that resolves to the response
+**Returns:** Promise that resolves to Response
 **Example:**
 ```typescript
-const data = await soonFetch<User[]>({
+const response = await soonFetch({
   url: "/api/users",
   options: {
     method: "GET",
@@ -566,27 +591,12 @@ const data = await soonFetch<User[]>({
   },
   baseURL: "https://api.example.com",
 });
-```
-#### parseWithBase
-Parse base URL configuration.
-Process baseURL, headers, body and other configuration items to generate final request configuration.
-**Parameters:**
-- `urlOptions`: Object containing url, options, baseURL and baseOptions
-**Returns:** Processed url, options, is_body_json and abortController
-**Example:**
+if (!response.ok) {
+  throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+}
-```typescript
-const result = parseWithBase({
-  url: "/api/users",
-  options: { method: "GET" },
-  baseURL: "https://api.example.com",
-});
+const data = await response.json() as User[];
 ```
 #### toFormData
@@ -653,28 +663,6 @@ const buffer = await progressReadBody(response.body!, (progress, downloaded, tot
 });
 ```
-#### parseOptions
-Parse and merge request options.
-Used to process request options, including baseURL, headers, and body.
-**Parameters:**
-- `urlOptions`: Object containing url, options, baseURL, and baseOptions
-**Returns:** Object containing parsed url, options, is_body_json, and abortController
-**Example:**
-```typescript
-const parsed = parseOptions({
-  url: "/api/users",
-  options: { method: "GET", query: { page: 1 } },
-  baseURL: "https://api.example.com",
-  baseOptions: { timeout: 5000 },
-});
-```
 #### requestWithStore
 Request wrapper with store support.
@@ -741,9 +729,9 @@ const data = await requestWithStore(store, () => fetch(url, options), requestKey
 import { createSoon, soonFetch } from "soon-fetch";
 // 使用 soonFetch 作为基础请求函数
-const request = async <T>(url: string, options?: SoonOptions) => {
+const request = async <T>(url: string, options?: SoonOptions): Promise<T> => {
   const isGet = !options?.method || options?.method.toLocaleLowerCase() === "get";
-  const response = await soonFetch<T>({
+  const response = await soonFetch({
     url,
     options,
     baseURL: '/api',
@@ -756,7 +744,12 @@ const request = async <T>(url: string, options?: SoonOptions) => {
       staleTime: isGet ? 2 * 1000 : 0,
     },
   });
-  return response;
+  if (!response.ok) {
+    throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+  }
+  return response.json() as Promise<T>;
 };
 const soon = createSoon(request);
@@ -779,6 +772,10 @@ export const login = soon
 login({ username: "admin", password: "123" }).then((res) => {
   localStorage.setItem("token", res.token);
 });
+//使用 Params 进行类型安全定义
+export const getUserById = soon.GET("/user/:id").Params<{ id: number }>().Ok<{ id: number; name: string }>();
+getUserById({ id: 1 }).then((res) => console.log(res));
 ```
 ### 特别功能
@@ -839,7 +836,7 @@ import { useEffect, useRef, useState } from "react";
 type User = { name: string; job: string };
 const api = soon.GET("/api/users").Query<{ page: number }>().Ok<User[]>();
 export default function App() {
-  const refAbort = useRef([]);
+  const refAbort = useRef<[AbortController] | []>([]);
   const [list, setList] = useState<User[]>([]);
   const [page, setPage] = useState(1);
   useEffect(() => {
@@ -888,6 +885,10 @@ export default function App() {
   login({username:'admin',password:'123'}).then(res=>{
     localStorage.setItem('token', res.token);
   })
+  //使用 Params 进行类型安全定义
+  export const getUserById = soon.GET('/user/:id').Params<{ id: number }>().Ok<{ id: number; name: string }>();
+  getUserById({ id: 1 }).then(res => console.log(res));
 ```
 ### API
@@ -969,7 +970,7 @@ login({ username: "admin", password: "123" }).then((res) => {
 const API = createShortApi(
   async (url, method, params, query, body, options) => {
     // 处理请求逻辑
-    const _url = mergeUrl(url, { params, query });
+    const { url: _url } = parseUrl(url, { params, query });
     const response = await fetch(_url, { ...options, method, body });
     return response.json();
   }
@@ -978,6 +979,10 @@ const API = createShortApi(
 // 使用示例
 const getUser = API.GET("/api/users/:id").Ok();
 const userData = await getUser({ id: 1 });
+// 使用 Params 进行类型安全定义
+const getUserById = API.GET("/api/users/:id").Params<{ id: number }>().Ok<{ id: number; name: string }>();
+const userData = await getUserById({ id: 1 });
 ```
 #### createShortMethods
@@ -1000,7 +1005,7 @@ const methods = createShortMethods(["get", "post"] as const, (method) => {
 // 使用: methods.get('/api/users')
 ```
-#### parseUrlOptions
+#### parseOptions
 解析 URL 选项。
@@ -1008,17 +1013,17 @@ const methods = createShortMethods(["get", "post"] as const, (method) => {
 - `urlOptions`: 包含 url、options、baseURL 和 baseOptions 的对象
-**返回:** 处理后的 url 和 options 元组
+**返回:** 包含解析后的 url、options、is_body_json 和 abortController 的对象
 **示例:**
 ```typescript
-const [url, options] = parseUrlOptions({
+const parsed = parseOptions({
   url: "/api/users/:id",
   options: { params: { id: "123" } },
   baseURL: "https://api.example.com",
 });
-// 返回: ['https://api.example.com/api/users/123', options]
+// 返回: { url: 'https://api.example.com/api/users/123', options: {...}, is_body_json: false, abortController: AbortController }
 ```
 #### mergeHeaders
@@ -1061,7 +1066,7 @@ const mergedSignal = mergeSignals(
 );
 ```
-#### mergeUrl
+#### parseUrl
 合并 URL 及其相关参数。
 处理 baseURL、路径参数和查询参数，生成完整 URL。
@@ -1076,7 +1081,7 @@ const mergedSignal = mergeSignals(
 **示例:**
 ```typescript
-const url = mergeUrl("/api/users/:id", {
+const url = parseUrl("/api/users/:id", {
   params: { id: "123" },
   query: { filter: "active" },
   baseURL: "https://api.example.com",
@@ -1148,24 +1153,6 @@ const key = genRequestKey({
 });
 ```
-#### raceAbort
-竞态处理函数。
-用于处理请求竞态，终止之前的请求。
-**参数:**
-- `abortController`: 当前请求的控制器
-- `controllers`: 已存在的控制器数组
-**示例:**
-```typescript
-const controller = new AbortController();
-const controllers = [];
-raceAbort(controller, controllers); // 终止之前的请求并添加当前控制器
-```
 #### createRequestStore
 创建请求存储实例。
@@ -1256,12 +1243,12 @@ silentRefresh(
   - `store`: 自定义请求存储
   - `sortRequestKey`: 是否对请求键进行排序
-**返回:** 解析为响应的 Promise
+**返回:** 解析为 Response 的 Promise
 **示例:**
 ```typescript
-const data = await soonFetch<User[]>({
+const response = await soonFetch({
   url: "/api/users",
   options: {
     method: "GET",
@@ -1271,27 +1258,12 @@ const data = await soonFetch<User[]>({
   },
   baseURL: "https://api.example.com",
 });
-```
-#### parseWithBase
-解析基础 URL 配置。
-处理 baseURL、headers、body 等配置项，生成最终的请求配置。
-**参数:**
-- `urlOptions`: 包含 url、options、baseURL 和 baseOptions 的对象
-**返回:** 处理后的 url、options、is_body_json 和 abortController
-**示例:**
+if (!response.ok) {
+  throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+}
-```typescript
-const result = parseWithBase({
-  url: "/api/users",
-  options: { method: "GET" },
-  baseURL: "https://api.example.com",
-});
+const data = await response.json() as User[];
 ```
 #### toFormData
@@ -1358,28 +1330,6 @@ const buffer = await progressReadBody(response.body, (progress, downloaded, tota
 });
 ```
-#### parseOptions
-解析和合并请求选项。
-用于处理请求选项，包括 baseURL、headers 和 body。
-**参数:**
-- `urlOptions`: 包含 url、options、baseURL 和 baseOptions 的对象
-**返回:** 包含解析后的 url、options、is_body_json 和 abortController 的对象
-**示例:**
-```typescript
-const parsed = parseOptions({
-  url: "/api/users",
-  options: { method: "GET", query: { page: 1 } },
-  baseURL: "https://api.example.com",
-  baseOptions: { timeout: 5000 },
-});
-```
 #### requestWithStore
 带存储支持的请求包装器。
@@ -1412,6 +1362,253 @@ const data = await requestWithStore(store, () => fetch(url, options), requestKey
 ##### 安装 Installation
-```bash
+```
     npm install soon-fetch
 ```
+## Best Practices / 最佳实践
+#### Real-World Project Structure / 真实项目结构
+Based on [soon-admin-vue](https://github.com/leafio/soon-admin-vue):
+#### File Organization / 文件组织
+```
+src/api/
+├── request.ts          # Request wrapper with unified error handling
+├── types.ts            # Shared type definitions (e.g., PagedParams)
+├── index.ts            # Export all API modules
+└── modules/
+    ├── auth.ts         # Authentication APIs
+    ├── user.ts         # User management APIs
+    ├── role.ts         # Role management APIs
+    ├── dept.ts         # Department management APIs
+    └── ...             # Other domain-specific modules
+```
+#### Step 1: Create Request Wrapper (src/api/request.ts)
+```typescript
+import { createSoon, soonFetch } from "soon-fetch";
+import type { SoonOptions } from "soon-fetch";
+type ReqOpts = SoonOptions & {
+  retry?: { max?: number; enable?: (result: any) => boolean };
+  toastErr?: boolean;
+};
+const request = async <T>(url: string, options?: ReqOpts): Promise<T> => {
+  const isGet = !options?.method || options?.method.toLowerCase() === "get";
+  try {
+    const response = await soonFetch({
+      url,
+      options,
+      baseURL: import.meta.env.VITE_API_BASE,
+      baseOptions: {
+        timeout: 20 * 1000,
+        headers: new Headers({ Authorization: localStorage.getItem("token") ?? "" }),
+        share: isGet,
+        staleTime: isGet ? 2 * 1000 : 0,
+      },
+    });
+    if (!response.ok) {
+      throw new Error(`HTTP ${response.status}`);
+    }
+    // Auto-parse JSON
+    if (response.headers.get("content-type")?.includes("json")) {
+      const body = await response.json();
+      return body.data as T;
+    }
+    return response as unknown as T;
+  } catch (error: any) {
+    // Unified error handling
+    if (error.name === "TimeoutError") {
+      ElMessage.error("Request timeout");
+    } else if (error.name !== "AbortError" && options?.toastErr !== false) {
+      ElMessage.error(error.message);
+    }
+    throw error;
+  }
+};
+export const soon = createSoon<ReqOpts>(request);
+```
+**Key Points:**
+- ✅ **Centralized error handling**: All HTTP errors, timeouts, and business errors handled in one place
+- ✅ **Auto Token refresh**: Handle 401 errors and retry automatically
+- ✅ **Smart caching**: GET requests cached by default, write operations not cached
+- ✅ **No repetitive try-catch**: Components call APIs directly without error handling boilerplate
+---
+#### Step 2: Define Typed APIs (src/api/modules/user.ts)
+```typescript
+import { downloadBlob, getHeaderFilename } from "soon-utils";
+import type { PagedParams } from "../types";
+import type { Dept } from "./dept";
+import type { Role } from "./role";
+import { soon } from "../request";
+// Type definitions
+export type User = {
+  id: number;
+  username: string;
+  email: string | null;
+  phone: string | null;
+  name: string | null;
+  avatar: string | null;
+  roleId: number | undefined;
+  deptId: number | undefined;
+  status: number;
+};
+export type UserInfo = User & {
+  createTime: Date;
+  updateTime: Date | null;
+  dept?: Pick<Dept, "id" | "name">;
+  role?: Pick<Role, "id" | "name">;
+};
+type ListQueryUser = PagedParams & {
+  keyword?: string;
+  timeRange?: [string, string];
+};
+// CRUD APIs - simple and type-safe
+export const list_user = soon.GET("/user").Query<ListQueryUser>().Ok<{ list: UserInfo[] }>();
+export const add_user = soon.POST("/user").Body<User>().Ok();
+export const update_user = soon.PUT("/user/:id").Body<User>().Ok();
+export const del_user = soon.DELETE("/user/:id").Ok();
+export const detail_user = soon.GET("/user/:id").Ok<UserInfo>();
+// File download - returns Response for custom handling
+export const download_user_table = async (query: ListQueryUser) => {
+  return soon.get<Response>("/user/export", { query }).then(async (res) => {
+    const body = await res.blob();
+    const filename = getHeaderFilename(res.headers) ?? "user.xlsx";
+    downloadBlob(body, filename);
+  });
+};
+// Captcha example
+export const getCaptcha = soon.GET("/captcha").Ok<{ id: number; img: string }>();
+```
+**Key Points:**
+- ✅ **Domain-based modules**: Each module handles one business domain (user, role, dept, etc.)
+- ✅ **Type safety**: Use `.Params<>()`, `.Body<>()`, `.Ok<>()` for full type inference
+- ✅ **Shared types**: Import cross-domain types from sibling modules
+- ✅ **Special operations**: Complex logic (file download) wrapped in async functions
+- ✅ **Naming convention**: Use snake_case for API exports (e.g., `list_user`, `add_user`)
+---
+#### Step 3: Centralized Exports (src/api/index.ts)
+```typescript
+export * from "./modules/auth";
+export * from "./modules/user";
+export * from "./modules/role";
+// ... other modules
+```
+**Usage in components:**
+```typescript
+import { list_user, add_user, del_user } from "@/api";
+```
+---
+#### Step 4: Use in Components - Clean and Simple!
+**Vue 3 Example:**
+```typescript
+<script setup lang="ts">
+import { ref, onMounted } from "vue";
+import { list_user, del_user } from "@/api";
+import type { UserInfo } from "@/api";
+const users = ref<UserInfo[]>([]);
+const loading = ref(false);
+const fetchUsers = async () => {
+  loading.value = true;
+  try {
+    const { list } = await list_user({ page: 1, pageSize: 10 });
+    users.value = list;
+  } finally {
+    loading.value = false;
+  }
+};
+const handleDelete = async (id: number) => {
+  await del_user({ id });
+  await fetchUsers();
+};
+onMounted(fetchUsers);
+</script>
+```
+**React Example with Race Condition Handling:**
+```typescript
+import { useEffect, useRef, useState } from "react";
+import { list_user } from "@/api";
+import type { UserInfo } from "@/api";
+export default function UserList() {
+  const [users, setUsers] = useState<UserInfo[]>([]);
+  const [loading, setLoading] = useState(false);
+  const abortRef = useRef<[AbortController] | []>([]);
+  useEffect(() => {
+    setLoading(true);
+    list_user({ page: 1, pageSize: 10 }, { aborts: abortRef.current })
+      .then(({ list }) => setUsers(list))
+      .catch((err) => {
+        if (err.name !== "AbortError") console.error(err);
+      })
+      .finally(() => setLoading(false));
+  }, []);
+  if (loading) return <div>Loading...</div>;
+  return (
+    <ul>
+      {users.map(u => (
+        <li key={u.id}>{u.name}</li>
+      ))}
+    </ul>
+  );
+}
+```
+**Key Points:**
+- ✅ **No repetitive error handling**: Errors already handled in request wrapper
+- ✅ **Race condition control**: Use `useRef` to manage `aborts` parameter
+- ✅ **Clean code**: Focus on business logic, not network error boilerplate
+- ✅ **Type safety**: Full TypeScript support with autocomplete and type checking
+---
+### Summary / 总结
+**Architecture Benefits:**
+1. **Separation of Concerns**: Network layer (request.ts) vs Business layer (modules/) vs UI layer (components)
+2. **DRY Principle**: Error handling written once, used everywhere
+3. **Type Safety**: End-to-end type inference from API definition to component usage
+4. **Maintainability**: Domain-based modules make it easy to find and modify APIs
+5. **Scalability**: Easy to add new domains by creating new module files
+**Core Philosophy:**
+- 🎯 **Centralize common logic** in request wrapper (errors, retries, caching)
+- 🎯 **Keep API definitions simple** with chainable type-safe methods
+- 🎯 **Components focus on UI** without repetitive error handling code
+- 🎯 **Handle edge cases** only when needed (race conditions, special business logic)