@hile/core 1.0.17 → 1.0.19

package/README.md

@@ -120,7 +120,49 @@ export const connectionService = defineService(async (shutdown) => {
 
 > 建议始终使用 `async` 服务函数，确保异常路径可正确触发销毁机制。
 
-### 6) 手动销毁（Graceful Shutdown）
+### 6) 生命周期、超时与可观测事件
+
+容器支持显式生命周期阶段：`init -> ready -> stopping -> stopped`。
+
+可通过构造参数设置超时：
+
+```typescript
+import { Container } from '@hile/core'
+
+const container = new Container({
+  startTimeoutMs: 5_000,
+  shutdownTimeoutMs: 3_000,
+})
+```
+
+订阅事件：
+
+```typescript
+const off = container.on((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'
@@ -131,7 +173,7 @@ process.on('SIGTERM', async () => {
 })
 ```
 
-### 7) 服务校验（isService）
+### 9) 服务校验（isService）
 
 ```typescript
 import { defineService, isService } from '@hile/core'
@@ -172,13 +214,19 @@ const result = await container.resolve(service)
 
 | 方法 | 说明 |
 |------|------|
+| `new Container(options?)` | 创建容器，可配置启动/销毁超时 |
 | `register(fn)` | 注册服务（同函数引用去重） |
 | `resolve(props)` | 加载服务（执行、等待或返回缓存） |
+| `shutdown()` | 销毁所有服务并执行清理回调 |
+| `on(listener)` | 订阅容器事件，返回取消订阅函数 |
+| `off(listener)` | 取消订阅 |
+| `getLifecycle(id)` | 获取服务生命周期阶段 |
+| `getDependencyGraph()` | 获取依赖图 `{ nodes, edges }` |
+| `getStartupOrder()` | 获取服务启动顺序（首次启动顺序） |
 | `hasService(fn)` | 检查函数是否已注册 |
 | `hasMeta(id)` | 检查服务是否已有运行时元数据 |
 | `getIdByService(fn)` | 通过函数获取服务 ID |
 | `getMetaById(id)` | 通过 ID 获取运行时元数据 |
-| `shutdown()` | 销毁所有服务并执行清理回调 |
 
 ### 服务状态
 

package/SKILL.md

@@ -1,180 +1,112 @@
 ---
 name: hile-core
-description: @hile/core 的代码生成与使用规范。适用于定义/加载 Hile 服务、生命周期 shutdown 编排、或涉及 defineService、loadService、Container 等话题。
+description: "@hile/core 的代码生成与使用规范。适用于定义/加载 Hile 服务、生命周期编排、依赖图与容器事件相关场景。"
 ---
 
 # @hile/core SKILL
 
-本文档用于约束 AI 与开发者在使用 `@hile/core` 时的代码生成方式，目标是保证服务定义、依赖加载与资源销毁行为一致且可维护。
+本文档面向代码生成器与维护者，目标是确保生成代码严格符合容器语义。
 
-## 1. 架构概览
+## 1. 强约束（必须遵守）
 
-Hile 以 `Container` 为核心，服务遵循“定义 → 加载”两阶段：
+1. 服务必须使用 `async (shutdown)` 形态定义。
+2. 只能通过 `defineService` / `container.register` 产出服务对象。
+3. 只能通过 `loadService` / `container.resolve` 获取服务实例。
+4. 外部资源创建后必须立即注册 `shutdown`。
+5. 禁止在模块顶层缓存 `await loadService(...)` 结果。
+6. 依赖服务必须在服务函数内部加载。
+7. 多个 teardown 默认按 LIFO 顺序执行。
 
-- 单例：同一服务函数仅初始化一次
-- 并发合并：并发加载同一服务时共享同一初始化过程
-- 失败回收：初始化失败时自动执行已注册的清理回调
+## 2. 生命周期与超时约束
 
-模块默认导出全局容器，并提供 `defineService` / `loadService` 便捷函数。
+容器生命周期：`init -> ready -> stopping -> stopped`。
 
-## 2. 关键类型
+- 启动超时：`new Container({ startTimeoutMs })`
+- 销毁超时：`new Container({ shutdownTimeoutMs })`
 
-```typescript
-type ServiceCutDownFunction = () => unknown | Promise<unknown>;
-type ServiceCutDownHandler = (fn: ServiceCutDownFunction) => void;
-type ServiceFunction<R> = (shutdown: ServiceCutDownHandler) => R | Promise<R>;
-
-const sericeFlag = Symbol('service');
+生成代码时：
 
-interface ServiceRegisterProps<R> {
-  id: number;
-  fn: ServiceFunction<R>;
-  flag: typeof sericeFlag;
-}
-```
+- 不要吞掉启动超时错误。
+- 不要假设 teardown 一定成功；应允许 `service:shutdown:error` 事件出现。
 
-## 3. 标准模板
+## 3. 可观测事件约束
 
-### 3.1 定义服务
+允许订阅：`container.on(listener)`。
 
-```typescript
-import { defineService } from '@hile/core'
+关键事件：
 
-export const xxxService = defineService(async (shutdown) => {
-  const resource = await createResource()
-  shutdown(() => resource.close())
-  return resource
-})
-```
+- `service:init`
+- `service:ready`
+- `service:error`
+- `service:shutdown:start`
+- `service:shutdown:done`
+- `service:shutdown:error`
+- `container:shutdown:start`
+- `container:shutdown:done`
+- `container:error`
 
 规则：
 
-- 服务函数第一个参数固定为 `shutdown`
-- 推荐必须使用 `async`
-- `defineService` 结果需使用模块级 `export const` 暴露
-- 命名建议以 `Service` 结尾
+- 订阅后必须在生命周期结束时取消订阅。
+- 记录错误时保留原始 error 对象。
 
-### 3.2 加载服务
+## 4. 依赖图与循环依赖
 
-```typescript
-import { loadService } from '@hile/core'
-import { databaseService } from './services/database'
+容器会自动记录服务依赖并检测循环依赖：
 
-const db = await loadService(databaseService)
-```
+- `getDependencyGraph()`
+- `getStartupOrder()`
 
 规则：
 
-- 始终通过 `loadService` 获取实例
-- `loadService` 返回 Promise，必须 `await`
+- 不要绕开容器手动构建“隐式全局单例依赖”。
+- 出现 `circular dependency detected` 时应通过拆分服务职责或引入中间层服务解决。
 
-### 3.3 服务依赖服务
+## 5. 反模式（禁止）
 
-```typescript
-import { defineService, loadService } from '@hile/core'
-import { databaseService } from './database'
-
-export const userService = defineService(async (shutdown) => {
-  const db = await loadService(databaseService)
-  return new UserRepository(db)
-})
-```
-
-规则：
-
-- 在服务函数内部加载依赖
-- 不在模块顶层缓存 `loadService` 结果
-
-### 3.4 注册清理回调
+### 5.1 顶层缓存实例
 
 ```typescript
-export const connectionService = defineService(async (shutdown) => {
-  const a = await connectA()
-  shutdown(() => a.close())
-
-  const b = await connectB()
-  shutdown(() => b.close())
+// ✗
+const db = await loadService(dbService)
 
-  return { a, b }
-})
+// ✓
+export async function query(sql: string) {
+  const db = await loadService(dbService)
+  return db.query(sql)
+}
 ```
 
-规则：
-
-- 资源创建后立即注册清理
-- 回调按 LIFO 执行
-- 支持异步回调
-
-### 3.5 全局优雅关闭
+### 5.2 手动伪造服务对象
 
 ```typescript
-import container from '@hile/core'
+// ✗
+const fake = { id: 1, fn: async () => 1 }
 
-process.on('SIGTERM', async () => {
-  await container.shutdown()
-  process.exit(0)
-})
+// ✓
+const real = defineService(async () => 1)
 ```
 
-## 4. 强制规则
-
-1. 服务函数必须使用 `async`，避免同步 `throw` 破坏销毁机制。
-2. 不要手动构造 `ServiceRegisterProps`。
-3. 不要在工厂函数里动态调用 `defineService` 生成新引用。
-4. 不要在模块顶层 `await loadService(...)`。
-5. 每个外部资源都应对应一次 `shutdown` 注册。
-
-## 5. 常见反模式
-
-### 同步 throw
+### 5.3 不注册资源清理
 
 ```typescript
 // ✗
-export const bad = defineService((shutdown) => {
-  const r = createSync()
-  shutdown(() => r.close())
-  throw new Error('boom')
+export const bad = defineService(async () => {
+  return await createPool()
 })
 
 // ✓
 export const good = defineService(async (shutdown) => {
-  const r = await createAsync()
-  shutdown(() => r.close())
-  throw new Error('boom')
+  const pool = await createPool()
+  shutdown(() => pool.end())
+  return pool
 })
 ```
 
-### 顶层缓存服务实例
-
-```typescript
-// ✗
-const db = await loadService(databaseService)
-
-// ✓
-export async function query(sql: string) {
-  const db = await loadService(databaseService)
-  return db.query(sql)
-}
-```
-
-## 6. API 速查
-
-### 便捷函数
-
-| 函数 | 说明 |
-|---|---|
-| `defineService(fn)` | 注册服务到默认容器 |
-| `loadService(props)` | 加载服务实例 |
-| `isService(props)` | 判断是否为合法服务注册对象 |
-
-### Container
+## 6. 边界条件清单
 
-| 方法 | 说明 |
-|---|---|
-| `register(fn)` | 注册服务 |
-| `resolve(props)` | 解析服务 |
-| `hasService(fn)` | 检查函数是否已注册 |
-| `hasMeta(id)` | 检查运行时元数据 |
-| `getIdByService(fn)` | 通过函数获取 ID |
-| `getMetaById(id)` | 通过 ID 获取元数据 |
-| `shutdown()` | 销毁所有服务 |
+- [ ] 服务同步抛错路径是否可观测
+- [ ] 异步 reject 路径是否会触发 teardown
+- [ ] teardown 抛错是否不覆盖原始业务错误
+- [ ] 并发 resolve 同一服务是否只初始化一次
+- [ ] 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;
+    on(listener: (event: ContainerEvent) => void): () => boolean;
+    off(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);
+        }
+    }
+    on(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+    off(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.17",
+  "version": "1.0.19",
   "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": "6672fc4cdc551c4265912cc85ee2e96fc44bc4c9"
+  "gitHead": "4bb9d38b309e72c720f2cba579ce5c498d27e044"
 }