zentao-api 0.3.1 → 0.3.2

package/dist/modules/registry.d.ts

@@ -1,5 +1,5 @@
-import type { ModuleAction, ModuleDefinition } from '../types/index.js';
 import { BUILTIN_MODULES } from './generated.js';
+import { applyBuiltinOverrides } from './override.js';
 export { BUILTIN_MODULES };
 export declare const MODULES: readonly [{
     readonly name: "user";
@@ -4330,84 +4330,6 @@ export declare const MODULES: readonly [{
         readonly render: "action";
     }];
 }];
-/** {@link defineModules} 的选项。 */
-export interface DefineModulesOptions {
-    /**
-     * 同名模块的写入策略。
-     *
-     * - `false`（默认）：合并模块的元数据，并按动作名对动作做"同名替换、未知追加"。
-     * - `true`：整体替换已存在的模块定义，原有动作会被丢弃。
-     */
-    replace?: boolean;
-}
-/**
- * 注册或扩展模块定义。
- *
- * 行为细节：
- * - 模块名匹配大小写不敏感。
- * - 未知模块直接追加到注册表末尾。
- * - 已存在的模块默认按 `mergeModule` 合并：模块元数据浅合并、动作按名同名替换/未知追加；
- *   `options.replace` 为 `true` 时整体替换。
- * - 所有写入都会做深克隆 + 深冻结：调用方后续修改自己的对象不会污染注册表，注册表也不可被外部改写。
- *
- * @param input - 单个或一组模块定义。
- * @param options - 写入策略，参见 {@link DefineModulesOptions}。
- * @throws {ZentaoError} `E_INVALID_MODULE_DEFINITION` —— 缺少 `name` 或 `actions` 字段。
- */
-export declare function defineModules(input: ModuleDefinition | ModuleDefinition[], options?: DefineModulesOptions): void;
-/**
- * 为已存在的模块追加或覆盖动作。
- *
- * 不做深度合并：同名动作整体替换，未知动作追加。这避免在 schema、参数数组等字段上出现隐式合并规则。
- *
- * @param moduleName - 目标模块名（大小写不敏感）。
- * @param input - 单个或一组动作定义。
- * @throws {ZentaoError} `E_INVALID_MODULE`（模块未注册）或 `E_INVALID_ACTION_DEFINITION`
- *   （动作缺少 `name` / `path` / `method` 等必填字段）。
- */
-export declare function defineModuleActions(moduleName: string, input: ModuleAction | ModuleAction[]): void;
-/**
- * 获取模块定义。
- *
- * 模块名匹配大小写不敏感。返回值是注册表内部的已深冻结引用（O(1) 查询、零拷贝），
- * 任何写入尝试在严格模式下会抛 `TypeError`；如需修改请使用 {@link defineModules}。
- *
- * @param moduleName - 模块名。
- * @returns 已注册的模块定义。
- * @throws {ZentaoError} `E_INVALID_MODULE` —— 模块未注册。
- */
-export declare function getModule(moduleName: string): ModuleDefinition;
-/**
- * 获取指定模块下的某个动作。
- *
- * 解析顺序：
- * 1. `actionName === 'ls'` 时映射为 `list`（仅作为别名，不会修改注册表）。
- * 2. 在该模块的动作中按名称大小写不敏感匹配。
- * 3. 当请求的动作不是基础 CRUD（`list`/`get`/`create`/`update`/`delete`）时，
- *    额外允许命中 `type === 'action'` 的自定义动作（即使名字不在基础 CRUD 中）。
- *
- * 返回值同样是已深冻结的引用，请勿尝试修改。
- *
- * @param moduleName - 模块名（大小写不敏感）。
- * @param actionName - 动作名（大小写不敏感）；支持 `ls` 作为 `list` 的别名。
- * @returns 匹配到的动作定义。
- * @throws {ZentaoError} `E_INVALID_MODULE`（模块未注册）或 `E_INVALID_ACTION`（动作不存在）。
- */
-export declare function getModuleAction(moduleName: string, actionName: string): ModuleAction;
-/**
- * 返回当前运行时注册表中的所有模块名。
- *
- * 顺序与模块写入注册表的顺序一致；包括内置模块和通过 {@link defineModules} 追加的用户模块。
- *
- * @returns 模块名数组（保留原始大小写）。
- */
-export declare function getModuleNames(): string[];
-/**
- * 判断模块名是否已注册。
- *
- * @param moduleName - 模块名；匹配大小写不敏感。
- * @returns 已注册返回 `true`，否则 `false`。
- */
-export declare function isModuleName(moduleName: string): boolean;
-/** @internal */
-export declare function resetModuleDefinitions(): void;
+export { type DefineModulesOptions, defineModules, defineModuleActions, extendModuleAction, resetModuleDefinitions, } from './define.js';
+export { applyBuiltinOverrides };
+export { getModule, getModuleAction, getModuleNames, isModuleName, } from './query.js';

package/dist/modules/registry.js

@@ -1,224 +1,19 @@
-import { ZentaoError } from '../misc/errors.js';
-import { asArray } from '../utils/index.js';
+// 模块注册表的统一出入口（barrel）。
+// 实际实现按职责拆分：
+// - ./registry-store —— 共享运行时状态与 克隆/冻结/合并/校验 等底层原语（内部使用）。
+// - ./define         —— 定义/写入模块（defineModules / defineModuleActions / resetModuleDefinitions）。
+// - ./override       —— 内置覆盖/扩展（基于 define，随 SDK 发布并在加载/重置时自动应用）。
+// - ./query          —— 获取模块信息（getModule / getModuleAction / getModuleNames / isModuleName）。
 import { BUILTIN_MODULES } from './generated.js';
+import { applyBuiltinOverrides } from './override.js';
+import { setPostResetHook } from './registry-store.js';
 export { BUILTIN_MODULES };
 export const MODULES = BUILTIN_MODULES;
-// 运行时注册表存放「深克隆 + 深冻结」后的模块定义：
-// - 深克隆：避免用户后续修改自己的输入对象时污染注册表；
-// - 深冻结：让 getModule / getModuleAction 可以零拷贝返回引用，
-//   外部尝试改写会在严格模式下抛 TypeError，开销也降到 O(1) 查询。
-let modules = freezeModules(cloneBuiltinModules());
-let moduleMap = buildModuleMap(modules);
-function deepClone(value) {
-    if (Array.isArray(value)) {
-        return value.map((item) => deepClone(item));
-    }
-    if (value && typeof value === 'object' && !(value instanceof Function)) {
-        const result = {};
-        for (const [key, nestedValue] of Object.entries(value)) {
-            result[key] = deepClone(nestedValue);
-        }
-        return result;
-    }
-    return value;
-}
-function cloneBuiltinModules() {
-    return deepClone(BUILTIN_MODULES);
-}
-function deepFreeze(value) {
-    if (value === null || typeof value !== 'object')
-        return value;
-    if (Object.isFrozen(value))
-        return value;
-    for (const key of Object.keys(value)) {
-        deepFreeze(value[key]);
-    }
-    return Object.freeze(value);
-}
-function freezeAction(action) {
-    return deepFreeze(action);
-}
-function freezeModule(module) {
-    module.actions.forEach(freezeAction);
-    return deepFreeze(module);
-}
-function freezeModules(source) {
-    source.forEach(freezeModule);
-    return source;
-}
-function findActionIndex(source, actionName) {
-    const key = actionName.toLowerCase();
-    return source.findIndex((action) => String(action.name).toLowerCase() === key);
-}
-function mergeActions(base, extension) {
-    const next = base.slice();
-    for (const action of extension) {
-        const index = findActionIndex(next, String(action.name));
-        const frozen = freezeAction(deepClone(action));
-        if (index >= 0) {
-            next[index] = frozen;
-        }
-        else {
-            next.push(frozen);
-        }
-    }
-    return next;
-}
-function mergeModule(base, extension) {
-    return freezeModule({
-        ...base,
-        ...deepClone(extension),
-        actions: mergeActions(base.actions, extension.actions),
-    });
-}
-function buildModuleMap(source) {
-    return new Map(source.map((module) => [module.name.toLowerCase(), module]));
-}
-function rebuildMap() {
-    moduleMap = buildModuleMap(modules);
-}
-function validateModule(module) {
-    if (!module || typeof module.name !== 'string' || !Array.isArray(module.actions)) {
-        throw new ZentaoError('E_INVALID_MODULE_DEFINITION');
-    }
-}
-function validateAction(action) {
-    if (!action || typeof action.name !== 'string' || typeof action.path !== 'string' || typeof action.method !== 'string') {
-        throw new ZentaoError('E_INVALID_ACTION_DEFINITION');
-    }
-}
-/**
- * 注册或扩展模块定义。
- *
- * 行为细节：
- * - 模块名匹配大小写不敏感。
- * - 未知模块直接追加到注册表末尾。
- * - 已存在的模块默认按 `mergeModule` 合并：模块元数据浅合并、动作按名同名替换/未知追加；
- *   `options.replace` 为 `true` 时整体替换。
- * - 所有写入都会做深克隆 + 深冻结：调用方后续修改自己的对象不会污染注册表，注册表也不可被外部改写。
- *
- * @param input - 单个或一组模块定义。
- * @param options - 写入策略，参见 {@link DefineModulesOptions}。
- * @throws {ZentaoError} `E_INVALID_MODULE_DEFINITION` —— 缺少 `name` 或 `actions` 字段。
- */
-export function defineModules(input, options = {}) {
-    for (const module of asArray(input)) {
-        validateModule(module);
-        const key = module.name.toLowerCase();
-        const index = modules.findIndex((item) => item.name.toLowerCase() === key);
-        if (index >= 0) {
-            modules[index] = options.replace
-                ? freezeModule(deepClone(module))
-                : mergeModule(modules[index], module);
-        }
-        else {
-            modules.push(freezeModule(deepClone(module)));
-        }
-    }
-    rebuildMap();
-}
-/**
- * 为已存在的模块追加或覆盖动作。
- *
- * 不做深度合并：同名动作整体替换，未知动作追加。这避免在 schema、参数数组等字段上出现隐式合并规则。
- *
- * @param moduleName - 目标模块名（大小写不敏感）。
- * @param input - 单个或一组动作定义。
- * @throws {ZentaoError} `E_INVALID_MODULE`（模块未注册）或 `E_INVALID_ACTION_DEFINITION`
- *   （动作缺少 `name` / `path` / `method` 等必填字段）。
- */
-export function defineModuleActions(moduleName, input) {
-    const key = moduleName.toLowerCase();
-    const module = moduleMap.get(key);
-    if (!module) {
-        throw new ZentaoError('E_INVALID_MODULE', { module: moduleName });
-    }
-    const actions = module.actions.slice();
-    for (const action of asArray(input)) {
-        validateAction(action);
-        const index = findActionIndex(actions, String(action.name));
-        const frozen = freezeAction(deepClone(action));
-        // 同名动作替换，未知动作追加；不做深度合并，避免 schema/数组字段出现隐式规则。
-        if (index >= 0) {
-            actions[index] = frozen;
-        }
-        else {
-            actions.push(frozen);
-        }
-    }
-    const nextModule = freezeModule({ ...module, actions });
-    const index = modules.findIndex((item) => item.name.toLowerCase() === key);
-    modules[index] = nextModule;
-    rebuildMap();
-}
-/**
- * 获取模块定义。
- *
- * 模块名匹配大小写不敏感。返回值是注册表内部的已深冻结引用（O(1) 查询、零拷贝），
- * 任何写入尝试在严格模式下会抛 `TypeError`；如需修改请使用 {@link defineModules}。
- *
- * @param moduleName - 模块名。
- * @returns 已注册的模块定义。
- * @throws {ZentaoError} `E_INVALID_MODULE` —— 模块未注册。
- */
-export function getModule(moduleName) {
-    const module = moduleMap.get(moduleName.toLowerCase());
-    if (!module) {
-        throw new ZentaoError('E_INVALID_MODULE', { module: moduleName });
-    }
-    return module;
-}
-/**
- * 获取指定模块下的某个动作。
- *
- * 解析顺序：
- * 1. `actionName === 'ls'` 时映射为 `list`（仅作为别名，不会修改注册表）。
- * 2. 在该模块的动作中按名称大小写不敏感匹配。
- * 3. 当请求的动作不是基础 CRUD（`list`/`get`/`create`/`update`/`delete`）时，
- *    额外允许命中 `type === 'action'` 的自定义动作（即使名字不在基础 CRUD 中）。
- *
- * 返回值同样是已深冻结的引用，请勿尝试修改。
- *
- * @param moduleName - 模块名（大小写不敏感）。
- * @param actionName - 动作名（大小写不敏感）；支持 `ls` 作为 `list` 的别名。
- * @returns 匹配到的动作定义。
- * @throws {ZentaoError} `E_INVALID_MODULE`（模块未注册）或 `E_INVALID_ACTION`（动作不存在）。
- */
-export function getModuleAction(moduleName, actionName) {
-    const module = getModule(moduleName);
-    const normalized = actionName === 'ls' ? 'list' : actionName;
-    const direct = module.actions.find((action) => String(action.name).toLowerCase() === normalized.toLowerCase());
-    if (direct)
-        return direct;
-    const crud = new Set(['list', 'get', 'create', 'update', 'delete']);
-    if (!crud.has(normalized)) {
-        const custom = module.actions.find((action) => action.type === 'action' && String(action.name).toLowerCase() === normalized.toLowerCase());
-        if (custom)
-            return custom;
-    }
-    throw new ZentaoError('E_INVALID_ACTION', { module: moduleName, action: actionName });
-}
-/**
- * 返回当前运行时注册表中的所有模块名。
- *
- * 顺序与模块写入注册表的顺序一致；包括内置模块和通过 {@link defineModules} 追加的用户模块。
- *
- * @returns 模块名数组（保留原始大小写）。
- */
-export function getModuleNames() {
-    return modules.map((module) => module.name);
-}
-/**
- * 判断模块名是否已注册。
- *
- * @param moduleName - 模块名；匹配大小写不敏感。
- * @returns 已注册返回 `true`，否则 `false`。
- */
-export function isModuleName(moduleName) {
-    return moduleMap.has(moduleName.toLowerCase());
-}
-/** @internal */
-export function resetModuleDefinitions() {
-    modules = freezeModules(cloneBuiltinModules());
-    rebuildMap();
-}
+export { defineModules, defineModuleActions, extendModuleAction, resetModuleDefinitions, } from './define.js';
+export { applyBuiltinOverrides };
+// 内置覆盖接线：避免 define ↔ override 之间的循环依赖。
+// - 加载时应用一次；
+// - 注册为 store 的「重置后钩子」，使 resetModuleDefinitions 还原内置基线后自动重新应用。
+setPostResetHook(applyBuiltinOverrides);
+applyBuiltinOverrides();
+export { getModule, getModuleAction, getModuleNames, isModuleName, } from './query.js';

package/dist/types/client.d.ts

@@ -0,0 +1,38 @@
+/** 创建 {@link ZentaoClient} 时使用的配置。 */
+export interface ZentaoClientOptions {
+    /** 禅道站点根地址，例如 `https://zentao.example.com`；SDK 会自动拼接 `/api.php/v2`。 */
+    baseUrl: string;
+    /** 禅道 API Token；未提供时可稍后通过 {@link ZentaoClient.login} 获取并写入实例。 */
+    token?: string;
+    /** 默认请求超时时间，单位毫秒。 */
+    timeout?: number;
+    /** 是否跳过 TLS 证书验证；仅 Node.js 运行时支持，浏览器中会抛错。 */
+    insecure?: boolean;
+}
+/** 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;
+    /** 请求体；`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;
+}

package/dist/types/client.js

@@ -0,0 +1 @@
+export {};

package/dist/types/data.d.ts

@@ -0,0 +1,42 @@
+/** 本地数据处理的基础记录类型，对应一条对象数据。 */
+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[];
+}

package/dist/types/data.js

@@ -0,0 +1 @@
+export {};