@esengine/transaction 2.0.7 → 2.1.1

package/dist/index.js

@@ -0,0 +1,1621 @@
+var __defProp = Object.defineProperty;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
+
+// src/core/TransactionContext.ts
+function generateId() {
+  return `tx_${Date.now().toString(36)}_${Math.random().toString(36).substring(2, 11)}`;
+}
+__name(generateId, "generateId");
+var _TransactionContext = class _TransactionContext {
+  constructor(options = {}) {
+    __publicField(this, "_id");
+    __publicField(this, "_state", "pending");
+    __publicField(this, "_timeout");
+    __publicField(this, "_operations", []);
+    __publicField(this, "_storage");
+    __publicField(this, "_metadata");
+    __publicField(this, "_contextData", /* @__PURE__ */ new Map());
+    __publicField(this, "_startTime", 0);
+    __publicField(this, "_distributed");
+    this._id = generateId();
+    this._timeout = options.timeout ?? 3e4;
+    this._storage = options.storage ?? null;
+    this._metadata = options.metadata ?? {};
+    this._distributed = options.distributed ?? false;
+  }
+  // =========================================================================
+  // 只读属性 | Readonly properties
+  // =========================================================================
+  get id() {
+    return this._id;
+  }
+  get state() {
+    return this._state;
+  }
+  get timeout() {
+    return this._timeout;
+  }
+  get operations() {
+    return this._operations;
+  }
+  get storage() {
+    return this._storage;
+  }
+  get metadata() {
+    return this._metadata;
+  }
+  // =========================================================================
+  // 公共方法 | Public methods
+  // =========================================================================
+  /**
+   * @zh 添加操作
+   * @en Add operation
+   */
+  addOperation(operation) {
+    if (this._state !== "pending") {
+      throw new Error(`Cannot add operation to transaction in state: ${this._state}`);
+    }
+    this._operations.push(operation);
+    return this;
+  }
+  /**
+   * @zh 执行事务
+   * @en Execute transaction
+   */
+  async execute() {
+    if (this._state !== "pending") {
+      return {
+        success: false,
+        transactionId: this._id,
+        results: [],
+        error: `Transaction already in state: ${this._state}`,
+        duration: 0
+      };
+    }
+    this._startTime = Date.now();
+    this._state = "executing";
+    const results = [];
+    let executedCount = 0;
+    try {
+      await this._saveLog();
+      for (let i = 0; i < this._operations.length; i++) {
+        if (this._isTimedOut()) {
+          throw new Error("Transaction timed out");
+        }
+        const op = this._operations[i];
+        const isValid = await op.validate(this);
+        if (!isValid) {
+          throw new Error(`Validation failed for operation: ${op.name}`);
+        }
+        const result = await op.execute(this);
+        results.push(result);
+        executedCount++;
+        await this._updateOperationLog(i, "executed");
+        if (!result.success) {
+          throw new Error(result.error ?? `Operation ${op.name} failed`);
+        }
+      }
+      this._state = "committed";
+      await this._updateTransactionState("committed");
+      return {
+        success: true,
+        transactionId: this._id,
+        results,
+        data: this._collectResultData(results),
+        duration: Date.now() - this._startTime
+      };
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      await this._compensate(executedCount - 1);
+      return {
+        success: false,
+        transactionId: this._id,
+        results,
+        error: errorMessage,
+        duration: Date.now() - this._startTime
+      };
+    }
+  }
+  /**
+   * @zh 手动回滚事务
+   * @en Manually rollback transaction
+   */
+  async rollback() {
+    if (this._state === "committed" || this._state === "rolledback") {
+      return;
+    }
+    await this._compensate(this._operations.length - 1);
+  }
+  /**
+   * @zh 获取上下文数据
+   * @en Get context data
+   */
+  get(key) {
+    return this._contextData.get(key);
+  }
+  /**
+   * @zh 设置上下文数据
+   * @en Set context data
+   */
+  set(key, value) {
+    this._contextData.set(key, value);
+  }
+  // =========================================================================
+  // 私有方法 | Private methods
+  // =========================================================================
+  _isTimedOut() {
+    return Date.now() - this._startTime > this._timeout;
+  }
+  async _compensate(fromIndex) {
+    this._state = "rolledback";
+    for (let i = fromIndex; i >= 0; i--) {
+      const op = this._operations[i];
+      try {
+        await op.compensate(this);
+        await this._updateOperationLog(i, "compensated");
+      } catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        await this._updateOperationLog(i, "failed", errorMessage);
+      }
+    }
+    await this._updateTransactionState("rolledback");
+  }
+  async _saveLog() {
+    if (!this._storage) return;
+    const log = {
+      id: this._id,
+      state: this._state,
+      createdAt: this._startTime,
+      updatedAt: this._startTime,
+      timeout: this._timeout,
+      operations: this._operations.map((op) => ({
+        name: op.name,
+        data: op.data,
+        state: "pending"
+      })),
+      metadata: this._metadata,
+      distributed: this._distributed
+    };
+    await this._storage.saveTransaction(log);
+  }
+  async _updateTransactionState(state) {
+    this._state = state;
+    if (this._storage) {
+      await this._storage.updateTransactionState(this._id, state);
+    }
+  }
+  async _updateOperationLog(index, state, error) {
+    if (this._storage) {
+      await this._storage.updateOperationState(this._id, index, state, error);
+    }
+  }
+  _collectResultData(results) {
+    const data = {};
+    for (const result of results) {
+      if (result.data !== void 0) {
+        Object.assign(data, result.data);
+      }
+    }
+    return Object.keys(data).length > 0 ? data : void 0;
+  }
+};
+__name(_TransactionContext, "TransactionContext");
+var TransactionContext = _TransactionContext;
+function createTransactionContext(options = {}) {
+  return new TransactionContext(options);
+}
+__name(createTransactionContext, "createTransactionContext");
+
+// src/core/TransactionManager.ts
+var _TransactionManager = class _TransactionManager {
+  constructor(config = {}) {
+    __publicField(this, "_storage");
+    __publicField(this, "_defaultTimeout");
+    __publicField(this, "_serverId");
+    __publicField(this, "_autoRecover");
+    __publicField(this, "_activeTransactions", /* @__PURE__ */ new Map());
+    this._storage = config.storage ?? null;
+    this._defaultTimeout = config.defaultTimeout ?? 3e4;
+    this._serverId = config.serverId ?? this._generateServerId();
+    this._autoRecover = config.autoRecover ?? true;
+  }
+  // =========================================================================
+  // 只读属性 | Readonly properties
+  // =========================================================================
+  /**
+   * @zh 服务器 ID
+   * @en Server ID
+   */
+  get serverId() {
+    return this._serverId;
+  }
+  /**
+   * @zh 存储实例
+   * @en Storage instance
+   */
+  get storage() {
+    return this._storage;
+  }
+  /**
+   * @zh 活跃事务数量
+   * @en Active transaction count
+   */
+  get activeCount() {
+    return this._activeTransactions.size;
+  }
+  // =========================================================================
+  // 公共方法 | Public methods
+  // =========================================================================
+  /**
+   * @zh 开始新事务
+   * @en Begin new transaction
+   *
+   * @param options - @zh 事务选项 @en Transaction options
+   * @returns @zh 事务上下文 @en Transaction context
+   */
+  begin(options = {}) {
+    const ctx = new TransactionContext({
+      timeout: options.timeout ?? this._defaultTimeout,
+      storage: this._storage ?? void 0,
+      metadata: {
+        ...options.metadata,
+        serverId: this._serverId
+      },
+      distributed: options.distributed
+    });
+    this._activeTransactions.set(ctx.id, ctx);
+    return ctx;
+  }
+  /**
+   * @zh 执行事务（便捷方法）
+   * @en Execute transaction (convenience method)
+   *
+   * @param builder - @zh 事务构建函数 @en Transaction builder function
+   * @param options - @zh 事务选项 @en Transaction options
+   * @returns @zh 事务结果 @en Transaction result
+   */
+  async run(builder, options = {}) {
+    const ctx = this.begin(options);
+    try {
+      await builder(ctx);
+      const result = await ctx.execute();
+      return result;
+    } finally {
+      this._activeTransactions.delete(ctx.id);
+    }
+  }
+  /**
+   * @zh 获取活跃事务
+   * @en Get active transaction
+   */
+  getTransaction(id) {
+    return this._activeTransactions.get(id);
+  }
+  /**
+   * @zh 恢复未完成的事务
+   * @en Recover pending transactions
+   */
+  async recover() {
+    if (!this._storage) return 0;
+    const pendingTransactions = await this._storage.getPendingTransactions(this._serverId);
+    let recoveredCount = 0;
+    for (const log of pendingTransactions) {
+      try {
+        await this._recoverTransaction(log);
+        recoveredCount++;
+      } catch (error) {
+        console.error(`Failed to recover transaction ${log.id}:`, error);
+      }
+    }
+    return recoveredCount;
+  }
+  /**
+   * @zh 获取分布式锁
+   * @en Acquire distributed lock
+   */
+  async acquireLock(key, ttl = 1e4) {
+    if (!this._storage) return null;
+    return this._storage.acquireLock(key, ttl);
+  }
+  /**
+   * @zh 释放分布式锁
+   * @en Release distributed lock
+   */
+  async releaseLock(key, token) {
+    if (!this._storage) return false;
+    return this._storage.releaseLock(key, token);
+  }
+  /**
+   * @zh 使用分布式锁执行
+   * @en Execute with distributed lock
+   */
+  async withLock(key, fn, ttl = 1e4) {
+    const token = await this.acquireLock(key, ttl);
+    if (!token) {
+      throw new Error(`Failed to acquire lock for key: ${key}`);
+    }
+    try {
+      return await fn();
+    } finally {
+      await this.releaseLock(key, token);
+    }
+  }
+  /**
+   * @zh 清理已完成的事务日志
+   * @en Clean up completed transaction logs
+   */
+  async cleanup(beforeTimestamp) {
+    if (!this._storage) return 0;
+    const timestamp = beforeTimestamp ?? Date.now() - 24 * 60 * 60 * 1e3;
+    const pendingTransactions = await this._storage.getPendingTransactions();
+    let cleanedCount = 0;
+    for (const log of pendingTransactions) {
+      if (log.createdAt < timestamp && (log.state === "committed" || log.state === "rolledback")) {
+        await this._storage.deleteTransaction(log.id);
+        cleanedCount++;
+      }
+    }
+    return cleanedCount;
+  }
+  // =========================================================================
+  // 私有方法 | Private methods
+  // =========================================================================
+  _generateServerId() {
+    return `server_${Date.now().toString(36)}_${Math.random().toString(36).substring(2, 8)}`;
+  }
+  async _recoverTransaction(log) {
+    if (log.state === "executing") {
+      const executedOps = log.operations.filter((op) => op.state === "executed");
+      if (executedOps.length > 0 && this._storage) {
+        for (let i = executedOps.length - 1; i >= 0; i--) {
+          await this._storage.updateOperationState(log.id, i, "compensated");
+        }
+        await this._storage.updateTransactionState(log.id, "rolledback");
+      } else {
+        await this._storage?.updateTransactionState(log.id, "failed");
+      }
+    }
+  }
+};
+__name(_TransactionManager, "TransactionManager");
+var TransactionManager = _TransactionManager;
+function createTransactionManager(config = {}) {
+  return new TransactionManager(config);
+}
+__name(createTransactionManager, "createTransactionManager");
+
+// src/storage/MemoryStorage.ts
+var _MemoryStorage = class _MemoryStorage {
+  constructor(config = {}) {
+    __publicField(this, "_transactions", /* @__PURE__ */ new Map());
+    __publicField(this, "_data", /* @__PURE__ */ new Map());
+    __publicField(this, "_locks", /* @__PURE__ */ new Map());
+    __publicField(this, "_maxTransactions");
+    this._maxTransactions = config.maxTransactions ?? 1e3;
+  }
+  // =========================================================================
+  // 分布式锁 | Distributed Lock
+  // =========================================================================
+  async acquireLock(key, ttl) {
+    this._cleanExpiredLocks();
+    const existing = this._locks.get(key);
+    if (existing && existing.expireAt > Date.now()) {
+      return null;
+    }
+    const token = `lock_${Date.now()}_${Math.random().toString(36).substring(2)}`;
+    this._locks.set(key, {
+      token,
+      expireAt: Date.now() + ttl
+    });
+    return token;
+  }
+  async releaseLock(key, token) {
+    const lock = this._locks.get(key);
+    if (!lock || lock.token !== token) {
+      return false;
+    }
+    this._locks.delete(key);
+    return true;
+  }
+  // =========================================================================
+  // 事务日志 | Transaction Log
+  // =========================================================================
+  async saveTransaction(tx) {
+    if (this._transactions.size >= this._maxTransactions) {
+      this._cleanOldTransactions();
+    }
+    this._transactions.set(tx.id, {
+      ...tx
+    });
+  }
+  async getTransaction(id) {
+    const tx = this._transactions.get(id);
+    return tx ? {
+      ...tx
+    } : null;
+  }
+  async updateTransactionState(id, state) {
+    const tx = this._transactions.get(id);
+    if (tx) {
+      tx.state = state;
+      tx.updatedAt = Date.now();
+    }
+  }
+  async updateOperationState(transactionId, operationIndex, state, error) {
+    const tx = this._transactions.get(transactionId);
+    if (tx && tx.operations[operationIndex]) {
+      tx.operations[operationIndex].state = state;
+      if (error) {
+        tx.operations[operationIndex].error = error;
+      }
+      if (state === "executed") {
+        tx.operations[operationIndex].executedAt = Date.now();
+      } else if (state === "compensated") {
+        tx.operations[operationIndex].compensatedAt = Date.now();
+      }
+      tx.updatedAt = Date.now();
+    }
+  }
+  async getPendingTransactions(serverId) {
+    const result = [];
+    for (const tx of this._transactions.values()) {
+      if (tx.state === "pending" || tx.state === "executing") {
+        if (!serverId || tx.metadata?.serverId === serverId) {
+          result.push({
+            ...tx
+          });
+        }
+      }
+    }
+    return result;
+  }
+  async deleteTransaction(id) {
+    this._transactions.delete(id);
+  }
+  // =========================================================================
+  // 数据操作 | Data Operations
+  // =========================================================================
+  async get(key) {
+    this._cleanExpiredData();
+    const entry = this._data.get(key);
+    if (!entry) return null;
+    if (entry.expireAt && entry.expireAt < Date.now()) {
+      this._data.delete(key);
+      return null;
+    }
+    return entry.value;
+  }
+  async set(key, value, ttl) {
+    this._data.set(key, {
+      value,
+      expireAt: ttl ? Date.now() + ttl : void 0
+    });
+  }
+  async delete(key) {
+    return this._data.delete(key);
+  }
+  // =========================================================================
+  // 辅助方法 | Helper methods
+  // =========================================================================
+  /**
+   * @zh 清空所有数据（测试用）
+   * @en Clear all data (for testing)
+   */
+  clear() {
+    this._transactions.clear();
+    this._data.clear();
+    this._locks.clear();
+  }
+  /**
+   * @zh 获取事务数量
+   * @en Get transaction count
+   */
+  get transactionCount() {
+    return this._transactions.size;
+  }
+  _cleanExpiredLocks() {
+    const now = Date.now();
+    for (const [key, lock] of this._locks) {
+      if (lock.expireAt < now) {
+        this._locks.delete(key);
+      }
+    }
+  }
+  _cleanExpiredData() {
+    const now = Date.now();
+    for (const [key, entry] of this._data) {
+      if (entry.expireAt && entry.expireAt < now) {
+        this._data.delete(key);
+      }
+    }
+  }
+  _cleanOldTransactions() {
+    const sorted = Array.from(this._transactions.entries()).sort((a, b) => a[1].createdAt - b[1].createdAt);
+    const toRemove = sorted.slice(0, Math.floor(this._maxTransactions * 0.2)).filter(([_, tx]) => tx.state === "committed" || tx.state === "rolledback");
+    for (const [id] of toRemove) {
+      this._transactions.delete(id);
+    }
+  }
+};
+__name(_MemoryStorage, "MemoryStorage");
+var MemoryStorage = _MemoryStorage;
+function createMemoryStorage(config = {}) {
+  return new MemoryStorage(config);
+}
+__name(createMemoryStorage, "createMemoryStorage");
+
+// src/storage/RedisStorage.ts
+var LOCK_SCRIPT = `
+if redis.call("get", KEYS[1]) == ARGV[1] then
+    return redis.call("del", KEYS[1])
+else
+    return 0
+end
+`;
+var _RedisStorage = class _RedisStorage {
+  constructor(config) {
+    __publicField(this, "_client", null);
+    __publicField(this, "_factory");
+    __publicField(this, "_prefix");
+    __publicField(this, "_transactionTTL");
+    __publicField(this, "_closed", false);
+    this._factory = config.factory;
+    this._prefix = config.prefix ?? "tx:";
+    this._transactionTTL = config.transactionTTL ?? 86400;
+  }
+  // =========================================================================
+  // 生命周期 | Lifecycle
+  // =========================================================================
+  /**
+   * @zh 获取 Redis 客户端（惰性连接）
+   * @en Get Redis client (lazy connection)
+   */
+  async _getClient() {
+    if (this._closed) {
+      throw new Error("RedisStorage is closed");
+    }
+    if (!this._client) {
+      this._client = await this._factory();
+    }
+    return this._client;
+  }
+  /**
+   * @zh 关闭存储连接
+   * @en Close storage connection
+   */
+  async close() {
+    if (this._closed) return;
+    this._closed = true;
+    if (this._client) {
+      await this._client.quit();
+      this._client = null;
+    }
+  }
+  /**
+   * @zh 支持 await using 语法
+   * @en Support await using syntax
+   */
+  async [Symbol.asyncDispose]() {
+    await this.close();
+  }
+  // =========================================================================
+  // 分布式锁 | Distributed Lock
+  // =========================================================================
+  async acquireLock(key, ttl) {
+    const client = await this._getClient();
+    const lockKey = `${this._prefix}lock:${key}`;
+    const token = `${Date.now()}_${Math.random().toString(36).substring(2)}`;
+    const ttlSeconds = Math.ceil(ttl / 1e3);
+    const result = await client.set(lockKey, token, "NX", "EX", String(ttlSeconds));
+    return result === "OK" ? token : null;
+  }
+  async releaseLock(key, token) {
+    const client = await this._getClient();
+    const lockKey = `${this._prefix}lock:${key}`;
+    const result = await client.eval(LOCK_SCRIPT, 1, lockKey, token);
+    return result === 1;
+  }
+  // =========================================================================
+  // 事务日志 | Transaction Log
+  // =========================================================================
+  async saveTransaction(tx) {
+    const client = await this._getClient();
+    const key = `${this._prefix}tx:${tx.id}`;
+    await client.set(key, JSON.stringify(tx));
+    await client.expire(key, this._transactionTTL);
+    if (tx.metadata?.serverId) {
+      const serverKey = `${this._prefix}server:${tx.metadata.serverId}:txs`;
+      await client.hset(serverKey, tx.id, String(tx.createdAt));
+    }
+  }
+  async getTransaction(id) {
+    const client = await this._getClient();
+    const key = `${this._prefix}tx:${id}`;
+    const data = await client.get(key);
+    return data ? JSON.parse(data) : null;
+  }
+  async updateTransactionState(id, state) {
+    const tx = await this.getTransaction(id);
+    if (tx) {
+      tx.state = state;
+      tx.updatedAt = Date.now();
+      await this.saveTransaction(tx);
+    }
+  }
+  async updateOperationState(transactionId, operationIndex, state, error) {
+    const tx = await this.getTransaction(transactionId);
+    if (tx && tx.operations[operationIndex]) {
+      tx.operations[operationIndex].state = state;
+      if (error) {
+        tx.operations[operationIndex].error = error;
+      }
+      if (state === "executed") {
+        tx.operations[operationIndex].executedAt = Date.now();
+      } else if (state === "compensated") {
+        tx.operations[operationIndex].compensatedAt = Date.now();
+      }
+      tx.updatedAt = Date.now();
+      await this.saveTransaction(tx);
+    }
+  }
+  async getPendingTransactions(serverId) {
+    const client = await this._getClient();
+    const result = [];
+    if (serverId) {
+      const serverKey = `${this._prefix}server:${serverId}:txs`;
+      const txIds = await client.hgetall(serverKey);
+      for (const id of Object.keys(txIds)) {
+        const tx = await this.getTransaction(id);
+        if (tx && (tx.state === "pending" || tx.state === "executing")) {
+          result.push(tx);
+        }
+      }
+    } else {
+      const pattern = `${this._prefix}tx:*`;
+      const keys = await client.keys(pattern);
+      for (const key of keys) {
+        const data = await client.get(key);
+        if (data) {
+          const tx = JSON.parse(data);
+          if (tx.state === "pending" || tx.state === "executing") {
+            result.push(tx);
+          }
+        }
+      }
+    }
+    return result;
+  }
+  async deleteTransaction(id) {
+    const client = await this._getClient();
+    const key = `${this._prefix}tx:${id}`;
+    const tx = await this.getTransaction(id);
+    await client.del(key);
+    if (tx?.metadata?.serverId) {
+      const serverKey = `${this._prefix}server:${tx.metadata.serverId}:txs`;
+      await client.hdel(serverKey, id);
+    }
+  }
+  // =========================================================================
+  // 数据操作 | Data Operations
+  // =========================================================================
+  async get(key) {
+    const client = await this._getClient();
+    const fullKey = `${this._prefix}data:${key}`;
+    const data = await client.get(fullKey);
+    return data ? JSON.parse(data) : null;
+  }
+  async set(key, value, ttl) {
+    const client = await this._getClient();
+    const fullKey = `${this._prefix}data:${key}`;
+    if (ttl) {
+      const ttlSeconds = Math.ceil(ttl / 1e3);
+      await client.set(fullKey, JSON.stringify(value), "EX", String(ttlSeconds));
+    } else {
+      await client.set(fullKey, JSON.stringify(value));
+    }
+  }
+  async delete(key) {
+    const client = await this._getClient();
+    const fullKey = `${this._prefix}data:${key}`;
+    const result = await client.del(fullKey);
+    return result > 0;
+  }
+};
+__name(_RedisStorage, "RedisStorage");
+var RedisStorage = _RedisStorage;
+function createRedisStorage(config) {
+  return new RedisStorage(config);
+}
+__name(createRedisStorage, "createRedisStorage");
+
+// src/storage/MongoStorage.ts
+var _MongoStorage = class _MongoStorage {
+  constructor(config) {
+    __publicField(this, "_connection");
+    __publicField(this, "_transactionCollection");
+    __publicField(this, "_dataCollection");
+    __publicField(this, "_lockCollection");
+    __publicField(this, "_closed", false);
+    this._connection = config.connection;
+    this._transactionCollection = config.transactionCollection ?? "transactions";
+    this._dataCollection = config.dataCollection ?? "transaction_data";
+    this._lockCollection = config.lockCollection ?? "transaction_locks";
+  }
+  // =========================================================================
+  // 生命周期 | Lifecycle
+  // =========================================================================
+  /**
+   * @zh 获取集合
+   * @en Get collection
+   */
+  _getCollection(name) {
+    if (this._closed) {
+      throw new Error("MongoStorage is closed");
+    }
+    if (!this._connection.isConnected()) {
+      throw new Error("MongoDB connection is not connected");
+    }
+    return this._connection.collection(name);
+  }
+  /**
+   * @zh 关闭存储
+   * @en Close storage
+   *
+   * @zh 不会关闭共享连接，只标记存储为已关闭
+   * @en Does not close shared connection, only marks storage as closed
+   */
+  async close() {
+    this._closed = true;
+  }
+  /**
+   * @zh 支持 await using 语法
+   * @en Support await using syntax
+   */
+  async [Symbol.asyncDispose]() {
+    await this.close();
+  }
+  /**
+   * @zh 确保索引存在
+   * @en Ensure indexes exist
+   */
+  async ensureIndexes() {
+    const txColl = this._getCollection(this._transactionCollection);
+    await txColl.createIndex({
+      state: 1
+    });
+    await txColl.createIndex({
+      "metadata.serverId": 1
+    });
+    await txColl.createIndex({
+      createdAt: 1
+    });
+    const lockColl = this._getCollection(this._lockCollection);
+    await lockColl.createIndex({
+      expireAt: 1
+    }, {
+      expireAfterSeconds: 0
+    });
+    const dataColl = this._getCollection(this._dataCollection);
+    await dataColl.createIndex({
+      expireAt: 1
+    }, {
+      expireAfterSeconds: 0
+    });
+  }
+  // =========================================================================
+  // 分布式锁 | Distributed Lock
+  // =========================================================================
+  async acquireLock(key, ttl) {
+    const coll = this._getCollection(this._lockCollection);
+    const token = `${Date.now()}_${Math.random().toString(36).substring(2)}`;
+    const expireAt = new Date(Date.now() + ttl);
+    try {
+      await coll.insertOne({
+        _id: key,
+        token,
+        expireAt
+      });
+      return token;
+    } catch {
+      const existing = await coll.findOne({
+        _id: key
+      });
+      if (existing && existing.expireAt < /* @__PURE__ */ new Date()) {
+        const result = await coll.updateOne({
+          _id: key,
+          expireAt: {
+            $lt: /* @__PURE__ */ new Date()
+          }
+        }, {
+          $set: {
+            token,
+            expireAt
+          }
+        });
+        if (result.modifiedCount > 0) {
+          return token;
+        }
+      }
+      return null;
+    }
+  }
+  async releaseLock(key, token) {
+    const coll = this._getCollection(this._lockCollection);
+    const result = await coll.deleteOne({
+      _id: key,
+      token
+    });
+    return result.deletedCount > 0;
+  }
+  // =========================================================================
+  // 事务日志 | Transaction Log
+  // =========================================================================
+  async saveTransaction(tx) {
+    const coll = this._getCollection(this._transactionCollection);
+    const existing = await coll.findOne({
+      _id: tx.id
+    });
+    if (existing) {
+      await coll.updateOne({
+        _id: tx.id
+      }, {
+        $set: {
+          ...tx,
+          _id: tx.id
+        }
+      });
+    } else {
+      await coll.insertOne({
+        ...tx,
+        _id: tx.id
+      });
+    }
+  }
+  async getTransaction(id) {
+    const coll = this._getCollection(this._transactionCollection);
+    const doc = await coll.findOne({
+      _id: id
+    });
+    if (!doc) return null;
+    const { _id, ...tx } = doc;
+    return tx;
+  }
+  async updateTransactionState(id, state) {
+    const coll = this._getCollection(this._transactionCollection);
+    await coll.updateOne({
+      _id: id
+    }, {
+      $set: {
+        state,
+        updatedAt: Date.now()
+      }
+    });
+  }
+  async updateOperationState(transactionId, operationIndex, state, error) {
+    const coll = this._getCollection(this._transactionCollection);
+    const update = {
+      [`operations.${operationIndex}.state`]: state,
+      updatedAt: Date.now()
+    };
+    if (error) {
+      update[`operations.${operationIndex}.error`] = error;
+    }
+    if (state === "executed") {
+      update[`operations.${operationIndex}.executedAt`] = Date.now();
+    } else if (state === "compensated") {
+      update[`operations.${operationIndex}.compensatedAt`] = Date.now();
+    }
+    await coll.updateOne({
+      _id: transactionId
+    }, {
+      $set: update
+    });
+  }
+  async getPendingTransactions(serverId) {
+    const coll = this._getCollection(this._transactionCollection);
+    const filter = {
+      state: {
+        $in: [
+          "pending",
+          "executing"
+        ]
+      }
+    };
+    if (serverId) {
+      filter["metadata.serverId"] = serverId;
+    }
+    const docs = await coll.find(filter);
+    return docs.map(({ _id, ...tx }) => tx);
+  }
+  async deleteTransaction(id) {
+    const coll = this._getCollection(this._transactionCollection);
+    await coll.deleteOne({
+      _id: id
+    });
+  }
+  // =========================================================================
+  // 数据操作 | Data Operations
+  // =========================================================================
+  async get(key) {
+    const coll = this._getCollection(this._dataCollection);
+    const doc = await coll.findOne({
+      _id: key
+    });
+    if (!doc) return null;
+    if (doc.expireAt && doc.expireAt < /* @__PURE__ */ new Date()) {
+      await coll.deleteOne({
+        _id: key
+      });
+      return null;
+    }
+    return doc.value;
+  }
+  async set(key, value, ttl) {
+    const coll = this._getCollection(this._dataCollection);
+    const doc = {
+      _id: key,
+      value
+    };
+    if (ttl) {
+      doc.expireAt = new Date(Date.now() + ttl);
+    }
+    const existing = await coll.findOne({
+      _id: key
+    });
+    if (existing) {
+      await coll.updateOne({
+        _id: key
+      }, {
+        $set: doc
+      });
+    } else {
+      await coll.insertOne(doc);
+    }
+  }
+  async delete(key) {
+    const coll = this._getCollection(this._dataCollection);
+    const result = await coll.deleteOne({
+      _id: key
+    });
+    return result.deletedCount > 0;
+  }
+};
+__name(_MongoStorage, "MongoStorage");
+var MongoStorage = _MongoStorage;
+function createMongoStorage(connection, options) {
+  return new MongoStorage({
+    connection,
+    ...options
+  });
+}
+__name(createMongoStorage, "createMongoStorage");
+
+// src/operations/BaseOperation.ts
+var _BaseOperation = class _BaseOperation {
+  constructor(data) {
+    __publicField(this, "data");
+    this.data = data;
+  }
+  /**
+   * @zh 验证前置条件（默认通过）
+   * @en Validate preconditions (passes by default)
+   */
+  async validate(_ctx) {
+    return true;
+  }
+  /**
+   * @zh 创建成功结果
+   * @en Create success result
+   */
+  success(data) {
+    return {
+      success: true,
+      data
+    };
+  }
+  /**
+   * @zh 创建失败结果
+   * @en Create failure result
+   */
+  failure(error, errorCode) {
+    return {
+      success: false,
+      error,
+      errorCode
+    };
+  }
+};
+__name(_BaseOperation, "BaseOperation");
+var BaseOperation = _BaseOperation;
+
+// src/operations/CurrencyOperation.ts
+var _CurrencyOperation = class _CurrencyOperation extends BaseOperation {
+  constructor() {
+    super(...arguments);
+    __publicField(this, "name", "currency");
+    __publicField(this, "_provider", null);
+    __publicField(this, "_beforeBalance", 0);
+  }
+  /**
+   * @zh 设置货币数据提供者
+   * @en Set currency data provider
+   */
+  setProvider(provider) {
+    this._provider = provider;
+    return this;
+  }
+  async validate(ctx) {
+    if (this.data.amount <= 0) {
+      return false;
+    }
+    if (this.data.type === "deduct") {
+      const balance = await this._getBalance(ctx);
+      return balance >= this.data.amount;
+    }
+    return true;
+  }
+  async execute(ctx) {
+    const { type, playerId, currency, amount } = this.data;
+    this._beforeBalance = await this._getBalance(ctx);
+    let afterBalance;
+    if (type === "add") {
+      afterBalance = this._beforeBalance + amount;
+    } else {
+      if (this._beforeBalance < amount) {
+        return this.failure("Insufficient balance", "INSUFFICIENT_BALANCE");
+      }
+      afterBalance = this._beforeBalance - amount;
+    }
+    await this._setBalance(ctx, afterBalance);
+    ctx.set(`currency:${playerId}:${currency}:before`, this._beforeBalance);
+    ctx.set(`currency:${playerId}:${currency}:after`, afterBalance);
+    return this.success({
+      beforeBalance: this._beforeBalance,
+      afterBalance
+    });
+  }
+  async compensate(ctx) {
+    await this._setBalance(ctx, this._beforeBalance);
+  }
+  async _getBalance(ctx) {
+    const { playerId, currency } = this.data;
+    if (this._provider) {
+      return this._provider.getBalance(playerId, currency);
+    }
+    if (ctx.storage) {
+      const balance = await ctx.storage.get(`player:${playerId}:currency:${currency}`);
+      return balance ?? 0;
+    }
+    return 0;
+  }
+  async _setBalance(ctx, amount) {
+    const { playerId, currency } = this.data;
+    if (this._provider) {
+      await this._provider.setBalance(playerId, currency, amount);
+      return;
+    }
+    if (ctx.storage) {
+      await ctx.storage.set(`player:${playerId}:currency:${currency}`, amount);
+    }
+  }
+};
+__name(_CurrencyOperation, "CurrencyOperation");
+var CurrencyOperation = _CurrencyOperation;
+function createCurrencyOperation(data) {
+  return new CurrencyOperation(data);
+}
+__name(createCurrencyOperation, "createCurrencyOperation");
+
+// src/operations/InventoryOperation.ts
+var _InventoryOperation = class _InventoryOperation extends BaseOperation {
+  constructor() {
+    super(...arguments);
+    __publicField(this, "name", "inventory");
+    __publicField(this, "_provider", null);
+    __publicField(this, "_beforeItem", null);
+  }
+  /**
+   * @zh 设置背包数据提供者
+   * @en Set inventory data provider
+   */
+  setProvider(provider) {
+    this._provider = provider;
+    return this;
+  }
+  async validate(ctx) {
+    const { type, quantity } = this.data;
+    if (quantity <= 0) {
+      return false;
+    }
+    if (type === "remove") {
+      const item = await this._getItem(ctx);
+      return item !== null && item.quantity >= quantity;
+    }
+    if (type === "add" && this._provider?.hasCapacity) {
+      return this._provider.hasCapacity(this.data.playerId, 1);
+    }
+    return true;
+  }
+  async execute(ctx) {
+    const { type, playerId, itemId, quantity, properties } = this.data;
+    this._beforeItem = await this._getItem(ctx);
+    let afterItem = null;
+    switch (type) {
+      case "add": {
+        if (this._beforeItem) {
+          afterItem = {
+            ...this._beforeItem,
+            quantity: this._beforeItem.quantity + quantity
+          };
+        } else {
+          afterItem = {
+            itemId,
+            quantity,
+            properties
+          };
+        }
+        break;
+      }
+      case "remove": {
+        if (!this._beforeItem || this._beforeItem.quantity < quantity) {
+          return this.failure("Insufficient item quantity", "INSUFFICIENT_ITEM");
+        }
+        const newQuantity = this._beforeItem.quantity - quantity;
+        if (newQuantity > 0) {
+          afterItem = {
+            ...this._beforeItem,
+            quantity: newQuantity
+          };
+        } else {
+          afterItem = null;
+        }
+        break;
+      }
+      case "update": {
+        if (!this._beforeItem) {
+          return this.failure("Item not found", "ITEM_NOT_FOUND");
+        }
+        afterItem = {
+          ...this._beforeItem,
+          quantity: quantity > 0 ? quantity : this._beforeItem.quantity,
+          properties: properties ?? this._beforeItem.properties
+        };
+        break;
+      }
+    }
+    await this._setItem(ctx, afterItem);
+    ctx.set(`inventory:${playerId}:${itemId}:before`, this._beforeItem);
+    ctx.set(`inventory:${playerId}:${itemId}:after`, afterItem);
+    return this.success({
+      beforeItem: this._beforeItem ?? void 0,
+      afterItem: afterItem ?? void 0
+    });
+  }
+  async compensate(ctx) {
+    await this._setItem(ctx, this._beforeItem);
+  }
+  async _getItem(ctx) {
+    const { playerId, itemId } = this.data;
+    if (this._provider) {
+      return this._provider.getItem(playerId, itemId);
+    }
+    if (ctx.storage) {
+      return ctx.storage.get(`player:${playerId}:inventory:${itemId}`);
+    }
+    return null;
+  }
+  async _setItem(ctx, item) {
+    const { playerId, itemId } = this.data;
+    if (this._provider) {
+      await this._provider.setItem(playerId, itemId, item);
+      return;
+    }
+    if (ctx.storage) {
+      if (item) {
+        await ctx.storage.set(`player:${playerId}:inventory:${itemId}`, item);
+      } else {
+        await ctx.storage.delete(`player:${playerId}:inventory:${itemId}`);
+      }
+    }
+  }
+};
+__name(_InventoryOperation, "InventoryOperation");
+var InventoryOperation = _InventoryOperation;
+function createInventoryOperation(data) {
+  return new InventoryOperation(data);
+}
+__name(createInventoryOperation, "createInventoryOperation");
+
+// src/operations/TradeOperation.ts
+var _TradeOperation = class _TradeOperation extends BaseOperation {
+  constructor() {
+    super(...arguments);
+    __publicField(this, "name", "trade");
+    __publicField(this, "_provider", null);
+    __publicField(this, "_subOperations", []);
+    __publicField(this, "_executedCount", 0);
+  }
+  /**
+   * @zh 设置交易数据提供者
+   * @en Set trade data provider
+   */
+  setProvider(provider) {
+    this._provider = provider;
+    return this;
+  }
+  async validate(ctx) {
+    this._buildSubOperations();
+    for (const op of this._subOperations) {
+      const isValid = await op.validate(ctx);
+      if (!isValid) {
+        return false;
+      }
+    }
+    return true;
+  }
+  async execute(ctx) {
+    this._buildSubOperations();
+    this._executedCount = 0;
+    try {
+      for (const op of this._subOperations) {
+        const result = await op.execute(ctx);
+        if (!result.success) {
+          await this._compensateExecuted(ctx);
+          return this.failure(result.error ?? "Trade operation failed", "TRADE_FAILED");
+        }
+        this._executedCount++;
+      }
+      return this.success({
+        tradeId: this.data.tradeId,
+        completed: true
+      });
+    } catch (error) {
+      await this._compensateExecuted(ctx);
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      return this.failure(errorMessage, "TRADE_ERROR");
+    }
+  }
+  async compensate(ctx) {
+    await this._compensateExecuted(ctx);
+  }
+  _buildSubOperations() {
+    if (this._subOperations.length > 0) return;
+    const { partyA, partyB } = this.data;
+    if (partyA.items) {
+      for (const item of partyA.items) {
+        const removeOp = new InventoryOperation({
+          type: "remove",
+          playerId: partyA.playerId,
+          itemId: item.itemId,
+          quantity: item.quantity,
+          reason: `trade:${this.data.tradeId}:give`
+        });
+        const addOp = new InventoryOperation({
+          type: "add",
+          playerId: partyB.playerId,
+          itemId: item.itemId,
+          quantity: item.quantity,
+          reason: `trade:${this.data.tradeId}:receive`
+        });
+        if (this._provider?.inventoryProvider) {
+          removeOp.setProvider(this._provider.inventoryProvider);
+          addOp.setProvider(this._provider.inventoryProvider);
+        }
+        this._subOperations.push(removeOp, addOp);
+      }
+    }
+    if (partyA.currencies) {
+      for (const curr of partyA.currencies) {
+        const deductOp = new CurrencyOperation({
+          type: "deduct",
+          playerId: partyA.playerId,
+          currency: curr.currency,
+          amount: curr.amount,
+          reason: `trade:${this.data.tradeId}:give`
+        });
+        const addOp = new CurrencyOperation({
+          type: "add",
+          playerId: partyB.playerId,
+          currency: curr.currency,
+          amount: curr.amount,
+          reason: `trade:${this.data.tradeId}:receive`
+        });
+        if (this._provider?.currencyProvider) {
+          deductOp.setProvider(this._provider.currencyProvider);
+          addOp.setProvider(this._provider.currencyProvider);
+        }
+        this._subOperations.push(deductOp, addOp);
+      }
+    }
+    if (partyB.items) {
+      for (const item of partyB.items) {
+        const removeOp = new InventoryOperation({
+          type: "remove",
+          playerId: partyB.playerId,
+          itemId: item.itemId,
+          quantity: item.quantity,
+          reason: `trade:${this.data.tradeId}:give`
+        });
+        const addOp = new InventoryOperation({
+          type: "add",
+          playerId: partyA.playerId,
+          itemId: item.itemId,
+          quantity: item.quantity,
+          reason: `trade:${this.data.tradeId}:receive`
+        });
+        if (this._provider?.inventoryProvider) {
+          removeOp.setProvider(this._provider.inventoryProvider);
+          addOp.setProvider(this._provider.inventoryProvider);
+        }
+        this._subOperations.push(removeOp, addOp);
+      }
+    }
+    if (partyB.currencies) {
+      for (const curr of partyB.currencies) {
+        const deductOp = new CurrencyOperation({
+          type: "deduct",
+          playerId: partyB.playerId,
+          currency: curr.currency,
+          amount: curr.amount,
+          reason: `trade:${this.data.tradeId}:give`
+        });
+        const addOp = new CurrencyOperation({
+          type: "add",
+          playerId: partyA.playerId,
+          currency: curr.currency,
+          amount: curr.amount,
+          reason: `trade:${this.data.tradeId}:receive`
+        });
+        if (this._provider?.currencyProvider) {
+          deductOp.setProvider(this._provider.currencyProvider);
+          addOp.setProvider(this._provider.currencyProvider);
+        }
+        this._subOperations.push(deductOp, addOp);
+      }
+    }
+  }
+  async _compensateExecuted(ctx) {
+    for (let i = this._executedCount - 1; i >= 0; i--) {
+      await this._subOperations[i].compensate(ctx);
+    }
+  }
+};
+__name(_TradeOperation, "TradeOperation");
+var TradeOperation = _TradeOperation;
+function createTradeOperation(data) {
+  return new TradeOperation(data);
+}
+__name(createTradeOperation, "createTradeOperation");
+
+// src/distributed/SagaOrchestrator.ts
+function generateSagaId() {
+  return `saga_${Date.now().toString(36)}_${Math.random().toString(36).substring(2, 11)}`;
+}
+__name(generateSagaId, "generateSagaId");
+var _SagaOrchestrator = class _SagaOrchestrator {
+  constructor(config = {}) {
+    __publicField(this, "_storage");
+    __publicField(this, "_timeout");
+    __publicField(this, "_serverId");
+    this._storage = config.storage ?? null;
+    this._timeout = config.timeout ?? 3e4;
+    this._serverId = config.serverId ?? "default";
+  }
+  /**
+   * @zh 执行 Saga
+   * @en Execute Saga
+   */
+  async execute(steps) {
+    const sagaId = generateSagaId();
+    const startTime = Date.now();
+    const completedSteps = [];
+    const sagaLog = {
+      id: sagaId,
+      state: "pending",
+      steps: steps.map((s) => ({
+        name: s.name,
+        serverId: s.serverId,
+        state: "pending"
+      })),
+      createdAt: startTime,
+      updatedAt: startTime,
+      metadata: {
+        orchestratorServerId: this._serverId
+      }
+    };
+    await this._saveSagaLog(sagaLog);
+    try {
+      sagaLog.state = "running";
+      await this._saveSagaLog(sagaLog);
+      for (let i = 0; i < steps.length; i++) {
+        const step = steps[i];
+        if (Date.now() - startTime > this._timeout) {
+          throw new Error("Saga execution timed out");
+        }
+        sagaLog.steps[i].state = "executing";
+        sagaLog.steps[i].startedAt = Date.now();
+        await this._saveSagaLog(sagaLog);
+        const result = await step.execute(step.data);
+        if (!result.success) {
+          sagaLog.steps[i].state = "failed";
+          sagaLog.steps[i].error = result.error;
+          await this._saveSagaLog(sagaLog);
+          throw new Error(result.error ?? `Step ${step.name} failed`);
+        }
+        sagaLog.steps[i].state = "completed";
+        sagaLog.steps[i].completedAt = Date.now();
+        completedSteps.push(step.name);
+        await this._saveSagaLog(sagaLog);
+      }
+      sagaLog.state = "completed";
+      sagaLog.updatedAt = Date.now();
+      await this._saveSagaLog(sagaLog);
+      return {
+        success: true,
+        sagaId,
+        completedSteps,
+        duration: Date.now() - startTime
+      };
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      const failedStepIndex = completedSteps.length;
+      sagaLog.state = "compensating";
+      await this._saveSagaLog(sagaLog);
+      for (let i = completedSteps.length - 1; i >= 0; i--) {
+        const step = steps[i];
+        sagaLog.steps[i].state = "compensating";
+        await this._saveSagaLog(sagaLog);
+        try {
+          await step.compensate(step.data);
+          sagaLog.steps[i].state = "compensated";
+        } catch (compError) {
+          const compErrorMessage = compError instanceof Error ? compError.message : String(compError);
+          sagaLog.steps[i].state = "failed";
+          sagaLog.steps[i].error = `Compensation failed: ${compErrorMessage}`;
+        }
+        await this._saveSagaLog(sagaLog);
+      }
+      sagaLog.state = "compensated";
+      sagaLog.updatedAt = Date.now();
+      await this._saveSagaLog(sagaLog);
+      return {
+        success: false,
+        sagaId,
+        completedSteps,
+        failedStep: steps[failedStepIndex]?.name,
+        error: errorMessage,
+        duration: Date.now() - startTime
+      };
+    }
+  }
+  /**
+   * @zh 恢复未完成的 Saga
+   * @en Recover pending Sagas
+   */
+  async recover() {
+    if (!this._storage) return 0;
+    const pendingSagas = await this._getPendingSagas();
+    let recoveredCount = 0;
+    for (const saga of pendingSagas) {
+      try {
+        await this._recoverSaga(saga);
+        recoveredCount++;
+      } catch (error) {
+        console.error(`Failed to recover saga ${saga.id}:`, error);
+      }
+    }
+    return recoveredCount;
+  }
+  /**
+   * @zh 获取 Saga 日志
+   * @en Get Saga log
+   */
+  async getSagaLog(sagaId) {
+    if (!this._storage) return null;
+    return this._storage.get(`saga:${sagaId}`);
+  }
+  async _saveSagaLog(log) {
+    if (!this._storage) return;
+    log.updatedAt = Date.now();
+    await this._storage.set(`saga:${log.id}`, log);
+  }
+  async _getPendingSagas() {
+    return [];
+  }
+  async _recoverSaga(saga) {
+    if (saga.state === "running" || saga.state === "compensating") {
+      const completedSteps = saga.steps.filter((s) => s.state === "completed").map((s) => s.name);
+      saga.state = "compensated";
+      saga.updatedAt = Date.now();
+      if (this._storage) {
+        await this._storage.set(`saga:${saga.id}`, saga);
+      }
+    }
+  }
+};
+__name(_SagaOrchestrator, "SagaOrchestrator");
+var SagaOrchestrator = _SagaOrchestrator;
+function createSagaOrchestrator(config = {}) {
+  return new SagaOrchestrator(config);
+}
+__name(createSagaOrchestrator, "createSagaOrchestrator");
+
+// src/integration/RoomTransactionMixin.ts
+function withTransactions(Base, config = {}) {
+  var _a;
+  return _a = class extends Base {
+    constructor(...args) {
+      super(...args);
+      __publicField(this, "_transactionManager");
+      this._transactionManager = new TransactionManager({
+        storage: config.storage,
+        defaultTimeout: config.defaultTimeout,
+        serverId: config.serverId
+      });
+    }
+    get transactions() {
+      return this._transactionManager;
+    }
+    beginTransaction(options) {
+      return this._transactionManager.begin(options);
+    }
+    runTransaction(builder, options) {
+      return this._transactionManager.run(builder, options);
+    }
+  }, __name(_a, "TransactionRoom"), _a;
+}
+__name(withTransactions, "withTransactions");
+var _TransactionRoom = class _TransactionRoom {
+  constructor(config = {}) {
+    __publicField(this, "_transactionManager");
+    this._transactionManager = new TransactionManager({
+      storage: config.storage,
+      defaultTimeout: config.defaultTimeout,
+      serverId: config.serverId
+    });
+  }
+  get transactions() {
+    return this._transactionManager;
+  }
+  beginTransaction(options) {
+    return this._transactionManager.begin(options);
+  }
+  runTransaction(builder, options) {
+    return this._transactionManager.run(builder, options);
+  }
+};
+__name(_TransactionRoom, "TransactionRoom");
+var TransactionRoom = _TransactionRoom;
+
+// src/tokens.ts
+import { createServiceToken } from "@esengine/ecs-framework";
+var TransactionManagerToken = createServiceToken("transactionManager");
+var TransactionStorageToken = createServiceToken("transactionStorage");
+export {
+  BaseOperation,
+  CurrencyOperation,
+  InventoryOperation,
+  MemoryStorage,
+  MongoStorage,
+  RedisStorage,
+  SagaOrchestrator,
+  TradeOperation,
+  TransactionContext,
+  TransactionManager,
+  TransactionManagerToken,
+  TransactionRoom,
+  TransactionStorageToken,
+  createCurrencyOperation,
+  createInventoryOperation,
+  createMemoryStorage,
+  createMongoStorage,
+  createRedisStorage,
+  createSagaOrchestrator,
+  createTradeOperation,
+  createTransactionContext,
+  createTransactionManager,
+  withTransactions
+};
+//# sourceMappingURL=index.js.map