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

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 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 { ApiPaginatedListData, ApiResponse, CreateApiFunction, CsrfProvider, CursorPaginatedResult, HttpClient, InferRouteBody, InferRouteParams, InferRouteQuery, InferRouteResponse, MockRequest, MockRequestContext, RouteDefinition, StreamResponseRoute, TokenProvider, 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
@@ -265,4 +265,105 @@ type ExtractPageItem<T> = T extends ApiPaginatedListData<infer Item> ? Item : T
  */
 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 };
+//#region src/stream-api-client.d.ts
+/**
+ * 流式路由响应类型映射（react 场景：Blob）
+ *
+ * 将 core 层的 BinaryStreamMarker 映射为 Blob。
+ * 非流式路由映射为 never。
+ *
+ * @typeParam TRoute - 路由定义类型
+ */
+type InferStreamRouteResponse<TRoute extends RouteDefinition> = TRoute extends StreamResponseRoute ? Blob : never;
+/**
+ * 流式下载函数签名
+ *
+ * 参数与 core GET 函数一致（基于 InferRouteParams / InferRouteQuery），
+ * 返回 Promise<Blob>。
+ *
+ * @typeParam TRoute - 路由定义类型
+ */
+type StreamDownloadFunction<TRoute extends RouteDefinition> = InferRouteParams<TRoute> extends undefined ? InferRouteQuery<TRoute> extends undefined ? () => Promise<InferStreamRouteResponse<TRoute>> : (query?: InferRouteQuery<TRoute>) => Promise<InferStreamRouteResponse<TRoute>> : InferRouteQuery<TRoute> extends undefined ? (params: InferRouteParams<TRoute>) => Promise<InferStreamRouteResponse<TRoute>> : (params: InferRouteParams<TRoute>, query?: InferRouteQuery<TRoute>) => Promise<InferStreamRouteResponse<TRoute>>;
+/**
+ * react API mapped type
+ *
+ * 流式路由映射为 StreamDownloadFunction，JSON 路由映射为 core CreateApiFunction。
+ *
+ * @typeParam TRoutes - 路由定义集合类型
+ */
+type ReactApi<TRoutes extends Record<string, RouteDefinition>> = { [K in keyof TRoutes]: TRoutes[K] extends StreamResponseRoute ? StreamDownloadFunction<TRoutes[K]> : CreateApiFunction<TRoutes[K]> };
+/**
+ * 流式 fetch 配置
+ *
+ * 提供 react 场景流式 fetch 所需的配置项（与 react 应用环境一致）。
+ */
+type StreamFetchConfig = {
+  /**
+   * API 基础 URL
+   */
+  baseUrl: string;
+  /**
+   * 自定义请求头
+   */
+  headers?: Record<string, string>;
+  /**
+   * Token 提供者（用于 Authorization 头）
+   */
+  tokenProvider?: TokenProvider;
+  /**
+   * CSRF 提供者（用于 X-CSRF-Token 头）
+   */
+  csrfProvider?: CsrfProvider;
+  /**
+   * 自定义 fetch 函数（依赖注入，测试时可 mock）
+   *
+   * 省略时用全局 fetch。
+   */
+  fetch?: typeof fetch;
+};
+/**
+ * 创建流式下载函数
+ *
+ * 工厂模式：创建时绑定路由定义与配置，返回的函数发起 fetch 请求并返回 Blob。
+ * 错误路径（4xx/5xx）按 JSON 解析 ApiResponse 错误信封抛出。
+ *
+ * @typeParam TRoute - 流式路由定义类型
+ * @param route - 流式路由定义
+ * @param config - 流式 fetch 配置
+ * @returns 流式下载函数，返回 Promise<Blob>
+ * @throws {@link Error} 类型断言失败时抛出
+ */
+declare function createStreamDownloadFunction<TRoute extends StreamResponseRoute>(route: TRoute, config: StreamFetchConfig): StreamDownloadFunction<TRoute>;
+/**
+ * 创建 react API 客户端 factory
+ *
+ * 返回的 factory 接受 routes 集合，生成 ReactApi：
+ * - JSON 路由：复用 core createApiClientFactory，走 HttpClient.request（JSON 解析 + safeParse）
+ * - 流式路由：走独立的 fetch + blob 路径，返回 Promise<Blob>
+ *
+ * react adapter 独立提供此能力，不依赖 preset-browser。react 应用（浏览器、React Native、
+ * Electron renderer）均可使用。
+ *
+ * @param client - core HttpClient（用于 JSON 路由）
+ * @param streamConfig - 流式 fetch 配置（baseUrl / headers / tokenProvider / csrfProvider）
+ * @returns API factory，接受 routes 返回 ReactApi
+ * @throws {@link Error} 类型断言失败时抛出
+ *
+ * @example
+ *   ```typescript
+ *   const factory = createReactApiClientFactory(client, {
+ *     baseUrl: '/api',
+ *     tokenProvider: { getToken: () => localStorage.getItem('token') },
+ *   });
+ *   const api = factory(orderRoutes);
+ *
+ *   // JSON 路由：Promise<ApiResponse<Order>>
+ *   const order = await api.detail({ id: '123' });
+ *
+ *   // 流式路由：Promise<Blob>
+ *   const blob = await api.downloadExport({ taskId: 'abc' });
+ *   ```
+ */
+declare function createReactApiClientFactory(client: HttpClient, streamConfig: StreamFetchConfig): <TRoutes extends Record<string, RouteDefinition>>(routes: TRoutes) => ReactApi<TRoutes>;
+//#endregion
+export { type ExtractPageItem, type InferStreamRouteResponse, 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, type ReactApi, type StreamDownloadFunction, type StreamFetchConfig, createConfigurableMockHttpClient, createDelayedMockHttpClient, createErrorMockHttpClient, createInfiniteHook, createMockHttpClient, createMutationHook, createQueryHook, createReactApiClientFactory, createRouteMock, createStreamDownloadFunction };

package/dist/index.js

@@ -1 +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};
+import e from"swr";import{buildPath as t,createApiClientFactory as n,createConfigurableMockHttpClient as r,createDelayedMockHttpClient as i,createErrorMockHttpClient as a,createMockHttpClient as o,createRouteMock as s,isStreamRoute as c,isType as l}from"@longzai-intelligence-transport/http-core";import{useCallback as u,useState as d}from"react";import f from"swr/infinite";function p(e,t,n){let r=[e.method,e.path];return t&&r.push(t),n&&r.push(n),r}function m(e){return`params`in e&&e.params!==void 0}function h(e){return`query`in e&&e.query!==void 0}function g(t,n,r,i,a){return e(p(t,l(r)?r:void 0,l(i)?i:void 0),()=>n.request({route:t,params:l(r)?r:void 0,query:l(i)?i:void 0}),a)}function _(t,n,r,i){return e(p(t,l(r)?r:void 0),()=>n.request({route:t,params:l(r)?r:void 0}),i)}function v(t,n,r,i){return e(r?p(t,void 0,l(r)?r:void 0):null,()=>n.request({route:t,query:l(r)?r:void 0}),i)}function y(t,n,r){return e(p(t),()=>n.request({route:t}),r)}function b(e,t){let n=m(e),r=h(e);if(n&&r){let n=(n,r,i)=>g(e,t,n,r,i);if(l(n))return n}if(n){let n=(n,r)=>_(e,t,n,r);if(l(n))return n}if(r){let n=(n,r)=>v(e,t,n,r);if(l(n))return n}let i=n=>y(e,t,n);if(l(i))return i;throw Error(`无法创建 Query Hook：路由配置不合法`)}function x(e){return`params`in e&&e.params!==void 0}function S(e){return`body`in e&&e.body!==void 0}function C(e,t,n,r,i){if(n&&r){let[n,r]=i;return t.request({route:e,params:l(n)?n:void 0,body:l(r)?r:void 0})}if(n){let[n]=i;return t.request({route:e,params:l(n)?n:void 0})}if(r){let[n]=i;return t.request({route:e,body:l(n)?n:void 0})}return t.request({route:e})}function w(e,t){let n=x(e),r=S(e);return()=>{let[i,a]=d(!1),[o,s]=d(void 0),[c,l]=d(void 0);return{trigger:u(async(...i)=>{a(!0),l(void 0);try{let a=await C(e,t,n,r,i);return s(a),a}catch(e){let t=e instanceof Error?e:Error(String(e));throw l(t),t}finally{a(!1)}},[t]),isMutating:i,data:o,error:c,reset:u(()=>{a(!1),s(void 0),l(void 0)},[])}}}function T(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 E(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 D(e,t,n,r){return async i=>{let a=i[n?2:1],o=await t.request({route:e,params:n&&l(r)?r:void 0,query:l(a)?a:void 0});return l(o)?o:{success:!1,data:null,message:`分页数据类型不匹配`,timestamp:Date.now()}}}function O(e,t,n){let r=`params`in e&&e.params!==void 0,i=n?.paginationMode??`page`,a=n?.defaultPageSize??20,o=(n,o)=>f((t,r)=>i===`page`?T(e,n,t,r):i===`cursor`?E(e,n,r,a):null,D(e,t,r,n),o);if(l(o))return o;throw Error(`无法创建 Infinite Hook：路由配置不合法`)}function k(e,n){let r=async(r,i)=>{let a=n.baseUrl+t(e.path,r,i),o={...n.headers};if(n.tokenProvider){let e=await n.tokenProvider.getToken();e!==null&&(o.Authorization=`Bearer ${e}`)}if(n.csrfProvider){let e=await n.csrfProvider.getToken();e!==null&&(o[`X-CSRF-Token`]=e)}let s=await(n.fetch??fetch)(a,{headers:o});if(!s.ok)throw await s.json();return s.blob()};if(l(r))return r;throw Error(`流式下载函数构建失败`)}function A(e,t){let r=n(e);return e=>{let n={...r(e)};for(let[r,i]of Object.entries(e))i&&c(i)&&(n[r]=k(i,t));if(l(n))return n;throw Error(`API 客户端构建失败`)}}export{r as createConfigurableMockHttpClient,i as createDelayedMockHttpClient,a as createErrorMockHttpClient,O as createInfiniteHook,o as createMockHttpClient,w as createMutationHook,b as createQueryHook,A as createReactApiClientFactory,s as createRouteMock,k as createStreamDownloadFunction};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@longzai-intelligence-transport/http-adapter-react",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "keywords": [
     "adapter",
     "hook",
@@ -38,7 +38,7 @@
     "clean": "rimraf dist out .cache"
   },
   "dependencies": {
-    "@longzai-intelligence-transport/http-core": "0.1.0"
+    "@longzai-intelligence-transport/http-core": "0.1.1"
   },
   "devDependencies": {
     "@testing-library/react": "^16.3.2",