@h-ai/core 1.0.0-beta.1 → 1.0.0-beta.11

package/dist/{core-types-_JqVAGGT.d.ts → core-types-DM_AiIaS.d.ts}

@@ -330,7 +330,88 @@ declare const zodValidation: {
  * if (!result.success) result.error.message
  * ```
  */
-declare const config$1: ConfigFn;
+declare const config$1: {
+    loadEnvFiles(_options: {
+        mode: string;
+        envDir?: string;
+    }): HaiResult<Record<string, string>>;
+    load<T>(_name: string, _filePath: string, _schema?: ZodType<T>): HaiResult<T>;
+    validate<T>(_name: string, _schema: 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;
+};
+
+/** 通用环境配置：来源合并、结构覆盖与无损 dotenv 编解码，不依赖业务模块。 */
+
+/**
+ * 单个环境来源中的字面变量，undefined 表示未设置。
+ * @example 模块内部上下文
+ * ```ts
+ * const values: Environment = { HAI_APP_NAME: 'Example' }
+ * ```
+ */
+type Environment = Record<string, string | undefined>;
+/**
+ * 从低到高合并来源；高来源父项删除旧细项，同来源始终先父后子。
+ * @example 模块内部上下文
+ * ```ts
+ * const values = mergeEnv([{ HAI_APP_NAME: 'base' }, { HAI_APP_NAME: 'test' }])
+ * ```
+ */
+declare function mergeEnv(layers: readonly Environment[]): Record<string, string>;
+/**
+ * dotenv 使用 Node 字面规则；补齐生成器双引号的 JSON 转义，拒绝同文件重复键。
+ * @example 模块内部上下文
+ * ```ts
+ * const values = parseEnvironment('HAI_APP_NAME=Example\n')
+ * ```
+ */
+declare function parseEnvironment(text: string): Record<string, string>;
+/**
+ * 所有值均按字面量编码；排序让模块 JSON 位于其细项之前。
+ * @example 模块内部上下文
+ * ```ts
+ * const text = stringifyEnv({ HAI_APP_NAME: 'Example' })
+ * ```
+ */
+declare function stringifyEnv(values: Record<string, string>, options?: {
+    target?: 'node' | 'compose';
+}): string;
+/**
+ * 在给定结构上解析环境变量；父对象提供基础值，具体路径继续覆盖。
+ * @example 模块内部上下文
+ * ```ts
+ * const result = resolveEnvironment({ name: 'app', value: { name: 'Example' }, environment: { HAI_APP_NAME: 'Test' } })
+ * ```
+ */
+declare function resolveEnvironment(options: {
+    name: string;
+    value: unknown;
+    environment?: Environment;
+    schema?: ZodType;
+    shape?: Readonly<Record<string, unknown>>;
+    missing?: 'error' | 'empty';
+}, literal?: boolean): HaiResult<unknown>;
+/**
+ * 默认展开对象，数组与动态键字典保留 JSON；不做模块名称判断。
+ * @example 模块内部上下文
+ * ```ts
+ * const values = toEnv({ prefix: 'HAI_APP', value: { name: 'Example', tags: ['demo'] } })
+ * ```
+ */
+declare function toEnv(options: {
+    prefix: string;
+    value: unknown;
+    schema?: ZodType;
+    shape?: Readonly<Record<string, unknown>>;
+}): Record<string, string>;
 
 /**
  * 配置管理对象。
@@ -341,10 +422,67 @@ declare const config$1: ConfigFn;
  * ```
  */
 declare const config: {
+    /**
+     * 合并从低到高的环境来源；高来源父项替换旧节点，同来源细项覆盖父 JSON。
+     * @param layers - 按优先级排列的字面变量。
+     * @returns 合并后的变量，可能含秘密。
+     * @example
+     * ```ts
+     * import { core } from '@h-ai/core'
+     * const value = core.config.mergeEnv([{ HAI_APP_NAME: 'base' }, { HAI_APP_NAME: 'test' }])
+     * ```
+     */
+    mergeEnv: typeof mergeEnv;
+    /**
+     * 解析 dotenv 字面文本，拒绝重复键，不执行 shell 或变量展开。
+     * @param text - dotenv 文本，可能包含秘密。
+     * @returns 字面变量；重复键抛出不含变量值的错误。
+     * @example
+     * ```ts
+     * import { core } from '@h-ai/core'
+     * const value = core.config.parseEnv('HAI_APP_NAME=Example\n')
+     * ```
+     */
+    parseEnv: typeof parseEnvironment;
+    /**
+     * 无损编码 dotenv，父变量排在细项前；含秘密时只能写入受保护文件。
+     * @param values - 字面变量，不进行脱敏。
+     * @param options - 输出语法目标，默认 Node dotenv。
+     * @param options.target - Compose 目标同时处理其美元符号插值规则。
+     * @returns dotenv 文本；非法变量名抛错。
+     * @example
+     * ```ts
+     * import { core } from '@h-ai/core'
+     * const value = core.config.stringifyEnv({ HAI_APP_NAME: 'Example' })
+     * ```
+     */
+    stringifyEnv: typeof stringifyEnv;
+    /**
+     * 按已有结构或 Schema 解析父 JSON 和细项，不修改缓存或进程环境。
+     * @param options - 配置名、原始结构、变量、可选 Schema 和缺失插值规则。
+     * @returns 解析结果；调用方仍须执行最终 Schema 校验。
+     * @example
+     * ```ts
+     * import { core } from '@h-ai/core'
+     * const value = core.config.resolve({ name: 'app', value: { name: 'Example' }, environment: { HAI_APP_NAME: 'Test' } })
+     * ```
+     */
+    resolve: (options: Parameters<typeof resolveEnvironment>[0]) => HaiResult<unknown>;
+    /**
+     * 默认将对象展开为细项；数组、动态字典和空对象保留 JSON。
+     * @param options - 完整变量前缀、配置值和可选 Schema。
+     * @returns 字面环境变量，不脱敏；非法名称抛错。
+     * @example
+     * ```ts
+     * import { core } from '@h-ai/core'
+     * const value = core.config.toEnv({ prefix: 'HAI_APP', value: { name: 'Example', tags: ['demo'] } })
+     * ```
+     */
+    toEnv: typeof toEnv;
     /**
      * 读取 dotenv 文件并按统一顺序合并，不修改进程环境。
      *
-     * 优先级：已有进程环境 > .env.local > .env.<mode> > .env。
+     * 优先级：已有进程环境 > .env.<mode>.local > .env.local > .env.<mode> > .env。
      * development/production 分别映射到 dev/prod；不存在的文件跳过。
      * 返回值可能包含私有配置，仅在 Node 启动/构建边界注入，不下发浏览器。
      * @param options - 文件所在目录及环境模式
@@ -486,7 +624,8 @@ declare const config: {
     /**
      * 监听配置文件变更并自动重载。
      *
-     * 文件变更时自动重新加载并调用回调。配置未加载时立即回调 NOT_LOADED 错误。
+     * 普通写入、原子替换及删除重建均触发重载；失败保留最近成功的缓存并通知错误。
+     * 配置未加载时立即回调 NOT_LOADED 错误。
      *
      * @param name - 配置名称
      * @param callback - 配置变更回调，接收新配置或错误
@@ -695,7 +834,7 @@ declare const i18n: {
     getGlobalLocale: typeof getGlobalLocale;
     runWithLocale: typeof runWithLocale;
     createMessageGetter: typeof createMessageGetter;
-    coreM: (key: "$schema" | "core_errorUnknown" | "core_errorNetwork" | "core_errorTimeout" | "core_errorNotFound" | "core_errorUnauthorized" | "core_errorForbidden" | "core_errorValidation" | "core_errorInternal" | "core_actionConfirm" | "core_actionCancel" | "core_actionSave" | "core_actionDelete" | "core_actionEdit" | "core_actionCreate" | "core_actionUpdate" | "core_actionSearch" | "core_actionReset" | "core_actionSubmit" | "core_actionLoading" | "core_actionRetry" | "core_statusSuccess" | "core_statusFailed" | "core_statusPending" | "core_statusProcessing" | "core_statusCompleted" | "core_statusCancelled" | "core_validationRequired" | "core_validationMinLength" | "core_validationMaxLength" | "core_validationEmail" | "core_validationUrl" | "core_validationNumber" | "core_validationInteger" | "core_validationPositive" | "core_validationPattern" | "core_timeJustNow" | "core_timeSecondsAgo" | "core_timeMinutesAgo" | "core_timeHoursAgo" | "core_timeDaysAgo" | "core_timeWeeksAgo" | "core_timeMonthsAgo" | "core_timeYearsAgo" | "core_browserFeatureUnsupported" | "core_configEnvVarMissing" | "core_configFileNotExist" | "core_configParseFailed" | "core_configValidationFailed" | "core_configNotLoaded" | "core_configUnsupportedInBrowser" | "core_cryptoRandomUnavailable" | "core_runtimeStartFailed" | "core_runtimeCloseFailed" | "core_runtimeEnvMissing" | "core_runtimeConfigInvalid" | "core_runtimeConfigProblem" | "core_runtimeErrorCode" | "core_requestAccessDenied", options?: MessageOptions) => string;
+    coreM: (key: "$schema" | "core_errorUnknown" | "core_errorNetwork" | "core_errorTimeout" | "core_errorNotFound" | "core_errorUnauthorized" | "core_errorForbidden" | "core_errorValidation" | "core_errorInternal" | "core_actionConfirm" | "core_actionCancel" | "core_actionSave" | "core_actionDelete" | "core_actionEdit" | "core_actionCreate" | "core_actionUpdate" | "core_actionSearch" | "core_actionReset" | "core_actionSubmit" | "core_actionLoading" | "core_actionRetry" | "core_statusSuccess" | "core_statusFailed" | "core_statusPending" | "core_statusProcessing" | "core_statusCompleted" | "core_statusCancelled" | "core_validationRequired" | "core_validationMinLength" | "core_validationMaxLength" | "core_validationEmail" | "core_validationUrl" | "core_validationNumber" | "core_validationInteger" | "core_validationPositive" | "core_validationPattern" | "core_timeJustNow" | "core_timeSecondsAgo" | "core_timeMinutesAgo" | "core_timeHoursAgo" | "core_timeDaysAgo" | "core_timeWeeksAgo" | "core_timeMonthsAgo" | "core_timeYearsAgo" | "core_browserFeatureUnsupported" | "core_configEnvVarMissing" | "core_configFileNotExist" | "core_configParseFailed" | "core_configValidationFailed" | "core_configNotLoaded" | "core_configUnsupportedInBrowser" | "core_cryptoRandomUnavailable" | "core_parallelConcurrencyInvalid" | "core_runtimeStartFailed" | "core_runtimeCloseFailed" | "core_runtimeEnvMissing" | "core_runtimeConfigInvalid" | "core_runtimeConfigProblem" | "core_runtimeErrorCode" | "core_requestAccessDenied", options?: MessageOptions) => string;
 };
 
 /**
@@ -719,7 +858,7 @@ declare function unique<T>(arr: T[]): T[];
  * @param arr - 输入数组
  * @param fn - 分组键生成函数
  * @returns 分组结果对象
- * @remarks 当数组为空时返回空对象。
+ * @remarks 当数组为空时返回空对象；原型同名键也作为独立的自有分组。
  *
  * @example
  * ```ts
@@ -902,9 +1041,10 @@ declare function retry<T>(fn: () => Promise<T>, options?: {
  *
  * @param items - 输入列表
  * @param fn - 处理函数
- * @param concurrency - 最大并发数
+ * @param concurrency - 最大并发数，必须为大于 0 的安全整数
  * @returns 处理结果列表
  * @remarks 结果顺序与输入顺序一致。
+ * @throws 并发数非法时拒绝为 RangeError，不执行任何任务；任务异常原样传播。
  *
  * @example
  * ```ts
@@ -938,7 +1078,7 @@ declare function serial<T, R>(items: T[], fn: (item: T, index: number) => Promis
  * const onInput = async.debounce(() => {}, 300)
  * ```
  */
-declare function debounce<T extends (...args: unknown[]) => unknown>(fn: T, ms: number): (...args: Parameters<T>) => void;
+declare function debounce<Args extends unknown[]>(fn: (...args: Args) => unknown, ms: number): (...args: Args) => void;
 /**
  * 节流。
  *
@@ -952,7 +1092,7 @@ declare function debounce<T extends (...args: unknown[]) => unknown>(fn: T, ms:
  * const onScroll = async.throttle(() => {}, 200)
  * ```
  */
-declare function throttle<T extends (...args: unknown[]) => unknown>(fn: T, ms: number): (...args: Parameters<T>) => void;
+declare function throttle<Args extends unknown[]>(fn: (...args: Args) => unknown, ms: number): (...args: Args) => void;
 /**
  * 异步操作工具对象。
  * @example
@@ -1016,7 +1156,7 @@ declare function deepClone<T>(obj: T): T;
  * 深度合并多个对象。
  * @param objects - 需要合并的对象列表
  * @returns 合并后的新对象
- * @remarks 仅合并纯对象字段，数组会被直接覆盖。
+ * @remarks 仅递归合并普通对象字段；数组、Date、Map、Set 和类实例由后值直接覆盖，不修改输入。
  *
  * @example
  * ```ts
@@ -1174,7 +1314,7 @@ declare function sanitizeUrl(url: string, options?: SanitizeSensitiveFieldsOptio
  * @param key - 当前字段名；根节点传 null
  * @param options - 脱敏选项
  * @param cache - 循环引用 / 重复引用缓存
- * @returns 递归脱敏后的值；普通对象循环保留，Error 规范化为有界诊断树，原值不被修改。
+ * @returns 脱敏数据副本；类实例不保留原型和方法，普通对象循环保留，Error 规范化为有界诊断树，原值不被修改。
  * @example
  * ```ts
  * import { core } from '@h-ai/core'
@@ -1189,7 +1329,8 @@ declare function sanitizeSensitiveValue(value: unknown, key: string | null, opti
  *
  * @param value - 原始对象/数组/值
  * @param options - 脱敏选项
- * @returns 脱敏后的新值
+ * 类实例只复制自有可枚举数据属性；不保留原型、访问器和 toJSON。Date 转 ISO 字符串，URL 转脱敏字符串。
+ * @returns 用于诊断的脱敏副本，不作为原类实例使用。
  * @example
  * ```ts
  * import { core } from '@h-ai/core'
@@ -2194,6 +2335,8 @@ interface CoreOptions {
      * ```
      */
     configDir?: string;
+    /** 宿主显式提供模块 Schema，供扫描时识别可选字段和环境变量类型；Core 不注册业务模块。 */
+    configSchemas?: Readonly<Record<string, z.ZodType>>;
     /** 是否启用配置文件监听（默认 false） */
     watchConfig?: boolean;
 }

package/dist/node.d.ts

@@ -1,5 +1,5 @@
-import { W as NodeCoreFunctions } from './core-types-_JqVAGGT.js';
-export { A as AccessCondition, a as AccessConditionSchema, b as AccessDecision, c as AccessFunctions, d as ArrayFn, e as AsyncFn, f as BrowserConfigFn, B as BrowserCoreFunctions, 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, 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-_JqVAGGT.js';
+import { W as NodeCoreFunctions } from './core-types-DM_AiIaS.js';
+export { A as AccessCondition, a as AccessConditionSchema, b as AccessDecision, c as AccessFunctions, d as ArrayFn, e as AsyncFn, f as BrowserConfigFn, B as BrowserCoreFunctions, 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, 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-DM_AiIaS.js';
 import 'zod';
 
 /**