npm - soon-fetch - Versions diffs - 4.0.0 → 4.0.1 - Mend

soon-fetch 4.0.0 → 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));
@@ -227,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
@@ -541,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",
@@ -556,6 +591,12 @@ const data = await soonFetch<User[]>({
   },
   baseURL: "https://api.example.com",
 });
+if (!response.ok) {
+  throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+}
+const data = await response.json() as User[];
 ```
 #### toFormData
@@ -688,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',
@@ -703,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);
@@ -790,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(() => {
@@ -1197,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",
@@ -1212,6 +1258,12 @@ const data = await soonFetch<User[]>({
   },
   baseURL: "https://api.example.com",
 });
+if (!response.ok) {
+  throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+}
+const data = await response.json() as User[];
 ```
 #### toFormData
@@ -1310,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)