@h-ai/core 1.0.0-beta.17 → 1.0.0-beta.19

package/README.en.md

@@ -93,7 +93,9 @@ The startup boundary stops when required configuration is unavailable. `core.ini
 import { core } from '@h-ai/core'
 
 // 浏览器不读取 YAML；此处只设置日志，输出 warn 及以上级别。
-core.init({ logging: { level: 'warn' } }) // 返回 undefined；之后 info 日志被过滤。
+core.init({
+  logging: { level: 'warn' }
+}) // 返回 undefined；之后 info 日志被过滤。
 
 // 设置当前页面使用的默认消息语言。
 core.i18n.setGlobalLocale('zh-CN') // 返回 undefined；页面默认消息使用中文。
@@ -131,7 +133,9 @@ import { core } from '@h-ai/core'
 import { z } from 'zod'
 
 // 读取上方 config/app.yml；Schema 同时描述类型和校验规则。
-const AppSchema = z.object({ port: z.number().int().min(1).max(65535) })
+const AppSchema = z.object({
+  port: z.number().int().min(1).max(65535)
+})
 const loaded = core.config.load('app', './config/app.yml', AppSchema)
 if (!loaded.success)
   throw new Error(loaded.error.message, { cause: loaded.error })
@@ -230,11 +234,25 @@ import { core } from '@h-ai/core'
 import { z } from 'zod'
 
 // 用显式环境数据演示覆盖顺序、数值/布尔转换与字符串保留。
-const AppSchema = z.object({ port: z.number(), enabled: z.boolean(), label: z.string(), code: z.string() })
+const AppSchema = z.object({
+  port: z.number(),
+  enabled: z.boolean(),
+  label: z.string(),
+  code: z.string()
+})
 const resolved = core.config.resolve({
   name: 'app',
-  // eslint-disable-next-line no-template-curly-in-string -- 保留 YAML 中等待框架解析的字面表达式。
-  value: { port: '${PORT:3000}', enabled: '${ENABLED:false}', label: 'server-${PORT:3000}', code: '${APP_CODE:00123}' },
+
+  value: {
+    // eslint-disable-next-line no-template-curly-in-string -- 保留供配置解析器处理的字面占位符。
+    port: '${PORT:3000}',
+    // eslint-disable-next-line no-template-curly-in-string -- 保留供配置解析器处理的字面占位符。
+    enabled: '${ENABLED:false}',
+    // eslint-disable-next-line no-template-curly-in-string -- 保留供配置解析器处理的字面占位符。
+    label: 'server-${PORT:3000}',
+    // eslint-disable-next-line no-template-curly-in-string -- 保留供配置解析器处理的字面占位符。
+    code: '${APP_CODE:00123}'
+  },
   environment: { PORT: '4000', HAI_APP_PORT: '5000' },
   schema: AppSchema,
 })
@@ -265,9 +283,18 @@ resolve() also lets build/deploy tools calculate settings in memory. toEnv() con
 import { core } from '@h-ai/core'
 
 // 配置生成器把普通对象转成 HAI_APP_PORT 等变量；数组保留为 JSON。
-const values = core.config.toEnv({ prefix: 'HAI_APP', value: { port: 3000, tags: ['local'] } })
+const values = core.config.toEnv({
+  prefix: 'HAI_APP',
+  value: {
+    port: 3000,
+    tags: ['local']
+  }
+})
 // values：{ HAI_APP_PORT: '3000', HAI_APP_TAGS: '["local"]' }。
-const merged = core.config.mergeEnv([values, { HAI_APP_PORT: '4000' }])
+const merged = core.config.mergeEnv([
+  values,
+  { HAI_APP_PORT: '4000' }
+])
 // merged：{ HAI_APP_PORT: '4000', HAI_APP_TAGS: '["local"]' }。
 const text = core.config.stringifyEnv(merged) // 编码为可写入 .env 的文本。
 // text 含以下两行，每行以换行符结尾：
@@ -295,7 +322,9 @@ core.logger.trace('Processing detail', { step: 1 })
 core.logger.debug('Read started')
 core.logger.info('Order created', { orderId: 'order-1' })
 core.logger.warn('Retry scheduled')
-core.logger.error('Operation failed', { error: new Error('Example failure') })
+core.logger.error('Operation failed', {
+  error: new Error('Example failure')
+})
 core.logger.fatal('Service cannot continue')
 // 六次日志调用均返回 undefined；分别输出对应级别、上面的消息及所传字段。
 // 例如 info 日志的消息为 'Order created'，字段 orderId 为 'order-1'。
@@ -307,10 +336,16 @@ create() makes a named logger; child() attaches fixed context. configure() sets
 import { core } from '@h-ai/core'
 
 // 全局配置可作用于已经创建的 Logger；redact 补充业务隐私字段。
-core.logger.configure({ level: 'info', format: 'json', redact: ['customer.email'] }) // 返回 undefined；后续日志按此配置输出。
+core.logger.configure({
+  level: 'info',
+  format: 'json',
+  redact: ['customer.email']
+}) // 返回 undefined；后续日志按此配置输出。
 const orders = core.logger.create({ name: 'orders' }) // 返回 Logger 对象，可调用 info/warn 等方法。
 const request = core.logger.child({ requestId: 'request-1' }) // 返回带固定 requestId 的 Logger。
-orders.info('Order created', { customer: { email: 'user@example.com' } }) // 返回 undefined；输出中 customer.email 为 '[REDACTED]'。
+orders.info('Order created', {
+  customer: { email: 'user@example.com' }
+}) // 返回 undefined；输出中 customer.email 为 '[REDACTED]'。
 request.warn('Request needs attention') // 返回 undefined；输出中 requestId 为 'request-1'。
 core.logger.getLevel() // 'info'。
 ```
@@ -370,7 +405,10 @@ core.sanitize.sanitizeSensitiveValue('example-only', 'password') // '[REDACTED]'
 const safe = core.sanitize.sanitizeSensitiveFields({ password: 'example-only', email: 'user@example.com' })
 // safe：{ password: '[REDACTED]', email: 'user@example.com' }，原对象不变。
 // 默认仅遮蔽凭据；额外业务隐私可在已处理凭据的副本上继续清理。
-core.sanitize.sanitizeSensitiveFields(safe, { matcher: ['email'], replacement: '***' })
+core.sanitize.sanitizeSensitiveFields(safe, {
+  matcher: ['email'],
+  replacement: '***'
+})
 // => { password: '[REDACTED]', email: '***' }
 core.sanitize.sanitizeUrl('https://user:example-only@example.com/?token=example-only')
 // => 'https://[REDACTED]:[REDACTED]@example.com/?token=[REDACTED]'
@@ -449,6 +487,10 @@ Internal `cause` / `ext` are private by default. Field errors for 400/422 can re
 
 These constants belong to `HaiConfigError`; cross-module failures use `HaiCommonError`.
 
+`HaiCommonError.RATE_LIMIT_EXCEEDED` maps to `hai:common:203` / HTTP 429. Kit shortcut responses and guards use the same common error definitions.
+
+HTTP/UI boundaries expose business messages only for explicit valid 4xx statuses. Missing or invalid `httpStatus` is treated as 500 with a safe message. Custom business errors must carry a complete error definition or an explicit status.
+
 ### Messages and locales: `core.i18n`
 
 Create message getters with parameter interpolation, read built-in Core messages, and manage locale selection. Constants list framework locales and do not register application translations.
@@ -478,7 +520,9 @@ const message = core.i18n.createMessageGetter({
 // createMessageGetter 返回消息函数；如 message('welcome', { locale: 'zh-CN', params: { name: 'Alice' } }) 得到 '欢迎 Alice'。
 const greeting = await core.i18n.runWithLocale('en-US', async () => {
   await Promise.resolve()
-  return message('welcome', { params: { name: 'Alice' } })
+  return message('welcome', {
+    params: { name: 'Alice' }
+  })
 })
 // greeting：'Welcome Alice'；runWithLocale 返回回调的结果，此处等待 Promise 得到字符串。
 core.logger.info('Greeting prepared', { greeting })
@@ -500,7 +544,9 @@ const message = core.zodValidation.createPrefixedZodMessageGetter('core', key =>
     ? core.i18n.coreM('core_validationEmail', { locale: 'zh-CN' })
     : core.i18n.coreM('core_errorValidation', { locale: 'zh-CN' }))
 // 返回消息函数；message('validationEmail') 得到 '请输入有效的邮箱地址'。
-const parsed = z.object({ email: z.email() }).safeParse({ email: 'invalid' })
+const parsed = z.object({
+  email: z.email()
+}).safeParse({ email: 'invalid' })
 if (!parsed.success) {
   const errors = core.zodValidation.mapZodErrorToFormErrors(parsed.error, message)
   // errors：[{ field: 'email', message: '请输入有效的邮箱地址' }]。
@@ -617,10 +663,14 @@ import { AccessConditionSchema, core } from '@h-ai/core'
 
 core.access.normalizeClientIp('::ffff:198.51.100.23') // 198.51.100.23。
 const resolve = core.access.createClientIpResolver(['192.0.2.10']) // 返回 IP 解析函数，只信任这个代理。
-const request = new Request('https://example.test/api/orders', { headers: { 'x-forwarded-for': '198.51.100.23' } })
+const request = new Request('https://example.test/api/orders', {
+  headers: { 'x-forwarded-for': '198.51.100.23' }
+})
 // 第二参数必须来自真实 socket/可信平台；这里用测试地址模拟代理对端。
 const clientIp = resolve(request, '192.0.2.10') // '198.51.100.23'，读取受信代理的转发头。
-const check = core.access.createConditionCheck(AccessConditionSchema.parse({ allowIps: ['198.51.100.0/24'] }))
+const check = core.access.createConditionCheck(AccessConditionSchema.parse({
+  allowIps: ['198.51.100.0/24']
+}))
 // createConditionCheck 返回检查函数；check(clientIp) 得到 { allowed: true }。
 core.logger.info('Address checked', { allowed: check(clientIp).allowed })
 ```
@@ -632,7 +682,15 @@ import { core } from '@h-ai/core'
 
 // 可改为 loadPolicy({ file: './config/security/request-access.yml' }) 在启动时读独立文件。
 const policy = core.access.loadPolicy({
-  rules: [{ id: 'external-api', paths: ['/api/external/**'], methods: ['POST'], allowIps: ['192.0.2.0/24'], encryption: 'disabled' }],
+  rules: [
+    {
+      id: 'external-api',
+      paths: ['/api/external/**'],
+      methods: ['POST'],
+      allowIps: ['192.0.2.0/24'],
+      encryption: 'disabled'
+    }
+  ],
 })
 // policy.rules[0] 保留上方规则，并补 denyIps: []、windows: []、timezone: 'UTC'。
 const check = core.access.createRequestCheck(policy) // 返回请求检查函数，另带 encryption 方法和 requiresEncryption 属性。
@@ -702,7 +760,9 @@ core.object.omit(settings, ['port']) // { name: 'orders' }。
 core.object.keys(settings) // ['name', 'port']，元素类型为 'name' | 'port'。
 core.object.values(settings) // ['orders', 4000]。
 core.object.entries(settings) // [['name', 'orders'], ['port', 4000]]。
-core.object.fromEntries([['mode', 'local']]) // { mode: 'local' }。
+core.object.fromEntries([
+  ['mode', 'local']
+]) // { mode: 'local' }。
 ```
 
 deepClone uses structuredClone for cloneable Date/Map/Set/cyclic values and throws for unsupported values such as functions. deepMerge recursively merges plain objects only; later arrays, dates, collections, and class instances replace earlier values without modifying inputs. It does not clone instances.
@@ -739,11 +799,17 @@ import { core } from '@h-ai/core'
 
 core.array.unique([1, 1, 2]) // [1, 2]。
 core.array.chunk([1, 2, 3], 2) // [[1, 2], [3]]。
-core.array.groupBy([{ role: 'admin' }, { role: 'user' }], item => item.role)
+core.array.groupBy([
+  { role: 'admin' },
+  { role: 'user' }
+], item => item.role)
 // => { admin: [{ role: 'admin' }], user: [{ role: 'user' }] }
 core.array.first([1, 2, 3]) // 1；空数组为 undefined。
 core.array.last([1, 2, 3]) // 3；空数组为 undefined。
-core.array.flatten([[1], [2, 3]]) // [1, 2, 3]，只展开一层。
+core.array.flatten([
+  [1],
+  [2, 3]
+]) // [1, 2, 3]，只展开一层。
 core.array.compact([0, null, 1, undefined]) // [0, 1]，保留 0/false/空字符串。
 core.array.shuffle([1, 2, 3]) // 如 [2, 3, 1]，次序随机；新数组不修改输入。
 core.array.intersection([1, 2], [2, 3]) // [2]。

package/README.ja.md

@@ -93,7 +93,9 @@ core.logger.info('Application ready', { name: config.data.name }) // 返回 unde
 import { core } from '@h-ai/core'
 
 // 浏览器不读取 YAML；此处只设置日志，输出 warn 及以上级别。
-core.init({ logging: { level: 'warn' } }) // 返回 undefined；之后 info 日志被过滤。
+core.init({
+  logging: { level: 'warn' }
+}) // 返回 undefined；之后 info 日志被过滤。
 
 // 设置当前页面使用的默认消息语言。
 core.i18n.setGlobalLocale('zh-CN') // 返回 undefined；页面默认消息使用中文。
@@ -131,7 +133,9 @@ import { core } from '@h-ai/core'
 import { z } from 'zod'
 
 // 读取上方 config/app.yml；Schema 同时描述类型和校验规则。
-const AppSchema = z.object({ port: z.number().int().min(1).max(65535) })
+const AppSchema = z.object({
+  port: z.number().int().min(1).max(65535)
+})
 const loaded = core.config.load('app', './config/app.yml', AppSchema)
 if (!loaded.success)
   throw new Error(loaded.error.message, { cause: loaded.error })
@@ -230,11 +234,25 @@ import { core } from '@h-ai/core'
 import { z } from 'zod'
 
 // 用显式环境数据演示覆盖顺序、数值/布尔转换与字符串保留。
-const AppSchema = z.object({ port: z.number(), enabled: z.boolean(), label: z.string(), code: z.string() })
+const AppSchema = z.object({
+  port: z.number(),
+  enabled: z.boolean(),
+  label: z.string(),
+  code: z.string()
+})
 const resolved = core.config.resolve({
   name: 'app',
-  // eslint-disable-next-line no-template-curly-in-string -- 保留 YAML 中等待框架解析的字面表达式。
-  value: { port: '${PORT:3000}', enabled: '${ENABLED:false}', label: 'server-${PORT:3000}', code: '${APP_CODE:00123}' },
+
+  value: {
+    // eslint-disable-next-line no-template-curly-in-string -- 保留供配置解析器处理的字面占位符。
+    port: '${PORT:3000}',
+    // eslint-disable-next-line no-template-curly-in-string -- 保留供配置解析器处理的字面占位符。
+    enabled: '${ENABLED:false}',
+    // eslint-disable-next-line no-template-curly-in-string -- 保留供配置解析器处理的字面占位符。
+    label: 'server-${PORT:3000}',
+    // eslint-disable-next-line no-template-curly-in-string -- 保留供配置解析器处理的字面占位符。
+    code: '${APP_CODE:00123}'
+  },
   environment: { PORT: '4000', HAI_APP_PORT: '5000' },
   schema: AppSchema,
 })
@@ -265,9 +283,18 @@ resolve() はビルド・デプロイ時のメモリ上の設定計算にも使
 import { core } from '@h-ai/core'
 
 // 配置生成器把普通对象转成 HAI_APP_PORT 等变量；数组保留为 JSON。
-const values = core.config.toEnv({ prefix: 'HAI_APP', value: { port: 3000, tags: ['local'] } })
+const values = core.config.toEnv({
+  prefix: 'HAI_APP',
+  value: {
+    port: 3000,
+    tags: ['local']
+  }
+})
 // values：{ HAI_APP_PORT: '3000', HAI_APP_TAGS: '["local"]' }。
-const merged = core.config.mergeEnv([values, { HAI_APP_PORT: '4000' }])
+const merged = core.config.mergeEnv([
+  values,
+  { HAI_APP_PORT: '4000' }
+])
 // merged：{ HAI_APP_PORT: '4000', HAI_APP_TAGS: '["local"]' }。
 const text = core.config.stringifyEnv(merged) // 编码为可写入 .env 的文本。
 // text 含以下两行，每行以换行符结尾：
@@ -295,7 +322,9 @@ core.logger.trace('Processing detail', { step: 1 })
 core.logger.debug('Read started')
 core.logger.info('Order created', { orderId: 'order-1' })
 core.logger.warn('Retry scheduled')
-core.logger.error('Operation failed', { error: new Error('Example failure') })
+core.logger.error('Operation failed', {
+  error: new Error('Example failure')
+})
 core.logger.fatal('Service cannot continue')
 // 六次日志调用均返回 undefined；分别输出对应级别、上面的消息及所传字段。
 // 例如 info 日志的消息为 'Order created'，字段 orderId 为 'order-1'。
@@ -307,10 +336,16 @@ create() は名前付き Logger、child() は固定項目付き Logger を作り
 import { core } from '@h-ai/core'
 
 // 全局配置可作用于已经创建的 Logger；redact 补充业务隐私字段。
-core.logger.configure({ level: 'info', format: 'json', redact: ['customer.email'] }) // 返回 undefined；后续日志按此配置输出。
+core.logger.configure({
+  level: 'info',
+  format: 'json',
+  redact: ['customer.email']
+}) // 返回 undefined；后续日志按此配置输出。
 const orders = core.logger.create({ name: 'orders' }) // 返回 Logger 对象，可调用 info/warn 等方法。
 const request = core.logger.child({ requestId: 'request-1' }) // 返回带固定 requestId 的 Logger。
-orders.info('Order created', { customer: { email: 'user@example.com' } }) // 返回 undefined；输出中 customer.email 为 '[REDACTED]'。
+orders.info('Order created', {
+  customer: { email: 'user@example.com' }
+}) // 返回 undefined；输出中 customer.email 为 '[REDACTED]'。
 request.warn('Request needs attention') // 返回 undefined；输出中 requestId 为 'request-1'。
 core.logger.getLevel() // 'info'。
 ```
@@ -370,7 +405,10 @@ core.sanitize.sanitizeSensitiveValue('example-only', 'password') // '[REDACTED]'
 const safe = core.sanitize.sanitizeSensitiveFields({ password: 'example-only', email: 'user@example.com' })
 // safe：{ password: '[REDACTED]', email: 'user@example.com' }，原对象不变。
 // 默认仅遮蔽凭据；额外业务隐私可在已处理凭据的副本上继续清理。
-core.sanitize.sanitizeSensitiveFields(safe, { matcher: ['email'], replacement: '***' })
+core.sanitize.sanitizeSensitiveFields(safe, {
+  matcher: ['email'],
+  replacement: '***'
+})
 // => { password: '[REDACTED]', email: '***' }
 core.sanitize.sanitizeUrl('https://user:example-only@example.com/?token=example-only')
 // => 'https://[REDACTED]:[REDACTED]@example.com/?token=[REDACTED]'
@@ -449,6 +487,10 @@ HTTP/UI 境界では `core.error.toPublic(error, traceId?, locale?)` を使い
 
 これらは `HaiConfigError` の定数です。モジュール共通のエラーは `HaiCommonError` を使います。
 
+`HaiCommonError.RATE_LIMIT_EXCEEDED` は `hai:common:203` / HTTP 429 に対応します。Kit の応答ヘルパーとガードも共通エラー定義を使用します。
+
+HTTP/UI 境界で業務メッセージを公開するのは、明示された有効な4xx状態のみです。`httpStatus` が未指定または不正な場合は500として安全なメッセージを返します。独自の業務エラーには完全なエラー定義または明示的な状態を指定してください。
+
 ### メッセージと言語：`core.i18n`
 
 パラメーター置換付きのメッセージ取得関数を作り、Core 内蔵メッセージや言語を取得・設定します。定数は内蔵言語一覧であり、アプリ翻訳の自動登録は行いません。
@@ -478,7 +520,9 @@ const message = core.i18n.createMessageGetter({
 // createMessageGetter 返回消息函数；如 message('welcome', { locale: 'zh-CN', params: { name: 'Alice' } }) 得到 '欢迎 Alice'。
 const greeting = await core.i18n.runWithLocale('en-US', async () => {
   await Promise.resolve()
-  return message('welcome', { params: { name: 'Alice' } })
+  return message('welcome', {
+    params: { name: 'Alice' }
+  })
 })
 // greeting：'Welcome Alice'；runWithLocale 返回回调的结果，此处等待 Promise 得到字符串。
 core.logger.info('Greeting prepared', { greeting })
@@ -500,7 +544,9 @@ const message = core.zodValidation.createPrefixedZodMessageGetter('core', key =>
     ? core.i18n.coreM('core_validationEmail', { locale: 'zh-CN' })
     : core.i18n.coreM('core_errorValidation', { locale: 'zh-CN' }))
 // 返回消息函数；message('validationEmail') 得到 '请输入有效的邮箱地址'。
-const parsed = z.object({ email: z.email() }).safeParse({ email: 'invalid' })
+const parsed = z.object({
+  email: z.email()
+}).safeParse({ email: 'invalid' })
 if (!parsed.success) {
   const errors = core.zodValidation.mapZodErrorToFormErrors(parsed.error, message)
   // errors：[{ field: 'email', message: '请输入有效的邮箱地址' }]。
@@ -617,10 +663,14 @@ import { AccessConditionSchema, core } from '@h-ai/core'
 
 core.access.normalizeClientIp('::ffff:198.51.100.23') // 198.51.100.23。
 const resolve = core.access.createClientIpResolver(['192.0.2.10']) // 返回 IP 解析函数，只信任这个代理。
-const request = new Request('https://example.test/api/orders', { headers: { 'x-forwarded-for': '198.51.100.23' } })
+const request = new Request('https://example.test/api/orders', {
+  headers: { 'x-forwarded-for': '198.51.100.23' }
+})
 // 第二参数必须来自真实 socket/可信平台；这里用测试地址模拟代理对端。
 const clientIp = resolve(request, '192.0.2.10') // '198.51.100.23'，读取受信代理的转发头。
-const check = core.access.createConditionCheck(AccessConditionSchema.parse({ allowIps: ['198.51.100.0/24'] }))
+const check = core.access.createConditionCheck(AccessConditionSchema.parse({
+  allowIps: ['198.51.100.0/24']
+}))
 // createConditionCheck 返回检查函数；check(clientIp) 得到 { allowed: true }。
 core.logger.info('Address checked', { allowed: check(clientIp).allowed })
 ```
@@ -632,7 +682,15 @@ import { core } from '@h-ai/core'
 
 // 可改为 loadPolicy({ file: './config/security/request-access.yml' }) 在启动时读独立文件。
 const policy = core.access.loadPolicy({
-  rules: [{ id: 'external-api', paths: ['/api/external/**'], methods: ['POST'], allowIps: ['192.0.2.0/24'], encryption: 'disabled' }],
+  rules: [
+    {
+      id: 'external-api',
+      paths: ['/api/external/**'],
+      methods: ['POST'],
+      allowIps: ['192.0.2.0/24'],
+      encryption: 'disabled'
+    }
+  ],
 })
 // policy.rules[0] 保留上方规则，并补 denyIps: []、windows: []、timezone: 'UTC'。
 const check = core.access.createRequestCheck(policy) // 返回请求检查函数，另带 encryption 方法和 requiresEncryption 属性。
@@ -702,7 +760,9 @@ core.object.omit(settings, ['port']) // { name: 'orders' }。
 core.object.keys(settings) // ['name', 'port']，元素类型为 'name' | 'port'。
 core.object.values(settings) // ['orders', 4000]。
 core.object.entries(settings) // [['name', 'orders'], ['port', 4000]]。
-core.object.fromEntries([['mode', 'local']]) // { mode: 'local' }。
+core.object.fromEntries([
+  ['mode', 'local']
+]) // { mode: 'local' }。
 ```
 
 deepClone は structuredClone で Date/Map/Set/循環など複製可能な値を扱い、関数など非対応値では例外です。deepMerge は通常オブジェクトのみ再帰結合し、配列・Date・集合・クラスは後の値で置換し、入力は変更しません。インスタンスの複製ではありません。
@@ -739,11 +799,17 @@ import { core } from '@h-ai/core'
 
 core.array.unique([1, 1, 2]) // [1, 2]。
 core.array.chunk([1, 2, 3], 2) // [[1, 2], [3]]。
-core.array.groupBy([{ role: 'admin' }, { role: 'user' }], item => item.role)
+core.array.groupBy([
+  { role: 'admin' },
+  { role: 'user' }
+], item => item.role)
 // => { admin: [{ role: 'admin' }], user: [{ role: 'user' }] }
 core.array.first([1, 2, 3]) // 1；空数组为 undefined。
 core.array.last([1, 2, 3]) // 3；空数组为 undefined。
-core.array.flatten([[1], [2, 3]]) // [1, 2, 3]，只展开一层。
+core.array.flatten([
+  [1],
+  [2, 3]
+]) // [1, 2, 3]，只展开一层。
 core.array.compact([0, null, 1, undefined]) // [0, 1]，保留 0/false/空字符串。
 core.array.shuffle([1, 2, 3]) // 如 [2, 3, 1]，次序随机；新数组不修改输入。
 core.array.intersection([1, 2], [2, 3]) // [2]。

package/README.md

@@ -93,7 +93,9 @@ core.logger.info('Application ready', { name: config.data.name }) // 返回 unde
 import { core } from '@h-ai/core'
 
 // 浏览器不读取 YAML；此处只设置日志，输出 warn 及以上级别。
-core.init({ logging: { level: 'warn' } }) // 返回 undefined；之后 info 日志被过滤。
+core.init({
+  logging: { level: 'warn' }
+}) // 返回 undefined；之后 info 日志被过滤。
 
 // 设置当前页面使用的默认消息语言。
 core.i18n.setGlobalLocale('zh-CN') // 返回 undefined；页面默认消息使用中文。
@@ -131,7 +133,9 @@ import { core } from '@h-ai/core'
 import { z } from 'zod'
 
 // 读取上方 config/app.yml；Schema 同时描述类型和校验规则。
-const AppSchema = z.object({ port: z.number().int().min(1).max(65535) })
+const AppSchema = z.object({
+  port: z.number().int().min(1).max(65535)
+})
 const loaded = core.config.load('app', './config/app.yml', AppSchema)
 if (!loaded.success)
   throw new Error(loaded.error.message, { cause: loaded.error })
@@ -230,11 +234,25 @@ import { core } from '@h-ai/core'
 import { z } from 'zod'
 
 // 用显式环境数据演示覆盖顺序、数值/布尔转换与字符串保留。
-const AppSchema = z.object({ port: z.number(), enabled: z.boolean(), label: z.string(), code: z.string() })
+const AppSchema = z.object({
+  port: z.number(),
+  enabled: z.boolean(),
+  label: z.string(),
+  code: z.string()
+})
 const resolved = core.config.resolve({
   name: 'app',
-  // eslint-disable-next-line no-template-curly-in-string -- 保留 YAML 中等待框架解析的字面表达式。
-  value: { port: '${PORT:3000}', enabled: '${ENABLED:false}', label: 'server-${PORT:3000}', code: '${APP_CODE:00123}' },
+
+  value: {
+    // eslint-disable-next-line no-template-curly-in-string -- 保留供配置解析器处理的字面占位符。
+    port: '${PORT:3000}',
+    // eslint-disable-next-line no-template-curly-in-string -- 保留供配置解析器处理的字面占位符。
+    enabled: '${ENABLED:false}',
+    // eslint-disable-next-line no-template-curly-in-string -- 保留供配置解析器处理的字面占位符。
+    label: 'server-${PORT:3000}',
+    // eslint-disable-next-line no-template-curly-in-string -- 保留供配置解析器处理的字面占位符。
+    code: '${APP_CODE:00123}'
+  },
   environment: { PORT: '4000', HAI_APP_PORT: '5000' },
   schema: AppSchema,
 })
@@ -265,9 +283,18 @@ core.logger.info('Config resolved', { settings: validated.data })
 import { core } from '@h-ai/core'
 
 // 配置生成器把普通对象转成 HAI_APP_PORT 等变量；数组保留为 JSON。
-const values = core.config.toEnv({ prefix: 'HAI_APP', value: { port: 3000, tags: ['local'] } })
+const values = core.config.toEnv({
+  prefix: 'HAI_APP',
+  value: {
+    port: 3000,
+    tags: ['local']
+  }
+})
 // values：{ HAI_APP_PORT: '3000', HAI_APP_TAGS: '["local"]' }。
-const merged = core.config.mergeEnv([values, { HAI_APP_PORT: '4000' }])
+const merged = core.config.mergeEnv([
+  values,
+  { HAI_APP_PORT: '4000' }
+])
 // merged：{ HAI_APP_PORT: '4000', HAI_APP_TAGS: '["local"]' }。
 const text = core.config.stringifyEnv(merged) // 编码为可写入 .env 的文本。
 // text 含以下两行，每行以换行符结尾：
@@ -295,7 +322,9 @@ core.logger.trace('Processing detail', { step: 1 })
 core.logger.debug('Read started')
 core.logger.info('Order created', { orderId: 'order-1' })
 core.logger.warn('Retry scheduled')
-core.logger.error('Operation failed', { error: new Error('Example failure') })
+core.logger.error('Operation failed', {
+  error: new Error('Example failure')
+})
 core.logger.fatal('Service cannot continue')
 // 六次日志调用均返回 undefined；分别输出对应级别、上面的消息及所传字段。
 // 例如 info 日志的消息为 'Order created'，字段 orderId 为 'order-1'。
@@ -307,10 +336,16 @@ core.logger.fatal('Service cannot continue')
 import { core } from '@h-ai/core'
 
 // 全局配置可作用于已经创建的 Logger；redact 补充业务隐私字段。
-core.logger.configure({ level: 'info', format: 'json', redact: ['customer.email'] }) // 返回 undefined；后续日志按此配置输出。
+core.logger.configure({
+  level: 'info',
+  format: 'json',
+  redact: ['customer.email']
+}) // 返回 undefined；后续日志按此配置输出。
 const orders = core.logger.create({ name: 'orders' }) // 返回 Logger 对象，可调用 info/warn 等方法。
 const request = core.logger.child({ requestId: 'request-1' }) // 返回带固定 requestId 的 Logger。
-orders.info('Order created', { customer: { email: 'user@example.com' } }) // 返回 undefined；输出中 customer.email 为 '[REDACTED]'。
+orders.info('Order created', {
+  customer: { email: 'user@example.com' }
+}) // 返回 undefined；输出中 customer.email 为 '[REDACTED]'。
 request.warn('Request needs attention') // 返回 undefined；输出中 requestId 为 'request-1'。
 core.logger.getLevel() // 'info'。
 ```
@@ -370,7 +405,10 @@ core.sanitize.sanitizeSensitiveValue('example-only', 'password') // '[REDACTED]'
 const safe = core.sanitize.sanitizeSensitiveFields({ password: 'example-only', email: 'user@example.com' })
 // safe：{ password: '[REDACTED]', email: 'user@example.com' }，原对象不变。
 // 默认仅遮蔽凭据；额外业务隐私可在已处理凭据的副本上继续清理。
-core.sanitize.sanitizeSensitiveFields(safe, { matcher: ['email'], replacement: '***' })
+core.sanitize.sanitizeSensitiveFields(safe, {
+  matcher: ['email'],
+  replacement: '***'
+})
 // => { password: '[REDACTED]', email: '***' }
 core.sanitize.sanitizeUrl('https://user:example-only@example.com/?token=example-only')
 // => 'https://[REDACTED]:[REDACTED]@example.com/?token=[REDACTED]'
@@ -449,6 +487,10 @@ if (!failed.success)
 
 以上常量来自 `HaiConfigError`；跨模块通用错误使用 `HaiCommonError`。
 
+通用错误 `HaiCommonError.RATE_LIMIT_EXCEEDED` 对应 `hai:common:203` / HTTP 429；Kit 的快捷响应和守卫同样使用通用错误码。
+
+HTTP/UI 边界只对明确的有效 4xx 状态公开业务提示；错误缺少 `httpStatus` 或状态非法时按 500 返回安全提示。手写业务错误须提供完整错误定义或显式状态，不能依赖缺省状态展示原文。
+
 ### 消息与语言：`core.i18n`
 
 为业务字典创建带参数替换的消息获取器，也可取得 Core 内置消息和当前语言。常量列出框架内置语言，不会自动为应用注册翻译。
@@ -478,7 +520,9 @@ const message = core.i18n.createMessageGetter({
 // createMessageGetter 返回消息函数；如 message('welcome', { locale: 'zh-CN', params: { name: 'Alice' } }) 得到 '欢迎 Alice'。
 const greeting = await core.i18n.runWithLocale('en-US', async () => {
   await Promise.resolve()
-  return message('welcome', { params: { name: 'Alice' } })
+  return message('welcome', {
+    params: { name: 'Alice' }
+  })
 })
 // greeting：'Welcome Alice'；runWithLocale 返回回调的结果，此处等待 Promise 得到字符串。
 core.logger.info('Greeting prepared', { greeting })
@@ -500,7 +544,9 @@ const message = core.zodValidation.createPrefixedZodMessageGetter('core', key =>
     ? core.i18n.coreM('core_validationEmail', { locale: 'zh-CN' })
     : core.i18n.coreM('core_errorValidation', { locale: 'zh-CN' }))
 // 返回消息函数；message('validationEmail') 得到 '请输入有效的邮箱地址'。
-const parsed = z.object({ email: z.email() }).safeParse({ email: 'invalid' })
+const parsed = z.object({
+  email: z.email()
+}).safeParse({ email: 'invalid' })
 if (!parsed.success) {
   const errors = core.zodValidation.mapZodErrorToFormErrors(parsed.error, message)
   // errors：[{ field: 'email', message: '请输入有效的邮箱地址' }]。
@@ -617,10 +663,14 @@ import { AccessConditionSchema, core } from '@h-ai/core'
 
 core.access.normalizeClientIp('::ffff:198.51.100.23') // 198.51.100.23。
 const resolve = core.access.createClientIpResolver(['192.0.2.10']) // 返回 IP 解析函数，只信任这个代理。
-const request = new Request('https://example.test/api/orders', { headers: { 'x-forwarded-for': '198.51.100.23' } })
+const request = new Request('https://example.test/api/orders', {
+  headers: { 'x-forwarded-for': '198.51.100.23' }
+})
 // 第二参数必须来自真实 socket/可信平台；这里用测试地址模拟代理对端。
 const clientIp = resolve(request, '192.0.2.10') // '198.51.100.23'，读取受信代理的转发头。
-const check = core.access.createConditionCheck(AccessConditionSchema.parse({ allowIps: ['198.51.100.0/24'] }))
+const check = core.access.createConditionCheck(AccessConditionSchema.parse({
+  allowIps: ['198.51.100.0/24']
+}))
 // createConditionCheck 返回检查函数；check(clientIp) 得到 { allowed: true }。
 core.logger.info('Address checked', { allowed: check(clientIp).allowed })
 ```
@@ -632,7 +682,15 @@ import { core } from '@h-ai/core'
 
 // 可改为 loadPolicy({ file: './config/security/request-access.yml' }) 在启动时读独立文件。
 const policy = core.access.loadPolicy({
-  rules: [{ id: 'external-api', paths: ['/api/external/**'], methods: ['POST'], allowIps: ['192.0.2.0/24'], encryption: 'disabled' }],
+  rules: [
+    {
+      id: 'external-api',
+      paths: ['/api/external/**'],
+      methods: ['POST'],
+      allowIps: ['192.0.2.0/24'],
+      encryption: 'disabled'
+    }
+  ],
 })
 // policy.rules[0] 保留上方规则，并补 denyIps: []、windows: []、timezone: 'UTC'。
 const check = core.access.createRequestCheck(policy) // 返回请求检查函数，另带 encryption 方法和 requiresEncryption 属性。
@@ -702,7 +760,9 @@ core.object.omit(settings, ['port']) // { name: 'orders' }。
 core.object.keys(settings) // ['name', 'port']，元素类型为 'name' | 'port'。
 core.object.values(settings) // ['orders', 4000]。
 core.object.entries(settings) // [['name', 'orders'], ['port', 4000]]。
-core.object.fromEntries([['mode', 'local']]) // { mode: 'local' }。
+core.object.fromEntries([
+  ['mode', 'local']
+]) // { mode: 'local' }。
 ```
 
 deepClone 使用 structuredClone，支持 Date/Map/Set/循环等可克隆值；不可克隆的函数等会抛错。deepMerge 只递归普通对象，数组、Date、集合和类实例由后值覆盖，不修改输入；不把它当作实例克隆。
@@ -739,11 +799,17 @@ import { core } from '@h-ai/core'
 
 core.array.unique([1, 1, 2]) // [1, 2]。
 core.array.chunk([1, 2, 3], 2) // [[1, 2], [3]]。
-core.array.groupBy([{ role: 'admin' }, { role: 'user' }], item => item.role)
+core.array.groupBy([
+  { role: 'admin' },
+  { role: 'user' }
+], item => item.role)
 // => { admin: [{ role: 'admin' }], user: [{ role: 'user' }] }
 core.array.first([1, 2, 3]) // 1；空数组为 undefined。
 core.array.last([1, 2, 3]) // 3；空数组为 undefined。
-core.array.flatten([[1], [2, 3]]) // [1, 2, 3]，只展开一层。
+core.array.flatten([
+  [1],
+  [2, 3]
+]) // [1, 2, 3]，只展开一层。
 core.array.compact([0, null, 1, undefined]) // [0, 1]，保留 0/false/空字符串。
 core.array.shuffle([1, 2, 3]) // 如 [2, 3, 1]，次序随机；新数组不修改输入。
 core.array.intersection([1, 2], [2, 3]) // [2]。

package/dist/browser.d.ts

@@ -1,5 +1,5 @@
-import { B as BrowserCoreFunctions } from './core-types-n2KjBtto.js';
-export { A as AccessCondition, a as AccessConditionSchema, b as AccessDecision, c as AccessFunctions, d as ArrayFn, e as AsyncFn, f as BrowserConfigFn, C as ConfigFn, g as CoreConfig, h as CoreConfigSchema, i as CoreFunctions, j as CoreLogger, k as CoreOptions, l as CreateNotInitializedKitFn, E as Env, m as EnvSchema, n as ErrorFn, o as ErrorInfo, p as ErrorInfoValue, H as HaiCommonError, q as HaiConfigError, r as HaiError, s as HaiErrorDef, t as HaiResult, I as I18nFn, u as IdFn, v as InterpolationParams, L as Locale, w as LocaleInfo, x as LocaleMessages, y as LogContext, z as LogFormat, D as LogFormatSchema, F as LogLevel, G as LogLevelSchema, J as LogObserver, K as LogRecord, M as Logger, N as LoggerFunctions, O as LoggerOptions, P as LoggingConfig, Q as LoggingConfigSchema, R as MatchHandlers, S as MessageDictionary, T as MessageOptions, U as ModuleFn, V as ModuleRuntime, W as NodeCoreFunctions, X as NotInitializedKit, Y as ObjectFn, Z as PaginatedResult, _ as PaginationOptions, $ as PaginationOptionsInput, a0 as RequestAccessCheck, a1 as RequestAccessConfigInput, a2 as RequestAccessConfigSchema, a3 as RequestAccessPolicy, a4 as RequestAccessPolicySchema, a5 as RequestContext, a6 as RequestEncryptionMode, a7 as RuntimeStep, a8 as SanitizeFn, a9 as SanitizeSensitiveFieldsOptions, aa as SensitiveKeyMatcher, ab as StringFn, ac as TimeFn, ad as TrustedProxies, ae as TrustedProxiesSchema, af as TypeUtilFn, ag as ValidationFormError, ah as WatchCallback, ai as ZodMessageGetter, aj as ZodValidationFn, ak as ZodValidationMessageKey, al as err, am as ok } from './core-types-n2KjBtto.js';
+import { B as BrowserCoreFunctions } from './core-types-Dp3Vr2uI.js';
+export { A as AccessCondition, a as AccessConditionSchema, b as AccessDecision, c as AccessFunctions, d as ArrayFn, e as AsyncFn, f as BrowserConfigFn, C as ConfigFn, g as CoreConfig, h as CoreConfigSchema, i as CoreFunctions, j as CoreLogger, k as CoreOptions, l as CreateNotInitializedKitFn, E as Env, m as EnvSchema, n as ErrorFn, o as ErrorInfo, p as ErrorInfoValue, H as HaiCommonError, q as HaiConfigError, r as HaiError, s as HaiErrorDef, t as HaiResult, I as I18nFn, u as IdFn, v as InterpolationParams, L as Locale, w as LocaleInfo, x as LocaleMessages, y as LogContext, z as LogFormat, D as LogFormatSchema, F as LogLevel, G as LogLevelSchema, J as LogObserver, K as LogRecord, M as Logger, N as LoggerFunctions, O as LoggerOptions, P as LoggingConfig, Q as LoggingConfigSchema, R as MatchHandlers, S as MessageDictionary, T as MessageOptions, U as ModuleFn, V as ModuleRuntime, W as NodeCoreFunctions, X as NotInitializedKit, Y as ObjectFn, Z as PaginatedResult, _ as PaginationOptions, $ as PaginationOptionsInput, a0 as RequestAccessCheck, a1 as RequestAccessConfigInput, a2 as RequestAccessConfigSchema, a3 as RequestAccessPolicy, a4 as RequestAccessPolicySchema, a5 as RequestContext, a6 as RequestEncryptionMode, a7 as RuntimeStep, a8 as SanitizeFn, a9 as SanitizeSensitiveFieldsOptions, aa as SensitiveKeyMatcher, ab as StringFn, ac as TimeFn, ad as TrustedProxies, ae as TrustedProxiesSchema, af as TypeUtilFn, ag as ValidationFormError, ah as WatchCallback, ai as ZodMessageGetter, aj as ZodValidationFn, ak as ZodValidationMessageKey, al as err, am as ok } from './core-types-Dp3Vr2uI.js';
 import 'zod';
 
 /**