@adalo/metrics 0.0.0-staging.1

package/README.md

@@ -0,0 +1,120 @@
+# @adalo/metrics
+Utility library for Prometheus metrics and HTTP request counting in Node.js applications.
+
+## Testing and staging (for contributors)
+
+- **Run tests**: `yarn test` (or `yarn test:watch`). CI runs tests on every pull request.
+- **Test locally in a consuming app** (without publishing):
+  - From this repo: `yarn link`
+  - In the app repo (e.g. backend): `yarn link @adalo/metrics`
+  - Or use a file dependency: `"@adalo/metrics": "file:../path/to/metrics-js"`
+- **Test on staging before merging to main**:
+  - Push your changes to the **`staging`** branch (create it if needed). The **Deploy Staging** workflow will build and publish to npm with the dist-tag **`staging`** (version like `0.0.0-staging.123`).
+  - In the app that uses this library (e.g. backend), point the dependency to the staging build:
+    - In `package.json`: `"@adalo/metrics": "staging"` (resolves to latest `@adalo/metrics@staging`), or pin a specific version: `"@adalo/metrics": "0.0.0-staging.123"`.
+  - Deploy that app to staging and verify metrics/behavior. When satisfied, merge **metrics-js** into **main** and release a normal version; then update the app back to `"@adalo/metrics": "^x.y.z"` or `"latest"`.
+
+## Constructor
+```ts
+new MetricsClient({
+  appName,            // defaults: process.env.BUILD_APP_NAME || 'unknown-app'
+  dynoId,             // defaults: process.env.HOSTNAME || 'unknown-dyno'
+  processType,        // defaults: process.env.BUILD_DYNO_PROCESS_TYPE || 'undefined_build_dyno_type'
+  enabled,            // defaults: process.env.METRICS_ENABLED === 'true'
+  logValues,          // defaults: process.env.METRICS_LOG_VALUES === 'true'
+  pushgatewayUrl,     // defaults: process.env.METRICS_PUSHGATEWAY_URL || ''
+  pushgatewaySecret,  // defaults: process.env.METRICS_PUSHGATEWAY_SECRET || '' (Base64 of user:password)
+  intervalSec,        // defaults: process.env.METRICS_INTERVAL_SEC || 15
+})
+```
+## Example Usage
+```ts
+import { MetricsClient } from '@adalo/metrics-js'
+
+const metrics = new MetricsClient({ appName: 'my-app', enabled: true })
+
+// Express middleware
+app.use(metrics.trackHttpRequestMiddleware)
+
+
+// Start metrics push
+metrics.startPush()
+```
+
+
+## Custom usage
+```ts
+// Create custom gauges and counters
+
+const metrics = new MetricsClient()
+const testGauge = metricsClient.createGauge({
+  name: 'app_test_usage_percent',
+  help: 'Current test usage of the Node.js process in percent',
+  labelNames: metricsClient.withDefaultLabels(['test_result']),
+})
+
+// Push metrics manually
+metricsClient.gatewayPush({ groupings: { process_type: 'web' } })
+
+// Automatically push metrics at intervals (staging: 60s; prod: 900 or 1800 for 15/30 min)
+metricsClient.startPush(15) // interval in seconds
+```
+
+## HealthCheckClient
+
+Provides a health check endpoint for external monitoring services like BetterStack.
+Validates database and Redis connections with rate limiting to prevent excessive load.
+
+```typescript
+import { HealthCheckClient } from '@adalo/metrics'
+import Redis from 'ioredis'
+
+const redisClient = new Redis()
+const healthCheck = new HealthCheckClient({
+  databaseUrl: process.env.DATABASE_URL,
+  databaseName: 'main',
+  additionalDatabaseUrls: {
+    cluster_1: process.env.CLUSTER_1_URL,
+    cluster_2: process.env.CLUSTER_2_URL,
+  },
+  redisClient,
+})
+
+// Register on Express app
+healthCheck.registerHealthEndpoint(app, '/betterstack-health')
+```
+
+Response format (BetterStack compatible):
+```json
+{
+  "status": "healthy",
+  "timestamp": "2026-01-20T12:00:00.000Z",
+  "cached": false,
+  "components": {
+    "database": {
+      "status": "healthy",
+      "clusters": {
+        "main": { "status": "healthy", "connectMs": 5.2 },
+        "cluster_1": { "status": "healthy", "connectMs": 8.1 },
+        "cluster_2": { "status": "healthy", "connectMs": 6.4 }
+      }
+    },
+    "redis": { "status": "healthy" }
+  }
+}
+```
+
+Status codes:
+- `200` - healthy or degraded
+- `503` - unhealthy (at least one component failed)
+
+Environment variables:
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `DATABASE_URL` | Main PostgreSQL connection URL | - |
+
+## Tips
+secret env was created as 
+```js
+Buffer.from(`${username}:${password}`).toString('base64')
+```

package/__tests__/metricsRedisClient.test.js

@@ -0,0 +1,138 @@
+const http = require('http')
+const https = require('https')
+const { RedisMetricsClient } = require('../src/metrics/metricsRedisClient')
+const { IOREDIS } = require('../src/redisUtils')
+
+jest.mock('../src/redisUtils', () => ({
+  ...jest.requireActual('../src/redisUtils'),
+  getRedisClientType: jest.fn(),
+  IOREDIS: 'IOREDIS',
+  REDIS_V3: 'REDIS_V3',
+  REDIS_V4: 'REDIS_V4',
+}))
+
+const { getRedisClientType } = require('../src/redisUtils')
+
+describe('RedisMetricsClient', () => {
+  const originalEnv = process.env
+  let mockRedisClient
+  let mockHttpRequest
+  let mockHttpsRequest
+
+  beforeEach(() => {
+    jest.clearAllMocks()
+    process.env = { ...originalEnv }
+    process.exit = jest.fn()
+
+    mockRedisClient = {
+      publish: jest.fn().mockResolvedValue(1),
+      sendCommand: jest.fn().mockResolvedValue(1),
+      send_command: jest.fn((cmd, args, cb) => (cb ? cb(null, 1) : undefined)),
+      disconnect: jest.fn(),
+      quit: jest.fn().mockResolvedValue(undefined),
+    }
+
+    const createMockRequest = (cb) => {
+      const req = {
+        setHeader: jest.fn(),
+        end: jest.fn(),
+        on: jest.fn(),
+      }
+      setImmediate(() => {
+        const res = { statusCode: 200, on: jest.fn() }
+        if (cb) cb(res)
+      })
+      return req
+    }
+    mockHttpRequest = jest.spyOn(http, 'request').mockImplementation((opts, cb) => {
+      const req = createMockRequest((res) => {
+        if (typeof cb === 'function') cb(res)
+      })
+      return req
+    })
+    mockHttpsRequest = jest.spyOn(https, 'request').mockImplementation((opts, cb) => {
+      const req = createMockRequest((res) => {
+        if (typeof cb === 'function') cb(res)
+      })
+      return req
+    })
+  })
+
+  afterEach(() => {
+    process.env = originalEnv
+    mockHttpRequest.mockRestore()
+    mockHttpsRequest.mockRestore()
+  })
+
+  describe('constructor', () => {
+    it('throws when redisClient is missing', () => {
+      expect(() => new RedisMetricsClient({})).toThrow('RedisMetricsClient requires redisClient')
+      expect(() => new RedisMetricsClient()).toThrow('RedisMetricsClient requires redisClient')
+      expect(() => new RedisMetricsClient({ redisClient: null })).toThrow('RedisMetricsClient requires redisClient')
+    })
+
+    it('accepts redisClient and passes other options via metricsConfig', () => {
+      getRedisClientType.mockReturnValue(IOREDIS)
+      const client = new RedisMetricsClient({
+        redisClient: mockRedisClient,
+        appName: 'my-app',
+        processType: 'web',
+        pushgatewayUrl: 'http://vm:8428/api/v1/import/prometheus',
+      })
+      expect(client.redisClient).toBe(mockRedisClient)
+      expect(client.appName).toBe('my-app')
+      expect(client.processType).toBe('web')
+      expect(client.pushgatewayUrl).toBe('http://vm:8428/api/v1/import/prometheus')
+    })
+
+    it('uses Redis label names without dyno_id (app, process_type only for Redis metrics)', () => {
+      getRedisClientType.mockReturnValue(IOREDIS)
+      const client = new RedisMetricsClient({
+        redisClient: mockRedisClient,
+        appName: 'my-app',
+        processType: 'queue-metrics',
+      })
+      expect(client._redisLabelNames).toEqual(['app', 'process_type'])
+      expect(client.redisConnectionsGauge.labelNames).toContain('app')
+      expect(client.redisConnectionsGauge.labelNames).toContain('process_type')
+      expect(client.redisConnectionsGauge.labelNames).not.toContain('dyno_id')
+    })
+  })
+
+  describe('gateway push (mocked)', () => {
+    it('calls http.request when pushgatewayUrl is set', async () => {
+      getRedisClientType.mockReturnValue(IOREDIS)
+      const client = new RedisMetricsClient({
+        redisClient: mockRedisClient,
+        pushgatewayUrl: 'http://localhost:8428/api/v1/import/prometheus',
+        enabled: true,
+        cleanupExitsProcess: false,
+      })
+      await client.gatewayPush()
+      expect(mockHttpRequest).toHaveBeenCalled()
+      expect(mockHttpRequest.mock.calls[0][0].method).toBe('POST')
+      expect(mockHttpRequest.mock.calls[0][0].path).toContain('import/prometheus')
+    })
+  })
+
+  describe('gateway delete (mocked)', () => {
+    it('calls http.request for delete_series when removeOldMetrics and pushgatewayUrl set', async () => {
+      getRedisClientType.mockReturnValue(IOREDIS)
+      const client = new RedisMetricsClient({
+        redisClient: mockRedisClient,
+        pushgatewayUrl: 'http://localhost:8428/api/v1/import/prometheus',
+        removeOldMetrics: true,
+        enabled: true,
+        appName: 'test-app',
+        dynoId: 'dyno-1',
+        processType: 'web',
+        cleanupExitsProcess: false,
+      })
+      await client.gatewayDelete()
+      expect(mockHttpRequest).toHaveBeenCalled()
+      const call = mockHttpRequest.mock.calls[0][0]
+      expect(call.path).toContain('delete_series')
+      expect(call.path).toContain('match')
+    })
+  })
+})

package/babel.config.js

@@ -0,0 +1,20 @@
+const include = ['./src']
+const ignore = ['./lib']
+
+// This env var is set when running with jest
+if (process.env.NODE_ENV !== 'test') {
+  ignore.push('**/*.test.js', '**/*.test.ts', '**/__tests__/*')
+}
+
+const presets = [
+  [
+    '@babel/preset-env',
+    {
+      targets: { node: '22' },
+      useBuiltIns: 'usage',
+    },
+  ],
+  '@babel/preset-typescript',
+]
+
+module.exports = { include, ignore, presets }

package/lib/health/databaseChecker.d.ts

@@ -0,0 +1,43 @@
+/**
+ * @param {string} url
+ * @returns {string} postgres | mysql
+ */
+export function getDatabaseType(url: string): string;
+/**
+ * @param {string} url
+ * @param {string} [type]
+ * @returns {{ host: string, port: number, user: string, password: string, database: string } | null}
+ */
+export function parseConnectionUrl(url: string, type?: string | undefined): {
+    host: string;
+    port: number;
+    user: string;
+    password: string;
+    database: string;
+} | null;
+/**
+ * @param {string} env
+ * @param {string} url
+ * @param {number} connectionTimeoutMs
+ * @returns {{ pool: any, type: string }}
+ */
+export function createDatabasePool(env: string, url: string, connectionTimeoutMs: number): {
+    pool: any;
+    type: string;
+};
+/**
+ * @param {any} pool
+ * @param {string} type
+ * @returns {Promise<{ connectMs: number }>}
+ */
+export function runHealthCheck(pool: any, type: string): Promise<{
+    connectMs: number;
+}>;
+/**
+ * @param {any} pool
+ * @returns {Promise<void>}
+ */
+export function closePool(pool: any): Promise<void>;
+export const DB_TYPE_POSTGRES: "postgres";
+export const DB_TYPE_MYSQL: "mysql";
+//# sourceMappingURL=databaseChecker.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"databaseChecker.d.ts","sourceRoot":"","sources":["../../src/health/databaseChecker.js"],"names":[],"mappings":"AAqBA;;;GAGG;AACH,qCAHW,MAAM,GACJ,MAAM,CAYlB;AAED;;;;GAIG;AACH,wCAJW,MAAM,8BAEJ;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAiBnG;AAED;;;;;GAKG;AACH,wCALW,MAAM,OACN,MAAM,uBACN,MAAM;UACI,GAAG;UAAQ,MAAM;EA8BrC;AAED;;;;GAIG;AACH,qCAJW,GAAG,QACH,MAAM;eACiB,MAAM;GA8DvC;AAED;;;GAGG;AACH,gCAHW,GAAG,GACD,QAAQ,IAAI,CAAC,CAQzB;AAzKD,0CAAmC;AACnC,oCAA6B"}

package/lib/health/databaseChecker.js

@@ -0,0 +1,189 @@
+"use strict";
+
+const {
+  Pool
+} = require('pg');
+const mysql = require('mysql2/promise');
+const DB_TYPE_POSTGRES = 'postgres';
+const DB_TYPE_MYSQL = 'mysql';
+
+/**
+ * @returns {bigint}
+ */
+function nowNs() {
+  return process.hrtime.bigint();
+}
+
+/**
+ * @param {bigint} deltaNs
+ * @returns {number}
+ */
+function nsToMs(deltaNs) {
+  return Number(deltaNs) / 1_000_000;
+}
+
+/**
+ * @param {string} url
+ * @returns {string} postgres | mysql
+ */
+function getDatabaseType(url) {
+  if (!url || typeof url !== 'string') return DB_TYPE_POSTGRES;
+  const lower = url.toLowerCase();
+  if (lower.startsWith('mysql://') || lower.startsWith('mysql2://')) {
+    return DB_TYPE_MYSQL;
+  }
+  if (lower.startsWith('mariadb://')) {
+    return DB_TYPE_MYSQL;
+  }
+  return DB_TYPE_POSTGRES;
+}
+
+/**
+ * @param {string} url
+ * @param {string} [type]
+ * @returns {{ host: string, port: number, user: string, password: string, database: string } | null}
+ */
+function parseConnectionUrl(url, type) {
+  try {
+    const parsed = new URL(url);
+    const defaultPort = type === DB_TYPE_MYSQL ? 3306 : 5432;
+    const defaultDb = type === DB_TYPE_MYSQL ? 'mysql' : 'postgres';
+    return {
+      host: parsed.hostname || 'localhost',
+      port: parseInt(parsed.port || String(defaultPort), 10),
+      user: parsed.username || '',
+      password: parsed.password || '',
+      database: (parsed.pathname || '/').replace(/^\//, '') || defaultDb
+    };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * @param {string} env
+ * @param {string} url
+ * @param {number} connectionTimeoutMs
+ * @returns {{ pool: any, type: string }}
+ */
+function createDatabasePool(env, url, connectionTimeoutMs) {
+  const type = getDatabaseType(url);
+  if (type === DB_TYPE_MYSQL) {
+    const config = parseConnectionUrl(url, DB_TYPE_MYSQL);
+    if (!config) {
+      throw new Error(`Invalid MySQL URL for ${env}`);
+    }
+    const pool = mysql.createPool({
+      host: config.host,
+      port: config.port,
+      user: config.user,
+      password: config.password,
+      database: config.database,
+      connectionLimit: 1,
+      connectTimeout: connectionTimeoutMs,
+      waitForConnections: false
+    });
+    return {
+      pool,
+      type: DB_TYPE_MYSQL
+    };
+  }
+  const pool = new Pool({
+    connectionString: url,
+    max: 1,
+    idleTimeoutMillis: 30000,
+    connectionTimeoutMillis: connectionTimeoutMs
+  });
+  return {
+    pool,
+    type: DB_TYPE_POSTGRES
+  };
+}
+
+/**
+ * @param {any} pool
+ * @param {string} type
+ * @returns {Promise<{ connectMs: number }>}
+ */
+async function runHealthCheck(pool, type) {
+  if (type === DB_TYPE_MYSQL) {
+    let connectMs = 0.0;
+
+    /** @type {any} */
+    let conn;
+    try {
+      const startConnect = nowNs();
+      conn = await pool.getConnection();
+      connectMs = nsToMs(nowNs() - startConnect);
+      await conn.query('SELECT 1');
+      return {
+        connectMs
+      };
+    } catch (err) {
+      err.healthCheckTimings = {
+        connectMs
+      };
+      throw err;
+    } finally {
+      if (conn) {
+        try {
+          // Destroy the connection so next check measures a real connect.
+          // mysql2 pooled connections support destroy() to remove it from the pool.
+          if (typeof conn.destroy === 'function') conn.destroy();else if (typeof conn.end === 'function') await conn.end();else if (typeof conn.release === 'function') conn.release();
+        } catch {
+          // ignore
+        }
+      }
+    }
+  }
+  let connectMs = 0.0;
+
+  /** @type {import('pg').PoolClient | null} */
+  let client = null;
+  try {
+    const startConnect = nowNs();
+    client = await pool.connect();
+    connectMs = nsToMs(nowNs() - startConnect);
+    await client.query('SELECT 1');
+    return {
+      connectMs
+    };
+  } catch (err) {
+    err.healthCheckTimings = {
+      connectMs
+    };
+    throw err;
+  } finally {
+    if (client) {
+      try {
+        // Force the pool to drop the client so next check measures a real connect.
+        // In node-postgres, passing a truthy value removes the client from the pool.
+        client.release(true);
+      } catch {
+        // ignore
+      }
+    }
+  }
+}
+
+/**
+ * @param {any} pool
+ * @returns {Promise<void>}
+ */
+async function closePool(pool) {
+  try {
+    await pool.end();
+  } catch {
+    // ignore
+  }
+}
+module.exports = {
+  getDatabaseType,
+  parseConnectionUrl,
+  createDatabasePool,
+  runHealthCheck,
+  closePool,
+  DB_TYPE_POSTGRES,
+  DB_TYPE_MYSQL
+};
+//# sourceMappingURL=databaseChecker.js.map

package/lib/health/databaseChecker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"databaseChecker.js","names":["Pool","require","mysql","DB_TYPE_POSTGRES","DB_TYPE_MYSQL","nowNs","process","hrtime","bigint","nsToMs","deltaNs","Number","getDatabaseType","url","lower","toLowerCase","startsWith","parseConnectionUrl","type","parsed","URL","defaultPort","defaultDb","host","hostname","port","parseInt","String","user","username","password","database","pathname","replace","createDatabasePool","env","connectionTimeoutMs","config","Error","pool","createPool","connectionLimit","connectTimeout","waitForConnections","connectionString","max","idleTimeoutMillis","connectionTimeoutMillis","runHealthCheck","connectMs","conn","startConnect","getConnection","query","err","healthCheckTimings","destroy","end","release","client","connect","closePool","module","exports"],"sources":["../../src/health/databaseChecker.js"],"sourcesContent":["const { Pool } = require('pg')\nconst mysql = require('mysql2/promise')\n\nconst DB_TYPE_POSTGRES = 'postgres'\nconst DB_TYPE_MYSQL = 'mysql'\n\n/**\n * @returns {bigint}\n */\nfunction nowNs() {\n  return process.hrtime.bigint()\n}\n\n/**\n * @param {bigint} deltaNs\n * @returns {number}\n */\nfunction nsToMs(deltaNs) {\n  return Number(deltaNs) / 1_000_000\n}\n\n/**\n * @param {string} url\n * @returns {string} postgres | mysql\n */\nfunction getDatabaseType(url) {\n  if (!url || typeof url !== 'string') return DB_TYPE_POSTGRES\n  const lower = url.toLowerCase()\n  if (lower.startsWith('mysql://') || lower.startsWith('mysql2://')) {\n    return DB_TYPE_MYSQL\n  }\n  if (lower.startsWith('mariadb://')) {\n    return DB_TYPE_MYSQL\n  }\n  return DB_TYPE_POSTGRES\n}\n\n/**\n * @param {string} url\n * @param {string} [type]\n * @returns {{ host: string, port: number, user: string, password: string, database: string } | null}\n */\nfunction parseConnectionUrl(url, type) {\n  try {\n    const parsed = new URL(url)\n    const defaultPort = type === DB_TYPE_MYSQL ? 3306 : 5432\n    const defaultDb = type === DB_TYPE_MYSQL ? 'mysql' : 'postgres'\n    return {\n      host: parsed.hostname || 'localhost',\n      port: parseInt(parsed.port || String(defaultPort), 10),\n      user: parsed.username || '',\n      password: parsed.password || '',\n      database: (parsed.pathname || '/').replace(/^\\//, '') || defaultDb,\n    }\n  } catch {\n    return null\n  }\n}\n\n/**\n * @param {string} env\n * @param {string} url\n * @param {number} connectionTimeoutMs\n * @returns {{ pool: any, type: string }}\n */\nfunction createDatabasePool(env, url, connectionTimeoutMs) {\n  const type = getDatabaseType(url)\n\n  if (type === DB_TYPE_MYSQL) {\n    const config = parseConnectionUrl(url, DB_TYPE_MYSQL)\n    if (!config) {\n      throw new Error(`Invalid MySQL URL for ${env}`)\n    }\n    const pool = mysql.createPool({\n      host: config.host,\n      port: config.port,\n      user: config.user,\n      password: config.password,\n      database: config.database,\n      connectionLimit: 1,\n      connectTimeout: connectionTimeoutMs,\n      waitForConnections: false,\n    })\n    return { pool, type: DB_TYPE_MYSQL }\n  }\n\n  const pool = new Pool({\n    connectionString: url,\n    max: 1,\n    idleTimeoutMillis: 30000,\n    connectionTimeoutMillis: connectionTimeoutMs,\n  })\n  return { pool, type: DB_TYPE_POSTGRES }\n}\n\n/**\n * @param {any} pool\n * @param {string} type\n * @returns {Promise<{ connectMs: number }>}\n */\nasync function runHealthCheck(pool, type) {\n  if (type === DB_TYPE_MYSQL) {\n    let connectMs = 0.0\n\n    /** @type {any} */\n    let conn\n    try {\n      const startConnect = nowNs()\n      conn = await pool.getConnection()\n      connectMs = nsToMs(nowNs() - startConnect)\n\n      await conn.query('SELECT 1')\n      return { connectMs }\n    } catch (err) {\n      err.healthCheckTimings = {\n        connectMs,\n      }\n      throw err\n    } finally {\n      if (conn) {\n        try {\n          // Destroy the connection so next check measures a real connect.\n          // mysql2 pooled connections support destroy() to remove it from the pool.\n          if (typeof conn.destroy === 'function') conn.destroy()\n          else if (typeof conn.end === 'function') await conn.end()\n          else if (typeof conn.release === 'function') conn.release()\n        } catch {\n          // ignore\n        }\n      }\n    }\n  }\n\n  let connectMs = 0.0\n\n  /** @type {import('pg').PoolClient | null} */\n  let client = null\n  try {\n    const startConnect = nowNs()\n    client = await pool.connect()\n    connectMs = nsToMs(nowNs() - startConnect)\n\n    await client.query('SELECT 1')\n    return { connectMs }\n  } catch (err) {\n    err.healthCheckTimings = {\n      connectMs,\n    }\n    throw err\n  } finally {\n    if (client) {\n      try {\n        // Force the pool to drop the client so next check measures a real connect.\n        // In node-postgres, passing a truthy value removes the client from the pool.\n        client.release(true)\n      } catch {\n        // ignore\n      }\n    }\n  }\n}\n\n/**\n * @param {any} pool\n * @returns {Promise<void>}\n */\nasync function closePool(pool) {\n  try {\n    await pool.end()\n  } catch {\n    // ignore\n  }\n}\n\nmodule.exports = {\n  getDatabaseType,\n  parseConnectionUrl,\n  createDatabasePool,\n  runHealthCheck,\n  closePool,\n  DB_TYPE_POSTGRES,\n  DB_TYPE_MYSQL,\n}\n"],"mappings":"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","ignoreList":[]}

package/lib/health/healthCheckCache.d.ts

@@ -0,0 +1,59 @@
+/**
+ * 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]
+     * @param {string} [options.cacheKey] - Redis key (e.g. 'health:database:status')
+     * @param {string} [options.appName] - Used when cacheKey not set: healthcheck:${appName}
+     * @param {number} [options.staleThresholdMs]
+     */
+    constructor(options?: {
+        redisClient?: any;
+        cacheKey?: string | undefined;
+        appName?: string | undefined;
+        staleThresholdMs?: number | undefined;
+    });
+    redisClient: any;
+    appName: string;
+    staleThresholdMs: 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;;;;;;OAMG;IACH;QALyB,WAAW,GAAzB,GAAG;QACc,QAAQ;QACR,OAAO;QACP,gBAAgB;OAsB3C;IAnBC,iBAA8C;IAC9C,gBACgE;IAChE,yBAA2D;IAC3D,iBAAiE;IAEjE,+BAA+B;IAC/B,kBAAwB;IACxB,2BAAiC;IAG/B,qCAA4D;IAC5D,yBAA2B;IAS/B;;;;OAIG;IACH,6BAgCC;IAED;;;;;OAKG;IACH,OAHa,QAAQ,MAAM,GAAG,IAAI,CAAC,CAgDlC;IAED;;;;OAIG;IACH,YAHW,MAAM,GACJ,QAAQ,IAAI,CAAC,CAsCzB;IAED;;;OAGG;IACH,SAFa,QAAQ,IAAI,CAAC,CAyBzB;IAED;;;OAGG;IACH,oBAFa,OAAO,CAInB;CACF"}