@h-ai/core 0.1.0-alpha.65 → 0.1.0-alpha.67
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.en.md +30 -26
- package/README.ja.md +30 -26
- package/README.md +31 -27
- package/package.json +1 -1
package/README.en.md
CHANGED
|
@@ -4,9 +4,11 @@
|
|
|
4
4
|
|
|
5
5
|
[Framework home](../../README.en.md)
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
## Introduction
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
The core of hai Agent Framework: shared utilities, types, configuration management, and logging.
|
|
10
|
+
|
|
11
|
+
## Core features
|
|
10
12
|
|
|
11
13
|
- **HaiResult types**: functional error handling (`ok` / `err`) with a shared result format across modules.
|
|
12
14
|
- **Unified logging**: pino on Node.js and loglevel in browsers, with the same API.
|
|
@@ -18,9 +20,11 @@
|
|
|
18
20
|
- **Module utilities**: NotInitializedKit proxies and shared lifecycle infrastructure.
|
|
19
21
|
- **Utility library**: type checks and object / string / array / async / time operations.
|
|
20
22
|
|
|
21
|
-
##
|
|
23
|
+
## Getting started
|
|
24
|
+
|
|
25
|
+
### Quick start
|
|
22
26
|
|
|
23
|
-
|
|
27
|
+
#### Node.js environment
|
|
24
28
|
|
|
25
29
|
```typescript
|
|
26
30
|
import { core } from '@h-ai/core'
|
|
@@ -72,7 +76,7 @@ core.time.formatDate(new Date(), 'YYYY-MM-DD HH:mm:ss')
|
|
|
72
76
|
core.typeUtils.isDefined(value)
|
|
73
77
|
```
|
|
74
78
|
|
|
75
|
-
|
|
79
|
+
#### Browser environment
|
|
76
80
|
|
|
77
81
|
```typescript
|
|
78
82
|
import { core } from '@h-ai/core'
|
|
@@ -95,13 +99,13 @@ The browser retains the `core.config` API shape for type compatibility, but does
|
|
|
95
99
|
- `watch()` immediately calls its callback with the same error and returns a safe no-op unsubscribe function.
|
|
96
100
|
- Read configuration on the server and deliver it through an API, or use `core.init({ logging })` only to configure browser logging.
|
|
97
101
|
|
|
98
|
-
|
|
102
|
+
### Detailed API
|
|
99
103
|
|
|
100
|
-
|
|
104
|
+
#### Logging (Logger)
|
|
101
105
|
|
|
102
106
|
`core.logger` is both the default Logger instance and the shared entry point for logger management.
|
|
103
107
|
|
|
104
|
-
|
|
108
|
+
##### Write logs
|
|
105
109
|
|
|
106
110
|
Six levels: `trace` / `debug` / `info` / `warn` / `error` / `fatal`.
|
|
107
111
|
|
|
@@ -111,7 +115,7 @@ core.logger.error('Failed to connect', { error })
|
|
|
111
115
|
core.logger.debug('Processing item', { id, step: 'validation' })
|
|
112
116
|
```
|
|
113
117
|
|
|
114
|
-
|
|
118
|
+
##### Create a module logger
|
|
115
119
|
|
|
116
120
|
```typescript
|
|
117
121
|
// 独立名称空间,适合模块内全局使用
|
|
@@ -119,7 +123,7 @@ const logger = core.logger.create({ name: 'payment' })
|
|
|
119
123
|
logger.info('Payment processed')
|
|
120
124
|
```
|
|
121
125
|
|
|
122
|
-
|
|
126
|
+
##### Child loggers
|
|
123
127
|
|
|
124
128
|
```typescript
|
|
125
129
|
// 携带固定上下文,每条日志自动附带这些字段
|
|
@@ -135,7 +139,7 @@ opLogger.error('Login failed', { reason: 'invalid_password' })
|
|
|
135
139
|
|
|
136
140
|
> **Typical usage**: create `reqLogger` at the request entry, pass it to the service layer, and add operation context with `child`. Logs then include the complete request context.
|
|
137
141
|
|
|
138
|
-
|
|
142
|
+
##### Logger management
|
|
139
143
|
|
|
140
144
|
```typescript
|
|
141
145
|
// 配置输出格式和级别(Node.js / Browser)
|
|
@@ -156,7 +160,7 @@ Browser logs still use the DevTools console: `pretty` prints readable messages w
|
|
|
156
160
|
|
|
157
161
|
`core.logger` redacts log context by default: credentials such as `password`, `token`, `secret`, `privateKey`, and `apiV3Key` become `[REDACTED]`. Fields such as `url` / `baseUrl` / `endpoint` mask only embedded usernames/passwords. Email addresses and phone numbers are not masked by default.
|
|
158
162
|
|
|
159
|
-
|
|
163
|
+
##### Log level conventions
|
|
160
164
|
|
|
161
165
|
| Level | Use case |
|
|
162
166
|
| ------- | --------------------------------------------------- |
|
|
@@ -167,7 +171,7 @@ Browser logs still use the DevTools console: `pretty` prints readable messages w
|
|
|
167
171
|
| `error` | Operation failures requiring investigation |
|
|
168
172
|
| `fatal` | Fatal errors preventing continued service |
|
|
169
173
|
|
|
170
|
-
|
|
174
|
+
#### Internationalization (i18n)
|
|
171
175
|
|
|
172
176
|
```typescript
|
|
173
177
|
// 设置全局语言(所有 getMessage 函数自动响应)
|
|
@@ -191,7 +195,7 @@ core.i18n.DEFAULT_LOCALES // [{ code: 'zh-CN', label: '简体中文' }, { code:
|
|
|
191
195
|
core.i18n.DEFAULT_LOCALE // 'zh-CN'
|
|
192
196
|
```
|
|
193
197
|
|
|
194
|
-
|
|
198
|
+
#### Redaction utilities
|
|
195
199
|
|
|
196
200
|
`core.sanitize.sanitizeSensitiveFields()` recursively redacts objects and arrays. By default it handles password, token, secret, privateKey, apiV3Key, and similar credentials, and masks embedded credentials in `url` / `baseUrl` / `endpoint`. Modules can supply custom matchers.
|
|
197
201
|
|
|
@@ -211,7 +215,7 @@ core.sanitize.sanitizeSensitiveFields({ email: 'user@example.com' }, {
|
|
|
211
215
|
// => { email: '***' }
|
|
212
216
|
```
|
|
213
217
|
|
|
214
|
-
|
|
218
|
+
#### Zod validation error localization
|
|
215
219
|
|
|
216
220
|
`core.zodValidation` converts Zod `SafeParseError` / `ZodError` into flat form errors and maps Zod's
|
|
217
221
|
default English messages to the caller's own localized messages.
|
|
@@ -272,7 +276,7 @@ if (!result.success) {
|
|
|
272
276
|
}
|
|
273
277
|
```
|
|
274
278
|
|
|
275
|
-
|
|
279
|
+
#### Configuration management (Node.js only)
|
|
276
280
|
|
|
277
281
|
> Browsers have no filesystem access. `core.config` offers placeholder APIs only: file-related methods return `SERVICE_UNAVAILABLE` and do not load YAML.
|
|
278
282
|
|
|
@@ -327,7 +331,7 @@ core.config.clear('app') // 清除单个
|
|
|
327
331
|
core.config.clear() // 清除全部
|
|
328
332
|
```
|
|
329
333
|
|
|
330
|
-
|
|
334
|
+
##### Dotenv files and environment modes
|
|
331
335
|
|
|
332
336
|
Node-only `core.config.loadEnvFiles({ mode, envDir })` returns HaiResult and merges `.env` → `.env.<mode>` → `.env.local`, with existing process variables taking priority. development/production map to dev/prod; missing files are skipped. It does not mutate the process: check success before assigning. Track public environment files and `.env.example`; ignore private `.env.local`. core.init does not load dotenv. Browser calls return SERVICE_UNAVAILABLE.
|
|
333
337
|
|
|
@@ -339,7 +343,7 @@ Object.assign(process.env, env.data)
|
|
|
339
343
|
core.init({ configDir: './config' })
|
|
340
344
|
```
|
|
341
345
|
|
|
342
|
-
|
|
346
|
+
##### Environment variable mapping and interpolation
|
|
343
347
|
|
|
344
348
|
`core.config.load(name, ...)` automatically maps each YAML leaf to an
|
|
345
349
|
environment variable named `HAI_<CONFIG_NAME>_<YAML_PATH>`. Configuration names and keys are uppercased, levels are separated by `_`,
|
|
@@ -382,7 +386,7 @@ database: ${DB_CONNECTION} # → 环境变量缺失时报错
|
|
|
382
386
|
url: http://${HOST}:${PORT} # → string(混合文本)
|
|
383
387
|
```
|
|
384
388
|
|
|
385
|
-
|
|
389
|
+
#### ID generation
|
|
386
390
|
|
|
387
391
|
```typescript
|
|
388
392
|
const id = core.id.generate() // nanoid 21 字符
|
|
@@ -398,7 +402,7 @@ core.id.isValidUUID('f47ac10b-...') // true/false
|
|
|
398
402
|
core.id.isValidNanoId('abc123', 6) // true/false
|
|
399
403
|
```
|
|
400
404
|
|
|
401
|
-
|
|
405
|
+
#### Utilities
|
|
402
406
|
|
|
403
407
|
```typescript
|
|
404
408
|
// 类型检查
|
|
@@ -470,7 +474,7 @@ core.time.startOfDay(date)
|
|
|
470
474
|
core.time.endOfDay(date)
|
|
471
475
|
```
|
|
472
476
|
|
|
473
|
-
|
|
477
|
+
#### Module utilities (module)
|
|
474
478
|
|
|
475
479
|
Shared initialization error handling for modules:
|
|
476
480
|
|
|
@@ -488,9 +492,9 @@ const currentDdl: DdlOperations = notInitialized.proxy<DdlOperations>()
|
|
|
488
492
|
const currentHash: HashOperations = notInitialized.proxy<HashOperations>('sync')
|
|
489
493
|
```
|
|
490
494
|
|
|
491
|
-
|
|
495
|
+
### Error handling
|
|
492
496
|
|
|
493
|
-
|
|
497
|
+
#### HaiResult types
|
|
494
498
|
|
|
495
499
|
All operations that may fail return `HaiResult<T>`:
|
|
496
500
|
|
|
@@ -513,7 +517,7 @@ else {
|
|
|
513
517
|
}
|
|
514
518
|
```
|
|
515
519
|
|
|
516
|
-
|
|
520
|
+
#### Custom error codes (per module)
|
|
517
521
|
|
|
518
522
|
```typescript
|
|
519
523
|
import type { ErrorInfo } from '@h-ai/core'
|
|
@@ -539,7 +543,7 @@ const errorInst = core.error.buildHaiErrorInst(
|
|
|
539
543
|
)
|
|
540
544
|
```
|
|
541
545
|
|
|
542
|
-
|
|
546
|
+
#### Configuration error codes
|
|
543
547
|
|
|
544
548
|
```typescript
|
|
545
549
|
import { HaiConfigError } from '@h-ai/core'
|
|
@@ -551,7 +555,7 @@ HaiConfigError.CONFIG_ENV_VAR_MISSING // hai:core:013 - 环境变量缺失
|
|
|
551
555
|
HaiConfigError.CONFIG_NOT_LOADED // hai:core:014 - 配置未加载
|
|
552
556
|
```
|
|
553
557
|
|
|
554
|
-
##
|
|
558
|
+
## Development and testing
|
|
555
559
|
|
|
556
560
|
```bash
|
|
557
561
|
pnpm --filter @h-ai/core test
|
package/README.ja.md
CHANGED
|
@@ -4,7 +4,9 @@
|
|
|
4
4
|
|
|
5
5
|
[フレームワークのホーム](../../README.ja.md)
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
## 概要
|
|
8
|
+
|
|
9
|
+
hai Agent Framework の中核モジュール。共通ツール、型定義、設定管理、ログ機能を提供します。
|
|
8
10
|
|
|
9
11
|
## 主な機能
|
|
10
12
|
|
|
@@ -18,9 +20,11 @@
|
|
|
18
20
|
- **モジュールツール**:NotInitializedKit のプロキシと共通のライフサイクル基盤。
|
|
19
21
|
- **ツール関数**:型確認、オブジェクト・文字列・配列・非同期・時刻の操作。
|
|
20
22
|
|
|
21
|
-
##
|
|
23
|
+
## 使い始める
|
|
24
|
+
|
|
25
|
+
### クイックスタート
|
|
22
26
|
|
|
23
|
-
|
|
27
|
+
#### Node.js 環境
|
|
24
28
|
|
|
25
29
|
```typescript
|
|
26
30
|
import { core } from '@h-ai/core'
|
|
@@ -72,7 +76,7 @@ core.time.formatDate(new Date(), 'YYYY-MM-DD HH:mm:ss')
|
|
|
72
76
|
core.typeUtils.isDefined(value)
|
|
73
77
|
```
|
|
74
78
|
|
|
75
|
-
|
|
79
|
+
#### ブラウザー環境
|
|
76
80
|
|
|
77
81
|
```typescript
|
|
78
82
|
import { core } from '@h-ai/core'
|
|
@@ -95,13 +99,13 @@ core.array.unique([1, 1, 2])
|
|
|
95
99
|
- `watch()` は同じエラーで直ちにコールバックを呼び、安全な no-op の監視解除関数を返します。
|
|
96
100
|
- 設定が必要な場合はサーバーで読み込み API で渡すか、ブラウザーでは `core.init({ logging })` でログのみ設定してください。
|
|
97
101
|
|
|
98
|
-
|
|
102
|
+
### API の詳細
|
|
99
103
|
|
|
100
|
-
|
|
104
|
+
#### ログ(Logger)
|
|
101
105
|
|
|
102
106
|
`core.logger` は既定の Logger インスタンスであり、ログ管理の共通入口でもあります。
|
|
103
107
|
|
|
104
|
-
|
|
108
|
+
##### ログの記録
|
|
105
109
|
|
|
106
110
|
6 つのレベル:`trace` / `debug` / `info` / `warn` / `error` / `fatal`。
|
|
107
111
|
|
|
@@ -111,7 +115,7 @@ core.logger.error('Failed to connect', { error })
|
|
|
111
115
|
core.logger.debug('Processing item', { id, step: 'validation' })
|
|
112
116
|
```
|
|
113
117
|
|
|
114
|
-
|
|
118
|
+
##### モジュール用 logger の作成
|
|
115
119
|
|
|
116
120
|
```typescript
|
|
117
121
|
// 独立名称空间,适合模块内全局使用
|
|
@@ -119,7 +123,7 @@ const logger = core.logger.create({ name: 'payment' })
|
|
|
119
123
|
logger.info('Payment processed')
|
|
120
124
|
```
|
|
121
125
|
|
|
122
|
-
|
|
126
|
+
##### 子 logger(child)
|
|
123
127
|
|
|
124
128
|
```typescript
|
|
125
129
|
// 携带固定上下文,每条日志自动附带这些字段
|
|
@@ -135,7 +139,7 @@ opLogger.error('Login failed', { reason: 'invalid_password' })
|
|
|
135
139
|
|
|
136
140
|
> **典型的な使い方**:リクエスト入口で `reqLogger` を作成してサービス層に渡し、サービス層で `child` に操作コンテキストを追加します。ログに処理全体のコンテキストが自動的に含まれます。
|
|
137
141
|
|
|
138
|
-
|
|
142
|
+
##### ログの管理
|
|
139
143
|
|
|
140
144
|
```typescript
|
|
141
145
|
// 配置输出格式和级别(Node.js / Browser)
|
|
@@ -156,7 +160,7 @@ const level = core.logger.getLevel() // 'debug'
|
|
|
156
160
|
|
|
157
161
|
`core.logger` は既定でログの機密情報をマスクします。`password`、`token`、`secret`、`privateKey`、`apiV3Key` などは `[REDACTED]` に置換されます。`url` / `baseUrl` / `endpoint` は URL 内のユーザー名・パスワードのみをマスクします。メールアドレス・電話番号は既定では隠しません。
|
|
158
162
|
|
|
159
|
-
|
|
163
|
+
##### ログレベルの規約
|
|
160
164
|
|
|
161
165
|
| レベル | 用途 |
|
|
162
166
|
| ------- | ---------------------------------------- |
|
|
@@ -167,7 +171,7 @@ const level = core.logger.getLevel() // 'debug'
|
|
|
167
171
|
| `error` | 調査が必要な操作の失敗 |
|
|
168
172
|
| `fatal` | サービス継続不能の致命的エラー |
|
|
169
173
|
|
|
170
|
-
|
|
174
|
+
#### 国際化(i18n)
|
|
171
175
|
|
|
172
176
|
```typescript
|
|
173
177
|
// 设置全局语言(所有 getMessage 函数自动响应)
|
|
@@ -191,7 +195,7 @@ core.i18n.DEFAULT_LOCALES // [{ code: 'zh-CN', label: '简体中文' }, { code:
|
|
|
191
195
|
core.i18n.DEFAULT_LOCALE // 'zh-CN'
|
|
192
196
|
```
|
|
193
197
|
|
|
194
|
-
|
|
198
|
+
#### 機密情報のマスク
|
|
195
199
|
|
|
196
200
|
`core.sanitize.sanitizeSensitiveFields()` はオブジェクト・配列内の機密情報を再帰的にマスクします。既定では password、token、secret、privateKey、apiV3Key などを処理し、`url` / `baseUrl` / `endpoint` の認証情報もマスクします。独自の matcher も指定できます。
|
|
197
201
|
|
|
@@ -211,7 +215,7 @@ core.sanitize.sanitizeSensitiveFields({ email: 'user@example.com' }, {
|
|
|
211
215
|
// => { email: '***' }
|
|
212
216
|
```
|
|
213
217
|
|
|
214
|
-
|
|
218
|
+
#### Zod 検証エラーの i18n 変換
|
|
215
219
|
|
|
216
220
|
`core.zodValidation` は Zod の `SafeParseError` / `ZodError` をフラットなフォームエラーに変換し、
|
|
217
221
|
Zod の既定の英語メッセージを呼び出し元の i18n 文言に変換します。
|
|
@@ -272,7 +276,7 @@ if (!result.success) {
|
|
|
272
276
|
}
|
|
273
277
|
```
|
|
274
278
|
|
|
275
|
-
|
|
279
|
+
#### 設定管理(Node.js 専用)
|
|
276
280
|
|
|
277
281
|
> ブラウザーにはファイルシステムがないため、`core.config` は代替 API の形状のみを提供します。ファイル関連メソッドは `SERVICE_UNAVAILABLE` を返し、YAML を読み込みません。
|
|
278
282
|
|
|
@@ -327,7 +331,7 @@ core.config.clear('app') // 清除单个
|
|
|
327
331
|
core.config.clear() // 清除全部
|
|
328
332
|
```
|
|
329
333
|
|
|
330
|
-
|
|
334
|
+
##### dotenv ファイルと環境切り替え
|
|
331
335
|
|
|
332
336
|
Node 専用の `core.config.loadEnvFiles({ mode, envDir })` は HaiResult を返し、`.env` → `.env.<mode>` → `.env.local` の順で読み込みます。既存のプロセス変数が最優先です。development/production は dev/prod に対応し、存在しないファイルは省略します。プロセスは変更しないため、success を確認してから代入します。公開設定と `.env.example` は Git 登録し、私有の `.env.local` は除外します。core.init は dotenv を読み込まず、ブラウザーでは SERVICE_UNAVAILABLE を返します。
|
|
333
337
|
|
|
@@ -339,7 +343,7 @@ Object.assign(process.env, env.data)
|
|
|
339
343
|
core.init({ configDir: './config' })
|
|
340
344
|
```
|
|
341
345
|
|
|
342
|
-
|
|
346
|
+
##### 環境変数のマッピングと展開
|
|
343
347
|
|
|
344
348
|
`core.config.load(name, ...)` は YAML の各末端設定を
|
|
345
349
|
`HAI_<CONFIG_NAME>_<YAML_PATH>` の環境変数に自動対応付けします。設定名・各 key は大文字化し、階層は `_` で区切り、
|
|
@@ -382,7 +386,7 @@ database: ${DB_CONNECTION} # → 环境变量缺失时报错
|
|
|
382
386
|
url: http://${HOST}:${PORT} # → string(混合文本)
|
|
383
387
|
```
|
|
384
388
|
|
|
385
|
-
|
|
389
|
+
#### ID 生成
|
|
386
390
|
|
|
387
391
|
```typescript
|
|
388
392
|
const id = core.id.generate() // nanoid 21 字符
|
|
@@ -398,7 +402,7 @@ core.id.isValidUUID('f47ac10b-...') // true/false
|
|
|
398
402
|
core.id.isValidNanoId('abc123', 6) // true/false
|
|
399
403
|
```
|
|
400
404
|
|
|
401
|
-
|
|
405
|
+
#### ツール関数
|
|
402
406
|
|
|
403
407
|
```typescript
|
|
404
408
|
// 类型检查
|
|
@@ -470,7 +474,7 @@ core.time.startOfDay(date)
|
|
|
470
474
|
core.time.endOfDay(date)
|
|
471
475
|
```
|
|
472
476
|
|
|
473
|
-
|
|
477
|
+
#### モジュール共通ツール(module)
|
|
474
478
|
|
|
475
479
|
モジュール共通の初期化エラー処理:
|
|
476
480
|
|
|
@@ -488,9 +492,9 @@ const currentDdl: DdlOperations = notInitialized.proxy<DdlOperations>()
|
|
|
488
492
|
const currentHash: HashOperations = notInitialized.proxy<HashOperations>('sync')
|
|
489
493
|
```
|
|
490
494
|
|
|
491
|
-
|
|
495
|
+
### エラー処理
|
|
492
496
|
|
|
493
|
-
|
|
497
|
+
#### HaiResult 型
|
|
494
498
|
|
|
495
499
|
失敗する可能性がある操作は `HaiResult<T>` を返します:
|
|
496
500
|
|
|
@@ -513,7 +517,7 @@ else {
|
|
|
513
517
|
}
|
|
514
518
|
```
|
|
515
519
|
|
|
516
|
-
|
|
520
|
+
#### 独自のエラーコード(モジュール単位)
|
|
517
521
|
|
|
518
522
|
```typescript
|
|
519
523
|
import type { ErrorInfo } from '@h-ai/core'
|
|
@@ -539,7 +543,7 @@ const errorInst = core.error.buildHaiErrorInst(
|
|
|
539
543
|
)
|
|
540
544
|
```
|
|
541
545
|
|
|
542
|
-
|
|
546
|
+
#### 設定エラーコード
|
|
543
547
|
|
|
544
548
|
```typescript
|
|
545
549
|
import { HaiConfigError } from '@h-ai/core'
|
|
@@ -551,12 +555,12 @@ HaiConfigError.CONFIG_ENV_VAR_MISSING // hai:core:013 - 环境变量缺失
|
|
|
551
555
|
HaiConfigError.CONFIG_NOT_LOADED // hai:core:014 - 配置未加载
|
|
552
556
|
```
|
|
553
557
|
|
|
554
|
-
##
|
|
558
|
+
## 開発とテスト
|
|
555
559
|
|
|
556
560
|
```bash
|
|
557
561
|
pnpm --filter @h-ai/core test
|
|
558
562
|
```
|
|
559
563
|
|
|
560
|
-
##
|
|
564
|
+
## ライセンス
|
|
561
565
|
|
|
562
566
|
Apache-2.0
|
package/README.md
CHANGED
|
@@ -4,9 +4,11 @@
|
|
|
4
4
|
|
|
5
5
|
[框架首页](../../README.md)
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
## 简介
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
hai Agent Framework 核心模块 — 提供统一的基础工具、类型定义、配置管理和日志功能。
|
|
10
|
+
|
|
11
|
+
## 核心功能清单
|
|
10
12
|
|
|
11
13
|
- **HaiResult 类型** — 函数式错误处理(`ok` / `err`),所有模块统一返回值
|
|
12
14
|
- **统一日志** — Node.js 基于 pino,浏览器基于 loglevel,API 一致
|
|
@@ -18,9 +20,11 @@
|
|
|
18
20
|
- **模块工具** — NotInitializedKit 代理模式,各模块共用的生命周期基础设施
|
|
19
21
|
- **工具函数库** — 类型检查、对象 / 字符串 / 数组 / 异步 / 时间操作
|
|
20
22
|
|
|
21
|
-
##
|
|
23
|
+
## 使用入门
|
|
24
|
+
|
|
25
|
+
### 快速开始
|
|
22
26
|
|
|
23
|
-
|
|
27
|
+
#### Node.js 环境
|
|
24
28
|
|
|
25
29
|
```typescript
|
|
26
30
|
import { core } from '@h-ai/core'
|
|
@@ -72,7 +76,7 @@ core.time.formatDate(new Date(), 'YYYY-MM-DD HH:mm:ss')
|
|
|
72
76
|
core.typeUtils.isDefined(value)
|
|
73
77
|
```
|
|
74
78
|
|
|
75
|
-
|
|
79
|
+
#### 浏览器环境
|
|
76
80
|
|
|
77
81
|
```typescript
|
|
78
82
|
import { core } from '@h-ai/core'
|
|
@@ -95,13 +99,13 @@ core.array.unique([1, 1, 2])
|
|
|
95
99
|
- `watch()` 会立即用同一错误调用回调,并返回安全的 no-op 取消函数
|
|
96
100
|
- 需要配置时请由服务端读取后通过接口下发,或只在浏览器端用 `core.init({ logging })` 配置日志
|
|
97
101
|
|
|
98
|
-
|
|
102
|
+
### 详细 API
|
|
99
103
|
|
|
100
|
-
|
|
104
|
+
#### 日志(Logger)
|
|
101
105
|
|
|
102
106
|
`core.logger` 既是默认 Logger 实例,也是日志管理的统一入口。
|
|
103
107
|
|
|
104
|
-
|
|
108
|
+
##### 日志记录
|
|
105
109
|
|
|
106
110
|
6 个级别:`trace` / `debug` / `info` / `warn` / `error` / `fatal`
|
|
107
111
|
|
|
@@ -111,7 +115,7 @@ core.logger.error('Failed to connect', { error })
|
|
|
111
115
|
core.logger.debug('Processing item', { id, step: 'validation' })
|
|
112
116
|
```
|
|
113
117
|
|
|
114
|
-
|
|
118
|
+
##### 创建模块级 logger
|
|
115
119
|
|
|
116
120
|
```typescript
|
|
117
121
|
// 独立名称空间,适合模块内全局使用
|
|
@@ -119,7 +123,7 @@ const logger = core.logger.create({ name: 'payment' })
|
|
|
119
123
|
logger.info('Payment processed')
|
|
120
124
|
```
|
|
121
125
|
|
|
122
|
-
|
|
126
|
+
##### 子 logger(child)
|
|
123
127
|
|
|
124
128
|
```typescript
|
|
125
129
|
// 携带固定上下文,每条日志自动附带这些字段
|
|
@@ -135,7 +139,7 @@ opLogger.error('Login failed', { reason: 'invalid_password' })
|
|
|
135
139
|
|
|
136
140
|
> **典型用法**:在请求入口创建 `reqLogger`,传入 service 层,service 层再 `child` 添加操作上下文,最终日志自动串联完整链路。
|
|
137
141
|
|
|
138
|
-
|
|
142
|
+
##### 日志管理
|
|
139
143
|
|
|
140
144
|
```typescript
|
|
141
145
|
// 配置输出格式和级别(Node.js / Browser)
|
|
@@ -156,7 +160,7 @@ const level = core.logger.getLevel() // 'debug'
|
|
|
156
160
|
|
|
157
161
|
`core.logger` 默认会对日志上下文执行安全脱敏:`password`、`token`、`secret`、`privateKey`、`apiV3Key` 等凭证类字段会替换为 `[REDACTED]`,`url` / `baseUrl` / `endpoint` 这类字段只会掩码 URL 中内嵌的用户名和密码;邮箱、手机号默认不会被遮盖。
|
|
158
162
|
|
|
159
|
-
|
|
163
|
+
##### 日志级别规范
|
|
160
164
|
|
|
161
165
|
| 级别 | 适用场景 |
|
|
162
166
|
| ------- | ---------------------------------- |
|
|
@@ -167,7 +171,7 @@ const level = core.logger.getLevel() // 'debug'
|
|
|
167
171
|
| `error` | 操作失败(需人工排查) |
|
|
168
172
|
| `fatal` | 致命错误(服务无法继续) |
|
|
169
173
|
|
|
170
|
-
|
|
174
|
+
#### 国际化(i18n)
|
|
171
175
|
|
|
172
176
|
```typescript
|
|
173
177
|
// 设置全局语言(所有 getMessage 函数自动响应)
|
|
@@ -191,7 +195,7 @@ core.i18n.DEFAULT_LOCALES // [{ code: 'zh-CN', label: '简体中文' }, { code:
|
|
|
191
195
|
core.i18n.DEFAULT_LOCALE // 'zh-CN'
|
|
192
196
|
```
|
|
193
197
|
|
|
194
|
-
|
|
198
|
+
#### 脱敏工具
|
|
195
199
|
|
|
196
200
|
`core.sanitize.sanitizeSensitiveFields()` 可递归脱敏对象/数组中的敏感字段;默认会处理密码、token、secret、privateKey、apiV3Key 等凭证类字段,并自动掩码 `url` / `baseUrl` / `endpoint` 字段中的内嵌凭证。模块也可自定义 matcher。
|
|
197
201
|
|
|
@@ -211,7 +215,7 @@ core.sanitize.sanitizeSensitiveFields({ email: 'user@example.com' }, {
|
|
|
211
215
|
// => { email: '***' }
|
|
212
216
|
```
|
|
213
217
|
|
|
214
|
-
|
|
218
|
+
#### Zod 校验错误 i18n 映射
|
|
215
219
|
|
|
216
220
|
`core.zodValidation` 用于把 Zod `SafeParseError` / `ZodError` 转为扁平表单错误,并将 Zod
|
|
217
221
|
默认英文消息映射为调用方自己的 i18n 文案。
|
|
@@ -272,7 +276,7 @@ if (!result.success) {
|
|
|
272
276
|
}
|
|
273
277
|
```
|
|
274
278
|
|
|
275
|
-
|
|
279
|
+
#### 配置管理(Node.js 专用)
|
|
276
280
|
|
|
277
281
|
> 浏览器端没有文件系统,`core.config` 仅提供占位 API:文件相关方法返回 `SERVICE_UNAVAILABLE`,不会加载 YAML。
|
|
278
282
|
|
|
@@ -327,7 +331,7 @@ core.config.clear('app') // 清除单个
|
|
|
327
331
|
core.config.clear() // 清除全部
|
|
328
332
|
```
|
|
329
333
|
|
|
330
|
-
|
|
334
|
+
##### dotenv 文件与环境切换
|
|
331
335
|
|
|
332
336
|
Node 专用的 `core.config.loadEnvFiles({ mode, envDir })` 返回 HaiResult,读取 `.env` → `.env.<mode>` → `.env.local`,已有进程环境最高;development/production 映射为 dev/prod,文件不存在时跳过。该函数不修改进程,调用方检查 success 后注入。除 `.env.local` 外的公共环境文件及完整说明 `.env.example` 提交 Git。`core.init` 不自动读取 dotenv,浏览器调用返回 SERVICE_UNAVAILABLE。
|
|
333
337
|
|
|
@@ -339,7 +343,7 @@ Object.assign(process.env, env.data)
|
|
|
339
343
|
core.init({ configDir: './config' })
|
|
340
344
|
```
|
|
341
345
|
|
|
342
|
-
|
|
346
|
+
##### 环境变量映射与插值
|
|
343
347
|
|
|
344
348
|
`core.config.load(name, ...)` 会为每个 YAML 叶子配置项自动映射
|
|
345
349
|
`HAI_<配置名>_<YAML 路径>` 环境变量。配置名和每层 key 转成大写,层级以 `_`
|
|
@@ -382,7 +386,7 @@ database: ${DB_CONNECTION} # → 环境变量缺失时报错
|
|
|
382
386
|
url: http://${HOST}:${PORT} # → string(混合文本)
|
|
383
387
|
```
|
|
384
388
|
|
|
385
|
-
|
|
389
|
+
#### ID 生成
|
|
386
390
|
|
|
387
391
|
```typescript
|
|
388
392
|
const id = core.id.generate() // nanoid 21 字符
|
|
@@ -398,7 +402,7 @@ core.id.isValidUUID('f47ac10b-...') // true/false
|
|
|
398
402
|
core.id.isValidNanoId('abc123', 6) // true/false
|
|
399
403
|
```
|
|
400
404
|
|
|
401
|
-
|
|
405
|
+
#### 工具函数
|
|
402
406
|
|
|
403
407
|
```typescript
|
|
404
408
|
// 类型检查
|
|
@@ -470,7 +474,7 @@ core.time.startOfDay(date)
|
|
|
470
474
|
core.time.endOfDay(date)
|
|
471
475
|
```
|
|
472
476
|
|
|
473
|
-
|
|
477
|
+
#### 模块基础工具(module)
|
|
474
478
|
|
|
475
479
|
提供各模块共用的初始化错误处理:
|
|
476
480
|
|
|
@@ -488,9 +492,9 @@ const currentDdl: DdlOperations = notInitialized.proxy<DdlOperations>()
|
|
|
488
492
|
const currentHash: HashOperations = notInitialized.proxy<HashOperations>('sync')
|
|
489
493
|
```
|
|
490
494
|
|
|
491
|
-
|
|
495
|
+
### 错误处理
|
|
492
496
|
|
|
493
|
-
|
|
497
|
+
#### HaiResult 类型
|
|
494
498
|
|
|
495
499
|
所有可能失败的操作返回 `HaiResult<T>`:
|
|
496
500
|
|
|
@@ -513,7 +517,7 @@ else {
|
|
|
513
517
|
}
|
|
514
518
|
```
|
|
515
519
|
|
|
516
|
-
|
|
520
|
+
#### 自定义错误码(模块级)
|
|
517
521
|
|
|
518
522
|
```typescript
|
|
519
523
|
import type { ErrorInfo } from '@h-ai/core'
|
|
@@ -539,7 +543,7 @@ const errorInst = core.error.buildHaiErrorInst(
|
|
|
539
543
|
)
|
|
540
544
|
```
|
|
541
545
|
|
|
542
|
-
|
|
546
|
+
#### 配置错误码
|
|
543
547
|
|
|
544
548
|
```typescript
|
|
545
549
|
import { HaiConfigError } from '@h-ai/core'
|
|
@@ -551,12 +555,12 @@ HaiConfigError.CONFIG_ENV_VAR_MISSING // hai:core:013 - 环境变量缺失
|
|
|
551
555
|
HaiConfigError.CONFIG_NOT_LOADED // hai:core:014 - 配置未加载
|
|
552
556
|
```
|
|
553
557
|
|
|
554
|
-
##
|
|
558
|
+
## 开发测试
|
|
555
559
|
|
|
556
560
|
```bash
|
|
557
561
|
pnpm --filter @h-ai/core test
|
|
558
562
|
```
|
|
559
563
|
|
|
560
|
-
##
|
|
564
|
+
## 许可证
|
|
561
565
|
|
|
562
566
|
Apache-2.0
|
package/package.json
CHANGED