zentao-api 0.5.1 → 0.5.3

package/dist/index.d.ts

@@ -2,7 +2,7 @@ export { ZentaoClient } from './client/index.js';
 export { ERRORS, ZentaoError, type ErrorCode } from './misc/errors.js';
 export { getGlobalOptions, setGlobalOptions } from './misc/global-options.js';
 export { ZENTAO_PROFILES_STORAGE_KEY, addProfile, deleteProfile, getAllProfiles, getProfile, getProfileKey, switchProfile, } from './profiles/index.js';
-export { defineModuleActions, defineModules, type DefineModulesOptions, extendModuleAction, getModuleNames, getModule, getModuleAction, getModuleActionParams, getObjectProps, } from './modules/registry.js';
+export { defineModuleActions, defineModules, type DefineModulesOptions, type ExportRegistryOptions, type ExportedModuleAction, type ExportedModuleDefinition, exportRegistry, extendModuleAction, getModuleNames, getModule, getModuleAction, getModuleActionParams, getObjectProps, } from './modules/registry.js';
 export { request, type BuiltinRequestName, type RequestParamsFor, type RequestResultFor, } from './request/index.js';
 export { pickFields, pickFieldsSingle, filterData, searchData, sortData, processData, } from './utils/index.js';
 export { BUILD, VERSION } from './version.js';

package/dist/index.js

@@ -2,7 +2,7 @@ export { ZentaoClient } from './client/index.js';
 export { ERRORS, ZentaoError } from './misc/errors.js';
 export { getGlobalOptions, setGlobalOptions } from './misc/global-options.js';
 export { ZENTAO_PROFILES_STORAGE_KEY, addProfile, deleteProfile, getAllProfiles, getProfile, getProfileKey, switchProfile, } from './profiles/index.js';
-export { defineModuleActions, defineModules, extendModuleAction, getModuleNames, getModule, getModuleAction, getModuleActionParams, getObjectProps, } from './modules/registry.js';
+export { defineModuleActions, defineModules, exportRegistry, extendModuleAction, getModuleNames, getModule, getModuleAction, getModuleActionParams, getObjectProps, } from './modules/registry.js';
 export { request, } from './request/index.js';
 export { pickFields, pickFieldsSingle, filterData, searchData, sortData, processData, } from './utils/index.js';
 export { BUILD, VERSION } from './version.js';

package/dist/modules/export.d.ts

@@ -0,0 +1,33 @@
+import type { ModuleAction, ModuleActionParam, ModuleDefinition } from '../types/index.js';
+/** 导出的模块动作定义。 */
+export type ExportedModuleAction = Omit<ModuleAction, 'requestBody'> & {
+    bodyParams: ModuleActionParam[];
+};
+/** 导出的模块定义。 */
+export type ExportedModuleDefinition = Omit<ModuleDefinition, 'actions'> & {
+    actions: ExportedModuleAction[];
+};
+/** {@link exportRegistry} 的选项。 */
+export interface ExportRegistryOptions {
+    /** 是否保留注册表中的原始模块定义。 */
+    raw?: boolean;
+    /** 是否递归移除值为函数的属性；默认为 `true`。 */
+    jsonSafe?: boolean;
+}
+/**
+ * 导出注册表。
+ *
+ * 默认会把动作的 `requestBody` 转换成扁平的 `bodyParams`；传入 `raw: true`
+ * 时则保留原始模块结构。默认还会递归移除函数属性，以便安全地序列化为 JSON；
+ * 如需保留函数，可传入 `jsonSafe: false`。
+ *
+ * @param options - 导出选项。
+ * @returns 以模块名为键的模块定义。
+ */
+export declare function exportRegistry(options: ExportRegistryOptions & {
+    raw: true;
+}): Record<string, ModuleDefinition>;
+export declare function exportRegistry(options?: ExportRegistryOptions & {
+    raw?: false;
+}): Record<string, ExportedModuleDefinition>;
+export declare function exportRegistry(options: ExportRegistryOptions): Record<string, ModuleDefinition | ExportedModuleDefinition>;

package/dist/modules/export.js

@@ -0,0 +1,42 @@
+import { getModuleActionParams } from './query.js';
+import { getModuleMapState } from './registry-store.js';
+function removeFunctions(value) {
+    if (Array.isArray(value)) {
+        return value
+            .filter((item) => typeof item !== 'function')
+            .map((item) => removeFunctions(item));
+    }
+    if (value && typeof value === 'object') {
+        const result = {};
+        for (const [key, item] of Object.entries(value)) {
+            if (typeof item !== 'function') {
+                result[key] = removeFunctions(item);
+            }
+        }
+        return result;
+    }
+    return value;
+}
+export function exportRegistry(options = {}) {
+    const raw = options.raw ?? false;
+    const jsonSafe = options.jsonSafe ?? true;
+    const registry = {};
+    getModuleMapState().forEach((module) => {
+        const definition = raw
+            ? module
+            : {
+                ...module,
+                actions: module.actions.map((action) => {
+                    const { requestBody, ...exportedAction } = action;
+                    return {
+                        ...exportedAction,
+                        bodyParams: requestBody
+                            ? getModuleActionParams(module.name, action.name, { roles: ['body'] })
+                            : [],
+                    };
+                }),
+            };
+        registry[module.name] = jsonSafe ? removeFunctions(definition) : definition;
+    });
+    return registry;
+}

package/dist/modules/registry.d.ts

@@ -4239,3 +4239,4 @@ export declare const MODULES: readonly [{
 export { type DefineModulesOptions, defineModules, defineModuleActions, extendModuleAction, resetModuleDefinitions, } from './define.js';
 export { applyBuiltinOverrides };
 export { getModule, getModuleAction, getModuleActionParams, getModuleNames, isModuleName, getObjectProps, } from './query.js';
+export { type ExportRegistryOptions, type ExportedModuleAction, type ExportedModuleDefinition, exportRegistry, } from './export.js';

package/dist/modules/registry.js

@@ -17,3 +17,4 @@ export { applyBuiltinOverrides };
 setPostResetHook(applyBuiltinOverrides);
 applyBuiltinOverrides();
 export { getModule, getModuleAction, getModuleActionParams, getModuleNames, isModuleName, getObjectProps, } from './query.js';
+export { exportRegistry, } from './export.js';

package/dist/request/index.js

@@ -113,7 +113,7 @@ function hasListProcessing(options) {
  *
  * - 对象列表：交由 {@link processData} 完整处理。
  * - 基本类型数组：仅 `limit` 生效（按数量截断），避免破坏原始元素。
- * - 单条对象：只有 `pick` 生效。
+ * - 单条对象：应用 `convertSingle`，再应用 `pick`。
  * - 其他形态原样返回。
  */
 function applyProcessing(data, options) {
@@ -135,8 +135,8 @@ function applyProcessing(data, options) {
         const limit = Number(options.limit);
         return Number.isFinite(limit) && limit >= 0 ? data.slice(0, Math.floor(limit)) : data;
     }
-    if (isRecord(data) && options.pick && options.pick.length > 0) {
-        return processData(data, { pick: options.pick });
+    if (isRecord(data) && (options.convertSingle || (options.pick && options.pick.length > 0))) {
+        return processData(data, { convert: options.convertSingle, pick: options.pick });
     }
     return data;
 }

package/dist/types/data.d.ts

@@ -16,21 +16,21 @@ export interface DataRecordFilterGroup {
     /** 组内条件列表。 */
     conditions: DataRecordFilter[];
 }
-/** 排序表达式，格式为 `字段:asc|desc`。 */
-export type SortExpr = `${string}:${'asc' | 'desc'}`;
+/** 排序表达式；推荐 `字段:asc|desc`，兼容 `字段_asc|desc`。 */
+export type SortExpr = `${string}:${'asc' | 'desc'}` | `${string}_${'asc' | 'desc'}`;
 /** 自定义排序比较函数。 */
 export type SortFn = (a: DataRecord, b: DataRecord) => number;
 /** {@link processData} 处理列表时的选项；执行顺序为 转换 → 过滤 → 搜索 → 排序 → 限制数量 → 摘取。 */
 export interface ProcessListOptions {
-    /** 转换函数，用于对列表中的每条记录进行转换。 */
+    /** 列表转换函数，在过滤前对记录数组整体执行。 */
     convert?: (records: DataRecord[]) => DataRecord[];
-    /** 过滤表达式列表，例如 `["status=active", "pri>=2"]`，多条之间按 AND 组合。 */
+    /** 过滤表达式组，如 `["status=active,pri>=2", "assignedTo.id=5"]`；组内 AND、组间 OR，`=` 与 `:` 均表示相等。 */
     filter?: string[];
-    /** 模糊搜索关键词组，组内空格分隔为 OR，多组之间按 AND 组合。 */
+    /** 模糊搜索关键词组，如 `["登录,超时", "注册,失败"]`；组内 AND、组间 OR。 */
     search?: string[];
     /** 限定搜索字段，缺省时搜索全部字段。 */
     searchFields?: string[];
-    /** 排序表达式，多个字段以英文逗号分隔，例如 `pri:desc,id:asc`。 */
+    /** 排序表达式，多个字段以英文逗号分隔；推荐 `pri:desc,id:asc`，兼容 `pri_desc,id_asc`。 */
     sort?: string;
     /** 限制返回列表数量，在排序后、摘取前截断；不改变服务端页大小。 */
     limit?: string;

package/dist/types/options.d.ts

@@ -1,5 +1,5 @@
 import type { ZentaoClient } from '../client/index.js';
-import type { ProcessListOptions } from './data.js';
+import type { ProcessListOptions, ProcessSingleOptions } from './data.js';
 /** SDK 进程级全局默认选项，供高阶 {@link request} 调用复用。 */
 export interface GlobalOptions {
     /** 默认客户端；通常由 `ZentaoClient.init()` 设置。 */
@@ -33,6 +33,8 @@ export interface RequestOptions extends ProcessListOptions {
     timeout?: number;
     /** 本次调用 TLS 跳过证书验证选项；仅 Node.js 运行时支持。 */
     insecure?: boolean;
+    /** 单条对象转换函数，在字段摘取前执行；列表转换请使用 `convert`。 */
+    convertSingle?: ProcessSingleOptions['convert'];
     /**
      * 当禅道服务端返回 `{ status: "fail" }` 时是否抛出 `E_API_FAILED`。
      * 不传时回落到全局 `throwOnFail`，默认 false（保留原始失败响应）。

package/dist/utils/data.d.ts

@@ -8,13 +8,14 @@ export declare function filterData(data: DataRecord[], filterGroups: DataRecordF
 /**
  * 对列表做大小写不敏感的模糊匹配。
  *
- * 每个 `keywordGroups` 元素是一个关键词串，组内以空白分隔为 OR；多组之间按 AND 组合。
+ * 每个 `keywordGroups` 元素是一个关键词组，组内以逗号分隔为 AND；多个组之间按 OR 组合。
+ * 引号内的逗号视为关键词内容，不作为分隔符。
  */
 export declare function searchData(data: DataRecord[], keywordGroups: string[], searchFields?: string[]): DataRecord[];
 /**
  * 对列表排序，返回新数组（不修改入参）。
  *
- * `sortFields` 的每个元素可以是 `字段:asc|desc` 表达式或自定义比较函数，按先后顺序生效；
+ * `sortFields` 的每个元素可以是 `字段:asc|desc`（兼容 `字段_asc|desc`）或自定义比较函数，按先后顺序生效；
  * 数值字段按数字比较，否则按字符串 `localeCompare`。
  */
 export declare function sortData(data: DataRecord[], sortFields: (SortExpr | SortFn)[]): DataRecord[];

package/dist/version.js

@@ -1,5 +1,5 @@
-const fallbackBuild = "2026-08-11T13:56:37.064Z";
-const fallbackVersion = "0.5.1";
+const fallbackBuild = "2026-08-12T03:04:33.420Z";
+const fallbackVersion = "0.5.3";
 /**
  * 构建标识，由构建脚本通过 `__ZENTAO_API_BUILD__` 注入。
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zentao-api",
-  "version": "0.5.1",
+  "version": "0.5.3",
   "type": "module",
   "description": "Browser and Node.js SDK for ZenTao API",
   "license": "MIT",