@snail-js/api 0.1.21 → 0.1.23

package/README.md

@@ -60,7 +60,7 @@ export const Service = new BackEnd();
 
 ```typescript
 // user.ts
-import { Api, Get, Post, Query, Data,SnailApi } from "@snail-js/api";
+import { Api, Get, Post, Query, Data, SnailApi } from "@snail-js/api";
 
 import { Service } from "./service";
 
@@ -81,40 +81,38 @@ export const userApi = Service.createApi(UserApi);
 ```typescript
 import { userApi } from "./user";
 
-const getUser = await userApi.get("1");
-const { send, onSuccess, onError, onHitCache, on } = getUser;
-const data = await send();
+const { send:getUser, onSuccess, onError, onHitCache } = await userApi.get();
+
+const data = await getUser("1");
 ```
 
 ## `SnailMethod` 实例
+
 - 调用`Service.createApi(ApiInstance)`后会为`ApiInstance`内被`RequestMethod`(如：@Get、@Post...)装饰的方法创建一个代理，返回一个函数，此函数包含请求参数，调用此函数返回`SnailMethod` 实例
 
 ### `SnailMethod` 实例方法
 
 - `send` 发送请求
- _异步函数，发送当前请求_
+  _异步函数，发送当前请求_
 - `onSuccess` 请求成功回调
- _注册请求成功事件_
+  _注册请求成功事件_
 - `onError` 请求失败回调
- _注册请求失败事件_
+  _注册请求失败事件_
 - `onHitCache` 请求命中缓存回调
- _注册请求命中缓存事件_
+  _注册请求命中缓存事件_
 - `onFinish` 请求完成回调
- _注册请求完成事件_
-- `on` 监听事件
- _注册自定义事件_
-- `emit` 触发事件
- _触发自定义事件_
-- `off` 取消监听事件
- _取消自定义事件监听_
+  _注册请求完成事件_
+- `registerStrategies` 注册策略
+  _注册方法级策略_
 
 
 ### `SnailMethod` 实例属性
+
 - response : AxiosResponse
-- request : AxiosRequestConfig ,最终请求的request,这个request是被Versioning和Strategy处理过的
-- version : string,最终请求的版本，如果没有开启Versioning则为undefine
-- name : string,完整的SnailMethod名称，格式为`ServerName.ApiName.MethodName`
-- error : Error | null,请求失败的错误信息,无错误为null
+- request : AxiosRequestConfig ,最终请求的 request,这个 request 是被 Versioning 和 Strategy 处理过的
+- version : string,最终请求的版本，如果没有开启 Versioning 则为 undefine
+- name : string,完整的 SnailMethod 名称，格式为`ServerName.ApiName.MethodName`
+- error : Error | null,请求失败的错误信息,无错误为 null
 
 ### Server 配置
 
@@ -188,7 +186,8 @@ const data = await send();
 </table>
 
 ### Api 配置
-- 请使用`@Api()`装饰自定义Api类并继承`SnailApi`
+
+- 请使用`@Api()`装饰自定义 Api 类并继承`SnailApi`
 
 <table>
   <tr>
@@ -305,7 +304,7 @@ class UserApi {
 ### 请求策略
 
 - 在请求发送前执行，后面的策略返回结果会覆盖前面的策略
-- 若返回处理后的request，则使用处理后的 request 发送请求，否则使用原始 request 或上一个策略返回的request发送请求
+- 若返回处理后的 request，则使用处理后的 request 发送请求，否则使用原始 request 或上一个策略返回的 request 发送请求
 
 ```typescript
 class CustomStrategy extends Strategy {
@@ -346,15 +345,16 @@ class Test {
 // 发送请求前注册策略
 const TestApi = Service.createApi(Test);
 const getSomething = TestApi.get();
-getSomething.registerStrategies(CustomStrategy);
 { send, registerStrategies } = getSomething;
+getSomething.registerStrategies(CustomStrategy);
+
 
 ```
 
 ### 响应策略
 
 - 在收到服务器响应后执行
-- 若返回处理后的response，则使用处理后的response进行下一个策略或返回，否则使用原始response或上一个策略返回的response返回
+- 若返回处理后的 response，则使用处理后的 response 进行下一个策略或返回，否则使用原始 response 或上一个策略返回的 response 返回
 
 ```typescript
 // 如何定义
@@ -465,11 +465,11 @@ class Test {
 
 - `@HitSource(name:string)`
 - 为被装饰的方法设置缓存失效源，当设置的名称方法被调用且正常响应时，被装饰的方法缓存失效
-- name格式为：`serverName:apiName:methodName`
-> 注意：若您配置了SnailServer/SnailApi的name选项，请使用此name作为名称，否则使用类名作为名称
+- name 格式为：`serverName:apiName:methodName`
+  > 注意：若您配置了 SnailServer/SnailApi 的 name 选项，请使用此 name 作为名称，否则使用类名作为名称
 
 ```typescript
-@Api("test",{name:'api1'})
+@Api("test", { name: "api1" })
 @HitSource("api1")
 class Test {
   @Get("HelloWorld")
@@ -487,7 +487,7 @@ class Test {
 ```
 
 > 当请求`[Post]test`成功时，`[Get]test/HelloWorld`的缓存失效
-> 默认仅Get方法会进行缓存ing缓存，若要开启其他方法的缓存，请使用`@Server({cacheFor:'all'})`配置
+> 默认仅 Get 方法会进行缓存 ing 缓存，若要开启其他方法的缓存，请使用`@Server({cacheFor:'all'})`配置
 
 > `test3`方法请求成功时，不缓存
 
@@ -611,10 +611,10 @@ class User {
   age: number;
 }
 
-const getUser = userApi.get<User>("1");
+const getUser = userApi.get<User>();
 const { send } = getUser;
 
-const res = await send();
+const res = await send("1");
 
 // 默认情况，以data为key存储数据
 // res.data => CustomResponse & { data : User}
@@ -623,15 +623,15 @@ const res = await send();
 > API 被调用的返回格式
 
 ```typescript
-const getUser = userApi.get<User>("1");
+const getUser = userApi.get<User>();
 const { send } = getUser;
-const res = await send();
+const res = await send("1");
 
 // res.data => CustomResponse & { data: User }
 
-const getUser = userApi.get<Blob>("1");
+const getUser = userApi.get<Blob>();
 const { send } = getUser;
-const res = await send();
+const res = await send("1");
 // res => AxiosResponse<Blob>
 ```
 
@@ -648,16 +648,17 @@ const res = await send();
   baseURL: "/api",
   timeout: 5000,
 })
-class BackEnd extends Snail<CustomResponse, "record"> {}
+class BackEnd extends Snail<CustomResponse, "records"> {}
 
-const res = await userApi.get<User>("1");
+const res = await userApi.get<User>();
 // 自定义数据key
-// res.data => CustomResponse & { record : User}
+// res.data => CustomResponse & { records : User}
 ```
 
-### 非json数据的返回
-- 若后端返回的content-type不是json类型，send方法返回的将是`AxiosResponse`
-- 若后端返回的content-type是json类型，send方法返回的将是`AxiosResponse.data`
+### 非 json 数据的返回
+
+- 若后端返回的 content-type 不是 json 类型，send 方法返回的将是`AxiosResponse`
+- 若后端返回的 content-type 是 json 类型，send 方法返回的将是`AxiosResponse.data`
 
 ### 代码仓库
 

package/README_EN.md

@@ -80,9 +80,9 @@ export const userApi = Service.createApi(UserApi);
 ```ts
 import { userApi } from "./user";
 
-const getUser = await userApi.get("1");
-const { send, onSuccess, onError, onHitCache, on } = getUser;
-const data = await send();
+const { send:getUser, onSuccess, onError, onHitCache } = await userApi.get();
+
+const data = await getUser("1");
 ```
 
 ## `SnailMethod` Instance
@@ -102,13 +102,8 @@ const data = await send();
   _Register cache hit event handler_
 - `onFinish`: Request completion callback  
   _Register completion event handler (fires on both success/error)_
-- `on`: Event listener  
-  _Register custom event handlers_
- _Register custom event handlers_
-- `emit`: Trigger custom events  
-  _Emit custom events_
-- `off`: Remove event listeners  
-  _Unregister custom event handlers_
+- `registerStrategies` Register Strategies
+  _Register Strategies of this method instance_
 
 ### `SnailMethod` Properties
 - `response`: AxiosResponse - Raw response object
@@ -172,6 +167,13 @@ const data = await send();
     <td>Get</td>
     <td>Methods to enable caching</td>
   </tr>
+  <tr>
+    <td>serverStatusCodeRule</td>
+    <td><a href="#SnailServerStatusCodeRuleOptions">SnailServerStatusCodeRuleOptions</a></td>
+    <td>否</td>
+    <td>undefined</td>
+    <td>Server status code validation rules (triggers error when rule function returns false)</td>
+  </tr>
   <tr>
     <td>enableLog</td>
     <td>boolean</td>
@@ -303,8 +305,9 @@ class Test {
 // Register strategy before request
 const TestApi = Service.createApi(Test);
 const getSomething = TestApi.get();
-getSomething.registerStrategies(CustomStrategy);
 { send, registerStrategies } = getSomething;
+registerStrategies(CustomStrategy);
+
 ```
 
 ### Response Strategy
@@ -385,6 +388,18 @@ export type VersioningOption =
   | VersioningCustomOption;
 ```
 
+### <a id="SnailServerStatusCodeRuleOptions">SnailServerStatusCodeRuleOptions</a> Type
+
+```typescript
+export class SnailServerStatusCodeRuleOptions {
+  // Defines validation rules for server status codes
+  // Triggers error when rule function returns false
+  rule: (statusCode: number) => boolean;
+  // Specifies the key in response.data for status code (default: 'code')
+  key?: string;
+}
+```
+
 ### Temporary Version Modifier @Version
 - Override version for specific methods
 ```typescript
@@ -533,10 +548,10 @@ class User {
   age: number;
 }
 
-const getUser = userApi.get<User>("1");
+const getUser = userApi.get<User>();
 const { send } = getUser;
 
-const res = await send();
+const res = await send("1");
 
 // Default data key:
 // res.data => CustomResponse & { data: User }
@@ -544,15 +559,15 @@ const res = await send();
 
 > API response format:
 ```typescript
-const getUser = userApi.get<User>("1");
+const getUser = userApi.get<User>();
 const { send } = getUser;
-const res = await send();
+const res = await send("1");
 
 // res.data => CustomResponse & { data: User }
 
-const getUser = userApi.get<Blob>("1");
+const getUser = userApi.get<Blob>();
 const { send } = getUser;
-const res = await send();
+const res = await send("1");
 // res => AxiosResponse<Blob>
 ```
 
@@ -565,8 +580,8 @@ const res = await send();
 })
 class BackEnd extends Snail<CustomResponse, "record"> {}
 
-const { send } = userApi.get<User>("1");
-const res = await send();
+const { send } = userApi.get<User>();
+const res = await send("1");
 // Custom data key:
 // res.data => CustomResponse & { record: User }
 ```

package/dist/core/snailMethod.d.ts

@@ -1,5 +1,5 @@
 import { AxiosResponse, AxiosRequestConfig } from "axios";
-import { EventHandler, Strategy, ResponseData, SendRequest, StandardResponseData, SnailMethodEventType } from "../typings";
+import { Strategy, ResponseData, StandardResponseData, SnailSuccessListener, SnailErrorListener, SnailHitCacheListener, SnailFinishListener } from "../typings";
 import { SnailApi } from "./snailApi";
 /**
  * SnailMethod
@@ -14,29 +14,24 @@ export declare class SnailMethod<RT extends ResponseData = StandardResponseData>
     private Request;
     private Response;
     private Error;
-    private eventMap;
-    private onceWrapperMap;
+    private EventEmit;
     private propertyKey;
     private Url;
     private Path;
     private Method;
+    private Adapter;
     private Version?;
-    private Args;
-    constructor(apiInstance: SnailApi, target: Object, propertyKey: string | symbol, args?: []);
-    send: SendRequest<RT>;
+    constructor(apiInstance: SnailApi, target: Object, propertyKey: string | symbol);
+    send: (...args: any) => Promise<unknown>;
     private init;
     private initUrl;
     private initVersion;
     private getExpireSources;
     private createRequest;
-    onSuccess: (handler: EventHandler<RT>) => void;
-    onError: (handler: EventHandler<RT>) => void;
-    onHitCache: (handler: EventHandler<RT>) => void;
-    onFinish: (handler: EventHandler<RT>) => void;
-    on: (eventName: SnailMethodEventType, handler: EventHandler<RT>) => void;
-    once: (eventName: SnailMethodEventType, handler: EventHandler<RT>) => void;
-    emit: (eventName: SnailMethodEventType, ...args: any) => boolean;
-    off: (eventName: SnailMethodEventType, handler: EventHandler<RT>) => void;
+    onSuccess: (listener: SnailSuccessListener<RT>) => void;
+    onError: <ErrorData = any>(listener: SnailErrorListener<RT, ErrorData>) => void;
+    onHitCache: (listener: SnailHitCacheListener<RT>) => void;
+    onFinish: (listener: SnailFinishListener<RT>) => void;
     private getCacheData;
     private setCacheData;
     get response(): AxiosResponse<RT, any>;

package/dist/core/snailServer.d.ts

@@ -1,17 +1,17 @@
 import "reflect-metadata";
 import { AxiosInstance } from "axios";
-import { Strategy, ApiInstanceOptions, VersioningOption, CacheStorage, ApiProxy, ResponseData, StandardResponseData, CacheForType, SnailServerStatusCodeRuleOptions } from "../typings";
+import { Strategy, ApiInstanceOptions, VersioningOption, CacheStorage, ApiProxy, StandardResponseWithoutData, SnailServerStatusCodeRuleOptions, ResponseJsonData } from "../typings";
 import { SnailApi } from "./snailApi";
 import { SnailSse } from "./snailSse";
 export declare const CacheStorageMap: Map<string, CacheStorage>;
 export declare const CacheTtlMap: Map<string, number>;
-export declare const CacheForMap: Map<string, CacheForType>;
+export declare const CacheForMap: Map<string, string[]>;
 export declare const ExpireSourceMap: Map<string, Set<string>>;
 export declare const AxiosInstanceMap: Map<string, AxiosInstance>;
 export declare const StrategyMap: Map<string, (new () => Strategy)[]>;
 export declare const VersioningMap: Map<string, VersioningOption>;
 export declare const ServerStatusCodeRuleMap: Map<string, SnailServerStatusCodeRuleOptions>;
-export declare class SnailServer<RT extends ResponseData = Omit<StandardResponseData, "data">, DK extends string = "data"> {
+export declare class SnailServer<RT extends StandardResponseWithoutData | ResponseJsonData = StandardResponseWithoutData, DK extends string = "data"> {
     private Name;
     private BaseURL;
     private Version;
@@ -23,7 +23,7 @@ export declare class SnailServer<RT extends ResponseData = Omit<StandardResponse
     private initStrategy;
     private initVersioning;
     registerStrategies: (...strategys: Array<new () => Strategy>) => void;
-    createApi<T extends SnailApi>(constructor: new (options: ApiInstanceOptions) => T): ApiProxy<T, RT, DK>;
+    createApi<TApiClass extends SnailApi>(constructor: new (options: ApiInstanceOptions) => TApiClass): ApiProxy<TApiClass, RT, DK>;
     private initCacheManage;
     private initExpireSource;
     private initAxios;

package/dist/decorators/api.d.ts

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

package/dist/decorators/method.d.ts

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

package/dist/eventEmmit/index.d.ts

@@ -0,0 +1 @@
+export * from "./snail.event";

package/dist/eventEmmit/snail.event.d.ts

@@ -0,0 +1,10 @@
+import { SnailEventListener } from "../typings";
+export declare class SnailEvent<DT = any> {
+    private eventMap;
+    private onceWrapperMap;
+    constructor();
+    on: <ErrorData = any>(eventName: string, listener: SnailEventListener<DT, ErrorData>) => void;
+    off: (eventName: string, listener: SnailEventListener<DT>) => void;
+    once: (eventName: string, listener: SnailEventListener<DT>) => void;
+    emit: (eventName: string, ...args: any) => boolean;
+}

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 export * from "./core";
 export { Server } from "./decorators/server";
-export { Api, Get, Put, Post, Patch, Options, Head, Delete, } from "./decorators/api";
+export { Api } from "./decorators/api";
+export { Get, Put, Post, Patch, Options, Head, Delete, } from "./decorators/method";
 export { NoCache, HitSource } from "./decorators/cache";
 export { Params, Data, Query } from "./decorators/args";
 export { UseStrategy } from "./decorators/strategy";