@hile/core 1.0.8

package/README.md

@@ -0,0 +1,181 @@
+# Hile
+
+轻量级异步服务容器，提供单例管理、并发请求合并和资源生命周期销毁。纯 TypeScript 实现，零运行时依赖。
+
+## 安装
+
+```bash
+pnpm add @hile/core
+```
+
+## 快速开始
+
+```typescript
+import { defineService, loadService } from '@hile/core'
+
+// 定义服务
+const greeterService = defineService(async (shutdown) => {
+  return {
+    hello(name: string) {
+      return `Hello, ${name}!`
+    }
+  }
+})
+
+// 加载并使用
+const greeter = await loadService(greeterService)
+greeter.hello('World') // "Hello, World!"
+```
+
+## 核心概念
+
+### 定义服务
+
+使用 `defineService` 注册一个服务。服务函数接收一个 `shutdown` 参数，用于注册资源清理回调。
+
+```typescript
+import { defineService } from '@hile/core'
+
+export const databaseService = defineService(async (shutdown) => {
+  const pool = await createPool('postgres://localhost:5432/app')
+  shutdown(() => pool.end())
+  return pool
+})
+```
+
+### 加载服务
+
+使用 `loadService` 获取服务实例。容器保证服务函数只执行一次，后续调用直接返回缓存结果。
+
+```typescript
+import { loadService } from '@hile/core'
+import { databaseService } from './services/database'
+
+const db = await loadService(databaseService)
+const users = await db.query('SELECT * FROM users')
+```
+
+### 并发请求合并
+
+多个地方同时请求同一服务时，服务函数不会重复执行，所有调用者共享同一结果。
+
+```typescript
+// 三个并发调用，服务函数只执行一次
+const [r1, r2, r3] = await Promise.all([
+  loadService(heavyService),
+  loadService(heavyService),
+  loadService(heavyService),
+])
+// r1 === r2 === r3
+```
+
+### 服务间依赖
+
+在服务函数内部通过 `loadService` 加载所依赖的其他服务：
+
+```typescript
+import { defineService, loadService } from '@hile/core'
+import { databaseService } from './database'
+import { cacheService } from './cache'
+
+export const userService = defineService(async (shutdown) => {
+  const db = await loadService(databaseService)
+  const cache = await loadService(cacheService)
+
+  return {
+    async getById(id: number) {
+      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
+    }
+  }
+})
+```
+
+### 资源销毁（Shutdown）
+
+服务函数的第一个参数 `shutdown` 是一个注册器，用于在初始化过程中注册清理回调。当服务启动失败时，容器会自动执行已注册的清理回调。
+
+```typescript
+export const connectionService = defineService(async (shutdown) => {
+  const primary = await connectPrimary()
+  shutdown(() => primary.disconnect())    // 最后执行
+
+  const replica = await connectReplica()
+  shutdown(() => replica.disconnect())    // 第 2 个执行
+
+  const cache = await initCache()
+  shutdown(() => cache.flush())           // 最先执行
+
+  return { primary, replica, cache }
+})
+```
+
+**关键特性：**
+
+- 销毁回调按 **逆序（LIFO）** 执行——后注册的先执行
+- 支持异步清理函数
+- 同一函数引用多次注册只会执行一次
+- 清理函数自身的错误不会影响原始错误的传播
+
+> **注意：** 请使用 `async` 函数定义服务。同步函数中直接 `throw` 的错误无法触发销毁机制。
+
+## 隔离容器
+
+除默认容器外，可以创建独立的 `Container` 实例，实现服务作用域隔离：
+
+```typescript
+import { Container } from '@hile/core'
+
+const container = new Container()
+
+const service = container.register(async (shutdown) => {
+  return { value: 42 }
+})
+
+const result = await container.resolve(service)
+```
+
+## API
+
+### 便捷函数
+
+| 函数 | 说明 |
+|------|------|
+| `defineService(fn)` | 注册服务到默认容器，返回 `ServiceRegisterProps` |
+| `loadService(props)` | 从默认容器加载服务，返回 `Promise<R>` |
+
+### Container
+
+| 方法 | 说明 |
+|------|------|
+| `register(fn)` | 注册服务。同一函数引用只注册一次，返回 `ServiceRegisterProps` |
+| `resolve(props)` | 加载服务。根据当前状态决定执行、等待或返回缓存 |
+| `hasService(fn)` | 检查服务函数是否已注册 |
+| `hasMeta(id)` | 检查服务是否已运行（存在运行时元数据） |
+| `getIdByService(fn)` | 根据函数引用获取服务 ID |
+| `getMetaById(id)` | 根据服务 ID 获取运行时元数据 |
+
+### 服务状态
+
+| 状态 | 值 | `resolve` 的行为 |
+|------|---|-----------------|
+| 从未运行 | — | 执行服务函数 |
+| 运行中 | `0` | 加入等待队列 |
+| 已成功 | `1` | 返回缓存值 |
+| 已失败 | `-1` | 返回缓存错误 |
+
+## 开发
+
+```bash
+pnpm install
+pnpm build        # 编译
+pnpm dev          # 监听模式
+pnpm test         # 运行测试
+```
+
+## License
+
+MIT

package/SKILL.md

@@ -0,0 +1,418 @@
+# Hile
+
+Hile 是一个轻量级异步服务容器。本文档是面向 AI 编码模型和人类开发者的 **代码生成规范**，阅读后应能正确地使用本库编写符合架构规则的代码。
+
+---
+
+## 1. 架构总览
+
+Hile 的核心是 `Container`（服务容器）。所有服务都必须经过 **定义 → 加载** 两个步骤才能使用。容器保证：
+
+- 每个服务函数只执行一次（**单例**）
+- 并发请求同一服务时自动合并（**不重复执行**）
+- 服务启动失败时自动执行已注册的清理回调（**销毁机制**）
+
+模块默认导出了一个全局容器实例，并提供 `defineService` / `loadService` 两个便捷函数。
+
+---
+
+## 2. 类型签名
+
+生成代码时，必须严格遵循以下类型：
+
+```typescript
+// 销毁回调：无参数，可返回 Promise
+type ServiceCutDownFunction = () => unknown | Promise<unknown>;
+
+// 销毁注册器：在服务函数内部调用，将清理回调注册到容器
+type ServiceCutDownHandler = (fn: ServiceCutDownFunction) => void;
+
+// 服务函数：第一个参数固定为销毁注册器，返回值为同步值或 Promise
+type ServiceFunction<R> = (shutdown: ServiceCutDownHandler) => R | Promise<R>;
+
+// 服务注册信息：由 defineService/register 返回，作为 loadService/resolve 的入参
+interface ServiceRegisterProps<R> {
+  id: number;
+  fn: ServiceFunction<R>;
+}
+```
+
+---
+
+## 3. 代码生成模板
+
+### 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 加载服务
+
+**模板：**
+
+```typescript
+import { loadService } from '@hile/core'
+import { databaseService } from './services/database'
+
+const db = await loadService(databaseService)
+```
+
+**规则：**
+- **永远** 使用 `loadService()` 获取服务实例，**不要** 直接调用服务函数
+- `loadService` 返回 `Promise`，**必须** `await`
+- 可以在任何地方多次调用 `loadService(同一个服务)`，容器保证只执行一次
+
+### 3.3 服务间依赖
+
+当一个服务依赖另一个服务时，在服务函数内部通过 `loadService` 加载依赖：
+
+```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
+})
+```
+
+**规则：**
+- 依赖的服务通过 `import` 引入其 `ServiceRegisterProps`，然后在函数体内 `loadService` 加载
+- **不要** 将 `loadService` 的结果缓存到模块作用域变量中
+- **不要** 在服务函数外部调用 `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 cache = await initCache()
+  shutdown(() => cache.flush())           // 注册第 3 个 → 最先执行
+
+  return { primary, replica, cache }
+})
+```
+
+**规则：**
+- 每初始化一个需要清理的资源后，**立即** 调用 `shutdown()` 注册对应的清理函数
+- 不要把所有清理逻辑放在一个 shutdown 里，**每个资源对应一个 shutdown 调用**
+- 销毁函数按 **逆序（LIFO）** 执行：后注册的先执行，先注册的后执行
+- 销毁函数可以是 `async`，容器会依次 `await`
+- 同一个函数引用多次传给 `shutdown()` 只会注册一次
+
+---
+
+## 4. 强制规则（生成代码时必须遵守）
+
+| # | 规则 | 原因 |
+|---|------|------|
+| 1 | 服务函数**必须**使用 `async` 声明 | 同步 `throw` 不会触发销毁机制，只有异步 reject 才会触发 |
+| 2 | 服务函数第一个参数**必须**是 `shutdown` | 这是容器注入的销毁注册器，即使不使用也要声明 |
+| 3 | `defineService` 的结果**必须**赋给模块级 `export const` | 服务基于函数引用去重，引用必须稳定 |
+| 4 | **不要**在 `defineService` 内直接写匿名函数再传给另一个函数 | 每次调用会创建新引用，导致重复注册 |
+| 5 | **不要**手动构造 `ServiceRegisterProps` 对象 | 必须通过 `defineService` 或 `container.register` 获取 |
+| 6 | **不要**缓存 `loadService` 的结果到模块顶层变量 | 服务可能尚未初始化，应在需要时 `await loadService()` |
+| 7 | 每个外部资源初始化后**立即**注册 `shutdown` | 确保初始化中途失败时已创建的资源能被正确清理 |
+| 8 | 一个文件只定义一个服务 | 保持服务职责单一、依赖清晰 |
+
+---
+
+## 5. 完整示例：项目结构
+
+```
+src/
+├── services/
+│   ├── config.ts        # 配置服务
+│   ├── database.ts      # 数据库服务（依赖 config）
+│   ├── cache.ts         # 缓存服务（依赖 config）
+│   └── user.ts          # 用户服务（依赖 database, cache）
+└── main.ts              # 入口
+```
+
+### services/config.ts
+
+```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
+})
+```
+
+### 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
+})
+```
+
+### 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>` | 加载服务，返回服务实例 |
+
+### 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 查运行时元数据 |
+
+### 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. 内部机制（供理解，不供直接调用）
+
+### 数据结构
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `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）时自动触发；成功时不触发
+
+### 函数去重机制
+
+容器通过 `===` 比较函数引用。两个函数即使代码完全相同，只要引用不同就会被视为不同服务。因此服务必须定义为模块级常量。
+
+---
+
+## 9. 开发
+
+```bash
+pnpm install
+pnpm build        # 编译
+pnpm dev          # 监听模式
+pnpm test         # 运行测试
+```
+
+**技术栈：** TypeScript, Vitest
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,95 @@
+export type ServiceCutDownFunction = () => unknown | Promise<unknown>;
+export type ServiceCutDownHandler = (fn: ServiceCutDownFunction) => void;
+export type ServiceFunction<R> = (fn: ServiceCutDownHandler) => R | Promise<R>;
+export interface ServiceRegisterProps<R> {
+    id: number;
+    fn: ServiceFunction<R>;
+}
+interface Paddings<R = any> {
+    status: -1 | 0 | 1;
+    value: R;
+    error?: any;
+    queue: Set<{
+        resolve: (value: R) => void;
+        reject: (error: any) => void;
+    }>;
+}
+export declare class Container {
+    private id;
+    private readonly packages;
+    private readonly paddings;
+    private readonly shutdownFunctions;
+    private readonly shutdownQueues;
+    private getId;
+    /**
+     * 注册服务到容器
+     * @param fn - 服务函数
+     * @returns - 服务注册信息
+     */
+    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 - 销毁结果
+     */
+    private shutdown;
+    /**
+     * 检查服务是否已注册
+     * @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>;
+export default container;

package/dist/index.js

@@ -0,0 +1,187 @@
+export class Container {
+    id = 1;
+    packages = new Map();
+    paddings = new Map();
+    shutdownFunctions = new Map();
+    shutdownQueues = [];
+    getId() {
+        let i = this.id++;
+        if (i >= Number.MAX_SAFE_INTEGER) {
+            i = this.id = 1;
+        }
+        return i;
+    }
+    /**
+     * 注册服务到容器
+     * @param fn - 服务函数
+     * @returns - 服务注册信息
+     */
+    register(fn) {
+        if (this.packages.has(fn)) {
+            return { id: this.packages.get(fn), fn };
+        }
+        const id = this.getId();
+        this.packages.set(fn, id);
+        return { id, fn };
+    }
+    /**
+     * 从容器中解决服务
+     * 当服务未注册时，会自动注册并运行服务
+     * 当服务已注册时，会返回服务实例
+     * 当服务运行中时，会等待服务运行完成并返回服务实例
+     * 当服务运行完成时，会返回服务实例
+     * 当服务运行失败时，会返回错误
+     * 多次调用正在运行中的服务时，不会重复运行同一服务，而是将等待状态（Promise）加入到等待队列，
+     * 直到服务运行完毕被 resolve 或者 reject
+     * @param props - 服务注册信息
+     * @returns - 服务实例
+     */
+    resolve(props) {
+        const { id, fn } = props;
+        return new Promise((resolve, reject) => {
+            if (!this.paddings.has(id)) {
+                return this.run(id, fn, (e, v) => {
+                    if (e) {
+                        reject(e);
+                    }
+                    else {
+                        resolve(v);
+                    }
+                });
+            }
+            const state = this.paddings.get(id);
+            switch (state.status) {
+                case 0:
+                    state.queue.add({ resolve, reject });
+                    break;
+                case 1:
+                    resolve(state.value);
+                    break;
+                case -1:
+                    reject(state.error);
+                    break;
+            }
+        });
+    }
+    /**
+     * 运行服务
+     * 注意：运行服务过程中将自动按顺序注册销毁函数，
+     * 如果服务启动失败，则立即执行销毁函数，并返回错误
+     * 销毁函数执行都是逆向执行的
+     * 先加入的后执行，后加入的先执行
+     * @param id - 服务ID
+     * @param fn - 服务函数
+     * @param callback - 回调函数
+     */
+    run(id, fn, callback) {
+        const state = { status: 0, value: undefined, queue: new Set() };
+        this.paddings.set(id, state);
+        const curDown = (fn) => {
+            if (!this.shutdownQueues.includes(id)) {
+                this.shutdownQueues.push(id);
+            }
+            if (!this.shutdownFunctions.has(id)) {
+                this.shutdownFunctions.set(id, []);
+            }
+            const pools = this.shutdownFunctions.get(id);
+            if (!pools.includes(fn)) {
+                pools.push(fn);
+            }
+        };
+        Promise.resolve(fn(curDown)).then((value) => {
+            state.status = 1;
+            state.value = value;
+            for (const queue of state.queue) {
+                queue.resolve(value);
+            }
+            state.queue.clear();
+            callback(null, value);
+        }).catch(e => {
+            state.status = -1;
+            state.error = e;
+            // 通知所有等待的任务结果是失败的，并清空等待队列
+            const clear = () => {
+                for (const queue of state.queue) {
+                    queue.reject(e);
+                }
+                state.queue.clear();
+                callback(e);
+            };
+            // 已运行的销毁函数立即执行，
+            // 无论成功失败都通知所有等待的任务结果是失败的，并清空等待队列
+            this.shutdownService(id)
+                .then(clear)
+                .catch(clear);
+        });
+    }
+    /**
+     * 销毁服务
+     * @param id - 服务ID
+     * @returns - 销毁结果
+     */
+    async shutdownService(id) {
+        if (this.shutdownQueues.includes(id)) {
+            const pools = this.shutdownFunctions.get(id);
+            let i = pools.length;
+            while (i--) {
+                await Promise.resolve(pools[i]());
+            }
+            this.shutdownFunctions.clear();
+            this.shutdownQueues.splice(this.shutdownQueues.indexOf(id), 1);
+        }
+    }
+    /**
+     * 销毁所有服务
+     * 销毁过程都是逆向销毁的，
+     * 先注册的后销毁，后注册的先销毁
+     * @returns - 销毁结果
+     */
+    async shutdown() {
+        let i = this.shutdownQueues.length;
+        while (i--) {
+            await this.shutdownService(this.shutdownQueues[i]);
+        }
+        this.shutdownFunctions.clear();
+        this.shutdownQueues.length = 0;
+    }
+    /**
+     * 检查服务是否已注册
+     * @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);
+    }
+}
+export const container = new Container();
+export function defineService(fn) {
+    return container.register(fn);
+}
+export function loadService(props) {
+    return container.resolve(props);
+}
+export default container;

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@hile/core",
+  "version": "1.0.8",
+  "description": "Hile core - lightweight async service container",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "build": "tsc -b",
+    "dev": "tsc -b --watch",
+    "test": "vitest run"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "SKILL.md"
+  ],
+  "author": "",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "^25.3.1",
+    "vitest": "^4.0.18"
+  },
+  "gitHead": "16396508dcd3a71359fd8371feefb2f621a92a76"
+}