@pawells/nestjs-shared 1.0.0-dev.4c8c698

package/build/common/services/metrics-registry.service.js

@@ -0,0 +1,262 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var MetricsRegistryService_1;
+import { Injectable } from '@nestjs/common';
+import { ModuleRef } from '@nestjs/core';
+import { Registry, collectDefaultMetrics, Histogram, Counter, Gauge } from 'prom-client';
+import { HTTP_DURATION_BUCKETS, HTTP_REQUEST_SIZE_BUCKETS, MILLISECONDS_TO_SECONDS, } from '../constants/histogram-buckets.constants.js';
+import { AppLogger } from './logger.service.js';
+import { getErrorMessage } from '../utils/error.utils.js';
+const HTTP_STATUS_CODE_500 = 500;
+const HTTP_STATUS_CODE_400 = 400;
+/**
+ * Metrics Registry Service.
+ * Centralized service for managing Prometheus metrics across the application.
+ *
+ * Features:
+ * - HTTP request metrics (duration, count, size)
+ * - Custom metric creation (counter, gauge, histogram)
+ * - Default Node.js metrics collection
+ * - Prometheus registry management
+ * - Per-route metric cardinality prevention
+ *
+ * @remarks
+ * - Controlled by METRICS_ENABLED environment variable (default: true)
+ * - Automatically collects Node.js default metrics
+ * - HTTP request metrics use normalized route paths to prevent unbounded label cardinality
+ *
+ * @example
+ * ```typescript
+ * // Record HTTP request
+ * metricsService.recordHttpRequest('GET', '/users/:id', 200, 45, 2048);
+ *
+ * // Create custom metric
+ * const customCounter = metricsService.createCounter('orders_total', 'Total orders processed');
+ * customCounter.inc({ status: 'completed' });
+ *
+ * // Get metrics in Prometheus format
+ * const metrics = await metricsService.getMetrics();
+ * ```
+ */
+let MetricsRegistryService = MetricsRegistryService_1 = class MetricsRegistryService {
+    _contextualLogger;
+    registry;
+    enabled;
+    // HTTP Request Metrics
+    httpRequestDuration = null;
+    httpRequestTotal = null;
+    httpRequestSize = null;
+    Module;
+    constructor(module) {
+        this.Module = module;
+        this.registry = new Registry();
+        this.enabled = process.env['METRICS_ENABLED'] !== 'false';
+        if (this.enabled) {
+            // Collect default Node.js metrics
+            collectDefaultMetrics({ register: this.registry });
+            // HTTP Request Duration Histogram
+            this.httpRequestDuration = new Histogram({
+                name: 'http_request_duration_seconds',
+                help: 'Duration of HTTP requests in seconds',
+                labelNames: ['method', 'route', 'status_code', 'status_class'],
+                buckets: HTTP_DURATION_BUCKETS,
+                registers: [this.registry],
+            });
+            // HTTP Request Total Counter
+            this.httpRequestTotal = new Counter({
+                name: 'http_requests_total',
+                help: 'Total number of HTTP requests',
+                labelNames: ['method', 'route', 'status_code', 'status_class'],
+                registers: [this.registry],
+            });
+            // HTTP Request Size Histogram
+            this.httpRequestSize = new Histogram({
+                name: 'http_request_size_bytes',
+                help: 'Size of HTTP requests in bytes',
+                labelNames: ['method', 'route'],
+                buckets: HTTP_REQUEST_SIZE_BUCKETS,
+                registers: [this.registry],
+            });
+        }
+    }
+    onModuleInit() {
+        if (!this.enabled) {
+            this.Logger.info('Prometheus metrics disabled');
+        }
+        else {
+            this.Logger.info('MetricsRegistryService initialized with HTTP metrics');
+        }
+    }
+    /**
+     * Get contextual logger for metrics registry
+     * Memoized for performance
+     */
+    get Logger() {
+        this._contextualLogger ??= this.Module.get(AppLogger).createContextualLogger(MetricsRegistryService_1.name);
+        return this._contextualLogger;
+    }
+    /**
+     * Get the Prometheus registry
+     */
+    getRegistry() {
+        return this.registry;
+    }
+    /**
+     * Record HTTP request metrics
+     */
+    recordHttpRequest(method, route, statusCode, duration, size) {
+        if (!this.enabled || !this.httpRequestDuration || !this.httpRequestTotal)
+            return;
+        const statusClass = statusCode >= HTTP_STATUS_CODE_500 ? '5xx' : statusCode >= HTTP_STATUS_CODE_400 ? '4xx' : '2xx';
+        const labels = { method, route, status_code: statusCode.toString(), status_class: statusClass };
+        this.httpRequestDuration.observe(labels, duration / MILLISECONDS_TO_SECONDS); // Convert to seconds
+        this.httpRequestTotal.inc(labels);
+        if (size !== undefined && this.httpRequestSize) {
+            this.httpRequestSize.observe({ method, route }, size);
+        }
+    }
+    /**
+     * Record a counter metric
+     */
+    recordCounter(name, value = 1, labels = {}) {
+        if (!this.enabled)
+            return;
+        try {
+            const counter = this.registry.getSingleMetric(name);
+            if (counter) {
+                counter.inc(labels, value);
+            }
+            else {
+                this.Logger.warn(`Counter metric '${name}' not found in registry`);
+            }
+        }
+        catch (error) {
+            const errorMsg = getErrorMessage(error);
+            this.Logger.error(`Failed to record counter '${name}': ${errorMsg}`);
+        }
+    }
+    /**
+     * Record a gauge metric
+     */
+    recordGauge(name, value, labels = {}) {
+        if (!this.enabled)
+            return;
+        try {
+            const gauge = this.registry.getSingleMetric(name);
+            if (gauge) {
+                gauge.set(labels, value);
+            }
+            else {
+                this.Logger.warn(`Gauge metric '${name}' not found in registry`);
+            }
+        }
+        catch (error) {
+            this.Logger.error(`Failed to record gauge '${name}': ${getErrorMessage(error)}`);
+        }
+    }
+    /**
+     * Record a histogram observation
+     */
+    recordHistogram(name, value, labels = {}) {
+        if (!this.enabled)
+            return;
+        try {
+            const histogram = this.registry.getSingleMetric(name);
+            if (histogram) {
+                histogram.observe(labels, value);
+            }
+            else {
+                this.Logger.warn(`Histogram metric '${name}' not found in registry`);
+            }
+        }
+        catch (error) {
+            this.Logger.error(`Failed to record histogram '${name}': ${getErrorMessage(error)}`);
+        }
+    }
+    /**
+     * Create and register a new counter metric
+     */
+    createCounter(name, help, labelNames = []) {
+        const counter = new Counter({
+            name,
+            help,
+            labelNames,
+            registers: [this.registry],
+        });
+        this.Logger.info(`Created counter metric: ${name}`);
+        return counter;
+    }
+    /**
+     * Create and register a new gauge metric
+     */
+    createGauge(name, help, labelNames = []) {
+        const gauge = new Gauge({
+            name,
+            help,
+            labelNames,
+            registers: [this.registry],
+        });
+        this.Logger.info(`Created gauge metric: ${name}`);
+        return gauge;
+    }
+    /**
+     * Create and register a new histogram metric
+     */
+    createHistogram(name, help, labelNames = [], buckets) {
+        const config = {
+            name,
+            help,
+            labelNames,
+            registers: [this.registry],
+        };
+        if (buckets !== undefined) {
+            config.buckets = buckets;
+        }
+        const histogram = new Histogram(config);
+        this.Logger.info(`Created histogram metric: ${name}`);
+        return histogram;
+    }
+    /**
+     * Register a custom metric
+     */
+    registerMetric(metric) {
+        if (metric && typeof metric === 'object' && 'register' in metric && typeof metric.register === 'function') {
+            metric.register(this.registry);
+        }
+        return metric;
+    }
+    /**
+     * Get metrics in Prometheus format
+     */
+    // eslint-disable-next-line require-await
+    async getMetrics() {
+        return this.registry.metrics();
+    }
+    /**
+     * Get registry metrics as JSON for debugging
+     */
+    // eslint-disable-next-line require-await
+    async getMetricsAsJSON() {
+        return this.registry.getMetricsAsJSON();
+    }
+    /**
+     * Clear all metrics (useful for testing)
+     */
+    clear() {
+        this.registry.clear();
+        this.Logger.warn('All metrics cleared');
+    }
+};
+MetricsRegistryService = MetricsRegistryService_1 = __decorate([
+    Injectable(),
+    __metadata("design:paramtypes", [ModuleRef])
+], MetricsRegistryService);
+export { MetricsRegistryService };
+//# sourceMappingURL=metrics-registry.service.js.map

package/build/common/services/metrics-registry.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics-registry.service.js","sourceRoot":"","sources":["../../../src/common/services/metrics-registry.service.ts"],"names":[],"mappings":"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"}

package/build/common/services/nest-logger-adapter.service.d.ts

@@ -0,0 +1,62 @@
+import { LoggerService } from '@nestjs/common';
+import { AppLogger } from './logger.service.js';
+/**
+ * Adapts {@link AppLogger} to the NestJS {@link LoggerService} interface.
+ *
+ * Pass an instance to `NestFactory.create()` via the `logger` option to route
+ * all framework bootstrap and lifecycle logs through `AppLogger`, eliminating
+ * the default `[Nest]` format and producing a single, consistent log format.
+ *
+ * @example
+ * ```ts
+ * const app = await NestFactory.create(AppModule, {
+ *   logger: new NestLoggerAdapter(),
+ * });
+ * ```
+ */
+export declare class NestLoggerAdapter implements LoggerService {
+    private readonly logger;
+    /**
+     * @param logger - Optional existing `AppLogger` instance to delegate to.
+     *   When omitted, a new `AppLogger` is created using environment variables
+     *   (`SERVICE_NAME`, `LOG_LEVEL`, `LOG_FORMAT`).
+     */
+    constructor(logger?: AppLogger);
+    /** Maps NestJS `log()` (INFO level) to {@link AppLogger.info}. */
+    log(message: any, ...optionalParams: any[]): void;
+    /**
+     * Maps NestJS `error()` to {@link AppLogger.error}.
+     *
+     * NestJS calls this as `error(message, stack?, context?)`.
+     * When a stack trace is present it is forwarded as `metadata.stack`.
+     */
+    error(message: any, ...optionalParams: any[]): void;
+    /** Maps NestJS `warn()` to {@link AppLogger.warn}. */
+    warn(message: any, ...optionalParams: any[]): void;
+    /** Maps NestJS `debug()` to {@link AppLogger.debug}. */
+    debug(message: any, ...optionalParams: any[]): void;
+    /**
+     * Maps NestJS `verbose()` to {@link AppLogger.debug}.
+     * `AppLogger` has no `verbose` level; `debug` is the nearest equivalent.
+     */
+    verbose(message: any, ...optionalParams: any[]): void;
+    /** Maps NestJS `fatal()` to {@link AppLogger.fatal}. */
+    fatal(message: any, ...optionalParams: any[]): void;
+    /**
+     * Extracts the NestJS context string (e.g. `"NestFactory"`, `"RouterExplorer"`)
+     * from variadic params. NestJS passes context as the last string argument.
+     */
+    private extractContext;
+    /**
+     * Extracts `stack` and `context` from variadic error params.
+     *
+     * NestJS error signature: `error(message, stack?, context?)` where `stack`
+     * is a multiline string (contains `\n`) or begins with `"Error:"`.
+     */
+    private extractErrorParams;
+    /** Returns `true` if the string looks like a stack trace. */
+    private looksLikeStack;
+    /** Coerces any log message type to a string. */
+    private formatMessage;
+}
+//# sourceMappingURL=nest-logger-adapter.service.d.ts.map

package/build/common/services/nest-logger-adapter.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nest-logger-adapter.service.d.ts","sourceRoot":"","sources":["../../../src/common/services/nest-logger-adapter.service.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAEhD;;;;;;;;;;;;;GAaG;AACH,qBAAa,iBAAkB,YAAW,aAAa;IACtD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAY;IAEnC;;;;OAIG;gBACS,MAAM,CAAC,EAAE,SAAS;IAI9B,kEAAkE;IAC3D,GAAG,CAAC,OAAO,EAAE,GAAG,EAAE,GAAG,cAAc,EAAE,GAAG,EAAE,GAAG,IAAI;IAKxD;;;;;OAKG;IACI,KAAK,CAAC,OAAO,EAAE,GAAG,EAAE,GAAG,cAAc,EAAE,GAAG,EAAE,GAAG,IAAI;IAU1D,sDAAsD;IAC/C,IAAI,CAAC,OAAO,EAAE,GAAG,EAAE,GAAG,cAAc,EAAE,GAAG,EAAE,GAAG,IAAI;IAKzD,wDAAwD;IACjD,KAAK,CAAC,OAAO,EAAE,GAAG,EAAE,GAAG,cAAc,EAAE,GAAG,EAAE,GAAG,IAAI;IAK1D;;;OAGG;IACI,OAAO,CAAC,OAAO,EAAE,GAAG,EAAE,GAAG,cAAc,EAAE,GAAG,EAAE,GAAG,IAAI;IAK5D,wDAAwD;IACjD,KAAK,CAAC,OAAO,EAAE,GAAG,EAAE,GAAG,cAAc,EAAE,GAAG,EAAE,GAAG,IAAI;IAK1D;;;OAGG;IACH,OAAO,CAAC,cAAc;IAMtB;;;;;OAKG;IACH,OAAO,CAAC,kBAAkB;IAuB1B,6DAA6D;IAC7D,OAAO,CAAC,cAAc;IAItB,gDAAgD;IAChD,OAAO,CAAC,aAAa;CAKrB"}

package/build/common/services/nest-logger-adapter.service.js

@@ -0,0 +1,120 @@
+import { AppLogger } from './logger.service.js';
+/**
+ * Adapts {@link AppLogger} to the NestJS {@link LoggerService} interface.
+ *
+ * Pass an instance to `NestFactory.create()` via the `logger` option to route
+ * all framework bootstrap and lifecycle logs through `AppLogger`, eliminating
+ * the default `[Nest]` format and producing a single, consistent log format.
+ *
+ * @example
+ * ```ts
+ * const app = await NestFactory.create(AppModule, {
+ *   logger: new NestLoggerAdapter(),
+ * });
+ * ```
+ */
+export class NestLoggerAdapter {
+    logger;
+    /**
+     * @param logger - Optional existing `AppLogger` instance to delegate to.
+     *   When omitted, a new `AppLogger` is created using environment variables
+     *   (`SERVICE_NAME`, `LOG_LEVEL`, `LOG_FORMAT`).
+     */
+    constructor(logger) {
+        this.logger = logger ?? new AppLogger();
+    }
+    /** Maps NestJS `log()` (INFO level) to {@link AppLogger.info}. */
+    log(message, ...optionalParams) {
+        const context = this.extractContext(optionalParams);
+        this.logger.info(this.formatMessage(message), context);
+    }
+    /**
+     * Maps NestJS `error()` to {@link AppLogger.error}.
+     *
+     * NestJS calls this as `error(message, stack?, context?)`.
+     * When a stack trace is present it is forwarded as `metadata.stack`.
+     */
+    error(message, ...optionalParams) {
+        const { context, stack } = this.extractErrorParams(optionalParams);
+        const msg = this.formatMessage(message);
+        if (stack !== undefined) {
+            this.logger.error(msg, context, { stack });
+        }
+        else {
+            this.logger.error(msg, context);
+        }
+    }
+    /** Maps NestJS `warn()` to {@link AppLogger.warn}. */
+    warn(message, ...optionalParams) {
+        const context = this.extractContext(optionalParams);
+        this.logger.warn(this.formatMessage(message), context);
+    }
+    /** Maps NestJS `debug()` to {@link AppLogger.debug}. */
+    debug(message, ...optionalParams) {
+        const context = this.extractContext(optionalParams);
+        this.logger.debug(this.formatMessage(message), context);
+    }
+    /**
+     * Maps NestJS `verbose()` to {@link AppLogger.debug}.
+     * `AppLogger` has no `verbose` level; `debug` is the nearest equivalent.
+     */
+    verbose(message, ...optionalParams) {
+        const context = this.extractContext(optionalParams);
+        this.logger.debug(this.formatMessage(message), context);
+    }
+    /** Maps NestJS `fatal()` to {@link AppLogger.fatal}. */
+    fatal(message, ...optionalParams) {
+        const context = this.extractContext(optionalParams);
+        this.logger.fatal(this.formatMessage(message), context);
+    }
+    /**
+     * Extracts the NestJS context string (e.g. `"NestFactory"`, `"RouterExplorer"`)
+     * from variadic params. NestJS passes context as the last string argument.
+     */
+    extractContext(params) {
+        if (params.length === 0)
+            return undefined;
+        const last = params[params.length - 1];
+        return typeof last === 'string' ? last : undefined;
+    }
+    /**
+     * Extracts `stack` and `context` from variadic error params.
+     *
+     * NestJS error signature: `error(message, stack?, context?)` where `stack`
+     * is a multiline string (contains `\n`) or begins with `"Error:"`.
+     */
+    extractErrorParams(params) {
+        if (params.length === 0)
+            return {};
+        if (params.length === 1) {
+            const [param] = params;
+            if (typeof param !== 'string')
+                return {};
+            return this.looksLikeStack(param) ? { stack: param } : { context: param };
+        }
+        const [first, ...rest] = params;
+        if (typeof first === 'string' && this.looksLikeStack(first)) {
+            const contextParam = rest[rest.length - 1];
+            return {
+                stack: first,
+                context: typeof contextParam === 'string' ? contextParam : undefined,
+            };
+        }
+        // No stack — treat last string param as context
+        const last = params[params.length - 1];
+        return { context: typeof last === 'string' ? last : undefined };
+    }
+    /** Returns `true` if the string looks like a stack trace. */
+    looksLikeStack(value) {
+        return value.includes('\n') || value.startsWith('Error:');
+    }
+    /** Coerces any log message type to a string. */
+    formatMessage(message) {
+        if (message instanceof Error)
+            return message.message;
+        if (typeof message === 'string')
+            return message;
+        return String(message);
+    }
+}
+//# sourceMappingURL=nest-logger-adapter.service.js.map

package/build/common/services/nest-logger-adapter.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nest-logger-adapter.service.js","sourceRoot":"","sources":["../../../src/common/services/nest-logger-adapter.service.ts"],"names":[],"mappings":"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"}

package/build/common/utils/error.utils.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Extracts a string representation of an error suitable for use as a log
+ * stack-trace argument. Returns the stack trace when available, falls back to
+ * the error message, and stringifies any non-Error thrown value.
+ *
+ * @param error Any caught value (ideally an Error, but can be anything)
+ */
+export declare function getErrorStack(error: unknown): string;
+/**
+ * Extracts the human-readable message from a caught value.
+ * Returns `error.message` for Error instances and stringifies anything else.
+ *
+ * @param error Any caught value (ideally an Error, but can be anything)
+ */
+export declare function getErrorMessage(error: unknown): string;
+//# sourceMappingURL=error.utils.d.ts.map

package/build/common/utils/error.utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error.utils.d.ts","sourceRoot":"","sources":["../../../src/common/utils/error.utils.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAKpD;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAKtD"}

package/build/common/utils/error.utils.js

@@ -0,0 +1,26 @@
+/**
+ * Extracts a string representation of an error suitable for use as a log
+ * stack-trace argument. Returns the stack trace when available, falls back to
+ * the error message, and stringifies any non-Error thrown value.
+ *
+ * @param error Any caught value (ideally an Error, but can be anything)
+ */
+export function getErrorStack(error) {
+    if (error instanceof Error) {
+        return error.stack ?? error.message;
+    }
+    return String(error);
+}
+/**
+ * Extracts the human-readable message from a caught value.
+ * Returns `error.message` for Error instances and stringifies anything else.
+ *
+ * @param error Any caught value (ideally an Error, but can be anything)
+ */
+export function getErrorMessage(error) {
+    if (error instanceof Error) {
+        return error.message;
+    }
+    return String(error);
+}
+//# sourceMappingURL=error.utils.js.map

package/build/common/utils/error.utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error.utils.js","sourceRoot":"","sources":["../../../src/common/utils/error.utils.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAAC,KAAc;IAC3C,IAAI,KAAK,YAAY,KAAK,EAAE,CAAC;QAC5B,OAAO,KAAK,CAAC,KAAK,IAAI,KAAK,CAAC,OAAO,CAAC;IACrC,CAAC;IACD,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;AACtB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,KAAc;IAC7C,IAAI,KAAK,YAAY,KAAK,EAAE,CAAC;QAC5B,OAAO,KAAK,CAAC,OAAO,CAAC;IACtB,CAAC;IACD,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;AACtB,CAAC"}