@hile/core 1.0.17 → 1.0.18

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.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'
@@ -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()` | 销毁所有服务并执行清理回调 |
+| `onEvent(listener)` | 订阅容器事件，返回取消订阅函数 |
+| `offEvent(listener)` | 取消订阅 |
+| `getLifecycle(id)` | 获取服务生命周期阶段 |
+| `getDependencyGraph()` | 获取依赖图 `{ nodes, edges }` |
+| `getStartupOrder()` | 获取服务启动顺序（首次启动顺序） |
 | `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.17",
+  "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": "6672fc4cdc551c4265912cc85ee2e96fc44bc4c9"
+  "gitHead": "81347b9de460b693ed82af46c0f4a287d4527323"
 }