kythia-core 0.11.0-beta → 0.12.0-beta

package/dist/database/KythiaModel.js

@@ -0,0 +1,1121 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KythiaModel = void 0;
+const jsonStringify = require("json-stable-stringify");
+const sequelize_1 = require("sequelize");
+const lru_cache_1 = require("lru-cache");
+const logger_1 = __importDefault(require("../utils/logger"));
+const NEGATIVE_CACHE_PLACEHOLDER = '__KYTHIA_NEGATIVE_CACHE__';
+const RECONNECT_DELAY_MINUTES = 3;
+const REDIS_ERROR_TOLERANCE_COUNT = 3;
+const REDIS_ERROR_TOLERANCE_INTERVAL_MS = 10 * 1000;
+function safeStringify(obj, logger) {
+    try {
+        return JSON.stringify(obj, (_key, value) => typeof value === 'bigint' ? value.toString() : value);
+    }
+    catch (err) {
+        (logger || console).error(`❌ [SAFE STRINGIFY] Failed: ${err.message}`);
+        return '{}';
+    }
+}
+function safeParse(str, logger) {
+    try {
+        return JSON.parse(str);
+    }
+    catch {
+        (logger || console).warn('⚠️ [SAFE PARSE] Invalid JSON data, returning null');
+        return null;
+    }
+}
+class KythiaModel extends sequelize_1.Model {
+    static client;
+    static redis;
+    static isRedisConnected = false;
+    static logger = logger_1.default;
+    static config = {};
+    static CACHE_VERSION = '1.0.0';
+    static localCache = new lru_cache_1.LRUCache({
+        max: 1000,
+    });
+    static localNegativeCache = new Set();
+    static MAX_LOCAL_CACHE_SIZE = 1000;
+    static DEFAULT_TTL = 60 * 60 * 1000;
+    static lastRedisOpts = null;
+    static reconnectTimeout = null;
+    static lastAutoReconnectTs = 0;
+    static pendingQueries = new Map();
+    static cacheStats = {
+        redisHits: 0,
+        mapHits: 0,
+        misses: 0,
+        sets: 0,
+        clears: 0,
+        errors: 0,
+    };
+    static redisErrorTimestamps = [];
+    static isShardMode = false;
+    static _redisFallbackURLs = [];
+    static _redisCurrentIndex = 0;
+    static _redisFailedIndexes = new Set();
+    static _justFailedOver = false;
+    static fillable;
+    static guarded;
+    static structure;
+    static table;
+    static cacheKeys;
+    static CACHE_KEYS;
+    static CACHE_TTL;
+    static customInvalidationTags;
+    static init(attributes, options) {
+        const model = super.init(attributes, options);
+        model.addHook('beforeValidate', (instance) => {
+            const ModelClass = instance.constructor;
+            if (ModelClass.fillable && Array.isArray(ModelClass.fillable)) {
+                const allowedFields = ModelClass.fillable;
+                Object.keys(instance.dataValues).forEach((key) => {
+                    if (!allowedFields.includes(key)) {
+                        delete instance.dataValues[key];
+                        if (instance.changed())
+                            instance.changed(key, false);
+                    }
+                });
+            }
+            else if (ModelClass.guarded && Array.isArray(ModelClass.guarded)) {
+                const forbiddenFields = ModelClass.guarded;
+                if (forbiddenFields.includes('*')) {
+                    instance.dataValues = {};
+                    return;
+                }
+                Object.keys(instance.dataValues).forEach((key) => {
+                    if (forbiddenFields.includes(key)) {
+                        delete instance.dataValues[key];
+                        if (instance.changed())
+                            instance.changed(key, false);
+                    }
+                });
+            }
+        });
+        return model;
+    }
+    static async autoBoot(sequelize) {
+        let tableName = this.table;
+        if (!tableName) {
+            const modelName = this.name;
+            const snakeCase = sequelize_1.Utils.underscoredIf(modelName, true);
+            tableName = sequelize_1.Utils.pluralize(snakeCase);
+        }
+        let manualAttributes = {};
+        let manualOptions = {};
+        if (this.structure) {
+            manualAttributes = this.structure.attributes || {};
+            manualOptions = this.structure.options || {};
+        }
+        const queryInterface = sequelize.getQueryInterface();
+        let tableSchema;
+        try {
+            tableSchema = await queryInterface.describeTable(tableName);
+        }
+        catch (error) {
+            console.warn(`⚠️ [KythiaModel] Table '${tableName}' not found for model '${this.name}'. Skipping auto-boot. err ${error}`);
+            return;
+        }
+        const dbAttributes = {};
+        for (const [colName, colInfo] of Object.entries(tableSchema)) {
+            dbAttributes[colName] = {
+                type: this._mapDbTypeToSequelize(colInfo.type),
+                allowNull: colInfo.allowNull,
+                defaultValue: colInfo.defaultValue,
+                primaryKey: colInfo.primaryKey,
+                autoIncrement: colInfo.autoIncrement,
+            };
+        }
+        const finalAttributes = { ...dbAttributes, ...manualAttributes };
+        super.init(finalAttributes, {
+            sequelize,
+            modelName: this.name,
+            tableName: tableName,
+            timestamps: manualOptions.timestamps !== undefined
+                ? manualOptions.timestamps
+                : !!finalAttributes.createdAt,
+            paranoid: manualOptions.paranoid !== undefined
+                ? manualOptions.paranoid
+                : !!finalAttributes.deletedAt,
+            ...manualOptions,
+        });
+        this._setupLaravelHooks();
+        return this;
+    }
+    static _mapDbTypeToSequelize(dbType) {
+        const type = dbType.toUpperCase();
+        if (type.startsWith('BOOLEAN') || type.startsWith('TINYINT(1)'))
+            return sequelize_1.DataTypes.BOOLEAN;
+        if (type.startsWith('INT') ||
+            type.startsWith('TINYINT') ||
+            type.startsWith('BIGINT'))
+            return sequelize_1.DataTypes.INTEGER;
+        if (type.startsWith('VARCHAR') ||
+            type.startsWith('TEXT') ||
+            type.startsWith('CHAR'))
+            return sequelize_1.DataTypes.STRING;
+        if (type.startsWith('DATETIME') || type.startsWith('TIMESTAMP'))
+            return sequelize_1.DataTypes.DATE;
+        if (type.startsWith('JSON'))
+            return sequelize_1.DataTypes.JSON;
+        if (type.startsWith('FLOAT') ||
+            type.startsWith('DOUBLE') ||
+            type.startsWith('DECIMAL'))
+            return sequelize_1.DataTypes.FLOAT;
+        if (type.startsWith('ENUM'))
+            return sequelize_1.DataTypes.STRING;
+        return sequelize_1.DataTypes.STRING;
+    }
+    static _setupLaravelHooks() {
+        this.addHook('beforeValidate', (instance) => {
+            const ModelClass = instance.constructor;
+            const pkAttribute = ModelClass.primaryKeyAttribute || 'id';
+            if (ModelClass.fillable && Array.isArray(ModelClass.fillable)) {
+                const allowedFields = ModelClass.fillable;
+                Object.keys(instance.dataValues).forEach((key) => {
+                    if (key === pkAttribute)
+                        return;
+                    if (!allowedFields.includes(key)) {
+                        delete instance.dataValues[key];
+                        if (instance.changed())
+                            instance.changed(key, false);
+                    }
+                });
+            }
+            else if (ModelClass.guarded && Array.isArray(ModelClass.guarded)) {
+                const forbiddenFields = ModelClass.guarded;
+                if (forbiddenFields.includes('*')) {
+                    instance.dataValues = {};
+                    return;
+                }
+                Object.keys(instance.dataValues).forEach((key) => {
+                    if (key === pkAttribute)
+                        return;
+                    if (forbiddenFields.includes(key)) {
+                        delete instance.dataValues[key];
+                        if (instance.changed())
+                            instance.changed(key, false);
+                    }
+                });
+            }
+        });
+    }
+    static setDependencies({ logger, config, redis, redisOptions, }) {
+        if (!config) {
+            throw new Error('KythiaModel.setDependencies requires config!');
+        }
+        this.logger = logger || logger_1.default;
+        this.config = config;
+        this.CACHE_VERSION = config.db?.redisCacheVersion || '1.0.0';
+        const redisConfig = config?.db?.redis;
+        this.isShardMode =
+            (typeof redisConfig === 'object' &&
+                redisConfig !== null &&
+                redisConfig.shard) ||
+                false;
+        if (this.isShardMode) {
+            this.logger.info('🟣 [REDIS][SHARD] Detected redis sharding mode (shard: true). Local fallback cache DISABLED!');
+        }
+        this._redisFallbackURLs = [];
+        if (Array.isArray(redisOptions)) {
+            this._redisFallbackURLs = redisOptions.filter((opt) => opt && (typeof opt !== 'string' || opt.trim().length > 0));
+        }
+        else if (typeof redisOptions === 'string') {
+            if (redisOptions.trim().length > 0) {
+                this._redisFallbackURLs = redisOptions
+                    .split(',')
+                    .map((url) => url.trim())
+                    .filter((url) => url.length > 0);
+            }
+        }
+        else if (redisOptions &&
+            typeof redisOptions === 'object' &&
+            Array.isArray(redisOptions.urls)) {
+            this._redisFallbackURLs = redisOptions.urls.slice();
+        }
+        else if (redisOptions &&
+            typeof redisOptions === 'object' &&
+            Object.keys(redisOptions).length > 0) {
+            this._redisFallbackURLs = [redisOptions];
+        }
+        this._redisCurrentIndex = 0;
+        if (redis) {
+            this.redis = redis;
+            this.isRedisConnected = redis.status === 'ready';
+        }
+        else if (this._redisFallbackURLs.length > 0) {
+            this.initializeRedis();
+        }
+        else {
+            if (this.isShardMode) {
+                this.logger.error('❌ [REDIS][SHARD] No Redis client/options, but shard:true. Application will work WITHOUT caching!');
+                this.isRedisConnected = false;
+            }
+            else {
+                this.logger.warn('🟠 [REDIS] No Redis provided. Switching to In-Memory Cache mode.');
+                this.isRedisConnected = false;
+            }
+        }
+    }
+    static _trackRedisError(err) {
+        const now = Date.now();
+        this.redisErrorTimestamps = (this.redisErrorTimestamps || []).filter((ts) => now - ts < REDIS_ERROR_TOLERANCE_INTERVAL_MS);
+        this.redisErrorTimestamps.push(now);
+        if (this.redisErrorTimestamps.length >= REDIS_ERROR_TOLERANCE_COUNT) {
+            if (this.isRedisConnected) {
+                const triedFallback = this._tryRedisFailover();
+                if (triedFallback) {
+                    this.logger.warn(`[REDIS] Error tolerance reached, switching to NEXT Redis failover...`);
+                }
+                else if (this.isShardMode) {
+                    this.logger.error(`❌ [REDIS][SHARD] ${this.redisErrorTimestamps.length} consecutive errors in ${REDIS_ERROR_TOLERANCE_INTERVAL_MS / 1000}s. SHARD MODE: Disabling cache (NO fallback), all queries go to DB. (Last error: ${err?.message})`);
+                    this.isRedisConnected = false;
+                    this._scheduleReconnect();
+                }
+                else {
+                    this.logger.error(`❌ [REDIS] ${this.redisErrorTimestamps.length} consecutive errors in ${REDIS_ERROR_TOLERANCE_INTERVAL_MS / 1000}s. All Redis exhausted, fallback to In-Memory Cache! (Last error: ${err?.message})`);
+                    this.isRedisConnected = false;
+                    this._scheduleReconnect();
+                }
+            }
+            this.redisErrorTimestamps = [];
+        }
+        else {
+            this.logger.warn(`🟠 [REDIS] Error #${this.redisErrorTimestamps.length}/${REDIS_ERROR_TOLERANCE_COUNT} tolerated. (${err?.message})`);
+        }
+    }
+    static _tryRedisFailover() {
+        if (!Array.isArray(this._redisFallbackURLs) ||
+            this._redisFallbackURLs.length < 2) {
+            return false;
+        }
+        const prevIndex = this._redisCurrentIndex;
+        if (this._redisCurrentIndex + 1 < this._redisFallbackURLs.length) {
+            this._redisCurrentIndex++;
+            this.logger.warn(`[REDIS][FAILOVER] Trying to switch Redis connection from url index ${prevIndex} to ${this._redisCurrentIndex}`);
+            this._justFailedOver = true;
+            this._closeCurrentRedis();
+            this.initializeRedis();
+            return true;
+        }
+        return false;
+    }
+    static _closeCurrentRedis() {
+        if (this.redis && typeof this.redis.quit === 'function') {
+            try {
+                this.redis.quit();
+            }
+            catch (e) {
+                console.log(e);
+            }
+        }
+        this.redis = undefined;
+        this.isRedisConnected = false;
+    }
+    static initializeRedis(redisOptions) {
+        if (redisOptions) {
+            if (Array.isArray(redisOptions)) {
+                this._redisFallbackURLs = redisOptions.slice();
+                this._redisCurrentIndex = 0;
+            }
+            else if (redisOptions &&
+                typeof redisOptions === 'object' &&
+                Array.isArray(redisOptions.urls)) {
+                this._redisFallbackURLs = redisOptions.urls.slice();
+                this._redisCurrentIndex = 0;
+            }
+            else {
+                this._redisFallbackURLs = [redisOptions];
+                this._redisCurrentIndex = 0;
+            }
+        }
+        if (!Array.isArray(this._redisFallbackURLs) ||
+            this._redisFallbackURLs.length === 0) {
+            if (this.isShardMode) {
+                this.logger.error('❌ [REDIS][SHARD] No Redis URL/options provided but shard:true. Will run without caching!');
+                this.isRedisConnected = false;
+            }
+            else {
+                this.logger.warn('🟠 [REDIS] No Redis client or options provided. Operating in In-Memory Cache mode only.');
+                this.isRedisConnected = false;
+            }
+            return null;
+        }
+        const Redis = require('ioredis');
+        this.lastRedisOpts = Array.isArray(this._redisFallbackURLs)
+            ? this._redisFallbackURLs.slice()
+            : [this._redisFallbackURLs];
+        if (this.redis)
+            return this.redis;
+        const opt = this._redisFallbackURLs[this._redisCurrentIndex];
+        if (opt && typeof opt === 'object' && opt.shard) {
+            this.isShardMode = true;
+        }
+        let redisOpt;
+        if (typeof opt === 'string') {
+            redisOpt = { url: opt, retryStrategy: this._makeRetryStrategy() };
+        }
+        else if (opt && typeof opt === 'object') {
+            redisOpt = {
+                maxRetriesPerRequest: 2,
+                enableReadyCheck: true,
+                retryStrategy: this._makeRetryStrategy(),
+                ...opt,
+            };
+        }
+        else {
+            this.logger.error('❌ [REDIS] Invalid redis config detected in list');
+            this.isRedisConnected = false;
+            return null;
+        }
+        this.logger.info(`[REDIS][INIT] Connecting to Redis fallback #${this._redisCurrentIndex + 1}/${this._redisFallbackURLs.length}: ${typeof opt === 'string' ? opt : redisOpt.url || '(object)'}`);
+        this.redis = new Redis(redisOpt.url || redisOpt);
+        this._setupRedisEventHandlers();
+        return this.redis;
+    }
+    static _makeRetryStrategy() {
+        return (times) => {
+            if (times > 5) {
+                this.logger.error(`❌ [REDIS] Could not connect after ${times - 1} retries for Redis #${this._redisCurrentIndex + 1}.`);
+                return null;
+            }
+            const delay = Math.min(times * 500, 2000);
+            this.logger.warn(`🟠 [REDIS] Connection failed for Redis #${this._redisCurrentIndex + 1}. Retrying in ${delay}ms (Attempt ${times})...`);
+            return delay;
+        };
+    }
+    static _setupRedisEventHandlers() {
+        if (!this.redis)
+            return;
+        this.redis.on('connect', async () => {
+            if (!this.isRedisConnected) {
+                this.logger.info('✅ [REDIS] Connection established. Switching to Redis Cache mode.');
+            }
+            this.isRedisConnected = true;
+            this.redisErrorTimestamps = [];
+            if (this.reconnectTimeout) {
+                clearTimeout(this.reconnectTimeout);
+                this.reconnectTimeout = null;
+            }
+            this._redisFailedIndexes.delete(this._redisCurrentIndex);
+            if (this._justFailedOver) {
+                this.logger.warn(`[REDIS][FAILOVER] Connected to new server, flushing potentially stale cache...`);
+                try {
+                    await this.redis.flushdb();
+                    this.logger.info(`[REDIS][FAILOVER] Stale cache flushed successfully.`);
+                }
+                catch (err) {
+                    this.logger.error(`[REDIS][FAILOVER] FAILED TO FLUSH CACHE:`, err);
+                }
+                this._justFailedOver = false;
+            }
+        });
+        this.redis.on('error', (err) => {
+            if (err && (err.code === 'ECONNREFUSED' || err.message)) {
+                this.logger.warn(`🟠 [REDIS] Connection error: ${err.message}`);
+            }
+        });
+        this.redis.on('close', () => {
+            if (this.isRedisConnected) {
+                if (this.isShardMode) {
+                    this.logger.error('❌ [REDIS][SHARD] Connection closed. Cache DISABLED (no fallback).');
+                }
+                else {
+                    this.logger.error('❌ [REDIS] Connection closed. Fallback/failover will be attempted.');
+                }
+            }
+            this.isRedisConnected = false;
+            this._redisFailedIndexes.add(this._redisCurrentIndex);
+            this.logger.warn(`[REDIS] Connection #${this._redisCurrentIndex + 1} closed. Attempting immediate failover...`);
+            const triedFailover = this._tryRedisFailover();
+            if (!triedFailover) {
+                this.logger.warn(`[REDIS] Failover exhausted. Scheduling full reconnect...`);
+                this._scheduleReconnect();
+            }
+        });
+    }
+    static _scheduleReconnect() {
+        if (this.reconnectTimeout)
+            return;
+        const sinceLast = Date.now() - this.lastAutoReconnectTs;
+        if (sinceLast < RECONNECT_DELAY_MINUTES * 60 * 1000)
+            return;
+        this.lastAutoReconnectTs = Date.now();
+        if (this.isShardMode) {
+            this.logger.warn(`[REDIS][SHARD] Attempting auto-reconnect after ${RECONNECT_DELAY_MINUTES}min downtime...`);
+        }
+        else {
+            this.logger.warn(`🟢 [REDIS] Attempting auto-reconnect after ${RECONNECT_DELAY_MINUTES}min downtime...`);
+        }
+        this.reconnectTimeout = setTimeout(() => {
+            this.reconnectTimeout = null;
+            this._redisCurrentIndex = 0;
+            this._redisFailedIndexes.clear();
+            this._closeCurrentRedis();
+            this.initializeRedis();
+        }, RECONNECT_DELAY_MINUTES * 60 * 1000);
+    }
+    static getCacheKey(queryIdentifier) {
+        let dataToHash = queryIdentifier;
+        if (dataToHash &&
+            typeof dataToHash === 'object' &&
+            !dataToHash.where &&
+            !dataToHash.include) {
+            dataToHash = { where: dataToHash };
+        }
+        const opts = {
+            replacer: (_key, value) => typeof value === 'bigint' ? value.toString() : value,
+        };
+        const keyBody = typeof queryIdentifier === 'string'
+            ? queryIdentifier
+            : jsonStringify(this.normalizeQueryOptions(dataToHash), opts);
+        return `${this.CACHE_VERSION}:${this.name}:${keyBody}`;
+    }
+    static normalizeQueryOptions(data) {
+        if (!data || typeof data !== 'object')
+            return data;
+        if (Array.isArray(data))
+            return data.map((item) => this.normalizeQueryOptions(item));
+        const normalized = {};
+        Object.keys(data)
+            .sort()
+            .forEach((key) => {
+            normalized[key] = this.normalizeQueryOptions(data[key]);
+        });
+        Object.getOwnPropertySymbols(data).forEach((symbol) => {
+            const key = `$${symbol.toString().slice(7, -1)}`;
+            normalized[key] = this.normalizeQueryOptions(data[symbol]);
+        });
+        return normalized;
+    }
+    static _generateSmartTags(instance) {
+        if (!instance)
+            return [`${this.name}`];
+        const tags = [`${this.name}`];
+        const pk = this.primaryKeyAttribute;
+        if (instance[pk]) {
+            tags.push(`${this.name}:${pk}:${instance[pk]}`);
+        }
+        const smartKeys = this.cacheKeys || this.CACHE_KEYS || [];
+        if (Array.isArray(smartKeys)) {
+            for (const keyGroup of smartKeys) {
+                const keys = Array.isArray(keyGroup) ? keyGroup : [keyGroup];
+                const hasAllValues = keys.every((k) => instance[k] !== undefined && instance[k] !== null);
+                if (hasAllValues) {
+                    const tagParts = keys
+                        .map((k) => `${k}:${instance[k]}`)
+                        .join(':');
+                    tags.push(`${this.name}:${tagParts}`);
+                }
+            }
+        }
+        return tags;
+    }
+    static async setCacheEntry(cacheKeyOrQuery, data, ttl, tags = []) {
+        const cacheKey = typeof cacheKeyOrQuery === 'string'
+            ? cacheKeyOrQuery
+            : this.getCacheKey(cacheKeyOrQuery);
+        const finalTtl = ttl || this.CACHE_TTL || this.DEFAULT_TTL;
+        if (this.isRedisConnected) {
+            await this._redisSetCacheEntry(cacheKey, data, finalTtl, tags);
+        }
+        else if (!this.isShardMode) {
+            this._mapSetCacheEntry(cacheKey, data, finalTtl);
+        }
+    }
+    static async getCachedEntry(cacheKeyOrQuery, includeOptions) {
+        const cacheKey = typeof cacheKeyOrQuery === 'string'
+            ? cacheKeyOrQuery
+            : this.getCacheKey(cacheKeyOrQuery);
+        if (this.isRedisConnected) {
+            return this._redisGetCachedEntry(cacheKey, includeOptions);
+        }
+        else if (!this.isShardMode) {
+            return this._mapGetCachedEntry(cacheKey, includeOptions);
+        }
+        return { hit: false, data: undefined };
+    }
+    static async clearCache(keys) {
+        const cacheKey = typeof keys === 'string' ? keys : this.getCacheKey(keys);
+        if (this.isRedisConnected) {
+            await this._redisClearCache(cacheKey);
+        }
+        else if (!this.isShardMode) {
+            this._mapClearCache(cacheKey);
+        }
+    }
+    static async _redisSetCacheEntry(cacheKey, data, ttl, tags = []) {
+        if (!this.redis)
+            return;
+        try {
+            let plainData = data;
+            if (data && typeof data.toJSON === 'function') {
+                plainData = data.toJSON();
+            }
+            else if (Array.isArray(data)) {
+                plainData = data.map((item) => item && typeof item.toJSON === 'function' ? item.toJSON() : item);
+            }
+            const valueToStore = plainData === null
+                ? NEGATIVE_CACHE_PLACEHOLDER
+                : safeStringify(plainData, this.logger);
+            const multi = this.redis.multi();
+            multi.set(cacheKey, valueToStore, 'PX', ttl);
+            for (const tag of tags) {
+                multi.sadd(tag, cacheKey);
+            }
+            await multi.exec();
+            this.cacheStats.sets++;
+        }
+        catch (err) {
+            this._trackRedisError(err);
+        }
+    }
+    static async _redisGetCachedEntry(cacheKey, includeOptions) {
+        if (!this.redis)
+            return { hit: false, data: undefined };
+        try {
+            const result = await this.redis.get(cacheKey);
+            if (result === null || result === undefined)
+                return { hit: false, data: undefined };
+            this.cacheStats.redisHits++;
+            if (result === NEGATIVE_CACHE_PLACEHOLDER) {
+                return { hit: true, data: null };
+            }
+            const parsedData = safeParse(result, this.logger);
+            if (parsedData === null) {
+                return { hit: false, data: undefined };
+            }
+            const includeAsArray = includeOptions
+                ? Array.isArray(includeOptions)
+                    ? includeOptions
+                    : [includeOptions]
+                : undefined;
+            const buildInstance = (data) => {
+                const instance = this.build(data, {
+                    isNewRecord: false,
+                    include: includeAsArray,
+                });
+                return instance;
+            };
+            if (Array.isArray(parsedData)) {
+                const instances = parsedData.map((d) => buildInstance(d));
+                return { hit: true, data: instances };
+            }
+            else {
+                const instance = buildInstance(parsedData);
+                return { hit: true, data: instance };
+            }
+        }
+        catch (err) {
+            this._trackRedisError(err);
+            return { hit: false, data: undefined };
+        }
+    }
+    static async _redisClearCache(cacheKey) {
+        if (!this.redis)
+            return;
+        try {
+            await this.redis.del(cacheKey);
+            this.cacheStats.clears++;
+        }
+        catch (err) {
+            this._trackRedisError(err);
+        }
+    }
+    static async invalidateByTags(tags) {
+        if (!this.isRedisConnected ||
+            !Array.isArray(tags) ||
+            tags.length === 0 ||
+            !this.redis)
+            return;
+        try {
+            const keysToDelete = await this.redis.sunion(tags);
+            if (keysToDelete && keysToDelete.length > 0) {
+                this.logger.info(`🎯 [SNIPER] Invalidating ${keysToDelete.length} keys for tags: ${tags.join(', ')}`);
+                await this.redis.multi().del(keysToDelete).del(tags).exec();
+            }
+            else {
+                await this.redis.del(tags);
+            }
+        }
+        catch (err) {
+            this._trackRedisError(err);
+        }
+    }
+    static _mapSetCacheEntry(cacheKey, data, ttl) {
+        if (this.isShardMode)
+            return;
+        if (data === null) {
+            this.localNegativeCache.add(cacheKey);
+            this.localCache.delete(cacheKey);
+        }
+        else {
+            let plainData = data;
+            if (data && typeof data.toJSON === 'function') {
+                plainData = data.toJSON();
+            }
+            else if (Array.isArray(data)) {
+                plainData = data.map((item) => item && typeof item.toJSON === 'function' ? item.toJSON() : item);
+            }
+            const dataCopy = plainData === null
+                ? NEGATIVE_CACHE_PLACEHOLDER
+                : safeStringify(plainData, this.logger);
+            this.localCache.set(cacheKey, {
+                data: dataCopy,
+                expires: Date.now() + ttl,
+            });
+            this.localNegativeCache.delete(cacheKey);
+        }
+        this.cacheStats.sets++;
+    }
+    static _mapGetCachedEntry(cacheKey, includeOptions) {
+        if (this.isShardMode)
+            return { hit: false, data: undefined };
+        if (this.localNegativeCache.has(cacheKey)) {
+            this.cacheStats.mapHits++;
+            return { hit: true, data: null };
+        }
+        const entry = this.localCache.get(cacheKey);
+        if (entry && entry.expires > Date.now()) {
+            this.cacheStats.mapHits++;
+            const dataRaw = entry.data;
+            let parsedData;
+            if (typeof dataRaw === 'string') {
+                parsedData = safeParse(dataRaw, this.logger);
+            }
+            else {
+                parsedData = dataRaw;
+            }
+            if (typeof parsedData !== 'object' || parsedData === null) {
+                return { hit: true, data: parsedData };
+            }
+            const includeAsArray = includeOptions
+                ? Array.isArray(includeOptions)
+                    ? includeOptions
+                    : [includeOptions]
+                : undefined;
+            if (Array.isArray(parsedData)) {
+                const instances = this.bulkBuild(parsedData, {
+                    isNewRecord: false,
+                    include: includeAsArray,
+                });
+                return { hit: true, data: instances };
+            }
+            else {
+                const instance = this.build(parsedData, {
+                    isNewRecord: false,
+                    include: includeAsArray,
+                });
+                return { hit: true, data: instance };
+            }
+        }
+        if (entry)
+            this.localCache.delete(cacheKey);
+        return { hit: false, data: undefined };
+    }
+    static _mapClearCache(cacheKey) {
+        if (this.isShardMode)
+            return;
+        this.localCache.delete(cacheKey);
+        this.localNegativeCache.delete(cacheKey);
+        this.cacheStats.clears++;
+    }
+    static _mapClearAllModelCache() {
+        if (this.isShardMode)
+            return;
+        const prefix = `${this.CACHE_VERSION}:${this.name}:`;
+        let cleared = 0;
+        for (const key of this.localCache.keys()) {
+            if (key.startsWith(prefix)) {
+                this.localCache.delete(key);
+                cleared++;
+            }
+        }
+        for (const key of this.localNegativeCache.keys()) {
+            if (key.startsWith(prefix)) {
+                this.localNegativeCache.delete(key);
+                cleared++;
+            }
+        }
+        if (cleared > 0) {
+            this.logger.info(`♻️ [MAP CACHE] Cleared ${cleared} in-memory entries for ${this.name} (Redis fallback).`);
+        }
+    }
+    static _normalizeFindOptions(options) {
+        if (!options ||
+            typeof options !== 'object' ||
+            Object.keys(options).length === 0)
+            return { where: {} };
+        if (options.where) {
+            const sequelizeOptions = { ...options };
+            delete sequelizeOptions.cacheTags;
+            delete sequelizeOptions.noCache;
+            return sequelizeOptions;
+        }
+        const knownOptions = [
+            'order',
+            'limit',
+            'attributes',
+            'include',
+            'group',
+            'having',
+        ];
+        const cacheSpecificOptions = ['cacheTags', 'noCache'];
+        const whereClause = {};
+        const otherOptions = {};
+        for (const key in options) {
+            if (cacheSpecificOptions.includes(key)) {
+                continue;
+            }
+            if (knownOptions.includes(key))
+                otherOptions[key] = options[key];
+            else
+                whereClause[key] = options[key];
+        }
+        return { where: whereClause, ...otherOptions };
+    }
+    static async getCache(keys, options = {}) {
+        const { noCache, customCacheKey, ttl, ...explicitQueryOptions } = options;
+        if (Array.isArray(keys)) {
+            const pk = this.primaryKeyAttribute;
+            return this.findAll({ where: { [pk]: keys.map((m) => m[pk]) } });
+        }
+        const normalizedKeys = this._normalizeFindOptions(keys);
+        const finalQuery = {
+            ...normalizedKeys,
+            ...explicitQueryOptions,
+            where: {
+                ...(normalizedKeys.where || {}),
+                ...(explicitQueryOptions.where || {}),
+            },
+        };
+        if (noCache) {
+            return this.findOne(finalQuery);
+        }
+        if (!finalQuery.where || Object.keys(finalQuery.where).length === 0) {
+            return null;
+        }
+        const cacheKey = customCacheKey || this.getCacheKey(finalQuery);
+        const cacheResult = await this.getCachedEntry(cacheKey, finalQuery.include);
+        if (cacheResult.hit)
+            return cacheResult.data;
+        this.cacheStats.misses++;
+        if (this.pendingQueries.has(cacheKey))
+            return this.pendingQueries.get(cacheKey);
+        const queryPromise = this.findOne(finalQuery)
+            .then(async (record) => {
+            if (this.isRedisConnected || !this.isShardMode) {
+                const tags = [`${this.name}`];
+                if (record)
+                    tags.push(`${this.name}:${this.primaryKeyAttribute}:${record[this.primaryKeyAttribute]}`);
+                await this.setCacheEntry(cacheKey, record, ttl, tags);
+            }
+            return record;
+        })
+            .finally(() => this.pendingQueries.delete(cacheKey));
+        this.pendingQueries.set(cacheKey, queryPromise);
+        return queryPromise;
+    }
+    static async getAllCache(options = {}) {
+        const { cacheTags, noCache, customCacheKey, ttl, ...explicitQueryOptions } = options || {};
+        const normalizedOptions = this._normalizeFindOptions(explicitQueryOptions);
+        if (noCache) {
+            return this.findAll(normalizedOptions);
+        }
+        const cacheKey = customCacheKey || this.getCacheKey(normalizedOptions);
+        const cacheResult = await this.getCachedEntry(cacheKey, normalizedOptions.include);
+        if (cacheResult.hit)
+            return cacheResult.data;
+        this.cacheStats.misses++;
+        if (this.pendingQueries.has(cacheKey))
+            return this.pendingQueries.get(cacheKey);
+        const queryPromise = this.findAll(normalizedOptions)
+            .then(async (records) => {
+            if (this.isRedisConnected || !this.isShardMode) {
+                const tags = [`${this.name}`];
+                if (Array.isArray(cacheTags))
+                    tags.push(...cacheTags);
+                await this.setCacheEntry(cacheKey, records, ttl, tags);
+            }
+            return records;
+        })
+            .finally(() => this.pendingQueries.delete(cacheKey));
+        this.pendingQueries.set(cacheKey, queryPromise);
+        return queryPromise;
+    }
+    static async scheduleAdd(keySuffix, score, value) {
+        if (!this.isRedisConnected || !this.redis)
+            return;
+        const key = `${this.name}:${keySuffix}`;
+        try {
+            await this.redis.zadd(key, score, value);
+        }
+        catch (e) {
+            this._trackRedisError(e);
+        }
+    }
+    static async scheduleRemove(keySuffix, value) {
+        if (!this.isRedisConnected || !this.redis)
+            return;
+        const key = `${this.name}:${keySuffix}`;
+        try {
+            await this.redis.zrem(key, value);
+        }
+        catch (e) {
+            this._trackRedisError(e);
+        }
+    }
+    static async scheduleGetExpired(keySuffix, scoreLimit = Date.now()) {
+        if (!this.isRedisConnected || !this.redis)
+            return [];
+        const key = `${this.name}:${keySuffix}`;
+        try {
+            return await this.redis.zrangebyscore(key, 0, scoreLimit);
+        }
+        catch (e) {
+            this._trackRedisError(e);
+            return [];
+        }
+    }
+    static async scheduleClear(keySuffix) {
+        if (!this.isRedisConnected || !this.redis)
+            return;
+        const key = `${this.name}:${keySuffix}`;
+        try {
+            await this.redis.del(key);
+        }
+        catch (e) {
+            this._trackRedisError(e);
+        }
+    }
+    static async findOrCreateWithCache(options) {
+        if (!options || !options.where) {
+            throw new Error("findOrCreateWithCache requires a 'where' option.");
+        }
+        const { where, defaults, noCache, ...otherOptions } = options;
+        if (noCache) {
+            return this.findOrCreate(options);
+        }
+        const normalizedWhere = this._normalizeFindOptions(where).where;
+        const cacheKey = this.getCacheKey(normalizedWhere);
+        const cacheResult = await this.getCachedEntry(cacheKey, otherOptions.include);
+        if (cacheResult.hit && cacheResult.data) {
+            const instance = cacheResult.data;
+            let needsUpdate = false;
+            if (defaults && typeof defaults === 'object') {
+                for (const key in defaults) {
+                    if (instance[key] === undefined ||
+                        String(instance[key]) !== String(defaults[key])) {
+                        instance[key] = defaults[key];
+                        needsUpdate = true;
+                    }
+                }
+            }
+            if (needsUpdate) {
+                await instance.saveAndUpdateCache();
+            }
+            return [instance, false];
+        }
+        this.cacheStats.misses++;
+        if (this.pendingQueries.has(cacheKey)) {
+            return this.pendingQueries.get(cacheKey);
+        }
+        const findPromise = this.findOne({ where, ...otherOptions })
+            .then(async (instance) => {
+            if (instance) {
+                let needsUpdate = false;
+                if (defaults && typeof defaults === 'object') {
+                    for (const key in defaults) {
+                        if (instance[key] === undefined ||
+                            String(instance[key]) !== String(defaults[key])) {
+                            instance[key] = defaults[key];
+                            needsUpdate = true;
+                        }
+                    }
+                }
+                if (needsUpdate) {
+                    await instance.saveAndUpdateCache();
+                }
+                else {
+                    const tags = [
+                        `${this.name}`,
+                        `${this.name}:${this.primaryKeyAttribute}:${instance[this.primaryKeyAttribute]}`,
+                    ];
+                    await this.setCacheEntry(cacheKey, instance, undefined, tags);
+                }
+                return [instance, false];
+            }
+            else {
+                const createData = { ...where, ...defaults };
+                const newInstance = await this.create(createData);
+                const tags = [
+                    `${this.name}`,
+                    `${this.name}:${this.primaryKeyAttribute}:${newInstance[this.primaryKeyAttribute]}`,
+                ];
+                await this.setCacheEntry(cacheKey, newInstance, undefined, tags);
+                return [newInstance, true];
+            }
+        })
+            .finally(() => {
+            this.pendingQueries.delete(cacheKey);
+        });
+        this.pendingQueries.set(cacheKey, findPromise);
+        return findPromise;
+    }
+    static async countWithCache(options = {}, ttl = 5 * 60 * 1000) {
+        const { ...countOptions } = options || {};
+        const cacheKeyOptions = { queryType: 'count', ...countOptions };
+        const cacheKey = this.getCacheKey(cacheKeyOptions);
+        const cacheResult = await this.getCachedEntry(cacheKey);
+        if (cacheResult.hit) {
+            return cacheResult.data;
+        }
+        this.cacheStats.misses++;
+        const count = await this.count(countOptions);
+        if (this.isRedisConnected || !this.isShardMode) {
+            const tags = [`${this.name}`];
+            this.setCacheEntry(cacheKey, count, ttl, tags);
+        }
+        return count;
+    }
+    async saveAndUpdateCache() {
+        const savedInstance = await this.save();
+        const pk = this.constructor.primaryKeyAttribute;
+        const pkValue = this[pk];
+        if (pkValue &&
+            (this.constructor.isRedisConnected ||
+                !this.constructor.isShardMode)) {
+            const cacheKey = this.constructor.getCacheKey({
+                where: { [pk]: pkValue },
+            });
+            const tags = [
+                `${this.constructor.name}`,
+                `${this.constructor.name}:${pk}:${pkValue}`,
+            ];
+            await this.constructor.setCacheEntry(cacheKey, savedInstance, undefined, tags);
+            this.constructor.logger.info(`🔄 [CACHE] Updated cache for ${this.constructor.name}:${pk}:${pkValue}`);
+        }
+        return savedInstance;
+    }
+    static async clearNegativeCache(keys) {
+        return this.clearCache(keys);
+    }
+    static async aggregateWithCache(options = {}, cacheOptions = {}) {
+        const { cacheTags, ...queryOptions } = options || {};
+        const { ttl = 5 * 60 * 1000 } = cacheOptions || {};
+        const cacheKeyOptions = { queryType: 'aggregate', ...queryOptions };
+        const cacheKey = this.getCacheKey(cacheKeyOptions);
+        const cacheResult = await this.getCachedEntry(cacheKey);
+        if (cacheResult.hit) {
+            return cacheResult.data;
+        }
+        this.cacheStats.misses++;
+        const result = await this.findAll(queryOptions);
+        if (this.isRedisConnected || !this.isShardMode) {
+            const tags = [`${this.name}`];
+            if (Array.isArray(cacheTags))
+                tags.push(...cacheTags);
+            this.setCacheEntry(cacheKey, result, ttl, tags);
+        }
+        return result;
+    }
+    static initializeCacheHooks() {
+        if (!this.redis) {
+            this.logger.warn(`❌ Redis not initialized for model ${this.name}. Cache hooks will not be attached.`);
+            return;
+        }
+        const afterSaveLogic = async (instance) => {
+            const modelClass = instance.constructor;
+            if (modelClass.isRedisConnected) {
+                const tagsToInvalidate = modelClass._generateSmartTags(instance);
+                if (Array.isArray(modelClass.customInvalidationTags)) {
+                    tagsToInvalidate.push(...modelClass.customInvalidationTags);
+                }
+                await modelClass.invalidateByTags(tagsToInvalidate);
+            }
+            else if (!modelClass.isShardMode) {
+                modelClass._mapClearAllModelCache();
+            }
+        };
+        const afterDestroyLogic = async (instance) => {
+            const modelClass = instance.constructor;
+            if (modelClass.isRedisConnected) {
+                const tagsToInvalidate = modelClass._generateSmartTags(instance);
+                if (Array.isArray(modelClass.customInvalidationTags)) {
+                    tagsToInvalidate.push(...modelClass.customInvalidationTags);
+                }
+                await modelClass.invalidateByTags(tagsToInvalidate);
+            }
+            else if (!modelClass.isShardMode) {
+                modelClass._mapClearAllModelCache();
+            }
+        };
+        const afterBulkLogic = async () => {
+            if (this.isRedisConnected) {
+                await this.invalidateByTags([`${this.name}`]);
+            }
+            else if (!this.isShardMode) {
+                this._mapClearAllModelCache();
+            }
+        };
+        this.addHook('afterSave', afterSaveLogic);
+        this.addHook('afterDestroy', afterDestroyLogic);
+        this.addHook('afterBulkCreate', afterBulkLogic);
+        this.addHook('afterBulkUpdate', afterBulkLogic);
+        this.addHook('afterBulkDestroy', afterBulkLogic);
+    }
+    static attachHooksToAllModels(sequelizeInstance, client) {
+        if (!this.redis) {
+            this.logger.error('❌ Cannot attach hooks because Redis is not initialized.');
+            return;
+        }
+        for (const modelName in sequelizeInstance.models) {
+            const model = sequelizeInstance.models[modelName];
+            if (model.prototype instanceof KythiaModel) {
+                model.client = client;
+                this.logger.info(`⚙️  Attaching hooks to ${model.name}`);
+                model.initializeCacheHooks();
+            }
+        }
+    }
+    static async touchParent(childInstance, foreignKeyField, ParentModel, timestampField = 'updatedAt') {
+        if (!childInstance || !childInstance[foreignKeyField]) {
+            return;
+        }
+        try {
+            const parentPk = ParentModel.primaryKeyAttribute;
+            const parent = await ParentModel.findByPk(childInstance[foreignKeyField]);
+            if (parent) {
+                parent.changed(timestampField, true);
+                await parent.save({ fields: [timestampField] });
+                this.logger.info(`🔄 Touched parent ${ParentModel.name} #${parent[parentPk]} due to change in ${this.name}.`);
+            }
+        }
+        catch (e) {
+            this.logger.error(`🔄 Failed to touch parent ${ParentModel.name}`, e);
+        }
+    }
+    static setupParentTouch(foreignKeyField, ParentModel, timestampField = 'updatedAt') {
+        const touchHandler = (instance) => {
+            return this.touchParent(instance, foreignKeyField, ParentModel, timestampField);
+        };
+        const bulkTouchHandler = (instances) => {
+            if (instances && instances.length > 0) {
+                return this.touchParent(instances[0], foreignKeyField, ParentModel, timestampField);
+            }
+            return Promise.resolve();
+        };
+        this.addHook('afterSave', touchHandler);
+        this.addHook('afterDestroy', touchHandler);
+        this.addHook('afterBulkCreate', bulkTouchHandler);
+    }
+}
+exports.KythiaModel = KythiaModel;
+exports.default = KythiaModel;
+//# sourceMappingURL=KythiaModel.js.map