@omni-api/plugin-orm 0.0.1

package/README.md

@@ -0,0 +1,49 @@
+# @omni/plugin-orm
+
+OmniAPI 数据库事务中间件，**不绑定具体 ORM**。
+
+## 核心概念
+- `DataSource`：约定接口（`client` + `withTransaction` + `health`）
+- `attachDataSource(ds)`：把 DataSource 挂到 ctx（全局或 router 级中间件）
+- `transactional()`：把 handler 包进事务
+- `getTx(ctx)`：在 handler / service 中获取当前事务/客户端
+
+## 用法
+
+```ts
+import { PrismaClient } from '@prisma/client';
+import { attachDataSource, transactional, getTx, prismaDataSource } from '@omni/plugin-orm';
+
+const ds = prismaDataSource(new PrismaClient());
+
+defineProcedure({
+  name: 'order.create',
+  middleware: [attachDataSource(ds), transactional()],
+  handler: async ({ input, ctx }) => {
+    const db = getTx<typeof ds.client>(ctx);
+    const order = await db.order.create({ data: ... });
+    await db.audit.create({ data: { event: 'order_created', orderId: order.id } });
+    return order;
+  },
+});
+```
+
+## 内置适配器
+- `prismaDataSource(prisma)` — Prisma
+- `drizzleDataSource(db)` — Drizzle
+- `createMemoryDataSource(initial)` — 内存（仅示例 / 单测）
+- 自己实现 `DataSource` 接口适配任何驱动
+
+## getTx 设计
+
+通过 `AsyncLocalStorage` 自动透传事务，**业务代码不需要传 tx 参数**：
+
+```ts
+// service.ts
+function userService_create(ctx, data) {
+  const db = getTx(ctx);   // 自动拿到事务/非事务客户端
+  return db.user.create(...);
+}
+
+// 上层是否包了 transactional() 都不影响 service 写法
+```

package/dist/index.d.ts

@@ -0,0 +1,90 @@
+import { Middleware, Context } from '@omni-api/core';
+
+/**
+ * 数据源约定：与具体 ORM 解耦的最小接口。
+ *
+ * 任何 ORM/驱动都可以实现这个接口被 OmniAPI 使用：
+ *   - Prisma：`{ withTransaction: async (fn) => prisma.$transaction(fn), client: prisma }`
+ *   - Drizzle：`{ withTransaction: async (fn) => db.transaction(fn), client: db }`
+ *   - 原生 pg：`{ withTransaction: async (fn) => pool.connect()...., client: pool }`
+ *
+ * @template TClient ORM 的根客户端类型（例如 PrismaClient / DrizzleDB）
+ * @template TTx     事务上下文类型（通常是 client 在 transaction 中的同形版本）
+ */
+interface DataSource<TClient = unknown, TTx = TClient> {
+    /** 根客户端 —— 不需要事务时直接用这个 */
+    client: TClient;
+    /**
+     * 在事务中执行 fn；fn 抛错则回滚。
+     * 实现方需保证：fn 看到的 tx 对象是事务范围内的句柄。
+     */
+    withTransaction<R>(fn: (tx: TTx) => Promise<R>): Promise<R>;
+    /** 健康检查（可选实现） */
+    health?(): Promise<boolean>;
+}
+
+/**
+ * 在中间件 / handler 中获取当前事务对象。
+ *
+ * - 如果在 transactional() 中间件内：返回事务句柄
+ * - 否则：返回 dataSource.client（非事务模式）
+ *
+ * 这样业务代码可以无脑写：
+ *   ```ts
+ *   const db = getTx<DBClient>(ctx);
+ *   await db.user.create(...);
+ *   ```
+ *   不论外层是否包了事务，都不需要改。
+ */
+declare function getTx<TTx = unknown>(ctx: Context): TTx;
+/**
+ * 把 DataSource 挂到 ctx —— 通常作为 App 全局中间件。
+ *
+ * 这一步不开启事务，仅让 getTx() 在非事务路径下也能拿到 client。
+ */
+declare function attachDataSource(ds: DataSource): Middleware;
+/**
+ * 事务中间件：把 handler（含其调用栈中所有 getTx）跑在一个数据库事务里。
+ *
+ * 用法：
+ *   ```ts
+ *   defineProcedure({
+ *     name: 'order.create',
+ *     middleware: [auth(), transactional()],
+ *     handler: async ({ input, ctx }) => {
+ *       const db = getTx<DBClient>(ctx);
+ *       await db.order.create({ data: ... });
+ *       await db.audit.log({ ... });    // 同一个事务
+ *     },
+ *   });
+ *   ```
+ */
+declare function transactional(): Middleware;
+
+/**
+ * 内存版 DataSource —— 仅供示例 / 单测使用。
+ *
+ * 提供一个最小可工作的 DataSource：
+ *   - client 是一个普通对象（业务可任意往里塞数据/方法）
+ *   - withTransaction 用「快照 + 回滚」语义模拟事务
+ *
+ * 真实场景请用 Prisma/Drizzle/原生驱动的适配器。
+ */
+declare function createMemoryDataSource<TClient extends object = Record<string, unknown>>(initial: TClient): DataSource<TClient, TClient>;
+
+/**
+ * Prisma 适配器示例（不引入 prisma 依赖；通过结构类型适配）。
+ */
+interface PrismaLike {
+    $transaction<R>(fn: (tx: unknown) => Promise<R>): Promise<R>;
+}
+declare function prismaDataSource<TClient extends PrismaLike>(client: TClient): DataSource<TClient, TClient>;
+/**
+ * Drizzle 适配器示例。
+ */
+interface DrizzleLike {
+    transaction<R>(fn: (tx: unknown) => Promise<R>): Promise<R>;
+}
+declare function drizzleDataSource<TClient extends DrizzleLike>(client: TClient): DataSource<TClient, TClient>;
+
+export { type DataSource, type DrizzleLike, type PrismaLike, attachDataSource, createMemoryDataSource, drizzleDataSource, getTx, prismaDataSource, transactional };

package/dist/index.js

@@ -0,0 +1,89 @@
+import { AsyncLocalStorage } from 'async_hooks';
+
+// src/transactional.ts
+var txStore = new AsyncLocalStorage();
+function getTx(ctx) {
+  const inTx = txStore.getStore();
+  if (inTx !== void 0) return inTx;
+  const ds = ctx.state.__dataSource;
+  if (!ds) {
+    throw new Error(
+      "getTx: no DataSource attached. Did you forget to register dataSourcePlugin?"
+    );
+  }
+  return ds.client;
+}
+function attachDataSource(ds) {
+  return async (ctx, next) => {
+    ctx.state.__dataSource = ds;
+    return next();
+  };
+}
+function transactional() {
+  return async (ctx, next) => {
+    const ds = ctx.state.__dataSource;
+    if (!ds) {
+      throw new Error("transactional: DataSource not attached. Use attachDataSource() first.");
+    }
+    return ds.withTransaction(async (tx) => {
+      return txStore.run(tx, () => next());
+    });
+  };
+}
+
+// src/memory-datasource.ts
+function createMemoryDataSource(initial) {
+  const client = initial;
+  return {
+    client,
+    async withTransaction(fn) {
+      const snapshot = structuredClone(client);
+      try {
+        return await fn(client);
+      } catch (err) {
+        for (const k of Object.keys(client)) delete client[k];
+        Object.assign(client, snapshot);
+        throw err;
+      }
+    },
+    async health() {
+      return true;
+    }
+  };
+}
+
+// src/adapters.ts
+function prismaDataSource(client) {
+  return {
+    client,
+    withTransaction(fn) {
+      return client.$transaction((tx) => fn(tx));
+    },
+    async health() {
+      try {
+        const c = client;
+        if (typeof c.$queryRaw === "function") {
+          await c.$queryRaw(["SELECT 1"]);
+        }
+        return true;
+      } catch {
+        return false;
+      }
+    }
+  };
+}
+function drizzleDataSource(client) {
+  return {
+    client,
+    withTransaction(fn) {
+      return client.transaction((tx) => fn(tx));
+    },
+    async health() {
+      return true;
+    }
+  };
+}
+
+export { attachDataSource, createMemoryDataSource, drizzleDataSource, getTx, prismaDataSource, transactional };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/transactional.ts","../src/memory-datasource.ts","../src/adapters.ts"],"names":[],"mappings":";;;AAQA,IAAM,OAAA,GAAU,IAAI,iBAAA,EAA2B;AAexC,SAAS,MAAqB,GAAA,EAAmB;AACtD,EAAA,MAAM,IAAA,GAAO,QAAQ,QAAA,EAAS;AAC9B,EAAA,IAAI,IAAA,KAAS,QAAW,OAAO,IAAA;AAG/B,EAAA,MAAM,EAAA,GAAM,IAAI,KAAA,CAAwC,YAAA;AACxD,EAAA,IAAI,CAAC,EAAA,EAAI;AACP,IAAA,MAAM,IAAI,KAAA;AAAA,MACR;AAAA,KACF;AAAA,EACF;AACA,EAAA,OAAO,EAAA,CAAG,MAAA;AACZ;AAOO,SAAS,iBAAiB,EAAA,EAA4B;AAC3D,EAAA,OAAO,OAAO,KAAK,IAAA,KAAS;AAC1B,IAAC,GAAA,CAAI,MAAwC,YAAA,GAAe,EAAA;AAC5D,IAAA,OAAO,IAAA,EAAK;AAAA,EACd,CAAA;AACF;AAkBO,SAAS,aAAA,GAA4B;AAC1C,EAAA,OAAO,OAAO,KAAK,IAAA,KAAS;AAC1B,IAAA,MAAM,EAAA,GAAM,IAAI,KAAA,CAAwC,YAAA;AACxD,IAAA,IAAI,CAAC,EAAA,EAAI;AACP,MAAA,MAAM,IAAI,MAAM,uEAAuE,CAAA;AAAA,IACzF;AACA,IAAA,OAAO,EAAA,CAAG,eAAA,CAAgB,OAAO,EAAA,KAAO;AACtC,MAAA,OAAO,OAAA,CAAQ,GAAA,CAAI,EAAA,EAAI,MAAM,MAAM,CAAA;AAAA,IACrC,CAAC,CAAA;AAAA,EACH,CAAA;AACF;;;AChEO,SAAS,uBACd,OAAA,EAC8B;AAC9B,EAAA,MAAM,MAAA,GAAS,OAAA;AAEf,EAAA,OAAO;AAAA,IACL,MAAA;AAAA,IACA,MAAM,gBAAgB,EAAA,EAAI;AAExB,MAAA,MAAM,QAAA,GAAW,gBAAgB,MAAM,CAAA;AACvC,MAAA,IAAI;AACF,QAAA,OAAO,MAAM,GAAG,MAAM,CAAA;AAAA,MACxB,SAAS,GAAA,EAAK;AAEZ,QAAA,KAAA,MAAW,KAAK,MAAA,CAAO,IAAA,CAAK,MAAM,CAAA,EAAG,OAAQ,OAAmC,CAAC,CAAA;AACjF,QAAA,MAAA,CAAO,MAAA,CAAO,QAAQ,QAAQ,CAAA;AAC9B,QAAA,MAAM,GAAA;AAAA,MACR;AAAA,IACF,CAAA;AAAA,IACA,MAAM,MAAA,GAAS;AACb,MAAA,OAAO,IAAA;AAAA,IACT;AAAA,GACF;AACF;;;ACzBO,SAAS,iBACd,MAAA,EAC8B;AAC9B,EAAA,OAAO;AAAA,IACL,MAAA;AAAA,IACA,gBAAmB,EAAA,EAA6C;AAE9D,MAAA,OAAO,OAAO,YAAA,CAAa,CAAC,EAAA,KAAO,EAAA,CAAG,EAAa,CAAC,CAAA;AAAA,IACtD,CAAA;AAAA,IACA,MAAM,MAAA,GAAS;AACb,MAAA,IAAI;AACF,QAAA,MAAM,CAAA,GAAI,MAAA;AACV,QAAA,IAAI,OAAO,CAAA,CAAE,SAAA,KAAc,UAAA,EAAY;AACrC,UAAA,MAAM,CAAA,CAAE,SAAA,CAAU,CAAC,UAAU,CAAC,CAAA;AAAA,QAChC;AACA,QAAA,OAAO,IAAA;AAAA,MACT,CAAA,CAAA,MAAQ;AACN,QAAA,OAAO,KAAA;AAAA,MACT;AAAA,IACF;AAAA,GACF;AACF;AASO,SAAS,kBACd,MAAA,EAC8B;AAC9B,EAAA,OAAO;AAAA,IACL,MAAA;AAAA,IACA,gBAAmB,EAAA,EAA6C;AAC9D,MAAA,OAAO,OAAO,WAAA,CAAY,CAAC,EAAA,KAAO,EAAA,CAAG,EAAa,CAAC,CAAA;AAAA,IACrD,CAAA;AAAA,IACA,MAAM,MAAA,GAAS;AACb,MAAA,OAAO,IAAA;AAAA,IACT;AAAA,GACF;AACF","file":"index.js","sourcesContent":["import { AsyncLocalStorage } from 'node:async_hooks';\nimport { type Context, type Middleware } from '@omni-api/core';\nimport type { DataSource } from './datasource.js';\n\n/**\n * 事务上下文存储。用 AsyncLocalStorage 让 getTx() 能在嵌套调用中拿到正确的事务对象，\n * 而不需要业务一路把 tx 传下去。\n */\nconst txStore = new AsyncLocalStorage<unknown>();\n\n/**\n * 在中间件 / handler 中获取当前事务对象。\n *\n * - 如果在 transactional() 中间件内：返回事务句柄\n * - 否则：返回 dataSource.client（非事务模式）\n *\n * 这样业务代码可以无脑写：\n *   ```ts\n *   const db = getTx<DBClient>(ctx);\n *   await db.user.create(...);\n *   ```\n *   不论外层是否包了事务，都不需要改。\n */\nexport function getTx<TTx = unknown>(ctx: Context): TTx {\n  const inTx = txStore.getStore();\n  if (inTx !== undefined) return inTx as TTx;\n\n  // 不在事务中：用 ctx.state 里的 client（由 transactional 中间件外部装配）\n  const ds = (ctx.state as { __dataSource?: DataSource }).__dataSource;\n  if (!ds) {\n    throw new Error(\n      'getTx: no DataSource attached. Did you forget to register dataSourcePlugin?',\n    );\n  }\n  return ds.client as TTx;\n}\n\n/**\n * 把 DataSource 挂到 ctx —— 通常作为 App 全局中间件。\n *\n * 这一步不开启事务，仅让 getTx() 在非事务路径下也能拿到 client。\n */\nexport function attachDataSource(ds: DataSource): Middleware {\n  return async (ctx, next) => {\n    (ctx.state as { __dataSource?: DataSource }).__dataSource = ds;\n    return next();\n  };\n}\n\n/**\n * 事务中间件：把 handler（含其调用栈中所有 getTx）跑在一个数据库事务里。\n *\n * 用法：\n *   ```ts\n *   defineProcedure({\n *     name: 'order.create',\n *     middleware: [auth(), transactional()],\n *     handler: async ({ input, ctx }) => {\n *       const db = getTx<DBClient>(ctx);\n *       await db.order.create({ data: ... });\n *       await db.audit.log({ ... });    // 同一个事务\n *     },\n *   });\n *   ```\n */\nexport function transactional(): Middleware {\n  return async (ctx, next) => {\n    const ds = (ctx.state as { __dataSource?: DataSource }).__dataSource;\n    if (!ds) {\n      throw new Error('transactional: DataSource not attached. Use attachDataSource() first.');\n    }\n    return ds.withTransaction(async (tx) => {\n      return txStore.run(tx, () => next());\n    });\n  };\n}\n","import type { DataSource } from './datasource.js';\n\n/**\n * 内存版 DataSource —— 仅供示例 / 单测使用。\n *\n * 提供一个最小可工作的 DataSource：\n *   - client 是一个普通对象（业务可任意往里塞数据/方法）\n *   - withTransaction 用「快照 + 回滚」语义模拟事务\n *\n * 真实场景请用 Prisma/Drizzle/原生驱动的适配器。\n */\nexport function createMemoryDataSource<TClient extends object = Record<string, unknown>>(\n  initial: TClient,\n): DataSource<TClient, TClient> {\n  const client = initial;\n\n  return {\n    client,\n    async withTransaction(fn) {\n      // 简单快照（仅一层，深拷贝用 structuredClone）\n      const snapshot = structuredClone(client);\n      try {\n        return await fn(client);\n      } catch (err) {\n        // 回滚：把 client 恢复成快照\n        for (const k of Object.keys(client)) delete (client as Record<string, unknown>)[k];\n        Object.assign(client, snapshot);\n        throw err;\n      }\n    },\n    async health() {\n      return true;\n    },\n  };\n}\n","import type { DataSource } from './datasource.js';\n\n/**\n * Prisma 适配器示例（不引入 prisma 依赖；通过结构类型适配）。\n */\nexport interface PrismaLike {\n  $transaction<R>(fn: (tx: unknown) => Promise<R>): Promise<R>;\n}\n\nexport function prismaDataSource<TClient extends PrismaLike>(\n  client: TClient,\n): DataSource<TClient, TClient> {\n  return {\n    client,\n    withTransaction<R>(fn: (tx: TClient) => Promise<R>): Promise<R> {\n      // tx 在 prisma 内是同形客户端，做 cast 即可\n      return client.$transaction((tx) => fn(tx as TClient));\n    },\n    async health() {\n      try {\n        const c = client as { $queryRaw?: (...args: unknown[]) => Promise<unknown> };\n        if (typeof c.$queryRaw === 'function') {\n          await c.$queryRaw(['SELECT 1']);\n        }\n        return true;\n      } catch {\n        return false;\n      }\n    },\n  };\n}\n\n/**\n * Drizzle 适配器示例。\n */\nexport interface DrizzleLike {\n  transaction<R>(fn: (tx: unknown) => Promise<R>): Promise<R>;\n}\n\nexport function drizzleDataSource<TClient extends DrizzleLike>(\n  client: TClient,\n): DataSource<TClient, TClient> {\n  return {\n    client,\n    withTransaction<R>(fn: (tx: TClient) => Promise<R>): Promise<R> {\n      return client.transaction((tx) => fn(tx as TClient));\n    },\n    async health() {\n      return true;\n    },\n  };\n}\n"]}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@omni-api/plugin-orm",
+  "version": "0.0.1",
+  "description": "Database transaction middleware for OmniAPI; ORM-agnostic via DataSource convention.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": ["dist", "README.md"],
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist .turbo coverage"
+  },
+  "dependencies": {
+    "@omni-api/core": "workspace:*"
+  },
+  "devDependencies": {
+    "tsup": "^8.3.0",
+    "typescript": "^5.7.0",
+    "vitest": "^2.1.0",
+    "zod": "^3.23.8",
+    "@types/node": "^22.10.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}