@snail-js/api 0.1.5 → 0.1.7

package/README.md

@@ -378,23 +378,116 @@ export const Sse = Service.createSse(ServerSend);
 ```
 
 ### 服务端推送装饰器`@Sse`
+
 - `@Sse(path:string,options:{withCredentials: boolean})`
 - 创建一个服务端推送连接，当被装饰的方法调用时打开连接
 - 被装饰的方法调用后会返回`{eventSource:EventSource,close:function}`
- - eventSource: sse连接实例
- - close: 关闭此sse连接的方法
+- eventSource: sse 连接实例
+- close: 关闭此 sse 连接的方法
 
 ### 注册`onopen`装饰器`@OnSseOpen`
+
 - 当`@Sse`装饰的方法被调用时，将`@OnSseOpen`装饰的方法注册为`@Sse`装饰的方法返回的`EventSource`实例`onopen`处理函数
 
 ### 注册`onerror`装饰器`@OnSseError`
+
 - 当`@Sse`装饰的方法被调用时，将`@OnSseError`装饰的方法注册为`@Sse`装饰的方法返回的`EventSource`实例`onerror`处理函数
 
 ### 事件处理装饰器`@SseEvent`
+
 - `@SseEvent(eventName?:string)`
 - 未传入`eventName`，默认注册为`message`事件处理器
 - 传入`eventName`，注册为对应名称的事件处理器
 
+---
+
+## TypeScript 支持
+
+### 默认返回类型
+
+```typescript
+export interface ResponseData<T = any> {
+  code: 0;
+  message: string;
+  data: T;
+}
+```
+
+### 定义返回类型
+
+1. 定义后端标准数据格式
+
+```typescript
+export class CustomResponse {
+  status_code: number;
+  msg: string;
+}
+```
+
+2. 创建时应用格式
+
+```typescript
+// service.ts
+import { Snail, Server } from "@snail-js/api";
+
+@Server({
+  baseURL: "/api",
+  timeout: 5000,
+})
+class BackEnd extends Snail<CustomResponse> {}
+
+export const Service = new BackEnd();
+```
+
+3. 调用 API 时携带数据格式
+
+```typescript
+import { userApi } from "./user";
+
+class User {
+  id: number;
+  name: string;
+  tel: string;
+  age: number;
+}
+
+const res = await userApi.get<User>("1");
+// 默认情况，以data为key存储数据
+// res.data => CustomResponse & { data : User}
+```
+
+> API 被调用的返回格式
+
+```typescript
+const res = await userApi.get<User>("1");
+
+// res type
+{
+  data: T;
+  error: null | Error
+  hitCache?: boolean
+}
+```
+
+> `data: T`,后端响应数据；默认为`ResponseData<T = any>`类型；可由用户自定义修改
+
+> `error: null | Error` ; 请求过程中的错误包含在此，可先判断 error 是否为 null 再进行数据处理
+
+> `hitCache?: boolean`; 标识请求是否击中缓存；若从缓存获得数据，则不会发送请求。
+
+4. 若后端返回数据不是以 data 为 key 包含数据
+
+```typescript
+@Server({
+  baseURL: "/api",
+  timeout: 5000,
+})
+class BackEnd extends Snail<CustomResponse, "record"> {}
+
+const res = await userApi.get<User>("1");
+// 自定义数据key
+// res.data => CustomResponse & { record : User}
+```
 
 ### 代码仓库
 

package/dist/core/snail.d.ts

@@ -1,8 +1,6 @@
 import "reflect-metadata";
 import { Strategy, ApiProxy, SseProxy, ResponseData } from "../typings";
-export declare class Snail<R extends {
-    data: any;
-} = ResponseData> {
+export declare class Snail<R extends {} = ResponseData, DK extends string = "data"> {
     private axiosInstance;
     private strategies;
     private cacheStorage?;
@@ -10,7 +8,7 @@ export declare class Snail<R extends {
     private sourceMap;
     private eventSource;
     registerStrategy(strategy: Strategy): void;
-    createApi<T extends object>(constructor: new () => T): ApiProxy<T, R>;
+    createApi<T extends object>(constructor: new () => T): ApiProxy<T, R, DK>;
     private buildRequestArgs;
     private getStrategies;
     private applyStrategies;

package/dist/snail-api.js

@@ -3944,9 +3944,17 @@ class Snail {
               onUploadProgress,
               onDownloadProgress
             });
+            const responseStrategies = strategies.filter(
+              (strategy) => strategy.applyResponse
+            );
+            const strategyResponse = await this.applyStrategies(
+              response,
+              responseStrategies,
+              "response"
+            );
             hitSource !== null && this.setCache(request, response);
             this.expireCache(propertyKey);
-            return this.handleResponse(response, false);
+            return this.handleResponse(strategyResponse, false);
           } catch (error) {
             return this.handleError(error);
           }
@@ -4024,16 +4032,9 @@ class Snail {
         statusText: "get response data from cache",
         config: { headers: new AxiosHeaders2() }
       };
-      const responseStrategies = strategies.filter(
-        (strategy) => strategy.applyResponse
-      );
-      const strategyResponse = await this.applyStrategies(
-        cacheResponse,
-        responseStrategies,
-        "response"
-      );
-      return strategyResponse;
+      return cacheResponse;
     }
+    return void 0;
   }
   initCacheManage(options) {
     if (!this.cacheStorage && options !== void 0) {

package/dist/snail-api.umd.cjs

@@ -3948,9 +3948,17 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
                 onUploadProgress,
                 onDownloadProgress
               });
+              const responseStrategies = strategies.filter(
+                (strategy) => strategy.applyResponse
+              );
+              const strategyResponse = await this.applyStrategies(
+                response,
+                responseStrategies,
+                "response"
+              );
               hitSource !== null && this.setCache(request, response);
               this.expireCache(propertyKey);
-              return this.handleResponse(response, false);
+              return this.handleResponse(strategyResponse, false);
             } catch (error) {
               return this.handleError(error);
             }
@@ -4028,16 +4036,9 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
           statusText: "get response data from cache",
           config: { headers: new AxiosHeaders() }
         };
-        const responseStrategies = strategies.filter(
-          (strategy) => strategy.applyResponse
-        );
-        const strategyResponse = await this.applyStrategies(
-          cacheResponse,
-          responseStrategies,
-          "response"
-        );
-        return strategyResponse;
+        return cacheResponse;
       }
+      return void 0;
     }
     initCacheManage(options) {
       if (!this.cacheStorage && options !== void 0) {

package/dist/typings/apiProxy.d.ts

@@ -1,11 +1,11 @@
+import { ResponseData } from "./response.data";
 export type ApiResponse<T> = Promise<{
     data: T | null;
     error: Error | null;
+    hitCache?: boolean;
 }>;
-export type ApiProxy<T, R extends {
-    data: any;
-}> = {
+export type ApiProxy<T, R extends {} = ResponseData, DK extends string = "data"> = {
     [K in keyof T]: T[K] extends (...args: infer A) => any ? <D = any>(...args: A) => ApiResponse<R & {
-        data: D;
+        [KK in DK]: D;
     }> : T[K];
 };

package/dist/typings/response.data.d.ts

@@ -1,17 +1,11 @@
-export interface ResponseErrorData<E> {
-    code: number;
-    message: string;
-    data: E;
-}
 export interface PaginationData<T> {
     total: number;
     page: number;
     size: number;
     record: T[];
 }
-export interface ResponseSuccessData<T> {
+export interface ResponseData<T = any> {
     code: 0;
     message: string;
     data: T | PaginationData<T>;
 }
-export type ResponseData<T = any, E = any> = ResponseSuccessData<T> | ResponseErrorData<E>;

package/dist/typings/sse.d.ts

@@ -1,6 +1,6 @@
 export type SseProxy<T extends object> = {
     [K in keyof T]: T[K] extends (...args: infer A) => any ? () => {
-        sourceEvent: EventSource;
+        eventSource: EventSource;
         close: Function;
     } : T[K];
 };

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@snail-js/api",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "Http Request with Decorators Api, build on axios",
   "type": "module",
   "main": "./src/index.ts",
   "exports": {
     ".": {
-      "import": "./dist/snail-api.mjs",
+      "import": "./dist/snail-api.js",
       "require": "./dist/snail-api.umd.cjs",
       "types": "./dist/index.d.ts"
     }