@hile/core 1.0.16 → 1.0.18

package/README.md

@@ -1,6 +1,6 @@
-# Hile
+# @hile/core
 
-轻量级异步服务容器，提供单例管理、并发请求合并和资源生命周期销毁。纯 TypeScript 实现，零运行时依赖。
+轻量级异步服务容器，提供单例管理、并发请求合并与生命周期销毁能力。纯 TypeScript 实现，零运行时依赖。
 
 ## 安装
 
@@ -13,7 +13,6 @@ pnpm add @hile/core
 ```typescript
 import { defineService, loadService } from '@hile/core'
 
-// 定义服务
 const greeterService = defineService(async (shutdown) => {
   return {
     hello(name: string) {
@@ -22,16 +21,15 @@ const greeterService = defineService(async (shutdown) => {
   }
 })
 
-// 加载并使用
 const greeter = await loadService(greeterService)
-greeter.hello('World') // "Hello, World!"
+greeter.hello('World') // Hello, World!
 ```
 
 ## 核心概念
 
-### 定义服务
+### 1) 定义服务
 
-使用 `defineService` 注册一个服务。服务函数接收一个 `shutdown` 参数，用于注册资源清理回调。
+通过 `defineService` 注册服务。服务函数接收 `shutdown` 注册器，用于登记资源清理回调。
 
 ```typescript
 import { defineService } from '@hile/core'
@@ -43,9 +41,9 @@ export const databaseService = defineService(async (shutdown) => {
 })
 ```
 
-### 加载服务
+### 2) 加载服务
 
-使用 `loadService` 获取服务实例。容器保证服务函数只执行一次，后续调用直接返回缓存结果。
+通过 `loadService` 获取服务实例。容器保证同一服务函数只执行一次。
 
 ```typescript
 import { loadService } from '@hile/core'
@@ -55,23 +53,23 @@ const db = await loadService(databaseService)
 const users = await db.query('SELECT * FROM users')
 ```
 
-### 并发请求合并
+### 3) 并发请求合并
 
-多个地方同时请求同一服务时，服务函数不会重复执行，所有调用者共享同一结果。
+并发加载同一服务时，初始化只执行一次，调用方共享结果。
 
 ```typescript
-// 三个并发调用，服务函数只执行一次
 const [r1, r2, r3] = await Promise.all([
   loadService(heavyService),
   loadService(heavyService),
   loadService(heavyService),
 ])
+
 // r1 === r2 === r3
 ```
 
-### 服务间依赖
+### 4) 服务间依赖
 
-在服务函数内部通过 `loadService` 加载所依赖的其他服务：
+服务内部可通过 `loadService` 继续加载依赖服务。
 
 ```typescript
 import { defineService, loadService } from '@hile/core'
@@ -94,37 +92,77 @@ export const userService = defineService(async (shutdown) => {
 })
 ```
 
-### 资源销毁（Shutdown）
+### 5) 资源销毁（Shutdown）
 
-服务函数的第一个参数 `shutdown` 是一个注册器，用于在初始化过程中注册清理回调。当服务启动失败时，容器会自动执行已注册的清理回调。
+当服务初始化失败或手动执行全局关闭时，容器会按规则执行已注册的清理回调。
 
 ```typescript
 export const connectionService = defineService(async (shutdown) => {
   const primary = await connectPrimary()
-  shutdown(() => primary.disconnect())    // 最后执行
+  shutdown(() => primary.disconnect())
 
   const replica = await connectReplica()
-  shutdown(() => replica.disconnect())    // 第 2 个执行
+  shutdown(() => replica.disconnect())
 
   const cache = await initCache()
-  shutdown(() => cache.flush())           // 最先执行
+  shutdown(() => cache.flush())
 
   return { primary, replica, cache }
 })
 ```
 
-**关键特性：**
+特性：
 
-- 销毁回调按 **逆序（LIFO）** 执行——后注册的先执行
+- 清理回调按逆序（LIFO）执行
 - 支持异步清理函数
-- 同一函数引用多次注册只会执行一次
-- 清理函数自身的错误不会影响原始错误的传播
+- 同一函数引用重复注册只执行一次
+- 清理函数错误不会覆盖原始业务错误
+
+> 建议始终使用 `async` 服务函数，确保异常路径可正确触发销毁机制。
 
-> **注意：** 请使用 `async` 函数定义服务。同步函数中直接 `throw` 的错误无法触发销毁机制。
+### 6) 生命周期、超时与可观测事件
 
-### 手动销毁（Graceful Shutdown）
+容器支持显式生命周期阶段：`init -> ready -> stopping -> stopped`。
 
-调用 `container.shutdown()` 可手动触发所有已注册服务的销毁回调，适用于进程退出时优雅关闭资源：
+可通过构造参数设置超时：
+
+```typescript
+import { Container } from '@hile/core'
+
+const container = new Container({
+  startTimeoutMs: 5_000,
+  shutdownTimeoutMs: 3_000,
+})
+```
+
+订阅事件：
+
+```typescript
+const off = container.onEvent((event) => {
+  if (event.type === 'service:ready') {
+    console.log(`service#${event.id} ready in ${event.durationMs}ms`)
+  }
+})
+
+// later
+off()
+```
+
+### 7) 依赖图与启动顺序
+
+容器会在 `resolve` 过程中自动记录依赖关系，并检测循环依赖。
+
+```typescript
+const graph = container.getDependencyGraph()
+// graph.nodes: number[]
+// graph.edges: Array<{ from: number; to: number }>
+
+const startupOrder = container.getStartupOrder()
+```
+
+若出现循环依赖，会抛出 `circular dependency detected` 错误。
+
+### 8) 手动销毁（Graceful Shutdown）
 
 ```typescript
 import container from '@hile/core'
@@ -135,24 +173,20 @@ process.on('SIGTERM', async () => {
 })
 ```
 
-销毁按 **服务注册逆序** 执行：后注册的服务先销毁。调用后销毁队列清空，重复调用不会再次执行。
-
-### 服务校验（isService）
-
-使用 `isService` 判断一个对象是否为合法的服务注册信息。内部通过不可伪造的 Symbol 标识校验，确保只有通过 `defineService` / `container.register` 创建的对象才会返回 `true`：
+### 9) 服务校验（isService）
 
 ```typescript
 import { defineService, isService } from '@hile/core'
 
 const myService = defineService(async (shutdown) => 'hello')
 
-isService(myService)            // true
-isService({ id: 1, fn: () => {} } as any)  // false
+isService(myService) // true
+isService({ id: 1, fn: () => {} } as any) // false
 ```
 
 ## 隔离容器
 
-除默认容器外，可以创建独立的 `Container` 实例，实现服务作用域隔离：
+除了默认容器，也可以手动创建独立容器以实现作用域隔离。
 
 ```typescript
 import { Container } from '@hile/core'
@@ -168,31 +202,37 @@ const result = await container.resolve(service)
 
 ## API
 
-### 便捷函数
+### 顶层函数
 
 | 函数 | 说明 |
 |------|------|
-| `defineService(fn)` | 注册服务到默认容器，返回 `ServiceRegisterProps` |
-| `loadService(props)` | 从默认容器加载服务，返回 `Promise<R>` |
-| `isService(props)` | 判断对象是否为合法的服务注册信息（通过内部 Symbol 校验） |
+| `defineService(fn)` | 注册服务到默认容器 |
+| `loadService(props)` | 从默认容器加载服务 |
+| `isService(props)` | 判断对象是否为合法服务注册信息 |
 
-### Container
+### `Container`
 
 | 方法 | 说明 |
 |------|------|
-| `register(fn)` | 注册服务。同一函数引用只注册一次，返回 `ServiceRegisterProps` |
-| `resolve(props)` | 加载服务。根据当前状态决定执行、等待或返回缓存 |
-| `hasService(fn)` | 检查服务函数是否已注册 |
-| `hasMeta(id)` | 检查服务是否已运行（存在运行时元数据） |
-| `getIdByService(fn)` | 根据函数引用获取服务 ID |
-| `getMetaById(id)` | 根据服务 ID 获取运行时元数据 |
-| `shutdown()` | 手动销毁所有服务，返回 `Promise<void>`。按服务注册逆序执行所有销毁回调 |
+| `new Container(options?)` | 创建容器，可配置启动/销毁超时 |
+| `register(fn)` | 注册服务（同函数引用去重） |
+| `resolve(props)` | 加载服务（执行、等待或返回缓存） |
+| `shutdown()` | 销毁所有服务并执行清理回调 |
+| `onEvent(listener)` | 订阅容器事件，返回取消订阅函数 |
+| `offEvent(listener)` | 取消订阅 |
+| `getLifecycle(id)` | 获取服务生命周期阶段 |
+| `getDependencyGraph()` | 获取依赖图 `{ nodes, edges }` |
+| `getStartupOrder()` | 获取服务启动顺序（首次启动顺序） |
+| `hasService(fn)` | 检查函数是否已注册 |
+| `hasMeta(id)` | 检查服务是否已有运行时元数据 |
+| `getIdByService(fn)` | 通过函数获取服务 ID |
+| `getMetaById(id)` | 通过 ID 获取运行时元数据 |
 
 ### 服务状态
 
-| 状态 | 值 | `resolve` 的行为 |
-|------|---|-----------------|
-| 从未运行 | — | 执行服务函数 |
+| 状态 | 值 | `resolve` 行为 |
+|------|---|---------------|
+| 未运行 | — | 执行服务函数 |
 | 运行中 | `0` | 加入等待队列 |
 | 已成功 | `1` | 返回缓存值 |
 | 已失败 | `-1` | 返回缓存错误 |
@@ -201,9 +241,9 @@ const result = await container.resolve(service)
 
 ```bash
 pnpm install
-pnpm build        # 编译
-pnpm dev          # 监听模式
-pnpm test         # 运行测试
+pnpm build
+pnpm dev
+pnpm test
 ```
 
 ## License

package/SKILL.md

@@ -1,44 +1,31 @@
 ---
 name: hile-core
-description: Code generation and usage rules for @hile/core async service container. Use when defining or loading Hile services, wiring lifecycle shutdown, or when the user asks about @hile/core, defineService, loadService, or service container patterns.
+description: @hile/core 的代码生成与使用规范。适用于定义/加载 Hile 服务、生命周期 shutdown 编排、或涉及 defineService、loadService、Container 等话题。
 ---
 
-# Hile
+# @hile/core SKILL
 
-Hile 是一个轻量级异步服务容器。本文档是面向 AI 编码模型和人类开发者的 **代码生成规范**，阅读后应能正确地使用本库编写符合架构规则的代码。
+本文档用于约束 AI 与开发者在使用 `@hile/core` 时的代码生成方式，目标是保证服务定义、依赖加载与资源销毁行为一致且可维护。
 
----
-
-## 1. 架构总览
-
-Hile 的核心是 `Container`（服务容器）。所有服务都必须经过 **定义 → 加载** 两个步骤才能使用。容器保证：
-
-- 每个服务函数只执行一次（**单例**）
-- 并发请求同一服务时自动合并（**不重复执行**）
-- 服务启动失败时自动执行已注册的清理回调（**销毁机制**）
+## 1. 架构概览
 
-模块默认导出了一个全局容器实例，并提供 `defineService` / `loadService` 两个便捷函数。
+Hile 以 `Container` 为核心，服务遵循“定义 → 加载”两阶段：
 
----
+- 单例：同一服务函数仅初始化一次
+- 并发合并：并发加载同一服务时共享同一初始化过程
+- 失败回收：初始化失败时自动执行已注册的清理回调
 
-## 2. 类型签名
+模块默认导出全局容器，并提供 `defineService` / `loadService` 便捷函数。
 
-生成代码时，必须严格遵循以下类型：
+## 2. 关键类型
 
 ```typescript
-// 销毁回调：无参数，可返回 Promise
 type ServiceCutDownFunction = () => unknown | Promise<unknown>;
-
-// 销毁注册器：在服务函数内部调用，将清理回调注册到容器
 type ServiceCutDownHandler = (fn: ServiceCutDownFunction) => void;
-
-// 服务函数：第一个参数固定为销毁注册器，返回值为同步值或 Promise
 type ServiceFunction<R> = (shutdown: ServiceCutDownHandler) => R | Promise<R>;
 
-// 内部服务标识（Symbol，不可外部构造）
 const sericeFlag = Symbol('service');
 
-// 服务注册信息：由 defineService/register 返回，作为 loadService/resolve 的入参
 interface ServiceRegisterProps<R> {
   id: number;
   fn: ServiceFunction<R>;
@@ -46,39 +33,28 @@ interface ServiceRegisterProps<R> {
 }
 ```
 
----
+## 3. 标准模板
 
-## 3. 代码生成模板
-
-### 3.1 定义服务（必须遵循的模式）
-
-**模板：**
+### 3.1 定义服务
 
 ```typescript
 import { defineService } from '@hile/core'
 
 export const xxxService = defineService(async (shutdown) => {
-  // 1. 初始化资源
   const resource = await createResource()
-
-  // 2. 注册销毁回调（每创建一个资源就注册一个对应的清理）
   shutdown(() => resource.close())
-
-  // 3. 返回服务实例
   return resource
 })
 ```
 
-**规则：**
-- 服务函数的第一个参数 **必须** 命名为 `shutdown`，类型为 `ServiceCutDownHandler`
-- 服务函数 **应当** 使用 `async` 声明（确保销毁机制在失败时正确触发）
-- `defineService` 的返回值 **必须** 赋值给一个模块级常量并 `export`
-- 常量命名 **必须** 以 `Service` 结尾（如 `databaseService`、`cacheService`）
-- 每个服务定义 **应当** 放在独立的文件中
+规则：
 
-### 3.2 加载服务
+- 服务函数第一个参数固定为 `shutdown`
+- 推荐必须使用 `async`
+- `defineService` 结果需使用模块级 `export const` 暴露
+- 命名建议以 `Service` 结尾
 
-**模板：**
+### 3.2 加载服务
 
 ```typescript
 import { loadService } from '@hile/core'
@@ -87,68 +63,49 @@ import { databaseService } from './services/database'
 const db = await loadService(databaseService)
 ```
 
-**规则：**
-- **永远** 使用 `loadService()` 获取服务实例，**不要** 直接调用服务函数
-- `loadService` 返回 `Promise`，**必须** `await`
-- 可以在任何地方多次调用 `loadService(同一个服务)`，容器保证只执行一次
+规则：
 
-### 3.3 服务间依赖
+- 始终通过 `loadService` 获取实例
+- `loadService` 返回 Promise，必须 `await`
 
-当一个服务依赖另一个服务时，在服务函数内部通过 `loadService` 加载依赖：
+### 3.3 服务依赖服务
 
 ```typescript
 import { defineService, loadService } from '@hile/core'
 import { databaseService } from './database'
-import { configService } from './config'
 
 export const userService = defineService(async (shutdown) => {
-  // 加载依赖的服务（若已完成则直接返回缓存，否则等待）
-  const config = await loadService(configService)
   const db = await loadService(databaseService)
-
-  const repo = new UserRepository(db, config)
-  shutdown(() => repo.dispose())
-
-  return repo
+  return new UserRepository(db)
 })
 ```
 
-**规则：**
-- 依赖的服务通过 `import` 引入其 `ServiceRegisterProps`，然后在函数体内 `loadService` 加载
-- **不要** 将 `loadService` 的结果缓存到模块作用域变量中
-- **不要** 在服务函数外部调用 `loadService` 来获取另一个服务并传入——应在服务函数内部加载
+规则：
 
-### 3.4 注册销毁回调
+- 在服务函数内部加载依赖
+- 不在模块顶层缓存 `loadService` 结果
 
-**模板：**
+### 3.4 注册清理回调
 
 ```typescript
 export const connectionService = defineService(async (shutdown) => {
-  const primary = await connectPrimary()
-  shutdown(() => primary.disconnect())    // 注册第 1 个 → 最后执行
-
-  const replica = await connectReplica()
-  shutdown(() => replica.disconnect())    // 注册第 2 个
+  const a = await connectA()
+  shutdown(() => a.close())
 
-  const cache = await initCache()
-  shutdown(() => cache.flush())           // 注册第 3 个 → 最先执行
+  const b = await connectB()
+  shutdown(() => b.close())
 
-  return { primary, replica, cache }
+  return { a, b }
 })
 ```
 
-**规则：**
-- 每初始化一个需要清理的资源后，**立即** 调用 `shutdown()` 注册对应的清理函数
-- 不要把所有清理逻辑放在一个 shutdown 里，**每个资源对应一个 shutdown 调用**
-- 销毁函数按 **逆序（LIFO）** 执行：后注册的先执行，先注册的后执行
-- 销毁函数可以是 `async`，容器会依次 `await`
-- 同一个函数引用多次传给 `shutdown()` 只会注册一次
-
-### 3.5 手动销毁所有服务
+规则：
 
-在应用退出或需要优雅关闭时，调用 `container.shutdown()` 手动触发所有已注册的销毁回调：
+- 资源创建后立即注册清理
+- 回调按 LIFO 执行
+- 支持异步回调
 
-**模板：**
+### 3.5 全局优雅关闭
 
 ```typescript
 import container from '@hile/core'
@@ -159,298 +116,65 @@ process.on('SIGTERM', async () => {
 })
 ```
 
-**规则：**
-- `shutdown()` 返回 `Promise`，**必须** `await`
-- 销毁按 **服务注册逆序** 执行：后注册的服务先销毁
-- 每个服务内部的销毁回调同样按 **逆序（LIFO）** 执行
-- `shutdown()` 执行完毕后，再次调用不会重复执行（销毁队列已被清空）
+## 4. 强制规则
 
----
-
-## 4. 强制规则（生成代码时必须遵守）
+1. 服务函数必须使用 `async`，避免同步 `throw` 破坏销毁机制。
+2. 不要手动构造 `ServiceRegisterProps`。
+3. 不要在工厂函数里动态调用 `defineService` 生成新引用。
+4. 不要在模块顶层 `await loadService(...)`。
+5. 每个外部资源都应对应一次 `shutdown` 注册。
 
-| # | 规则 | 原因 |
-|---|------|------|
-| 1 | 服务函数**必须**使用 `async` 声明 | 同步 `throw` 不会触发销毁机制，只有异步 reject 才会触发 |
-| 2 | 服务函数第一个参数**必须**是 `shutdown` | 这是容器注入的销毁注册器，即使不使用也要声明 |
-| 3 | `defineService` 的结果**必须**赋给模块级 `export const` | 服务基于函数引用去重，引用必须稳定 |
-| 4 | **不要**在 `defineService` 内直接写匿名函数再传给另一个函数 | 每次调用会创建新引用，导致重复注册 |
-| 5 | **不要**手动构造 `ServiceRegisterProps` 对象 | 必须通过 `defineService` 或 `container.register` 获取，内部 `flag` 为不可伪造的 Symbol |
-| 6 | **不要**缓存 `loadService` 的结果到模块顶层变量 | 服务可能尚未初始化，应在需要时 `await loadService()` |
-| 7 | 每个外部资源初始化后**立即**注册 `shutdown` | 确保初始化中途失败时已创建的资源能被正确清理 |
-| 8 | 一个文件只定义一个服务 | 保持服务职责单一、依赖清晰 |
-
----
+## 5. 常见反模式
 
-## 5. 完整示例：项目结构
-
-```
-src/
-├── services/
-│   ├── config.ts        # 配置服务
-│   ├── database.ts      # 数据库服务（依赖 config）
-│   ├── cache.ts         # 缓存服务（依赖 config）
-│   └── user.ts          # 用户服务（依赖 database, cache）
-└── main.ts              # 入口
-```
-
-### services/config.ts
+### 同步 throw
 
 ```typescript
-import { defineService } from '@hile/core'
-
-interface AppConfig {
-  dbUrl: string
-  cacheHost: string
-}
-
-export const configService = defineService(async (shutdown) => {
-  const config: AppConfig = {
-    dbUrl: process.env.DB_URL ?? 'postgres://localhost:5432/app',
-    cacheHost: process.env.CACHE_HOST ?? 'localhost',
-  }
-  return config
+// ✗
+export const bad = defineService((shutdown) => {
+  const r = createSync()
+  shutdown(() => r.close())
+  throw new Error('boom')
 })
-```
-
-### services/database.ts
-
-```typescript
-import { defineService, loadService } from '@hile/core'
-import { configService } from './config'
 
-export const databaseService = defineService(async (shutdown) => {
-  const config = await loadService(configService)
-  const pool = await createPool(config.dbUrl)
-  shutdown(() => pool.end())
-  return pool
+// ✓
+export const good = defineService(async (shutdown) => {
+  const r = await createAsync()
+  shutdown(() => r.close())
+  throw new Error('boom')
 })
 ```
 
-### services/cache.ts
+### 顶层缓存服务实例
 
 ```typescript
-import { defineService, loadService } from '@hile/core'
-import { configService } from './config'
-
-export const cacheService = defineService(async (shutdown) => {
-  const config = await loadService(configService)
-  const client = await createRedisClient(config.cacheHost)
-  shutdown(() => client.quit())
-  return client
-})
-```
-
-### services/user.ts
-
-```typescript
-import { defineService, loadService } from '@hile/core'
-import { databaseService } from './database'
-import { cacheService } from './cache'
-
-interface User {
-  id: number
-  name: string
-}
-
-export const userService = defineService(async (shutdown) => {
-  const db = await loadService(databaseService)
-  const cache = await loadService(cacheService)
-
-  return {
-    async getById(id: number): Promise<User> {
-      const cached = await cache.get(`user:${id}`)
-      if (cached) return JSON.parse(cached)
-      const user = await db.query('SELECT * FROM users WHERE id = $1', [id])
-      await cache.set(`user:${id}`, JSON.stringify(user))
-      return user
-    }
-  }
-})
-```
-
-### main.ts
-
-```typescript
-import { loadService } from '@hile/core'
-import { userService } from './services/user'
-
-async function main() {
-  const users = await loadService(userService)
-  const user = await users.getById(1)
-  console.log(user)
-}
-
-main()
-```
-
----
-
-## 6. 反模式（生成代码时必须避免）
-
-### 6.1 不要使用同步 throw
-
-```typescript
-// ✗ 错误：同步 throw 不会触发 shutdown 销毁机制
-export const badService = defineService((shutdown) => {
-  const res = createResourceSync()
-  shutdown(() => res.close())
-  if (!res.isValid()) throw new Error('invalid')
-  return res
-})
-
-// ✓ 正确：使用 async 函数
-export const goodService = defineService(async (shutdown) => {
-  const res = await createResource()
-  shutdown(() => res.close())
-  if (!res.isValid()) throw new Error('invalid')
-  return res
-})
-```
-
-### 6.2 不要在模块顶层缓存服务结果
-
-```typescript
-// ✗ 错误：模块加载时服务可能尚未就绪
+// ✗
 const db = await loadService(databaseService)
-export function query(sql: string) {
-  return db.query(sql)
-}
 
-// ✓ 正确：每次在函数内部加载
+// ✓
 export async function query(sql: string) {
   const db = await loadService(databaseService)
   return db.query(sql)
 }
 ```
 
-### 6.3 不要内联定义服务函数
-
-```typescript
-// ✗ 错误：每次调用 getService() 都创建新函数引用，无法去重
-function getService() {
-  return defineService(async (shutdown) => { ... })
-}
-
-// ✓ 正确：模块级常量
-export const myService = defineService(async (shutdown) => { ... })
-```
-
-### 6.4 不要延迟注册 shutdown
-
-```typescript
-// ✗ 错误：如果 doSomething 抛错，resourceA 不会被清理
-export const badService = defineService(async (shutdown) => {
-  const a = await createResourceA()
-  const b = await doSomething(a)
-  shutdown(() => a.close())  // 太晚了！
-  shutdown(() => b.close())
-  return b
-})
-
-// ✓ 正确：创建后立即注册
-export const goodService = defineService(async (shutdown) => {
-  const a = await createResourceA()
-  shutdown(() => a.close())  // 立即注册
-  const b = await doSomething(a)
-  shutdown(() => b.close())
-  return b
-})
-```
-
----
-
-## 7. API 速查
-
-### 便捷函数（操作默认容器）
-
-| 函数 | 签名 | 说明 |
-|------|------|------|
-| `defineService` | `<R>(fn: ServiceFunction<R>) => ServiceRegisterProps<R>` | 注册服务，返回注册信息 |
-| `loadService` | `<R>(props: ServiceRegisterProps<R>) => Promise<R>` | 加载服务，返回服务实例 |
-| `isService` | `<R>(props: ServiceRegisterProps<R>) => boolean` | 判断对象是否为合法的服务注册信息（通过内部 Symbol 校验） |
-
-### Container 类（用于创建隔离容器）
-
-| 方法 | 签名 | 说明 |
-|------|------|------|
-| `register` | `<R>(fn: ServiceFunction<R>) => ServiceRegisterProps<R>` | 注册服务。同一函数引用只注册一次 |
-| `resolve` | `<R>(props: ServiceRegisterProps<R>) => Promise<R>` | 解析服务（状态机见下方） |
-| `hasService` | `<R>(fn: ServiceFunction<R>) => boolean` | 检查服务是否已注册 |
-| `hasMeta` | `(id: number) => boolean` | 检查服务是否已运行过 |
-| `getIdByService` | `<R>(fn: ServiceFunction<R>) => number \| undefined` | 根据函数引用查 ID |
-| `getMetaById` | `(id: number) => Paddings \| undefined` | 根据 ID 查运行时元数据 |
-| `shutdown` | `() => Promise<void>` | 手动销毁所有服务，按服务注册逆序执行所有销毁回调 |
-
-### resolve 状态机
-
-```
-resolve(props)
-  │
-  ├─ paddings 中无记录 → 首次运行
-  │    → run(id, fn, callback)
-  │    → 创建 Paddings { status: 0 }
-  │    ├─ fn 成功 → status = 1, value = 返回值, 通知 queue 所有等待者
-  │    └─ fn 失败 → status = -1, error = 错误
-  │                → 先逆序执行 shutdown 回调
-  │                → 再通知 queue 所有等待者
-  │
-  ├─ status = 0 (运行中) → 加入 queue 等待
-  ├─ status = 1 (已成功) → 直接 resolve(缓存值)
-  └─ status = -1 (已失败) → 直接 reject(缓存错误)
-```
-
----
-
-## 8. 内部机制（供理解，不供直接调用）
+## 6. API 速查
 
-### 数据结构
-
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| `packages` | `Map<Function, number>` | 函数引用 → 服务 ID |
-| `paddings` | `Map<number, Paddings>` | 服务 ID → 运行时状态 |
-| `shutdownFunctions` | `Map<number, ServiceCutDownFunction[]>` | 服务 ID → 销毁回调数组 |
-| `shutdownQueues` | `number[]` | 注册了销毁回调的服务 ID 队列（有序） |
-
-### Paddings 结构
-
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| `status` | `-1 \| 0 \| 1` | -1 失败 / 0 运行中 / 1 成功 |
-| `value` | `R` | 成功时的返回值 |
-| `error` | `any` | 失败时的错误 |
-| `queue` | `Set<{ resolve, reject }>` | 等待中的 Promise 回调 |
-
-### 销毁执行顺序
-
-- **单个服务内**：销毁回调按注册的逆序（LIFO）依次 `await` 执行
-- **全局销毁**：按服务注册顺序的逆序依次销毁
-- **触发时机**：
-  - 服务函数异步失败（reject）时自动触发该服务的销毁回调
-  - 手动调用 `container.shutdown()` 时触发所有已注册服务的销毁回调（按服务注册逆序）
-
-### 服务标识机制（sericeFlag）
-
-容器内部使用 `const sericeFlag = Symbol('service')` 作为服务注册信息的标识。`register` 返回的对象会携带 `flag: sericeFlag` 字段。`isService()` 通过检查 `flag === sericeFlag` 以及 `id` 和 `fn` 的类型来判断一个对象是否为合法的服务注册信息。由于 Symbol 不可伪造，外部无法手动构造通过 `isService` 校验的对象。
-
-### 函数去重机制
-
-容器通过 `===` 比较函数引用。两个函数即使代码完全相同，只要引用不同就会被视为不同服务。因此服务必须定义为模块级常量。
-
----
-
-## 9. 开发
-
-```bash
-pnpm install
-pnpm build        # 编译
-pnpm dev          # 监听模式
-pnpm test         # 运行测试
-```
+### 便捷函数
 
-**技术栈：** TypeScript, Vitest
+| 函数 | 说明 |
+|---|---|
+| `defineService(fn)` | 注册服务到默认容器 |
+| `loadService(props)` | 加载服务实例 |
+| `isService(props)` | 判断是否为合法服务注册对象 |
 
-## License
+### Container
 
-MIT
+| 方法 | 说明 |
+|---|---|
+| `register(fn)` | 注册服务 |
+| `resolve(props)` | 解析服务 |
+| `hasService(fn)` | 检查函数是否已注册 |
+| `hasMeta(id)` | 检查运行时元数据 |
+| `getIdByService(fn)` | 通过函数获取 ID |
+| `getMetaById(id)` | 通过 ID 获取元数据 |
+| `shutdown()` | 销毁所有服务 |

package/dist/index.d.ts

@@ -2,102 +2,100 @@ export type ServiceCutDownFunction = () => unknown | Promise<unknown>;
 export type ServiceCutDownHandler = (fn: ServiceCutDownFunction) => void;
 export type ServiceFunction<R> = (fn: ServiceCutDownHandler) => R | Promise<R>;
 declare const sericeFlag: unique symbol;
+export type ServiceLifecycleStage = 'init' | 'ready' | 'stopping' | 'stopped';
 export interface ServiceRegisterProps<R> {
     id: number;
     fn: ServiceFunction<R>;
     flag: typeof sericeFlag;
 }
+export interface ContainerOptions {
+    startTimeoutMs?: number;
+    shutdownTimeoutMs?: number;
+}
+export type ContainerEvent = {
+    type: 'service:init';
+    id: number;
+} | {
+    type: 'service:ready';
+    id: number;
+    durationMs: number;
+} | {
+    type: 'service:error';
+    id: number;
+    error: any;
+    durationMs: number;
+} | {
+    type: 'service:shutdown:start';
+    id: number;
+} | {
+    type: 'service:shutdown:done';
+    id: number;
+    durationMs: number;
+} | {
+    type: 'service:shutdown:error';
+    id: number;
+    error: any;
+} | {
+    type: 'container:shutdown:start';
+} | {
+    type: 'container:shutdown:done';
+    durationMs: number;
+} | {
+    type: 'container:error';
+    error: any;
+};
 interface Paddings<R = any> {
     status: -1 | 0 | 1;
+    lifecycle: ServiceLifecycleStage;
     value: R;
     error?: any;
     queue: Set<{
         resolve: (value: R) => void;
         reject: (error: any) => void;
     }>;
+    startedAt: number;
+    endedAt?: number;
 }
 export declare class Container {
+    private readonly options;
     private id;
     private readonly packages;
     private readonly paddings;
+    private readonly dependencies;
+    private readonly dependents;
     private readonly shutdownFunctions;
     private readonly shutdownQueues;
+    private readonly startupOrder;
+    private readonly listeners;
+    private readonly context;
+    constructor(options?: ContainerOptions);
+    private emit;
     private getId;
-    /**
-     * 注册服务到容器
-     * @param fn - 服务函数
-     * @returns - 服务注册信息
-     */
+    private hasPath;
+    private trackDependency;
+    onEvent(listener: (event: ContainerEvent) => void): () => boolean;
+    offEvent(listener: (event: ContainerEvent) => void): void;
+    getLifecycle(id: number): ServiceLifecycleStage | undefined;
+    getDependencyGraph(): {
+        nodes: number[];
+        edges: {
+            from: number;
+            to: number;
+        }[];
+    };
+    getStartupOrder(): number[];
     register<R>(fn: ServiceFunction<R>): ServiceRegisterProps<R>;
-    /**
-     * 从容器中解决服务
-     * 当服务未注册时，会自动注册并运行服务
-     * 当服务已注册时，会返回服务实例
-     * 当服务运行中时，会等待服务运行完成并返回服务实例
-     * 当服务运行完成时，会返回服务实例
-     * 当服务运行失败时，会返回错误
-     * 多次调用正在运行中的服务时，不会重复运行同一服务，而是将等待状态（Promise）加入到等待队列，
-     * 直到服务运行完毕被 resolve 或者 reject
-     * @param props - 服务注册信息
-     * @returns - 服务实例
-     */
     resolve<R>(props: ServiceRegisterProps<R>): Promise<R>;
-    /**
-     * 运行服务
-     * 注意：运行服务过程中将自动按顺序注册销毁函数，
-     * 如果服务启动失败，则立即执行销毁函数，并返回错误
-     * 销毁函数执行都是逆向执行的
-     * 先加入的后执行，后加入的先执行
-     * @param id - 服务ID
-     * @param fn - 服务函数
-     * @param callback - 回调函数
-     */
     private run;
-    /**
-     * 销毁服务
-     * @param id - 服务ID
-     * @returns - 销毁结果
-     */
     private shutdownService;
-    /**
-     * 销毁所有服务
-     * 销毁过程都是逆向销毁的，
-     * 先注册的后销毁，后注册的先销毁
-     * @returns - 销毁结果
-     */
     shutdown(): Promise<void>;
-    /**
-     * 检查服务是否已注册
-     * @param fn - 服务函数
-     * @returns - 是否已注册
-     */
     hasService<R>(fn: ServiceFunction<R>): boolean;
-    /**
-     * 检查服务是否已运行
-     * @param id - 服务ID
-     * @returns - 是否已运行
-     */
     hasMeta(id: number): boolean;
-    /**
-     * 获取服务ID
-     * @param fn - 服务函数
-     * @returns - 服务ID
-     */
     getIdByService<R>(fn: ServiceFunction<R>): number | undefined;
-    /**
-     * 获取服务元数据
-     * @param id - 服务ID
-     * @returns - 服务元数据
-     */
     getMetaById(id: number): Paddings<any> | undefined;
 }
 export declare const container: Container;
 export declare function defineService<R>(fn: ServiceFunction<R>): ServiceRegisterProps<R>;
 export declare function loadService<R>(props: ServiceRegisterProps<R>): Promise<R>;
-/**
- * 判断是否为服务
- * @param props - 服务注册信息
- * @returns - 是否为服务
- */
 export declare function isService<R>(props: ServiceRegisterProps<R>): boolean;
 export default container;

package/dist/index.js

@@ -1,10 +1,45 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
 const sericeFlag = Symbol('service');
+async function withTimeout(promise, timeoutMs, message) {
+    if (!timeoutMs || timeoutMs <= 0)
+        return promise;
+    let timer;
+    const timeoutPromise = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new Error(message || `Operation timeout after ${timeoutMs}ms`)), timeoutMs);
+    });
+    try {
+        return await Promise.race([promise, timeoutPromise]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
 export class Container {
+    options;
     id = 1;
     packages = new Map();
     paddings = new Map();
+    dependencies = new Map();
+    dependents = new Map();
     shutdownFunctions = new Map();
     shutdownQueues = [];
+    startupOrder = [];
+    listeners = new Set();
+    context = new AsyncLocalStorage();
+    constructor(options = {}) {
+        this.options = options;
+    }
+    emit(event) {
+        for (const listener of this.listeners) {
+            try {
+                listener(event);
+            }
+            catch {
+                // ignore listener errors
+            }
+        }
+    }
     getId() {
         let i = this.id++;
         if (i >= Number.MAX_SAFE_INTEGER) {
@@ -12,11 +47,65 @@ export class Container {
         }
         return i;
     }
-    /**
-     * 注册服务到容器
-     * @param fn - 服务函数
-     * @returns - 服务注册信息
-     */
+    hasPath(from, to, visited = new Set()) {
+        if (from === to)
+            return true;
+        if (visited.has(from))
+            return false;
+        visited.add(from);
+        const deps = this.dependencies.get(from);
+        if (!deps)
+            return false;
+        for (const next of deps) {
+            if (this.hasPath(next, to, visited))
+                return true;
+        }
+        return false;
+    }
+    trackDependency(parentId, childId) {
+        if (parentId === childId) {
+            throw new Error(`circular dependency detected: ${parentId} -> ${childId}`);
+        }
+        if (!this.dependencies.has(parentId)) {
+            this.dependencies.set(parentId, new Set());
+        }
+        if (!this.dependents.has(childId)) {
+            this.dependents.set(childId, new Set());
+        }
+        const parentDeps = this.dependencies.get(parentId);
+        if (!parentDeps.has(childId)) {
+            if (this.hasPath(childId, parentId)) {
+                const error = new Error(`circular dependency detected: ${parentId} -> ${childId}`);
+                this.emit({ type: 'container:error', error });
+                throw error;
+            }
+            parentDeps.add(childId);
+            this.dependents.get(childId).add(parentId);
+        }
+    }
+    onEvent(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+    offEvent(listener) {
+        this.listeners.delete(listener);
+    }
+    getLifecycle(id) {
+        return this.paddings.get(id)?.lifecycle;
+    }
+    getDependencyGraph() {
+        const nodes = Array.from(this.packages.values()).sort((a, b) => a - b);
+        const edges = [];
+        for (const [id, deps] of this.dependencies.entries()) {
+            for (const dep of deps) {
+                edges.push({ from: id, to: dep });
+            }
+        }
+        return { nodes, edges };
+    }
+    getStartupOrder() {
+        return [...this.startupOrder];
+    }
     register(fn) {
         if (this.packages.has(fn)) {
             return { id: this.packages.get(fn), fn, flag: sericeFlag };
@@ -25,20 +114,13 @@ export class Container {
         this.packages.set(fn, id);
         return { id, fn, flag: sericeFlag };
     }
-    /**
-     * 从容器中解决服务
-     * 当服务未注册时，会自动注册并运行服务
-     * 当服务已注册时，会返回服务实例
-     * 当服务运行中时，会等待服务运行完成并返回服务实例
-     * 当服务运行完成时，会返回服务实例
-     * 当服务运行失败时，会返回错误
-     * 多次调用正在运行中的服务时，不会重复运行同一服务，而是将等待状态（Promise）加入到等待队列，
-     * 直到服务运行完毕被 resolve 或者 reject
-     * @param props - 服务注册信息
-     * @returns - 服务实例
-     */
     resolve(props) {
         const { id, fn } = props;
+        const stack = this.context.getStore() || [];
+        const parentId = stack.length ? stack[stack.length - 1] : undefined;
+        if (parentId !== undefined) {
+            this.trackDependency(parentId, id);
+        }
         return new Promise((resolve, reject) => {
             if (!this.paddings.has(id)) {
                 return this.run(id, fn, (e, v) => {
@@ -64,20 +146,20 @@ export class Container {
             }
         });
     }
-    /**
-     * 运行服务
-     * 注意：运行服务过程中将自动按顺序注册销毁函数，
-     * 如果服务启动失败，则立即执行销毁函数，并返回错误
-     * 销毁函数执行都是逆向执行的
-     * 先加入的后执行，后加入的先执行
-     * @param id - 服务ID
-     * @param fn - 服务函数
-     * @param callback - 回调函数
-     */
     run(id, fn, callback) {
-        const state = { status: 0, value: undefined, queue: new Set() };
+        const state = {
+            status: 0,
+            lifecycle: 'init',
+            value: undefined,
+            queue: new Set(),
+            startedAt: Date.now(),
+        };
         this.paddings.set(id, state);
-        const curDown = (fn) => {
+        if (!this.startupOrder.includes(id)) {
+            this.startupOrder.push(id);
+        }
+        this.emit({ type: 'service:init', id });
+        const curDown = (cutDownFn) => {
             if (!this.shutdownQueues.includes(id)) {
                 this.shutdownQueues.push(id);
             }
@@ -85,13 +167,19 @@ export class Container {
                 this.shutdownFunctions.set(id, []);
             }
             const pools = this.shutdownFunctions.get(id);
-            if (!pools.includes(fn)) {
-                pools.push(fn);
+            if (!pools.includes(cutDownFn)) {
+                pools.push(cutDownFn);
             }
         };
-        Promise.resolve(fn(curDown)).then((value) => {
+        const parentStack = this.context.getStore() || [];
+        const startupPromise = this.context.run([...parentStack, id], () => Promise.resolve(fn(curDown)));
+        withTimeout(startupPromise, this.options.startTimeoutMs, `service startup timeout: ${id} exceeded ${this.options.startTimeoutMs}ms`).then((value) => {
             state.status = 1;
+            state.lifecycle = 'ready';
             state.value = value;
+            state.endedAt = Date.now();
+            const durationMs = state.endedAt - state.startedAt;
+            this.emit({ type: 'service:ready', id, durationMs });
             for (const queue of state.queue) {
                 queue.resolve(value);
             }
@@ -99,81 +187,74 @@ export class Container {
             callback(null, value);
         }).catch(e => {
             state.status = -1;
+            state.lifecycle = 'stopping';
             state.error = e;
-            // 通知所有等待的任务结果是失败的，并清空等待队列
+            state.endedAt = Date.now();
+            const durationMs = state.endedAt - state.startedAt;
+            this.emit({ type: 'service:error', id, error: e, durationMs });
             const clear = () => {
+                state.lifecycle = 'stopped';
                 for (const queue of state.queue) {
                     queue.reject(e);
                 }
                 state.queue.clear();
                 callback(e);
             };
-            // 已运行的销毁函数立即执行，
-            // 无论成功失败都通知所有等待的任务结果是失败的，并清空等待队列
             this.shutdownService(id)
                 .then(clear)
-                .catch(clear);
+                .catch((shutdownError) => {
+                this.emit({ type: 'service:shutdown:error', id, error: shutdownError });
+                clear();
+            });
         });
     }
-    /**
-     * 销毁服务
-     * @param id - 服务ID
-     * @returns - 销毁结果
-     */
     async shutdownService(id) {
         if (this.shutdownQueues.includes(id)) {
+            const meta = this.paddings.get(id);
+            if (meta) {
+                meta.lifecycle = 'stopping';
+            }
+            this.emit({ type: 'service:shutdown:start', id });
+            const startedAt = Date.now();
             const pools = this.shutdownFunctions.get(id);
             let i = pools.length;
             while (i--) {
-                await Promise.resolve(pools[i]());
+                const teardown = pools[i];
+                try {
+                    await withTimeout(Promise.resolve(teardown()), this.options.shutdownTimeoutMs, `service shutdown timeout: ${id} exceeded ${this.options.shutdownTimeoutMs}ms`);
+                }
+                catch (error) {
+                    this.emit({ type: 'service:shutdown:error', id, error });
+                }
             }
             this.shutdownFunctions.delete(id);
             this.shutdownQueues.splice(this.shutdownQueues.indexOf(id), 1);
+            if (meta) {
+                meta.lifecycle = 'stopped';
+            }
+            this.emit({ type: 'service:shutdown:done', id, durationMs: Date.now() - startedAt });
         }
     }
-    /**
-     * 销毁所有服务
-     * 销毁过程都是逆向销毁的，
-     * 先注册的后销毁，后注册的先销毁
-     * @returns - 销毁结果
-     */
     async shutdown() {
+        const startedAt = Date.now();
+        this.emit({ type: 'container:shutdown:start' });
         let i = this.shutdownQueues.length;
         while (i--) {
             await this.shutdownService(this.shutdownQueues[i]);
         }
         this.shutdownFunctions.clear();
         this.shutdownQueues.length = 0;
+        this.emit({ type: 'container:shutdown:done', durationMs: Date.now() - startedAt });
     }
-    /**
-     * 检查服务是否已注册
-     * @param fn - 服务函数
-     * @returns - 是否已注册
-     */
     hasService(fn) {
         return this.packages.has(fn);
     }
-    /**
-     * 检查服务是否已运行
-     * @param id - 服务ID
-     * @returns - 是否已运行
-     */
     hasMeta(id) {
         return this.paddings.has(id);
     }
-    /**
-     * 获取服务ID
-     * @param fn - 服务函数
-     * @returns - 服务ID
-     */
     getIdByService(fn) {
         return this.packages.get(fn);
     }
-    /**
-     * 获取服务元数据
-     * @param id - 服务ID
-     * @returns - 服务元数据
-     */
     getMetaById(id) {
         return this.paddings.get(id);
     }
@@ -185,11 +266,6 @@ export function defineService(fn) {
 export function loadService(props) {
     return container.resolve(props);
 }
-/**
- * 判断是否为服务
- * @param props - 服务注册信息
- * @returns - 是否为服务
- */
 export function isService(props) {
     return props.flag === sericeFlag && typeof props.id === 'number' && typeof props.fn === 'function';
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hile/core",
-  "version": "1.0.16",
+  "version": "1.0.18",
   "description": "Hile core - lightweight async service container",
   "type": "module",
   "main": "./dist/index.js",
@@ -23,5 +23,5 @@
     "@types/node": "^25.3.1",
     "vitest": "^4.0.18"
   },
-  "gitHead": "a6eab4e7803f0df7d4bca9a0bdeca76692dbc883"
+  "gitHead": "81347b9de460b693ed82af46c0f4a287d4527323"
 }