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

package/README.md

@@ -7,6 +7,7 @@
 - **HaiResult 类型** — 函数式错误处理（`ok` / `err`），所有模块统一返回值
 - **统一日志** — Node.js 基于 pino，浏览器基于 loglevel，API 一致
 - **国际化（i18n）** — 集中式 locale 管理 + 类型安全的消息获取器
+- **Zod 校验错误映射** — 兼容 Zod v3/v4 的 issue 提取与默认英文消息本地化
 - **配置管理** — YAML 加载、环境变量插值、Zod 校验、文件监听（Node.js 专用）
 - **ID 生成** — nanoid 与 UUID v4
 - **错误定义** — 标准化错误码体系，支持跨模块统一的错误定义与实例创建
@@ -172,6 +173,67 @@ core.i18n.DEFAULT_LOCALES // [{ code: 'zh-CN', label: '简体中文' }, { code:
 core.i18n.DEFAULT_LOCALE // 'zh-CN'
 ```
 
+### Zod 校验错误 i18n 映射
+
+`core.zodValidation` 用于把 Zod `SafeParseError` / `ZodError` 转为扁平表单错误，并将 Zod
+默认英文消息映射为调用方自己的 i18n 文案。
+
+- 两个公开入口：
+  - `createPrefixedZodMessageGetter()`：按模块前缀自动派生 `serv_validation*` / `kit_validation*` 这类 key，省掉手写 `KEY_MAP`
+  - `mapZodErrorToFormErrors()`：一步完成提取 + 本地化 + 扁平化
+- 自定义业务消息不会被覆盖；只有 Zod 默认英文消息才会被替换
+
+```typescript
+import type { ZodMessageGetter } from '@h-ai/core'
+import { core } from '@h-ai/core'
+import { z } from 'zod'
+
+const LoginSchema = z.object({
+  email: z.string().email(),
+  password: z.string().min(8),
+  nickname: z.string().min(1, '请填写昵称'),
+})
+
+const getMessage: ZodMessageGetter = (key, params) => {
+  switch (key) {
+    case 'validationEmail':
+      return '请输入合法邮箱地址'
+    case 'validationStringMin':
+      return `至少输入 ${params?.min} 个字符`
+    case 'validationRequired':
+      return '此项为必填项'
+    default:
+      return '输入不合法'
+  }
+}
+
+const result = LoginSchema.safeParse({
+  email: 'bad',
+  password: '123',
+  nickname: '',
+})
+
+if (!result.success) {
+  const getMessage = core.zodValidation.createPrefixedZodMessageGetter(
+    'kit',
+    (messageKey, params) => {
+      if (messageKey === 'kit_validationEmail')
+        return '请输入合法邮箱地址'
+      if (messageKey === 'kit_validationStringMin')
+        return `至少输入 ${params?.min} 个字符`
+      return '输入不合法'
+    },
+  )
+  const errors = core.zodValidation.mapZodErrorToFormErrors(result.error, getMessage)
+
+  errors[0]?.field // 'email'
+  errors[0]?.message // '请输入合法邮箱地址'
+  errors[2]?.message // '请填写昵称'（schema 自定义消息原样保留）
+
+  core.logger.info('Validation failed', { errors })
+}
+```
+
 ### 配置管理（Node.js 专用）
 
 ```typescript

package/dist/browser.d.ts

@@ -1,5 +1,5 @@
-import { 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, H as HaiError, o as HaiErrorDef, a as HaiResult, 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 { b as CoreOptions, e as CoreLogger, N as I18nFn, O as zodValidation, Q as IdFn, T as TypeUtilFn, R as ObjectFn, S as StringFn, U as ArrayFn, W as AsyncFn, X as TimeFn, Y as ErrorFn, _ as ModuleFn } from './core-types-aT8pmvMq.js';
+export { c as CoreConfig, d as CoreConfigSchema, C as CoreFunctions, E as Env, f as EnvSchema, g as ErrorInfo, h as ErrorInfoValue, i as HaiCommonError, j as HaiConfigError, a as HaiError, k as HaiErrorDef, H as HaiResult, 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 'zod';
 
 /**
@@ -16,6 +16,7 @@ declare const core: {
     init: typeof initCore;
     logger: CoreLogger;
     i18n: I18nFn;
+    zodValidation: typeof zodValidation;
     id: IdFn;
     typeUtils: TypeUtilFn;
     object: ObjectFn;

package/dist/browser.js

@@ -1,5 +1,5 @@
-import { __commonJS, __toESM, createCore } from './chunk-STH6Q4GV.js';
-export { CoreConfigSchema, EnvSchema, HaiCommonError, HaiConfigError, IdConfigSchema, LogFormatSchema, LogLevelSchema, LoggingConfigSchema, err, ok } from './chunk-STH6Q4GV.js';
+import { __commonJS, __toESM, createCore } from './chunk-JM2QORKH.js';
+export { CoreConfigSchema, EnvSchema, HaiCommonError, HaiConfigError, IdConfigSchema, LogFormatSchema, LogLevelSchema, LoggingConfigSchema, err, ok } from './chunk-JM2QORKH.js';
 
 // ../../node_modules/loglevel/lib/loglevel.js
 var require_loglevel = __commonJS({

package/dist/{chunk-STH6Q4GV.js → chunk-JM2QORKH.js}

@@ -14208,6 +14208,109 @@ var i18n = {
   coreM
 };
 
+// src/i18n/core-zod-mapper.ts
+function createPrefixedZodMessageGetter(prefix, getMessage) {
+  return (key, params) => getMessage(`${prefix}_${key}`, params);
+}
+var ZOD_DEFAULT_MESSAGE_PATTERNS = [
+  /^Too small:/,
+  /^Too big:/,
+  /^Invalid input:/,
+  /^Invalid option:/,
+  /^Invalid string:/,
+  /^Invalid email$/,
+  /^Invalid email address$/,
+  /^Invalid url$/i,
+  /^Invalid UUID$/,
+  /^Invalid enum value/,
+  /^Required$/,
+  /^String must contain/,
+  /^Number must be/,
+  /^Array must contain/
+];
+function extractZodIssues(error49) {
+  if (!error49 || typeof error49 !== "object")
+    return [];
+  const obj = error49;
+  return obj.issues ?? obj.errors ?? [];
+}
+function isDefaultZodMessage(message) {
+  return ZOD_DEFAULT_MESSAGE_PATTERNS.some((pattern) => pattern.test(message));
+}
+function formatLimit(value) {
+  if (typeof value === "number" || typeof value === "bigint")
+    return String(value);
+  return void 0;
+}
+function getIssueTarget(issue2) {
+  return issue2.origin ?? issue2.type;
+}
+function getIssueFormat(issue2) {
+  if (typeof issue2.format === "string")
+    return issue2.format;
+  if (typeof issue2.validation === "string")
+    return issue2.validation;
+  return void 0;
+}
+function localizeZodIssue(issue2, getMessage) {
+  if (!isDefaultZodMessage(issue2.message))
+    return issue2.message;
+  const target = getIssueTarget(issue2);
+  const format = getIssueFormat(issue2);
+  const min = formatLimit(issue2.minimum);
+  const max = formatLimit(issue2.maximum);
+  if (issue2.code === "too_small") {
+    if (target === "string" && min)
+      return getMessage("validationStringMin", { min });
+    if ((target === "number" || target === "bigint") && min)
+      return getMessage("validationNumberMin", { min });
+    if (target === "array" && min)
+      return getMessage("validationArrayMin", { min });
+    if (min)
+      return getMessage("validationTooSmall", { min });
+  }
+  if (issue2.code === "too_big") {
+    if (target === "string" && max)
+      return getMessage("validationStringMax", { max });
+    if ((target === "number" || target === "bigint") && max)
+      return getMessage("validationNumberMax", { max });
+    if (target === "array" && max)
+      return getMessage("validationArrayMax", { max });
+    if (max)
+      return getMessage("validationTooBig", { max });
+  }
+  if (issue2.code === "invalid_type") {
+    if (issue2.received === "undefined" || issue2.message.includes("received undefined"))
+      return getMessage("validationRequired");
+    return getMessage("validationInvalidType");
+  }
+  if (issue2.code === "invalid_format" || issue2.code === "invalid_string") {
+    if (format === "email")
+      return getMessage("validationEmail");
+    if (format === "url")
+      return getMessage("validationUrl");
+    if (format === "uuid")
+      return getMessage("validationUuid");
+    return getMessage("validationInvalid");
+  }
+  if (issue2.code === "invalid_value" || issue2.code === "invalid_enum_value")
+    return getMessage("validationEnum");
+  return getMessage("validationInvalid");
+}
+function mapZodIssuesToFormErrors(issues, getMessage) {
+  return issues.map((issue2) => ({
+    field: issue2.path.join(".") || "_",
+    message: localizeZodIssue(issue2, getMessage)
+  }));
+}
+function mapZodErrorToFormErrors(error49, getMessage) {
+  return mapZodIssuesToFormErrors(extractZodIssues(error49), getMessage);
+}
+var zodValidation = {
+  createPrefixedZodMessageGetter,
+  mapZodErrorToFormErrors
+};
+
 // src/utils/core-util-array.ts
 function unique(arr) {
   return [...new Set(arr)];
@@ -14672,6 +14775,19 @@ function createCore(loggerFns) {
      * ```
      */
     i18n,
+    /**
+     * Zod 校验错误 → i18n 消息映射工具（kit / serv / api-client 共享）。
+     *
+     * 调用方注入自己的 `ZodMessageGetter`，把统一的校验消息 key 映射到本模块的 i18n 字典。
+     *
+     * @example
+     * ```ts
+     * import { core } from '@h-ai/core'
+     *
+     * const errors = core.zodValidation.mapZodErrorToFormErrors(zodError, getMessage)
+     * ```
+     */
+    zodValidation,
     // ─── ID ───
     /**
      * ID 生成工具。
@@ -14782,5 +14898,5 @@ function createCore(loggerFns) {
 }
 
 export { CoreConfigSchema, EnvSchema, HaiCommonError, HaiConfigError, IdConfigSchema, LogFormatSchema, LogLevelSchema, LoggingConfigSchema, __commonJS, __toESM, createCore, err, i18n, ok, typeUtils };
-//# sourceMappingURL=chunk-STH6Q4GV.js.map
-//# sourceMappingURL=chunk-STH6Q4GV.js.map
+//# sourceMappingURL=chunk-JM2QORKH.js.map
+//# sourceMappingURL=chunk-JM2QORKH.js.map