axios-annotations 2.3.0 → 3.0.0

package/es/core/builder.d.ts

@@ -0,0 +1,33 @@
+import type { AxiosResponse, Method } from 'axios';
+import type Config from "./config";
+import { AxiosRequestConfig } from "axios";
+export type ParamsMapper<T = any> = (params: Record<string, any>) => T;
+export declare enum ParamsMappingType {
+    HEADER = "HEADER",
+    PARAM = "PARAM",
+    BODY = "BODY",
+    PATH_VARIABLE = "PATH_VARIABLE"
+}
+export interface ParamsMapping<T = any> {
+    key: string;
+    value: T | ParamsMapper<T>;
+    required?: boolean;
+}
+export type AxiosConfigMapper = (params: Record<string, any>) => AxiosRequestConfig;
+export default class RequestBuilder {
+    private _configs;
+    private readonly _mapping;
+    private readonly _pathVariablesMapping;
+    private _addMapping;
+    private _addPathVariablesMapping;
+    private _clearMapping;
+    param(key: string, required?: boolean): this;
+    param(mapping: ParamsMapping): this;
+    header(key: string, required?: boolean): this;
+    header(mapping: ParamsMapping): this;
+    body(keyOrMapping: string | ParamsMapping): this;
+    pathVariable(keyOrMapping: string | ParamsMapping): this;
+    config(cfg: AxiosRequestConfig | AxiosConfigMapper): this;
+    build(config: Config, path: string, method: Method, source?: Record<string, any>): AxiosRequestConfig;
+    buildWith(config: Config, path: string, method: Method, source?: Record<string, any>): Promise<AxiosResponse<any>>;
+}

package/es/core/builder.js

@@ -0,0 +1,515 @@
+var __assign = this && this.__assign || function() {
+    __assign = Object.assign || function(t) {
+        for(var s, i = 1, n = arguments.length; i < n; i++){
+            s = arguments[i];
+            for(var p in s)if (Object.prototype.hasOwnProperty.call(s, p)) t[p] = s[p];
+        }
+        return t;
+    };
+    return __assign.apply(this, arguments);
+};
+var __awaiter = this && this.__awaiter || function(thisArg, _arguments, P, generator) {
+    function adopt(value) {
+        return value instanceof P ? value : new P(function(resolve) {
+            resolve(value);
+        });
+    }
+    return new (P || (P = Promise))(function(resolve, reject) {
+        function fulfilled(value) {
+            try {
+                step(generator.next(value));
+            } catch (e) {
+                reject(e);
+            }
+        }
+        function rejected(value) {
+            try {
+                step(generator["throw"](value));
+            } catch (e) {
+                reject(e);
+            }
+        }
+        function step(result) {
+            result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected);
+        }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __generator = this && this.__generator || function(thisArg, body) {
+    var _ = {
+        label: 0,
+        sent: function sent() {
+            if (t[0] & 1) throw t[1];
+            return t[1];
+        },
+        trys: [],
+        ops: []
+    }, f, y, t, g = Object.create((typeof Iterator === "function" ? Iterator : Object).prototype);
+    return g.next = verb(0), g["throw"] = verb(1), g["return"] = verb(2), typeof Symbol === "function" && (g[Symbol.iterator] = function() {
+        return this;
+    }), g;
+    function verb(n) {
+        return function(v) {
+            return step([
+                n,
+                v
+            ]);
+        };
+    }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while(g && (g = 0, op[0] && (_ = 0)), _)try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [
+                op[0] & 2,
+                t.value
+            ];
+            switch(op[0]){
+                case 0:
+                case 1:
+                    t = op;
+                    break;
+                case 4:
+                    _.label++;
+                    return {
+                        value: op[1],
+                        done: false
+                    };
+                case 5:
+                    _.label++;
+                    y = op[1];
+                    op = [
+                        0
+                    ];
+                    continue;
+                case 7:
+                    op = _.ops.pop();
+                    _.trys.pop();
+                    continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) {
+                        _ = 0;
+                        continue;
+                    }
+                    if (op[0] === 3 && (!t || op[1] > t[0] && op[1] < t[3])) {
+                        _.label = op[1];
+                        break;
+                    }
+                    if (op[0] === 6 && _.label < t[1]) {
+                        _.label = t[1];
+                        t = op;
+                        break;
+                    }
+                    if (t && _.label < t[2]) {
+                        _.label = t[2];
+                        _.ops.push(op);
+                        break;
+                    }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop();
+                    continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) {
+            op = [
+                6,
+                e
+            ];
+            y = 0;
+        } finally{
+            f = t = 0;
+        }
+        if (op[0] & 5) throw op[1];
+        return {
+            value: op[0] ? op[1] : void 0,
+            done: true
+        };
+    }
+};
+var __values = this && this.__values || function(o) {
+    var s = typeof Symbol === "function" && Symbol.iterator, m = s && o[s], i = 0;
+    if (m) return m.call(o);
+    if (o && typeof o.length === "number") return {
+        next: function next() {
+            if (o && i >= o.length) o = void 0;
+            return {
+                value: o && o[i++],
+                done: !o
+            };
+        }
+    };
+    throw new TypeError(s ? "Object is not iterable." : "Symbol.iterator is not defined.");
+};
+var __read = this && this.__read || function(o, n) {
+    var m = typeof Symbol === "function" && o[Symbol.iterator];
+    if (!m) return o;
+    var i = m.call(o), r, ar = [], e;
+    try {
+        while((n === void 0 || n-- > 0) && !(r = i.next()).done)ar.push(r.value);
+    } catch (error) {
+        e = {
+            error: error
+        };
+    } finally{
+        try {
+            if (r && !r.done && (m = i["return"])) m.call(i);
+        } finally{
+            if (e) throw e.error;
+        }
+    }
+    return ar;
+};
+var __spreadArray = this && this.__spreadArray || function(to, from, pack) {
+    if (pack || arguments.length === 2) for(var i = 0, l = from.length, ar; i < l; i++){
+        if (ar || !(i in from)) {
+            if (!ar) ar = Array.prototype.slice.call(from, 0, i);
+            ar[i] = from[i];
+        }
+    }
+    return to.concat(ar || Array.prototype.slice.call(from));
+};
+import { mergeAxiosConfigs, isNullOrEmpty, normalizePath, isPlainObject, formatUrl } from "./common.js";
+export var ParamsMappingType;
+(function(ParamsMappingType) {
+    // 请求头
+    ParamsMappingType["HEADER"] = "HEADER";
+    // 查询串
+    ParamsMappingType["PARAM"] = "PARAM";
+    // 请求体
+    ParamsMappingType["BODY"] = "BODY";
+    // 路径变量
+    ParamsMappingType["PATH_VARIABLE"] = "PATH_VARIABLE";
+})(ParamsMappingType || (ParamsMappingType = {}));
+var RequestBuilder = /** @class */ function() {
+    function RequestBuilder() {
+        this._configs = null;
+        this._mapping = new Map();
+        this._pathVariablesMapping = [];
+    }
+    RequestBuilder.prototype._addMapping = function(type, mapping) {
+        var scopeMapping = this._mapping.get(type);
+        if (!scopeMapping) {
+            scopeMapping = new Map();
+            this._mapping.set(type, scopeMapping);
+        }
+        scopeMapping.set(mapping.key, mapping);
+    };
+    RequestBuilder.prototype._addPathVariablesMapping = function(mapping) {
+        this._pathVariablesMapping.push(mapping);
+    };
+    RequestBuilder.prototype._clearMapping = function(type) {
+        var scopeMapping = this._mapping.get(type);
+        if (scopeMapping) {
+            scopeMapping.clear();
+        }
+    };
+    RequestBuilder.prototype.param = function(keyOrMapping, required) {
+        if (typeof keyOrMapping === 'string') {
+            this._addMapping(ParamsMappingType.PARAM, {
+                value: undefined,
+                key: keyOrMapping,
+                // 查询串为空默认不填充
+                required: required === true
+            });
+        } else {
+            if (isNullOrEmpty(keyOrMapping.key)) {
+                throw new Error('param mapping key is required');
+            }
+            this._addMapping(ParamsMappingType.PARAM, __assign(__assign({}, keyOrMapping), {
+                required: keyOrMapping.required === true
+            }));
+        }
+        return this;
+    };
+    RequestBuilder.prototype.header = function(keyOrMapping, required) {
+        if (typeof keyOrMapping === 'string') {
+            this._addMapping(ParamsMappingType.HEADER, {
+                value: undefined,
+                key: keyOrMapping,
+                // 请求头默认强制填充，找不到填充空字符串
+                required: required !== false
+            });
+        } else {
+            if (isNullOrEmpty(keyOrMapping.key)) {
+                throw new Error('header mapping key is required');
+            }
+            this._addMapping(ParamsMappingType.HEADER, __assign(__assign({}, keyOrMapping), {
+                required: keyOrMapping.required === true
+            }));
+        }
+        return this;
+    };
+    // 请求体只有一个规则，因为不同请求体类型无法合并，请求体自动不存在则设置 null
+    RequestBuilder.prototype.body = function(keyOrMapping) {
+        this._clearMapping(ParamsMappingType.BODY);
+        if (typeof keyOrMapping === 'string') {
+            this._addMapping(ParamsMappingType.BODY, {
+                value: undefined,
+                key: keyOrMapping,
+                // 请求体 required 不生效，无法给出不同类型的默认值
+                required: false
+            });
+        } else {
+            if (isNullOrEmpty(keyOrMapping.key)) {
+                throw new Error('body mapping key is required');
+            }
+            this._addMapping(ParamsMappingType.BODY, __assign(__assign({}, keyOrMapping), {
+                required: false
+            }));
+        }
+        return this;
+    };
+    // 路径参数集合
+    // 路径参数数据源要求可合并并且不需要指定key，单独数据集合
+    RequestBuilder.prototype.pathVariable = function(keyOrMapping) {
+        if (typeof keyOrMapping === 'string') {
+            this._addPathVariablesMapping({
+                value: undefined,
+                key: keyOrMapping,
+                required: false // 必填参数无意义，占位符是固定的字符
+            });
+        } else {
+            this._addPathVariablesMapping(__assign(__assign({}, keyOrMapping), {
+                required: false
+            }));
+        }
+        return this;
+    };
+    RequestBuilder.prototype.config = function(cfg) {
+        if (!this._configs) {
+            this._configs = [];
+        }
+        if (this._configs.indexOf(cfg) === -1) {
+            this._configs.push(cfg);
+        }
+        return this;
+    };
+    RequestBuilder.prototype.build = function(config, path, method, source) {
+        var e_1, _a, _b, _c, e_2, _d, _e, _f, e_3, _g, e_4, _h;
+        if (source === void 0) {
+            source = {};
+        }
+        var params = {};
+        var headers = {};
+        var url = path.indexOf("http") >= 0 ? path : config.baseURL + normalizePath("/".concat(path));
+        var body = null;
+        // 处理查询串
+        var paramMapping = this._mapping.get(ParamsMappingType.PARAM);
+        if (paramMapping) {
+            try {
+                for(var paramMapping_1 = __values(paramMapping), paramMapping_1_1 = paramMapping_1.next(); !paramMapping_1_1.done; paramMapping_1_1 = paramMapping_1.next()){
+                    var _j = __read(paramMapping_1_1.value, 2), key = _j[0], mapping = _j[1];
+                    if (typeof mapping.value === 'function') {
+                        var mapper = mapping.value;
+                        var result = mapper.call(undefined, source);
+                        if (isNullOrEmpty(result)) {
+                            if (mapping.required === false) {
+                                continue;
+                            }
+                        }
+                        Object.assign(params, (_b = {}, _b[key] = result, _b));
+                    } else {
+                        // 如果指定了静态值，则使用静态值
+                        var value = mapping.value;
+                        if (isNullOrEmpty(value)) {
+                            // 没有指定静态值，查询数据源
+                            value = source[key];
+                        }
+                        if (isNullOrEmpty(value)) {
+                            if (mapping.required === false) {
+                                continue;
+                            } else {
+                                value = '';
+                            }
+                        }
+                        Object.assign(params, (_c = {}, _c[key] = value, _c));
+                    }
+                }
+            } catch (e_1_1) {
+                e_1 = {
+                    error: e_1_1
+                };
+            } finally{
+                try {
+                    if (paramMapping_1_1 && !paramMapping_1_1.done && (_a = paramMapping_1["return"])) _a.call(paramMapping_1);
+                } finally{
+                    if (e_1) throw e_1.error;
+                }
+            }
+        }
+        // 处理请求头
+        var headerMapping = this._mapping.get(ParamsMappingType.HEADER);
+        if (headerMapping) {
+            try {
+                for(var headerMapping_1 = __values(headerMapping), headerMapping_1_1 = headerMapping_1.next(); !headerMapping_1_1.done; headerMapping_1_1 = headerMapping_1.next()){
+                    var _k = __read(headerMapping_1_1.value, 2), key = _k[0], mapping = _k[1];
+                    if (typeof mapping.value === 'function') {
+                        var mapper = mapping.value;
+                        var result = mapper.call(undefined, source);
+                        if (isNullOrEmpty(result)) {
+                            if (mapping.required === true) {
+                                result = '';
+                            } else {
+                                continue;
+                            }
+                        }
+                        Object.assign(headers, (_e = {}, _e[key] = result, _e));
+                    } else {
+                        var value = mapping.value;
+                        if (isNullOrEmpty(value)) {
+                            value = source[key];
+                        }
+                        if (isNullOrEmpty(value)) {
+                            if (mapping.required === false) {
+                                continue;
+                            } else {
+                                value = '';
+                            }
+                        }
+                        Object.assign(headers, (_f = {}, _f[key] = value, _f));
+                    }
+                }
+            } catch (e_2_1) {
+                e_2 = {
+                    error: e_2_1
+                };
+            } finally{
+                try {
+                    if (headerMapping_1_1 && !headerMapping_1_1.done && (_d = headerMapping_1["return"])) _d.call(headerMapping_1);
+                } finally{
+                    if (e_2) throw e_2.error;
+                }
+            }
+        }
+        // 处理请求体
+        var bodyMapping = this._mapping.get(ParamsMappingType.BODY);
+        if (bodyMapping) {
+            try {
+                for(var bodyMapping_1 = __values(bodyMapping), bodyMapping_1_1 = bodyMapping_1.next(); !bodyMapping_1_1.done; bodyMapping_1_1 = bodyMapping_1.next()){
+                    var _l = __read(bodyMapping_1_1.value, 2), key = _l[0], mapping = _l[1];
+                    if (typeof mapping.value === 'function') {
+                        var mapper = mapping.value;
+                        var result = mapper.call(undefined, source);
+                        if (result === undefined) {
+                            result = null;
+                        }
+                        body = result;
+                    } else {
+                        var value = mapping.value;
+                        if (isNullOrEmpty(value)) {
+                            value = source[key];
+                        }
+                        if (value === undefined) {
+                            value = null;
+                        }
+                        body = value;
+                    }
+                }
+            } catch (e_3_1) {
+                e_3 = {
+                    error: e_3_1
+                };
+            } finally{
+                try {
+                    if (bodyMapping_1_1 && !bodyMapping_1_1.done && (_g = bodyMapping_1["return"])) _g.call(bodyMapping_1);
+                } finally{
+                    if (e_3) throw e_3.error;
+                }
+            }
+        }
+        var mergeConfigs = {
+            headers: headers,
+            url: url,
+            method: method,
+            data: body,
+            params: params
+        };
+        if (this._configs) {
+            mergeConfigs = mergeAxiosConfigs.apply(void 0, __spreadArray([], __read(this._configs.map(function(cfg) {
+                return mergeAxiosConfigs(mergeConfigs, typeof cfg === 'function' ? cfg(source) : cfg);
+            })), false));
+        }
+        var pathVariables = null;
+        if (this._pathVariablesMapping.length) {
+            pathVariables = {};
+            try {
+                for(var _m = __values(this._pathVariablesMapping), _o = _m.next(); !_o.done; _o = _m.next()){
+                    var mapping = _o.value;
+                    if (typeof mapping.value === 'function') {
+                        Object.assign(pathVariables, mapping.value(source));
+                    } else {
+                        var value = mapping.value;
+                        if (isNullOrEmpty(value)) {
+                            if (!mapping.key) {
+                                // 如果不指定key，则使用 source 数据源本体
+                                // 所以，如果需要开启路径参数功能至少配置一个 @PathVariables()
+                                value = source;
+                            } else {
+                                value = source[mapping.key];
+                            }
+                        }
+                        if (value === undefined) {
+                            // 说明找不到
+                            value = null;
+                        } else {
+                            if (!isPlainObject(value)) {
+                                console.error('check path variables collection is plain object: ', value);
+                                value = null;
+                            }
+                        }
+                        Object.assign(pathVariables, value);
+                    }
+                }
+            } catch (e_4_1) {
+                e_4 = {
+                    error: e_4_1
+                };
+            } finally{
+                try {
+                    if (_o && !_o.done && (_h = _m["return"])) _h.call(_m);
+                } finally{
+                    if (e_4) throw e_4.error;
+                }
+            }
+        }
+        if (pathVariables) {
+            // 路径变量不为空，认为有意图使用占位符
+            var url_1 = mergeConfigs.url;
+            if (url_1) {
+                // url 的声明为 String?
+                mergeConfigs.url = formatUrl(url_1, pathVariables);
+            }
+            var baseUrl = mergeConfigs.baseURL;
+            if (baseUrl) {
+                // 一般不会对 baseUrl 使用占位符
+                mergeConfigs.baseURL = formatUrl(baseUrl, pathVariables);
+            }
+        }
+        return mergeConfigs;
+    };
+    RequestBuilder.prototype.buildWith = function(config_1, path_1, method_1) {
+        return __awaiter(this, arguments, void 0, function(config, path, method, source) {
+            var axiosInstance;
+            if (source === void 0) {
+                source = {};
+            }
+            return __generator(this, function(_a) {
+                switch(_a.label){
+                    case 0:
+                        return [
+                            4 /*yield*/ ,
+                            config.requestAxiosInstance()
+                        ];
+                    case 1:
+                        axiosInstance = _a.sent();
+                        return [
+                            2 /*return*/ ,
+                            axiosInstance.request(this.build(config, path, method, source))
+                        ];
+                }
+            });
+        });
+    };
+    return RequestBuilder;
+}();
+export default RequestBuilder;

package/es/core/common.d.ts

@@ -0,0 +1,36 @@
+import type { AxiosRequestConfig } from 'axios';
+import RequestBuilder from "./builder";
+import Config from "./config";
+export declare function normalizePath(path: string): string;
+export declare function isNullOrEmpty(param: any): boolean;
+type MetaPropertyDescriptor = PropertyDescriptor & {
+    builder: RequestBuilder;
+    config?: Config;
+};
+export declare function castToMetaDescriptor(descriptor: PropertyDescriptor): MetaPropertyDescriptor;
+/**
+ * Merges multiple Axios request configurations with specific logic for Axios.
+ * - `headers` and `params` are shallowly merged.
+ * - All other properties are replaced by the last provided value.
+ *
+ * @param sources A list of AxiosRequestConfig objects to merge.
+ * @returns A new, merged AxiosRequestConfig object.
+ */
+export declare function mergeAxiosConfigs(...sources: AxiosRequestConfig[]): AxiosRequestConfig;
+/**
+ * 替换链接占位符，注意使用基本类型
+ * Replaces placeholders in a URL with values from a data object.
+ * e.g., formatUrl("http://a.com/{c}?d={e}", {c: 'x', e: 100}) -> "http://a.com/x?d=100"
+ *
+ * @param url The URL string with placeholders like {key}.
+ * @param data The plain object data source.
+ * @returns The formatted URL string.
+ */
+export declare function formatUrl(url: string, data: Record<string, any>): string;
+/**
+ * Checks if a value is a plain object, i.e., an object created by `{}` or `new Object()`.
+ * @param value The value to check.
+ * @returns True if the value is a plain object, false otherwise.
+ */
+export declare function isPlainObject(value: any): value is Record<string, any>;
+export {};