@hile/typeorm 1.0.1

package/README.md

@@ -0,0 +1,88 @@
+# @hile/typeorm
+
+基于 `@hile/core` 的 TypeORM 集成：将 TypeORM DataSource 封装为 Hile 服务（单例、随进程退出销毁），并提供事务封装 `transaction`。
+
+## 安装
+
+```bash
+pnpm add @hile/typeorm
+```
+
+依赖 `@hile/core` 与 `typeorm`，请一并安装。
+
+## 快速开始
+
+通过环境变量配置数据库，用 `loadService` 获取 DataSource：
+
+```typescript
+import { loadService } from '@hile/core'
+import typeormService from '@hile/typeorm'
+
+const ds = await loadService(typeormService)
+// 使用 ds.getRepository(Entity)、ds.manager 等
+```
+
+## 环境变量
+
+DataSource 从以下环境变量读取配置：
+
+| 变量 | 说明 |
+|------|------|
+| `TYPEORM_TYPE` | 数据库类型（如 `mysql`、`postgres`） |
+| `TYPEORM_HOST` | 主机 |
+| `TYPEORM_USERNAME` | 用户名 |
+| `TYPEORM_PASSWORD` | 密码 |
+| `TYPEORM_DATABASE` | 数据库名 |
+| `TYPEORM_PORT` | 端口 |
+
+行为：`synchronize: true`；当 `NODE_ENV === 'development'` 时开启 `logging`。连接在进程退出时通过 Hile 的 shutdown 自动销毁。
+
+## 事务
+
+使用 `transaction` 在 DataSource 上执行事务，并在失败时执行已注册的回滚逻辑（LIFO）：
+
+```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(() => {
+    // 事务失败时执行的清理（如撤销外部副作用）
+  })
+  return value
+})
+```
+
+- 成功：`transaction` 提交并返回回调的返回值。
+- 失败：回滚事务并按后进先出顺序执行所有通过 `rollback(fn)` 注册的函数，再抛出原错误。
+
+## 与 @hile/cli 一起使用
+
+若使用 `@hile/cli` 启动应用，可在项目根 `package.json` 中配置自动加载本包默认服务：
+
+```json
+{
+  "hile": {
+    "auto_load_packages": ["@hile/typeorm"]
+  }
+}
+```
+
+之后在业务中直接 `loadService(typeormService)` 即可，DataSource 会在应用启动时初始化、退出时销毁。
+
+## 开发
+
+```bash
+pnpm install
+pnpm build    # 编译
+pnpm dev      # 监听模式
+pnpm test     # 测试
+```
+
+## License
+
+MIT

package/SKILL.md

@@ -0,0 +1,110 @@
+# @hile/typeorm
+
+本文档是面向 AI 编码模型和人类开发者的 **代码生成规范**，阅读后应能正确地使用本库编写符合架构规则的代码。
+
+---
+
+## 1. 架构总览
+
+`@hile/typeorm` 在 `@hile/core` 之上提供：
+
+- **默认导出**：一个通过 `defineService` 定义的 TypeORM **DataSource** 服务，配置来自环境变量，进程退出时通过 `shutdown` 注册 `connection.destroy()`。
+- **transaction**：事务封装函数，接收 DataSource 与回调，在回调内提供 `QueryRunner` 与 `rollback` 注册器；提交成功则返回结果，失败则回滚并按 LIFO 执行已注册的 rollback 回调。
+
+依赖：`@hile/core`、`typeorm`。生成代码时必须遵循 Hile 的服务定义与加载规则，并正确使用本包默认服务与 `transaction` 签名。
+
+---
+
+## 2. 类型与环境变量
+
+### 2.1 环境变量（DataSource 默认服务）
+
+| 变量 | 说明 |
+|------|------|
+| `TYPEORM_TYPE` | 数据库类型 |
+| `TYPEORM_HOST` | 主机 |
+| `TYPEORM_USERNAME` | 用户名 |
+| `TYPEORM_PASSWORD` | 密码 |
+| `TYPEORM_DATABASE` | 数据库名 |
+| `TYPEORM_PORT` | 端口（字符串会被转为数字） |
+
+DataSource 行为：`synchronize: true`；`logging` 在 `NODE_ENV === 'development'` 时为 `true`。
+
+### 2.2 类型（生成代码时须遵循）
+
+- 使用 `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. 代码生成模板与规则
+
+### 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 在事务中执行并注册回滚
+
+**模板：**
+
+```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 执行 */ })
+  return value
+})
+```
+
+**规则：**
+- 第一个参数必须是 `DataSource` 实例（通常来自 `loadService(typeormService)`）。
+- 回调内需要“事务失败时执行”的逻辑通过 `rollback(fn)` 注册，不要依赖在回调外再执行清理。
+
+### 3.3 与 @hile/core 的约定
+
+- 本包默认导出是 Hile 服务（`defineService`），遵循 core 的 SKILL：服务函数为 `async (shutdown)`，资源创建后立即 `shutdown(() => connection.destroy())`。
+- 其他服务若依赖 DataSource，应在该服务函数内 `loadService(typeormService)` 获取，不要在模块顶层缓存 DataSource。
+
+### 3.4 反模式
+
+- **不要**在未通过 Hile 加载的情况下，多处自行 `new DataSource` 并与本包默认服务混用。
+- **不要**在 `transaction` 回调外依赖“事务未提交”的状态做后续逻辑；提交/回滚由 `transaction` 内部统一处理。
+- **不要**省略 `shutdown(() => connection.destroy())` 或将其放在 `initialize()` 之后才注册（应在连接初始化前注册，与源码一致）。
+
+---
+
+## 4. API 速查
+
+| 导出 | 说明 |
+|------|------|
+| 默认导出 | `defineService` 返回的 DataSource 服务（需通过 `loadService` 使用） |
+| `transaction(datasource, callback)` | 在 DataSource 上执行事务，回调接收 `(runner, rollback)`，返回 `Promise<T>` |

package/dist/index.d.ts

@@ -0,0 +1,21 @@
+import { DataSource, QueryRunner } from 'typeorm';
+/**
+ * 创建数据源服务
+ * 数据从环境变量中获取
+ * 环境变量：
+ * - TYPEORM_TYPE: 数据库类型
+ * - TYPEORM_HOST: 数据库主机
+ * - TYPEORM_USERNAME: 数据库用户名
+ * - TYPEORM_PASSWORD: 数据库密码
+ * - TYPEORM_DATABASE: 数据库名称
+ * - TYPEORM_PORT: 数据库端口
+ */
+declare const _default: import("@hile/core").ServiceRegisterProps<DataSource>;
+export default _default;
+/**
+ * 事务处理
+ * @param datasource - 数据源
+ * @param callback - 回调函数
+ * @returns - 返回值
+ */
+export declare function transaction<T>(datasource: DataSource, callback: (runner: QueryRunner, rollback: (roll: () => unknown | Promise<unknown>) => number) => Promise<T>): Promise<T>;

package/dist/index.js

@@ -0,0 +1,62 @@
+import { defineService } from '@hile/core';
+import { DataSource } from 'typeorm';
+/**
+ * 创建数据源服务
+ * 数据从环境变量中获取
+ * 环境变量：
+ * - TYPEORM_TYPE: 数据库类型
+ * - TYPEORM_HOST: 数据库主机
+ * - TYPEORM_USERNAME: 数据库用户名
+ * - TYPEORM_PASSWORD: 数据库密码
+ * - TYPEORM_DATABASE: 数据库名称
+ * - TYPEORM_PORT: 数据库端口
+ */
+export default defineService(async (shutdown) => {
+    const configs = {
+        // @ts-ignore
+        type: process.env.TYPEORM_TYPE,
+        host: process.env.TYPEORM_HOST,
+        username: process.env.TYPEORM_USERNAME,
+        password: process.env.TYPEORM_PASSWORD,
+        database: process.env.TYPEORM_DATABASE,
+        port: typeof process.env.TYPEORM_PORT === 'string'
+            ? Number(process.env.TYPEORM_PORT)
+            : process.env.TYPEORM_PORT,
+    };
+    const connection = new DataSource({
+        ...configs,
+        synchronize: true,
+        logging: process.env.NODE_ENV === 'development',
+    });
+    shutdown(() => connection.destroy());
+    await connection.initialize();
+    return connection;
+});
+/**
+ * 事务处理
+ * @param datasource - 数据源
+ * @param callback - 回调函数
+ * @returns - 返回值
+ */
+export async function transaction(datasource, callback) {
+    const rollbacks = [];
+    const runner = datasource.createQueryRunner();
+    await runner.connect();
+    await runner.startTransaction();
+    const push = (roll) => rollbacks.push(roll);
+    try {
+        const res = await callback(runner, push);
+        await runner.commitTransaction();
+        return res;
+    }
+    catch (e) {
+        await runner.rollbackTransaction();
+        let i = rollbacks.length;
+        while (i--)
+            await Promise.resolve(rollbacks[i]());
+        throw e;
+    }
+    finally {
+        await runner.release();
+    }
+}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@hile/typeorm",
+  "version": "1.0.1",
+  "description": "TypeORM DataSource as Hile service with transaction helper",
+  "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",
+    "skill.json"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "^25.3.1",
+    "vitest": "^4.0.18"
+  },
+  "dependencies": {
+    "@hile/core": "1.0.11",
+    "typeorm": "^0.3.28"
+  },
+  "gitHead": "75eb1011ddecf2b85dadb584dd3876c8b65bfb03"
+}

package/skill.json

@@ -0,0 +1,16 @@
+{
+  "name": "@hile/typeorm",
+  "version": "1.0.0",
+  "description": "Code generation and contribution rules for @hile/typeorm (TypeORM DataSource as Hile service). Use when editing this package or when the user asks about @hile/typeorm, DataSource, or transaction patterns.",
+  "repository": "",
+  "skills": [
+    {
+      "id": "typeorm",
+      "name": "@hile/typeorm 开发指南",
+      "description": "提供 @hile/typeorm 模块的开发与代码生成规范：DataSource 服务、环境变量、事务封装",
+      "path": "SKILL.md"
+    }
+  ],
+  "authors": [],
+  "license": "MIT"
+}