@h-ai/core 0.1.0-alpha.13 → 0.1.0-alpha.16

package/dist/{core-util-module-B-wH5_ZT.d.ts → core-types-aT8pmvMq.d.ts}

@@ -169,6 +169,82 @@ declare const CoreConfigSchema: z.ZodObject<{
 }, z.core.$strip>;
 type CoreConfig = z.infer<typeof CoreConfigSchema>;
 
+/**
+ * 校验消息 key 集合（locale 无关的标识符）。
+ *
+ * 调用方负责把每个 key 映射到自己模块的 i18n 字典（例如 kit 的
+ * `kit_validationStringMin`、serv 的 `serv_validationStringMin`）。
+ *
+ * @example
+ * ```ts
+ * const key: ZodValidationMessageKey = 'validationRequired'
+ * ```
+ */
+/**
+ * 创建按固定前缀派生消息 key 的 `ZodMessageGetter`。
+ *
+ * 适用于模块消息键遵循 `{prefix}_{ZodValidationMessageKey}` 命名约定的场景，
+ * 例如 `serv_validationRequired`、`kit_validationEmail`。
+ *
+ * @param prefix - 模块消息前缀，如 `serv`、`kit`
+ * @param getMessage - 实际消息获取函数，接收带前缀的消息 key
+ * @returns 可注入给 `core.zodValidation.*` 的 `ZodMessageGetter`
+ *
+ * @example
+ * ```ts
+ * const getMessage = createPrefixedZodMessageGetter<string>(
+ *   'serv',
+ *   (messageKey, params) => `${messageKey}:${params?.min ?? ''}`,
+ * )
+ *
+ * getMessage('validationStringMin', { min: 3 })
+ * // 'serv_validationStringMin:3'
+ * ```
+ */
+declare function createPrefixedZodMessageGetter<TMessageKey extends string>(prefix: string, getMessage: (messageKey: TMessageKey, params?: Record<string, string | number>) => string): ZodMessageGetter;
+/**
+ * 一步把 Zod SafeParseError / ZodError 转为扁平 `ValidationFormError[]`。
+ *
+ * @param error - Zod `SafeParseError`、`ZodError` 或兼容的错误对象
+ * @param getMessage - 调用方注入的消息获取器
+ * @returns 扁平化后的表单错误列表
+ *
+ * @example
+ * ```ts
+ * const errors = mapZodErrorToFormErrors(
+ *   {
+ *     issues: [
+ *       { path: ['email'], code: 'invalid_format', format: 'email', message: 'Invalid email address' },
+ *     ],
+ *   },
+ *   key => key === 'validationEmail' ? '请输入合法邮箱地址' : '输入不合法',
+ * )
+ * ```
+ */
+declare function mapZodErrorToFormErrors(error: unknown, getMessage: ZodMessageGetter): ValidationFormError[];
+/**
+ * Zod 校验 i18n 工具集合（通过 `core.zodValidation` 暴露）。
+ *
+ * 按最小知识原则，仅暴露调用方真正需要的两个入口：
+ * 1. `createPrefixedZodMessageGetter()`：把模块前缀与消息获取器适配起来
+ * 2. `mapZodErrorToFormErrors()`：一步完成 ZodError → 本地化扁平错误列表
+ *
+ * @example
+ * ```ts
+ * const getMessage = zodValidation.createPrefixedZodMessageGetter(
+ *   'kit',
+ *   (messageKey, params) => messageKey === 'kit_validationEmail'
+ *     ? '请输入合法邮箱地址'
+ *     : `至少输入 ${params?.min} 个字符`,
+ * )
+ * const errors = zodValidation.mapZodErrorToFormErrors(zodError, getMessage)
+ * ```
+ */
+declare const zodValidation: {
+    createPrefixedZodMessageGetter: typeof createPrefixedZodMessageGetter;
+    mapZodErrorToFormErrors: typeof mapZodErrorToFormErrors;
+};
+
 /**
  * @h-ai/core — 错误注册与处理
  *
@@ -670,6 +746,43 @@ declare const async: {
 /** async 子工具类型 */
 type AsyncFn = typeof async;
 
+/**
+ * @h-ai/core — 模块初始化工具
+ *
+ * 封装各模块共同的「未初始化」错误处理模式，消除跨模块冗余。
+ * @module core-util-module
+ */
+
+/**
+ * 未初始化工具集返回类型。
+ *
+ * 提供错误创建、HaiResult 包装和 Proxy 代理等能力，
+ * 用于模块未初始化时的安全回退。
+ *
+ * @template E - 模块错误类型（必须继承 HaiError）
+ */
+interface NotInitializedKit<E extends HaiError> {
+    /** 创建未初始化错误对象 */
+    error: () => E;
+    /** 创建包含未初始化错误的失败 HaiResult */
+    result: <T>() => HaiResult<T>;
+    /**
+     * 创建 Proxy 代理，拦截所有方法调用并返回未初始化错误。
+     *
+     * @param mode - 'async'（默认）所有方法返回 `Promise<HaiResult>`；'sync' 所有方法返回 `HaiResult`
+     */
+    proxy: <T>(mode?: 'async' | 'sync') => T;
+}
+/** module 子工具类型 */
+/** overloaded function type for createNotInitializedKit */
+interface CreateNotInitializedKitFn {
+    (codeOrDef: HaiErrorDef, messageFn: () => string): NotInitializedKit<HaiError>;
+    <E extends HaiError>(codeOrDef: E['code'], messageFn: () => string): NotInitializedKit<E>;
+}
+interface ModuleFn {
+    createNotInitializedKit: CreateNotInitializedKitFn;
+}
+
 /**
  * @h-ai/core — 对象操作工具
  * @module core-util-object
@@ -1222,13 +1335,16 @@ declare const typeUtils: {
 /** typeUtils 子工具类型 */
 type TypeUtilFn = typeof typeUtils;
 
-/**
- * @h-ai/core — 类型定义
- *
- * 核心模块的公共类型（前后端通用）
- * @module core-types
- */
-
+type ZodValidationMessageKey = 'validationFailed' | 'validationRequired' | 'validationInvalid' | 'validationInvalidType' | 'validationStringMin' | 'validationStringMax' | 'validationNumberMin' | 'validationNumberMax' | 'validationArrayMin' | 'validationArrayMax' | 'validationTooSmall' | 'validationTooBig' | 'validationEmail' | 'validationUrl' | 'validationUuid' | 'validationEnum';
+type ZodMessageGetter = (key: ZodValidationMessageKey, params?: Record<string, string | number>) => string;
+interface ValidationFormError {
+    field: string;
+    message: string;
+}
+interface ZodValidationFn {
+    readonly createPrefixedZodMessageGetter: <TMessageKey extends string>(prefix: string, getMessage: (messageKey: TMessageKey, params?: Record<string, string | number>) => string) => ZodMessageGetter;
+    readonly mapZodErrorToFormErrors: (error: unknown, getMessage: ZodMessageGetter) => ValidationFormError[];
+}
 type HaiResult<T> = {
     success: true;
     data: T;
@@ -1566,6 +1682,8 @@ interface CoreFunctions {
     readonly logger: CoreLogger;
     /** 国际化工具 */
     readonly i18n: I18nFn;
+    /** Zod 校验错误 → i18n 消息映射工具（kit / serv / api-client 共享） */
+    readonly zodValidation: typeof zodValidation;
     /** ID 生成工具 */
     readonly id: IdFn;
     /** 类型检查工具 */
@@ -1586,41 +1704,4 @@ interface CoreFunctions {
     readonly module: ModuleFn;
 }
 
-/**
- * @h-ai/core — 模块初始化工具
- *
- * 封装各模块共同的「未初始化」错误处理模式，消除跨模块冗余。
- * @module core-util-module
- */
-
-/**
- * 未初始化工具集返回类型。
- *
- * 提供错误创建、HaiResult 包装和 Proxy 代理等能力，
- * 用于模块未初始化时的安全回退。
- *
- * @template E - 模块错误类型（必须继承 HaiError）
- */
-interface NotInitializedKit<E extends HaiError> {
-    /** 创建未初始化错误对象 */
-    error: () => E;
-    /** 创建包含未初始化错误的失败 HaiResult */
-    result: <T>() => HaiResult<T>;
-    /**
-     * 创建 Proxy 代理，拦截所有方法调用并返回未初始化错误。
-     *
-     * @param mode - 'async'（默认）所有方法返回 `Promise<HaiResult>`；'sync' 所有方法返回 `HaiResult`
-     */
-    proxy: <T>(mode?: 'async' | 'sync') => T;
-}
-/** module 子工具类型 */
-/** overloaded function type for createNotInitializedKit */
-interface CreateNotInitializedKitFn {
-    (codeOrDef: HaiErrorDef, messageFn: () => string): NotInitializedKit<HaiError>;
-    <E extends HaiError>(codeOrDef: E['code'], messageFn: () => string): NotInitializedKit<E>;
-}
-interface ModuleFn {
-    createNotInitializedKit: CreateNotInitializedKitFn;
-}
-
-export { type ArrayFn as A, type LoggerFunctions as B, type CoreOptions as C, type LoggerOptions as D, type ErrorFn as E, type LoggingConfig as F, LoggingConfigSchema as G, type HaiError as H, type I18nFn as I, type MatchHandlers as J, type MessageDictionary as K, type Locale as L, type ModuleFn as M, type MessageOptions as N, type ObjectFn as O, type PaginatedResult as P, type PaginationOptions as Q, type PaginationOptionsInput as R, type StringFn as S, type TypeUtilFn as T, err as U, ok as V, type HaiResult as a, type CoreLogger as b, type IdFn as c, type AsyncFn as d, type TimeFn as e, type CoreConfig as f, CoreConfigSchema as g, type CoreFunctions as h, type Env as i, EnvSchema as j, type ErrorInfo as k, type ErrorInfoValue as l, HaiCommonError as m, HaiConfigError as n, type HaiErrorDef as o, type IdConfig as p, IdConfigSchema as q, type InterpolationParams as r, type LocaleInfo as s, type LocaleMessages as t, type LogContext as u, type LogFormat as v, LogFormatSchema as w, type LogLevel as x, LogLevelSchema as y, type Logger as z };
+export { type MessageOptions as A, type PaginationOptions as B, type CoreFunctions as C, type PaginationOptionsInput as D, type Env as E, type ZodValidationFn as F, type ZodValidationMessageKey as G, type HaiResult as H, type IdConfig as I, err as J, ok as K, type Locale as L, type MatchHandlers as M, type I18nFn as N, zodValidation as O, type PaginatedResult as P, type IdFn as Q, type ObjectFn as R, type StringFn as S, type TypeUtilFn as T, type ArrayFn as U, type ValidationFormError as V, type AsyncFn as W, type TimeFn as X, type ErrorFn as Y, type ZodMessageGetter as Z, type ModuleFn as _, type HaiError as a, type CoreOptions as b, type CoreConfig as c, CoreConfigSchema as d, type CoreLogger as e, EnvSchema as f, type ErrorInfo as g, type ErrorInfoValue as h, HaiCommonError as i, HaiConfigError as j, type HaiErrorDef as k, IdConfigSchema as l, type InterpolationParams as m, type LocaleInfo as n, type LocaleMessages as o, type LogContext as p, type LogFormat as q, LogFormatSchema as r, type LogLevel as s, LogLevelSchema as t, type Logger as u, type LoggerFunctions as v, type LoggerOptions as w, type LoggingConfig as x, LoggingConfigSchema as y, type MessageDictionary as z };

package/dist/node.d.ts

@@ -1,6 +1,6 @@
-import { H as HaiError, a as HaiResult, C as CoreOptions, b as CoreLogger, I as I18nFn, c as IdFn, T as TypeUtilFn, O as ObjectFn, S as StringFn, A as ArrayFn, d as AsyncFn, e as TimeFn, E as ErrorFn, M as ModuleFn } from './core-util-module-B-wH5_ZT.js';
-export { f as CoreConfig, g as CoreConfigSchema, h as CoreFunctions, i as Env, j as EnvSchema, k as ErrorInfo, l as ErrorInfoValue, m as HaiCommonError, n as HaiConfigError, o as HaiErrorDef, p as IdConfig, q as IdConfigSchema, r as InterpolationParams, L as Locale, s as LocaleInfo, t as LocaleMessages, u as LogContext, v as LogFormat, w as LogFormatSchema, x as LogLevel, y as LogLevelSchema, z as Logger, B as LoggerFunctions, D as LoggerOptions, F as LoggingConfig, G as LoggingConfigSchema, J as MatchHandlers, K as MessageDictionary, N as MessageOptions, P as PaginatedResult, Q as PaginationOptions, R as PaginationOptionsInput, U as err, V as ok } from './core-util-module-B-wH5_ZT.js';
-import * as zod from 'zod';
+import { H as HaiResult, a as HaiError, C as CoreFunctions, b as CoreOptions } from './core-types-aT8pmvMq.js';
+export { c as CoreConfig, d as CoreConfigSchema, e as CoreLogger, E as Env, f as EnvSchema, g as ErrorInfo, h as ErrorInfoValue, i as HaiCommonError, j as HaiConfigError, k as HaiErrorDef, I as IdConfig, l as IdConfigSchema, m as InterpolationParams, L as Locale, n as LocaleInfo, o as LocaleMessages, p as LogContext, q as LogFormat, r as LogFormatSchema, s as LogLevel, t as LogLevelSchema, u as Logger, v as LoggerFunctions, w as LoggerOptions, x as LoggingConfig, y as LoggingConfigSchema, M as MatchHandlers, z as MessageDictionary, A as MessageOptions, P as PaginatedResult, B as PaginationOptions, D as PaginationOptionsInput, V as ValidationFormError, Z as ZodMessageGetter, F as ZodValidationFn, G as ZodValidationMessageKey, J as err, K as ok } from './core-types-aT8pmvMq.js';
+import { ZodType } from 'zod';
 
 /**
  * @h-ai/core — 配置管理（Node.js 专用）
@@ -23,7 +23,197 @@ import * as zod from 'zod';
  * ```
  */
 type WatchCallback<T = unknown> = (config: T | null, error?: HaiError) => void;
+/**
+ * 配置管理对象。
+ *
+ * @example
+ * ```ts
+ * const result = config.load('app', './config/app.yml')
+ * if (result.success) {
+ *   const cfg = config.get('app')
+ * }
+ * ```
+ */
+declare const config: {
+    /**
+     * 加载配置到缓存。
+     *
+     * 加载 YAML 文件并可选地用 Zod Schema 校验，成功后写入缓存。
+     *
+     * @param name - 配置名称（缓存 key）
+     * @param filePath - YAML 文件路径
+     * @param schema - 可选 Zod Schema（不传则跳过校验）
+     * @returns 成功时返回解析后的配置数据；失败时返回 HaiError
+     *
+     * @example
+     * ```ts
+     * const result = config.load('core', './config/_core.yml', CoreConfigSchema)
+     * if (result.success) {
+     *   // result.data 为校验后的配置
+     * }
+     * ```
+     */
+    load<T>(name: string, filePath: string, schema?: ZodType<T>): HaiResult<T>;
+    /**
+     * 验证已加载的配置数据。
+     *
+     * 对缓存中的配置数据重新用 Schema 校验，校验通过后更新缓存。
+     *
+     * @param name - 配置名称
+     * @param schema - Zod 验证模式
+     * @returns 校验结果；未加载时返回 NOT_LOADED，格式错误返回 VALIDATION_ERROR
+     *
+     * @example
+     * ```ts
+     * const result = config.validate('app', AppSchema)
+     * if (!result.success) {
+     *   // result.error.code 可能为 NOT_LOADED 或 VALIDATION_ERROR
+     * }
+     * ```
+     */
+    validate<T>(name: string, schema: ZodType<T>): HaiResult<T>;
+    /**
+     * 获取已加载的配置。
+     *
+     * @param name - 配置名称
+     * @returns 配置数据；未加载时返回 undefined
+     *
+     * @example
+     * ```ts
+     * const cfg = config.get<CoreConfig>('core')
+     * if (cfg) {
+     *   // 使用 cfg
+     * }
+     * ```
+     */
+    get<T>(name: string): T | undefined;
+    /**
+     * 获取配置，不存在时抛出错误。
+     *
+     * @param name - 配置名称
+     * @returns 配置数据
+     * @throws 配置未加载时抛出 Error
+     *
+     * @example
+     * ```ts
+     * try {
+     *   const cfg = config.getOrThrow<CoreConfig>('core')
+     * } catch (e) {
+     *   // 配置未加载
+     * }
+     * ```
+     */
+    getOrThrow<T>(name: string): T;
+    /**
+     * 重新加载配置。
+     *
+     * 从磁盘重新读取配置文件并更新缓存，同时通知所有 watch 回调。
+     *
+     * @param name - 配置名称
+     * @returns 重载结果；未加载时返回 NOT_LOADED
+     *
+     * @example
+     * ```ts
+     * const result = config.reload('app')
+     * ```
+     */
+    reload(name: string): HaiResult<unknown>;
+    /**
+     * 检查配置是否已加载。
+     *
+     * @param name - 配置名称
+     * @returns 是否已加载到缓存
+     *
+     * @example
+     * ```ts
+     * if (config.has('db')) {
+     *   const dbCfg = config.get('db')
+     * }
+     * ```
+     */
+    has(name: string): boolean;
+    /**
+     * 清除配置缓存（同时停止对应监听）。
+     *
+     * @param name - 配置名称；不传则清除全部
+     *
+     * @example
+     * ```ts
+     * config.clear('app')   // 清除单个
+     * config.clear()        // 清除全部
+     * ```
+     */
+    clear(name?: string): void;
+    /**
+     * 获取所有已加载的配置名称。
+     *
+     * @returns 配置名称数组
+     *
+     * @example
+     * ```ts
+     * const names = config.keys() // ['core', 'db', 'app']
+     * ```
+     */
+    keys(): string[];
+    /**
+     * 监听配置文件变更并自动重载。
+     *
+     * 文件变更时自动重新加载并调用回调。配置未加载时立即回调 NOT_LOADED 错误。
+     *
+     * @param name - 配置名称
+     * @param callback - 配置变更回调，接收新配置或错误
+     * @returns 取消监听函数
+     *
+     * @example
+     * ```ts
+     * const unwatch = config.watch('app', (cfg, error) => {
+     *   if (error) { core.logger.error('reload failed', { error }); return }
+     *   core.logger.info('config updated', { cfg })
+     * })
+     * // 取消监听
+     * unwatch()
+     * ```
+     */
+    watch<T = unknown>(name: string, callback: WatchCallback<T>): () => void;
+    /**
+     * 停止配置文件监听。
+     *
+     * @param name - 配置名称；不传则停止所有监听
+     *
+     * @example
+     * ```ts
+     * config.unwatch('app')  // 停止单个
+     * config.unwatch()       // 停止全部
+     * ```
+     */
+    unwatch(name?: string): void;
+    /**
+     * 检查是否正在监听某个配置。
+     *
+     * @param name - 配置名称
+     * @returns 是否有活跃的 watcher
+     *
+     * @example
+     * ```ts
+     * if (config.isWatching('app')) {
+     *   config.unwatch('app')
+     * }
+     * ```
+     */
+    isWatching(name: string): boolean;
+};
 
+/**
+ * @h-ai/core — Core 服务聚合（Node.js）
+ *
+ * 提供 Node.js 环境的 core 对象，聚合常用功能。 所有功能统一通过 core 对象访问，并提供配置加载能力。
+ * @module core-main.node
+ */
+
+type NodeCoreFunctions = CoreFunctions & {
+    readonly config: typeof config;
+    readonly init: typeof initCore;
+};
 /**
  * Core 服务对象 - 聚合常用功能（Node.js）。
  *
@@ -33,35 +223,7 @@ type WatchCallback<T = unknown> = (config: T | null, error?: HaiError) => void;
  * core.init({ configDir: './config' })
  * ```
  */
-declare const core: {
-    /** 配置管理 */
-    config: {
-        load<T>(name: string, filePath: string, schema?: zod.ZodType<T>): HaiResult<T>;
-        validate<T>(name: string, schema: zod.ZodType<T>): HaiResult<T>;
-        get<T>(name: string): T | undefined;
-        getOrThrow<T>(name: string): T;
-        reload(name: string): HaiResult<unknown>;
-        has(name: string): boolean;
-        clear(name?: string): void;
-        keys(): string[];
-        watch<T = unknown>(name: string, callback: WatchCallback<T>): () => void;
-        unwatch(name?: string): void;
-        isWatching(name: string): boolean;
-    };
-    /** 初始化 Core */
-    init: typeof initCore;
-    logger: CoreLogger;
-    i18n: I18nFn;
-    id: IdFn;
-    typeUtils: TypeUtilFn;
-    object: ObjectFn;
-    string: StringFn;
-    array: ArrayFn;
-    async: AsyncFn;
-    time: TimeFn;
-    error: ErrorFn;
-    module: ModuleFn;
-};
+declare const core: NodeCoreFunctions;
 /**
  * 初始化 Core（内部实现，通过 `core.init()` 调用）。
  *
@@ -79,4 +241,4 @@ declare const core: {
  */
 declare function initCore(options?: CoreOptions): void;
 
-export { CoreLogger, CoreOptions, HaiError, HaiResult, core };
+export { CoreFunctions, CoreOptions, HaiError, HaiResult, core };

package/dist/node.js

@@ -1,5 +1,5 @@
-import { createCore, CoreConfigSchema, i18n, err, HaiConfigError, ok, typeUtils } from './chunk-STH6Q4GV.js';
-export { CoreConfigSchema, EnvSchema, HaiCommonError, HaiConfigError, IdConfigSchema, LogFormatSchema, LogLevelSchema, LoggingConfigSchema, err, ok } from './chunk-STH6Q4GV.js';
+import { createCore, CoreConfigSchema, i18n, err, HaiConfigError, ok, typeUtils } from './chunk-JM2QORKH.js';
+export { CoreConfigSchema, EnvSchema, HaiCommonError, HaiConfigError, IdConfigSchema, LogFormatSchema, LogLevelSchema, LoggingConfigSchema, err, ok } from './chunk-JM2QORKH.js';
 import { existsSync, readdirSync, watch, readFileSync } from 'fs';
 import { join } from 'path';
 import process2 from 'process';
@@ -572,6 +572,8 @@ function createNodeCore() {
   });
   return {
     ...baseCore,
+    /** Zod 校验错误 → i18n 消息映射工具（kit / serv / api-client 共享）。 */
+    zodValidation: baseCore.zodValidation,
     /** 配置管理 */
     config,
     /** 初始化 Core */