zentao-api 0.2.1 → 0.3.1

package/dist/modules/registry.js

@@ -7,7 +7,7 @@ export const MODULES = BUILTIN_MODULES;
 // - 深克隆：避免用户后续修改自己的输入对象时污染注册表；
 // - 深冻结：让 getModule / getModuleAction 可以零拷贝返回引用，
 //   外部尝试改写会在严格模式下抛 TypeError，开销也降到 O(1) 查询。
-let modules = freezeModules(deepClone(BUILTIN_MODULES));
+let modules = freezeModules(cloneBuiltinModules());
 let moduleMap = buildModuleMap(modules);
 function deepClone(value) {
     if (Array.isArray(value)) {
@@ -22,6 +22,9 @@ function deepClone(value) {
     }
     return value;
 }
+function cloneBuiltinModules() {
+    return deepClone(BUILTIN_MODULES);
+}
 function deepFreeze(value) {
     if (value === null || typeof value !== 'object')
         return value;
@@ -216,6 +219,6 @@ export function isModuleName(moduleName) {
 }
 /** @internal */
 export function resetModuleDefinitions() {
-    modules = freezeModules(deepClone(BUILTIN_MODULES));
+    modules = freezeModules(cloneBuiltinModules());
     rebuildMap();
 }

package/dist/request/index.d.ts

@@ -1,16 +1,116 @@
-import type { RequestOptions, ResponseData } from '../types/index.js';
+import type { DataRecord, RequestOptions, ResponseData } from '../types/index.js';
+import type { BUILTIN_MODULES } from '../modules/generated.js';
+type BuiltinModuleDefinition = (typeof BUILTIN_MODULES)[number];
+type BuiltinModuleName = BuiltinModuleDefinition['name'];
+type BuiltinAction<M extends BuiltinModuleName> = Extract<BuiltinModuleDefinition, {
+    name: M;
+}>['actions'][number];
+type BuiltinActionName<M extends BuiltinModuleName> = BuiltinAction<M>['name'] & string;
+type BuiltinListRequestName = BuiltinModuleName;
+type BuiltinNamedRequestName = {
+    [M in BuiltinModuleName]: `${M}/${BuiltinActionName<M>}`;
+}[BuiltinModuleName];
+type BuiltinIdRequestName = `${BuiltinModuleName}/${number}`;
+/** 内置模块支持的请求名：`module`、`module/action` 或 `module/123`。 */
+export type BuiltinRequestName = BuiltinListRequestName | BuiltinNamedRequestName | BuiltinIdRequestName;
+type ModuleNameOf<Name extends BuiltinRequestName> = Name extends `${infer M}/${string}` ? Extract<M, BuiltinModuleName> : Extract<Name, BuiltinModuleName>;
+type ActionNameOf<Name extends BuiltinRequestName> = Name extends `${string}/${infer A}` ? A extends `${number}` ? 'get' : A : 'list';
+type ActionOfRequest<Name extends BuiltinRequestName> = Extract<BuiltinAction<ModuleNameOf<Name>>, {
+    name: ActionNameOf<Name>;
+}>;
+type UnionToIntersection<T> = (T extends unknown ? (value: T) => void : never) extends (value: infer R) => void ? R : never;
+type NumericInput = number | `${number}`;
+type BooleanInput = boolean | 0 | 1 | 'true' | 'false' | '1' | '0' | 'yes' | 'no' | 'on' | 'off';
+type OptionValue<T> = T extends readonly (infer Option)[] ? Option extends {
+    value: infer Value;
+} ? Value : never : never;
+type ParamInput<T> = (T extends {
+    options: infer Options;
+} ? OptionValue<Options> : never) | (T extends {
+    type: 'number' | 'integer';
+} ? NumericInput : T extends {
+    type: 'boolean';
+} ? BooleanInput : string);
+type QueryParams<A> = A extends {
+    params: readonly (infer Param)[];
+} ? UnionToIntersection<Param extends {
+    name: infer Name extends string;
+} ? {
+    [K in Name]?: ParamInput<Param>;
+} : unknown> : {};
+type SchemaProperties<S> = S extends {
+    properties: infer Properties;
+} ? Properties : {};
+type SchemaRequiredKeys<S> = S extends {
+    required: readonly (infer Key)[];
+} ? Extract<Key, keyof SchemaProperties<S> & string> : never;
+type SchemaValue<S> = S extends {
+    type: 'integer' | 'number';
+} ? NumericInput : S extends {
+    type: 'boolean';
+} ? BooleanInput : S extends {
+    type: 'array';
+    items?: infer Items;
+} ? Array<SchemaValue<Items>> | readonly SchemaValue<Items>[] | string | Record<string, unknown> : S extends {
+    type: 'object';
+} ? Record<string, unknown> : string;
+type BodyParams<A> = A extends {
+    requestBody: {
+        schema: infer Schema;
+    };
+} ? {
+    [K in SchemaRequiredKeys<Schema>]: SchemaValue<SchemaProperties<Schema>[K]>;
+} & {
+    [K in Exclude<keyof SchemaProperties<Schema> & string, SchemaRequiredKeys<Schema>>]?: SchemaValue<SchemaProperties<Schema>[K]>;
+} & {
+    data?: string | Partial<{
+        [K in keyof SchemaProperties<Schema> & string]: SchemaValue<SchemaProperties<Schema>[K]>;
+    }>;
+} : {
+    data?: string | Record<string, unknown>;
+};
+type ScopedParams<PathParams> = 'scope' extends keyof PathParams ? {
+    product?: string | number;
+    productID?: string | number;
+    project?: string | number;
+    projectID?: string | number;
+    execution?: string | number;
+    executionID?: string | number;
+} : {};
+type PathParams<A> = A extends {
+    pathParams: infer Params;
+} ? {
+    [K in Exclude<keyof Params & string, 'scope' | 'scopeID'>]?: string | number;
+} & ScopedParams<Params> & {
+    id?: string | number;
+} : {
+    id?: string | number;
+};
+/** 根据内置请求名推导出的参数类型。 */
+export type RequestParamsFor<Name extends BuiltinRequestName> = PathParams<ActionOfRequest<Name>> & QueryParams<ActionOfRequest<Name>> & BodyParams<ActionOfRequest<Name>> & {
+    page?: string | number;
+    recPerPage?: string | number;
+} & Record<string, unknown>;
+/** 根据内置请求名推导出的 `ResponseData.data` 类型。 */
+export type RequestResultFor<Name extends BuiltinRequestName> = ActionOfRequest<Name> extends {
+    resultType: 'list';
+} ? DataRecord[] : ActionOfRequest<Name> extends {
+    resultType: 'object';
+} ? DataRecord : unknown;
 /**
- * 按模块动作名请求禅道 API。
+ * 按模块名或模块动作名请求禅道 API。
  *
  * 选项优先级为：本次调用 options > 全局 options > 客户端默认值。
  * 当响应 `status` 为 `"fail"` 时，默认按原样返回；若 `options.throwOnFail`
  * 或全局 `throwOnFail` 为真，则改为抛出 `E_API_FAILED`。
  *
  * @typeParam T 期望的 `data` 字段类型；不传时为 `unknown`，调用方需要自行收窄。
- * @param name - 模块动作名，例如 `product/list`。
+ * @param name - 请求名，例如 `product`、`product/list` 或 `product/1`。
  * @param params - 请求参数。
  * @param options - 请求选项。
  * @returns 归一化后的禅道 API 响应。
  * @throws {ZentaoError} 传输层错误、参数缺失或 `throwOnFail` 启用时的业务失败。
  */
-export declare function request<T = unknown>(name: `${string}/${string}`, params?: Record<string, unknown>, options?: RequestOptions): Promise<ResponseData<T>>;
+export declare function request<Name extends BuiltinRequestName>(name: Name, params?: RequestParamsFor<Name>, options?: RequestOptions): Promise<ResponseData<RequestResultFor<Name>>>;
+export declare function request<T = unknown>(name: string, params?: Record<string, unknown>, options?: RequestOptions): Promise<ResponseData<T>>;
+export {};

package/dist/request/index.js

@@ -2,17 +2,22 @@ import { ZentaoError } from '../misc/errors.js';
 import { getGlobalOptions } from '../misc/global-options.js';
 import { getModule } from '../modules/registry.js';
 import { extractPager, extractResult, resolveModuleCommand } from '../modules/resolve.js';
-/** 将 `moduleName/methodName` 形式的请求名拆成模块名和动作名。 */
+import { isRecord, processData } from '../utils/index.js';
+/** 将 `moduleName`、`moduleName/methodName` 或 `moduleName/<objectID>` 请求名拆成模块名、动作名和对象 ID。 */
 function splitRequestName(name) {
-    const [moduleName, actionName] = name.split('/');
-    // 如果没有指定 actionName
+    const parts = name.split('/');
+    if (parts.length > 2 || !parts[0]) {
+        throw new ZentaoError('E_INVALID_REQUEST_NAME');
+    }
+    const [moduleName, actionName] = parts;
+    // 如果没有指定 actionName，按列表动作处理。
     if (!actionName?.length) {
         return {
             moduleName,
             actionName: 'list',
         };
     }
-    // 如果 actionName 为数值
+    // 如果 actionName 为数值，按详情快捷写法处理。
     if (Number.isInteger(Number(actionName))) {
         return {
             moduleName,
@@ -25,22 +30,78 @@ function splitRequestName(name) {
         actionName,
     };
 }
+function stringifyMessage(value) {
+    if (typeof value === 'string')
+        return value;
+    if (value === undefined)
+        return undefined;
+    try {
+        return JSON.stringify(value);
+    }
+    catch {
+        return String(value);
+    }
+}
+function extractApiCode(record) {
+    for (const key of ['code', 'errorCode', 'errno']) {
+        const value = record[key];
+        if (typeof value === 'string' || typeof value === 'number')
+            return value;
+    }
+    return undefined;
+}
+/** 判断本次调用是否携带了需要本地处理列表的选项。 */
+function hasListProcessing(options) {
+    return Boolean((options.filter && options.filter.length > 0) ||
+        (options.search && options.search.length > 0) ||
+        options.sort ||
+        options.limit ||
+        (options.pick && options.pick.length > 0));
+}
+/**
+ * 对归一化后的业务数据应用本地处理（过滤 → 搜索 → 排序 → 限制数量 → 摘取）。
+ *
+ * - 对象列表：交由 {@link processData} 完整处理。
+ * - 基本类型数组：仅 `limit` 生效（按数量截断），避免破坏原始元素。
+ * - 单条对象：只有 `pick` 生效。
+ * - 其他形态原样返回。
+ */
+function applyProcessing(data, options) {
+    if (Array.isArray(data)) {
+        if (!hasListProcessing(options))
+            return data;
+        if (data.every(isRecord)) {
+            return processData(data, {
+                filter: options.filter,
+                search: options.search,
+                searchFields: options.searchFields,
+                sort: options.sort,
+                limit: options.limit,
+                pick: options.pick,
+            });
+        }
+        // 非对象数组（如 ID 列表）只能按数量截断，其余处理不适用。
+        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 });
+    }
+    return data;
+}
 /** 将禅道原始响应归一化为稳定的 ResponseData 结构。 */
-function normalizeResponse(command, raw, limit) {
+function normalizeResponse(command, raw, options) {
     if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
         return { status: 'success', data: raw };
     }
     const record = raw;
     const status = record.status === 'fail' ? 'fail' : 'success';
-    let data = extractResult(command.action, record);
-    const numericLimit = limit === undefined ? undefined : Number(limit);
-    if (Array.isArray(data) && numericLimit !== undefined && !Number.isNaN(numericLimit)) {
-        data = data.slice(0, numericLimit);
-    }
+    const data = applyProcessing(extractResult(command.action, record), options);
+    const rawMessage = record.message;
     const pager = extractPager(command.action, record);
-    return {
+    const response = {
         status,
-        message: typeof record.message === 'string' ? record.message : undefined,
+        message: stringifyMessage(rawMessage),
         data: data,
         pager: pager ? {
             total: Number(pager.recTotal),
@@ -48,21 +109,16 @@ function normalizeResponse(command, raw, limit) {
             recPerPage: Number(pager.recPerPage),
         } : undefined,
     };
+    if (rawMessage !== undefined && typeof rawMessage !== 'string') {
+        response.rawMessage = rawMessage;
+    }
+    const apiCode = extractApiCode(record);
+    if (apiCode !== undefined)
+        response.apiCode = apiCode;
+    if (status === 'fail')
+        response.raw = record;
+    return response;
 }
-/**
- * 按模块动作名请求禅道 API。
- *
- * 选项优先级为：本次调用 options > 全局 options > 客户端默认值。
- * 当响应 `status` 为 `"fail"` 时，默认按原样返回；若 `options.throwOnFail`
- * 或全局 `throwOnFail` 为真，则改为抛出 `E_API_FAILED`。
- *
- * @typeParam T 期望的 `data` 字段类型；不传时为 `unknown`，调用方需要自行收窄。
- * @param name - 模块动作名，例如 `product/list`。
- * @param params - 请求参数。
- * @param options - 请求选项。
- * @returns 归一化后的禅道 API 响应。
- * @throws {ZentaoError} 传输层错误、参数缺失或 `throwOnFail` 启用时的业务失败。
- */
 export async function request(name, params = {}, options = {}) {
     const globals = getGlobalOptions();
     const client = options.client ?? globals.client;
@@ -74,8 +130,8 @@ export async function request(name, params = {}, options = {}) {
     // recPerPage 是最常用的列表参数，允许在全局或本次调用中统一覆盖。
     const recPerPage = params.recPerPage ?? options.recPerPage ?? globals.recPerPage;
     const mergedParams = {
-        ...(id !== undefined ? { id } : {}),
         ...params,
+        ...(id !== undefined ? { id } : {}),
         ...(recPerPage !== undefined ? { recPerPage } : {}),
     };
     const command = resolveModuleCommand(module, actionName, mergedParams);
@@ -86,7 +142,9 @@ export async function request(name, params = {}, options = {}) {
         timeout: options.timeout ?? globals.timeout,
         insecure: options.insecure ?? globals.insecure,
     });
-    const response = normalizeResponse(command, raw, options.limit ?? globals.limit);
+    // limit 现归入本地处理选项；本次调用优先，缺省回落到全局默认。
+    const processOptions = { ...options, limit: options.limit ?? globals.limit };
+    const response = normalizeResponse(command, raw, processOptions);
     if (response.status === 'fail' && (options.throwOnFail ?? globals.throwOnFail)) {
         throw new ZentaoError('E_API_FAILED', { message: response.message ?? '' }, response);
     }

package/dist/types/index.d.ts

@@ -29,27 +29,37 @@ export interface GlobalOptions {
 }
 /** SDK 支持的 HTTP 方法。 */
 export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE';
+/** 请求体序列化方式。 */
+export type ClientRequestBodyType = 'json' | 'form' | 'raw';
+/** 响应体解析方式。 */
+export type ClientResponseType = 'auto' | 'json' | 'text' | 'arrayBuffer' | 'blob' | 'response';
 /** `ZentaoClient.request()` 的单次请求选项。 */
 export interface ClientRequestOptions {
     /** HTTP 方法，默认 `GET`。 */
     method?: HttpMethod;
-    /** JSON 请求体；`GET` 请求会忽略该字段。 */
+    /** 请求体；`GET` 请求会忽略该字段。普通对象默认按 JSON 发送，`FormData` / `Blob` / `ArrayBuffer` 等会原样发送。 */
     body?: unknown;
+    /** 请求体序列化方式。默认 `json`；传入 `FormData` 等原生 body 时会自动按 `raw` 处理。 */
+    bodyType?: ClientRequestBodyType;
+    /** 响应体解析方式。默认 `auto`，会优先尝试 JSON，失败后回落为文本。 */
+    responseType?: ClientResponseType;
+    /** 额外请求头；会与 SDK 自动注入的 `Token` / `Content-Type` 合并。 */
+    headers?: HeadersInit;
     /** URL 查询参数；`undefined` 值会被跳过。 */
     query?: Record<string, string | number | boolean | undefined>;
+    /** 外部取消信号；会与 SDK 自身的超时控制合并。 */
+    signal?: AbortSignal;
     /** 单次请求超时时间，优先级高于全局和客户端默认值。 */
     timeout?: number;
     /** 单次请求 TLS 跳过证书验证选项；仅 Node.js 运行时支持。 */
     insecure?: boolean;
 }
-/** 高阶 `request("moduleName/methodName")` 的单次调用选项。 */
-export interface RequestOptions {
+/** 高阶 `request("moduleName")` / `request("moduleName/methodName")` / `request("moduleName/<objectID>")` 的单次调用选项。 */
+export interface RequestOptions extends ProcessListOptions {
     /** 本次调用使用的客户端；优先级高于全局客户端。 */
     client?: ZentaoClient;
     /** 本次调用使用的每页记录数，优先级高于全局 `recPerPage`。 */
     recPerPage?: string;
-    /** 本次调用限制返回列表数量，优先级高于全局 `limit`。 */
-    limit?: string;
     /** 本次调用超时时间。 */
     timeout?: number;
     /** 本次调用 TLS 跳过证书验证选项；仅 Node.js 运行时支持。 */
@@ -66,6 +76,12 @@ export interface ResponseData<T = unknown> {
     status: 'success' | 'fail';
     /** 禅道服务端返回的消息。 */
     message?: string;
+    /** 原始消息字段；当服务端返回对象/数组等非字符串消息时保留在这里。 */
+    rawMessage?: unknown;
+    /** 服务端返回的业务错误码或状态码字段。 */
+    apiCode?: string | number;
+    /** 失败响应的原始对象，便于上层展示服务端返回的完整上下文。 */
+    raw?: Record<string, unknown>;
     /** 根据模块动作 `resultGetter` 提取后的业务数据。 */
     data?: T;
     /** 统一分页信息。 */
@@ -185,8 +201,8 @@ export type ModuleActionMethod = HttpMethod | Lowercase<HttpMethod>;
 export type ModuleActionName = ModuleActionType | (string & {});
 /** 模块动作参数可选项。 */
 export type ModuleActionParamOption = {
-    value: unknown;
-    label: string;
+    readonly value: unknown;
+    readonly label: string;
 };
 /** 模块动作的查询参数定义。 */
 export interface ModuleActionParam {
@@ -201,7 +217,7 @@ export interface ModuleActionParam {
     /** 参数值类型，用于基础类型转换。 */
     type?: 'string' | 'number' | 'boolean';
     /** 参数可选值。 */
-    options?: ModuleActionParamOption[];
+    options?: readonly ModuleActionParamOption[];
 }
 /** 模块动作结果形态。 */
 export type ModuleActionResultType = 'text' | 'object' | 'list';
@@ -214,7 +230,7 @@ export interface ModuleActionRequestBody {
     /** 请求体是否必填。 */
     required?: boolean;
     /** OpenAPI 风格 schema，用于从 params 组装 body。 */
-    schema: Record<string, unknown>;
+    schema: Readonly<Record<string, unknown>>;
     /** 请求体示例。 */
     example?: unknown;
 }
@@ -223,7 +239,7 @@ export interface ModuleActionResponse {
     /** 响应说明。 */
     description?: string;
     /** 响应 schema。 */
-    schema: Record<string, unknown>;
+    schema: Readonly<Record<string, unknown>>;
     /** 响应示例。 */
     example?: unknown;
 }
@@ -255,9 +271,9 @@ export interface ModuleAction {
     /** API 路径模板，可包含 `{productID}` 等路径参数。 */
     path: string;
     /** 路径参数定义；字符串为说明，对象可携带默认值和可选项。 */
-    pathParams?: Record<string, string | Omit<ModuleActionParam, 'name'>>;
+    pathParams?: Readonly<Record<string, string | Omit<ModuleActionParam, 'name'>>>;
     /** 查询参数定义。 */
-    params?: ModuleActionParam[];
+    params?: readonly ModuleActionParam[];
     /** 请求体定义。 */
     requestBody?: ModuleActionRequestBody;
     /** 结果形态。 */
@@ -280,7 +296,49 @@ export interface ModuleDefinition {
     /** 模块说明。 */
     description?: string;
     /** 模块支持的动作集合。 */
-    actions: ModuleAction[];
+    actions: readonly ModuleAction[];
+}
+/** 本地数据处理的基础记录类型，对应一条对象数据。 */
+export type DataRecord = Record<string, unknown>;
+/** 单条过滤条件，字段名支持 `.` 访问子字段。 */
+export interface DataRecordFilter {
+    /** 字段路径，例如 `status` 或 `assignedTo.id`。 */
+    key: string;
+    /** 比较运算符。 */
+    operator: '=' | '!=' | '>' | '<' | '>=' | '<=' | '~' | '!~';
+    /** 比较值；数组用于 `=`/`!=`/`~`/`!~` 的“任一/全不”匹配。 */
+    value: string | number | boolean | string[];
+}
+/** 一组过滤条件，组内按 `operator` 组合；多组之间按 AND 组合。 */
+export interface DataRecordFilterGroup {
+    /** 组内条件的组合方式。 */
+    operator: 'AND' | 'OR';
+    /** 组内条件列表。 */
+    conditions: DataRecordFilter[];
+}
+/** 排序表达式，格式为 `字段:asc|desc`。 */
+export type SortExpr = `${string}:${'asc' | 'desc'}`;
+/** 自定义排序比较函数。 */
+export type SortFn = (a: DataRecord, b: DataRecord) => number;
+/** {@link processData} 处理列表时的选项；执行顺序为 过滤 → 搜索 → 排序 → 限制数量 → 摘取。 */
+export interface ProcessListOptions {
+    /** 过滤表达式列表，例如 `["status=active", "pri>=2"]`，多条之间按 AND 组合。 */
+    filter?: string[];
+    /** 模糊搜索关键词组，组内空格分隔为 OR，多组之间按 AND 组合。 */
+    search?: string[];
+    /** 限定搜索字段，缺省时搜索全部字段。 */
+    searchFields?: string[];
+    /** 排序表达式，多个字段以英文逗号分隔，例如 `pri:desc,id:asc`。 */
+    sort?: string;
+    /** 限制返回列表数量，在排序后、摘取前截断；不改变服务端页大小。 */
+    limit?: string;
+    /** 摘取字段路径列表。 */
+    pick?: string[];
+}
+/** {@link processData} 处理单条对象时的选项。 */
+export interface ProcessSingleOptions {
+    /** 摘取字段路径列表。 */
+    pick?: string[];
 }
 /** 将模块动作和参数解析后的可执行请求描述。 */
 export interface ResolvedModuleCommand {

package/dist/utils/array.d.ts

@@ -0,0 +1 @@
+export declare function asArray<T>(value: T | T[]): T[];

package/dist/utils/array.js

@@ -0,0 +1,3 @@
+export function asArray(value) {
+    return Array.isArray(value) ? value : [value];
+}

package/dist/utils/data.d.ts

@@ -0,0 +1,24 @@
+import type { DataRecord, DataRecordFilterGroup, ProcessListOptions, ProcessSingleOptions, SortExpr, SortFn } from '../types/index.js';
+/** 从单条对象中摘取指定字段，支持通过 `.` 访问子字段，保留嵌套结构。 */
+export declare function pickFieldsSingle(data: DataRecord, fields: string[]): DataRecord;
+/** 对列表中的每条对象摘取指定字段。 */
+export declare function pickFields(data: DataRecord[], fields: string[]): DataRecord[];
+/** 按条件组过滤列表，多组之间按 AND 组合。 */
+export declare function filterData(data: DataRecord[], filterGroups: DataRecordFilterGroup[]): DataRecord[];
+/**
+ * 对列表做大小写不敏感的模糊匹配。
+ *
+ * 每个 `keywordGroups` 元素是一个关键词串，组内以空白分隔为 OR；多组之间按 AND 组合。
+ */
+export declare function searchData(data: DataRecord[], keywordGroups: string[], searchFields?: string[]): DataRecord[];
+/**
+ * 对列表排序，返回新数组（不修改入参）。
+ *
+ * `sortFields` 的每个元素可以是 `字段:asc|desc` 表达式或自定义比较函数，按先后顺序生效；
+ * 数值字段按数字比较，否则按字符串 `localeCompare`。
+ */
+export declare function sortData(data: DataRecord[], sortFields: (SortExpr | SortFn)[]): DataRecord[];
+/** 处理单条对象：仅支持字段摘取。 */
+export declare function processData(data: DataRecord, options: ProcessSingleOptions): DataRecord;
+/** 处理列表：按 过滤 → 搜索 → 排序 → 限制数量 → 摘取 的顺序执行。 */
+export declare function processData(data: DataRecord[], options: ProcessListOptions): DataRecord[];

package/dist/utils/index.d.ts

@@ -1,6 +1,4 @@
-/** 判断值是否为普通对象（非数组、非 null）。 */
-export declare function isRecord(value: unknown): value is Record<string, unknown>;
-/** 将用户传入的站点根地址规范化，兼容误传入 `/api.php/v2` 的场景。 */
-export declare function normalizeSiteUrl(baseUrl: string): string;
-export declare function getNestedValue(obj: unknown, path: string): unknown;
-export declare function asArray<T>(value: T | T[]): T[];
+export { isRecord, getNestedValue } from './object.js';
+export { asArray } from './array.js';
+export { normalizeSiteUrl } from './url.js';
+export { pickFields, pickFieldsSingle, filterData, searchData, sortData, processData, } from './data.js';

package/dist/utils/index.js

@@ -1,37 +1,4 @@
-import { ZentaoError } from '../misc/errors.js';
-/** 判断值是否为普通对象（非数组、非 null）。 */
-export function isRecord(value) {
-    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
-}
-/** 将用户传入的站点根地址规范化，兼容误传入 `/api.php/v2` 的场景。 */
-export function normalizeSiteUrl(baseUrl) {
-    const trimmed = baseUrl.trim().replace(/\/+$/, '');
-    if (!trimmed)
-        throw new ZentaoError('E_INVALID_BASE_URL');
-    const siteUrl = trimmed.replace(/\/api\.php\/v2$/i, '');
-    let parsed;
-    try {
-        parsed = new URL(siteUrl);
-    }
-    catch {
-        throw new ZentaoError('E_INVALID_BASE_URL');
-    }
-    if (!['http:', 'https:'].includes(parsed.protocol) || parsed.search || parsed.hash) {
-        throw new ZentaoError('E_INVALID_BASE_URL');
-    }
-    return parsed.toString().replace(/\/+$/, '');
-}
-export function getNestedValue(obj, path) {
-    const keys = path.split('.');
-    let current = obj;
-    for (const key of keys) {
-        if (current === null || current === undefined || typeof current !== 'object') {
-            return undefined;
-        }
-        current = current[key];
-    }
-    return current;
-}
-export function asArray(value) {
-    return Array.isArray(value) ? value : [value];
-}
+export { isRecord, getNestedValue } from './object.js';
+export { asArray } from './array.js';
+export { normalizeSiteUrl } from './url.js';
+export { pickFields, pickFieldsSingle, filterData, searchData, sortData, processData, } from './data.js';

package/dist/utils/object.d.ts

@@ -0,0 +1,3 @@
+/** 判断值是否为普通对象（非数组、非 null）。 */
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+export declare function getNestedValue(obj: unknown, path: string): unknown;

package/dist/utils/object.js

@@ -0,0 +1,15 @@
+/** 判断值是否为普通对象（非数组、非 null）。 */
+export function isRecord(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+export function getNestedValue(obj, path) {
+    const keys = path.split('.');
+    let current = obj;
+    for (const key of keys) {
+        if (current === null || current === undefined || typeof current !== 'object') {
+            return undefined;
+        }
+        current = current[key];
+    }
+    return current;
+}

package/dist/utils/url.d.ts

@@ -0,0 +1,2 @@
+/** 将用户传入的站点根地址规范化，兼容误传入 `/api.php/v2` 的场景。 */
+export declare function normalizeSiteUrl(baseUrl: string): string;

package/dist/utils/url.js

@@ -0,0 +1,19 @@
+import { ZentaoError } from '../misc/errors.js';
+/** 将用户传入的站点根地址规范化，兼容误传入 `/api.php/v2` 的场景。 */
+export function normalizeSiteUrl(baseUrl) {
+    const trimmed = baseUrl.trim().replace(/\/+$/, '');
+    if (!trimmed)
+        throw new ZentaoError('E_INVALID_BASE_URL');
+    const siteUrl = trimmed.replace(/\/api\.php\/v2$/i, '');
+    let parsed;
+    try {
+        parsed = new URL(siteUrl);
+    }
+    catch {
+        throw new ZentaoError('E_INVALID_BASE_URL');
+    }
+    if (!['http:', 'https:'].includes(parsed.protocol) || parsed.search || parsed.hash) {
+        throw new ZentaoError('E_INVALID_BASE_URL');
+    }
+    return parsed.toString().replace(/\/+$/, '');
+}

package/dist/version.js

@@ -1,5 +1,5 @@
-const fallbackBuild = "2026-06-23T08:50:58.737Z";
-const fallbackVersion = "0.2.1";
+const fallbackBuild = "2026-06-27T12:02:58.054Z";
+const fallbackVersion = "0.3.1";
 /**
  * 构建标识，由构建脚本通过 `__ZENTAO_API_BUILD__` 注入。
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zentao-api",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "type": "module",
   "description": "Browser and Node.js SDK for ZenTao API",
   "license": "MIT",
@@ -49,6 +49,7 @@
     "registry:check": "bun run scripts/update-registry.ts --check",
     "build": "rm -rf dist && tsc -p tsconfig.json && bun run scripts/build-browser.ts",
     "smoke:node": "node scripts/smoke-node.mjs",
+    "smoke:browser": "bun run scripts/smoke-browser-bundler.ts",
     "smoke:package": "bun run scripts/smoke-package.ts",
     "docs:reference": "typedoc",
     "docs:zentao-api": "bun run scripts/generate-zentao-api-docs.ts",
@@ -56,7 +57,7 @@
     "docs:dev": "bun run docs:generate && vitepress dev docs",
     "docs:build": "bun run docs:generate && vitepress build docs",
     "docs:preview": "bun run docs:build && vitepress preview docs",
-    "check": "bun run test:coverage && bun run typecheck && bun run typecheck:tests && bun run registry:check && bun run build && bun run smoke:node && bun run smoke:package",
+    "check": "bun run test:coverage && bun run typecheck && bun run typecheck:tests && bun run registry:check && bun run build && bun run smoke:node && bun run smoke:browser && bun run smoke:package",
     "prepublishOnly": "bun run check"
   },
   "devDependencies": {