@hile/typeorm 1.0.8 → 1.0.9

package/README.md

@@ -1,6 +1,6 @@
 # @hile/typeorm
 
-基于 `@hile/core` 的 TypeORM 集成：将 TypeORM DataSource 封装为 Hile 服务（单例、随进程退出销毁），并提供事务封装 `transaction`。
+基于 `@hile/core` 的 TypeORM 集成：将 `DataSource` 封装为 Hile 服务（单例、可优雅销毁），并提供事务辅助函数 `transaction`。
 
 ## 安装
 
@@ -8,12 +8,10 @@
 pnpm add @hile/typeorm
 ```
 
-依赖 `@hile/core` 与 `typeorm`，请一并安装。
+同时安装依赖：`@hile/core`、`typeorm`。
 
 ## 快速开始
 
-通过环境变量配置数据库，用 `loadService` 获取 DataSource：
-
 ```typescript
 import { loadService } from '@hile/core'
 import typeormService from '@hile/typeorm'
@@ -24,7 +22,7 @@ const ds = await loadService(typeormService)
 
 ## 环境变量
 
-DataSource 从以下环境变量读取配置：
+默认 DataSource 从以下环境变量读取配置：
 
 | 变量 | 说明 |
 |------|------|
@@ -34,15 +32,20 @@ DataSource 从以下环境变量读取配置：
 | `TYPEORM_PASSWORD` | 密码 |
 | `TYPEORM_DATABASE` | 数据库名 |
 | `TYPEORM_PORT` | 端口 |
-| `TYPEORM_CHARSET` | 数据库字符集 |
+| `TYPEORM_CHARSET` | 字符集 |
 | `TYPEORM_ENTITY_PREFIX` | 实体表名前缀 |
 | `TYPEORM_ENTITIES` | 实体目录（单一路径） |
 
-行为：`synchronize: true`；当 `NODE_ENV === 'development'` 时开启 `logging`。未设置 `TYPEORM_ENTITIES` 时实体列表为空。连接在进程退出时通过 Hile 的 shutdown 自动销毁。
+行为说明：
+
+- `synchronize: true`
+- 当 `NODE_ENV === 'development'` 时启用 `logging`
+- 未配置 `TYPEORM_ENTITIES` 时，实体数组为空
+- 进程退出时通过 Hile 的 shutdown 自动销毁连接
 
-## 事务
+## 事务辅助
 
-使用 `transaction` 在 DataSource 上执行事务，并在失败时执行已注册的回滚逻辑（LIFO）：
+使用 `transaction` 在 DataSource 上执行事务，并注册失败时的回滚逻辑（LIFO）：
 
 ```typescript
 import { loadService } from '@hile/core'
@@ -52,20 +55,21 @@ import typeormService from '@hile/typeorm'
 const ds = await loadService(typeormService)
 
 const result = await transaction(ds, async (runner, rollback) => {
-  // 使用 runner 进行查询/写入
+  // 用 runner 执行数据库操作
   rollback(() => {
-    // 事务失败时执行的清理（如撤销外部副作用）
+    // 事务失败时执行的补偿逻辑
   })
+
   return value
 })
 ```
 
-- 成功：`transaction` 提交并返回回调的返回值。
-- 失败：回滚事务并按后进先出顺序执行所有通过 `rollback(fn)` 注册的函数，再抛出原错误。
+- 成功：提交事务并返回回调结果
+- 失败：回滚事务，并按后进先出顺序执行 `rollback(fn)` 注册函数，最后抛出原错误
 
 ## 与 @hile/cli 一起使用
 
-若使用 `@hile/cli` 启动应用，可在项目根 `package.json` 中配置自动加载本包默认服务：
+可在 `package.json` 配置自动加载：
 
 ```json
 {
@@ -75,15 +79,15 @@ const result = await transaction(ds, async (runner, rollback) => {
 }
 ```
 
-之后在业务中直接 `loadService(typeormService)` 即可，DataSource 会在应用启动时初始化、退出时销毁。
+这样应用启动时会初始化 DataSource，退出时自动销毁。
 
 ## 开发
 
 ```bash
 pnpm install
-pnpm build    # 编译
-pnpm dev      # 监听模式
-pnpm test     # 测试
+pnpm build
+pnpm dev
+pnpm test
 ```
 
 ## License

package/SKILL.md

@@ -1,118 +1,77 @@
 ---
 name: hile-typeorm
-description: Code generation and usage rules for @hile/typeorm. Use when using TypeORM DataSource as Hile service, transaction helper, or when the user asks about @hile/typeorm or TypeORM service patterns.
+description: @hile/typeorm 的代码生成与使用规范。适用于 DataSource 服务加载、transaction 事务封装、及与 @hile/core/@hile/cli 集成场景。
 ---
 
-# @hile/typeorm
+# @hile/typeorm SKILL
 
-本文档是面向 AI 编码模型和人类开发者的 **代码生成规范**，阅读后应能正确地使用本库编写符合架构规则的代码。
+本文档规范 `@hile/typeorm` 的使用方式，确保 DataSource 生命周期与事务行为一致。
 
----
-
-## 1. 架构总览
+## 1. 架构概览
 
-`@hile/typeorm` 在 `@hile/core` 之上提供：
+`@hile/typeorm` 提供：
 
-- **默认导出**：一个通过 `defineService` 定义的 TypeORM **DataSource** 服务，配置来自环境变量，进程退出时通过 `shutdown` 注册 `connection.destroy()`。
-- **transaction**：事务封装函数，接收 DataSource 与回调，在回调内提供 `QueryRunner` 与 `rollback` 注册器；提交成功则返回结果，失败则回滚并按 LIFO 执行已注册的 rollback 回调。
+- 默认导出：Hile 服务化的 TypeORM `DataSource`
+- `transaction`：事务封装，支持失败时 LIFO 执行补偿回调
 
-依赖：`@hile/core`、`typeorm`。生成代码时必须遵循 Hile 的服务定义与加载规则，并正确使用本包默认服务与 `transaction` 签名。
-
----
+依赖：`@hile/core`、`typeorm`。
 
-## 2. 类型与环境变量
-
-### 2.1 环境变量（DataSource 默认服务）
+## 2. 环境变量
 
 | 变量 | 说明 |
-|------|------|
+|---|---|
 | `TYPEORM_TYPE` | 数据库类型 |
 | `TYPEORM_HOST` | 主机 |
 | `TYPEORM_USERNAME` | 用户名 |
 | `TYPEORM_PASSWORD` | 密码 |
 | `TYPEORM_DATABASE` | 数据库名 |
-| `TYPEORM_PORT` | 端口（字符串会被转为数字） |
-| `TYPEORM_CHARSET` | 数据库字符集 |
-| `TYPEORM_ENTITY_PREFIX` | 实体表名前缀 |
-| `TYPEORM_ENTITIES` | 实体目录（单一路径，会以单元素数组传入 DataSource.entities） |
-
-DataSource 行为：`synchronize: true`；`logging` 在 `NODE_ENV === 'development'` 时为 `true`。未设置 `TYPEORM_ENTITIES` 时 `entities` 为空数组。
-
-### 2.2 类型（生成代码时须遵循）
+| `TYPEORM_PORT` | 端口（字符串转数字） |
+| `TYPEORM_CHARSET` | 字符集 |
+| `TYPEORM_ENTITY_PREFIX` | 表名前缀 |
+| `TYPEORM_ENTITIES` | 实体目录（单一路径） |
 
-- 使用 `typeorm` 的 `DataSource`、`DataSourceOptions`、`QueryRunner`。
-- **transaction** 签名：
-
-```typescript
-function transaction<T>(
-  datasource: DataSource,
-  callback: (
-    runner: QueryRunner,
-    rollback: (roll: () => unknown | Promise<unknown>) => number
-  ) => Promise<T>
-): Promise<T>;
-```
-
-- 默认服务：`defineService(async (shutdown) => { ... return connection; })`，在 `connection.initialize()` 前 `shutdown(() => connection.destroy())`。
-
----
+行为：
 
-## 3. 代码生成模板与规则
+- `synchronize: true`
+- `NODE_ENV === 'development'` 时 `logging: true`
+- 未设置 `TYPEORM_ENTITIES` 时实体为空数组
 
-### 3.1 使用默认 DataSource 服务
+## 3. 标准模板
 
-**模板：**
+### 3.1 加载默认 DataSource 服务
 
 ```typescript
 import { loadService } from '@hile/core'
 import typeormService from '@hile/typeorm'
 
 const ds = await loadService(typeormService)
-// 使用 ds 进行 TypeORM 操作
 ```
 
-**规则：**
-- 仅通过 `loadService(默认导出)` 获取 DataSource，不要自行 `new DataSource` 并暴露为“全局数据源”与 Hile 并存。
-- 环境变量在应用启动前必须配置完整，否则 DataSource 初始化可能失败。
-
-### 3.2 在事务中执行并注册回滚
-
-**模板：**
+### 3.2 事务执行与补偿
 
 ```typescript
-import { loadService } from '@hile/core'
 import { transaction } from '@hile/typeorm'
-import typeormService from '@hile/typeorm'
-
-const ds = await loadService(typeormService)
 
 const result = await transaction(ds, async (runner, rollback) => {
-  // 使用 runner 进行查询/写入
-  rollback(() => { /* 业务级回滚逻辑，失败时 LIFO 执行 */ })
+  rollback(async () => {
+    // 事务失败时执行的补偿逻辑
+  })
+
+  // 使用 runner 执行写操作
   return value
 })
 ```
 
-**规则：**
-- 第一个参数必须是 `DataSource` 实例（通常来自 `loadService(typeormService)`）。
-- 回调内需要“事务失败时执行”的逻辑通过 `rollback(fn)` 注册，不要依赖在回调外再执行清理。
-
-### 3.3 与 @hile/core 的约定
-
-- 本包默认导出是 Hile 服务（`defineService`），遵循 core 的 SKILL：服务函数为 `async (shutdown)`，资源创建后立即 `shutdown(() => connection.destroy())`。
-- 其他服务若依赖 DataSource，应在该服务函数内 `loadService(typeormService)` 获取，不要在模块顶层缓存 DataSource。
+## 4. 强制规则
 
-### 3.4 反模式
-
-- **不要**在未通过 Hile 加载的情况下，多处自行 `new DataSource` 并与本包默认服务混用。
-- **不要**在 `transaction` 回调外依赖“事务未提交”的状态做后续逻辑；提交/回滚由 `transaction` 内部统一处理。
-- **不要**省略 `shutdown(() => connection.destroy())` 或将其放在 `initialize()` 之后才注册（应在连接初始化前注册，与源码一致）。
-
----
+1. 统一通过 `loadService(typeormService)` 获取 DataSource。
+2. 不在多个模块里自行 new 全局 DataSource 与本包混用。
+3. 需要失败补偿时，使用 `rollback(fn)` 注册，不在事务外分散处理。
+4. 依赖 DataSource 的服务在函数内部 `loadService`，不要模块顶层缓存。
 
-## 4. API 速查
+## 5. API 速查
 
 | 导出 | 说明 |
-|------|------|
-| 默认导出 | `defineService` 返回的 DataSource 服务（需通过 `loadService` 使用） |
-| `transaction(datasource, callback)` | 在 DataSource 上执行事务，回调接收 `(runner, rollback)`，返回 `Promise<T>` |
+|---|---|
+| 默认导出 | Hile 服务化 DataSource |
+| `transaction(datasource, callback)` | 事务封装，失败时执行 rollback 队列 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hile/typeorm",
-  "version": "1.0.8",
+  "version": "1.0.9",
   "description": "TypeORM DataSource as Hile service with transaction helper",
   "type": "module",
   "main": "./dist/index.js",
@@ -22,8 +22,8 @@
     "vitest": "^4.0.18"
   },
   "dependencies": {
-    "@hile/core": "^1.0.16",
+    "@hile/core": "^1.0.17",
     "typeorm": "^0.3.28"
   },
-  "gitHead": "a6eab4e7803f0df7d4bca9a0bdeca76692dbc883"
+  "gitHead": "6672fc4cdc551c4265912cc85ee2e96fc44bc4c9"
 }