@snail-js/api 0.1.2 → 0.1.4

package/README.md

@@ -2,6 +2,7 @@
   <img src="https://img.shields.io/badge/TypeScript-1e80ff"></img>
   <img src="https://img.shields.io/npm/v/axios?label=axios&labelColor=1e80ff&color=67C23A"></img>
 </p>
+
 ## 项目介绍
 
 - 基于 Axios 二次封装
@@ -48,6 +49,7 @@ import { Snail, Server } from "@snail-js/api";
   timeout: 5000,
 })
 class BackEnd extends Snail {}
+
 export const Service = new BackEnd();
 ```
 
@@ -88,16 +90,17 @@ if (error !== null) {
 - `baseUrl`：同`Axios`，使用`vite.proxy`时，请使用`\`开头，直接跨域请求请填写完整地址
 - `Versioning`:版本管理器
   - type:管理器类型，enum:Uri,Head,Query,Custom
-  - prifix:前缀
+  - prifix:前缀,字符串；添加在版本号前面的字符，默认为`v`
   - defaultVersion:全局默认版本
 - timenout:全局超时时间，会被 Api 的 timeout 值覆盖
 - CacheManage：缓存管理器
-  - type:缓存管理器类型，CacheType,enum:localStorage,IndexDB,Memory
+  - type:缓存管理器类型，CacheType,`enum:localStorage,IndexDB,Memory`
   - ttl: 缓存过期时间
+- enableLog: 是否打印日志
 
 ## Api 配置
 
-- url?: api 请求端点，与 Server 中的`baseUrl`拼接请求地址，，不要使用`/`开头
+- url?: api 请求端点，与 Server 中的`baseUrl`拼接请求地址，不要使用`/`开头
 - timeout?: 请求超时时间;会覆盖`Server.timeout`
 - version?: 请求版本，会覆盖`Server.Versioning.defaultVersion`;
 
@@ -287,6 +290,8 @@ export type VersioningOption =
 
 ### 临时版本修改器`@Version`
 
+- 临时改变方法请求的版本
+
 ```typescript
 @Api("test")
 class Test {
@@ -299,12 +304,106 @@ class Test {
 > 临时改变 api 版本，便于测试
 
 ### 缓存装饰器`@Cache`
-- 待测试，测试后发布文档
+
+- `@Cache(string | null)`
+- 当设置为 null 时，此方法不应用缓存
+- 当设置为 string 时，应为此 Api 类下的方法名称，当设置的此名称方法被调用且正常响应时，被装饰的方法缓存失效
+
+```typescript
+@Api("test")
+class Test {
+  @Get("HelloWorld")
+  @Cache("test2")
+  test1() {}
+
+  @Post()
+  test2() {}
+
+  @Get()
+  @Cache(null)
+  test3() {}
+}
+```
+
+> 当请求`[Post]test`成功时，`[Get]test/HelloWorld`的缓存失效
+> 注意：`test2`方法请求成功的前提是需要设置`@Cache(null)`,否则仅第一次请求会发送，后续请求需等待缓存管理设置的 ttl 时间到期才会发送请求
+> 因此，若未设置`test2`方法的`@Cache(null)`，仅第一次请求会使`[Get]test/HelloWorld`的缓存失效，后续需等待 ttl 时间到期，才会继续失效
+
+> `test3`方法请求成功时，不缓存
+
+> 注意：要使用缓存，请配置`@Server({CacheManage})`缓存管理器
+
+### 上传进度装饰器`@UploadProgress`
+
+- `@UploadProgress((progress: AxiosProgressEvent) => void)`
+
+## Server Send Event 服务端推送
+
+### 创建 sse 端点
+
+```typescript
+@Api("sse")
+class ServerSend {
+  @Sse()
+  create() {}
+
+  @OnSseOpen()
+  handleOpen(event: Event) {
+    console.log("sse-open:", event);
+  }
+
+  @OnSseError()
+  handleError(event: Event) {
+    console.log("sse-error:", event);
+  }
+
+  // 处理默认message事件
+  @SseEvent()
+  handleEvent(event: MessageEvent) {
+    console.log("sse-event[message]:", event.data);
+  }
+
+  // 处理自定义名称事件
+  @SseEvent("chunk")
+  handleEvent(event: Event) {
+    console.log("sse-event[chunk]:", event);
+  }
+}
+
+export const Sse = Service.createSse(ServerSend);
+```
+
+### 服务端推送装饰器`@Sse`
+- `@Sse(path:string,options:{withCredentials: boolean})`
+- 创建一个服务端推送连接，当被装饰的方法调用时打开连接
+- 被装饰的方法调用后会返回`{eventSource:EventSource,close:function}`
+ - 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`，注册为对应名称的事件处理器
+
 
 ### 代码仓库
 
-- ![Static Badge](https://img.shields.io/badge/snail-js?style=flat&label=gitee&labelColor=F56C6C&link=https%3A%2F%2Fgitee.com%2Flimich%2Fsnail)
-- ![Static Badge](https://img.shields.io/badge/snail-js?style=flat&label=github&labelColor=F56C6C&link=https%3A%2F%2Fgihub.com%2Flimingchang%2Fsnail)
+<p>
+  <a src="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">
+    <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,5 +1,5 @@
 import "reflect-metadata";
-import { Strategy, ApiProxy, ResponseData } from "../typings";
+import { Strategy, ApiProxy, SseProxy, ResponseData } from "../typings";
 export declare class Snail<R extends {
     data: any;
 } = ResponseData> {
@@ -7,14 +7,28 @@ export declare class Snail<R extends {
     private strategies;
     private cacheStorage?;
     private version?;
+    private sourceMap;
+    private eventSource;
     registerStrategy(strategy: Strategy): void;
     createApi<T extends object>(constructor: new () => T): ApiProxy<T, R>;
     private buildRequestArgs;
     private getStrategies;
     private applyStrategies;
     private applyVersion;
-    private applyCache;
-    private getCacheConfig;
+    private getCache;
+    private initCacheManage;
+    private getHitSource;
+    private setHitSource;
+    private setCache;
+    private expireCache;
+    private getServerConfig;
+    private getApiConfig;
+    private initAxios;
+    private generateSseUrl;
     private handleResponse;
     private handleError;
+    createSse<T extends object>(constructor: new () => T): SseProxy<T>;
+    private initSse;
+    private setSse;
+    private registerSseEvent;
 }

package/dist/decorators/api.d.ts

@@ -1,12 +1,40 @@
 import "reflect-metadata";
 import { ApiConfig } from "../typings";
-export declare const METHOD_KEY = "SNAIL_METHOD_KEY";
-export declare const API_CONFIG_KEY = "SNAIL_API_CONFIG_KEY";
+export declare const METHOD_KEY: unique symbol;
+export declare const API_CONFIG_KEY: unique symbol;
 export declare const Api: (url?: string, config?: ApiConfig) => ClassDecorator;
+/**
+ * 定义装饰的方法为Get请求
+ * @param path 字符型，请求端点，默认为空
+ */
 export declare const Get: (path?: string) => (target: any, propertyKey: string | symbol) => void;
+/**
+ * 定义装饰的方法为Post请求
+ * @param path 字符型，请求端点，默认为空
+ */
 export declare const Post: (path?: string) => (target: any, propertyKey: string | symbol) => void;
+/**
+ * 定义装饰的方法为Put请求
+ * @param path 字符型，请求端点，默认为空
+ */
 export declare const Put: (path?: string) => (target: any, propertyKey: string | symbol) => void;
+/**
+ * 定义装饰的方法为Delete请求
+ * @param path 字符型，请求端点，默认为空
+ */
 export declare const Delete: (path?: string) => (target: any, propertyKey: string | symbol) => void;
+/**
+ * 定义装饰的方法为Patch请求
+ * @param path 字符型，请求端点，默认为空
+ */
 export declare const Patch: (path?: string) => (target: any, propertyKey: string | symbol) => void;
+/**
+ * 定义装饰的方法为Options请求
+ * @param path 字符型，请求端点，默认为空
+ */
 export declare const Options: (path?: string) => (target: any, propertyKey: string | symbol) => void;
+/**
+ * 定义装饰的方法为Head请求
+ * @param path 字符型，请求端点，默认为空
+ */
 export declare const Head: (path?: string) => (target: any, propertyKey: string | symbol) => void;

package/dist/decorators/cache.d.ts

@@ -1,4 +1,10 @@
 import "reflect-metadata";
-import { CacheManagementOption } from '../typings';
-export declare const CACHE_KEY = "SNALI_CACHE_KEY";
-export declare const Cache: (options: CacheManagementOption) => (target: any, propertyKey?: string) => void;
+export declare const CACHE_OPTIONS_KEY: unique symbol;
+/**
+ * 为请求方法设置失效源，或设置不启用缓存
+ * @param hitSource 失效源，字符型|null；
+ * - 设置为null时，该请求方法不启用缓存；
+ * - 设置为字符时，对应该Api下请求方法名称，当设置的名称方法请求成功时，被装饰的请求方法缓存失效
+ * @returns
+ */
+export declare const Cache: (hitSource: string | null) => (target: any, propertyKey?: string) => void;

package/dist/decorators/param.d.ts

@@ -1,4 +1,14 @@
 import "reflect-metadata";
 export declare const REQUEST_ARGS_KEY: unique symbol;
+/**
+ * 将被装饰的参数定义为查询参数
+ * @param key 可选，查询参数的key，未给定key，则被装饰的参数应为对象
+ * @returns
+ */
 export declare const Params: (key?: string) => (target: any, propertyKey: string | symbol, parameterIndex: number) => void;
-export declare const Data: () => (target: any, propertyKey: string | symbol, parameterIndex: number) => void;
+/**
+ * 将被装饰的参数定义为请求数据
+ * @param key 可选，请求data的key，未给定key，则被装饰的参数应为对象
+ * @returns
+ */
+export declare const Data: (key?: string) => (target: any, propertyKey: string | symbol, parameterIndex: number) => void;

package/dist/decorators/progress.d.ts

@@ -0,0 +1,4 @@
+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;

package/dist/decorators/server.d.ts

@@ -1,4 +1,9 @@
 import "reflect-metadata";
 import { SnailOption } from "../typings";
-export declare const SERVER_CONFIG_KEY = "SANIL_SERVER_CONFIG_KEY";
+export declare const SERVER_CONFIG_KEY: unique symbol;
+/**
+ * 装饰一个继承Snail 的 class，创建后端交互基本实例
+ * @param config @type SnailOption
+ * @returns
+ */
 export declare const Server: (config: SnailOption) => (target: any) => void;

package/dist/decorators/sse.d.ts

@@ -0,0 +1,31 @@
+import "reflect-metadata";
+export declare const EVENT_SOURCE_OPTION_KEY: unique symbol;
+/**
+ * 将装饰的方法创建为SSE连接
+ * @param path 路径，要连接到服务端sse端点路径
+ * @param options 配置选项
+ * @returns 调用被装饰的方法可获得返回{close,eventSource}
+ */
+export declare const Sse: (path?: string, options?: {
+    withCredentials: boolean;
+}) => (target: any, propertyKey: string) => void;
+export declare const EVENT_SOURCE_EVENTS_KEY: unique symbol;
+/**
+ * 将装饰的方法注册为eventSource的对应事件
+ * @param eventName 事件名称，可选，默认处理message事件
+ * @param options boolean | AddEventListenerOptions 可选，注册事件选项
+ * @returns
+ */
+export declare const SseEvent: (eventName?: string, options?: boolean | AddEventListenerOptions) => (target: any, propertyKey: string) => void;
+export declare const EVENT_SOURCE_OPEN_KEY: unique symbol;
+/**
+ * 将装饰的方法注册为eventSource.onOpen
+ * @returns
+ */
+export declare const OnSseOpen: () => (target: any, propertyKey: string) => void;
+export declare const EVENT_SOURCE_ERROR_KEY: unique symbol;
+/**
+ * 将装饰的方法注册eventSource.onError
+ * @returns
+ */
+export declare const OnSseError: () => (target: any, propertyKey: string) => void;

package/dist/decorators/strategy.d.ts

@@ -1,4 +1,10 @@
 import "reflect-metadata";
 import { Strategy } from "../typings";
 export declare const STRATEGY_KEY: unique symbol;
+/**
+ * 策略装饰器，为请求添加请求策略或响应策略
+ * @param strategies @type Strategy[]
+ * - 传入的策略请使用new 实例化
+ * @returns
+ */
 export declare const UseStrategy: (...strategies: Strategy[]) => (target: any, propertyKey?: string) => void;

package/dist/decorators/versioning.d.ts

@@ -2,5 +2,15 @@ import "reflect-metadata";
 import { VersioningOption } from "../typings";
 export declare const VERSIONING_KEY: unique symbol;
 export declare const VERSION_KEY: unique symbol;
+/**
+ * 版本管理装饰器,为请求设置全局版本管理器
+ * @param options 版本管理选项
+ * @returns
+ */
 export declare const Versioning: (options: VersioningOption) => (target: any) => void;
+/**
+ * 为方法设置版本
+ * @param version 字符型，临时设置被装饰的请求版本
+ * @returns
+ */
 export declare const Version: (version: string) => (target: any, propertyKey: string) => void;

package/dist/index.d.ts

@@ -1,9 +1,10 @@
 export * from "./core";
-export * from "./decorators/server";
-export * from "./decorators/api";
-export * from "./decorators/cache";
-export * from "./decorators/param";
-export * from "./decorators/strategy";
-export * from "./decorators/versioning";
+export { Server } from "./decorators/server";
+export { Api, Get, Put, Post, Patch, Options, Head, Delete, } from "./decorators/api";
+export { Cache } from "./decorators/cache";
+export { Params, Data } from "./decorators/param";
+export { UseStrategy } from "./decorators/strategy";
+export { Versioning, Version } from "./decorators/versioning";
+export { Sse, SseEvent, OnSseError, OnSseOpen } from "./decorators/sse";
 export * from "./typings";
 export * from "./utils";