evaengine 1.0.14 → 3.0.0

package/dist/utils/request_client.d.ts

@@ -0,0 +1,33 @@
+/**
+ * A request-promise-native compatible HTTP client built on the global fetch.
+ *
+ * Keeps the option object and error shape used by the legacy `request`
+ * ecosystem so callers of HttpClient/RestClient see no interface change:
+ * - resolves with the response body (or the full response with
+ *   `resolveWithFullResponse`)
+ * - rejects with an error carrying `.name` (`StatusCodeError`/`RequestError`),
+ *   `.statusCode`, `.response` and `.request`
+ * - supports `url`, `method`, `headers`, `body`, `json`, `qs`, `form`,
+ *   `formData`, `simple`, `resolveWithFullResponse` and `timeout`
+ */
+type RequestClientParams = {
+    url?: string;
+    method?: string;
+    headers?: Record<string, unknown>;
+    body?: unknown;
+    json?: unknown;
+    qs?: Record<string, unknown> | string;
+    form?: Record<string, unknown>;
+    formData?: Record<string, unknown>;
+    simple?: boolean;
+    resolveWithFullResponse?: boolean;
+    timeout?: number;
+};
+/**
+ * Create a request-promise-native compatible callable client.
+ * @param [logger] when given, verbose request/response logs are emitted
+ */
+export declare const createRequestClient: (logger?: {
+    verbose: (message: string, ...args: unknown[]) => void;
+} | null) => (params?: RequestClientParams) => Promise<unknown>;
+export {};

package/dist/utils/request_client.js

@@ -0,0 +1,153 @@
+/**
+ * A request-promise-native compatible HTTP client built on the global fetch.
+ *
+ * Keeps the option object and error shape used by the legacy `request`
+ * ecosystem so callers of HttpClient/RestClient see no interface change:
+ * - resolves with the response body (or the full response with
+ *   `resolveWithFullResponse`)
+ * - rejects with an error carrying `.name` (`StatusCodeError`/`RequestError`),
+ *   `.statusCode`, `.response` and `.request`
+ * - supports `url`, `method`, `headers`, `body`, `json`, `qs`, `form`,
+ *   `formData`, `simple`, `resolveWithFullResponse` and `timeout`
+ */
+const MAX_BODY_LENGTH = parseInt(process.env.MAX_REQUEST_DEBUG_BODY, 10) || 3000;
+const TOO_LONG_BODY = '____TLDR____';
+let debugId = 0;
+const toPlainHeaders = (headers = {}) => {
+    const result = {};
+    Object.entries(headers).forEach(([key, value]) => {
+        result[key] = String(value);
+    });
+    return result;
+};
+const buildQueryString = (qs) => {
+    if (qs === undefined || qs === null) {
+        return '';
+    }
+    if (typeof qs === 'string') {
+        return qs.startsWith('?') ? qs : `?${qs}`;
+    }
+    return `?${new URLSearchParams(qs).toString()}`;
+};
+const buildBody = (params) => {
+    if (params.formData) {
+        const form = new FormData();
+        Object.entries(params.formData).forEach(([key, value]) => {
+            // FormData.append 运行时按 WebIDL 语义转换非字符串值，断言仅满足编译
+            form.append(key, value);
+        });
+        return { body: form, contentType: null };
+    }
+    if (params.form) {
+        return {
+            body: new URLSearchParams(params.form).toString(),
+            contentType: 'application/x-www-form-urlencoded'
+        };
+    }
+    //The legacy `json` option also accepts a value used as the JSON body
+    if (params.json !== undefined && params.json !== false && params.json !== true) {
+        return { body: JSON.stringify(params.json), contentType: 'application/json' };
+    }
+    if (params.json === true && params.body !== undefined) {
+        return { body: JSON.stringify(params.body), contentType: 'application/json' };
+    }
+    return { body: params.body, contentType: null };
+};
+const truncateBody = (body) => {
+    if (typeof body !== 'string') {
+        return body ? String(body) : '';
+    }
+    return body.length > MAX_BODY_LENGTH ? TOO_LONG_BODY : body;
+};
+/**
+ * Create a request-promise-native compatible callable client.
+ * @param [logger] when given, verbose request/response logs are emitted
+ */
+export const createRequestClient = (logger) => {
+    const request = (params = {}) => new Promise((resolve, reject) => {
+        const { url, method: rawMethod = 'GET', headers = {}, resolveWithFullResponse = false, simple = true, timeout = 0, qs } = params;
+        const method = String(rawMethod).toUpperCase();
+        const targetUrl = `${url}${buildQueryString(qs)}`;
+        const { body, contentType } = buildBody(params);
+        const requestHeaders = toPlainHeaders(headers);
+        if (contentType
+            && !Object.keys(requestHeaders).some(key => key.toLowerCase() === 'content-type')) {
+            requestHeaders['Content-Type'] = contentType;
+        }
+        const abortController = new AbortController();
+        const timer = timeout > 0
+            ? setTimeout(() => abortController.abort(new Error('Request timed out')), timeout)
+            : null;
+        const requestForDump = {
+            method,
+            uri: {
+                protocol: new URL(targetUrl).protocol,
+                href: targetUrl
+            },
+            headers: requestHeaders,
+            req: {},
+            _json: params.json !== undefined && params.json !== false
+                ? true : body !== undefined,
+            formData: params.formData || null,
+            body: params.formData
+                ? new URLSearchParams(params.formData).toString()
+                : body
+        };
+        const id = ++debugId;
+        if (logger) {
+            logger.verbose('[HTTP_REQUEST_%s] [%s %s] [REQ_HEADERS: %s] [REQ_BODY: %s]', id, method, targetUrl, JSON.stringify(requestHeaders), truncateBody(body));
+        }
+        fetch(targetUrl, {
+            method,
+            headers: requestHeaders,
+            body,
+            signal: abortController.signal,
+            redirect: 'follow'
+        }).then(async (response) => {
+            if (timer) {
+                clearTimeout(timer);
+            }
+            const rawBody = await response.text();
+            let parsedBody = rawBody;
+            if (params.json !== undefined && params.json !== false) {
+                try {
+                    parsedBody = JSON.parse(rawBody);
+                }
+                catch {
+                    parsedBody = rawBody;
+                }
+            }
+            const responseForDump = {
+                statusCode: response.status,
+                statusMessage: response.statusText,
+                headers: toPlainHeaders(Object.fromEntries(response.headers.entries())),
+                body: parsedBody,
+                request: requestForDump
+            };
+            if (logger) {
+                logger.verbose('[HTTP_RESPONSE_%s] [%s %s] [%s] [RES_HEADERS: %s] [RES_BODY: %s]', id, method, targetUrl, response.status, JSON.stringify(responseForDump.headers), truncateBody(parsedBody));
+            }
+            if (response.status >= 400 && simple) {
+                const error = new Error(`Response status ${response.status}`);
+                error.name = 'StatusCodeError';
+                error.statusCode = response.status;
+                error.response = responseForDump;
+                error.request = requestForDump;
+                reject(error);
+                return;
+            }
+            resolve(resolveWithFullResponse ? responseForDump : parsedBody);
+        }).catch((err) => {
+            if (timer) {
+                clearTimeout(timer);
+            }
+            // 与原实现一致：非 Error 值时 err.message 为 undefined，new Error(undefined) 的语义保持不变
+            const error = new Error(err.message);
+            error.name = 'RequestError';
+            error.request = requestForDump;
+            reject(error);
+        });
+    });
+    return request;
+};
+//# sourceMappingURL=request_client.js.map

package/dist/utils/request_client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"request_client.js","sourceRoot":"","sources":["../../src/utils/request_client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAgDH,MAAM,eAAe,GAAG,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,sBAAgC,EAAE,EAAE,CAAC,IAAI,IAAI,CAAC;AAC3F,MAAM,aAAa,GAAG,cAAc,CAAC;AAErC,IAAI,OAAO,GAAG,CAAC,CAAC;AAEhB,MAAM,cAAc,GAAG,CAAC,UAAmC,EAAE,EAA0B,EAAE;IACvF,MAAM,MAAM,GAA2B,EAAE,CAAC;IAC1C,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE;QAC/C,MAAM,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;IAC9B,CAAC,CAAC,CAAC;IACH,OAAO,MAAM,CAAC;AAChB,CAAC,CAAC;AAEF,MAAM,gBAAgB,GAAG,CAAC,EAAqC,EAAU,EAAE;IAAI,IAAI,EAAE,KAAK,SAAS,IAAI,EAAE,KAAK,IAAI,EAAE,CAAC;QACjH,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,IAAI,OAAO,EAAE,KAAK,QAAQ,EAAE,CAAC;QAC3B,OAAO,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC;IAC5C,CAAC;IACD,OAAO,IAAI,IAAI,eAAe,CAAC,EAA4B,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC;AAC5E,CAAC,CAAC;AAEF,MAAM,SAAS,GAAG,CAAC,MAA2B,EAA8D,EAAE;IAC5G,IAAI,MAAM,CAAC,QAAQ,EAAE,CAAC;QACpB,MAAM,IAAI,GAAG,IAAI,QAAQ,EAAE,CAAC;QAC5B,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE;YACvD,gDAAgD;YAChD,IAAI,CAAC,MAAM,CAAC,GAAG,EAAE,KAAsB,CAAC,CAAC;QAC3C,CAAC,CAAC,CAAC;QACH,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC;IAC3C,CAAC;IACD,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC;QAChB,OAAO;YACL,IAAI,EAAE,IAAI,eAAe,CAAC,MAAM,CAAC,IAA8B,CAAC,CAAC,QAAQ,EAAE;YAC3E,WAAW,EAAE,mCAAmC;SACjD,CAAC;IACJ,CAAC;IACD,qEAAqE;IACrE,IAAI,MAAM,CAAC,IAAI,KAAK,SAAS,IAAI,MAAM,CAAC,IAAI,KAAK,KAAK,IAAI,MAAM,CAAC,IAAI,KAAK,IAAI,EAAE,CAAC;QAC/E,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,WAAW,EAAE,kBAAkB,EAAE,CAAC;IAChF,CAAC;IACD,IAAI,MAAM,CAAC,IAAI,KAAK,IAAI,IAAI,MAAM,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QACtD,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,WAAW,EAAE,kBAAkB,EAAE,CAAC;IAChF,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,MAAM,CAAC,IAA4B,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC;AAC1E,CAAC,CAAC;AAEF,MAAM,YAAY,GAAG,CAAC,IAAa,EAAU,EAAE;IAC7C,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;QAC7B,OAAO,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAClC,CAAC;IACD,OAAO,IAAI,CAAC,MAAM,GAAG,eAAe,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,IAAI,CAAC;AAC9D,CAAC,CAAC;AAEF;;;GAGG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,MAA0E,EAAE,EAAE;IAChH,MAAM,OAAO,GAAG,CAAC,SAA8B,EAAE,EAAoB,EAAE,CAAC,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACtG,MAAM,EACJ,GAAG,EACH,MAAM,EAAE,SAAS,GAAG,KAAK,EACzB,OAAO,GAAG,EAAE,EACZ,uBAAuB,GAAG,KAAK,EAC/B,MAAM,GAAG,IAAI,EACb,OAAO,GAAG,CAAC,EACX,EAAE,EACH,GAAG,MAAM,CAAC;QAEX,MAAM,MAAM,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC,WAAW,EAAE,CAAC;QAC/C,MAAM,SAAS,GAAG,GAAG,GAAG,GAAG,gBAAgB,CAAC,EAAE,CAAC,EAAE,CAAC;QAClD,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC;QAEhD,MAAM,cAAc,GAAG,cAAc,CAAC,OAAO,CAAC,CAAC;QAC/C,IAAI,WAAW;eACV,CAAC,MAAM,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,WAAW,EAAE,KAAK,cAAc,CAAC,EAAE,CAAC;YACpF,cAAc,CAAC,cAAc,CAAC,GAAG,WAAW,CAAC;QAC/C,CAAC;QAED,MAAM,eAAe,GAAG,IAAI,eAAe,EAAE,CAAC;QAC9C,MAAM,KAAK,GAAG,OAAO,GAAG,CAAC;YACvB,CAAC,CAAC,UAAU,CAAC,GAAG,EAAE,CAAC,eAAe,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,mBAAmB,CAAC,CAAC,EAAE,OAAO,CAAC;YAClF,CAAC,CAAC,IAAI,CAAC;QAET,MAAM,cAAc,GAAmB;YACrC,MAAM;YACN,GAAG,EAAE;gBACH,QAAQ,EAAE,IAAI,GAAG,CAAC,SAAS,CAAC,CAAC,QAAQ;gBACrC,IAAI,EAAE,SAAS;aAChB;YACD,OAAO,EAAE,cAAc;YACvB,GAAG,EAAE,EAAE;YACP,KAAK,EAAE,MAAM,CAAC,IAAI,KAAK,SAAS,IAAI,MAAM,CAAC,IAAI,KAAK,KAAK;gBACvD,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,KAAK,SAAS;YAC7B,QAAQ,EAAE,MAAM,CAAC,QAAQ,IAAI,IAAI;YACjC,IAAI,EAAE,MAAM,CAAC,QAAQ;gBACnB,CAAC,CAAC,IAAI,eAAe,CAAC,MAAM,CAAC,QAAkC,CAAC,CAAC,QAAQ,EAAE;gBAC3E,CAAC,CAAC,IAAI;SACT,CAAC;QAEF,MAAM,EAAE,GAAG,EAAE,OAAO,CAAC;QACrB,IAAI,MAAM,EAAE,CAAC;YACX,MAAM,CAAC,OAAO,CAAC,4DAA4D,EAAE,EAAE,EAC7E,MAAM,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,CAAC,cAAc,CAAC,EAAE,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC;QAC3E,CAAC;QAED,KAAK,CAAC,SAAS,EAAE;YACf,MAAM;YACN,OAAO,EAAE,cAAc;YACvB,IAAI;YACJ,MAAM,EAAE,eAAe,CAAC,MAAM;YAC9B,QAAQ,EAAE,QAAQ;SACnB,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,QAAQ,EAAE,EAAE;YACzB,IAAI,KAAK,EAAE,CAAC;gBACV,YAAY,CAAC,KAAK,CAAC,CAAC;YACtB,CAAC;YACD,MAAM,OAAO,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;YACtC,IAAI,UAAU,GAAY,OAAO,CAAC;YAClC,IAAI,MAAM,CAAC,IAAI,KAAK,SAAS,IAAI,MAAM,CAAC,IAAI,KAAK,KAAK,EAAE,CAAC;gBACvD,IAAI,CAAC;oBACH,UAAU,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;gBACnC,CAAC;gBAAC,MAAM,CAAC;oBACP,UAAU,GAAG,OAAO,CAAC;gBACvB,CAAC;YACH,CAAC;YAED,MAAM,eAAe,GAAoB;gBACvC,UAAU,EAAE,QAAQ,CAAC,MAAM;gBAC3B,aAAa,EAAE,QAAQ,CAAC,UAAU;gBAClC,OAAO,EAAE,cAAc,CAAC,MAAM,CAAC,WAAW,CAAC,QAAQ,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;gBACvE,IAAI,EAAE,UAAU;gBAChB,OAAO,EAAE,cAAc;aACxB,CAAC;YAEF,IAAI,MAAM,EAAE,CAAC;gBACX,MAAM,CAAC,OAAO,CAAC,kEAAkE,EAAE,EAAE,EACnF,MAAM,EAAE,SAAS,EAAE,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC,SAAS,CAAC,eAAe,CAAC,OAAO,CAAC,EAC3E,YAAY,CAAC,UAAU,CAAC,CAAC,CAAC;YAC9B,CAAC;YAED,IAAI,QAAQ,CAAC,MAAM,IAAI,GAAG,IAAI,MAAM,EAAE,CAAC;gBACrC,MAAM,KAAK,GAAG,IAAI,KAAK,CAAC,mBAAmB,QAAQ,CAAC,MAAM,EAAE,CAAuB,CAAC;gBACpF,KAAK,CAAC,IAAI,GAAG,iBAAiB,CAAC;gBAC/B,KAAK,CAAC,UAAU,GAAG,QAAQ,CAAC,MAAM,CAAC;gBACnC,KAAK,CAAC,QAAQ,GAAG,eAAe,CAAC;gBACjC,KAAK,CAAC,OAAO,GAAG,cAAc,CAAC;gBAC/B,MAAM,CAAC,KAAK,CAAC,CAAC;gBACd,OAAO;YACT,CAAC;YAED,OAAO,CAAC,uBAAuB,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC;QAClE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;YACxB,IAAI,KAAK,EAAE,CAAC;gBACV,YAAY,CAAC,KAAK,CAAC,CAAC;YACtB,CAAC;YACD,yEAAyE;YACzE,MAAM,KAAK,GAAG,IAAI,KAAK,CAAE,GAAa,CAAC,OAAO,CAAuB,CAAC;YACtE,KAAK,CAAC,IAAI,GAAG,cAAc,CAAC;YAC5B,KAAK,CAAC,OAAO,GAAG,cAAc,CAAC;YAC/B,MAAM,CAAC,KAAK,CAAC,CAAC;QAChB,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,OAAO,OAAO,CAAC;AACjB,CAAC,CAAC"}

package/dist/utils/smart_query.d.ts

@@ -0,0 +1,144 @@
+type SmartQueryWhere = Record<string, Record<PropertyKey, unknown>>;
+type SmartQueryCriteria = {
+    order?: unknown[];
+    where?: SmartQueryWhere;
+};
+/**
+ * 自动根据 req.query 生成 sequelize 查询条件, 自动判断参数清单中是否有值
+ */
+export default class SmartQuery {
+    query: Record<string, unknown>;
+    /** WHERE 查询条件 */
+    where: SmartQueryWhere;
+    /**
+     * 排序列表
+     */
+    order: unknown[];
+    constructor(query: Record<string, unknown>);
+    /**
+     * 当 query 中包含名为 paramName 的属性时，为 fieldName 添加全等查询条件
+     * @param paramName query 中的参数名称
+     * @param fieldName 对应的数据库字段名称，默认与 paramName 一致
+     * @param defaultValue 当 query 中不包含 paramName 或为空时，使用该值
+     */
+    equal(paramName: string, fieldName?: string, defaultValue?: unknown): this;
+    /**
+     * 当 query 中包含名为 paramName 的属性时，为 fieldName 添加 in 查询条件, 值可以为 `delimiter` 分割的字符串或者数组
+     * @param paramName query 中的参数名称
+     * @param [fieldName=paramName] 对应的数据库字段名称，默认与 paramName 一致
+     * @param [defaultValue=null] 当 query 中不包含 paramName 或为空时，使用该值
+     * @param [delimiter=,] 当值为字符串时的分隔符，默认为 ,
+     */
+    in(paramName: string, fieldName?: string, defaultValue?: unknown, delimiter?: string): this;
+    /**
+     * 当 query 中包含名为 paramName 的属性时，为 fieldName 添加 not in 查询条件, 值可以为 `delimiter` 分割的字符串或者数组
+     * @param paramName query 中的参数名称
+     * @param [fieldName=paramName] 对应的数据库字段名称，默认与 paramName 一致
+     * @param [defaultValue=null] 当 query 中不包含 paramName 或为空时，使用该值
+     * @param [delimiter=,] 当值为字符串时的分隔符，默认为 ,
+     */
+    notIn(paramName: string, fieldName?: string, defaultValue?: unknown, delimiter?: string): this;
+    /**
+     * 当 query 中包含名为 paramName 的属性时，为 fieldName 添加 LIKE 查询条件，并自动在值的头尾添加 %
+     * @param paramName query 中的参数名称
+     * @param fieldName 对应的数据库字段名称，默认与 paramName 一致
+     * @param defaultValue 当 query 中不包含 paramName 或为空时，使用该值
+     */
+    like(paramName: string, fieldName?: string, defaultValue?: unknown): this;
+    /**
+     * 当 query 中包含名为 paramName 的属性时，为 fieldName 添加 LIKE 查询条件，并自动在值的尾部添加 %
+     * @param paramName query 中的参数名称
+     * @param fieldName 对应的数据库字段名称，默认与 paramName 一致
+     * @param defaultValue 当 query 中不包含 paramName 或为空时，使用该值
+     */
+    startsWith(paramName: string, fieldName?: string, defaultValue?: unknown): this;
+    /**
+     * 当 query 中包含名为 paramName 的属性时，为 fieldName 添加 LIKE 查询条件，并自动在值的头部添加 %
+     * @param paramName query 中的参数名称
+     * @param fieldName 对应的数据库字段名称，默认与 paramName 一致
+     * @param defaultValue 当 query 中不包含 paramName 或为空时，使用该值
+     */
+    endsWith(paramName: string, fieldName?: string, defaultValue?: unknown): this;
+    /**
+     * 当 query 中包含名为 paramName 的属性时，为 fieldName 添加 >= 查询条件
+     * @param paramName query 中的参数名称
+     * @param fieldName 对应的数据库字段名称，默认与 paramName 一致
+     * @param defaultValue 当 query 中不包含 paramName 或为空时，使用该值
+     */
+    gte(paramName: string, fieldName?: string, defaultValue?: unknown): this;
+    /**
+     * 当 query 中包含名为 paramName 的属性时，为 fieldName 添加 <= 查询条件
+     * @param paramName query 中的参数名称
+     * @param fieldName 对应的数据库字段名称，默认与 paramName 一致
+     * @param defaultValue 当 query 中不包含 paramName 或为空时，使用该值
+     */
+    lte(paramName: string, fieldName?: string, defaultValue?: unknown): this;
+    /**
+     * 当 query 中包含名为 minParamName 的属性时，为 fieldName 添加 >= 查询条件，
+     * 当 query 中包含名为 maxParamName 的属性时，为 fieldName 添加 <= 查询条件
+     * @param minParamName query 中的最小值参数名称
+     * @param maxParamName query 中的最大值参数名称
+     * @param fieldName 对应的数据库字段名称
+     * @param minDefault 当 query 中不包含 minParamName 或为空时，使用该值作为默认值
+     * @param maxDefault 当 query 中不包含 maxParamName 或为空时，使用该值作为默认值
+     */
+    range(minParamName: string, maxParamName: string, fieldName: string, minDefault?: unknown, maxDefault?: unknown): this;
+    /**
+     * 当 query 中包含名为 minParamName 的属性时，为 fieldName 添加 >= 查询条件并将时分秒设为0格式化到 targetFormat ，
+     * 当 query 中包含名为 maxParamName 的属性时，为 fieldName 添加 <= 查询条件并将时分秒分别设为 23:59:59 后格式化到 targetFormat
+     * @param minParamName query 中的最小值参数名称
+     * @param maxParamName query 中的最大值参数名称
+     * @param fieldName 对应的数据库字段名称
+     * @param [minDefault=null] 当 query 中不包含 minParamName 或为空时，使用该值作为默认值
+     * @param [maxDefault=null] 当 query 中不包含 maxParamName 或为空时，使用该值作为默认值
+     * @param [sourceFormat='YYYY-MM-DD'] 原值时间格式
+     * @param [targetFormat='X'] 数据库时间格式
+     */
+    dateRange(minParamName: string, maxParamName: string, fieldName: string, minDefault?: string | null, maxDefault?: string | null, sourceFormat?: string, targetFormat?: string): this;
+    /**
+     * 当 query 中包含名为 minParamName 的属性时，为 fieldName 添加 >= 查询条件并格式化到 targetFormat ，
+     * 当 query 中包含名为 maxParamName 的属性时，为 fieldName 添加 <= 查询条件并并格式化到 targetFormat
+     * @param minParamName query 中的最小值参数名称
+     * @param maxParamName query 中的最大值参数名称
+     * @param fieldName 对应的数据库字段名称
+     * @param [minDefault=null] 当 query 中不包含 minParamName 或为空时，使用该值作为默认值
+     * @param [maxDefault=null] 当 query 中不包含 maxParamName 或为空时，使用该值作为默认值
+     * @param [sourceFormat='YYYY-MM-DD HH:mm:ss'] 原值时间格式
+     * @param [targetFormat='X'] 数据库时间格式
+     */
+    dateTimeRange(minParamName: string, maxParamName: string, fieldName: string, minDefault?: string | null, maxDefault?: string | null, sourceFormat?: string, targetFormat?: string): this;
+    /**
+     * 处理用户的排序请求
+     * @param [autoMapping=[]] 根据字段名自动排序，数组成员为字段名，每个字段名自动生成正反序，
+     *                                  如 `created_at` 生成 `created_at` 正序和 `-created_at` 倒序
+     * @param [manualMapping={}]
+     * @param [defaultOrder=null] 默认排序，当 query 中不包含 `paramName` 属性时使用。如不设置则为 `autoMapping` 的第一个字段的倒序
+     * @param [paramName='order'] 参数名称
+     */
+    orderable(autoMapping?: string[], manualMapping?: Record<string, unknown>, defaultOrder?: unknown, paramName?: string): this;
+    /**
+     * 获取完整的有效查询参数
+     */
+    getCriteria(): SmartQueryCriteria;
+    /**
+     * 当 query 中包含名为 paramName 的属性时，为 fieldName 添加 in 或 not in 查询条件, 值可以为 `delimiter` 分割的字符串或者数组
+     * @protected
+     * @param paramName query 中的参数名称
+     * @param fieldName 对应的数据库字段名称
+     * @param [defaultValue=null] 当 query 中不包含 paramName 或为空时，使用该值
+     * @param [delimiter=,] 当值为字符串时的分隔符，默认为 ,
+     * @param [negation=false] 是否取反，为 true 时使用 $notIn
+     */
+    applyIn(paramName: string, fieldName: string, defaultValue?: unknown, delimiter?: string, negation?: boolean): this;
+    /**
+     * 添加 where
+     *
+     * @protected
+     */
+    applyWhere(filedName: string, predicate: string, value: unknown): void;
+    /**
+     * 判定指定名称的参数是否有效
+     */
+    determineParam(paramName: string): boolean;
+}
+export {};

package/dist/utils/smart_query.js

@@ -0,0 +1,310 @@
+import moment from 'moment-timezone';
+import { Op } from 'sequelize';
+import { InvalidArgumentException } from "../exceptions/index.js";
+// Op 的值是 sequelize 的 symbol 运算符；where 的键可能是 string 或 symbol
+const OPERATORS = {
+    $eq: Op.eq,
+    $like: Op.like,
+    $in: Op.in,
+    $notIn: Op.notIn,
+    $gte: Op.gte,
+    $lte: Op.lte
+};
+/**
+ * 自动根据 req.query 生成 sequelize 查询条件, 自动判断参数清单中是否有值
+ */
+export default class SmartQuery {
+    query;
+    /** WHERE 查询条件 */
+    where;
+    /**
+     * 排序列表
+     */
+    order;
+    constructor(query) {
+        this.query = query;
+        this.where = {};
+        this.order = [];
+    }
+    /**
+     * 当 query 中包含名为 paramName 的属性时，为 fieldName 添加全等查询条件
+     * @param paramName query 中的参数名称
+     * @param fieldName 对应的数据库字段名称，默认与 paramName 一致
+     * @param defaultValue 当 query 中不包含 paramName 或为空时，使用该值
+     */
+    equal(paramName, fieldName = paramName, defaultValue = null) {
+        const value = this.determineParam(paramName) ? this.query[paramName] : defaultValue;
+        if (value != null) {
+            this.applyWhere(fieldName, '$eq', value);
+        }
+        return this;
+    }
+    /**
+     * 当 query 中包含名为 paramName 的属性时，为 fieldName 添加 in 查询条件, 值可以为 `delimiter` 分割的字符串或者数组
+     * @param paramName query 中的参数名称
+     * @param [fieldName=paramName] 对应的数据库字段名称，默认与 paramName 一致
+     * @param [defaultValue=null] 当 query 中不包含 paramName 或为空时，使用该值
+     * @param [delimiter=,] 当值为字符串时的分隔符，默认为 ,
+     */
+    in(paramName, fieldName = paramName, defaultValue = null, delimiter = ',') {
+        return this.applyIn(paramName, fieldName, defaultValue, delimiter, false);
+    }
+    /**
+     * 当 query 中包含名为 paramName 的属性时，为 fieldName 添加 not in 查询条件, 值可以为 `delimiter` 分割的字符串或者数组
+     * @param paramName query 中的参数名称
+     * @param [fieldName=paramName] 对应的数据库字段名称，默认与 paramName 一致
+     * @param [defaultValue=null] 当 query 中不包含 paramName 或为空时，使用该值
+     * @param [delimiter=,] 当值为字符串时的分隔符，默认为 ,
+     */
+    notIn(paramName, fieldName = paramName, defaultValue = null, delimiter = ',') {
+        return this.applyIn(paramName, fieldName, defaultValue, delimiter, true);
+    }
+    /**
+     * 当 query 中包含名为 paramName 的属性时，为 fieldName 添加 LIKE 查询条件，并自动在值的头尾添加 %
+     * @param paramName query 中的参数名称
+     * @param fieldName 对应的数据库字段名称，默认与 paramName 一致
+     * @param defaultValue 当 query 中不包含 paramName 或为空时，使用该值
+     */
+    like(paramName, fieldName = paramName, defaultValue = null) {
+        const value = this.determineParam(paramName) ? this.query[paramName] : defaultValue;
+        if (value != null) {
+            this.applyWhere(fieldName, '$like', `%${value}%`);
+        }
+        return this;
+    }
+    /**
+     * 当 query 中包含名为 paramName 的属性时，为 fieldName 添加 LIKE 查询条件，并自动在值的尾部添加 %
+     * @param paramName query 中的参数名称
+     * @param fieldName 对应的数据库字段名称，默认与 paramName 一致
+     * @param defaultValue 当 query 中不包含 paramName 或为空时，使用该值
+     */
+    startsWith(paramName, fieldName = paramName, defaultValue = null) {
+        const value = this.determineParam(paramName) ? this.query[paramName] : defaultValue;
+        if (value != null) {
+            this.applyWhere(fieldName, '$like', `${value}%`);
+        }
+        return this;
+    }
+    /**
+     * 当 query 中包含名为 paramName 的属性时，为 fieldName 添加 LIKE 查询条件，并自动在值的头部添加 %
+     * @param paramName query 中的参数名称
+     * @param fieldName 对应的数据库字段名称，默认与 paramName 一致
+     * @param defaultValue 当 query 中不包含 paramName 或为空时，使用该值
+     */
+    endsWith(paramName, fieldName = paramName, defaultValue = null) {
+        const value = this.determineParam(paramName) ? this.query[paramName] : defaultValue;
+        if (value != null) {
+            this.applyWhere(fieldName, '$like', `%${value}`);
+        }
+        return this;
+    }
+    /**
+     * 当 query 中包含名为 paramName 的属性时，为 fieldName 添加 >= 查询条件
+     * @param paramName query 中的参数名称
+     * @param fieldName 对应的数据库字段名称，默认与 paramName 一致
+     * @param defaultValue 当 query 中不包含 paramName 或为空时，使用该值
+     */
+    gte(paramName, fieldName = paramName, defaultValue = null) {
+        const value = this.determineParam(paramName) ? this.query[paramName] : defaultValue;
+        if (value != null) {
+            this.applyWhere(fieldName, '$gte', value);
+        }
+        return this;
+    }
+    /**
+     * 当 query 中包含名为 paramName 的属性时，为 fieldName 添加 <= 查询条件
+     * @param paramName query 中的参数名称
+     * @param fieldName 对应的数据库字段名称，默认与 paramName 一致
+     * @param defaultValue 当 query 中不包含 paramName 或为空时，使用该值
+     */
+    lte(paramName, fieldName = paramName, defaultValue = null) {
+        const value = this.determineParam(paramName) ? this.query[paramName] : defaultValue;
+        if (value != null) {
+            this.applyWhere(fieldName, '$lte', value);
+        }
+        return this;
+    }
+    /**
+     * 当 query 中包含名为 minParamName 的属性时，为 fieldName 添加 >= 查询条件，
+     * 当 query 中包含名为 maxParamName 的属性时，为 fieldName 添加 <= 查询条件
+     * @param minParamName query 中的最小值参数名称
+     * @param maxParamName query 中的最大值参数名称
+     * @param fieldName 对应的数据库字段名称
+     * @param minDefault 当 query 中不包含 minParamName 或为空时，使用该值作为默认值
+     * @param maxDefault 当 query 中不包含 maxParamName 或为空时，使用该值作为默认值
+     */
+    range(minParamName, maxParamName, fieldName, minDefault = null, maxDefault = null) {
+        const min = this.determineParam(minParamName) ? this.query[minParamName] : minDefault;
+        const max = this.determineParam(maxParamName) ? this.query[maxParamName] : maxDefault;
+        if (min != null) {
+            this.applyWhere(fieldName, '$gte', min);
+        }
+        if (max != null) {
+            this.applyWhere(fieldName, '$lte', max);
+        }
+        return this;
+    }
+    /**
+     * 当 query 中包含名为 minParamName 的属性时，为 fieldName 添加 >= 查询条件并将时分秒设为0格式化到 targetFormat ，
+     * 当 query 中包含名为 maxParamName 的属性时，为 fieldName 添加 <= 查询条件并将时分秒分别设为 23:59:59 后格式化到 targetFormat
+     * @param minParamName query 中的最小值参数名称
+     * @param maxParamName query 中的最大值参数名称
+     * @param fieldName 对应的数据库字段名称
+     * @param [minDefault=null] 当 query 中不包含 minParamName 或为空时，使用该值作为默认值
+     * @param [maxDefault=null] 当 query 中不包含 maxParamName 或为空时，使用该值作为默认值
+     * @param [sourceFormat='YYYY-MM-DD'] 原值时间格式
+     * @param [targetFormat='X'] 数据库时间格式
+     */
+    dateRange(minParamName, maxParamName, fieldName, minDefault = null, maxDefault = null, sourceFormat = 'YYYY-MM-DD', targetFormat = 'X') {
+        const minParam = this.determineParam(minParamName)
+            ? this.query[minParamName]
+            : null;
+        // minDefault 为 null 时依赖 moment(null) 的 invalid 语义，不做可选值替换
+        const min = minParam != null && moment(minParam, sourceFormat).isValid()
+            ? moment(minParam, sourceFormat)
+            : moment(minDefault, sourceFormat);
+        const maxParam = this.determineParam(maxParamName) ? this.query[maxParamName] : null;
+        const max = maxParam != null && moment(maxParam, sourceFormat).isValid()
+            ? moment(maxParam, sourceFormat)
+            : moment(maxDefault, sourceFormat);
+        if (min.isValid()) {
+            this.applyWhere(fieldName, '$gte', min.hours(0).minutes(0).seconds(0).format(targetFormat));
+        }
+        if (max.isValid()) {
+            this.applyWhere(fieldName, '$lte', max.hours(23).minutes(59).seconds(59).format(targetFormat));
+        }
+        return this;
+    }
+    /**
+     * 当 query 中包含名为 minParamName 的属性时，为 fieldName 添加 >= 查询条件并格式化到 targetFormat ，
+     * 当 query 中包含名为 maxParamName 的属性时，为 fieldName 添加 <= 查询条件并并格式化到 targetFormat
+     * @param minParamName query 中的最小值参数名称
+     * @param maxParamName query 中的最大值参数名称
+     * @param fieldName 对应的数据库字段名称
+     * @param [minDefault=null] 当 query 中不包含 minParamName 或为空时，使用该值作为默认值
+     * @param [maxDefault=null] 当 query 中不包含 maxParamName 或为空时，使用该值作为默认值
+     * @param [sourceFormat='YYYY-MM-DD HH:mm:ss'] 原值时间格式
+     * @param [targetFormat='X'] 数据库时间格式
+     */
+    dateTimeRange(minParamName, maxParamName, fieldName, minDefault = null, maxDefault = null, sourceFormat = 'YYYY-MM-DD HH:mm:ss', targetFormat = 'X') {
+        const minParam = this.determineParam(minParamName)
+            ? this.query[minParamName]
+            : null;
+        // minDefault 为 null 时依赖 moment(null) 的 invalid 语义，不做可选值替换
+        const min = minParam != null && moment(minParam, sourceFormat).isValid()
+            ? moment(minParam, sourceFormat)
+            : moment(minDefault, sourceFormat);
+        const maxParam = this.determineParam(maxParamName) ? this.query[maxParamName] : null;
+        const max = maxParam != null && moment(maxParam, sourceFormat).isValid()
+            ? moment(maxParam, sourceFormat)
+            : moment(maxDefault, sourceFormat);
+        if (min.isValid()) {
+            this.applyWhere(fieldName, '$gte', min.format(targetFormat));
+        }
+        if (max.isValid()) {
+            this.applyWhere(fieldName, '$lte', max.format(targetFormat));
+        }
+        return this;
+    }
+    /**
+     * 处理用户的排序请求
+     * @param [autoMapping=[]] 根据字段名自动排序，数组成员为字段名，每个字段名自动生成正反序，
+     *                                  如 `created_at` 生成 `created_at` 正序和 `-created_at` 倒序
+     * @param [manualMapping={}]
+     * @param [defaultOrder=null] 默认排序，当 query 中不包含 `paramName` 属性时使用。如不设置则为 `autoMapping` 的第一个字段的倒序
+     * @param [paramName='order'] 参数名称
+     */
+    orderable(autoMapping = [], manualMapping = {}, defaultOrder = null, paramName = 'order') {
+        const ordersMapping = {};
+        let conventionOrder = defaultOrder;
+        if (autoMapping instanceof Array) {
+            autoMapping.forEach((field) => {
+                ordersMapping[`-${field}`] = [field, 'DESC'];
+                ordersMapping[field] = [field, 'ASC'];
+            });
+            if (conventionOrder === null) {
+                conventionOrder = [autoMapping[0], 'DESC'];
+            }
+        }
+        Object.assign(ordersMapping, manualMapping);
+        const order = this.determineParam(paramName) && Object.keys(ordersMapping).includes(this.query[paramName])
+            ? ordersMapping[this.query[paramName]] : conventionOrder;
+        if (order != null) {
+            this.order = [order];
+        }
+        return this;
+    }
+    /**
+     * 获取完整的有效查询参数
+     */
+    getCriteria() {
+        const criteria = {};
+        if (this.order instanceof Array && this.order.length > 0) {
+            criteria.order = this.order;
+        }
+        if (Object.keys(this.where).length > 0) {
+            criteria.where = this.where;
+        }
+        return criteria;
+    }
+    /**
+     * 当 query 中包含名为 paramName 的属性时，为 fieldName 添加 in 或 not in 查询条件, 值可以为 `delimiter` 分割的字符串或者数组
+     * @protected
+     * @param paramName query 中的参数名称
+     * @param fieldName 对应的数据库字段名称
+     * @param [defaultValue=null] 当 query 中不包含 paramName 或为空时，使用该值
+     * @param [delimiter=,] 当值为字符串时的分隔符，默认为 ,
+     * @param [negation=false] 是否取反，为 true 时使用 $notIn
+     */
+    applyIn(paramName, fieldName, defaultValue = null, delimiter = ',', negation = false) {
+        let value = this.determineParam(paramName) ? this.query[paramName] : defaultValue;
+        if (value === null) {
+            return this;
+        }
+        if (typeof value === 'number') {
+            value = String(value);
+        }
+        if (typeof value === 'string') {
+            value = value.split(delimiter);
+        }
+        else if (value instanceof Array === false) {
+            throw new InvalidArgumentException(`Value for contains must be typeof string or array, but \`${typeof value}\` given`);
+        }
+        this.applyWhere(fieldName, negation ? '$notIn' : '$in', value);
+        return this;
+    }
+    /**
+     * 添加 where
+     *
+     * @protected
+     */
+    applyWhere(filedName, predicate, value) {
+        if (!Object.keys(this.where).includes(filedName)) {
+            this.where[filedName] = {};
+        }
+        this.where[filedName][OPERATORS[predicate] || predicate] = value;
+    }
+    /**
+     * 判定指定名称的参数是否有效
+     */
+    determineParam(paramName) {
+        if (!Object.keys(this.query).includes(paramName)) {
+            return false;
+        }
+        const value = this.query[paramName];
+        if (value === null) {
+            return false;
+        }
+        if (typeof value === 'string') {
+            return value.trim() !== '';
+        }
+        if (value instanceof Array) {
+            return value.length > 0;
+        }
+        if (value instanceof Object) {
+            return Object.keys(value).length > 0;
+        }
+        return true;
+    }
+}
+//# sourceMappingURL=smart_query.js.map