@arcaelas/dynamite 1.0.15 → 1.0.17

package/src/decorators/index.js

@@ -0,0 +1,36 @@
+"use strict";
+/**
+ * @file index.ts
+ * @descripcion Decorador @Index para Partition Key
+ * @autor Miguel Alejandro
+ * @fecha 2025-01-27
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = Index;
+const wrapper_1 = require("../core/wrapper");
+const naming_1 = require("../utils/naming");
+/**
+ * Decorador para marcar propiedad como Partition Key.
+ * Configura la propiedad como índice principal para consultas.
+ */
+function Index() {
+    return (target, prop) => {
+        const ctor = target.constructor;
+        const tableName = (0, naming_1.toSnakePlural)(ctor.name);
+        const entry = (0, wrapper_1.ensureConfig)(ctor, tableName);
+        // Verificar si ya existe un índice primario
+        const existingIndex = [...entry.columns.values()].find((col) => col.index === true);
+        if (existingIndex && existingIndex.name !== String(prop)) {
+            throw new Error(`La tabla ${tableName} ya tiene definida una PartitionKey (${existingIndex.name}). ` +
+                `No se puede definir otra PartitionKey en '${String(prop)}'`);
+        }
+        // Obtener o crear la columna y marcar como índice
+        const column = (0, wrapper_1.ensureColumn)(entry, prop, String(prop));
+        column.index = true;
+        // Asegurar que la columna no sea nula por defecto
+        if (column.nullable === undefined) {
+            column.nullable = false;
+        }
+    };
+}
+//# sourceMappingURL=index.js.map

package/src/decorators/index_sort.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @file index_sort.ts
+ * @descripcion Decorador @IndexSort para Sort Key
+ * @autor Miguel Alejandro
+ * @fecha 2025-01-27
+ */
+/**
+ * Decorador para marcar propiedad como Sort Key.
+ * Configura la propiedad como clave de ordenación para consultas.
+ * Requiere que exista una PartitionKey (@Index) definida previamente.
+ */
+export default function IndexSort(): PropertyDecorator;

package/src/decorators/index_sort.js

@@ -0,0 +1,43 @@
+"use strict";
+/**
+ * @file index_sort.ts
+ * @descripcion Decorador @IndexSort para Sort Key
+ * @autor Miguel Alejandro
+ * @fecha 2025-01-27
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = IndexSort;
+const wrapper_1 = require("../core/wrapper");
+const naming_1 = require("../utils/naming");
+/**
+ * Decorador para marcar propiedad como Sort Key.
+ * Configura la propiedad como clave de ordenación para consultas.
+ * Requiere que exista una PartitionKey (@Index) definida previamente.
+ */
+function IndexSort() {
+    return (target, prop) => {
+        const ctor = target.constructor;
+        const tableName = (0, naming_1.toSnakePlural)(ctor.name);
+        const entry = (0, wrapper_1.ensureConfig)(ctor, tableName);
+        // Verificar que exista una PartitionKey definida
+        const hasPartitionKey = [...entry.columns.values()].some((col) => col.index === true);
+        if (!hasPartitionKey) {
+            throw new Error(`No se puede definir una SortKey en '${String(prop)}' sin una PartitionKey. ` +
+                `Asegúrate de marcar una propiedad con @Index primero.`);
+        }
+        // Verificar si ya existe una SortKey
+        const existingSortKey = [...entry.columns.values()].find((col) => col.indexSort === true);
+        if (existingSortKey && existingSortKey.name !== String(prop)) {
+            throw new Error(`La tabla ${tableName} ya tiene una SortKey definida (${existingSortKey.name}). ` +
+                `No se puede definir otra SortKey en '${String(prop)}'`);
+        }
+        // Obtener o crear la columna y marcar como índice de ordenación
+        const column = (0, wrapper_1.ensureColumn)(entry, prop, String(prop));
+        column.indexSort = true;
+        // Asegurar que la columna no sea nula por defecto
+        if (column.nullable === undefined) {
+            column.nullable = false;
+        }
+    };
+}
+//# sourceMappingURL=index_sort.js.map

package/src/decorators/mutate.d.ts

@@ -0,0 +1,2 @@
+import type { Mutate } from "../core/wrapper";
+export default function Mutate(fn: Mutate): PropertyDecorator;

package/src/decorators/mutate.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = Mutate;
+const wrapper_1 = require("../core/wrapper");
+const naming_1 = require("../utils/naming");
+function Mutate(fn) {
+    if (typeof fn !== "function")
+        throw new TypeError("@Mutate requiere función");
+    return (target, prop) => {
+        const ctor = target.constructor;
+        const entry = (0, wrapper_1.ensureConfig)(ctor, (0, naming_1.toSnakePlural)(ctor.name));
+        const col = (0, wrapper_1.ensureColumn)(entry, prop, String(prop));
+        col.mutate ??= [];
+        col.mutate.push(fn);
+        !Object.getOwnPropertyDescriptor(ctor.prototype, prop)?.set &&
+            defineVirtual(ctor.prototype, col, prop);
+    };
+}
+/** Define propiedad virtual con getter/setter para manejo de mutaciones */
+function defineVirtual(proto, col, prop) {
+    Object.defineProperty(proto, prop, {
+        get() {
+            return (this[wrapper_1.STORE] ?? {})[prop];
+        },
+        set(val) {
+            const buf = (this[wrapper_1.STORE] ??= {});
+            val =
+                val === undefined && col.default !== undefined
+                    ? typeof col.default === "function"
+                        ? col.default()
+                        : col.default
+                    : val;
+            if (col.mutate)
+                for (const m of col.mutate)
+                    val = m(val);
+            if (col.validate) {
+                for (const v of col.validate) {
+                    const r = v(val);
+                    r !== true &&
+                        (() => {
+                            throw new Error(typeof r === "string" ? r : "Validación fallida");
+                        })();
+                }
+            }
+            buf[prop] = val;
+        },
+        enumerable: true,
+        configurable: true,
+    });
+}
+//# sourceMappingURL=mutate.js.map

package/src/decorators/name.d.ts

@@ -0,0 +1 @@
+export default function Name(label: string): ClassDecorator & PropertyDecorator;

package/src/decorators/name.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = Name;
+const wrapper_1 = require("../core/wrapper");
+const naming_1 = require("../utils/naming");
+function Name(label) {
+    if (!label || typeof label !== "string")
+        throw new TypeError("@Name requiere una cadena no vacía");
+    return (target, prop) => {
+        const ctor = prop === undefined ? target : target.constructor;
+        const entry = (0, wrapper_1.ensureConfig)(ctor, (0, naming_1.toSnakePlural)(ctor.name));
+        if (prop === undefined) {
+            const auto = (0, naming_1.toSnakePlural)(ctor.name);
+            if (entry.name !== auto && entry.name !== label && entry.name) {
+                throw new Error(`La clase ${ctor.name} ya tiene un @Name distinto (${entry.name})`);
+            }
+            entry.name = label;
+        }
+        else {
+            const col = (0, wrapper_1.ensureColumn)(entry, prop, label);
+            if (col.name && col.name !== label) {
+                throw new Error(`La columna '${String(prop)}' ya tiene @Name distinto (${col.name})`);
+            }
+            col.name = label;
+        }
+    };
+}
+//# sourceMappingURL=name.js.map

package/src/decorators/not_null.d.ts

@@ -0,0 +1 @@
+export default function NotNull(): PropertyDecorator;

package/src/decorators/not_null.js

@@ -0,0 +1,13 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = NotNull;
+const validate_1 = __importDefault(require("./validate"));
+function NotNull() {
+    return validate_1.default((value) => value !== null &&
+        value !== undefined &&
+        (typeof value !== "string" || value.trim() !== ""));
+}
+//# sourceMappingURL=not_null.js.map

package/src/decorators/primary_key.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Decorador para marcar una propiedad como clave primaria.
+ * Aplica automáticamente @Index y @IndexSort y marca el campo como primaryKey en los metadatos.
+ * @param name - Nombre opcional para el índice (no utilizado actualmente, mantenido por compatibilidad)
+ */
+export default function PrimaryKey(name?: string): PropertyDecorator;

package/src/decorators/primary_key.js

@@ -0,0 +1,30 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = PrimaryKey;
+const wrapper_1 = require("../core/wrapper");
+const naming_1 = require("../utils/naming");
+const index_1 = __importDefault(require("./index"));
+const index_sort_1 = __importDefault(require("./index_sort"));
+/**
+ * Decorador para marcar una propiedad como clave primaria.
+ * Aplica automáticamente @Index y @IndexSort y marca el campo como primaryKey en los metadatos.
+ * @param name - Nombre opcional para el índice (no utilizado actualmente, mantenido por compatibilidad)
+ */
+function PrimaryKey(name = "primary") {
+    return (target, prop) => {
+        // Aplicar decoradores de índice
+        (0, index_1.default)()(target, prop);
+        (0, index_sort_1.default)()(target, prop);
+        // Marcar explícitamente como clave primaria en los metadatos
+        const ctor = target.constructor;
+        const entry = (0, wrapper_1.ensureConfig)(ctor, (0, naming_1.toSnakePlural)(ctor.name));
+        const column = (0, wrapper_1.ensureColumn)(entry, prop, String(prop));
+        // Establecer metadatos adicionales para clave primaria
+        column.primaryKey = true;
+        column.nullable = false; // Las claves primarias no pueden ser nulas
+    };
+}
+//# sourceMappingURL=primary_key.js.map

package/src/decorators/updated_at.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Decorador que marca una propiedad para que se actualice automáticamente con la fecha/hora actual
+ * cada vez que se guarde el modelo.
+ *
+ * @example
+ * class User extends Table<User> {
+ *   @PrimaryKey() id: string;
+ *   name: string;
+ *   @UpdatedAt() updated_at: string;
+ * }
+ */
+export default function UpdatedAt(): (target: any, propertyKey: string | symbol) => void;

package/src/decorators/updated_at.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = UpdatedAt;
+const wrapper_1 = require("../core/wrapper");
+/**
+ * Decorador que marca una propiedad para que se actualice automáticamente con la fecha/hora actual
+ * cada vez que se guarde el modelo.
+ *
+ * @example
+ * class User extends Table<User> {
+ *   @PrimaryKey() id: string;
+ *   name: string;
+ *   @UpdatedAt() updated_at: string;
+ * }
+ */
+function UpdatedAt() {
+    return function (target, propertyKey) {
+        const ctor = target.constructor;
+        const entry = (0, wrapper_1.ensureConfig)(ctor, ctor.name);
+        const column = (0, wrapper_1.ensureColumn)(entry, propertyKey, propertyKey);
+        // Marcamos la columna como updatedAt para que se actualice automáticamente al guardar
+        column.updatedAt = true;
+        // No establecemos un valor por defecto aquí, se establecerá en el método save()
+    };
+}
+//# sourceMappingURL=updated_at.js.map

package/src/decorators/validate.d.ts

@@ -0,0 +1 @@
+export default function Validate(validators: ((v: unknown) => true | string) | ((v: unknown) => true | string)[]): PropertyDecorator;

package/src/decorators/validate.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = Validate;
+const wrapper_1 = require("../core/wrapper");
+const naming_1 = require("../utils/naming");
+function Validate(validators) {
+    const list = Array.isArray(validators) ? validators : [validators];
+    if (!list.length || list.some((v) => typeof v !== "function")) {
+        throw new TypeError("@Validate requiere funciones");
+    }
+    return (target, prop) => {
+        const ctor = target.constructor;
+        const entry = (0, wrapper_1.ensureConfig)(ctor, (0, naming_1.toSnakePlural)(ctor.name));
+        const col = (0, wrapper_1.ensureColumn)(entry, prop, String(prop));
+        col.validate ??= [];
+        col.validate.push(...list);
+        !Object.getOwnPropertyDescriptor(ctor.prototype, prop)?.set &&
+            defineVirtual(ctor.prototype, col, prop);
+    };
+}
+/** Define propiedad virtual con getter/setter para manejo de validaciones */
+function defineVirtual(proto, col, prop) {
+    Object.defineProperty(proto, prop, {
+        get() {
+            return (this[wrapper_1.STORE] ?? {})[prop];
+        },
+        set(val) {
+            const buf = (this[wrapper_1.STORE] ??= {});
+            val =
+                val === undefined && col.default !== undefined
+                    ? typeof col.default === "function"
+                        ? col.default()
+                        : col.default
+                    : val;
+            if (col.mutate)
+                for (const m of col.mutate)
+                    val = m(val);
+            if (col.validate) {
+                for (const v of col.validate) {
+                    const r = v(val);
+                    r !== true &&
+                        (() => {
+                            throw new Error(typeof r === "string" ? r : "Validación fallida");
+                        })();
+                }
+            }
+            buf[prop] = val;
+        },
+        enumerable: true,
+        configurable: true,
+    });
+}
+//# sourceMappingURL=validate.js.map

package/src/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @file index.ts
+ * @descripcion Punto de entrada público de la librería
+ * @autor Miguel Alejandro
+ * @fecha 2025-08-07
+ */
+export { Dynamite } from "./core/client";
+export { default as Table } from "./core/table";
+export { default as BelongsTo } from "./decorators/belongs_to";
+export { default as CreatedAt } from "./decorators/created_at";
+export { default as Default } from "./decorators/default";
+export { default as HasMany } from "./decorators/has_many";
+export { default as Index } from "./decorators/index";
+export { default as IndexSort } from "./decorators/index_sort";
+export { default as Mutate } from "./decorators/mutate";
+export { default as Name } from "./decorators/name";
+export { default as NotNull } from "./decorators/not_null";
+export { default as PrimaryKey } from "./decorators/primary_key";
+export { default as UpdatedAt } from "./decorators/updated_at";
+export { default as Validate } from "./decorators/validate";
+export { belongsTo, hasMany } from "./utils/relations";
+export type { BelongsTo as BelongsToType, CreationOptional, FilterableAttributes, HasMany as HasManyType, InferAttributes, NonAttribute, QueryOperator, QueryResult, WhereOptions, WhereOptionsWithoutWhere, } from "./@types/index";

package/src/index.js

@@ -0,0 +1,47 @@
+"use strict";
+/**
+ * @file index.ts
+ * @descripcion Punto de entrada público de la librería
+ * @autor Miguel Alejandro
+ * @fecha 2025-08-07
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hasMany = exports.belongsTo = exports.Validate = exports.UpdatedAt = exports.PrimaryKey = exports.NotNull = exports.Name = exports.Mutate = exports.IndexSort = exports.Index = exports.HasMany = exports.Default = exports.CreatedAt = exports.BelongsTo = exports.Table = exports.Dynamite = void 0;
+// Clases núcleo
+var client_1 = require("./core/client");
+Object.defineProperty(exports, "Dynamite", { enumerable: true, get: function () { return client_1.Dynamite; } });
+var table_1 = require("./core/table");
+Object.defineProperty(exports, "Table", { enumerable: true, get: function () { return __importDefault(table_1).default; } });
+// Decoradores
+var belongs_to_1 = require("./decorators/belongs_to");
+Object.defineProperty(exports, "BelongsTo", { enumerable: true, get: function () { return __importDefault(belongs_to_1).default; } });
+var created_at_1 = require("./decorators/created_at");
+Object.defineProperty(exports, "CreatedAt", { enumerable: true, get: function () { return __importDefault(created_at_1).default; } });
+var default_1 = require("./decorators/default");
+Object.defineProperty(exports, "Default", { enumerable: true, get: function () { return __importDefault(default_1).default; } });
+var has_many_1 = require("./decorators/has_many");
+Object.defineProperty(exports, "HasMany", { enumerable: true, get: function () { return __importDefault(has_many_1).default; } });
+var index_1 = require("./decorators/index");
+Object.defineProperty(exports, "Index", { enumerable: true, get: function () { return __importDefault(index_1).default; } });
+var index_sort_1 = require("./decorators/index_sort");
+Object.defineProperty(exports, "IndexSort", { enumerable: true, get: function () { return __importDefault(index_sort_1).default; } });
+var mutate_1 = require("./decorators/mutate");
+Object.defineProperty(exports, "Mutate", { enumerable: true, get: function () { return __importDefault(mutate_1).default; } });
+var name_1 = require("./decorators/name");
+Object.defineProperty(exports, "Name", { enumerable: true, get: function () { return __importDefault(name_1).default; } });
+var not_null_1 = require("./decorators/not_null");
+Object.defineProperty(exports, "NotNull", { enumerable: true, get: function () { return __importDefault(not_null_1).default; } });
+var primary_key_1 = require("./decorators/primary_key");
+Object.defineProperty(exports, "PrimaryKey", { enumerable: true, get: function () { return __importDefault(primary_key_1).default; } });
+var updated_at_1 = require("./decorators/updated_at");
+Object.defineProperty(exports, "UpdatedAt", { enumerable: true, get: function () { return __importDefault(updated_at_1).default; } });
+var validate_1 = require("./decorators/validate");
+Object.defineProperty(exports, "Validate", { enumerable: true, get: function () { return __importDefault(validate_1).default; } });
+// Relaciones
+var relations_1 = require("./utils/relations");
+Object.defineProperty(exports, "belongsTo", { enumerable: true, get: function () { return relations_1.belongsTo; } });
+Object.defineProperty(exports, "hasMany", { enumerable: true, get: function () { return relations_1.hasMany; } });
+//# sourceMappingURL=index.js.map

package/src/utils/batch-relations.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @file batch-relations.ts
+ * @description Optimized batch loading for relations
+ * @autor Miguel Alejandro
+ * @fecha 2025-01-27
+ */
+/** Batch loader para hasMany relations */
+export declare const batchLoadHasMany: (Model: any, parentItems: any[], relation: any) => Promise<Map<any, any>>;
+/** Batch loader para belongsTo relations con cache */
+export declare const batchLoadBelongsTo: (Model: any, parentItems: any[], relation: any) => Promise<Map<any, any>>;
+/** Optimized processIncludes con batch loading */
+export declare const processIncludesBatch: (Model: any, items: any[], include: any, depth?: number) => Promise<any[]>;
+/** Clear expired cache entries */
+export declare const cleanupRelationCache: () => void;

package/src/utils/batch-relations.js

@@ -0,0 +1,131 @@
+"use strict";
+/**
+ * @file batch-relations.ts
+ * @description Optimized batch loading for relations
+ * @autor Miguel Alejandro
+ * @fecha 2025-01-27
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cleanupRelationCache = exports.processIncludesBatch = exports.batchLoadBelongsTo = exports.batchLoadHasMany = void 0;
+const wrapper_1 = require("../core/wrapper");
+/** Cache multi-nivel con TTL */
+const relCache = new Map();
+/** Batch loader para hasMany relations */
+const batchLoadHasMany = async (Model, parentItems, relation) => {
+    const { targetModel, foreignKey, localKey } = relation;
+    const TargetModel = targetModel();
+    // Agrupar claves para batch query
+    const parentKeys = parentItems.map((item) => item[localKey]).filter(Boolean);
+    if (!parentKeys.length)
+        return new Map();
+    // Single query con 'in' operator
+    const relatedItems = await TargetModel.where({
+        [foreignKey]: { in: parentKeys },
+    });
+    // Group by foreign key
+    const grouped = new Map();
+    relatedItems.forEach((item) => {
+        const key = item[foreignKey];
+        if (!grouped.has(key))
+            grouped.set(key, []);
+        grouped.get(key).push(item);
+    });
+    return grouped;
+};
+exports.batchLoadHasMany = batchLoadHasMany;
+/** Batch loader para belongsTo relations con cache */
+const batchLoadBelongsTo = async (Model, parentItems, relation) => {
+    const { targetModel, localKey, foreignKey } = relation;
+    const TargetModel = targetModel();
+    const cacheKey = `${TargetModel.name}_belongsTo`;
+    // Verificar cache existente
+    const cache = relCache.get(cacheKey) || new Map();
+    relCache.set(cacheKey, cache);
+    const now = Date.now();
+    // Separar keys en cache vs no-cache
+    const keysToFetch = [];
+    const cachedResults = new Map();
+    parentItems.forEach((item) => {
+        const key = item[localKey];
+        if (!key)
+            return;
+        const cached = cache.get(key);
+        if (cached && cached.expires > now) {
+            cachedResults.set(key, cached.data);
+        }
+        else {
+            keysToFetch.push(key);
+        }
+    });
+    // Fetch missing items
+    if (keysToFetch.length) {
+        const fetchedItems = await TargetModel.where({
+            [foreignKey]: { in: keysToFetch },
+        });
+        // Update cache (5min TTL)
+        const expires = now + 300000;
+        fetchedItems.forEach((item) => {
+            const key = item[foreignKey];
+            cache.set(key, { data: item, expires });
+            cachedResults.set(key, item);
+        });
+    }
+    return cachedResults;
+};
+exports.batchLoadBelongsTo = batchLoadBelongsTo;
+/** Optimized processIncludes con batch loading */
+const processIncludesBatch = async (Model, items, include, depth = 0) => {
+    if (!include || depth > 10 || !items.length)
+        return items;
+    const meta = (0, wrapper_1.mustMeta)(Model);
+    // Process all relations in parallel
+    const relationPromises = Object.entries(include).map(async ([relationKey, relationOptions]) => {
+        const relation = meta.relations.get(relationKey);
+        if (!relation)
+            return;
+        let relatedData;
+        // Use batch loading based on relation type
+        if (relation.type === "hasMany") {
+            relatedData = await (0, exports.batchLoadHasMany)(Model, items, relation);
+        }
+        else {
+            relatedData = await (0, exports.batchLoadBelongsTo)(Model, items, relation);
+        }
+        // Assign relations to items
+        items.forEach((item) => {
+            const key = item[relation.localKey];
+            const related = relatedData.get(key);
+            if (relation.type === "hasMany") {
+                item[relationKey] = related || [];
+            }
+            else {
+                item[relationKey] = related || null;
+            }
+        });
+        // Recursive processing for nested includes
+        if (relationOptions?.include && relatedData.size) {
+            const allRelated = Array.from(relatedData.values()).flat();
+            const TargetModel = relation.targetModel();
+            await (0, exports.processIncludesBatch)(TargetModel, allRelated, relationOptions.include, depth + 1);
+        }
+    });
+    await Promise.all(relationPromises);
+    return items;
+};
+exports.processIncludesBatch = processIncludesBatch;
+/** Clear expired cache entries */
+const cleanupRelationCache = () => {
+    const now = Date.now();
+    relCache.forEach((cache, modelKey) => {
+        cache.forEach((entry, key) => {
+            if (entry.expires <= now)
+                cache.delete(key);
+        });
+        if (cache.size === 0)
+            relCache.delete(modelKey);
+    });
+};
+exports.cleanupRelationCache = cleanupRelationCache;
+// Auto cleanup every 5 minutes
+setInterval(exports.cleanupRelationCache, 300000);
+//# sourceMappingURL=batch-relations.js.map

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, CircularReferenceError, CircularTracker, ValidationResult, circularDetector, };
+export default circularDetector;