@hile/core 1.0.16 → 1.0.17

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,35 @@ 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` 函数定义服务。同步函数中直接 `throw` 的错误无法触发销毁机制。
+- 同一函数引用重复注册只执行一次
+- 清理函数错误不会覆盖原始业务错误
 
-### 手动销毁（Graceful Shutdown）
+> 建议始终使用 `async` 服务函数，确保异常路径可正确触发销毁机制。
 
-调用 `container.shutdown()` 可手动触发所有已注册服务的销毁回调，适用于进程退出时优雅关闭资源：
+### 6) 手动销毁（Graceful Shutdown）
 
 ```typescript
 import container from '@hile/core'
@@ -135,24 +131,20 @@ process.on('SIGTERM', async () => {
 })
 ```
 
-销毁按 **服务注册逆序** 执行：后注册的服务先销毁。调用后销毁队列清空，重复调用不会再次执行。
-
-### 服务校验（isService）
-
-使用 `isService` 判断一个对象是否为合法的服务注册信息。内部通过不可伪造的 Symbol 标识校验，确保只有通过 `defineService` / `container.register` 创建的对象才会返回 `true`：
+### 7) 服务校验（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 +160,31 @@ 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>`。按服务注册逆序执行所有销毁回调 |
+| `register(fn)` | 注册服务（同函数引用去重） |
+| `resolve(props)` | 加载服务（执行、等待或返回缓存） |
+| `hasService(fn)` | 检查函数是否已注册 |
+| `hasMeta(id)` | 检查服务是否已有运行时元数据 |
+| `getIdByService(fn)` | 通过函数获取服务 ID |
+| `getMetaById(id)` | 通过 ID 获取运行时元数据 |
+| `shutdown()` | 销毁所有服务并执行清理回调 |
 
 ### 服务状态
 
-| 状态 | 值 | `resolve` 的行为 |
-|------|---|-----------------|
-| 从未运行 | — | 执行服务函数 |
+| 状态 | 值 | `resolve` 行为 |
+|------|---|---------------|
+| 未运行 | — | 执行服务函数 |
 | 运行中 | `0` | 加入等待队列 |
 | 已成功 | `1` | 返回缓存值 |
 | 已失败 | `-1` | 返回缓存错误 |
@@ -201,9 +193,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hile/core",
-  "version": "1.0.16",
+  "version": "1.0.17",
   "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": "6672fc4cdc551c4265912cc85ee2e96fc44bc4c9"
 }