@pawells/nestjs-shared 1.0.0-dev.3052c75

package/build/common/interfaces/log-entry.interface.js

@@ -0,0 +1,33 @@
+const DEBUG_LEVEL = 0;
+const INFO_LEVEL = 1;
+const WARN_LEVEL = 2;
+const ERROR_LEVEL = 3;
+const FATAL_LEVEL = 4;
+const SILENT_LEVEL = 5;
+export var LogLevel;
+(function (LogLevel) {
+    LogLevel[LogLevel["DEBUG"] = 0] = "DEBUG";
+    LogLevel[LogLevel["INFO"] = 1] = "INFO";
+    LogLevel[LogLevel["WARN"] = 2] = "WARN";
+    LogLevel[LogLevel["ERROR"] = 3] = "ERROR";
+    LogLevel[LogLevel["FATAL"] = 4] = "FATAL";
+    /** Suppresses all log output. */
+    LogLevel[LogLevel["SILENT"] = 5] = "SILENT";
+})(LogLevel || (LogLevel = {}));
+export const LOG_LEVEL_STRINGS = {
+    [LogLevel.DEBUG]: 'debug',
+    [LogLevel.INFO]: 'info',
+    [LogLevel.WARN]: 'warn',
+    [LogLevel.ERROR]: 'error',
+    [LogLevel.FATAL]: 'fatal',
+    [LogLevel.SILENT]: 'silent',
+};
+export const LOG_LEVEL_FROM_STRING = {
+    debug: LogLevel.DEBUG,
+    info: LogLevel.INFO,
+    warn: LogLevel.WARN,
+    error: LogLevel.ERROR,
+    fatal: LogLevel.FATAL,
+    silent: LogLevel.SILENT,
+};
+//# sourceMappingURL=log-entry.interface.js.map

package/build/common/interfaces/log-entry.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"log-entry.interface.js","sourceRoot":"","sources":["../../../src/common/interfaces/log-entry.interface.ts"],"names":[],"mappings":"AAgBA,MAAM,WAAW,GAAG,CAAC,CAAC;AACtB,MAAM,UAAU,GAAG,CAAC,CAAC;AACrB,MAAM,UAAU,GAAG,CAAC,CAAC;AACrB,MAAM,WAAW,GAAG,CAAC,CAAC;AACtB,MAAM,WAAW,GAAG,CAAC,CAAC;AACtB,MAAM,YAAY,GAAG,CAAC,CAAC;AAEvB,MAAM,CAAN,IAAY,QAQX;AARD,WAAY,QAAQ;IACnB,yCAAmB,CAAA;IACnB,uCAAiB,CAAA;IACjB,uCAAiB,CAAA;IACjB,yCAAmB,CAAA;IACnB,yCAAmB,CAAA;IACnB,iCAAiC;IACjC,2CAAqB,CAAA;AACtB,CAAC,EARW,QAAQ,KAAR,QAAQ,QAQnB;AAED,MAAM,CAAC,MAAM,iBAAiB,GAA6B;IAC1D,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO;IACzB,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM;IACvB,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM;IACvB,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO;IACzB,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO;IACzB,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,QAAQ;CAC3B,CAAC;AAEF,MAAM,CAAC,MAAM,qBAAqB,GAA6B;IAC9D,KAAK,EAAE,QAAQ,CAAC,KAAK;IACrB,IAAI,EAAE,QAAQ,CAAC,IAAI;IACnB,IAAI,EAAE,QAAQ,CAAC,IAAI;IACnB,KAAK,EAAE,QAAQ,CAAC,KAAK;IACrB,KAAK,EAAE,QAAQ,CAAC,KAAK;IACrB,MAAM,EAAE,QAAQ,CAAC,MAAM;CACvB,CAAC"}

package/build/common/interfaces/logger.interface.d.ts

@@ -0,0 +1,62 @@
+import { LogMetadata } from './log-entry.interface.js';
+/**
+ * Basic logging interface following Interface Segregation Principle
+ * Provides essential logging methods without contextual logger creation
+ */
+export interface ILogger {
+    /**
+     * Log debug message
+     * @param message - Log message
+     * @param context - Optional context override
+     * @param metadata - Optional structured metadata
+     */
+    debug(message: string | Error, context?: string, metadata?: LogMetadata): void;
+    debug(message: string | Error, metadata?: LogMetadata): void;
+    /**
+     * Log info message
+     * @param message - Log message
+     * @param context - Optional context override
+     * @param metadata - Optional structured metadata
+     */
+    info(message: string | Error, context?: string, metadata?: LogMetadata): void;
+    info(message: string | Error, metadata?: LogMetadata): void;
+    /**
+     * Log warning message
+     * @param message - Log message
+     * @param context - Optional context override
+     * @param metadata - Optional structured metadata
+     */
+    warn(message: string | Error, context?: string, metadata?: LogMetadata): void;
+    warn(message: string | Error, metadata?: LogMetadata): void;
+    /**
+     * Log error message
+     * @param message - Log message or Error object
+     * @param trace - Optional stack trace
+     * @param context - Optional context override
+     * @param metadata - Optional structured metadata
+     */
+    error(message: string | Error, trace?: string, context?: string, metadata?: LogMetadata): void;
+    error(message: string | Error, context?: string, metadata?: LogMetadata): void;
+    /**
+     * Log fatal message
+     * @param message - Log message or Error object
+     * @param trace - Optional stack trace
+     * @param context - Optional context override
+     * @param metadata - Optional structured metadata
+     */
+    fatal(message: string | Error, trace?: string, context?: string, metadata?: LogMetadata): void;
+    fatal(message: string | Error, context?: string, metadata?: LogMetadata): void;
+}
+/**
+ * Contextual logging interface extending basic logging
+ * Adds capability to create contextual logger instances
+ */
+export interface IContextualLogger extends ILogger {
+    /**
+     * Create a contextual logger instance
+     * @param context - Context string
+     * @returns New logger instance with context
+     */
+    createContextualLogger(context: string): IContextualLogger;
+}
+//# sourceMappingURL=logger.interface.d.ts.map

package/build/common/interfaces/logger.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.interface.d.ts","sourceRoot":"","sources":["../../../src/common/interfaces/logger.interface.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAEvD;;;GAGG;AACH,MAAM,WAAW,OAAO;IACvB;;;;;OAKG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,KAAK,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;IAC/E,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,KAAK,EAAE,QAAQ,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;IAE7D;;;;;OAKG;IACH,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,KAAK,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;IAC9E,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,KAAK,EAAE,QAAQ,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;IAE5D;;;;;OAKG;IACH,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,KAAK,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;IAC9E,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,KAAK,EAAE,QAAQ,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;IAE5D;;;;;;OAMG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,KAAK,EAAE,KAAK,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;IAC/F,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,KAAK,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;IAE/E;;;;;;OAMG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,KAAK,EAAE,KAAK,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;IAC/F,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,KAAK,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;CAC/E;AAED;;;GAGG;AACH,MAAM,WAAW,iBAAkB,SAAQ,OAAO;IACjD;;;;OAIG;IACH,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,iBAAiB,CAAC;CAC3D"}

package/build/common/interfaces/logger.interface.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=logger.interface.js.map

package/build/common/interfaces/logger.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.interface.js","sourceRoot":"","sources":["../../../src/common/interfaces/logger.interface.ts"],"names":[],"mappings":""}

package/build/common/interfaces/metrics-exporter.interface.d.ts

@@ -0,0 +1,275 @@
+/**
+ * Metrics exporter interface types for @pawells/nestjs-shared
+ *
+ * Provides standardized interfaces for exporting metrics to different backends
+ * (Prometheus, OpenTelemetry, etc.)
+ */
+/**
+ * Supported metric instrument types
+ *
+ * @example
+ * ```typescript
+ * type CounterType = 'counter'; // Always incrementing
+ * type HistogramType = 'histogram'; // Distribution of values
+ * type GaugeType = 'gauge'; // Instantaneous value
+ * type CounterWithDownType = 'updown_counter'; // Can increment or decrement
+ * ```
+ */
+export type MetricType = 'counter' | 'histogram' | 'gauge' | 'updown_counter';
+/**
+ * Metric descriptor — registered once per metric, defines the shape of the metric
+ *
+ * A descriptor uniquely identifies a metric and specifies its properties. Descriptors
+ * are typically registered once during application startup and reused for all
+ * subsequent metric recordings.
+ *
+ * @property name - Unique identifier for the metric (e.g., 'http_request_duration_seconds')
+ * @property type - The kind of metric instrument
+ * @property help - Human-readable description of what the metric measures
+ * @property labelNames - Names of labels/tags associated with this metric
+ *   (e.g., ['method', 'route', 'status_code'])
+ * @property buckets - Histogram bucket boundaries (histogram type only).
+ *   Defaults to exponential buckets if not specified.
+ * @property unit - Optional unit of measurement (e.g., 'seconds', 'bytes', 'requests')
+ *
+ * @example
+ * ```typescript
+ * const httpDurationDescriptor: MetricDescriptor = {
+ *   name: 'http_request_duration_seconds',
+ *   type: 'histogram',
+ *   help: 'Duration of HTTP requests in seconds',
+ *   labelNames: ['method', 'route', 'status_code'],
+ *   buckets: [0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10],
+ *   unit: 'seconds',
+ * };
+ * ```
+ */
+export interface MetricDescriptor {
+    /**
+     * Unique identifier for the metric
+     * Convention: snake_case with unit suffix (e.g., 'request_duration_seconds')
+     */
+    name: string;
+    /**
+     * Type of metric instrument
+     */
+    type: MetricType;
+    /**
+     * Human-readable description
+     */
+    help: string;
+    /**
+     * Names of labels/tags for this metric
+     * Labels provide dimensions for filtering and aggregating metric values
+     */
+    labelNames: string[];
+    /**
+     * Histogram bucket boundaries
+     * Only used for 'histogram' type metrics.
+     * Buckets should be in ascending order.
+     */
+    buckets?: number[];
+    /**
+     * Unit of measurement
+     * Used by exporters for formatting and can be included in metric names
+     */
+    unit?: string;
+}
+/**
+ * Metric value — emitted each time a metric is recorded
+ *
+ * Represents a single data point for a metric at a specific point in time.
+ * Each value includes the descriptor, numeric value, labels (tag values),
+ * and a timestamp.
+ *
+ * @property descriptor - The metric descriptor that defines this value's shape
+ * @property value - The numeric value of the metric (always a number)
+ * @property labels - Label values paired with the metric. Keys must match
+ *   the descriptor's labelNames. Values are typically strings but can be
+ *   numbers for performance.
+ * @property timestamp - Performance timestamp (milliseconds since start, from performance.now())
+ *   Used for ordering and time-series analysis.
+ *
+ * @example
+ * ```typescript
+ * const httpDurationValue: MetricValue = {
+ *   descriptor: httpDurationDescriptor,
+ *   value: 0.125,  // seconds
+ *   labels: {
+ *     method: 'GET',
+ *     route: '/api/users',
+ *     status_code: '200',
+ *   },
+ *   timestamp: performance.now(),
+ * };
+ * ```
+ */
+export interface MetricValue {
+    /**
+     * Descriptor that defines this metric's structure
+     */
+    descriptor: MetricDescriptor;
+    /**
+     * Numeric value of the metric
+     * Range depends on metric type:
+     * - counter: >= 0 (always increasing)
+     * - gauge: any number
+     * - histogram: any number (typically distribution measure)
+     * - updown_counter: any number (can increase or decrease)
+     */
+    value: number;
+    /**
+     * Label values paired with the metric
+     * Keys correspond to descriptor.labelNames
+     * Values are typically strings but can be numbers
+     */
+    labels: Record<string, string | number>;
+    /**
+     * Performance timestamp in milliseconds (from performance.now())
+     * Used for ordering, trending, and time-series analysis
+     */
+    timestamp: number;
+}
+/**
+ * Metrics exporter interface
+ *
+ * Implemented by exporters that handle metric collection and export to external systems
+ * (Prometheus, OpenTelemetry, CloudWatch, etc.).
+ *
+ * An exporter can support two modes:
+ * - **Event-based** (`supportsEventBased`): Receives metrics as they're recorded
+ * - **Pull-based** (`supportsPull`): Provides metrics on-demand during scrape/pull requests
+ *
+ * @example
+ * ```typescript
+ * // Prometheus exporter (event-based push + pull-based scrape)
+ * class PrometheusExporter implements IMetricsExporter {
+ *   readonly supportsEventBased = true;
+ *   readonly supportsPull = true;
+ *
+ *   onMetricRecorded(value: MetricValue) {
+ *     // Update Prometheus registry
+ *     this.registry.observe(value);
+ *   }
+ *
+ *   getMetrics(): string {
+ *     // Return Prometheus text format
+ *     return this.registry.metrics();
+ *   }
+ * }
+ *
+ * // OpenTelemetry exporter (event-based only)
+ * class OTelExporter implements IMetricsExporter {
+ *   readonly supportsEventBased = true;
+ *   readonly supportsPull = false;
+ *
+ *   onMetricRecorded(value: MetricValue) {
+ *     // Send to OTEL collector
+ *     this.client.send(value);
+ *   }
+ * }
+ * ```
+ */
+export interface IMetricsExporter {
+    /**
+     * Whether this exporter wants to be called synchronously on each metric recording
+     *
+     * If true, onMetricRecorded() will be called for every metric value recorded.
+     * Used for active/eager exporters like Prometheus that maintain in-memory registries.
+     *
+     * @readonly
+     */
+    readonly supportsEventBased: boolean;
+    /**
+     * Whether this exporter supports pull-based reads (e.g., Prometheus scrape endpoint)
+     *
+     * If true, getMetrics() can be called to retrieve current metric values on-demand.
+     * Used for Prometheus-style scrape endpoints.
+     *
+     * @readonly
+     */
+    readonly supportsPull: boolean;
+    /**
+     * Called when a metric value is recorded
+     *
+     * Only called if supportsEventBased = true.
+     * Implementations should process the metric quickly to avoid blocking the request.
+     * If processing needs to be async, implementations should queue work and return immediately.
+     *
+     * @param value - The metric value being recorded
+     *
+     * @example
+     * ```typescript
+     * onMetricRecorded(value: MetricValue): void {
+     *   // Update in-memory registry
+     *   const key = this.buildKey(value);
+     *   this.registry.update(key, value);
+     *
+     *   // If async work needed, queue it
+     *   this.queue.push(value);
+     * }
+     * ```
+     */
+    onMetricRecorded?(value: MetricValue): void;
+    /**
+     * Called when a new metric descriptor is registered
+     *
+     * Exporters can use this hook to pre-create instruments or validate that
+     * they support the metric type. Implementations should be fast.
+     *
+     * @param descriptor - The metric descriptor being registered
+     *
+     * @example
+     * ```typescript
+     * onDescriptorRegistered(descriptor: MetricDescriptor): void {
+     *   // Pre-create Prometheus gauge/counter/histogram
+     *   this.registry.register(descriptor);
+     * }
+     * ```
+     */
+    onDescriptorRegistered?(descriptor: MetricDescriptor): void;
+    /**
+     * Retrieve all current metric values (pull-based)
+     *
+     * Only required if supportsPull = true.
+     * Called by scrape endpoints or pull-based collectors to fetch metrics.
+     * Should return metrics in the format expected by the external system
+     * (e.g., Prometheus text format, JSON, etc.).
+     *
+     * @returns Current metrics in the exporter's format (string, or Promise<string>)
+     *
+     * @example
+     * ```typescript
+     * // Prometheus exporter
+     * getMetrics(): string {
+     *   return this.registry.metrics(); // Returns Prometheus text format
+     * }
+     *
+     * // Async exporter
+     * getMetrics(): Promise<string> {
+     *   return this.client.fetchMetrics(); // Fetch from remote backend
+     * }
+     * ```
+     */
+    getMetrics?(): Promise<string> | string;
+    /**
+     * Called on application shutdown
+     *
+     * Exporters should use this hook to flush buffered metrics, close connections,
+     * and clean up resources.
+     *
+     * @returns Optional promise (for async cleanup)
+     *
+     * @example
+     * ```typescript
+     * shutdown(): Promise<void> {
+     *   return Promise.all([
+     *     this.client.flush(),
+     *     this.client.close(),
+     *   ]);
+     * }
+     * ```
+     */
+    shutdown?(): Promise<void> | void;
+}
+//# sourceMappingURL=metrics-exporter.interface.d.ts.map

package/build/common/interfaces/metrics-exporter.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics-exporter.interface.d.ts","sourceRoot":"","sources":["../../../src/common/interfaces/metrics-exporter.interface.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;;;;;;GAUG;AACH,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,WAAW,GAAG,OAAO,GAAG,gBAAgB,CAAC;AAE9E;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,WAAW,gBAAgB;IAChC;;;OAGG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;OAEG;IACH,IAAI,EAAE,UAAU,CAAC;IAEjB;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;;OAGG;IACH,UAAU,EAAE,MAAM,EAAE,CAAC;IAErB;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IAEnB;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,WAAW,WAAW;IAC3B;;OAEG;IACH,UAAU,EAAE,gBAAgB,CAAC;IAE7B;;;;;;;OAOG;IACH,KAAK,EAAE,MAAM,CAAC;IAEd;;;;OAIG;IACH,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,CAAC;IAExC;;;OAGG;IACH,SAAS,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,MAAM,WAAW,gBAAgB;IAChC;;;;;;;OAOG;IACH,QAAQ,CAAC,kBAAkB,EAAE,OAAO,CAAC;IAErC;;;;;;;OAOG;IACH,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAE/B;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,gBAAgB,CAAC,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI,CAAC;IAE5C;;;;;;;;;;;;;;;OAeG;IACH,sBAAsB,CAAC,CAAC,UAAU,EAAE,gBAAgB,GAAG,IAAI,CAAC;IAE5D;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,UAAU,CAAC,IAAI,OAAO,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC;IAExC;;;;;;;;;;;;;;;;;OAiBG;IACH,QAAQ,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CAClC"}

package/build/common/interfaces/metrics-exporter.interface.js

@@ -0,0 +1,8 @@
+/**
+ * Metrics exporter interface types for @pawells/nestjs-shared
+ *
+ * Provides standardized interfaces for exporting metrics to different backends
+ * (Prometheus, OpenTelemetry, etc.)
+ */
+export {};
+//# sourceMappingURL=metrics-exporter.interface.js.map

package/build/common/interfaces/metrics-exporter.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics-exporter.interface.js","sourceRoot":"","sources":["../../../src/common/interfaces/metrics-exporter.interface.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/build/common/metrics/base-metrics-collector.d.ts

@@ -0,0 +1,81 @@
+import { Logger } from '@nestjs/common';
+import { Counter, Gauge, Histogram } from 'prom-client';
+import { MetricsRegistryService } from '../services/metrics-registry.service.js';
+/**
+ * BaseMetricsCollector
+ *
+ * Abstract base class for domain-specific metrics collection. Services can extend this class
+ * to define custom Prometheus metrics that are registered with the centralized MetricsRegistryService.
+ *
+ * Usage:
+ * ```typescript
+ * class StreamMetricsCollector extends BaseMetricsCollector {
+ *   protected initializeMetrics(): void {
+ *     this.registerCounter('stream_created', 'Total streams created', ['region']);
+ *     this.registerGauge('active_streams', 'Currently active streams', ['region']);
+ *     this.registerHistogram('stream_duration', 'Stream duration in seconds', ['region']);
+ *   }
+ * }
+ *
+ * const collector = new StreamMetricsCollector(metricsRegistry);
+ * ```
+ */
+export declare abstract class BaseMetricsCollector {
+    protected readonly logger: Logger;
+    private readonly metricsRegistry;
+    private readonly metrics;
+    constructor(metricsRegistry: MetricsRegistryService);
+    /**
+     * Initialize metrics for this collector.
+     * Subclasses must implement this method to register their custom metrics.
+     *
+     * @example
+     * protected initializeMetrics(): void {
+     *   this.registerCounter('events_processed', 'Total events processed');
+     *   this.registerGauge('queue_depth', 'Current queue depth');
+     * }
+     */
+    protected abstract initializeMetrics(): void;
+    /**
+     * Register a counter metric.
+     *
+     * @param name - The metric name (e.g., 'requests_total')
+     * @param help - Help text describing the metric
+     * @param labelNames - Optional label names for the metric
+     * @returns The registered counter metric
+     */
+    protected registerCounter(name: string, help: string, labelNames?: string[]): Counter<string>;
+    /**
+     * Register a gauge metric.
+     *
+     * @param name - The metric name (e.g., 'queue_size')
+     * @param help - Help text describing the metric
+     * @param labelNames - Optional label names for the metric
+     * @returns The registered gauge metric
+     */
+    protected registerGauge(name: string, help: string, labelNames?: string[]): Gauge<string>;
+    /**
+     * Register a histogram metric.
+     *
+     * @param name - The metric name (e.g., 'request_duration')
+     * @param help - Help text describing the metric
+     * @param labelNames - Optional label names for the metric
+     * @param buckets - Optional bucket boundaries for the histogram
+     * @returns The registered histogram metric
+     */
+    protected registerHistogram(name: string, help: string, labelNames?: string[], buckets?: number[]): Histogram<string>;
+    /**
+     * Get a registered metric by name.
+     *
+     * @param name - The metric name
+     * @returns The metric instance, or undefined if not found
+     */
+    getMetric(name: string): Counter<string> | Gauge<string> | Histogram<string> | undefined;
+    /**
+     * Get all registered metrics.
+     *
+     * @returns A Map of all registered metrics keyed by name
+     */
+    getAllMetrics(): Map<string, Counter<string> | Gauge<string> | Histogram<string>>;
+}
+//# sourceMappingURL=base-metrics-collector.d.ts.map

package/build/common/metrics/base-metrics-collector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-metrics-collector.d.ts","sourceRoot":"","sources":["../../../src/common/metrics/base-metrics-collector.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AACxC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxD,OAAO,EAAE,sBAAsB,EAAE,MAAM,yCAAyC,CAAC;AAEjF;;;;;;;;;;;;;;;;;;GAkBG;AACH,8BAAsB,oBAAoB;IACzC,SAAS,CAAC,QAAQ,CAAC,MAAM,SAAqC;IAE9D,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAyB;IAEzD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA+E;gBAE3F,eAAe,EAAE,sBAAsB;IAMnD;;;;;;;;;OASG;IACH,SAAS,CAAC,QAAQ,CAAC,iBAAiB,IAAI,IAAI;IAE5C;;;;;;;OAOG;IACH,SAAS,CAAC,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,GAAE,MAAM,EAAO,GAAG,OAAO,CAAC,MAAM,CAAC;IAMjG;;;;;;;OAOG;IACH,SAAS,CAAC,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,GAAE,MAAM,EAAO,GAAG,KAAK,CAAC,MAAM,CAAC;IAM7F;;;;;;;;OAQG;IACH,SAAS,CAAC,iBAAiB,CAC1B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,UAAU,GAAE,MAAM,EAAO,EACzB,OAAO,CAAC,EAAE,MAAM,EAAE,GAChB,SAAS,CAAC,MAAM,CAAC;IAMpB;;;;;OAKG;IACI,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,GAAG,KAAK,CAAC,MAAM,CAAC,GAAG,SAAS,CAAC,MAAM,CAAC,GAAG,SAAS;IAI/F;;;;OAIG;IACI,aAAa,IAAI,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,GAAG,KAAK,CAAC,MAAM,CAAC,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC;CAGxF"}

package/build/common/metrics/base-metrics-collector.js

@@ -0,0 +1,88 @@
+import { Logger } from '@nestjs/common';
+/**
+ * BaseMetricsCollector
+ *
+ * Abstract base class for domain-specific metrics collection. Services can extend this class
+ * to define custom Prometheus metrics that are registered with the centralized MetricsRegistryService.
+ *
+ * Usage:
+ * ```typescript
+ * class StreamMetricsCollector extends BaseMetricsCollector {
+ *   protected initializeMetrics(): void {
+ *     this.registerCounter('stream_created', 'Total streams created', ['region']);
+ *     this.registerGauge('active_streams', 'Currently active streams', ['region']);
+ *     this.registerHistogram('stream_duration', 'Stream duration in seconds', ['region']);
+ *   }
+ * }
+ *
+ * const collector = new StreamMetricsCollector(metricsRegistry);
+ * ```
+ */
+export class BaseMetricsCollector {
+    logger = new Logger(this.constructor.name);
+    metricsRegistry;
+    metrics = new Map();
+    constructor(metricsRegistry) {
+        this.metricsRegistry = metricsRegistry;
+        this.initializeMetrics();
+        this.logger.log(`${this.constructor.name} initialized with ${this.metrics.size} metrics`);
+    }
+    /**
+     * Register a counter metric.
+     *
+     * @param name - The metric name (e.g., 'requests_total')
+     * @param help - Help text describing the metric
+     * @param labelNames - Optional label names for the metric
+     * @returns The registered counter metric
+     */
+    registerCounter(name, help, labelNames = []) {
+        const counter = this.metricsRegistry.createCounter(name, help, labelNames);
+        this.metrics.set(name, counter);
+        return counter;
+    }
+    /**
+     * Register a gauge metric.
+     *
+     * @param name - The metric name (e.g., 'queue_size')
+     * @param help - Help text describing the metric
+     * @param labelNames - Optional label names for the metric
+     * @returns The registered gauge metric
+     */
+    registerGauge(name, help, labelNames = []) {
+        const gauge = this.metricsRegistry.createGauge(name, help, labelNames);
+        this.metrics.set(name, gauge);
+        return gauge;
+    }
+    /**
+     * Register a histogram metric.
+     *
+     * @param name - The metric name (e.g., 'request_duration')
+     * @param help - Help text describing the metric
+     * @param labelNames - Optional label names for the metric
+     * @param buckets - Optional bucket boundaries for the histogram
+     * @returns The registered histogram metric
+     */
+    registerHistogram(name, help, labelNames = [], buckets) {
+        const histogram = this.metricsRegistry.createHistogram(name, help, labelNames, buckets);
+        this.metrics.set(name, histogram);
+        return histogram;
+    }
+    /**
+     * Get a registered metric by name.
+     *
+     * @param name - The metric name
+     * @returns The metric instance, or undefined if not found
+     */
+    getMetric(name) {
+        return this.metrics.get(name);
+    }
+    /**
+     * Get all registered metrics.
+     *
+     * @returns A Map of all registered metrics keyed by name
+     */
+    getAllMetrics() {
+        return new Map(this.metrics);
+    }
+}
+//# sourceMappingURL=base-metrics-collector.js.map

package/build/common/metrics/base-metrics-collector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-metrics-collector.js","sourceRoot":"","sources":["../../../src/common/metrics/base-metrics-collector.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAIxC;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,OAAgB,oBAAoB;IACtB,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC;IAE7C,eAAe,CAAyB;IAExC,OAAO,GAAqE,IAAI,GAAG,EAAE,CAAC;IAEvG,YAAY,eAAuC;QAClD,IAAI,CAAC,eAAe,GAAG,eAAe,CAAC;QACvC,IAAI,CAAC,iBAAiB,EAAE,CAAC;QACzB,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,WAAW,CAAC,IAAI,qBAAqB,IAAI,CAAC,OAAO,CAAC,IAAI,UAAU,CAAC,CAAC;IAC3F,CAAC;IAcD;;;;;;;OAOG;IACO,eAAe,CAAC,IAAY,EAAE,IAAY,EAAE,aAAuB,EAAE;QAC9E,MAAM,OAAO,GAAG,IAAI,CAAC,eAAe,CAAC,aAAa,CAAC,IAAI,EAAE,IAAI,EAAE,UAAU,CAAC,CAAC;QAC3E,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QAChC,OAAO,OAAO,CAAC;IAChB,CAAC;IAED;;;;;;;OAOG;IACO,aAAa,CAAC,IAAY,EAAE,IAAY,EAAE,aAAuB,EAAE;QAC5E,MAAM,KAAK,GAAG,IAAI,CAAC,eAAe,CAAC,WAAW,CAAC,IAAI,EAAE,IAAI,EAAE,UAAU,CAAC,CAAC;QACvE,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QAC9B,OAAO,KAAK,CAAC;IACd,CAAC;IAED;;;;;;;;OAQG;IACO,iBAAiB,CAC1B,IAAY,EACZ,IAAY,EACZ,aAAuB,EAAE,EACzB,OAAkB;QAElB,MAAM,SAAS,GAAG,IAAI,CAAC,eAAe,CAAC,eAAe,CAAC,IAAI,EAAE,IAAI,EAAE,UAAU,EAAE,OAAO,CAAC,CAAC;QACxF,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;QAClC,OAAO,SAAS,CAAC;IAClB,CAAC;IAED;;;;;OAKG;IACI,SAAS,CAAC,IAAY;QAC5B,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC/B,CAAC;IAED;;;;OAIG;IACI,aAAa;QACnB,OAAO,IAAI,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAC9B,CAAC;CACD"}

package/build/common/metrics/index.d.ts

@@ -0,0 +1,2 @@
+export { BaseMetricsCollector } from './base-metrics-collector.js';
+//# sourceMappingURL=index.d.ts.map

package/build/common/metrics/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/common/metrics/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC"}

package/build/common/metrics/index.js

@@ -0,0 +1,2 @@
+export { BaseMetricsCollector } from './base-metrics-collector.js';
+//# sourceMappingURL=index.js.map

package/build/common/metrics/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/common/metrics/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC"}

package/build/common/metrics.module.d.ts

@@ -0,0 +1,50 @@
+import { DynamicModule } from '@nestjs/common';
+import { ModuleMetadata } from '@nestjs/common/interfaces';
+/**
+ * Async options for MetricsModule.
+ * Configuration options for asynchronous MetricsModule initialization.
+ */
+export interface MetricsModuleAsyncOptions extends Pick<ModuleMetadata, 'imports'> {
+}
+/**
+ * Metrics Module.
+ * Provides comprehensive Prometheus metrics collection and exposure for NestJS applications.
+ *
+ * Features:
+ * - HTTP request metrics (duration, count, size) with automatic cardinality prevention
+ * - Custom metric creation (counter, gauge, histogram)
+ * - Default Node.js metrics collection
+ * - Prometheus endpoint at /metrics
+ * - Metrics registry management
+ *
+ * @remarks
+ * - Imported as global module in CommonModule
+ * - Controlled by METRICS_ENABLED environment variable (default: true)
+ * - Automatically normalizes dynamic path segments to prevent unbounded label cardinality
+ * - MetricsController exports metrics at GET /metrics in Prometheus format
+ *
+ * @example
+ * ```typescript
+ * // Access metrics in any injectable
+ * constructor(private metrics: MetricsRegistryService) {}
+ *
+ * // Create and record custom metrics
+ * const counter = this.metrics.createCounter('orders_total', 'Total orders');
+ * counter.inc({ status: 'completed' });
+ *
+ * // Get metrics (typically called by MetricsController)
+ * const prometheusText = await this.metrics.getMetrics();
+ * ```
+ */
+export declare class MetricsModule {
+    /**
+     * Configure metrics module for root application
+     * Enables HTTP metrics collection and /metrics endpoint
+     */
+    static forRoot(): DynamicModule;
+    /**
+     * Configure metrics module with async options
+     */
+    static forRootAsync(options: MetricsModuleAsyncOptions): DynamicModule;
+}
+//# sourceMappingURL=metrics.module.d.ts.map

package/build/common/metrics.module.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.module.d.ts","sourceRoot":"","sources":["../../src/common/metrics.module.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkB,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC/D,OAAO,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAK3D;;;GAGG;AACH,MAAM,WAAW,yBAA0B,SAAQ,IAAI,CAAC,cAAc,EAAE,SAAS,CAAC;CAEjF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,qBAYa,aAAa;IACzB;;;OAGG;WACW,OAAO,IAAI,aAAa;IAMtC;;OAEG;WACW,YAAY,CAAC,OAAO,EAAE,yBAAyB,GAAG,aAAa;CAM7E"}