@esengine/transaction 2.0.7 → 2.1.1

package/dist/distributed/SagaOrchestrator.d.ts

@@ -0,0 +1,173 @@
+/**
+ * @zh Saga 编排器
+ * @en Saga Orchestrator
+ *
+ * @zh 实现分布式事务的 Saga 模式编排
+ * @en Implements Saga pattern orchestration for distributed transactions
+ */
+import type { ITransactionStorage, OperationResult } from '../core/types.js';
+/**
+ * @zh Saga 步骤状态
+ * @en Saga step state
+ */
+export type SagaStepState = 'pending' | 'executing' | 'completed' | 'compensating' | 'compensated' | 'failed';
+/**
+ * @zh Saga 步骤
+ * @en Saga step
+ */
+export interface SagaStep<T = unknown> {
+    /**
+     * @zh 步骤名称
+     * @en Step name
+     */
+    name: string;
+    /**
+     * @zh 目标服务器 ID（分布式用）
+     * @en Target server ID (for distributed)
+     */
+    serverId?: string;
+    /**
+     * @zh 执行函数
+     * @en Execute function
+     */
+    execute: (data: T) => Promise<OperationResult>;
+    /**
+     * @zh 补偿函数
+     * @en Compensate function
+     */
+    compensate: (data: T) => Promise<void>;
+    /**
+     * @zh 步骤数据
+     * @en Step data
+     */
+    data: T;
+}
+/**
+ * @zh Saga 步骤日志
+ * @en Saga step log
+ */
+export interface SagaStepLog {
+    name: string;
+    serverId?: string;
+    state: SagaStepState;
+    startedAt?: number;
+    completedAt?: number;
+    error?: string;
+}
+/**
+ * @zh Saga 日志
+ * @en Saga log
+ */
+export interface SagaLog {
+    id: string;
+    state: 'pending' | 'running' | 'completed' | 'compensating' | 'compensated' | 'failed';
+    steps: SagaStepLog[];
+    createdAt: number;
+    updatedAt: number;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * @zh Saga 结果
+ * @en Saga result
+ */
+export interface SagaResult {
+    success: boolean;
+    sagaId: string;
+    completedSteps: string[];
+    failedStep?: string;
+    error?: string;
+    duration: number;
+}
+/**
+ * @zh Saga 编排器配置
+ * @en Saga orchestrator configuration
+ */
+export interface SagaOrchestratorConfig {
+    /**
+     * @zh 存储实例
+     * @en Storage instance
+     */
+    storage?: ITransactionStorage;
+    /**
+     * @zh 默认超时时间（毫秒）
+     * @en Default timeout in milliseconds
+     */
+    timeout?: number;
+    /**
+     * @zh 服务器 ID
+     * @en Server ID
+     */
+    serverId?: string;
+}
+/**
+ * @zh Saga 编排器
+ * @en Saga Orchestrator
+ *
+ * @zh 管理分布式事务的 Saga 模式执行流程
+ * @en Manages Saga pattern execution flow for distributed transactions
+ *
+ * @example
+ * ```typescript
+ * const orchestrator = new SagaOrchestrator({
+ *     storage: redisStorage,
+ *     serverId: 'server1',
+ * })
+ *
+ * const result = await orchestrator.execute([
+ *     {
+ *         name: 'deduct_currency',
+ *         serverId: 'server1',
+ *         execute: async (data) => {
+ *             // 扣除货币
+ *             return { success: true }
+ *         },
+ *         compensate: async (data) => {
+ *             // 恢复货币
+ *         },
+ *         data: { playerId: '1', amount: 100 },
+ *     },
+ *     {
+ *         name: 'add_item',
+ *         serverId: 'server2',
+ *         execute: async (data) => {
+ *             // 添加物品
+ *             return { success: true }
+ *         },
+ *         compensate: async (data) => {
+ *             // 移除物品
+ *         },
+ *         data: { playerId: '1', itemId: 'sword' },
+ *     },
+ * ])
+ * ```
+ */
+export declare class SagaOrchestrator {
+    private _storage;
+    private _timeout;
+    private _serverId;
+    constructor(config?: SagaOrchestratorConfig);
+    /**
+     * @zh 执行 Saga
+     * @en Execute Saga
+     */
+    execute<T>(steps: SagaStep<T>[]): Promise<SagaResult>;
+    /**
+     * @zh 恢复未完成的 Saga
+     * @en Recover pending Sagas
+     */
+    recover(): Promise<number>;
+    /**
+     * @zh 获取 Saga 日志
+     * @en Get Saga log
+     */
+    getSagaLog(sagaId: string): Promise<SagaLog | null>;
+    private _saveSagaLog;
+    private _getPendingSagas;
+    private _recoverSaga;
+}
+/**
+ * @zh 创建 Saga 编排器
+ * @en Create Saga orchestrator
+ */
+export declare function createSagaOrchestrator(config?: SagaOrchestratorConfig): SagaOrchestrator;
+//# sourceMappingURL=SagaOrchestrator.d.ts.map

package/dist/distributed/SagaOrchestrator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SagaOrchestrator.d.ts","sourceRoot":"","sources":["../../src/distributed/SagaOrchestrator.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EACR,mBAAmB,EAGnB,eAAe,EAClB,MAAM,kBAAkB,CAAC;AAE1B;;;GAGG;AACH,MAAM,MAAM,aAAa,GAAG,SAAS,GAAG,WAAW,GAAG,WAAW,GAAG,cAAc,GAAG,aAAa,GAAG,QAAQ,CAAA;AAE7G;;;GAGG;AACH,MAAM,WAAW,QAAQ,CAAC,CAAC,GAAG,OAAO;IACjC;;;OAGG;IACH,IAAI,EAAE,MAAM,CAAA;IAEZ;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IAEjB;;;OAGG;IACH,OAAO,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,OAAO,CAAC,eAAe,CAAC,CAAA;IAE9C;;;OAGG;IACH,UAAU,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IAEtC;;;OAGG;IACH,IAAI,EAAE,CAAC,CAAA;CACV;AAED;;;GAGG;AACH,MAAM,WAAW,WAAW;IACxB,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,KAAK,EAAE,aAAa,CAAA;IACpB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,KAAK,CAAC,EAAE,MAAM,CAAA;CACjB;AAED;;;GAGG;AACH,MAAM,WAAW,OAAO;IACpB,EAAE,EAAE,MAAM,CAAA;IACV,KAAK,EAAE,SAAS,GAAG,SAAS,GAAG,WAAW,GAAG,cAAc,GAAG,aAAa,GAAG,QAAQ,CAAA;IACtF,KAAK,EAAE,WAAW,EAAE,CAAA;IACpB,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,MAAM,CAAA;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACrC;AAED;;;GAGG;AACH,MAAM,WAAW,UAAU;IACvB,OAAO,EAAE,OAAO,CAAA;IAChB,MAAM,EAAE,MAAM,CAAA;IACd,cAAc,EAAE,MAAM,EAAE,CAAA;IACxB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,QAAQ,EAAE,MAAM,CAAA;CACnB;AAED;;;GAGG;AACH,MAAM,WAAW,sBAAsB;IACnC;;;OAGG;IACH,OAAO,CAAC,EAAE,mBAAmB,CAAA;IAE7B;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;IAEhB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;CACpB;AAUD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,qBAAa,gBAAgB;IACzB,OAAO,CAAC,QAAQ,CAA6B;IAC7C,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,SAAS,CAAS;gBAEd,MAAM,GAAE,sBAA2B;IAM/C;;;OAGG;IACG,OAAO,CAAC,CAAC,EAAE,KAAK,EAAE,QAAQ,CAAC,CAAC,CAAC,EAAE,GAAG,OAAO,CAAC,UAAU,CAAC;IAqG3D;;;OAGG;IACG,OAAO,IAAI,OAAO,CAAC,MAAM,CAAC;IAkBhC;;;OAGG;IACG,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC;YAK3C,YAAY;YAMZ,gBAAgB;YAIhB,YAAY;CAc7B;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,GAAE,sBAA2B,GAAG,gBAAgB,CAE5F"}

package/dist/distributed/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * @zh 分布式模块导出
+ * @en Distributed module exports
+ */
+export { SagaOrchestrator, createSagaOrchestrator, type SagaOrchestratorConfig, type SagaStep, type SagaStepState, type SagaStepLog, type SagaLog, type SagaResult } from './SagaOrchestrator.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/distributed/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/distributed/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EACH,gBAAgB,EAChB,sBAAsB,EACtB,KAAK,sBAAsB,EAC3B,KAAK,QAAQ,EACb,KAAK,aAAa,EAClB,KAAK,WAAW,EAChB,KAAK,OAAO,EACZ,KAAK,UAAU,EAClB,MAAM,uBAAuB,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,56 @@
+/**
+ * @zh @esengine/transaction 事务系统
+ * @en @esengine/transaction Transaction System
+ *
+ * @zh 提供游戏事务处理能力，支持商店购买、玩家交易、分布式事务
+ * @en Provides game transaction capabilities, supporting shop purchases, player trading, and distributed transactions
+ *
+ * @example
+ * ```typescript
+ * import {
+ *     TransactionManager,
+ *     MemoryStorage,
+ *     CurrencyOperation,
+ *     InventoryOperation,
+ * } from '@esengine/transaction'
+ *
+ * // 创建事务管理器
+ * const manager = new TransactionManager({
+ *     storage: new MemoryStorage(),
+ * })
+ *
+ * // 执行事务
+ * const result = await manager.run((tx) => {
+ *     tx.addOperation(new CurrencyOperation({
+ *         type: 'deduct',
+ *         playerId: 'player1',
+ *         currency: 'gold',
+ *         amount: 100,
+ *     }))
+ *     tx.addOperation(new InventoryOperation({
+ *         type: 'add',
+ *         playerId: 'player1',
+ *         itemId: 'sword',
+ *         quantity: 1,
+ *     }))
+ * })
+ *
+ * if (result.success) {
+ *     console.log('Transaction completed!')
+ * }
+ * ```
+ */
+export type { TransactionState, OperationResult, TransactionResult, OperationLog, TransactionLog, TransactionOptions, TransactionManagerConfig, ITransactionStorage, ITransactionOperation, ITransactionContext } from './core/types.js';
+export { TransactionContext, createTransactionContext } from './core/TransactionContext.js';
+export { TransactionManager, createTransactionManager } from './core/TransactionManager.js';
+export { MemoryStorage, createMemoryStorage, type MemoryStorageConfig } from './storage/MemoryStorage.js';
+export { RedisStorage, createRedisStorage, type RedisStorageConfig, type RedisClient } from './storage/RedisStorage.js';
+export { MongoStorage, createMongoStorage, type MongoStorageConfig } from './storage/MongoStorage.js';
+export { BaseOperation } from './operations/BaseOperation.js';
+export { CurrencyOperation, createCurrencyOperation, type CurrencyOperationType, type CurrencyOperationData, type CurrencyOperationResult, type ICurrencyProvider } from './operations/CurrencyOperation.js';
+export { InventoryOperation, createInventoryOperation, type InventoryOperationType, type InventoryOperationData, type InventoryOperationResult, type IInventoryProvider, type ItemData } from './operations/InventoryOperation.js';
+export { TradeOperation, createTradeOperation, type TradeOperationData, type TradeOperationResult, type TradeItem, type TradeCurrency, type TradeParty, type ITradeProvider } from './operations/TradeOperation.js';
+export { SagaOrchestrator, createSagaOrchestrator, type SagaOrchestratorConfig, type SagaStep, type SagaStepState, type SagaStepLog, type SagaLog, type SagaResult } from './distributed/SagaOrchestrator.js';
+export { withTransactions, TransactionRoom, type TransactionRoomConfig, type ITransactionRoom } from './integration/RoomTransactionMixin.js';
+export { TransactionManagerToken, TransactionStorageToken } from './tokens.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAMH,YAAY,EACR,gBAAgB,EAChB,eAAe,EACf,iBAAiB,EACjB,YAAY,EACZ,cAAc,EACd,kBAAkB,EAClB,wBAAwB,EACxB,mBAAmB,EACnB,qBAAqB,EACrB,mBAAmB,EACtB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACH,kBAAkB,EAClB,wBAAwB,EAC3B,MAAM,8BAA8B,CAAC;AAEtC,OAAO,EACH,kBAAkB,EAClB,wBAAwB,EAC3B,MAAM,8BAA8B,CAAC;AAMtC,OAAO,EACH,aAAa,EACb,mBAAmB,EACnB,KAAK,mBAAmB,EAC3B,MAAM,4BAA4B,CAAC;AAEpC,OAAO,EACH,YAAY,EACZ,kBAAkB,EAClB,KAAK,kBAAkB,EACvB,KAAK,WAAW,EACnB,MAAM,2BAA2B,CAAC;AAEnC,OAAO,EACH,YAAY,EACZ,kBAAkB,EAClB,KAAK,kBAAkB,EAC1B,MAAM,2BAA2B,CAAC;AAMnC,OAAO,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAE9D,OAAO,EACH,iBAAiB,EACjB,uBAAuB,EACvB,KAAK,qBAAqB,EAC1B,KAAK,qBAAqB,EAC1B,KAAK,uBAAuB,EAC5B,KAAK,iBAAiB,EACzB,MAAM,mCAAmC,CAAC;AAE3C,OAAO,EACH,kBAAkB,EAClB,wBAAwB,EACxB,KAAK,sBAAsB,EAC3B,KAAK,sBAAsB,EAC3B,KAAK,wBAAwB,EAC7B,KAAK,kBAAkB,EACvB,KAAK,QAAQ,EAChB,MAAM,oCAAoC,CAAC;AAE5C,OAAO,EACH,cAAc,EACd,oBAAoB,EACpB,KAAK,kBAAkB,EACvB,KAAK,oBAAoB,EACzB,KAAK,SAAS,EACd,KAAK,aAAa,EAClB,KAAK,UAAU,EACf,KAAK,cAAc,EACtB,MAAM,gCAAgC,CAAC;AAMxC,OAAO,EACH,gBAAgB,EAChB,sBAAsB,EACtB,KAAK,sBAAsB,EAC3B,KAAK,QAAQ,EACb,KAAK,aAAa,EAClB,KAAK,WAAW,EAChB,KAAK,OAAO,EACZ,KAAK,UAAU,EAClB,MAAM,mCAAmC,CAAC;AAM3C,OAAO,EACH,gBAAgB,EAChB,eAAe,EACf,KAAK,qBAAqB,EAC1B,KAAK,gBAAgB,EACxB,MAAM,uCAAuC,CAAC;AAM/C,OAAO,EACH,uBAAuB,EACvB,uBAAuB,EAC1B,MAAM,aAAa,CAAC"}