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

package/build/prometheus.exporter.js

@@ -0,0 +1,380 @@
+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 PrometheusExporter_1;
+import { Injectable } from '@nestjs/common';
+import { Counter, Gauge, Histogram, Registry, collectDefaultMetrics } from 'prom-client';
+import { AppLogger, getErrorMessage } from '@pawells/nestjs-shared/common';
+/**
+ * Prometheus metrics exporter implementation
+ *
+ * Implements the IMetricsExporter interface for Prometheus pull-based metrics collection.
+ * Uses prom-client library to manage Prometheus instruments (Counter, Gauge, Histogram)
+ * and exports metrics in Prometheus text format on demand.
+ *
+ * Architecture:
+ * - **Event-based buffering**: Metric values are buffered as they are recorded
+ * - **Pull-based export**: Flushes all pending values when `/metrics` endpoint is scraped
+ * - **Atomic swaps**: Uses atomic array swaps during flush to prevent concurrent data loss
+ * - **Bounded memory**: Limits pending values to 1000 per metric to prevent unbounded growth
+ * - **Node.js defaults**: Automatically collects Node.js process metrics (CPU, memory, GC, etc.)
+ *
+ * Type mapping:
+ * - `counter` → prom-client Counter (monotonically increasing)
+ * - `gauge` → prom-client Gauge (point-in-time value)
+ * - `updown_counter` → prom-client Gauge (can increase or decrease)
+ * - `histogram` → prom-client Histogram (distribution with buckets)
+ *
+ * @example
+ * ```typescript
+ * const exporter = new PrometheusExporter();
+ * registry.registerExporter(exporter);
+ *
+ * // Later, get metrics for Prometheus scrape endpoint
+ * const prometheusMetrics = await exporter.getMetrics();
+ * ```
+ */
+let PrometheusExporter = class PrometheusExporter {
+    static { PrometheusExporter_1 = this; }
+    /**
+     * This exporter buffers metric values as they are recorded and flushes
+     * them into prom-client instruments on each pull (getMetrics)
+     */
+    supportsEventBased = true;
+    /**
+     * This exporter supports pull-based metric retrieval
+     */
+    supportsPull = true;
+    /**
+     * Prom-client Registry instance for managing instruments
+     * @private
+     */
+    registry;
+    /**
+     * Cache of created prom-client instruments (Counter, Histogram, Gauge)
+     * Keyed by metric name
+     * @private
+     */
+    instruments;
+    /**
+     * Pending metric values to be flushed into prom-client instruments on next getMetrics()
+     * Keyed by metric name
+     * @private
+     */
+    pending;
+    /**
+     * Running totals for updown_counter metrics (persistent across scrapes)
+     * Keyed by metric name, then by normalized label key
+     * @private
+     */
+    gaugeValues;
+    /**
+     * Maximum number of pending metric values per metric before culling oldest entries
+     * Prevents unbounded memory growth if metrics are recorded much faster than pulled
+     * @private
+     */
+    // eslint-disable-next-line no-magic-numbers
+    static MAX_PENDING_PER_METRIC = 1000;
+    /**
+     * Logger instance for warnings and errors
+     */
+    logger;
+    /**
+     * Normalize label keys to handle consistent ordering regardless of insertion order
+     * @private
+     */
+    static normalizeLabelKey(labels) {
+        const sortedEntries = Object.entries(labels).sort(([a], [b]) => a.localeCompare(b));
+        return JSON.stringify(Object.fromEntries(sortedEntries));
+    }
+    /**
+     * Create a new PrometheusExporter instance
+     *
+     * Initializes a prom-client Registry and starts collecting Node.js default metrics
+     * (process CPU, memory, event loop, garbage collection, etc.).
+     */
+    constructor() {
+        this.registry = new Registry();
+        this.instruments = new Map();
+        this.pending = new Map();
+        this.gaugeValues = new Map();
+        this.logger = new AppLogger(undefined, PrometheusExporter_1.name);
+        // Collect Node.js default metrics into our registry
+        collectDefaultMetrics({ register: this.registry });
+    }
+    /**
+     * Called when a metric descriptor is registered in InstrumentationRegistry
+     *
+     * Pre-creates the corresponding prom-client instrument (Counter, Gauge, or Histogram)
+     * based on the descriptor's type. The created instrument is cached for future use.
+     * Initializes an empty pending array for the metric to buffer future recorded values.
+     *
+     * Type mapping:
+     * - `counter` → Counter (incremented by value via inc())
+     * - `histogram` → Histogram (observed via observe())
+     * - `gauge` or `updown_counter` → Gauge (set via set())
+     *
+     * @param descriptor - The metric descriptor being registered
+     * @throws Error if descriptor type is not supported
+     *
+     * @example
+     * ```typescript
+     * exporter.onDescriptorRegistered({
+     *   name: 'http_request_duration_seconds',
+     *   type: 'histogram',
+     *   help: 'Request duration in seconds',
+     *   labelNames: ['method', 'route', 'status_code'],
+     *   buckets: [0.001, 0.005, 0.01, 0.05, 0.1, 0.5, 1],
+     * });
+     * ```
+     */
+    onDescriptorRegistered(descriptor) {
+        const { name, type, help, labelNames, buckets } = descriptor;
+        // Guard against duplicate registration
+        if (this.instruments.has(name)) {
+            return;
+        }
+        // Validate required fields
+        if (!name) {
+            this.logger.warn('Metric descriptor registered with empty name');
+            return;
+        }
+        if (!help) {
+            this.logger.warn(`Metric descriptor "${name}" registered with empty help text`);
+            return;
+        }
+        let instrument;
+        switch (type) {
+            case 'counter':
+                instrument = new Counter({
+                    name,
+                    help,
+                    labelNames,
+                    registers: [this.registry],
+                });
+                break;
+            case 'histogram':
+                instrument = new Histogram({
+                    name,
+                    help,
+                    labelNames,
+                    buckets,
+                    registers: [this.registry],
+                });
+                break;
+            case 'gauge':
+            case 'updown_counter':
+                // Both gauge and updown_counter map to prom-client Gauge
+                instrument = new Gauge({
+                    name,
+                    help,
+                    labelNames,
+                    registers: [this.registry],
+                });
+                // Initialize running totals map for this metric
+                if (type === 'updown_counter') {
+                    this.gaugeValues.set(name, new Map());
+                }
+                break;
+            default:
+                throw new Error(`Unsupported metric type "${type}" for descriptor "${name}"`);
+        }
+        this.instruments.set(name, instrument);
+        this.pending.set(name, []);
+    }
+    /**
+     * Buffer a metric value to be flushed on next getMetrics() call
+     *
+     * Values are buffered rather than immediately recorded into prom-client.
+     * They are applied to the appropriate instrument during the next pull (getMetrics) call.
+     *
+     * Buffering behavior:
+     * - Values are appended to the pending array for the metric
+     * - If the pending array exceeds MAX_PENDING_PER_METRIC (1000), oldest entries are culled
+     * - If the metric descriptor was not registered first, a warning is logged and value is dropped
+     *
+     * @param value - The metric value to buffer
+     *
+     * @example
+     * ```typescript
+     * exporter.onMetricRecorded({
+     *   descriptor: { name: 'http_request_duration_seconds' },
+     *   value: 0.125,
+     *   labels: { method: 'GET', status_code: '200' },
+     *   timestamp: performance.now(),
+     * });
+     * ```
+     */
+    onMetricRecorded(value) {
+        const metricName = value.descriptor.name;
+        const pendingArray = this.pending.get(metricName);
+        if (pendingArray) {
+            pendingArray.push(value);
+            // Cap pending array to prevent unbounded memory growth
+            if (pendingArray.length > PrometheusExporter_1.MAX_PENDING_PER_METRIC) {
+                pendingArray.shift();
+            }
+        }
+        else {
+            // Warn if metric recorded before descriptor registration (data will be lost)
+            this.logger.warn(`Metric recorded before descriptor registration: ${metricName}`);
+        }
+    }
+    /**
+     * Retrieve all metrics in Prometheus text format
+     *
+     * Flushes all pending metric values into prom-client instruments, then returns
+     * the complete metrics output in Prometheus text format (version 0.0.4).
+     *
+     * Flush process:
+     * 1. For each metric, atomically swap the pending array with a fresh empty array
+     * 2. Apply all pending values to the corresponding instrument:
+     *    - Counter: increment by value
+     *    - Histogram: observe value
+     *    - Gauge: set to value
+     * 3. Skip any values where the instrument was not pre-created (shouldn't happen)
+     * 4. Return the serialized metrics from the registry
+     *
+     * Includes Node.js default metrics and all custom metrics registered with descriptors.
+     *
+     * @returns Promise resolving to metrics in Prometheus text format (version 0.0.4)
+     * @throws Error if metrics generation fails (logged but re-thrown)
+     *
+     * @example
+     * ```typescript
+     * const prometheusMetrics = await exporter.getMetrics();
+     * // Returns:
+     * // # HELP http_request_duration_seconds Duration of HTTP requests in seconds
+     * // # TYPE http_request_duration_seconds histogram
+     * // http_request_duration_seconds_bucket{le="0.001",...} 0
+     * // http_request_duration_seconds_bucket{le="0.01",...} 5
+     * ```
+     */
+    async getMetrics() {
+        // Flush all pending values into prom-client instruments
+        // Use atomic swap pattern: capture current values and replace with empty array
+        // to prevent loss of metrics recorded concurrently during flush
+        for (const [metricName, pendingValues] of this.pending.entries()) {
+            // Atomically swap pending array with a fresh one
+            this.pending.set(metricName, []);
+            if (pendingValues.length === 0) {
+                continue;
+            }
+            const instrument = this.instruments.get(metricName);
+            if (!instrument) {
+                // Instrument not yet created, skip pending values
+                continue;
+            }
+            // Record all pending values into the appropriate instrument
+            if (instrument instanceof Counter) {
+                // Counter: increment by value for each pending entry
+                for (const metricValue of pendingValues) {
+                    try {
+                        instrument.inc(metricValue.labels, metricValue.value);
+                    }
+                    catch (recordError) {
+                        this.logger.warn(`Failed to record metric value for "${metricName}": ${getErrorMessage(recordError)}`);
+                    }
+                }
+            }
+            else if (instrument instanceof Histogram) {
+                // Histogram: observe value for each pending entry
+                for (const metricValue of pendingValues) {
+                    try {
+                        instrument.observe(metricValue.labels, metricValue.value);
+                    }
+                    catch (recordError) {
+                        this.logger.warn(`Failed to record metric value for "${metricName}": ${getErrorMessage(recordError)}`);
+                    }
+                }
+            }
+            else if (instrument instanceof Gauge) {
+                // Gauge: set values directly per label set
+                // updown_counter: accumulate values per label set and maintain running total
+                const accumulatedValues = new Map();
+                for (const metricValue of pendingValues) {
+                    const labelKey = PrometheusExporter_1.normalizeLabelKey(metricValue.labels);
+                    const existing = accumulatedValues.get(labelKey);
+                    if (existing) {
+                        existing.value += metricValue.value;
+                    }
+                    else {
+                        accumulatedValues.set(labelKey, {
+                            labels: metricValue.labels,
+                            value: metricValue.value,
+                        });
+                    }
+                }
+                // Get running totals map for this metric (if it exists, it's an updown_counter)
+                const runningTotals = this.gaugeValues.get(metricName);
+                // Apply accumulated values to the gauge (iterate only through unique label sets)
+                for (const { labels, value: accumulatedValue } of accumulatedValues.values()) {
+                    try {
+                        let finalValue = accumulatedValue;
+                        // For updown_counters, add to running total; for regular gauges, use value directly
+                        if (runningTotals) {
+                            const normalizedKey = PrometheusExporter_1.normalizeLabelKey(labels);
+                            const currentTotal = runningTotals.get(normalizedKey) ?? 0;
+                            finalValue = currentTotal + accumulatedValue;
+                            runningTotals.set(normalizedKey, finalValue);
+                        }
+                        // Convert number values to strings if needed for prom-client
+                        const labelsForProm = {};
+                        for (const [key, val] of Object.entries(labels)) {
+                            labelsForProm[key] = String(val);
+                        }
+                        instrument.set(labelsForProm, finalValue);
+                    }
+                    catch (recordError) {
+                        this.logger.warn(`Failed to record metric value for "${metricName}": ${getErrorMessage(recordError)}`);
+                    }
+                }
+            }
+        }
+        // Return metrics in Prometheus text format
+        try {
+            return await this.registry.metrics();
+        }
+        catch (error) {
+            const message = getErrorMessage(error);
+            this.logger.error(`Failed to generate Prometheus metrics: ${message}`);
+            throw error;
+        }
+    }
+    /**
+     * Shutdown the exporter and clean up resources
+     *
+     * Clears the prom-client registry and releases all internal state:
+     * - registry.clear() — removes all instruments
+     * - instruments.clear() — removes cached instrument references
+     * - pending.clear() — discards any buffered but unflushed metric values
+     *
+     * Called by PrometheusModule during application shutdown (onApplicationShutdown).
+     *
+     * @returns Promise that resolves when shutdown is complete
+     *
+     * @example
+     * ```typescript
+     * await exporter.shutdown();
+     * ```
+     */
+    // eslint-disable-next-line require-await
+    async shutdown() {
+        this.registry.clear();
+        this.instruments.clear();
+        this.pending.clear();
+        this.gaugeValues.clear();
+    }
+};
+PrometheusExporter = PrometheusExporter_1 = __decorate([
+    Injectable(),
+    __metadata("design:paramtypes", [])
+], PrometheusExporter);
+export { PrometheusExporter };
+//# sourceMappingURL=prometheus.exporter.js.map

package/build/prometheus.exporter.js.map

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

package/build/prometheus.module.d.ts

@@ -0,0 +1,89 @@
+import { OnModuleInit, OnApplicationShutdown, type DynamicModule } from '@nestjs/common';
+import { InstrumentationRegistry } from '@pawells/nestjs-shared';
+import { PrometheusExporter } from './prometheus.exporter.js';
+/**
+ * Prometheus metrics module for NestJS
+ *
+ * Provides integration with @pawells/nestjs-shared InstrumentationRegistry
+ * to export metrics in Prometheus format via a `/metrics` HTTP endpoint.
+ *
+ * Features:
+ * - Event-based metric collection: buffers metric values and flushes on pull
+ * - Automatic HTTP endpoint: exposes GET /metrics with Prometheus text format
+ * - Node.js default metrics: process CPU, memory, event loop, garbage collection
+ * - MetricsGuard integration: optional METRICS_API_KEY authentication
+ * - Lifecycle management: registers exporter on init, cleans up on shutdown
+ *
+ * Registers PrometheusExporter globally and automatically connects it to the
+ * InstrumentationRegistry so that metric descriptors and values are forwarded
+ * to the Prometheus exporter.
+ *
+ * @example
+ * ```typescript
+ * import { PrometheusModule } from '@pawells/nestjs-prometheus';
+ *
+ * @Module({
+ *   imports: [
+ *     ConfigModule,
+ *     CommonModule,
+ *     PrometheusModule.forRoot(),  // Register module globally
+ *   ],
+ * })
+ * export class AppModule {}
+ *
+ * // Metrics are now available at: GET /metrics
+ * ```
+ */
+export declare class PrometheusModule implements OnModuleInit, OnApplicationShutdown {
+    private readonly exporter;
+    private readonly registry;
+    /**
+     * Create a global PrometheusModule with automatic registration
+     *
+     * Returns a DynamicModule that marks this module as global, enabling
+     * it to be imported once at the top level and used throughout the application.
+     *
+     * @returns DynamicModule configured as global
+     *
+     * @example
+     * ```typescript
+     * @Module({
+     *   imports: [PrometheusModule.forRoot()],
+     * })
+     * export class AppModule {}
+     * ```
+     */
+    static forRoot(): DynamicModule;
+    constructor(exporter: PrometheusExporter, registry: InstrumentationRegistry);
+    /**
+     * Initialize the module and register the Prometheus exporter
+     *
+     * Called by NestJS during module initialization. Registers the PrometheusExporter
+     * with the InstrumentationRegistry so that it receives descriptor registration
+     * events and metric values.
+     *
+     * @example
+     * ```typescript
+     * // During application startup:
+     * // 1. PrometheusModule is initialized
+     * // 2. onModuleInit() registers PrometheusExporter with InstrumentationRegistry
+     * // 3. All metrics registered with registry are now tracked by Prometheus exporter
+     * ```
+     */
+    onModuleInit(): void;
+    /**
+     * Clean up resources on application shutdown
+     *
+     * Called by NestJS during application shutdown. Calls the PrometheusExporter's
+     * shutdown method to clean up the registry and release resources.
+     *
+     * @example
+     * ```typescript
+     * // During application shutdown:
+     * // onApplicationShutdown() is called
+     * // PrometheusExporter clears registry and internal state
+     * ```
+     */
+    onApplicationShutdown(): Promise<void>;
+}
+//# sourceMappingURL=prometheus.module.d.ts.map

package/build/prometheus.module.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prometheus.module.d.ts","sourceRoot":"","sources":["../src/prometheus.module.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkB,YAAY,EAAE,qBAAqB,EAAE,KAAK,aAAa,EAAE,MAAM,gBAAgB,CAAC;AACzG,OAAO,EAAE,uBAAuB,EAAE,MAAM,wBAAwB,CAAC;AACjE,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAG9D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,qBAMa,gBAAiB,YAAW,YAAY,EAAE,qBAAqB;IAwB1E,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAxB1B;;;;;;;;;;;;;;;OAeG;WACW,OAAO,IAAI,aAAa;gBAOpB,QAAQ,EAAE,kBAAkB,EAC5B,QAAQ,EAAE,uBAAuB;IAGnD;;;;;;;;;;;;;;OAcG;IACI,YAAY,IAAI,IAAI;IAI3B;;;;;;;;;;;;OAYG;IACU,qBAAqB,IAAI,OAAO,CAAC,IAAI,CAAC;CAGnD"}

package/build/prometheus.module.js

@@ -0,0 +1,122 @@
+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 PrometheusModule_1;
+import { Global, Module } from '@nestjs/common';
+import { InstrumentationRegistry } from '@pawells/nestjs-shared';
+import { PrometheusExporter } from './prometheus.exporter.js';
+import { MetricsController } from './controllers/metrics.controller.js';
+/**
+ * Prometheus metrics module for NestJS
+ *
+ * Provides integration with @pawells/nestjs-shared InstrumentationRegistry
+ * to export metrics in Prometheus format via a `/metrics` HTTP endpoint.
+ *
+ * Features:
+ * - Event-based metric collection: buffers metric values and flushes on pull
+ * - Automatic HTTP endpoint: exposes GET /metrics with Prometheus text format
+ * - Node.js default metrics: process CPU, memory, event loop, garbage collection
+ * - MetricsGuard integration: optional METRICS_API_KEY authentication
+ * - Lifecycle management: registers exporter on init, cleans up on shutdown
+ *
+ * Registers PrometheusExporter globally and automatically connects it to the
+ * InstrumentationRegistry so that metric descriptors and values are forwarded
+ * to the Prometheus exporter.
+ *
+ * @example
+ * ```typescript
+ * import { PrometheusModule } from '@pawells/nestjs-prometheus';
+ *
+ * @Module({
+ *   imports: [
+ *     ConfigModule,
+ *     CommonModule,
+ *     PrometheusModule.forRoot(),  // Register module globally
+ *   ],
+ * })
+ * export class AppModule {}
+ *
+ * // Metrics are now available at: GET /metrics
+ * ```
+ */
+let PrometheusModule = PrometheusModule_1 = class PrometheusModule {
+    exporter;
+    registry;
+    /**
+     * Create a global PrometheusModule with automatic registration
+     *
+     * Returns a DynamicModule that marks this module as global, enabling
+     * it to be imported once at the top level and used throughout the application.
+     *
+     * @returns DynamicModule configured as global
+     *
+     * @example
+     * ```typescript
+     * @Module({
+     *   imports: [PrometheusModule.forRoot()],
+     * })
+     * export class AppModule {}
+     * ```
+     */
+    static forRoot() {
+        return {
+            module: PrometheusModule_1,
+        };
+    }
+    constructor(exporter, registry) {
+        this.exporter = exporter;
+        this.registry = registry;
+    }
+    /**
+     * Initialize the module and register the Prometheus exporter
+     *
+     * Called by NestJS during module initialization. Registers the PrometheusExporter
+     * with the InstrumentationRegistry so that it receives descriptor registration
+     * events and metric values.
+     *
+     * @example
+     * ```typescript
+     * // During application startup:
+     * // 1. PrometheusModule is initialized
+     * // 2. onModuleInit() registers PrometheusExporter with InstrumentationRegistry
+     * // 3. All metrics registered with registry are now tracked by Prometheus exporter
+     * ```
+     */
+    onModuleInit() {
+        this.registry.registerExporter(this.exporter);
+    }
+    /**
+     * Clean up resources on application shutdown
+     *
+     * Called by NestJS during application shutdown. Calls the PrometheusExporter's
+     * shutdown method to clean up the registry and release resources.
+     *
+     * @example
+     * ```typescript
+     * // During application shutdown:
+     * // onApplicationShutdown() is called
+     * // PrometheusExporter clears registry and internal state
+     * ```
+     */
+    async onApplicationShutdown() {
+        await this.exporter.shutdown();
+    }
+};
+PrometheusModule = PrometheusModule_1 = __decorate([
+    Global(),
+    Module({
+        providers: [PrometheusExporter],
+        exports: [PrometheusExporter],
+        controllers: [MetricsController],
+    }),
+    __metadata("design:paramtypes", [PrometheusExporter,
+        InstrumentationRegistry])
+], PrometheusModule);
+export { PrometheusModule };
+//# sourceMappingURL=prometheus.module.js.map

package/build/prometheus.module.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prometheus.module.js","sourceRoot":"","sources":["../src/prometheus.module.ts"],"names":[],"mappings":";;;;;;;;;;AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,EAA2D,MAAM,gBAAgB,CAAC;AACzG,OAAO,EAAE,uBAAuB,EAAE,MAAM,wBAAwB,CAAC;AACjE,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAC9D,OAAO,EAAE,iBAAiB,EAAE,MAAM,qCAAqC,CAAC;AAExE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAOI,IAAM,gBAAgB,wBAAtB,MAAM,gBAAgB;IAwBV;IACA;IAxBlB;;;;;;;;;;;;;;;OAeG;IACI,MAAM,CAAC,OAAO;QACpB,OAAO;YACN,MAAM,EAAE,kBAAgB;SACxB,CAAC;IACH,CAAC;IAED,YACkB,QAA4B,EAC5B,QAAiC;QADjC,aAAQ,GAAR,QAAQ,CAAoB;QAC5B,aAAQ,GAAR,QAAQ,CAAyB;IAChD,CAAC;IAEJ;;;;;;;;;;;;;;OAcG;IACI,YAAY;QAClB,IAAI,CAAC,QAAQ,CAAC,gBAAgB,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAC/C,CAAC;IAED;;;;;;;;;;;;OAYG;IACI,KAAK,CAAC,qBAAqB;QACjC,MAAM,IAAI,CAAC,QAAQ,CAAC,QAAQ,EAAE,CAAC;IAChC,CAAC;CACD,CAAA;AA/DY,gBAAgB;IAN5B,MAAM,EAAE;IACR,MAAM,CAAC;QACP,SAAS,EAAE,CAAC,kBAAkB,CAAC;QAC/B,OAAO,EAAE,CAAC,kBAAkB,CAAC;QAC7B,WAAW,EAAE,CAAC,iBAAiB,CAAC;KAChC,CAAC;qCAyB2B,kBAAkB;QAClB,uBAAuB;GAzBvC,gBAAgB,CA+D5B"}

package/build/test-setup.d.ts

@@ -0,0 +1,2 @@
+import 'reflect-metadata';
+//# sourceMappingURL=test-setup.d.ts.map

package/build/test-setup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-setup.d.ts","sourceRoot":"","sources":["../src/test-setup.ts"],"names":[],"mappings":"AAEA,OAAO,kBAAkB,CAAC"}

package/build/test-setup.js

@@ -0,0 +1,4 @@
+// Test setup file for vitest
+// Import reflect-metadata as required by NestJS
+import 'reflect-metadata';
+//# sourceMappingURL=test-setup.js.map

package/build/test-setup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-setup.js","sourceRoot":"","sources":["../src/test-setup.ts"],"names":[],"mappings":"AAAA,6BAA6B;AAC7B,gDAAgD;AAChD,OAAO,kBAAkB,CAAC"}