@snail-js/api 0.1.27 → 1.0.0

package/README_EN.md

@@ -1,607 +0,0 @@
-<p>
-  <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>
-  <img src="https://img.shields.io/npm/v/reflect-metadata?label=reflect-metadata&labelColor=1e80ff&color=67C23A"></img>
-</p>
-
-<a href='./README.md'>中文文档</a>|English Document
-
-## Project Introduction
-
-- Secondary encapsulation based on Axios
-- Use `reflect-metadata` to create and process metadata
-- Provide decorators to define request methods, supporting all HTTP methods and SSE
-
-## Installation
-
-`npm install @snail-js/api`
-
-## Usage
-
-1. Enable TypeScript decorator configuration:
-
-```json
-// tsconfig.json
-{
-  "module": "ESNext",
-  // Module resolution strategy
-  "moduleResolution": "node",
-  "baseUrl": ".",
-  // Target must be higher than ES6
-  "target": "ESNext",
-  // lib should include ES versions above ES6
-  "lib": ["ESNext", "DOM"],
-  // Include reflect-metadata types
-  "types": ["reflect-metadata"],
-  "emitDecoratorMetadata": true,
-  "experimentalDecorators": true,
-
-  "skipLibCheck": true,
-  "strictNullChecks": false
-}
-```
-
-2. Create Snail backend configuration instance:
-
-```ts
-// service.ts
-import { SnailServer, Server } from "@snail-js/api";
-
-@Server({
-  baseURL: "/api",
-  timeout: 5000,
-})
-class BackEnd extends SnailServer {}
-
-export const Service = new BackEnd();
-```
-
-3. Create API instance:
-
-```ts
-// user.ts
-import { Api, Get, Post, Query, Data, SnailApi } from "@snail-js/api";
-import { Service } from "./service";
-
-@Api("user")
-class UserApi extends SnailApi {
-  @Get()
-  get(@Query("id") id: string) {}
-
-  @Post()
-  create(@Data() user: User) {}
-}
-// Create and export API
-export const userApi = Service.createApi(UserApi);
-```
-
-4. Send requests:
-
-```ts
-import { userApi } from "./user";
-
-const { send:getUser, onSuccess, onError, onHitCache } = await userApi.get();
-
-const data = await getUser("1");
-```
-
-## `SnailMethod` Instance
-
-- When calling `Service.createApi(ApiInstance)`, creates a proxy for methods decorated with `RequestMethod` (e.g. @Get, @Post)
-- Returns a function containing request parameters, which when called returns a `SnailMethod` instance
-
-### `SnailMethod` Methods
-
-- `send`: Send request  
-  _Async function that executes the current request_
-- `onSuccess`: Request success callback  
-  _Register success event handler_
-- `onError`: Request failure callback  
-  _Register error event handler_
-- `onHitCache`: Cache hit callback  
-  _Register cache hit event handler_
-- `onFinish`: Request completion callback  
-  _Register completion event handler (fires on both success/error)_
-- `registerStrategies` Register Strategies
-  _Register Strategies of this method instance_
-
-### `SnailMethod` Properties
-- `response`: AxiosResponse - Raw response object
-- `request`: AxiosRequestConfig - Final processed request after applying Versioning and Strategies
-- `version`: string - Effective request version (undefined if Versioning disabled)
-- `name`: string - Full method identifier in `ServerName.ApiName.MethodName` format
-- `error`: Error | null - Error object if request failed, null otherwise
-
-### Server Configuration
-
-<table>
-  <tr>
-    <th>Option</th>
-    <th>Type</th>
-    <th>Required</th>
-    <th>Default Value</th>
-    <th>Description</th>
-  </tr>
-  <tr>
-    <td>name</td>
-    <td>string</td>
-    <td>No</td>
-    <td>Class name inheriting SnailServer</td>
-    <td>Unique server identifier</td>
-  </tr>
-  <tr>
-    <td>baseUrl</td>
-    <td>string</td>
-    <td>No</td>
-    <td>'\'</td>
-    <td>API prefix (same as axios baseURL)</td>
-  </tr>
-  <tr>
-    <td>Versioning</td>
-    <td><a href="#versioningoption">VersioningOption</a></td>
-    <td>No</td>
-    <td>undefine</td>
-    <td>Versioning configuration</td>
-  </tr>
-  <tr>
-    <td>timeout</td>
-    <td>number</td>
-    <td>No</td>
-    <td>5000</td>
-    <td>Global timeout (ms)</td>
-  </tr>
-  <tr>
-    <td>cacheManage</td>
-    <td>{type:CacheType,ttl:number}</td>
-    <td>No</td>
-    <td>{
-      type: CacheType.Memory,
-      ttl: 500
-    }</td>
-    <td>Cache manager (ttl in seconds)</td>
-  </tr>
-  <tr>
-    <td>cacheFor</td>
-    <td>RequestMethod | RequestMethod[] | 'All' | 'all' </td>
-    <td>No</td>
-    <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>
-    <td>No</td>
-    <td>false</td>
-    <td>Enable debug logs</td>
-  </tr>
-</table>
-
-### API Configuration
-- Decorate API classes with `@Api()` and extend `SnailApi`
-
-<table>
-  <tr>
-    <th>Option</th>
-    <th>Type</th>
-    <th>Required</th>
-    <th>Default Value</th>
-    <th>Description</th>
-  </tr>
-  <tr>
-    <td>name</td>
-    <td>string</td>
-    <td>No</td>
-    <td>default use extends`SnailApi` class name</td>
-    <td>Unique API identifier</td>
-  </tr>
-  <tr>
-    <td>timeout</td>
-    <td>number</td>
-    <td>No</td>
-    <td></td>
-    <td>Overrides server timeout</td>
-  </tr>
-  <tr>
-    <td>version</td>
-    <td>string</td>
-    <td>No</td>
-    <td></td>
-    <td>Overrides server defaultVersion</td>
-  </tr>
-</table>
-
-## Request Method Decorators
-- Used in API classes to mark request methods
-- Supports all axios methods: Get, Post, Head, Put, Delete, Patch, Options
-- Parameter: path?: string - Endpoint path (combined with baseURL)
-
-## Parameter Decorators
-### Query Parameters @Query
-- @Query(key?:string)
-Example:
-
-```ts
-@Api("user")
-class UserApi {
-  @Get()
-  get(@Query("id") id: string, @Query("sign") sign: string) {}
-}
-```
-> Parameters will be appended as ?k1=v1&k2=v2
-
-### Route Parameters @Params
-- @Params(key?:string)
-Example with object:
-```ts
-class RouteParams {
-  id: string;
-  sign: string;
-}
-
-@Api("user/:id/:sign")
-class UserApi {
-  @Get()
-  get(@Params() params: RouteParams) {}
-}
-```
-
-> Automatically maps object properties to route parameters
-
-### Request Data
-
-- `@Data(key?:string)`
-- Usage pattern same as `@Params`, supports mixed usage
-
-## Strategy Decorator `@UseStrategy`
-
-- `@UseStrategy(...Strategy[])`
-
-### Request Strategy
-
-- Executed before request sending, subsequent strategy results override previous ones
-- If returns processed request, uses it for sending; otherwise uses original or previous strategy's result
-
-```typescript
-class CustomStrategy extends Strategy {
-  applyRequest(request: AxiosRequestConfig) {
-    request.headers["Access-Token"] = "abcde";
-    return request;
-  }
-}
-
-// Applied to Snail for global request strategies
-@Server({
-  baseURL: "/api",
-  timeout: 5000,
-})
-@UseStrategy(CustomStrategy)
-class BackEnd extends Snail<ShanheResponse> {}
-export const Service = new BackEnd();
-// Register strategy after instance creation
-Service.registerStrategies(CustomStrategy);
-
-// Applied to API for method-specific strategies
-@Api("test")
-@UseStrategy(CustomStrategy)
-class Test {}
-const TestApi = Service.createApi(Test);
-TestApi.registerStrategies(CustomStrategy);
-
-// Applied to method for endpoint-level strategies
-@Api("test")
-@UseStrategy(CustomStrategy)
-class Test {
-  @Get()
-  @UseStrategy(CustomStrategy)
-  get() {}
-}
-// Register strategy before request
-const TestApi = Service.createApi(Test);
-const getSomething = TestApi.get();
-{ send, registerStrategies } = getSomething;
-registerStrategies(CustomStrategy);
-
-```
-
-### Response Strategy
-- Executed after receiving server response
-- Processed response propagates through strategy chain
-
-```typescript
-class CustomStrategy extends Strategy {
-  applyResponse(response: AxiosResponse) {
-    const { status } = response;
-    if (status == 200) {
-      // Custom processing
-    }
-    return response;
-  }
-}
-```
-
-## Version Management Decorators @Versioning & @Version
-### Version Manager @Versioning(VersioningOption)
-- Global version management
-
-```typescript
-@Server({
-  baseURL: "/api",
-  timeout: 5000,
-})
-@Versioning({
-  type: VersioningType.Header,
-  defaultVersion: "0.1.0",
-})
-class BackEnd extends Snail<ShanheResponse> {}
-
-export const Service = new BackEnd();
-```
-
-### <a id='versioningOption'>VersioningOption Type</a>
-
-```typescript
-export enum VersioningType {
-  Uri,
-  Header,
-  Query,
-  Custom,
-}
-
-interface VersioningCommonOption {
-  defaultVersion: string;
-}
-
-export interface VersioningUriOption extends VersioningCommonOption {
-  type: VersioningType.Uri;
-  prefix?: string;
-}
-
-export interface VersioningHeaderOption extends VersioningCommonOption {
-  type: VersioningType.Header;
-  header?: string;
-}
-
-export interface VersioningQueryOption extends VersioningCommonOption {
-  type: VersioningType.Query;
-  key?: string;
-}
-
-export interface VersioningCustomOption extends VersioningCommonOption {
-  type: VersioningType.Custom;
-  extractor: (requestOptions: unknown) => {
-    url: string;
-    headers: Record<string, any>;
-  };
-}
-
-export type VersioningOption =
-  | VersioningUriOption
-  | VersioningHeaderOption
-  | VersioningQueryOption
-  | 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
-@Api("test")
-class Test {
-  @Get("HelloWorld")
-  @Version("0.2.0")
-  test() {}
-}
-```
-
-> Enables temporary version override for testing
-
-### Cache Decorator @HitSource
-- @HitSource(name:string)
-- Defines cache invalidation sources
-- Name format: serverName:apiName:methodName
-> Note: Use configured names if available, otherwise class names
-
-```typescript
-@Api("test",{name:'api1'})
-@HitSource("api1")
-class Test {
-  @Get("HelloWorld")
-  @HitSource("api1.test2")
-  test1() {}
-
-  @Post()
-  test2() {}
-
-  @Get()
-  // Invalidates cache for all Test class methods
-  @HitSource("api1")
-  test3() {}
-}
-```
-
-> Successful [Post]test calls invalidate [Get]test/HelloWorld cache Default caching only for GET methods. Use @Server({cacheFor:'all'}) for other methods
-
-> When `test3` method request succeeds, it won't be cached
-
-> Note: To enable caching, configure `@Server({cacheManage})` cache manager
-
-### Upload Progress Decorator `@UploadProgress`
-
-- `@UploadProgress((progressEvent: AxiosProgressEvent) => void)`
-
-### Download Progress Decorator `@DownloadProgress`
-
-- `@DownloadProgress((progressEvent: AxiosProgressEvent) => void)`
-
-## Server-Sent Events (SSE)
-
-### Create SSE Endpoint
-
-```typescript
-@Sse("sse")
-class ServerSend extends SnailSse {
-
-  @OnSseOpen()
-  handleOpen(event: Event) {
-    console.log("SSE connection opened:", event);
-  }
-
-  @OnSseError()
-  handleError(event: Event) {
-    console.log("SSE error occurred:", event);
-  }
-
-  // Handle default message events
-  @SseEvent()
-  handleEvent(event: MessageEvent) {
-    console.log("SSE message event:", event.data);
-  }
-
-  // Handle custom named events
-  @SseEvent("chunk")
-  handleChunkEvent(event: Event) {
-    console.log("SSE chunk event:", event);
-  }
-}
-
-export const Sse = Service.createSse(ServerSend);
-```
-
-### SSE Decorator @Sse
-- @Sse(path: string, options?: { withCredentials?: boolean, version?: string })
-- Creates a server-sent events connection, returns a function to open SSE connection:
-  - Returns { eventSource: EventSource, close: () => void } when called:
-    - eventSource: SSE connection instance
-    - close: Method to close the connection
-### SSE Open Handler Decorator @OnSseOpen
-- Registers decorated method as onopen handler for EventSource instances created by @Sse decorated methods
-### SSE Error Handler Decorator @OnSseError
-- Registers decorated method as onerror handler for EventSource instances created by @Sse decorated methods
-### SSE Event Handler Decorator @SseEvent
-- @SseEvent(eventName?: string)
-- Without eventName : Registers as default message event handler
-- With eventName : Registers as handler for specified custom event
-
-------
-
-## TypeScript Support
-### Default Response Type
-
-```typescript
-export type StandardResponseData<
-  T extends ResponseJsonData = Record<string, any>
-> = {
-  code: number;
-  message: string;
-  data: T;
-};
-```
-
-### Custom Response Types
-1. Define backend response format:
-```typescript
-export class CustomResponse {
-  status_code: number;
-  msg: string;
-}
-```
-2. Apply type when creating service:
-```typescript
-// service.ts
-import { SnailServer, Server } from "@snail-js/api";
-
-@Server({
-  baseURL: "/api",
-  timeout: 5000,
-})
-class BackEnd extends SnailServer<CustomResponse> {}
-
-export const Service = new BackEnd();
-```
-
-3. Type annotation when calling APIs:
-```typescript
-import { userApi } from "./user";
-
-class User {
-  id: number;
-  name: string;
-  tel: string;
-  age: number;
-}
-
-const getUser = userApi.get<User>();
-const { send } = getUser;
-
-const res = await send("1");
-
-// Default data key:
-// res.data => CustomResponse & { data: User }
-```
-
-> API response format:
-```typescript
-const getUser = userApi.get<User>();
-const { send } = getUser;
-const res = await send("1");
-
-// res.data => CustomResponse & { data: User }
-
-const getUser = userApi.get<Blob>();
-const { send } = getUser;
-const res = await send("1");
-// res => AxiosResponse<Blob>
-```
-
-4. Custom data key configuration:
-
-```typescript
-@Server({
-  baseURL: "/api",
-  timeout: 5000,
-})
-class BackEnd extends Snail<CustomResponse, "record"> {}
-
-const { send } = userApi.get<User>();
-const res = await send("1");
-// Custom data key:
-// res.data => CustomResponse & { record: User }
-```
-
-### Non-JSON Responses
-- For non-JSON content-type responses: send() returns AxiosResponse
-- For JSON content-type responses: send() returns AxiosResponse.data
-
-### Repository
-<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>
-
-### Author
-
-- mc.lee

package/dist/cache/index.d.ts

@@ -1,9 +0,0 @@
-import MemoryCache from "./memoryCache";
-import LocalStorageCache from "./localstorageCache";
-import IndexDBCache from "./indexDBCache";
-import { CacheStorageAdapter, CacheStorage, MemoryCacheOption, IndexDBCacheOption, LocalStorageCacheOption, CustomCacheOption, CacheManagementOption } from "../typings";
-export declare function createCache<T extends CacheManagementOption>(options: T): CacheStorage;
-export declare function createCache<T extends MemoryCacheOption>(optios: T): MemoryCache;
-export declare function createCache<T extends LocalStorageCacheOption>(optios: T): LocalStorageCache;
-export declare function createCache<T extends IndexDBCacheOption>(optios: T): IndexDBCache;
-export declare function createCache<T extends CustomCacheOption>(optios: T): CacheStorageAdapter;

package/dist/cache/indexDBCache.d.ts

@@ -1,13 +0,0 @@
-import { CacheGetData, CacheStorageAdapter } from "../typings";
-export default class IndexDBCache implements CacheStorageAdapter {
-    ttl: number;
-    private db?;
-    constructor(ttl: number);
-    init(): Promise<void>;
-    private openDB;
-    get<T = any>(key: string): Promise<CacheGetData<T>>;
-    set<T = any>(key: string, value: T): Promise<boolean>;
-    delete(key: string): Promise<boolean>;
-    clear(): Promise<boolean>;
-    keys(): Promise<string[]>;
-}

package/dist/cache/localstorageCache.d.ts

@@ -1,10 +0,0 @@
-import { CacheGetData, CacheStorageAdapter } from "../typings";
-export default class LocalStorageCache implements CacheStorageAdapter {
-    ttl: number;
-    constructor(ttl: number);
-    get<T = any>(key: string): Promise<CacheGetData<T>>;
-    set<T = any>(key: string, value: T): Promise<boolean>;
-    delete(key: string): Promise<boolean>;
-    clear(): Promise<boolean>;
-    keys(): Promise<string[]>;
-}

package/dist/cache/memoryCache.d.ts

@@ -1,11 +0,0 @@
-import { CacheGetData, CacheStorageAdapter } from "../typings";
-export default class MemoryCache implements CacheStorageAdapter {
-    private CacheMap;
-    ttl: number;
-    constructor(ttl: number);
-    get<T = any>(key: string): Promise<CacheGetData<T>>;
-    set<T = any>(key: string, value: T): Promise<boolean>;
-    delete(key: string): Promise<boolean>;
-    clear(): Promise<boolean>;
-    keys(): Promise<string[]>;
-}

package/dist/core/index.d.ts

@@ -1,4 +0,0 @@
-export { SnailServer } from "./snailServer";
-export { SnailMethod } from "./snailMethod";
-export { SnailApi } from "./snailApi";
-export { SnailSse } from "./snailSse";

package/dist/core/snailApi.d.ts

@@ -1,22 +0,0 @@
-import { Strategy, ApiInstanceOptions } from "../typings";
-export declare class SnailApi {
-    private Name;
-    private serverInstance;
-    private Version?;
-    private Url?;
-    private Timeout?;
-    private EnableLog?;
-    constructor(options: ApiInstanceOptions);
-    private init;
-    private initStrategy;
-    registerStrategies: (...strategys: Array<new () => Strategy>) => void;
-    private initName;
-    private getApiConfig;
-    private isNoCache;
-    get version(): string | undefined;
-    get url(): string | undefined;
-    get name(): string;
-    get noCache(): boolean;
-    get enableLog(): boolean | undefined;
-    get timeout(): number | undefined;
-}