@longzai-intelligence-transport/http-adapter-react 0.1.0

package/README.md

@@ -0,0 +1,87 @@
+# @longzai-intelligence-transport/http-adapter-react
+
+React Hooks 适配器，基于 SWR 提供类型安全的 Query、Mutation、Infinite Hook 工厂。
+
+## 安装
+
+```bash
+bun add @longzai-intelligence-transport/http-adapter-react
+```
+
+## 功能特性
+
+- **Query Hook 工厂** - 创建类型安全的数据查询 Hook
+- **Mutation Hook 工厂** - 创建类型安全的数据变更 Hook
+- **Infinite Hook 工厂** - 创建类型安全的无限滚动 Hook
+- **完整的 TypeScript 支持** - 自动推断参数和返回类型
+
+## 依赖
+
+- `react` - React 框架（peer dependency，>=18.0.0）
+- `swr` - SWR 数据请求库（peer dependency，>=2.0.0）
+- `zod` - Schema 验证（peer dependency）
+- `@longzai-intelligence-transport/http-core` - 核心模块
+
+## 使用示例
+
+### Query Hook
+
+```typescript
+import { createQueryHook } from '@longzai-intelligence-transport/http-adapter-react';
+
+const useGetUser = createQueryHook(getUserApi, 'user');
+const { data, error, isLoading } = useGetUser({ id: '123' });
+```
+
+### Mutation Hook
+
+```typescript
+import { createMutationHook } from '@longzai-intelligence-transport/http-adapter-react';
+
+const useCreateUser = createMutationHook(createUserApi);
+const { trigger, isMutating } = useCreateUser();
+await trigger({ body: { name: 'John' } });
+```
+
+### Infinite Hook
+
+```typescript
+import { createInfiniteHook } from '@longzai-intelligence-transport/http-adapter-react';
+
+const useUserList = createInfiniteHook(getUserListApi);
+const { data, size, setSize, isLoadingMore } = useUserList();
+```
+
+## 导出模块
+
+### Query Hook
+
+- `createQueryHook` - 创建查询 Hook 工厂函数
+- `QueryHookFunction` - 查询 Hook 函数类型
+- `QueryHookReturn` - 查询 Hook 返回类型
+- `QueryHookNoParams` - 无参数查询 Hook 类型
+- `QueryHookWithParams` - 带路径参数查询 Hook 类型
+- `QueryHookWithQuery` - 带查询参数 Hook 类型
+- `QueryHookWithParamsAndQuery` - 带路径和查询参数 Hook 类型
+
+### Mutation Hook
+
+- `createMutationHook` - 创建变更 Hook 工厂函数
+- `MutationHookFunction` - 变更 Hook 函数类型
+- `MutationHookReturn` - 变更 Hook 返回类型
+- `MutationTriggerArgs` - 触发器参数类型
+- `MutationTriggerNoArgs` - 无参数触发器类型
+- `MutationTriggerWithParams` - 带路径参数触发器类型
+- `MutationTriggerWithBody` - 带请求体触发器类型
+- `MutationTriggerWithParamsAndBody` - 带路径参数和请求体触发器类型
+
+### Infinite Hook
+
+- `createInfiniteHook` - 创建无限滚动 Hook 工厂函数
+- `InfiniteHookFunction` - 无限滚动 Hook 函数类型
+- `InfiniteHookReturn` - 无限滚动 Hook 返回类型
+- `ExtractPageItem` - 提取分页项类型
+
+## 许可证
+
+UNLICENSED

package/dist/index.d.ts

@@ -0,0 +1,268 @@
+import { SWRConfiguration, SWRResponse } from "swr";
+import { ApiPaginatedListData, ApiResponse, CursorPaginatedResult, HttpClient, InferRouteBody, InferRouteParams, InferRouteQuery, InferRouteResponse, MockRequest, MockRequestContext, RouteDefinition, createConfigurableMockHttpClient, createDelayedMockHttpClient, createErrorMockHttpClient, createMockHttpClient, createRouteMock } from "@longzai-intelligence-transport/http-core";
+import { SWRInfiniteConfiguration, SWRInfiniteResponse } from "swr/infinite";
+
+//#region src/create-query-hook.factory.d.ts
+/**
+ * Query Hook 返回类型
+ *
+ * @typeParam TRoute - 路由定义类型
+ */
+type QueryHookReturn<TRoute extends RouteDefinition> = SWRResponse<ApiResponse<InferRouteResponse<TRoute>>>;
+/**
+ * Query Hook 函数类型 - 无参数
+ *
+ * @typeParam TRoute - 路由定义类型
+ */
+type QueryHookNoParams<TRoute extends RouteDefinition> = (config?: SWRConfiguration<ApiResponse<InferRouteResponse<TRoute>>>) => QueryHookReturn<TRoute>;
+/**
+ * Query Hook 函数类型 - 只有 params
+ *
+ * @typeParam TRoute - 路由定义类型
+ */
+type QueryHookWithParams<TRoute extends RouteDefinition> = (params: InferRouteParams<TRoute>, config?: SWRConfiguration<ApiResponse<InferRouteResponse<TRoute>>>) => QueryHookReturn<TRoute>;
+/**
+ * Query Hook 函数类型 - 只有 query
+ *
+ * @typeParam TRoute - 路由定义类型
+ */
+type QueryHookWithQuery<TRoute extends RouteDefinition> = (query?: InferRouteQuery<TRoute>, config?: SWRConfiguration<ApiResponse<InferRouteResponse<TRoute>>>) => QueryHookReturn<TRoute>;
+/**
+ * Query Hook 函数类型 - params + query
+ *
+ * @typeParam TRoute - 路由定义类型
+ */
+type QueryHookWithParamsAndQuery<TRoute extends RouteDefinition> = (params: InferRouteParams<TRoute>, query?: InferRouteQuery<TRoute>, config?: SWRConfiguration<ApiResponse<InferRouteResponse<TRoute>>>) => QueryHookReturn<TRoute>;
+/**
+ * 根据路由定义推断 Query Hook 函数类型
+ *
+ * 根据路由是否包含 params 和 query，自动推断对应的 Hook 签名
+ *
+ * @typeParam TRoute - 路由定义类型
+ */
+type QueryHookFunction<TRoute extends RouteDefinition> = InferRouteParams<TRoute> extends undefined ? InferRouteQuery<TRoute> extends undefined ? QueryHookNoParams<TRoute> : QueryHookWithQuery<TRoute> : InferRouteQuery<TRoute> extends undefined ? QueryHookWithParams<TRoute> : QueryHookWithParamsAndQuery<TRoute>;
+/**
+ * 创建 Query Hook 工厂
+ *
+ * 从路由定义自动创建类型安全的 SWR Query Hook。仅适用于 GET 请求。
+ *
+ * @example
+ *   ```typescript
+ *   import { createQueryHook } from '@longzai-intelligence-transport/http-adapter-react';
+ *   import { categoryRoutes } from './routes';
+ *   import { httpClient } from './http-client';
+ *
+ *   const useCategoryList = createQueryHook(categoryRoutes.list, httpClient);
+ *   const useCategoryDetail = createQueryHook(categoryRoutes.detail, httpClient);
+ *
+ *   // 组件中使用
+ *   function CategoryPage() {
+ *     const { data, isLoading } = useCategoryList({ enabled: true });
+ *     const categories = data?.data?.items ?? [];
+ *   }
+ *   ```;
+ *
+ * @typeParam TRoute - 路由定义类型
+ * @param route - 路由定义
+ * @param client - HTTP 客户端实例
+ * @returns 类型安全的 Query Hook
+ * @throws {@link Error} 当路由配置不合法时抛出错误
+ */
+declare function createQueryHook<TRoute extends RouteDefinition>(route: TRoute, client: HttpClient): QueryHookFunction<TRoute>;
+//#endregion
+//#region src/create-mutation-hook.factory.types.d.ts
+/**
+ * Mutation Hook 返回类型
+ *
+ * @typeParam TRoute - 路由定义类型
+ */
+type MutationHookReturn<TRoute extends RouteDefinition> = {
+  /**
+   * 触发请求
+   */
+  trigger: (...args: MutationTriggerArgs<TRoute>) => Promise<ApiResponse<InferRouteResponse<TRoute>>>;
+  /**
+   * 是否正在触发
+   */
+  isMutating: boolean;
+  /**
+   * 响应数据
+   */
+  data: ApiResponse<InferRouteResponse<TRoute>> | undefined;
+  /**
+   * 错误信息
+   */
+  error: Error | undefined;
+  /**
+   * 重置状态
+   */
+  reset: () => void;
+};
+/**
+ * Mutation trigger 参数类型 - 无参数
+ */
+type MutationTriggerNoArgs = [];
+/**
+ * Mutation trigger 参数类型 - 只有 params
+ *
+ * @typeParam TRoute - 路由定义类型
+ */
+type MutationTriggerWithParams<TRoute extends RouteDefinition> = [params: InferRouteParams<TRoute>];
+/**
+ * Mutation trigger 参数类型 - 只有 body
+ *
+ * @typeParam TRoute - 路由定义类型
+ */
+type MutationTriggerWithBody<TRoute extends RouteDefinition> = [body: InferRouteBody<TRoute>];
+/**
+ * Mutation trigger 参数类型 - params + body
+ *
+ * @typeParam TRoute - 路由定义类型
+ */
+type MutationTriggerWithParamsAndBody<TRoute extends RouteDefinition> = [params: InferRouteParams<TRoute>, body: InferRouteBody<TRoute>];
+/**
+ * 根据路由定义推断 Mutation trigger 参数类型
+ *
+ * @typeParam TRoute - 路由定义类型
+ */
+type MutationTriggerArgs<TRoute extends RouteDefinition> = InferRouteParams<TRoute> extends undefined ? InferRouteBody<TRoute> extends undefined ? MutationTriggerNoArgs : MutationTriggerWithBody<TRoute> : InferRouteBody<TRoute> extends undefined ? MutationTriggerWithParams<TRoute> : MutationTriggerWithParamsAndBody<TRoute>;
+/**
+ * Mutation Hook 函数类型
+ *
+ * @typeParam TRoute - 路由定义类型
+ */
+type MutationHookFunction<TRoute extends RouteDefinition> = (config?: SWRConfiguration<ApiResponse<InferRouteResponse<TRoute>>>) => MutationHookReturn<TRoute>;
+//#endregion
+//#region src/create-mutation-hook.factory.d.ts
+/**
+ * 创建 Mutation Hook 工厂
+ *
+ * 从路由定义自动创建类型安全的 Mutation Hook。适用于 POST/PUT/DELETE/PATCH 请求。
+ *
+ * @example
+ *   ```typescript
+ *   import { createMutationHook } from '@longzai-intelligence-transport/http-adapter-react';
+ *   import { categoryRoutes } from './routes';
+ *   import { httpClient } from './http-client';
+ *
+ *   const useCreateCategory = createMutationHook(categoryRoutes.create, httpClient);
+ *   const useUpdateCategory = createMutationHook(categoryRoutes.update, httpClient);
+ *   const useDeleteCategory = createMutationHook(categoryRoutes.delete, httpClient);
+ *
+ *   // 组件中使用
+ *   function CategoryForm() {
+ *     const { trigger: create, isMutating } = useCreateCategory();
+ *
+ *     const handleSubmit = async (data) => {
+ *       const result = await create(data);
+ *       if (result.success) {
+ *         // 创建成功
+ *       }
+ *     };
+ *   }
+ *   ```;
+ *
+ * @typeParam TRoute - 路由定义类型
+ * @param route - 路由定义
+ * @param client - HTTP 客户端实例
+ * @returns 类型安全的 Mutation Hook
+ */
+declare function createMutationHook<TRoute extends RouteDefinition>(route: TRoute, client: HttpClient): MutationHookFunction<TRoute>;
+//#endregion
+//#region src/create-infinite-hook.factory.d.ts
+/**
+ * 无限滚动分页模式
+ */
+type InfinitePaginationMode = 'page' | 'cursor';
+/**
+ * 无限滚动 Hook 配置选项
+ */
+type InfiniteHookOptions = {
+  /**
+   * 分页模式，默认 'page'
+   *
+   * - 'page': 使用 page/pageSize 分页，适用于需要跳页的场景
+   * - 'cursor': 使用 cursor 游标分页，适用于无限滚动场景
+   */
+  paginationMode?: InfinitePaginationMode;
+  /**
+   * 游标分页时的默认每页数量，默认 20
+   */
+  defaultPageSize?: number;
+};
+/**
+ * 无限滚动分页数据类型（支持 page 和 cursor 模式）
+ *
+ * @typeParam T - 列表项类型
+ */
+type InfinitePageData<T> = ApiPaginatedListData<T> | CursorPaginatedResult<T>;
+/**
+ * 无限滚动 Hook 返回类型
+ *
+ * @typeParam T - 列表项类型
+ */
+type InfiniteHookReturn<T> = SWRInfiniteResponse<ApiResponse<InfinitePageData<T> | null>>;
+/**
+ * 无限滚动 Hook 函数类型
+ *
+ * @typeParam TRoute - 路由定义类型
+ * @typeParam TItem - 列表项类型
+ */
+type InfiniteHookFunction<TRoute extends RouteDefinition, TItem> = (params?: InferRouteParams<TRoute>, config?: SWRInfiniteConfiguration<ApiResponse<InfinitePageData<TItem> | null>>) => InfiniteHookReturn<TItem>;
+/**
+ * 从路由响应中提取分页项类型
+ *
+ * @typeParam T - 响应数据类型
+ */
+type ExtractPageItem<T> = T extends ApiPaginatedListData<infer Item> ? Item : T extends CursorPaginatedResult<infer Item> ? Item : never;
+/**
+ * 创建无限滚动 Hook 工厂
+ *
+ * 从路由定义自动创建类型安全的 SWR Infinite Hook。用于分页加载、无限滚动场景。
+ *
+ * @example
+ *   ```typescript
+ *   import { createInfiniteHook } from '@longzai-intelligence-transport/http-adapter-react';
+ *   import { productRoutes } from './routes';
+ *   import { httpClient } from './http-client';
+ *
+ *   const useInfiniteProducts = createInfiniteHook(productRoutes.list, httpClient);
+ *
+ *   // 组件中使用
+ *   function ProductList() {
+ *     const { data, size, setSize, isLoading } = useInfiniteProducts();
+ *
+ *     const products = data?.flatMap((page) => page.data?.items ?? []) ?? [];
+ *
+ *     const loadMore = () => setSize(size + 1);
+ *
+ *     return (
+ *       <div>
+ *         {products.map((product) => (
+ *           <div key={product.id}>{product.name}</div>
+ *         ))}
+ *         <button onClick={loadMore}>加载更多</button>
+ *       </div>
+ *     );
+ *   }
+ *   ```;
+ *
+ * @example
+ *   ```typescript
+ *   // 使用游标分页模式
+ *   const useInfiniteProducts = createInfiniteHook(productRoutes.list, httpClient, {
+ *     paginationMode: 'cursor',
+ *     defaultPageSize: 20,
+ *   });
+ *   ```;
+ *
+ * @typeParam TRoute - 路由定义类型
+ * @param route - 路由定义
+ * @param client - HTTP 客户端实例
+ * @param options - Hook 配置选项
+ * @returns 类型安全的 Infinite Hook
+ * @throws {@link Error} 当路由配置不合法时抛出错误
+ */
+declare function createInfiniteHook<TRoute extends RouteDefinition>(route: TRoute, client: HttpClient, options?: InfiniteHookOptions): InfiniteHookFunction<TRoute, ExtractPageItem<InferRouteResponse<TRoute>>>;
+//#endregion
+export { type ExtractPageItem, type InfiniteHookFunction, type InfiniteHookOptions, type InfiniteHookReturn, type InfinitePageData, type InfinitePaginationMode, type MockRequest, type MockRequestContext, type MutationHookFunction, type MutationHookReturn, type MutationTriggerArgs, type MutationTriggerNoArgs, type MutationTriggerWithBody, type MutationTriggerWithParams, type MutationTriggerWithParamsAndBody, type QueryHookFunction, type QueryHookNoParams, type QueryHookReturn, type QueryHookWithParams, type QueryHookWithParamsAndQuery, type QueryHookWithQuery, createConfigurableMockHttpClient, createDelayedMockHttpClient, createErrorMockHttpClient, createInfiniteHook, createMockHttpClient, createMutationHook, createQueryHook, createRouteMock };

package/dist/index.js

@@ -0,0 +1 @@
+import e from"swr";import{createConfigurableMockHttpClient as t,createDelayedMockHttpClient as n,createErrorMockHttpClient as r,createMockHttpClient as i,createRouteMock as a,isType as o}from"@longzai-intelligence-transport/http-core";import{useCallback as s,useState as c}from"react";import l from"swr/infinite";function u(e,t,n){let r=[e.method,e.path];return t&&r.push(t),n&&r.push(n),r}function d(e){return`params`in e&&e.params!==void 0}function f(e){return`query`in e&&e.query!==void 0}function p(t,n,r,i,a){return e(u(t,o(r)?r:void 0,o(i)?i:void 0),()=>n.request({route:t,params:o(r)?r:void 0,query:o(i)?i:void 0}),a)}function m(t,n,r,i){return e(u(t,o(r)?r:void 0),()=>n.request({route:t,params:o(r)?r:void 0}),i)}function h(t,n,r,i){return e(r?u(t,void 0,o(r)?r:void 0):null,()=>n.request({route:t,query:o(r)?r:void 0}),i)}function g(t,n,r){return e(u(t),()=>n.request({route:t}),r)}function _(e,t){let n=d(e),r=f(e);if(n&&r){let n=(n,r,i)=>p(e,t,n,r,i);if(o(n))return n}if(n){let n=(n,r)=>m(e,t,n,r);if(o(n))return n}if(r){let n=(n,r)=>h(e,t,n,r);if(o(n))return n}let i=n=>g(e,t,n);if(o(i))return i;throw Error(`无法创建 Query Hook：路由配置不合法`)}function v(e){return`params`in e&&e.params!==void 0}function y(e){return`body`in e&&e.body!==void 0}function b(e,t,n,r,i){if(n&&r){let[n,r]=i;return t.request({route:e,params:o(n)?n:void 0,body:o(r)?r:void 0})}if(n){let[n]=i;return t.request({route:e,params:o(n)?n:void 0})}if(r){let[n]=i;return t.request({route:e,body:o(n)?n:void 0})}return t.request({route:e})}function x(e,t){let n=v(e),r=y(e);return()=>{let[i,a]=c(!1),[o,l]=c(void 0),[u,d]=c(void 0);return{trigger:s(async(...i)=>{a(!0),d(void 0);try{let a=await b(e,t,n,r,i);return l(a),a}catch(e){let t=e instanceof Error?e:Error(String(e));throw d(t),t}finally{a(!1)}},[t]),isMutating:i,data:o,error:u,reset:s(()=>{a(!1),l(void 0),d(void 0)},[])}}}function S(e,t,n,r){let i=[e.method,e.path];return t&&i.push(t),r&&r.data&&`hasNextPage`in r.data&&!r.data.hasNextPage?null:(i.push({page:n+1}),i)}function C(e,t,n,r){let i=[e.method,e.path];if(t&&i.push(t),n&&n.data&&`hasMore`in n.data&&!n.data.hasMore)return null;let a=n?.data&&`nextCursor`in n.data?n.data.nextCursor:void 0;return i.push(a?{cursor:a,limit:r}:{limit:r}),i}function w(e,t,n,r){return async i=>{let a=i[n?2:1],s=await t.request({route:e,params:n&&o(r)?r:void 0,query:o(a)?a:void 0});return o(s)?s:{success:!1,data:null,message:`分页数据类型不匹配`,timestamp:Date.now()}}}function T(e,t,n){let r=`params`in e&&e.params!==void 0,i=n?.paginationMode??`page`,a=n?.defaultPageSize??20,s=(n,o)=>l((t,r)=>i===`page`?S(e,n,t,r):i===`cursor`?C(e,n,r,a):null,w(e,t,r,n),o);if(o(s))return s;throw Error(`无法创建 Infinite Hook：路由配置不合法`)}export{t as createConfigurableMockHttpClient,n as createDelayedMockHttpClient,r as createErrorMockHttpClient,T as createInfiniteHook,i as createMockHttpClient,x as createMutationHook,_ as createQueryHook,a as createRouteMock};

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@longzai-intelligence-transport/http-adapter-react",
+  "version": "0.1.0",
+  "keywords": [
+    "adapter",
+    "hook",
+    "http",
+    "react",
+    "swr",
+    "utils"
+  ],
+  "license": "UNLICENSED",
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsgo --build tsconfig/build.json && resolve-aliases -p tsconfig/build.json",
+    "build:prod": "NODE_ENV=production tsdown",
+    "prepublishOnly": "bun run build:prod",
+    "typecheck": "bun run typecheck:app && bun run typecheck:node && bun run typecheck:test",
+    "typecheck:app": "tsgo --noEmit -p tsconfig/app.json",
+    "typecheck:node": "tsgo --noEmit -p tsconfig/node.json",
+    "typecheck:test": "tsgo --noEmit -p tsconfig/test.json",
+    "lint": "oxlint && oxfmt --check",
+    "lint:fix": "oxlint --fix && oxfmt",
+    "test": "bun test",
+    "test:watch": "bun test --watch",
+    "test:coverage": "bun test --coverage",
+    "clean": "rimraf dist out .cache"
+  },
+  "dependencies": {
+    "@longzai-intelligence-transport/http-core": "0.1.0"
+  },
+  "devDependencies": {
+    "@testing-library/react": "^16.3.2",
+    "@types/react": "^19.2.17",
+    "jsdom": "^29.1.1",
+    "react": "^19.2.7",
+    "swr": "^2.4.1",
+    "zod": "^4.4.3"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0",
+    "swr": ">=2.0.0",
+    "zod": "^4.4.3"
+  }
+}