@arcaelas/dynamite 1.0.9 → 1.0.13

package/src/utils/transaction-manager.d.ts

@@ -0,0 +1,88 @@
+/**
+ * @file transaction-manager.ts
+ * @description Transaction simulation and rollback system for DynamoDB
+ * @author Miguel Alejandro
+ * @fecha 2025-08-31
+ */
+import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
+interface TransactionOperation {
+    type: 'create' | 'update' | 'delete';
+    tableName: string;
+    key: Record<string, any>;
+    item?: Record<string, any>;
+    conditionExpression?: string;
+    rollbackData?: Record<string, any>;
+}
+interface TransactionSnapshot {
+    id: string;
+    operations: TransactionOperation[];
+    timestamp: number;
+    status: 'pending' | 'committed' | 'rolled_back' | 'failed';
+}
+interface TransactionConfig {
+    maxOperationsPerTransaction: number;
+    snapshotTTL: number;
+    enableOptimisticLocking: boolean;
+    maxRetries: number;
+}
+declare class TransactionManager {
+    private static readonly DEFAULT_CONFIG;
+    private client;
+    private config;
+    private activeTransactions;
+    private snapshots;
+    constructor(client: DynamoDBClient, config?: Partial<TransactionConfig>);
+    /**
+     * Iniciar nueva transacción
+     */
+    beginTransaction(operations: TransactionOperation[]): Promise<string>;
+    /**
+     * Ejecutar transacción usando DynamoDB TransactWrite
+     */
+    commitTransaction(transactionId: string): Promise<void>;
+    /**
+     * Rollback manual de transacción
+     */
+    rollbackTransaction(transactionId: string): Promise<void>;
+    /**
+     * Crear snapshot del estado actual para rollback
+     */
+    private createSnapshot;
+    /**
+     * Obtener estado actual de un item
+     */
+    private getCurrentItemState;
+    /**
+     * Crear operaciones inversas para rollback
+     */
+    private createRollbackOperations;
+    /**
+     * Ejecutar lote de operaciones usando TransactWrite
+     */
+    private executeBatch;
+    /**
+     * Dividir operaciones en lotes según límites DynamoDB
+     */
+    private splitIntoBatches;
+    /**
+     * Validar operaciones antes de transacción
+     */
+    private validateOperations;
+    /**
+     * Limpiar snapshots expirados
+     */
+    private cleanupExpiredSnapshots;
+    /**
+     * Obtener estado de transacción
+     */
+    getTransactionStatus(transactionId: string): TransactionSnapshot | null;
+    /**
+     * Listar transacciones activas
+     */
+    getActiveTransactions(): TransactionSnapshot[];
+    private generateTransactionId;
+}
+declare class TransactionError extends Error {
+    constructor(message: string);
+}
+export { TransactionManager, TransactionOperation, TransactionSnapshot, TransactionError, TransactionConfig };

package/src/utils/transaction-manager.js

@@ -0,0 +1,298 @@
+"use strict";
+/**
+ * @file transaction-manager.ts
+ * @description Transaction simulation and rollback system for DynamoDB
+ * @author Miguel Alejandro
+ * @fecha 2025-08-31
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TransactionError = exports.TransactionManager = void 0;
+const client_dynamodb_1 = require("@aws-sdk/client-dynamodb");
+const util_dynamodb_1 = require("@aws-sdk/util-dynamodb");
+const throttle_manager_1 = __importDefault(require("./throttle-manager"));
+const security_validator_1 = __importDefault(require("./security-validator"));
+class TransactionManager {
+    static { this.DEFAULT_CONFIG = {
+        maxOperationsPerTransaction: 25, // DynamoDB limit
+        snapshotTTL: 3600000, // 1 hour
+        enableOptimisticLocking: true,
+        maxRetries: 3,
+    }; }
+    constructor(client, config) {
+        this.activeTransactions = new Map();
+        this.snapshots = new Map();
+        this.client = client;
+        this.config = { ...TransactionManager.DEFAULT_CONFIG, ...config };
+        // Cleanup expired snapshots
+        setInterval(() => this.cleanupExpiredSnapshots(), 300000); // 5 minutes
+    }
+    /**
+     * Iniciar nueva transacción
+     */
+    async beginTransaction(operations) {
+        const transactionId = this.generateTransactionId();
+        // Validar operaciones
+        this.validateOperations(operations);
+        // Crear snapshot del estado actual para rollback
+        const snapshot = await this.createSnapshot(transactionId, operations);
+        this.activeTransactions.set(transactionId, snapshot);
+        this.snapshots.set(transactionId, snapshot);
+        return transactionId;
+    }
+    /**
+     * Ejecutar transacción usando DynamoDB TransactWrite
+     */
+    async commitTransaction(transactionId) {
+        const snapshot = this.activeTransactions.get(transactionId);
+        if (!snapshot) {
+            throw new TransactionError(`Transaction ${transactionId} not found`);
+        }
+        try {
+            snapshot.status = 'pending';
+            // Agrupar operaciones en lotes de 25 (límite DynamoDB)
+            const batches = this.splitIntoBatches(snapshot.operations);
+            for (const batch of batches) {
+                await this.executeBatch(batch);
+            }
+            snapshot.status = 'committed';
+            this.activeTransactions.delete(transactionId);
+        }
+        catch (error) {
+            snapshot.status = 'failed';
+            // Intentar rollback automático
+            try {
+                await this.rollbackTransaction(transactionId);
+            }
+            catch (rollbackError) {
+                console.error('Rollback failed after commit error:', rollbackError);
+            }
+            throw new TransactionError(`Transaction commit failed: ${error.message}`);
+        }
+    }
+    /**
+     * Rollback manual de transacción
+     */
+    async rollbackTransaction(transactionId) {
+        const snapshot = this.snapshots.get(transactionId);
+        if (!snapshot) {
+            throw new TransactionError(`Transaction snapshot ${transactionId} not found`);
+        }
+        try {
+            // Crear operaciones inversas para rollback
+            const rollbackOps = this.createRollbackOperations(snapshot.operations);
+            if (rollbackOps.length > 0) {
+                const batches = this.splitIntoBatches(rollbackOps);
+                for (const batch of batches) {
+                    await this.executeBatch(batch);
+                }
+            }
+            snapshot.status = 'rolled_back';
+            this.activeTransactions.delete(transactionId);
+        }
+        catch (error) {
+            throw new TransactionError(`Rollback failed: ${error.message}`);
+        }
+    }
+    /**
+     * Crear snapshot del estado actual para rollback
+     */
+    async createSnapshot(transactionId, operations) {
+        const snapshot = {
+            id: transactionId,
+            operations: [],
+            timestamp: Date.now(),
+            status: 'pending',
+        };
+        // Para cada operación, guardar el estado actual del item
+        for (const op of operations) {
+            try {
+                const currentItem = await this.getCurrentItemState(op.tableName, op.key);
+                const snapshotOp = {
+                    ...op,
+                    rollbackData: currentItem || undefined, // Estado actual para rollback
+                };
+                snapshot.operations.push(snapshotOp);
+            }
+            catch (error) {
+                if (error.name !== 'ResourceNotFoundException') {
+                    throw error;
+                }
+                // Item no existe, sin datos de rollback necesarios
+                snapshot.operations.push(op);
+            }
+        }
+        return snapshot;
+    }
+    /**
+     * Obtener estado actual de un item
+     */
+    async getCurrentItemState(tableName, key) {
+        const params = {
+            TransactItems: [{
+                    Get: {
+                        TableName: tableName,
+                        Key: (0, util_dynamodb_1.marshall)(key),
+                    }
+                }]
+        };
+        const result = await throttle_manager_1.default.executeWithRetry(() => this.client.send(new client_dynamodb_1.TransactGetItemsCommand(params)), `GetItem-${tableName}`);
+        return result.Responses?.[0]?.Item
+            ? (0, util_dynamodb_1.unmarshall)(result.Responses[0].Item)
+            : null;
+    }
+    /**
+     * Crear operaciones inversas para rollback
+     */
+    createRollbackOperations(operations) {
+        const rollbackOps = [];
+        // Procesar en orden inverso
+        for (let i = operations.length - 1; i >= 0; i--) {
+            const op = operations[i];
+            switch (op.type) {
+                case 'create':
+                    // Para rollback de create: delete el item
+                    rollbackOps.push({
+                        type: 'delete',
+                        tableName: op.tableName,
+                        key: op.key,
+                    });
+                    break;
+                case 'update':
+                    if (op.rollbackData) {
+                        // Para rollback de update: restore estado anterior
+                        rollbackOps.push({
+                            type: 'update',
+                            tableName: op.tableName,
+                            key: op.key,
+                            item: op.rollbackData,
+                        });
+                    }
+                    break;
+                case 'delete':
+                    if (op.rollbackData) {
+                        // Para rollback de delete: recrear el item
+                        rollbackOps.push({
+                            type: 'create',
+                            tableName: op.tableName,
+                            key: op.key,
+                            item: op.rollbackData,
+                        });
+                    }
+                    break;
+            }
+        }
+        return rollbackOps;
+    }
+    /**
+     * Ejecutar lote de operaciones usando TransactWrite
+     */
+    async executeBatch(operations) {
+        const transactItems = operations.map(op => {
+            security_validator_1.default.validateItemSize(op.item || op.key);
+            switch (op.type) {
+                case 'create':
+                case 'update':
+                    return {
+                        Put: {
+                            TableName: op.tableName,
+                            Item: (0, util_dynamodb_1.marshall)(op.item, { removeUndefinedValues: true }),
+                            ConditionExpression: op.conditionExpression,
+                        }
+                    };
+                case 'delete':
+                    return {
+                        Delete: {
+                            TableName: op.tableName,
+                            Key: (0, util_dynamodb_1.marshall)(op.key),
+                            ConditionExpression: op.conditionExpression,
+                        }
+                    };
+                default:
+                    throw new TransactionError(`Unknown operation type: ${op.type}`);
+            }
+        });
+        const command = new client_dynamodb_1.TransactWriteItemsCommand({
+            TransactItems: transactItems,
+        });
+        await throttle_manager_1.default.executeWithRetry(() => this.client.send(command), 'TransactWrite');
+    }
+    /**
+     * Dividir operaciones en lotes según límites DynamoDB
+     */
+    splitIntoBatches(operations) {
+        const batches = [];
+        const batchSize = this.config.maxOperationsPerTransaction;
+        for (let i = 0; i < operations.length; i += batchSize) {
+            batches.push(operations.slice(i, i + batchSize));
+        }
+        return batches;
+    }
+    /**
+     * Validar operaciones antes de transacción
+     */
+    validateOperations(operations) {
+        if (operations.length === 0) {
+            throw new TransactionError('Transaction must contain at least one operation');
+        }
+        if (operations.length > this.config.maxOperationsPerTransaction * 10) {
+            throw new TransactionError(`Too many operations: ${operations.length}`);
+        }
+        for (const op of operations) {
+            // Validar estructura de la operación
+            if (!op.tableName || !op.key) {
+                throw new TransactionError('Invalid operation: missing tableName or key');
+            }
+            // Validar datos de seguridad
+            security_validator_1.default.validateQueryFilters(op.key);
+            if (op.item) {
+                security_validator_1.default.validateValue(op.item);
+            }
+        }
+    }
+    /**
+     * Limpiar snapshots expirados
+     */
+    cleanupExpiredSnapshots() {
+        const now = Date.now();
+        const expired = [];
+        for (const [id, snapshot] of this.snapshots.entries()) {
+            if (now - snapshot.timestamp > this.config.snapshotTTL) {
+                expired.push(id);
+            }
+        }
+        expired.forEach(id => {
+            this.snapshots.delete(id);
+            this.activeTransactions.delete(id);
+        });
+        if (expired.length > 0) {
+            console.log(`Cleaned up ${expired.length} expired transaction snapshots`);
+        }
+    }
+    /**
+     * Obtener estado de transacción
+     */
+    getTransactionStatus(transactionId) {
+        return this.snapshots.get(transactionId) || null;
+    }
+    /**
+     * Listar transacciones activas
+     */
+    getActiveTransactions() {
+        return Array.from(this.activeTransactions.values());
+    }
+    generateTransactionId() {
+        return `txn_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+    }
+}
+exports.TransactionManager = TransactionManager;
+class TransactionError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'TransactionError';
+    }
+}
+exports.TransactionError = TransactionError;
+//# sourceMappingURL=transaction-manager.js.map

package/build/core/table.d.ts

@@ -1,138 +0,0 @@
-import { DynamoDBClientConfig } from "@aws-sdk/client-dynamodb";
-import { InferAttributes, STORE, WrapperEntry } from "./wrapper";
-export declare function connect(cfg: DynamoDBClientConfig): void;
-export default class Table<T extends {} = any> {
-    protected [STORE]: {
-        [K in keyof T]?: T[K];
-    };
-    constructor(data: InferAttributes<T>);
-    save(): Promise<this>;
-    update(patch: InferAttributes<T>): Promise<this>;
-    destroy(): Promise<void>;
-    static create<M extends Table>(this: {
-        new (data: InferAttributes<M>): M;
-        prototype: M;
-    }, data: InferAttributes<M>): Promise<M>;
-    static update<M extends Table>(this: {
-        new (data: InferAttributes<M>): M;
-        prototype: M;
-    }, id: string, record: InferAttributes<M>): Promise<void>;
-    static destroy<M extends Table>(this: {
-        new (data: InferAttributes<M>): M;
-        prototype: M;
-    }, id: string): Promise<null>;
-    /**
-     * Realiza una consulta sobre la tabla, devolviendo una lista de resultados
-     * según condiciones y opciones de paginación/orden. Utiliza `QueryCommand`
-     * si la condición es por PK/SK con igualdad, o `ScanCommand` como fallback.
-     *
-     * @template M Instancia de la clase Table.
-     * @template K Clave de atributos inferida.
-     *
-     * @param key     - Clave a filtrar (ej. "id").
-     * @param value   - Valor a comparar (equivalente a '=' implícito).
-     * @param options - (Opcional) Opciones de paginación: { limit, skip, order }.
-     *
-     * @example
-     *   await User.where('id', 'u1');
-     *   await User.where('email', '=', 'a@b.com', { limit: 5, order: 'DESC' });
-     *   await User.where({ email: 'x@y.com' }, { skip: 10, limit: 1 });
-     *
-     * @param filters - Objeto con pares clave/valor para consulta tipo AND.
-     * @param options - (Opcional) Opciones de paginación: { limit, skip, order }.
-     *
-     * @returns       - Array de instancias de la tabla que cumplen la condición.
-     */
-    static where<M extends Table, K extends keyof InferAttributes<M>>(this: {
-        new (data: InferAttributes<M>): M;
-        prototype: M;
-    }, key: K, value: InferAttributes<M>[K], options?: {
-        limit?: number;
-        skip?: number;
-        order?: "ASC" | "DESC";
-    }): Promise<M[]>;
-    static where<M extends Table, K extends keyof InferAttributes<M>>(this: {
-        new (data: InferAttributes<M>): M;
-        prototype: M;
-    }, key: K, op: "=" | "!=" | "<" | "<=" | ">" | ">=" | "in" | "not-in", value: InferAttributes<M>[K] | InferAttributes<M>[K][], options?: {
-        limit?: number;
-        skip?: number;
-        order?: "ASC" | "DESC";
-    }): Promise<M[]>;
-    static where<M extends Table>(this: {
-        new (data: InferAttributes<M>): M;
-        prototype: M;
-    }, filters: Partial<{
-        [K in keyof InferAttributes<M>]: InferAttributes<M>[K] | InferAttributes<M>[K][];
-    }>, options?: {
-        limit?: number;
-        skip?: number;
-        order?: "ASC" | "DESC";
-    }): Promise<M[]>;
-    /**
-     * Obtiene el primer elemento que coincida con la condición especificada.
-     * Equivalente a where() con { limit: 1, skip: 0, order: "ASC" }.
-     *
-     * @template M Instancia de la clase Table.
-     * @template K Clave de atributos inferida.
-     *
-     * @param key   - Clave a filtrar (ej. "id").
-     * @param value - Valor a comparar (equivalente a '=' implícito).
-     *
-     * @example
-     *   const user = await User.first('id', 'u1');
-     *   const firstActive = await User.first('status', '=', 'active');
-     *   const firstMatch = await User.first({ email: 'test@example.com' });
-     *
-     * @returns - El primer elemento encontrado o undefined si no hay coincidencias.
-     */
-    static first<M extends Table, K extends keyof InferAttributes<M>>(this: {
-        new (data: InferAttributes<M>): M;
-        prototype: M;
-    }, key: K, value: InferAttributes<M>[K]): Promise<M | undefined>;
-    static first<M extends Table, K extends keyof InferAttributes<M>>(this: {
-        new (data: InferAttributes<M>): M;
-        prototype: M;
-    }, key: K, op: "=" | "!=" | "<" | "<=" | ">" | ">=" | "in" | "not-in", value: InferAttributes<M>[K] | InferAttributes<M>[K][]): Promise<M | undefined>;
-    static first<M extends Table>(this: {
-        new (data: InferAttributes<M>): M;
-        prototype: M;
-    }, filters: Partial<{
-        [K in keyof InferAttributes<M>]: InferAttributes<M>[K] | InferAttributes<M>[K][];
-    }>): Promise<M | undefined>;
-    /**
-     * Obtiene el último elemento que coincida con la condición especificada.
-     * Equivalente a where() con { limit: 1, skip: 0, order: "DESC" }.
-     *
-     * @template M Instancia de la clase Table.
-     * @template K Clave de atributos inferida.
-     *
-     * @param key   - Clave a filtrar (ej. "id").
-     * @param value - Valor a comparar (equivalente a '=' implícito).
-     *
-     * @example
-     *   const user = await User.last('id', 'u1');
-     *   const lastActive = await User.last('status', '=', 'active');
-     *   const lastMatch = await User.last({ email: 'test@example.com' });
-     *
-     * @returns - El último elemento encontrado o undefined si no hay coincidencias.
-     */
-    static last<M extends Table, K extends keyof InferAttributes<M>>(this: {
-        new (data: InferAttributes<M>): M;
-        prototype: M;
-    }, key: K, value: InferAttributes<M>[K]): Promise<M | undefined>;
-    static last<M extends Table, K extends keyof InferAttributes<M>>(this: {
-        new (data: InferAttributes<M>): M;
-        prototype: M;
-    }, key: K, op: "=" | "!=" | "<" | "<=" | ">" | ">=" | "in" | "not-in", value: InferAttributes<M>[K] | InferAttributes<M>[K][]): Promise<M | undefined>;
-    static last<M extends Table>(this: {
-        new (data: InferAttributes<M>): M;
-        prototype: M;
-    }, filters: Partial<{
-        [K in keyof InferAttributes<M>]: InferAttributes<M>[K] | InferAttributes<M>[K][];
-    }>): Promise<M | undefined>;
-    toJSON(): Record<string, unknown>;
-    toString(): string;
-}
-export { STORE };
-export type { WrapperEntry };