@adalo/metrics 0.1.122 → 0.1.124

package/lib/health/healthCheckCache.d.ts

@@ -0,0 +1,57 @@
+/**
+ * HealthCheckCache provides a shared cache layer for health check results.
+ * It uses Redis if available for cross-process sharing, with graceful fallback
+ * to in-memory cache if Redis is not configured or unavailable.
+ */
+export class HealthCheckCache {
+    /**
+     * @param {Object} options
+     * @param {any} [options.redisClient] - Redis client instance (optional)
+     * @param {string} [options.appName] - Application name for cache key
+     * @param {number} [options.cacheTtlMs=60000] - Cache TTL in milliseconds
+     */
+    constructor(options?: {
+        redisClient?: any;
+        appName?: string | undefined;
+        cacheTtlMs?: number | undefined;
+    });
+    redisClient: any;
+    appName: string;
+    cacheTtlMs: number;
+    cacheKey: string;
+    /** In-memory fallback cache */
+    _memoryCache: any;
+    _memoryCacheTimestamp: any;
+    _redisClientType: string | undefined;
+    _redisAvailable: boolean;
+    /**
+     * Checks if Redis is available and working.
+     * @returns {Promise<boolean>}
+     * @private
+     */
+    private _checkRedisAvailable;
+    /**
+     * Gets cached health check result from Redis (if available) or in-memory cache.
+     * Throws error if Redis is configured but read fails (so caller can return proper error format).
+     * @returns {Promise<Object | null>} Cached result or null
+     * @throws {Error} If Redis is configured but read fails
+     */
+    get(): Promise<Object | null>;
+    /**
+     * Sets cached health check result in Redis (if available) and in-memory.
+     * @param {Object} result - Health check result to cache
+     * @returns {Promise<void>}
+     */
+    set(result: Object): Promise<void>;
+    /**
+     * Clears the cache (both Redis and in-memory).
+     * @returns {Promise<void>}
+     */
+    clear(): Promise<void>;
+    /**
+     * Checks if Redis is configured and available.
+     * @returns {boolean}
+     */
+    isRedisAvailable(): boolean;
+}
+//# sourceMappingURL=healthCheckCache.d.ts.map

package/lib/health/healthCheckCache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"healthCheckCache.d.ts","sourceRoot":"","sources":["../../src/health/healthCheckCache.js"],"names":[],"mappings":"AAOA;;;;GAIG;AACH;IACE;;;;;OAKG;IACH;QAJyB,WAAW,GAAzB,GAAG;QACc,OAAO;QACP,UAAU;OAqBrC;IAlBC,iBAA8C;IAC9C,gBAA6E;IAC7E,mBAAiD;IACjD,iBAA6C;IAE7C,+BAA+B;IAC/B,kBAAwB;IACxB,2BAAiC;IAG/B,qCAA4D;IAC5D,yBAA2B;IAS/B;;;;OAIG;IACH,6BAiCC;IAED;;;;;OAKG;IACH,OAHa,QAAQ,MAAM,GAAG,IAAI,CAAC,CA2DlC;IAED;;;;OAIG;IACH,YAHW,MAAM,GACJ,QAAQ,IAAI,CAAC,CA6CzB;IAED;;;OAGG;IACH,SAFa,QAAQ,IAAI,CAAC,CA4BzB;IAED;;;OAGG;IACH,oBAFa,OAAO,CAInB;CACF"}

package/lib/health/healthCheckCache.js

@@ -0,0 +1,200 @@
+"use strict";
+
+const {
+  getRedisClientType,
+  REDIS_V4,
+  IOREDIS,
+  REDIS_V3
+} = require('../redisUtils');
+
+/**
+ * HealthCheckCache provides a shared cache layer for health check results.
+ * It uses Redis if available for cross-process sharing, with graceful fallback
+ * to in-memory cache if Redis is not configured or unavailable.
+ */
+class HealthCheckCache {
+  /**
+   * @param {Object} options
+   * @param {any} [options.redisClient] - Redis client instance (optional)
+   * @param {string} [options.appName] - Application name for cache key
+   * @param {number} [options.cacheTtlMs=60000] - Cache TTL in milliseconds
+   */
+  constructor(options = {}) {
+    this.redisClient = options.redisClient || null;
+    this.appName = options.appName || process.env.BUILD_APP_NAME || 'unknown-app';
+    this.cacheTtlMs = options.cacheTtlMs ?? 60 * 1000;
+    this.cacheKey = `healthcheck:${this.appName}`;
+
+    /** In-memory fallback cache */
+    this._memoryCache = null;
+    this._memoryCacheTimestamp = null;
+    if (this.redisClient) {
+      this._redisClientType = getRedisClientType(this.redisClient);
+      this._redisAvailable = true;
+    } else {
+      this._redisAvailable = false;
+      console.warn(`[HealthCheckCache] Redis not configured for ${this.appName}, using in-memory cache only (not shared across processes)`);
+    }
+  }
+
+  /**
+   * Checks if Redis is available and working.
+   * @returns {Promise<boolean>}
+   * @private
+   */
+  async _checkRedisAvailable() {
+    if (!this.redisClient || !this._redisAvailable) {
+      return false;
+    }
+    try {
+      let pong;
+      if (this._redisClientType === REDIS_V3) {
+        pong = await new Promise((resolve, reject) => {
+          this.redisClient.ping((err, result) => {
+            if (err) reject(err);else resolve(result);
+          });
+        });
+      } else if (this._redisClientType === REDIS_V4 || this._redisClientType === IOREDIS) {
+        pong = await this.redisClient.ping();
+      } else {
+        return false;
+      }
+      return pong === 'PONG';
+    } catch (err) {
+      // Redis not available
+      if (this._redisAvailable) {
+        console.warn(`[HealthCheckCache] Redis became unavailable: ${err.message}`);
+        this._redisAvailable = false;
+      }
+      return false;
+    }
+  }
+
+  /**
+   * Gets cached health check result from Redis (if available) or in-memory cache.
+   * Throws error if Redis is configured but read fails (so caller can return proper error format).
+   * @returns {Promise<Object | null>} Cached result or null
+   * @throws {Error} If Redis is configured but read fails
+   */
+  async get() {
+    // If Redis is configured, we MUST read from it (don't fall back to memory)
+    if (this.redisClient) {
+      try {
+        let cachedStr;
+        if (this._redisClientType === REDIS_V3) {
+          cachedStr = await new Promise((resolve, reject) => {
+            this.redisClient.get(this.cacheKey, (err, result) => {
+              if (err) reject(err);else resolve(result);
+            });
+          });
+        } else if (this._redisClientType === REDIS_V4 || this._redisClientType === IOREDIS) {
+          cachedStr = await this.redisClient.get(this.cacheKey);
+        }
+        if (cachedStr) {
+          try {
+            const cached = JSON.parse(cachedStr);
+            if (cached.result && cached.timestamp) {
+              const age = Date.now() - cached.timestamp;
+              if (age < this.cacheTtlMs) {
+                // Also update in-memory cache as backup
+                this._memoryCache = cached.result;
+                this._memoryCacheTimestamp = cached.timestamp;
+                return cached.result;
+              }
+            }
+          } catch (parseErr) {
+            console.warn(`[HealthCheckCache] Failed to parse Redis cache:`, parseErr.message);
+          }
+        }
+        // No cache in Redis - return null (worker may not have run yet)
+        return null;
+      } catch (redisErr) {
+        // Redis read failed - throw error so caller can return proper error format
+        this._redisAvailable = false;
+        throw new Error(`Redis cache read failed: ${redisErr.message}`);
+      }
+    }
+
+    // No Redis configured - fall back to in-memory cache
+    if (this._memoryCache && this._memoryCacheTimestamp) {
+      const age = Date.now() - this._memoryCacheTimestamp;
+      if (age < this.cacheTtlMs) {
+        return this._memoryCache;
+      }
+    }
+    return null;
+  }
+
+  /**
+   * Sets cached health check result in Redis (if available) and in-memory.
+   * @param {Object} result - Health check result to cache
+   * @returns {Promise<void>}
+   */
+  async set(result) {
+    const cacheData = {
+      result,
+      timestamp: Date.now()
+    };
+
+    // Update in-memory cache
+    this._memoryCache = result;
+    this._memoryCacheTimestamp = cacheData.timestamp;
+
+    // Try to update Redis if available
+    if (await this._checkRedisAvailable()) {
+      try {
+        const cacheStr = JSON.stringify(cacheData);
+        const ttlSeconds = Math.ceil(this.cacheTtlMs / 1000) + 10;
+        if (this._redisClientType === REDIS_V3) {
+          await new Promise((resolve, reject) => {
+            this.redisClient.setex(this.cacheKey, ttlSeconds, cacheStr, err => {
+              if (err) reject(err);else resolve();
+            });
+          });
+        } else if (this._redisClientType === REDIS_V4 || this._redisClientType === IOREDIS) {
+          await this.redisClient.setex(this.cacheKey, ttlSeconds, cacheStr);
+        }
+      } catch (redisErr) {
+        // Redis write failed, but in-memory cache is updated
+        console.warn(`[HealthCheckCache] Redis write failed (in-memory cache updated):`, redisErr.message);
+        this._redisAvailable = false;
+      }
+    }
+  }
+
+  /**
+   * Clears the cache (both Redis and in-memory).
+   * @returns {Promise<void>}
+   */
+  async clear() {
+    this._memoryCache = null;
+    this._memoryCacheTimestamp = null;
+    if (await this._checkRedisAvailable()) {
+      try {
+        if (this._redisClientType === REDIS_V3) {
+          await new Promise((resolve, reject) => {
+            this.redisClient.del(this.cacheKey, err => {
+              if (err) reject(err);else resolve();
+            });
+          });
+        } else if (this._redisClientType === REDIS_V4 || this._redisClientType === IOREDIS) {
+          await this.redisClient.del(this.cacheKey);
+        }
+      } catch (redisErr) {
+        console.warn(`[HealthCheckCache] Redis clear failed:`, redisErr.message);
+      }
+    }
+  }
+
+  /**
+   * Checks if Redis is configured and available.
+   * @returns {boolean}
+   */
+  isRedisAvailable() {
+    return this._redisAvailable && this.redisClient !== null;
+  }
+}
+module.exports = {
+  HealthCheckCache
+};
+//# sourceMappingURL=healthCheckCache.js.map

package/lib/health/healthCheckCache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"healthCheckCache.js","names":["getRedisClientType","REDIS_V4","IOREDIS","REDIS_V3","require","HealthCheckCache","constructor","options","redisClient","appName","process","env","BUILD_APP_NAME","cacheTtlMs","cacheKey","_memoryCache","_memoryCacheTimestamp","_redisClientType","_redisAvailable","console","warn","_checkRedisAvailable","pong","Promise","resolve","reject","ping","err","result","message","get","cachedStr","cached","JSON","parse","timestamp","age","Date","now","parseErr","redisErr","Error","set","cacheData","cacheStr","stringify","ttlSeconds","Math","ceil","setex","clear","del","isRedisAvailable","module","exports"],"sources":["../../src/health/healthCheckCache.js"],"sourcesContent":["const {\n  getRedisClientType,\n  REDIS_V4,\n  IOREDIS,\n  REDIS_V3,\n} = require('../redisUtils')\n\n/**\n * HealthCheckCache provides a shared cache layer for health check results.\n * It uses Redis if available for cross-process sharing, with graceful fallback\n * to in-memory cache if Redis is not configured or unavailable.\n */\nclass HealthCheckCache {\n  /**\n   * @param {Object} options\n   * @param {any} [options.redisClient] - Redis client instance (optional)\n   * @param {string} [options.appName] - Application name for cache key\n   * @param {number} [options.cacheTtlMs=60000] - Cache TTL in milliseconds\n   */\n  constructor(options = {}) {\n    this.redisClient = options.redisClient || null\n    this.appName = options.appName || process.env.BUILD_APP_NAME || 'unknown-app'\n    this.cacheTtlMs = options.cacheTtlMs ?? 60 * 1000\n    this.cacheKey = `healthcheck:${this.appName}`\n    \n    /** In-memory fallback cache */\n    this._memoryCache = null\n    this._memoryCacheTimestamp = null\n\n    if (this.redisClient) {\n      this._redisClientType = getRedisClientType(this.redisClient)\n      this._redisAvailable = true\n    } else {\n      this._redisAvailable = false\n      console.warn(\n        `[HealthCheckCache] Redis not configured for ${this.appName}, using in-memory cache only (not shared across processes)`\n      )\n    }\n  }\n\n  /**\n   * Checks if Redis is available and working.\n   * @returns {Promise<boolean>}\n   * @private\n   */\n  async _checkRedisAvailable() {\n    if (!this.redisClient || !this._redisAvailable) {\n      return false\n    }\n\n    try {\n      let pong\n      if (this._redisClientType === REDIS_V3) {\n        pong = await new Promise((resolve, reject) => {\n          this.redisClient.ping((err, result) => {\n            if (err) reject(err)\n            else resolve(result)\n          })\n        })\n      } else if (\n        this._redisClientType === REDIS_V4 ||\n        this._redisClientType === IOREDIS\n      ) {\n        pong = await this.redisClient.ping()\n      } else {\n        return false\n      }\n      return pong === 'PONG'\n    } catch (err) {\n      // Redis not available\n      if (this._redisAvailable) {\n        console.warn(\n          `[HealthCheckCache] Redis became unavailable: ${err.message}`\n        )\n        this._redisAvailable = false\n      }\n      return false\n    }\n  }\n\n  /**\n   * Gets cached health check result from Redis (if available) or in-memory cache.\n   * Throws error if Redis is configured but read fails (so caller can return proper error format).\n   * @returns {Promise<Object | null>} Cached result or null\n   * @throws {Error} If Redis is configured but read fails\n   */\n  async get() {\n    // If Redis is configured, we MUST read from it (don't fall back to memory)\n    if (this.redisClient) {\n      try {\n        let cachedStr\n        if (this._redisClientType === REDIS_V3) {\n          cachedStr = await new Promise((resolve, reject) => {\n            this.redisClient.get(this.cacheKey, (err, result) => {\n              if (err) reject(err)\n              else resolve(result)\n            })\n          })\n        } else if (\n          this._redisClientType === REDIS_V4 ||\n          this._redisClientType === IOREDIS\n        ) {\n          cachedStr = await this.redisClient.get(this.cacheKey)\n        }\n\n        if (cachedStr) {\n          try {\n            const cached = JSON.parse(cachedStr)\n            if (cached.result && cached.timestamp) {\n              const age = Date.now() - cached.timestamp\n              if (age < this.cacheTtlMs) {\n                // Also update in-memory cache as backup\n                this._memoryCache = cached.result\n                this._memoryCacheTimestamp = cached.timestamp\n                return cached.result\n              }\n            }\n          } catch (parseErr) {\n            console.warn(\n              `[HealthCheckCache] Failed to parse Redis cache:`,\n              parseErr.message\n            )\n          }\n        }\n        // No cache in Redis - return null (worker may not have run yet)\n        return null\n      } catch (redisErr) {\n        // Redis read failed - throw error so caller can return proper error format\n        this._redisAvailable = false\n        throw new Error(`Redis cache read failed: ${redisErr.message}`)\n      }\n    }\n\n    // No Redis configured - fall back to in-memory cache\n    if (this._memoryCache && this._memoryCacheTimestamp) {\n      const age = Date.now() - this._memoryCacheTimestamp\n      if (age < this.cacheTtlMs) {\n        return this._memoryCache\n      }\n    }\n\n    return null\n  }\n\n  /**\n   * Sets cached health check result in Redis (if available) and in-memory.\n   * @param {Object} result - Health check result to cache\n   * @returns {Promise<void>}\n   */\n  async set(result) {\n    const cacheData = {\n      result,\n      timestamp: Date.now(),\n    }\n\n    // Update in-memory cache\n    this._memoryCache = result\n    this._memoryCacheTimestamp = cacheData.timestamp\n\n    // Try to update Redis if available\n    if (await this._checkRedisAvailable()) {\n      try {\n        const cacheStr = JSON.stringify(cacheData)\n        const ttlSeconds = Math.ceil(this.cacheTtlMs / 1000) + 10\n\n        if (this._redisClientType === REDIS_V3) {\n          await new Promise((resolve, reject) => {\n            this.redisClient.setex(\n              this.cacheKey,\n              ttlSeconds,\n              cacheStr,\n              (err) => {\n                if (err) reject(err)\n                else resolve()\n              }\n            )\n          })\n        } else if (\n          this._redisClientType === REDIS_V4 ||\n          this._redisClientType === IOREDIS\n        ) {\n          await this.redisClient.setex(this.cacheKey, ttlSeconds, cacheStr)\n        }\n      } catch (redisErr) {\n        // Redis write failed, but in-memory cache is updated\n        console.warn(\n          `[HealthCheckCache] Redis write failed (in-memory cache updated):`,\n          redisErr.message\n        )\n        this._redisAvailable = false\n      }\n    }\n  }\n\n  /**\n   * Clears the cache (both Redis and in-memory).\n   * @returns {Promise<void>}\n   */\n  async clear() {\n    this._memoryCache = null\n    this._memoryCacheTimestamp = null\n\n    if (await this._checkRedisAvailable()) {\n      try {\n        if (this._redisClientType === REDIS_V3) {\n          await new Promise((resolve, reject) => {\n            this.redisClient.del(this.cacheKey, (err) => {\n              if (err) reject(err)\n              else resolve()\n            })\n          })\n        } else if (\n          this._redisClientType === REDIS_V4 ||\n          this._redisClientType === IOREDIS\n        ) {\n          await this.redisClient.del(this.cacheKey)\n        }\n      } catch (redisErr) {\n        console.warn(\n          `[HealthCheckCache] Redis clear failed:`,\n          redisErr.message\n        )\n      }\n    }\n  }\n\n  /**\n   * Checks if Redis is configured and available.\n   * @returns {boolean}\n   */\n  isRedisAvailable() {\n    return this._redisAvailable && this.redisClient !== null\n  }\n}\n\nmodule.exports = { HealthCheckCache }\n\n"],"mappings":";;AAAA,MAAM;EACJA,kBAAkB;EAClBC,QAAQ;EACRC,OAAO;EACPC;AACF,CAAC,GAAGC,OAAO,CAAC,eAAe,CAAC;;AAE5B;AACA;AACA;AACA;AACA;AACA,MAAMC,gBAAgB,CAAC;EACrB;AACF;AACA;AACA;AACA;AACA;EACEC,WAAWA,CAACC,OAAO,GAAG,CAAC,CAAC,EAAE;IACxB,IAAI,CAACC,WAAW,GAAGD,OAAO,CAACC,WAAW,IAAI,IAAI;IAC9C,IAAI,CAACC,OAAO,GAAGF,OAAO,CAACE,OAAO,IAAIC,OAAO,CAACC,GAAG,CAACC,cAAc,IAAI,aAAa;IAC7E,IAAI,CAACC,UAAU,GAAGN,OAAO,CAACM,UAAU,IAAI,EAAE,GAAG,IAAI;IACjD,IAAI,CAACC,QAAQ,GAAG,eAAe,IAAI,CAACL,OAAO,EAAE;;IAE7C;IACA,IAAI,CAACM,YAAY,GAAG,IAAI;IACxB,IAAI,CAACC,qBAAqB,GAAG,IAAI;IAEjC,IAAI,IAAI,CAACR,WAAW,EAAE;MACpB,IAAI,CAACS,gBAAgB,GAAGjB,kBAAkB,CAAC,IAAI,CAACQ,WAAW,CAAC;MAC5D,IAAI,CAACU,eAAe,GAAG,IAAI;IAC7B,CAAC,MAAM;MACL,IAAI,CAACA,eAAe,GAAG,KAAK;MAC5BC,OAAO,CAACC,IAAI,CACV,+CAA+C,IAAI,CAACX,OAAO,4DAC7D,CAAC;IACH;EACF;;EAEA;AACF;AACA;AACA;AACA;EACE,MAAMY,oBAAoBA,CAAA,EAAG;IAC3B,IAAI,CAAC,IAAI,CAACb,WAAW,IAAI,CAAC,IAAI,CAACU,eAAe,EAAE;MAC9C,OAAO,KAAK;IACd;IAEA,IAAI;MACF,IAAII,IAAI;MACR,IAAI,IAAI,CAACL,gBAAgB,KAAKd,QAAQ,EAAE;QACtCmB,IAAI,GAAG,MAAM,IAAIC,OAAO,CAAC,CAACC,OAAO,EAAEC,MAAM,KAAK;UAC5C,IAAI,CAACjB,WAAW,CAACkB,IAAI,CAAC,CAACC,GAAG,EAAEC,MAAM,KAAK;YACrC,IAAID,GAAG,EAAEF,MAAM,CAACE,GAAG,CAAC,MACfH,OAAO,CAACI,MAAM,CAAC;UACtB,CAAC,CAAC;QACJ,CAAC,CAAC;MACJ,CAAC,MAAM,IACL,IAAI,CAACX,gBAAgB,KAAKhB,QAAQ,IAClC,IAAI,CAACgB,gBAAgB,KAAKf,OAAO,EACjC;QACAoB,IAAI,GAAG,MAAM,IAAI,CAACd,WAAW,CAACkB,IAAI,CAAC,CAAC;MACtC,CAAC,MAAM;QACL,OAAO,KAAK;MACd;MACA,OAAOJ,IAAI,KAAK,MAAM;IACxB,CAAC,CAAC,OAAOK,GAAG,EAAE;MACZ;MACA,IAAI,IAAI,CAACT,eAAe,EAAE;QACxBC,OAAO,CAACC,IAAI,CACV,gDAAgDO,GAAG,CAACE,OAAO,EAC7D,CAAC;QACD,IAAI,CAACX,eAAe,GAAG,KAAK;MAC9B;MACA,OAAO,KAAK;IACd;EACF;;EAEA;AACF;AACA;AACA;AACA;AACA;EACE,MAAMY,GAAGA,CAAA,EAAG;IACV;IACA,IAAI,IAAI,CAACtB,WAAW,EAAE;MACpB,IAAI;QACF,IAAIuB,SAAS;QACb,IAAI,IAAI,CAACd,gBAAgB,KAAKd,QAAQ,EAAE;UACtC4B,SAAS,GAAG,MAAM,IAAIR,OAAO,CAAC,CAACC,OAAO,EAAEC,MAAM,KAAK;YACjD,IAAI,CAACjB,WAAW,CAACsB,GAAG,CAAC,IAAI,CAAChB,QAAQ,EAAE,CAACa,GAAG,EAAEC,MAAM,KAAK;cACnD,IAAID,GAAG,EAAEF,MAAM,CAACE,GAAG,CAAC,MACfH,OAAO,CAACI,MAAM,CAAC;YACtB,CAAC,CAAC;UACJ,CAAC,CAAC;QACJ,CAAC,MAAM,IACL,IAAI,CAACX,gBAAgB,KAAKhB,QAAQ,IAClC,IAAI,CAACgB,gBAAgB,KAAKf,OAAO,EACjC;UACA6B,SAAS,GAAG,MAAM,IAAI,CAACvB,WAAW,CAACsB,GAAG,CAAC,IAAI,CAAChB,QAAQ,CAAC;QACvD;QAEA,IAAIiB,SAAS,EAAE;UACb,IAAI;YACF,MAAMC,MAAM,GAAGC,IAAI,CAACC,KAAK,CAACH,SAAS,CAAC;YACpC,IAAIC,MAAM,CAACJ,MAAM,IAAII,MAAM,CAACG,SAAS,EAAE;cACrC,MAAMC,GAAG,GAAGC,IAAI,CAACC,GAAG,CAAC,CAAC,GAAGN,MAAM,CAACG,SAAS;cACzC,IAAIC,GAAG,GAAG,IAAI,CAACvB,UAAU,EAAE;gBACzB;gBACA,IAAI,CAACE,YAAY,GAAGiB,MAAM,CAACJ,MAAM;gBACjC,IAAI,CAACZ,qBAAqB,GAAGgB,MAAM,CAACG,SAAS;gBAC7C,OAAOH,MAAM,CAACJ,MAAM;cACtB;YACF;UACF,CAAC,CAAC,OAAOW,QAAQ,EAAE;YACjBpB,OAAO,CAACC,IAAI,CACV,iDAAiD,EACjDmB,QAAQ,CAACV,OACX,CAAC;UACH;QACF;QACA;QACA,OAAO,IAAI;MACb,CAAC,CAAC,OAAOW,QAAQ,EAAE;QACjB;QACA,IAAI,CAACtB,eAAe,GAAG,KAAK;QAC5B,MAAM,IAAIuB,KAAK,CAAC,4BAA4BD,QAAQ,CAACX,OAAO,EAAE,CAAC;MACjE;IACF;;IAEA;IACA,IAAI,IAAI,CAACd,YAAY,IAAI,IAAI,CAACC,qBAAqB,EAAE;MACnD,MAAMoB,GAAG,GAAGC,IAAI,CAACC,GAAG,CAAC,CAAC,GAAG,IAAI,CAACtB,qBAAqB;MACnD,IAAIoB,GAAG,GAAG,IAAI,CAACvB,UAAU,EAAE;QACzB,OAAO,IAAI,CAACE,YAAY;MAC1B;IACF;IAEA,OAAO,IAAI;EACb;;EAEA;AACF;AACA;AACA;AACA;EACE,MAAM2B,GAAGA,CAACd,MAAM,EAAE;IAChB,MAAMe,SAAS,GAAG;MAChBf,MAAM;MACNO,SAAS,EAAEE,IAAI,CAACC,GAAG,CAAC;IACtB,CAAC;;IAED;IACA,IAAI,CAACvB,YAAY,GAAGa,MAAM;IAC1B,IAAI,CAACZ,qBAAqB,GAAG2B,SAAS,CAACR,SAAS;;IAEhD;IACA,IAAI,MAAM,IAAI,CAACd,oBAAoB,CAAC,CAAC,EAAE;MACrC,IAAI;QACF,MAAMuB,QAAQ,GAAGX,IAAI,CAACY,SAAS,CAACF,SAAS,CAAC;QAC1C,MAAMG,UAAU,GAAGC,IAAI,CAACC,IAAI,CAAC,IAAI,CAACnC,UAAU,GAAG,IAAI,CAAC,GAAG,EAAE;QAEzD,IAAI,IAAI,CAACI,gBAAgB,KAAKd,QAAQ,EAAE;UACtC,MAAM,IAAIoB,OAAO,CAAC,CAACC,OAAO,EAAEC,MAAM,KAAK;YACrC,IAAI,CAACjB,WAAW,CAACyC,KAAK,CACpB,IAAI,CAACnC,QAAQ,EACbgC,UAAU,EACVF,QAAQ,EACPjB,GAAG,IAAK;cACP,IAAIA,GAAG,EAAEF,MAAM,CAACE,GAAG,CAAC,MACfH,OAAO,CAAC,CAAC;YAChB,CACF,CAAC;UACH,CAAC,CAAC;QACJ,CAAC,MAAM,IACL,IAAI,CAACP,gBAAgB,KAAKhB,QAAQ,IAClC,IAAI,CAACgB,gBAAgB,KAAKf,OAAO,EACjC;UACA,MAAM,IAAI,CAACM,WAAW,CAACyC,KAAK,CAAC,IAAI,CAACnC,QAAQ,EAAEgC,UAAU,EAAEF,QAAQ,CAAC;QACnE;MACF,CAAC,CAAC,OAAOJ,QAAQ,EAAE;QACjB;QACArB,OAAO,CAACC,IAAI,CACV,kEAAkE,EAClEoB,QAAQ,CAACX,OACX,CAAC;QACD,IAAI,CAACX,eAAe,GAAG,KAAK;MAC9B;IACF;EACF;;EAEA;AACF;AACA;AACA;EACE,MAAMgC,KAAKA,CAAA,EAAG;IACZ,IAAI,CAACnC,YAAY,GAAG,IAAI;IACxB,IAAI,CAACC,qBAAqB,GAAG,IAAI;IAEjC,IAAI,MAAM,IAAI,CAACK,oBAAoB,CAAC,CAAC,EAAE;MACrC,IAAI;QACF,IAAI,IAAI,CAACJ,gBAAgB,KAAKd,QAAQ,EAAE;UACtC,MAAM,IAAIoB,OAAO,CAAC,CAACC,OAAO,EAAEC,MAAM,KAAK;YACrC,IAAI,CAACjB,WAAW,CAAC2C,GAAG,CAAC,IAAI,CAACrC,QAAQ,EAAGa,GAAG,IAAK;cAC3C,IAAIA,GAAG,EAAEF,MAAM,CAACE,GAAG,CAAC,MACfH,OAAO,CAAC,CAAC;YAChB,CAAC,CAAC;UACJ,CAAC,CAAC;QACJ,CAAC,MAAM,IACL,IAAI,CAACP,gBAAgB,KAAKhB,QAAQ,IAClC,IAAI,CAACgB,gBAAgB,KAAKf,OAAO,EACjC;UACA,MAAM,IAAI,CAACM,WAAW,CAAC2C,GAAG,CAAC,IAAI,CAACrC,QAAQ,CAAC;QAC3C;MACF,CAAC,CAAC,OAAO0B,QAAQ,EAAE;QACjBrB,OAAO,CAACC,IAAI,CACV,wCAAwC,EACxCoB,QAAQ,CAACX,OACX,CAAC;MACH;IACF;EACF;;EAEA;AACF;AACA;AACA;EACEuB,gBAAgBA,CAAA,EAAG;IACjB,OAAO,IAAI,CAAClC,eAAe,IAAI,IAAI,CAACV,WAAW,KAAK,IAAI;EAC1D;AACF;AAEA6C,MAAM,CAACC,OAAO,GAAG;EAAEjD;AAAiB,CAAC","ignoreList":[]}

package/lib/{healthCheckClient.d.ts → health/healthCheckClient.d.ts}

@@ -5,7 +5,11 @@ export type ComponentHealth = {
      */
     status: HealthStatus;
     /**
-     * - Optional status message
+     * - Error message if status is unhealthy
+     */
+    error?: string | undefined;
+    /**
+     * - Optional status message (deprecated, use error)
      */
     message?: string | undefined;
     /**
@@ -35,15 +39,15 @@ export type HealthCheckResult = {
      */
     timestamp: string;
     /**
-     * - Whether this result is from cache
+     * - Individual service health checks
      */
-    cached: boolean;
-    /**
-     * - Individual component health
-     */
-    components: {
+    checks: {
         [x: string]: ComponentHealth | DatabaseClusterHealth;
     };
+    /**
+     * - Top-level error messages (not related to specific services)
+     */
+    errors?: string[] | undefined;
 };
 export type CachedHealthResult = {
     /**
@@ -71,7 +75,8 @@ export type DatabaseConfig = {
 /**
  * @typedef {Object} ComponentHealth
  * @property {HealthStatus} status - Component health status
- * @property {string} [message] - Optional status message
+ * @property {string} [error] - Error message if status is unhealthy
+ * @property {string} [message] - Optional status message (deprecated, use error)
  * @property {number} [latencyMs] - Connection latency in milliseconds
  */
 /**
@@ -83,8 +88,8 @@ export type DatabaseConfig = {
  * @typedef {Object} HealthCheckResult
  * @property {HealthStatus} status - Overall health status
  * @property {string} timestamp - ISO timestamp of the check
- * @property {boolean} cached - Whether this result is from cache
- * @property {Object<string, ComponentHealth | DatabaseClusterHealth>} components - Individual component health
+ * @property {Object<string, ComponentHealth | DatabaseClusterHealth>} checks - Individual service health checks
+ * @property {string[]} [errors] - Top-level error messages (not related to specific services)
  */
 /**
  * @typedef {Object} CachedHealthResult
@@ -114,7 +119,8 @@ export class HealthCheckClient {
      * @param {string} [options.databaseUrl] - Main PostgreSQL connection URL
      * @param {string} [options.databaseName='main'] - Name for the main database
      * @param {Object<string, string>} [options.additionalDatabaseUrls] - Additional DB clusters (name -> URL)
-     * @param {any} [options.redisClient] - Redis client instance (ioredis or node-redis)
+     * @param {any} [options.redisClient] - Redis client instance (ioredis or node-redis) - used for cache
+     * @param {boolean} [options.includeRedisCheck=false] - Include Redis health check in results (for backend)
      * @param {number} [options.cacheTtlMs=60000] - Cache TTL in milliseconds (default: 60s)
      * @param {string} [options.appName] - Application name for logging
      */
@@ -125,20 +131,27 @@ export class HealthCheckClient {
             [x: string]: string;
         } | undefined;
         redisClient?: any;
+        includeRedisCheck?: boolean | undefined;
         cacheTtlMs?: number | undefined;
         appName?: string | undefined;
     });
     redisClient: any;
+    includeRedisCheck: boolean;
     cacheTtlMs: number;
     appName: string;
     prefixLogs: string;
     /** @type {CachedHealthResult | null} */
     _cachedResult: CachedHealthResult | null;
+    /** @type {Promise<HealthCheckResult> | null} */
+    _refreshPromise: Promise<HealthCheckResult> | null;
     /** @type {Map<string, Pool>} */
     _databasePools: Map<string, Pool>;
+    /** @type {DatabaseConfig | null} */
+    _mainDatabaseConfig: DatabaseConfig | null;
     /** @type {DatabaseConfig[]} */
-    _databaseConfigs: DatabaseConfig[];
+    _clusterConfigs: DatabaseConfig[];
     _redisClientType: string | undefined;
+    _cache: HealthCheckCache;
     /**
      * Initialize database configurations from options.
      * @param {Object} options - Constructor options
@@ -166,8 +179,8 @@ export class HealthCheckClient {
      */
     private _checkSingleDatabase;
     /**
-     * Tests all PostgreSQL database clusters in parallel.
-     * @returns {Promise<DatabaseClusterHealth | null>}
+     * Tests all PostgreSQL databases (main + clusters) in parallel.
+     * @returns {Promise<Object | null>} Database health with optional clusters
      * @private
      */
     private _checkAllDatabases;
@@ -180,10 +193,37 @@ export class HealthCheckClient {
     /**
      * Performs a full health check on all configured components.
      * Results are cached for the configured TTL to prevent excessive load.
+     * Uses a mutex pattern to prevent concurrent health checks when cache expires.
+     * If cache is expired but a refresh is in progress, returns stale cache (if available).
      *
      * @returns {Promise<HealthCheckResult>}
      */
     performHealthCheck(): Promise<HealthCheckResult>;
+    /**
+     * Internal method that actually performs the health check.
+     * This is separated to allow the mutex pattern in performHealthCheck.
+     * Only checks database - Redis is used only for cache, not health check.
+     *
+     * @returns {Promise<HealthCheckResult>}
+     * @private
+     */
+    private _performHealthCheckInternal;
+    /**
+     * Gets cached result from shared cache (Redis if available, otherwise in-memory).
+     * Returns null if no cache is available. This is used by endpoints to read-only access.
+     * If Redis fails, returns error result with proper format.
+     *
+     * @returns {Promise<HealthCheckResult | null>} Cached result, error result if Redis fails, or null if not available
+     */
+    getCachedResult(): Promise<HealthCheckResult | null>;
+    /**
+     * Forces a refresh of the health check cache.
+     * This is used by background workers to periodically update the cache.
+     * Updates shared cache (Redis if available, otherwise in-memory).
+     *
+     * @returns {Promise<HealthCheckResult>}
+     */
+    refreshCache(): Promise<HealthCheckResult>;
     /**
      * Clears the cached health check result, forcing the next check to be fresh.
      */
@@ -202,6 +242,9 @@ export class HealthCheckClient {
      * Response includes errors array when status is not healthy.
      * All sensitive data (passwords, connection strings, etc.) is masked.
      *
+     * This handler only reads from cache and never triggers database queries.
+     * Use a background worker to periodically refresh the cache.
+     *
      * @returns {(req: any, res: any) => Promise<void>} Express request handler
      */
     healthHandler(): (req: any, res: any) => Promise<void>;
@@ -209,7 +252,7 @@ export class HealthCheckClient {
      * Register health check endpoint on an Express app.
      *
      * @param {import('express').Application} app - Express application
-     * @param {string} [path='/health'] - Path for the health endpoint
+     * @param {string} [path='/health-status'] - Path for the health endpoint
      */
     registerHealthEndpoint(app: any, path?: string | undefined): void;
     /**
@@ -219,4 +262,5 @@ export class HealthCheckClient {
     cleanup(): Promise<void>;
 }
 import { Pool } from "pg";
+import { HealthCheckCache } from "./healthCheckCache";
 //# sourceMappingURL=healthCheckClient.d.ts.map

package/lib/health/healthCheckClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"healthCheckClient.d.ts","sourceRoot":"","sources":["../../src/health/healthCheckClient.js"],"names":[],"mappings":"2BAiEa,SAAS,GAAG,WAAW,GAAG,UAAU;;;;;YAKnC,YAAY;;;;;;;;;;;;;;;;;;YAQZ,YAAY;;;;;YACL,MAAM,GAAE,eAAe;;;;;;;YAK9B,YAAY;;;;eACZ,MAAM;;;;;YACC,MAAM,GAAE,eAAe,GAAG,qBAAqB;;;;;;;;;;;YAMtD,iBAAiB;;;;eACjB,MAAM;;;;;;UAKN,MAAM;;;;SACN,MAAM;;AAnCpB;;GAEG;AAEH;;;;;;GAMG;AAEH;;;;GAIG;AAEH;;;;;;GAMG;AAEH;;;;GAIG;AAEH;;;;GAIG;AAEH;;;;;;;;;;;GAWG;AACH;IACE;;;;;;;;;OASG;IACH;QAR4B,WAAW;QACX,YAAY;QACI,sBAAsB;;;QACzC,WAAW,GAAzB,GAAG;QACe,iBAAiB;QAClB,UAAU;QACV,OAAO;OAqClC;IAlCC,iBAA8C;IAC9C,2BAA2D;IAC3D,mBAAiE;IACjE,gBACgE;IAEhE,mBAAmD;IAEnD,wCAAwC;IACxC,eADW,kBAAkB,GAAG,IAAI,CACX;IAEzB,gDAAgD;IAChD,iBADW,QAAQ,iBAAiB,CAAC,GAAG,IAAI,CACjB;IAE3B,gCAAgC;IAChC,gBADW,IAAI,MAAM,EAAE,IAAI,CAAC,CACG;IAE/B,oCAAoC;IACpC,qBADW,cAAc,GAAG,IAAI,CACD;IAE/B,+BAA+B;IAC/B,iBADW,cAAc,EAAE,CACF;IAKvB,qCAA4D;IAG9D,yBAIE;IAGJ;;;;OAIG;IACH,uBAcC;IAED;;;;;OAKG;IACH,iBAaC;IAED;;;;OAIG;IACH,sBAGC;IAED;;;;;OAKG;IACH,6BAiBC;IAED;;;;OAIG;IACH,2BAsDC;IAED;;;;OAIG;IACH,oBA6CC;IAED;;;;;;;OAOG;IACH,sBAFa,QAAQ,iBAAiB,CAAC,CAqCtC;IAED;;;;;;;OAOG;IACH,oCAoCC;IAED;;;;;;OAMG;IACH,mBAFa,QAAQ,iBAAiB,GAAG,IAAI,CAAC,CA0B7C;IAED;;;;;;OAMG;IACH,gBAFa,QAAQ,iBAAiB,CAAC,CAOtC;IAED;;OAEG;IACH,mBAGC;IAED;;;;;;OAMG;IACH,0BA8BC;IAED;;;;;;;;;;OAUG;IACH,uBAFmB,GAAG,OAAO,GAAG,KAAK,QAAQ,IAAI,CAAC,CAuDjD;IAED;;;;;OAKG;IACH,kEAGC;IAED;;;OAGG;IACH,WAFa,QAAQ,IAAI,CAAC,CAWzB;CACF"}