@snail-js/api 0.1.3 → 0.1.5

package/README.md

@@ -4,11 +4,13 @@
 </p>
 
 ## 项目介绍
+
 - 基于 Axios 二次封装
 - 使用`reflect-metadata`创建和处理元数据
 - 提供装饰器方式定义请求，基本实例`Snail`，请求实例`Api`
 
 ## 安装
+
 `npm install @snail-js/api`
 
 ## 使用
@@ -61,7 +63,6 @@ import { Service } from "./service";
 
 @Api("user")
 class UserApi {
-
   @Get()
   get(@Params("id") id: string) {}
 
@@ -95,11 +96,11 @@ if (error !== null) {
 - CacheManage：缓存管理器
   - type:缓存管理器类型，CacheType,`enum:localStorage,IndexDB,Memory`
   - ttl: 缓存过期时间
-- enableLog:  是否打印日志
+- enableLog: 是否打印日志
 
 ## Api 配置
 
-- url?: api 请求端点，与 Server 中的`baseUrl`拼接请求地址，，不要使用`/`开头
+- url?: api 请求端点，与 Server 中的`baseUrl`拼接请求地址，不要使用`/`开头
 - timeout?: 请求超时时间;会覆盖`Server.timeout`
 - version?: 请求版本，会覆盖`Server.Versioning.defaultVersion`;
 
@@ -119,7 +120,6 @@ if (error !== null) {
 ```typescript
 @Api("user")
 class UserApi {
-
   @Get()
   get(@Params("id") id: string, @Params("sign") sign: string) {}
 }
@@ -137,7 +137,6 @@ class QueryParams {
 
 @Api("user")
 class UserApi {
-
   @Get()
   get(@Params() params: QueryParams) {}
 }
@@ -155,7 +154,6 @@ class QueryParams {
 
 @Api("user")
 class UserApi {
-
   @Get()
   get(@Params() params: QueryParams, @Params("a") a: number) {}
 }
@@ -291,11 +289,12 @@ export type VersioningOption =
 ```
 
 ### 临时版本修改器`@Version`
+
 - 临时改变方法请求的版本
+
 ```typescript
 @Api("test")
 class Test {
-
   @Get("HelloWorld")
   @Version("0.2.0")
   test() {}
@@ -305,15 +304,14 @@ class Test {
 > 临时改变 api 版本，便于测试
 
 ### 缓存装饰器`@Cache`
+
 - `@Cache(string | null)`
- - 当设置为null时，此方法不应用缓存
- - 当设置为string时，应为此Api类下的方法名称，当设置的此名称方法被调用且正常响应时，被装饰的方法缓存失效
+- 当设置为 null 时，此方法不应用缓存
+- 当设置为 string 时，应为此 Api 类下的方法名称，当设置的此名称方法被调用且正常响应时，被装饰的方法缓存失效
 
 ```typescript
-
 @Api("test")
 class Test {
-
   @Get("HelloWorld")
   @Cache("test2")
   test1() {}
@@ -328,17 +326,88 @@ class Test {
 ```
 
 > 当请求`[Post]test`成功时，`[Get]test/HelloWorld`的缓存失效
-> 注意：`test2`方法请求成功的前提是需要设置`@Cache(null)`,否则仅第一次请求会发送，后续请求需等待缓存管理设置的ttl时间到期才会发送请求
-> 因此，若未设置`test2`方法的`@Cache(null)`，仅第一次请求会使`[Get]test/HelloWorld`的缓存失效，后续需等待ttl时间到期，才会继续失效
+> 注意：`test2`方法请求成功的前提是需要设置`@Cache(null)`,否则仅第一次请求会发送，后续请求需等待缓存管理设置的 ttl 时间到期才会发送请求
+> 因此，若未设置`test2`方法的`@Cache(null)`，仅第一次请求会使`[Get]test/HelloWorld`的缓存失效，后续需等待 ttl 时间到期，才会继续失效
 
 > `test3`方法请求成功时，不缓存
 
 > 注意：要使用缓存，请配置`@Server({CacheManage})`缓存管理器
 
+### 上传进度装饰器`@UploadProgress`
+
+- `@UploadProgress((progressEvent: AxiosProgressEvent) => void)`
+
+### 下载进度装饰器`@DownloadProgress`
+
+- `@DownloadProgress((progressEvent: 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 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 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,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> {
@@ -8,6 +8,7 @@ export declare class Snail<R extends {
     private cacheStorage?;
     private version?;
     private sourceMap;
+    private eventSource;
     registerStrategy(strategy: Strategy): void;
     createApi<T extends object>(constructor: new () => T): ApiProxy<T, R>;
     private buildRequestArgs;
@@ -23,6 +24,11 @@ export declare class Snail<R extends {
     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

@@ -3,10 +3,38 @@ import { ApiConfig } from "../typings";
 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,3 +1,10 @@
 import "reflect-metadata";
 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,6 @@
+import "reflect-metadata";
+import { AxiosProgressEvent } from "axios";
+export declare const UPLOAD_PROGRESS_KEY: unique symbol;
+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/decorators/server.d.ts

@@ -1,4 +1,9 @@
 import "reflect-metadata";
 import { SnailOption } from "../typings";
 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

@@ -5,5 +5,6 @@ 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";

package/dist/snail-api.js

@@ -3682,6 +3682,13 @@ var CacheType = /* @__PURE__ */ ((CacheType2) => {
 })(CacheType || {});
 class Strategy {
 }
+class RegisterSseEvent {
+  constructor() {
+    __publicField(this, "eventName");
+    __publicField(this, "emit");
+    __publicField(this, "options");
+  }
+}
 function createCache(type, ttl) {
   if (type === CacheType.Memory) {
     return new MemoryCache(ttl);
@@ -3781,7 +3788,7 @@ const UseStrategy = (...strategies) => {
 };
 const REQUEST_ARGS_KEY = Symbol("SNAIL_REQUEST_ARGS_KEY");
 const Params = (key) => createArgsDecorator("params", key);
-const Data = () => createArgsDecorator("data");
+const Data = (key) => createArgsDecorator("data", key);
 const createArgsDecorator = (type, key) => {
   return (target, propertyKey, parameterIndex) => {
     const args = Reflect.getMetadata(REQUEST_ARGS_KEY, target, propertyKey) || [];
@@ -3808,6 +3815,46 @@ const Cache = (hitSource) => {
     Reflect.defineMetadata(key, hitSource, target);
   };
 };
+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) => {
+    Reflect.defineMetadata(
+      EVENT_SOURCE_OPTION_KEY,
+      {
+        path,
+        withCredentials: options == null ? void 0 : options.withCredentials
+      },
+      target,
+      propertyKey
+    );
+  };
+};
+const EVENT_SOURCE_EVENTS_KEY = Symbol("EVENT_SOURCE_EVENTS_KEY");
+const SseEvent = (eventName, options) => {
+  return (target, propertyKey) => {
+    const events = Reflect.getMetadata(EVENT_SOURCE_EVENTS_KEY, target) || [];
+    events.push({
+      eventName: eventName ? eventName : "message",
+      emit: target[propertyKey],
+      options
+    });
+    Reflect.defineMetadata(EVENT_SOURCE_EVENTS_KEY, events, target);
+  };
+};
+const EVENT_SOURCE_OPEN_KEY = Symbol("EVENT_SOURCE_OPEN_KEY");
+const OnSseOpen = () => {
+  return (target, propertyKey) => {
+    Reflect.defineMetadata(EVENT_SOURCE_OPEN_KEY, target[propertyKey], target);
+  };
+};
+const EVENT_SOURCE_ERROR_KEY = Symbol("EVENT_SOURCE_ERROR_KEY");
+const OnSseError = () => {
+  return (target, propertyKey) => {
+    Reflect.defineMetadata(EVENT_SOURCE_ERROR_KEY, target[propertyKey], target);
+  };
+};
 class Snail {
   constructor() {
     __publicField(this, "axiosInstance");
@@ -3816,6 +3863,7 @@ class Snail {
     __publicField(this, "cacheStorage");
     __publicField(this, "version");
     __publicField(this, "sourceMap", /* @__PURE__ */ new Map());
+    __publicField(this, "eventSource");
   }
   registerStrategy(strategy) {
     this.strategies.push(strategy);
@@ -3879,9 +3927,23 @@ class Snail {
               return this.handleResponse(cachedResponse, true);
             }
           }
+          const onUploadProgress = Reflect.getMetadata(
+            UPLOAD_PROGRESS_KEY,
+            target,
+            propertyKey
+          );
+          const onDownloadProgress = Reflect.getMetadata(
+            DOWNLOAD_PROGRESS_KEY,
+            target,
+            propertyKey
+          );
           try {
             enableLog && console.log("send request:", request);
-            const response = await this.axiosInstance(request);
+            const response = await this.axiosInstance({
+              ...request,
+              onUploadProgress,
+              onDownloadProgress
+            });
             hitSource !== null && this.setCache(request, response);
             this.expireCache(propertyKey);
             return this.handleResponse(response, false);
@@ -4033,6 +4095,15 @@ class Snail {
       });
     }
   }
+  generateSseUrl(baseURL, url) {
+    if (!baseURL && !url) {
+      return "/";
+    }
+    if (!baseURL && url) {
+      return `/${url}`;
+    }
+    return `${baseURL}/${url}`;
+  }
   handleResponse(response, hitCache) {
     return {
       data: response.data,
@@ -4046,6 +4117,75 @@ class Snail {
       error
     };
   }
+  createSse(constructor) {
+    const instance = new constructor();
+    const serverConfig = this.getServerConfig();
+    const { baseURL, enableLog } = serverConfig;
+    const apiConfig = this.getApiConfig(constructor);
+    enableLog && console.log("ApiConfig:", apiConfig);
+    this.version = apiConfig.version;
+    return new Proxy(instance, {
+      get: (target, propertyKey) => {
+        enableLog && console.log("proxy:", target, "|", propertyKey);
+        if (typeof propertyKey !== "string") return;
+        const sseOption = Reflect.getMetadata(
+          EVENT_SOURCE_OPTION_KEY,
+          target,
+          propertyKey
+        );
+        if (sseOption) {
+          const url = sseOption.path == "" ? apiConfig.url : apiConfig.url + `/${sseOption.path}`;
+          const { url: versionUrl } = this.applyVersion(
+            { url },
+            target,
+            propertyKey
+          );
+          const sseUrl = this.generateSseUrl(baseURL, versionUrl || url);
+          enableLog && console.log("sse-url:", sseUrl);
+          const { eventSource, close } = this.initSse(sseUrl, sseOption);
+          this.eventSource = eventSource;
+          this.setSse(target);
+          this.registerSseEvent(target);
+          return () => {
+            return { eventSource, close };
+          };
+        }
+      }
+    });
+  }
+  initSse(url, options) {
+    const eventSource = new EventSource(url, {
+      withCredentials: options.withCredentials ? options.withCredentials : false
+    });
+    console.log("EventSource:", eventSource);
+    return {
+      eventSource,
+      close: eventSource.close
+    };
+  }
+  setSse(target) {
+    const onOpenFunc = Reflect.getMetadata(EVENT_SOURCE_OPEN_KEY, target);
+    console.log("sse-proxy[open]:", onOpenFunc);
+    if (typeof onOpenFunc == "function") {
+      this.eventSource && (this.eventSource.onopen = onOpenFunc);
+    }
+    const onErrorFunc = Reflect.getMetadata(EVENT_SOURCE_ERROR_KEY, target);
+    console.log("sse-proxy[error]:", onErrorFunc);
+    if (typeof onErrorFunc == "function") {
+      this.eventSource && (this.eventSource.onerror = onErrorFunc);
+    }
+  }
+  registerSseEvent(target) {
+    const eventSource = this.eventSource;
+    if (!eventSource) return;
+    const events = Reflect.getMetadata(
+      EVENT_SOURCE_EVENTS_KEY,
+      target
+    );
+    events.map((event) => {
+      eventSource.addEventListener(event.eventName, event.emit, event.options);
+    });
+  }
 }
 export {
   Api,
@@ -4055,14 +4195,19 @@ export {
   Delete,
   Get,
   Head,
+  OnSseError,
+  OnSseOpen,
   Options,
   Params,
   Patch,
   Post,
   Put,
+  RegisterSseEvent,
   RequestMethod,
   Server,
   Snail,
+  Sse,
+  SseEvent,
   Strategy,
   UseStrategy,
   Version,

package/dist/snail-api.umd.cjs

@@ -3686,6 +3686,13 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
   })(CacheType || {});
   class Strategy {
   }
+  class RegisterSseEvent {
+    constructor() {
+      __publicField(this, "eventName");
+      __publicField(this, "emit");
+      __publicField(this, "options");
+    }
+  }
   function createCache(type, ttl) {
     if (type === CacheType.Memory) {
       return new MemoryCache(ttl);
@@ -3785,7 +3792,7 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
   };
   const REQUEST_ARGS_KEY = Symbol("SNAIL_REQUEST_ARGS_KEY");
   const Params = (key) => createArgsDecorator("params", key);
-  const Data = () => createArgsDecorator("data");
+  const Data = (key) => createArgsDecorator("data", key);
   const createArgsDecorator = (type, key) => {
     return (target, propertyKey, parameterIndex) => {
       const args = Reflect.getMetadata(REQUEST_ARGS_KEY, target, propertyKey) || [];
@@ -3812,6 +3819,46 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
       Reflect.defineMetadata(key, hitSource, target);
     };
   };
+  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) => {
+      Reflect.defineMetadata(
+        EVENT_SOURCE_OPTION_KEY,
+        {
+          path,
+          withCredentials: options == null ? void 0 : options.withCredentials
+        },
+        target,
+        propertyKey
+      );
+    };
+  };
+  const EVENT_SOURCE_EVENTS_KEY = Symbol("EVENT_SOURCE_EVENTS_KEY");
+  const SseEvent = (eventName, options) => {
+    return (target, propertyKey) => {
+      const events = Reflect.getMetadata(EVENT_SOURCE_EVENTS_KEY, target) || [];
+      events.push({
+        eventName: eventName ? eventName : "message",
+        emit: target[propertyKey],
+        options
+      });
+      Reflect.defineMetadata(EVENT_SOURCE_EVENTS_KEY, events, target);
+    };
+  };
+  const EVENT_SOURCE_OPEN_KEY = Symbol("EVENT_SOURCE_OPEN_KEY");
+  const OnSseOpen = () => {
+    return (target, propertyKey) => {
+      Reflect.defineMetadata(EVENT_SOURCE_OPEN_KEY, target[propertyKey], target);
+    };
+  };
+  const EVENT_SOURCE_ERROR_KEY = Symbol("EVENT_SOURCE_ERROR_KEY");
+  const OnSseError = () => {
+    return (target, propertyKey) => {
+      Reflect.defineMetadata(EVENT_SOURCE_ERROR_KEY, target[propertyKey], target);
+    };
+  };
   class Snail {
     constructor() {
       __publicField(this, "axiosInstance");
@@ -3820,6 +3867,7 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
       __publicField(this, "cacheStorage");
       __publicField(this, "version");
       __publicField(this, "sourceMap", /* @__PURE__ */ new Map());
+      __publicField(this, "eventSource");
     }
     registerStrategy(strategy) {
       this.strategies.push(strategy);
@@ -3883,9 +3931,23 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
                 return this.handleResponse(cachedResponse, true);
               }
             }
+            const onUploadProgress = Reflect.getMetadata(
+              UPLOAD_PROGRESS_KEY,
+              target,
+              propertyKey
+            );
+            const onDownloadProgress = Reflect.getMetadata(
+              DOWNLOAD_PROGRESS_KEY,
+              target,
+              propertyKey
+            );
             try {
               enableLog && console.log("send request:", request);
-              const response = await this.axiosInstance(request);
+              const response = await this.axiosInstance({
+                ...request,
+                onUploadProgress,
+                onDownloadProgress
+              });
               hitSource !== null && this.setCache(request, response);
               this.expireCache(propertyKey);
               return this.handleResponse(response, false);
@@ -4037,6 +4099,15 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
         });
       }
     }
+    generateSseUrl(baseURL, url) {
+      if (!baseURL && !url) {
+        return "/";
+      }
+      if (!baseURL && url) {
+        return `/${url}`;
+      }
+      return `${baseURL}/${url}`;
+    }
     handleResponse(response, hitCache) {
       return {
         data: response.data,
@@ -4050,6 +4121,75 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
         error
       };
     }
+    createSse(constructor) {
+      const instance = new constructor();
+      const serverConfig = this.getServerConfig();
+      const { baseURL, enableLog } = serverConfig;
+      const apiConfig = this.getApiConfig(constructor);
+      enableLog && console.log("ApiConfig:", apiConfig);
+      this.version = apiConfig.version;
+      return new Proxy(instance, {
+        get: (target, propertyKey) => {
+          enableLog && console.log("proxy:", target, "|", propertyKey);
+          if (typeof propertyKey !== "string") return;
+          const sseOption = Reflect.getMetadata(
+            EVENT_SOURCE_OPTION_KEY,
+            target,
+            propertyKey
+          );
+          if (sseOption) {
+            const url = sseOption.path == "" ? apiConfig.url : apiConfig.url + `/${sseOption.path}`;
+            const { url: versionUrl } = this.applyVersion(
+              { url },
+              target,
+              propertyKey
+            );
+            const sseUrl = this.generateSseUrl(baseURL, versionUrl || url);
+            enableLog && console.log("sse-url:", sseUrl);
+            const { eventSource, close } = this.initSse(sseUrl, sseOption);
+            this.eventSource = eventSource;
+            this.setSse(target);
+            this.registerSseEvent(target);
+            return () => {
+              return { eventSource, close };
+            };
+          }
+        }
+      });
+    }
+    initSse(url, options) {
+      const eventSource = new EventSource(url, {
+        withCredentials: options.withCredentials ? options.withCredentials : false
+      });
+      console.log("EventSource:", eventSource);
+      return {
+        eventSource,
+        close: eventSource.close
+      };
+    }
+    setSse(target) {
+      const onOpenFunc = Reflect.getMetadata(EVENT_SOURCE_OPEN_KEY, target);
+      console.log("sse-proxy[open]:", onOpenFunc);
+      if (typeof onOpenFunc == "function") {
+        this.eventSource && (this.eventSource.onopen = onOpenFunc);
+      }
+      const onErrorFunc = Reflect.getMetadata(EVENT_SOURCE_ERROR_KEY, target);
+      console.log("sse-proxy[error]:", onErrorFunc);
+      if (typeof onErrorFunc == "function") {
+        this.eventSource && (this.eventSource.onerror = onErrorFunc);
+      }
+    }
+    registerSseEvent(target) {
+      const eventSource = this.eventSource;
+      if (!eventSource) return;
+      const events = Reflect.getMetadata(
+        EVENT_SOURCE_EVENTS_KEY,
+        target
+      );
+      events.map((event) => {
+        eventSource.addEventListener(event.eventName, event.emit, event.options);
+      });
+    }
   }
   exports2.Api = Api;
   exports2.Cache = Cache;
@@ -4058,14 +4198,19 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
   exports2.Delete = Delete;
   exports2.Get = Get;
   exports2.Head = Head;
+  exports2.OnSseError = OnSseError;
+  exports2.OnSseOpen = OnSseOpen;
   exports2.Options = Options;
   exports2.Params = Params;
   exports2.Patch = Patch;
   exports2.Post = Post;
   exports2.Put = Put;
+  exports2.RegisterSseEvent = RegisterSseEvent;
   exports2.RequestMethod = RequestMethod;
   exports2.Server = Server;
   exports2.Snail = Snail;
+  exports2.Sse = Sse;
+  exports2.SseEvent = SseEvent;
   exports2.Strategy = Strategy;
   exports2.UseStrategy = UseStrategy;
   exports2.Version = Version;

package/dist/typings/apiProxy.d.ts

@@ -5,7 +5,7 @@ export type ApiResponse<T> = Promise<{
 export type ApiProxy<T, R extends {
     data: any;
 }> = {
-    [K in keyof T]: T[K] extends (...args: infer A) => any ? <D = any, E = any>(...args: A) => ApiResponse<R & {
+    [K in keyof T]: T[K] extends (...args: infer A) => any ? <D = any>(...args: A) => ApiResponse<R & {
         data: D;
     }> : T[K];
 };

package/dist/typings/index.d.ts

@@ -8,3 +8,4 @@ export * from "./cache.type";
 export * from "./response.data";
 export * from "./strategy";
 export * from "./apiProxy";
+export * from "./sse";

package/dist/typings/sse.d.ts

@@ -0,0 +1,11 @@
+export type SseProxy<T extends object> = {
+    [K in keyof T]: T[K] extends (...args: infer A) => any ? () => {
+        sourceEvent: EventSource;
+        close: Function;
+    } : T[K];
+};
+export declare class RegisterSseEvent {
+    eventName: string;
+    emit: (event: any) => any;
+    options: boolean | AddEventListenerOptions;
+}

package/dist/versioning/versioning.d.ts

@@ -1,8 +1,7 @@
 import { VersioningOption } from "../typings";
-interface VersioningResult {
+export interface VersioningResult {
     url?: string;
     headers?: Record<string, any>;
     params?: Record<string, any>;
 }
 export declare function applyVersioning(version: string, versioning: VersioningOption): VersioningResult;
-export {};

package/package.json

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