@snail-js/api 0.1.4 → 0.1.6

package/README.md

@@ -335,7 +335,11 @@ class Test {
 
 ### 上传进度装饰器`@UploadProgress`
 
-- `@UploadProgress((progress: AxiosProgressEvent) => void)`
+- `@UploadProgress((progressEvent: AxiosProgressEvent) => void)`
+
+### 下载进度装饰器`@DownloadProgress`
+
+- `@DownloadProgress((progressEvent: AxiosProgressEvent) => void)`
 
 ## Server Send Event 服务端推送
 
@@ -374,33 +378,126 @@ 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}
+```
 
 ### 代码仓库
 
 <p>
-  <a src="https://gitee.com/limich/snail">
+  <a href="https://gitee.com/limich/snail">
     <img src="https://img.shields.io/badge/snail-js?style=flat&label=gitee&labelColor=F56C6C&link=https%3A%2F%2Fgitee.com%2Flimich%2Fsnail"></img>
   </a>
 </p>
 <p>
-  <a src="https://github.com/limingchang/snail">
+  <a href="https://github.com/limingchang/snail">
     <img src="https://img.shields.io/badge/snail-js?style=flat&label=github&labelColor=F56C6C&link=https%3A%2F%2Fgihub.com%2Flimingchang%2Fsnail"></img>
   </a>
 </p>

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/decorators/progress.d.ts

@@ -1,4 +1,6 @@
 import "reflect-metadata";
 import { AxiosProgressEvent } from "axios";
 export declare const UPLOAD_PROGRESS_KEY: unique symbol;
-export declare const UploadProgress: (handler: (progress: AxiosProgressEvent) => void) => (target: any, propertyKey: string) => void;
+export declare const UploadProgress: (handler: (progressEvent: AxiosProgressEvent) => void) => (target: any, propertyKey: string) => void;
+export declare const DOWNLOAD_PROGRESS_KEY: unique symbol;
+export declare const DownloadProgress: (handler: (progressEvent: AxiosProgressEvent) => void) => (target: any, propertyKey: string) => void;

package/dist/snail-api.js

@@ -3816,6 +3816,7 @@ const Cache = (hitSource) => {
   };
 };
 const UPLOAD_PROGRESS_KEY = Symbol("SNAIL_UPLOAD_PROGRESS_KEY");
+const DOWNLOAD_PROGRESS_KEY = Symbol("SNAIL_DOWNLOAD_PROGRESS_KEY");
 const EVENT_SOURCE_OPTION_KEY = Symbol("SNAIL_EVENT_SOURCE_OPTION_KEY");
 const Sse = (path, options) => {
   return (target, propertyKey) => {
@@ -3931,15 +3932,29 @@ class Snail {
             target,
             propertyKey
           );
+          const onDownloadProgress = Reflect.getMetadata(
+            DOWNLOAD_PROGRESS_KEY,
+            target,
+            propertyKey
+          );
           try {
             enableLog && console.log("send request:", request);
             const response = await this.axiosInstance({
               ...request,
-              onUploadProgress
+              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);
           }
@@ -4017,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

@@ -3820,6 +3820,7 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
     };
   };
   const UPLOAD_PROGRESS_KEY = Symbol("SNAIL_UPLOAD_PROGRESS_KEY");
+  const DOWNLOAD_PROGRESS_KEY = Symbol("SNAIL_DOWNLOAD_PROGRESS_KEY");
   const EVENT_SOURCE_OPTION_KEY = Symbol("SNAIL_EVENT_SOURCE_OPTION_KEY");
   const Sse = (path, options) => {
     return (target, propertyKey) => {
@@ -3935,15 +3936,29 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
               target,
               propertyKey
             );
+            const onDownloadProgress = Reflect.getMetadata(
+              DOWNLOAD_PROGRESS_KEY,
+              target,
+              propertyKey
+            );
             try {
               enableLog && console.log("send request:", request);
               const response = await this.axiosInstance({
                 ...request,
-                onUploadProgress
+                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);
             }
@@ -4021,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@snail-js/api",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Http Request with Decorators Api, build on axios",
   "type": "module",
   "main": "./src/index.ts",