@longzai-intelligence-typeorm/optimistic-lock 0.0.4

package/README.md

@@ -0,0 +1,134 @@
+# @longzai-intelligence-typeorm/optimistic-lock
+
+TypeORM 乐观锁统一兜底能力。
+
+为资金 / 状态机 / 库存计数等并发敏感实体提供强类型的乐观锁条件更新工具，
+消除各域 repository 手写乐观锁导致的实现漂移与「`save()` 路径绕过乐观锁」系统性反模式。
+
+## 背景
+
+TypeORM 1.1.0 的 `repository.save(orm)` 路径不会在 `WHERE` 注入 `version` 条件
+（`EntityPersistExecutor` / `SubjectExecutor` 全文零 `lockMode` 命中），
+仅依靠 `@Column` / `@VersionColumn` 在 `SET` 中递增 `version`，无法检测并发冲突，存在丢失更新风险。
+
+唯一生效的乐观锁是 `repository.update({ id, version: expectedVersion }, ...)`：
+`WHERE` 带 `version`，`affectedRows = 0` 表示并发冲突。
+
+本包将这套语义封装为强类型工具，调用方用显式字面量构造 `where` / `set`，
+TypeScript 从字面量精确推断，**零 spread 动态合并、零类型断言**。
+
+## 安装
+
+```bash
+bun add @longzai-intelligence-typeorm/optimistic-lock
+```
+
+`peerDependencies`：`typeorm`、`@longzai-intelligence-error/core`、`@longzai-intelligence-error/utils`、`@longzai-intelligence-shared-kernel/core`。
+
+## 使用
+
+### 1. 在 repository 的 conditionalSave 中调用工具
+
+调用方用显式字面量构造 `where`（必须含 `version`）与 `set`（不含 `version`，由工具注入 `expectedVersion + 1`）：
+
+```typescript
+import { conditionalVersionedUpdate } from '@longzai-intelligence-typeorm/optimistic-lock';
+
+async conditionalSave(
+  entity: WalletEntity,
+  expectedVersion: number,
+  tx?: EntityManager,
+): Promise<Result<{ affectedRows: number }, DomainError>> {
+  const orm = WalletOrmMapper.toOrm(entity);
+
+  return conditionalVersionedUpdate(this.resolveRepository(tx), {
+    orm,
+    expectedVersion,
+    where: { id: orm.id, version: expectedVersion },     // 字面量，VersionedWhere 强制含 version
+    set: { balance: orm.balance, updatedAt: orm.updatedAt }, // 字面量，VersionedSet 排除 version
+  });
+}
+```
+
+### 2. 在调用方（usecase / port-adapter）处理冲突
+
+`conditionalVersionedUpdate` 只返回 `{ affectedRows }`，不判定冲突语义。
+用 helper 统一处理两种场景：
+
+#### fail 模式（资金 / 库存 / 订单状态机：冲突即报错）
+
+```typescript
+import {
+  conditionalVersionedUpdate, // 在 repository 内部
+  handleConditionalSaveOnFail,
+} from '@longzai-intelligence-typeorm/optimistic-lock';
+
+const result = await this.walletRepo.conditionalSave(wallet, expectedVersion, tx);
+const outcome = handleConditionalSaveOnFail(result, {
+  aggregate: 'wallet',
+  aggregateId: memberId,
+  expectedVersion,
+});
+
+if (outcome.isFailure) {
+  return failure(outcome.error); // ConcurrencyError（HTTP OPERATION_FAILED「操作冲突，请重试」）
+}
+// outcome.value.kind === 'updated'
+```
+
+#### idempotent 模式（支付回调：affectedRows=0 视为其他并发回调已处理）
+
+```typescript
+import { handleConditionalSaveOnIdempotent } from '@longzai-intelligence-typeorm/optimistic-lock';
+
+const result = await this.transactionRepo.conditionalSave(transaction, expectedState, expectedVersion);
+const outcome = handleConditionalSaveOnIdempotent(result);
+
+if (outcome.isFailure) {
+  return failure(outcome.error); // 仓储异常
+}
+if (outcome.value.kind === 'conflict') {
+  // 其他并发回调已处理，视为幂等成功
+  return success({ success: true, ... });
+}
+// outcome.value.kind === 'updated'
+```
+
+### 3. 直接构造乐观锁冲突错误
+
+```typescript
+import { createOptimisticLockConflictError } from '@longzai-intelligence-typeorm/optimistic-lock';
+
+return failure(
+  createOptimisticLockConflictError({
+    aggregate: 'order',
+    aggregateId: orderId,
+    expectedVersion: 5,
+  }),
+);
+// → ConcurrencyError，message 含上下文：并发更新冲突：...（aggregate=order, aggregateId=..., expectedVersion=5）
+```
+
+## 强类型契约
+
+| 类型                    | 约束                                                                                       |
+| ----------------------- | ------------------------------------------------------------------------------------------ |
+| `VersionedWhere<TOrm>`  | `FindOptionsWhere<TOrm> & { version: number }`，强制 `where` 字面量含 `version`            |
+| `VersionedSet<TOrm>`    | `Omit<QueryDeepPartialEntity<TOrm>, 'version'>`，调用方 `set` 不含 `version`（由工具注入） |
+| `ConditionalSaveResult` | `{ affectedRows: number }`，`0` 表示并发冲突                                               |
+
+调用方写错（如 `where` 漏 `version`、`set` 误含 `version`）会在编译期被 TypeScript 拦截，无需运行时检查或类型断言。
+
+## API
+
+| 导出                                | 说明                                                                             |
+| ----------------------------------- | -------------------------------------------------------------------------------- |
+| `conditionalVersionedUpdate`        | 乐观锁条件更新工具（强类型 `VersionedWhere` / `VersionedSet` 强制 version 契约） |
+| `handleConditionalSaveOnFail`       | 冲突处理 helper（fail 模式：affectedRows=0 转 `ConcurrencyError`）               |
+| `handleConditionalSaveOnIdempotent` | 冲突处理 helper（idempotent 模式：affectedRows=0 视为幂等成功）                  |
+| `createOptimisticLockConflictError` | 错误工厂，统一产出 `ConcurrencyError`（code=CONCURRENCY_ERROR）                  |
+| `ConditionalSaveResult`             | 条件更新返回值类型（`{ affectedRows }`）                                         |
+| `ConditionalVersionedUpdateParams`  | `conditionalVersionedUpdate` 入参类型                                            |
+| `VersionedWhere`                    | 带 version 强制的 WHERE 条件类型                                                 |
+| `VersionedSet`                      | 排除 version 的 SET 字段类型                                                     |
+| `OptimisticLockConflictContext`     | 冲突错误上下文（aggregate / aggregateId / expectedVersion）                      |

package/dist/index.d.ts

@@ -0,0 +1,199 @@
+import { ConcurrencyError, DomainError } from "@longzai-intelligence-error/core";
+import { Result } from "@longzai-intelligence-shared-kernel/core";
+import { EntityManager, FindOptionsWhere, ObjectLiteral, QueryDeepPartialEntity, Repository } from "typeorm";
+//#region src/types/conditional-save.types.d.ts
+/**
+ * 条件更新受影响行数结果
+ *
+ * affectedRows = 0 表示 WHERE 条件（含 version [+ 业务字段]）未命中，
+ * 即其他并发事务已先行更新该行，发生乐观锁冲突。
+ */
+type ConditionalSaveResult = {
+  /**
+   * 受影响的数据库行数
+   *
+   * - 1：条件更新成功（命中 version + 业务字段）
+   * - 0：乐观锁冲突（并发事务已更新该行，或业务字段状态已变迁）
+   */
+  readonly affectedRows: number;
+};
+/**
+ * 带版本号强制的 WHERE 条件类型
+ *
+ * FindOptionsWhere<TOrm> 与 { version: number } 的交叉类型，
+ * 强制调用方构造的 where 字面量必须包含 version 字段。
+ *
+ * 调用方用字面量构造，TypeScript 检查字面量是否同时满足 FindOptionsWhere 与含 version，
+ * 字段级类型完整保留，无 spread、无断言。
+ *
+ * @typeParam TOrm - ORM 实体类型
+ */
+type VersionedWhere<TOrm extends ObjectLiteral> = FindOptionsWhere<TOrm> & {
+  /**
+   * 期望版本号（查询时记录）
+   */
+  version: number;
+};
+/**
+ * 排除 version 的业务字段 SET 类型
+ *
+ * 调用方构造的 set 字面量只含业务字段（不含 version），
+ * version 由 conditionalVersionedUpdate 工具注入 expectedVersion + 1，
+ * 保证 version 递增逻辑统一、不可被调用方覆写。
+ *
+ * @typeParam TOrm - ORM 实体类型
+ */
+type VersionedSet<TOrm extends ObjectLiteral> = Omit<QueryDeepPartialEntity<TOrm>, 'version'>;
+/**
+ * conditionalVersionedUpdate 入参
+ *
+ * @typeParam TOrm - ORM 实体类型，必须含 id 与 version 字段
+ */
+type ConditionalVersionedUpdateParams<TOrm extends ObjectLiteral & {
+  id: string | number;
+}> = {
+  /**
+   * 已应用领域变更的 ORM 实体
+   *
+   * 工具从中读取 id 用于错误上下文（实际 WHERE 字段由 where 参数显式提供）。
+   */
+  readonly orm: TOrm;
+  /**
+   * 查询时记录的期望版本号
+   *
+   * 工具据此构造 SET 中的 version = expectedVersion + 1；
+   * 调用方还需在 where 字面量中显式写入 version: expectedVersion（由 VersionedWhere 类型强制）。
+   */
+  readonly expectedVersion: number;
+  /**
+   * WHERE 条件字面量（含 version + 业务字段，如 id / tradeState）
+   *
+   * 由调用方用显式字面量构造，VersionedWhere 类型强制 version 字段必填。
+   * 字段级类型完整保留，无 spread、无断言。
+   */
+  readonly where: VersionedWhere<TOrm>;
+  /**
+   * SET 业务字段字面量（不含 version，version 由工具注入）
+   *
+   * 由调用方用显式字面量构造，只含业务字段（如 balance / status / updatedAt）。
+   */
+  readonly set: VersionedSet<TOrm>;
+  /**
+   * 可选的事务管理器
+   *
+   * 由 PortAdapter 在 dataSource.transaction() 闭包内透传；
+   * 未提供时使用默认 repository（无事务）。
+   */
+  readonly tx?: EntityManager;
+};
+//#endregion
+//#region src/utils/conditional-versioned-update.utils.d.ts
+/**
+ * 执行乐观锁条件更新
+ *
+ * WHERE 含 version = expectedVersion（调用方字面量提供，VersionedWhere 类型强制），
+ * SET 含业务字段（调用方字面量提供）+ version = expectedVersion + 1（工具注入）。
+ * 受影响行数为 0 表示并发冲突。
+ *
+ * @typeParam TOrm - ORM 实体类型，必须含 id 与 version 字段
+ * @param repository - TypeORM Repository 实例（由调用方从 resolveRepository(tx) 获取）
+ * @param params - 条件更新入参（orm / expectedVersion / where / set / tx?）
+ * @returns 成功时返回包含受影响行数的结果；失败时返回 RepositoryError
+ */
+declare function conditionalVersionedUpdate<TOrm extends ObjectLiteral & {
+  id: string | number;
+}>(repository: Repository<TOrm>, params: ConditionalVersionedUpdateParams<TOrm>): Promise<Result<ConditionalSaveResult, DomainError>>;
+//#endregion
+//#region src/errors/optimistic-lock.errors.d.ts
+/**
+ * 乐观锁冲突错误上下文
+ *
+ * 用于在错误消息中附加定位信息（聚合类型、聚合 ID、期望版本号），便于日志检索与排障。
+ * 字段全部可选，调用方按需提供。
+ */
+type OptimisticLockConflictContext = {
+  /**
+   * 聚合根类型（如 wallet / order / wechat-transaction）
+   */
+  readonly aggregate?: string;
+  /**
+   * 聚合根 ID（如 memberId / orderId / outTradeNo）
+   */
+  readonly aggregateId?: string;
+  /**
+   * 查询时记录的期望版本号
+   */
+  readonly expectedVersion?: number;
+};
+/**
+ * 构造乐观锁冲突错误
+ *
+ * 统一产出 ConcurrencyError，将可选的上下文信息编进错误消息便于排障。
+ * 各域 usecase 不应自行 new ConcurrencyError(...)，统一走本工厂保证错误消息格式一致。
+ *
+ * @param context - 可选的错误上下文（聚合类型 / 聚合 ID / 期望版本号）
+ * @returns ConcurrencyError 实例
+ */
+declare function createOptimisticLockConflictError(context?: OptimisticLockConflictContext): ConcurrencyError;
+//#endregion
+//#region src/helpers/conflict-handler.helpers.d.ts
+/**
+ * 冲突处理策略
+ *
+ * - fail：affectedRows = 0 视为并发冲突错误（资金/库存/订单状态机等场景）
+ * - idempotent：affectedRows = 0 视为幂等成功（支付回调等重复通知场景）
+ */
+type ConflictStrategy = 'fail' | 'idempotent';
+/**
+ * fail 模式的处理结果
+ *
+ * conditionalSave 成功且 affectedRows > 0 时为 updated；
+ * 失败（含 affectedRows = 0 冲突）时直接返回 failure(ConcurrencyError)。
+ */
+type FailOutcome = Result<{
+  kind: 'updated';
+  affectedRows: number;
+}, DomainError>;
+/**
+ * idempotent 模式的处理结果
+ *
+ * - updated：conditionalSave 成功且 affectedRows > 0
+ * - conflict：affectedRows = 0，调用方据此走幂等成功分支（非错误）
+ *
+ * 失败时返回 failure（仓储异常）。
+ */
+type IdempotentOutcome = Result<{
+  kind: 'updated';
+  affectedRows: number;
+} | {
+  kind: 'conflict';
+}, DomainError>;
+/**
+ * 处理条件更新结果（fail 模式）
+ *
+ * 适用于资金/库存/订单状态机等「并发冲突必须报错」的场景。
+ *
+ * - conditionalSave 失败（仓储异常）→ 原样返回 failure
+ * - affectedRows = 0（并发冲突）→ failure(ConcurrencyError)
+ * - affectedRows > 0（更新成功）→ success({ kind: 'updated', affectedRows })
+ *
+ * @param result - OptimisticRepository.conditionalSave 的返回值
+ * @param context - 可选的冲突错误上下文（聚合类型 / 聚合 ID / 期望版本号）
+ * @returns 处理后的结果
+ */
+declare function handleConditionalSaveOnFail(result: Result<ConditionalSaveResult, DomainError>, context?: OptimisticLockConflictContext): FailOutcome;
+/**
+ * 处理条件更新结果（idempotent 模式）
+ *
+ * 适用于支付回调等「affectedRows = 0 表示其他并发回调已处理，应视为幂等成功」的场景。
+ *
+ * - conditionalSave 失败（仓储异常）→ 原样返回 failure
+ * - affectedRows = 0（并发回调已处理）→ success({ kind: 'conflict' })
+ * - affectedRows > 0（本次更新成功）→ success({ kind: 'updated', affectedRows })
+ *
+ * @param result - OptimisticRepository.conditionalSave 的返回值
+ * @returns 处理后的结果
+ */
+declare function handleConditionalSaveOnIdempotent(result: Result<ConditionalSaveResult, DomainError>): IdempotentOutcome;
+//#endregion
+export { type ConditionalSaveResult, type ConditionalVersionedUpdateParams, type ConflictStrategy, type FailOutcome, type IdempotentOutcome, type OptimisticLockConflictContext, type VersionedSet, type VersionedWhere, conditionalVersionedUpdate, createOptimisticLockConflictError, handleConditionalSaveOnFail, handleConditionalSaveOnIdempotent };

package/dist/index.js

@@ -0,0 +1 @@
+import{ConcurrencyError as e,RepositoryError as t}from"@longzai-intelligence-error/core";import{ensureError as n}from"@longzai-intelligence-error/utils";import{failure as r,success as i}from"@longzai-intelligence-shared-kernel/core";async function a(e,a){try{let{expectedVersion:t,where:n,set:r}=a,o=t+1,s={...r,version:o};return i({affectedRows:(await e.update(n,s)).affected??0})}catch(e){return r(new t(`乐观锁条件更新失败`,n(e),{ormId:String(a.orm.id)}))}}const o=`并发更新冲突：记录已被其他事务修改，请重试`;function s(t){let n=[];return t?.aggregate!==void 0&&n.push(`aggregate=${t.aggregate}`),t?.aggregateId!==void 0&&n.push(`aggregateId=${t.aggregateId}`),t?.expectedVersion!==void 0&&n.push(`expectedVersion=${t.expectedVersion}`),new e(n.length>0?`${o}（${n.join(`, `)}）`:o)}function c(e,t){if(e.isFailure)return r(e.error);let{affectedRows:n}=e.value;return n===0?r(s(t)):i({kind:`updated`,affectedRows:n})}function l(e){if(e.isFailure)return r(e.error);let{affectedRows:t}=e.value;return i(t===0?{kind:`conflict`}:{kind:`updated`,affectedRows:t})}export{a as conditionalVersionedUpdate,s as createOptimisticLockConflictError,c as handleConditionalSaveOnFail,l as handleConditionalSaveOnIdempotent};

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@longzai-intelligence-typeorm/optimistic-lock",
+  "version": "0.0.4",
+  "private": false,
+  "keywords": [
+    "concurrency",
+    "conditional-update",
+    "optimistic-lock",
+    "typeorm"
+  ],
+  "license": "UNLICENSED",
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "lzi-builder",
+    "build:prod": "NODE_ENV=production lzi-builder",
+    "prepublishOnly": "bun run build:prod",
+    "typecheck": "bun run typecheck:app && bun run typecheck:node && bun run typecheck:test",
+    "typecheck:app": "tsgo --noEmit -p tsconfig/app.json",
+    "typecheck:node": "tsgo --noEmit -p tsconfig/node.json",
+    "typecheck:test": "tsgo --noEmit -p tsconfig/test.json",
+    "lint": "oxlint && oxfmt --check",
+    "lint:fix": "oxlint --fix && oxfmt",
+    "test": "bun test",
+    "test:watch": "bun test --watch",
+    "test:coverage": "bun test --coverage",
+    "clean": "lzi-dev-cli clean"
+  },
+  "peerDependencies": {
+    "@longzai-intelligence-error/core": "^0.1.0",
+    "@longzai-intelligence-error/utils": "^0.1.0",
+    "@longzai-intelligence-shared-kernel/core": "^0.1.0",
+    "typeorm": "^1.0.0"
+  },
+  "packageManager": "bun@1.3.14"
+}