@arcaelas/dynamite 1.0.9 → 1.0.13

package/src/utils/circular-detector.d.ts

@@ -0,0 +1,82 @@
+/**
+ * @file circular-detector.ts
+ * @description Detection and prevention of circular references in relations
+ * @author Miguel Alejandro
+ * @fecha 2025-08-31
+ */
+interface TraversalPath {
+    modelName: string;
+    relationKey: string;
+    depth: number;
+}
+interface CircularDetectionConfig {
+    maxDepth: number;
+    maxIncludeDepth: number;
+    trackingEnabled: boolean;
+}
+declare class CircularReferenceDetector {
+    private static readonly DEFAULT_CONFIG;
+    private config;
+    private activePaths;
+    private pathHistory;
+    constructor(config?: Partial<CircularDetectionConfig>);
+    /**
+     * Verificar si una ruta de inclusión es segura
+     */
+    validateIncludePath(modelName: string, includeOptions: any, currentDepth?: number, visitedModels?: Set<string>): void;
+    /**
+     * Validar estructura de relaciones en tiempo de definición
+     */
+    validateRelationStructure(models: Map<string, any>, maxAllowedCycles?: number): ValidationResult;
+    /**
+     * Construir grafo de relaciones
+     */
+    private buildRelationGraph;
+    /**
+     * Detectar ciclos usando DFS
+     */
+    private detectCycles;
+    /**
+     * Generar sugerencias para resolver ciclos
+     */
+    private generateSuggestions;
+    /**
+     * Inferir nombre del modelo target (simplificado)
+     */
+    private inferTargetModelName;
+    /**
+     * Crear contexto de rastreo para includes anidados
+     */
+    createTrackingContext(): CircularTracker;
+    /**
+     * Obtener historial de paths para debugging
+     */
+    getPathHistory(): TraversalPath[];
+    /**
+     * Limpiar historial
+     */
+    clearHistory(): void;
+}
+/**
+ * Tracker específico para una operación de include
+ */
+declare class CircularTracker {
+    private visitedModels;
+    private currentPath;
+    private maxDepth;
+    constructor(maxDepth: number);
+    enter(modelName: string): void;
+    exit(modelName: string): void;
+    getCurrentPath(): string[];
+}
+interface ValidationResult {
+    isValid: boolean;
+    cycles: string[][];
+    suggestions: string[];
+}
+declare class CircularReferenceError extends Error {
+    constructor(message: string);
+}
+declare const circularDetector: CircularReferenceDetector;
+export { CircularReferenceDetector, CircularTracker, CircularReferenceError, ValidationResult, circularDetector };
+export default circularDetector;

package/src/utils/circular-detector.js

@@ -0,0 +1,209 @@
+"use strict";
+/**
+ * @file circular-detector.ts
+ * @description Detection and prevention of circular references in relations
+ * @author Miguel Alejandro
+ * @fecha 2025-08-31
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.circularDetector = exports.CircularReferenceError = exports.CircularTracker = exports.CircularReferenceDetector = void 0;
+class CircularReferenceDetector {
+    static { this.DEFAULT_CONFIG = {
+        maxDepth: 10,
+        maxIncludeDepth: 5,
+        trackingEnabled: true,
+    }; }
+    constructor(config) {
+        this.activePaths = new Set();
+        this.pathHistory = [];
+        this.config = { ...CircularReferenceDetector.DEFAULT_CONFIG, ...config };
+    }
+    /**
+     * Verificar si una ruta de inclusión es segura
+     */
+    validateIncludePath(modelName, includeOptions, currentDepth = 0, visitedModels = new Set()) {
+        // Verificar profundidad máxima
+        if (currentDepth > this.config.maxIncludeDepth) {
+            throw new CircularReferenceError(`Include depth exceeded limit of ${this.config.maxIncludeDepth} at model: ${modelName}`);
+        }
+        // Detectar referencia circular directa
+        if (visitedModels.has(modelName)) {
+            const path = Array.from(visitedModels).join(' -> ') + ` -> ${modelName}`;
+            throw new CircularReferenceError(`Circular reference detected in include path: ${path}`);
+        }
+        if (!includeOptions || typeof includeOptions !== 'object') {
+            return;
+        }
+        const newVisited = new Set(visitedModels);
+        newVisited.add(modelName);
+        // Validar cada relación incluida
+        for (const [relationKey, relationOptions] of Object.entries(includeOptions)) {
+            if (this.config.trackingEnabled) {
+                this.pathHistory.push({
+                    modelName,
+                    relationKey,
+                    depth: currentDepth,
+                });
+            }
+            // Si la relación tiene sus propios includes, validar recursivamente
+            if (relationOptions && typeof relationOptions === 'object' && 'include' in relationOptions) {
+                // Aquí necesitaríamos obtener el modelo target de la relación
+                // Por simplicidad, usamos el relationKey como modelo (esto debería mejorar)
+                const targetModelName = this.inferTargetModelName(relationKey);
+                this.validateIncludePath(targetModelName, relationOptions.include, currentDepth + 1, newVisited);
+            }
+        }
+    }
+    /**
+     * Validar estructura de relaciones en tiempo de definición
+     */
+    validateRelationStructure(models, maxAllowedCycles = 0) {
+        const graph = this.buildRelationGraph(models);
+        const cycles = this.detectCycles(graph);
+        return {
+            isValid: cycles.length <= maxAllowedCycles,
+            cycles,
+            suggestions: this.generateSuggestions(cycles),
+        };
+    }
+    /**
+     * Construir grafo de relaciones
+     */
+    buildRelationGraph(models) {
+        const graph = new Map();
+        for (const [modelName, model] of models.entries()) {
+            const relations = [];
+            // Esto necesitaría acceso a los metadatos del modelo
+            // Por ahora simulamos la extracción de relaciones
+            const meta = model.getMeta?.();
+            if (meta?.relations) {
+                for (const [relationKey, relation] of meta.relations.entries()) {
+                    const targetModel = relation.targetModel?.()?.name || relationKey;
+                    relations.push(targetModel);
+                }
+            }
+            graph.set(modelName, relations);
+        }
+        return graph;
+    }
+    /**
+     * Detectar ciclos usando DFS
+     */
+    detectCycles(graph) {
+        const cycles = [];
+        const visited = new Set();
+        const recursionStack = new Set();
+        const dfs = (node, path) => {
+            if (recursionStack.has(node)) {
+                // Ciclo detectado
+                const cycleStart = path.indexOf(node);
+                const cycle = path.slice(cycleStart).concat(node);
+                cycles.push(cycle);
+                return;
+            }
+            if (visited.has(node)) {
+                return;
+            }
+            visited.add(node);
+            recursionStack.add(node);
+            path.push(node);
+            const neighbors = graph.get(node) || [];
+            for (const neighbor of neighbors) {
+                dfs(neighbor, [...path]);
+            }
+            recursionStack.delete(node);
+        };
+        for (const node of graph.keys()) {
+            if (!visited.has(node)) {
+                dfs(node, []);
+            }
+        }
+        return cycles;
+    }
+    /**
+     * Generar sugerencias para resolver ciclos
+     */
+    generateSuggestions(cycles) {
+        const suggestions = [];
+        for (const cycle of cycles) {
+            if (cycle.length === 2) {
+                suggestions.push(`Circular reference between ${cycle[0]} and ${cycle[1]}. Consider using lazy loading or removing one direction.`);
+            }
+            else {
+                suggestions.push(`Complex circular reference detected: ${cycle.join(' -> ')}. Consider breaking the cycle at the weakest relationship.`);
+            }
+        }
+        if (cycles.length > 0) {
+            suggestions.push('General: Use @NonAttribute for computed relationships or implement lazy loading to break cycles.');
+        }
+        return suggestions;
+    }
+    /**
+     * Inferir nombre del modelo target (simplificado)
+     */
+    inferTargetModelName(relationKey) {
+        // Conversión simple: posts -> Post, user -> User
+        return relationKey.charAt(0).toUpperCase() + relationKey.slice(1).replace(/s$/, '');
+    }
+    /**
+     * Crear contexto de rastreo para includes anidados
+     */
+    createTrackingContext() {
+        return new CircularTracker(this.config.maxIncludeDepth);
+    }
+    /**
+     * Obtener historial de paths para debugging
+     */
+    getPathHistory() {
+        return [...this.pathHistory];
+    }
+    /**
+     * Limpiar historial
+     */
+    clearHistory() {
+        this.pathHistory = [];
+        this.activePaths.clear();
+    }
+}
+exports.CircularReferenceDetector = CircularReferenceDetector;
+/**
+ * Tracker específico para una operación de include
+ */
+class CircularTracker {
+    constructor(maxDepth) {
+        this.visitedModels = new Set();
+        this.currentPath = [];
+        this.maxDepth = maxDepth;
+    }
+    enter(modelName) {
+        if (this.currentPath.length >= this.maxDepth) {
+            throw new CircularReferenceError(`Maximum include depth ${this.maxDepth} exceeded at: ${modelName}`);
+        }
+        if (this.visitedModels.has(modelName)) {
+            const cyclePath = this.currentPath.join(' -> ') + ` -> ${modelName}`;
+            throw new CircularReferenceError(`Circular reference detected: ${cyclePath}`);
+        }
+        this.visitedModels.add(modelName);
+        this.currentPath.push(modelName);
+    }
+    exit(modelName) {
+        this.currentPath.pop();
+        this.visitedModels.delete(modelName);
+    }
+    getCurrentPath() {
+        return [...this.currentPath];
+    }
+}
+exports.CircularTracker = CircularTracker;
+class CircularReferenceError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'CircularReferenceError';
+    }
+}
+exports.CircularReferenceError = CircularReferenceError;
+// Instancia singleton
+const circularDetector = new CircularReferenceDetector();
+exports.circularDetector = circularDetector;
+exports.default = circularDetector;
+//# sourceMappingURL=circular-detector.js.map

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

@@ -0,0 +1,42 @@
+/**
+ * @file memory-manager.ts
+ * @description Memory management and leak prevention
+ * @author Miguel Alejandro
+ * @fecha 2025-08-31
+ */
+declare class MemoryManager {
+    private static instance;
+    private cleanupTasks;
+    private maxCacheSize;
+    private maxCacheAge;
+    static getInstance(): MemoryManager;
+    /**
+     * Registrar una tarea de limpieza
+     */
+    registerCleanup(id: string, cleanup: () => void, intervalMs?: number): void;
+    /**
+     * Desregistrar y limpiar tarea
+     */
+    unregisterCleanup(id: string): void;
+    /**
+     * Limpiar cache con límites de tamaño y edad
+     */
+    cleanCache<T>(cache: Map<string, {
+        data: T;
+        expires: number;
+        created: number;
+    }>, maxSize?: number): void;
+    /**
+     * Monitorear uso de memoria
+     */
+    getMemoryUsage(): NodeJS.MemoryUsage;
+    /**
+     * Forzar garbage collection si está disponible
+     */
+    forceGC(): void;
+    /**
+     * Cleanup completo al shutdown
+     */
+    shutdown(): void;
+}
+export default MemoryManager;

package/src/utils/memory-manager.js

@@ -0,0 +1,108 @@
+"use strict";
+/**
+ * @file memory-manager.ts
+ * @description Memory management and leak prevention
+ * @author Miguel Alejandro
+ * @fecha 2025-08-31
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+class MemoryManager {
+    constructor() {
+        this.cleanupTasks = new Map();
+        this.maxCacheSize = 1000;
+        this.maxCacheAge = 300000; // 5 minutos
+    }
+    static getInstance() {
+        if (!MemoryManager.instance) {
+            MemoryManager.instance = new MemoryManager();
+        }
+        return MemoryManager.instance;
+    }
+    /**
+     * Registrar una tarea de limpieza
+     */
+    registerCleanup(id, cleanup, intervalMs) {
+        // Limpiar tarea previa si existe
+        this.unregisterCleanup(id);
+        const task = { id, cleanup };
+        if (intervalMs) {
+            task.interval = setInterval(() => {
+                try {
+                    cleanup();
+                }
+                catch (error) {
+                    console.warn(`Cleanup task ${id} failed:`, error);
+                }
+            }, intervalMs);
+        }
+        this.cleanupTasks.set(id, task);
+    }
+    /**
+     * Desregistrar y limpiar tarea
+     */
+    unregisterCleanup(id) {
+        const task = this.cleanupTasks.get(id);
+        if (task) {
+            if (task.interval) {
+                clearInterval(task.interval);
+            }
+            task.cleanup();
+            this.cleanupTasks.delete(id);
+        }
+    }
+    /**
+     * Limpiar cache con límites de tamaño y edad
+     */
+    cleanCache(cache, maxSize = this.maxCacheSize) {
+        const now = Date.now();
+        // Remover entradas expiradas
+        for (const [key, entry] of cache.entries()) {
+            if (entry.expires <= now || (now - entry.created) > this.maxCacheAge) {
+                cache.delete(key);
+            }
+        }
+        // Si aún excede el tamaño, remover las más antiguas
+        if (cache.size > maxSize) {
+            const entries = Array.from(cache.entries())
+                .sort((a, b) => a[1].created - b[1].created);
+            const toRemove = entries.slice(0, cache.size - maxSize);
+            toRemove.forEach(([key]) => cache.delete(key));
+        }
+    }
+    /**
+     * Monitorear uso de memoria
+     */
+    getMemoryUsage() {
+        return process.memoryUsage();
+    }
+    /**
+     * Forzar garbage collection si está disponible
+     */
+    forceGC() {
+        if (global.gc) {
+            global.gc();
+        }
+    }
+    /**
+     * Cleanup completo al shutdown
+     */
+    shutdown() {
+        console.log('MemoryManager: Iniciando cleanup completo...');
+        for (const [id, task] of this.cleanupTasks.entries()) {
+            try {
+                this.unregisterCleanup(id);
+            }
+            catch (error) {
+                console.warn(`Error cleaning up task ${id}:`, error);
+            }
+        }
+        this.cleanupTasks.clear();
+        this.forceGC();
+    }
+}
+// Cleanup automático en shutdown
+process.on('SIGTERM', () => MemoryManager.getInstance().shutdown());
+process.on('SIGINT', () => MemoryManager.getInstance().shutdown());
+process.on('uncaughtException', () => MemoryManager.getInstance().shutdown());
+exports.default = MemoryManager;
+//# sourceMappingURL=memory-manager.js.map

package/src/utils/naming.d.ts

@@ -0,0 +1,8 @@
+/**
+ * @file naming.ts
+ * @descripcion Utilidades de conversión de nombres
+ * @autor Miguel Alejandro
+ * @fecha 2025-01-27
+ */
+/** Convierte nombre de clase a formato snake_case plural para tablas */
+export declare function toSnakePlural(input: string): string;

package/src/utils/naming.js

@@ -0,0 +1,18 @@
+"use strict";
+/**
+ * @file naming.ts
+ * @descripcion Utilidades de conversión de nombres
+ * @autor Miguel Alejandro
+ * @fecha 2025-01-27
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toSnakePlural = toSnakePlural;
+const pluralize_1 = __importDefault(require("pluralize"));
+/** Convierte nombre de clase a formato snake_case plural para tablas */
+function toSnakePlural(input) {
+    return (0, pluralize_1.default)(input.replace(/([a-z0-9])([A-Z])/g, "$1_$2").toLowerCase());
+}
+//# sourceMappingURL=naming.js.map

package/src/utils/projection.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @file projection.ts
+ * @description Selective field loading and projection optimization
+ * @autor Miguel Alejandro
+ * @fecha 2025-01-27
+ */
+/** Build DynamoDB ProjectionExpression */
+export declare const buildProjection: (attributes?: string[], meta?: any) => string | undefined;
+/** Optimize attributes loading for relations */
+export declare const optimizeRelationAttributes: (include: any, baseAttributes?: string[]) => string[];
+/** Smart attribute selection for common patterns */
+export declare const getSmartAttributes: (Model: any, scenario: "list" | "detail" | "minimal") => string[];

package/src/utils/projection.js

@@ -0,0 +1,51 @@
+"use strict";
+/**
+ * @file projection.ts
+ * @description Selective field loading and projection optimization
+ * @autor Miguel Alejandro
+ * @fecha 2025-01-27
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getSmartAttributes = exports.optimizeRelationAttributes = exports.buildProjection = void 0;
+const wrapper_1 = require("../core/wrapper");
+/** Build DynamoDB ProjectionExpression */
+const buildProjection = (attributes, meta) => {
+    if (!attributes?.length || !meta)
+        return undefined;
+    // Validate attributes exist in model
+    const validAttributes = attributes.filter((attr) => meta.columns.has(attr) || meta.relations.has(attr));
+    return validAttributes.length ? validAttributes.join(", ") : undefined;
+};
+exports.buildProjection = buildProjection;
+/** Optimize attributes loading for relations */
+const optimizeRelationAttributes = (include, baseAttributes) => {
+    const attributes = new Set(baseAttributes || []);
+    // Add foreign keys needed for relations
+    Object.entries(include || {}).forEach(([relationKey, options]) => {
+        attributes.add(relationKey);
+        // Add foreign key fields
+        if (options?.foreignKey)
+            attributes.add(options.foreignKey);
+        if (options?.localKey)
+            attributes.add(options.localKey);
+    });
+    return Array.from(attributes);
+};
+exports.optimizeRelationAttributes = optimizeRelationAttributes;
+/** Smart attribute selection for common patterns */
+const getSmartAttributes = (Model, scenario) => {
+    const meta = (0, wrapper_1.mustMeta)(Model);
+    const columns = Array.from(meta.columns.keys());
+    switch (scenario) {
+        case "minimal":
+            return columns.filter((col) => meta.columns.get(col)?.primaryKey ||
+                ["id", "name", "title", "email"].includes(col));
+        case "list":
+            return columns.filter((col) => !["description", "content", "body", "metadata"].includes(col));
+        case "detail":
+        default:
+            return columns;
+    }
+};
+exports.getSmartAttributes = getSmartAttributes;
+//# sourceMappingURL=projection.js.map

package/src/utils/relations.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @file relations.ts
+ * @descripcion Sistema de relaciones optimizado
+ * @autor Miguel Alejandro
+ * @fecha 2025-01-28
+ */
+/** Decorador @hasMany para relaciones 1:N */
+export declare const hasMany: (targetModel: () => any, foreignKey: string, localKey?: string) => (target: any, propertyKey: string) => void;
+/** Decorador @belongsTo para relaciones N:1 */
+export declare const belongsTo: (targetModel: () => any, localKey: string, foreignKey?: string) => (target: any, propertyKey: string) => void;
+/** Procesamiento optimizado de includes con batch loading transparente */
+export declare const processIncludes: (Model: any, items: any[], include: Record<string, any>, depth?: number) => Promise<any[]>;
+/** Separar opciones de query e include */
+export declare const separateQueryOptions: (options: Record<string, any>) => {
+    queryOptions: Record<string, any>;
+    includeOptions: Record<string, any> | undefined;
+};