@pawells/nestjs-prometheus 1.0.0-dev.dd031b4 → 1.0.0

package/package.json

@@ -1,80 +1,41 @@
 {
-  "name": "@pawells/nestjs-prometheus",
-  "displayName": "@pawells/nestjs-prometheus",
-  "version": "1.0.0-dev.dd031b4",
-  "description": "NestJS Prometheus metrics module with endpoint controller",
-  "type": "module",
-  "main": "./build/index.js",
-  "types": "./build/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./build/index.d.ts",
-      "import": "./build/index.js"
-    }
-  },
-  "scripts": {
-    "build": "tsc --project tsconfig.build.json",
-    "typecheck": "tsc --noEmit",
-    "lint": "eslint src/",
-    "lint:fix": "eslint src/ --fix",
-    "test": "vitest run",
-    "test:coverage": "vitest --coverage",
-    "pipeline": "yarn typecheck && yarn lint && yarn test && yarn build"
-  },
-  "peerDependencies": {
-    "@nestjs/common": ">=10.0.0",
-    "@nestjs/config": ">=3.0.0",
-    "@nestjs/core": ">=10.0.0",
-    "@nestjs/throttler": ">=5.0.0",
-    "@opentelemetry/api": ">=1.0.0",
-    "class-transformer": ">=0.5.0",
-    "class-validator": ">=0.14.0",
-    "compression": ">=1.0.0",
-    "csrf-csrf": ">=3.0.0",
-    "express": ">=4.0.0",
-    "helmet": ">=7.0.0",
-    "joi": ">=17.0.0",
-    "prom-client": ">=15.0.0",
-    "rxjs": ">=7.0.0",
-    "xss": ">=1.0.0"
-  },
-  "dependencies": {
-    "@pawells/nestjs-shared": "^1.0.0"
-  },
-  "devDependencies": {
-    "@nestjs/common": "^11.0.0",
-    "@nestjs/config": "^3.3.0",
-    "@nestjs/core": "^11.0.0",
-    "@nestjs/throttler": "^6.4.0",
-    "@opentelemetry/api": "^1.9.0",
-    "class-transformer": "^0.5.1",
-    "class-validator": "^0.14.1",
-    "compression": "^1.7.4",
-    "csrf-csrf": "^3.2.0",
-    "express": "^4.21.0",
-    "helmet": "^8.0.0",
-    "joi": "^17.13.0",
-    "prom-client": "^15.1.0",
-    "reflect-metadata": "^0.2.2",
-    "rxjs": "^7.8.0",
-    "xss": "^1.0.15"
-  },
-  "engines": {
-    "node": ">=22.0.0"
-  },
-  "packageManager": "yarn@4.12.0",
-  "author": "Aaron Wells <69355326+PhillipAWells@users.noreply.github.com>",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/PhillipAWells/nestjs-common"
-  },
-  "files": [
-    "build/",
-    "README.md",
-    "LICENSE"
-  ],
-  "publishConfig": {
-    "access": "public"
-  }
+	"name": "@pawells/nestjs-prometheus",
+	"displayName": "@pawells/nestjs-prometheus",
+	"version": "1.0.0",
+	"description": "NestJS Prometheus metrics module with endpoint controller",
+	"type": "module",
+	"main": "./index.js",
+	"types": "./index.d.ts",
+	"exports": {
+		".": {
+			"types": "./index.d.ts",
+			"import": "./index.js"
+		}
+	},
+	"scripts": {
+		"build": "tsc --project tsconfig.build.json",
+		"typecheck": "tsc --noEmit",
+		"lint": "eslint src/",
+		"lint:fix": "eslint src/ --fix",
+		"test": "vitest run",
+		"test:coverage": "vitest --coverage",
+		"pipeline": "yarn typecheck && yarn lint && yarn test && yarn build"
+	},
+	"peerDependencies": {
+		"@nestjs/common": ">=10.0.0",
+		"prom-client": ">=15.0.0"
+	},
+	"dependencies": {
+		"@pawells/nestjs-shared": "1.0.0"
+	},
+	"engines": {
+		"node": ">=24.0.0"
+	},
+	"packageManager": "yarn@4.12.0",
+	"author": "Aaron Wells <69355326+PhillipAWells@users.noreply.github.com>",
+	"license": "MIT",
+	"publishConfig": {
+		"access": "public"
+	},
+	"module": "./index.js"
 }

package/build/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2026 Aaron Wells
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.

package/build/README.md

@@ -1,290 +0,0 @@
-# NestJS Prometheus Module
-
-[![GitHub Release](https://img.shields.io/github/v/release/PhillipAWells/nestjs-common)](https://github.com/PhillipAWells/nestjs-common/releases)
-[![CI](https://github.com/PhillipAWells/nestjs-common/actions/workflows/ci.yml/badge.svg)](https://github.com/PhillipAWells/nestjs-common/actions/workflows/ci.yml)
-[![npm version](https://img.shields.io/npm/v/@pawells/nestjs-prometheus.svg?style=flat)](https://www.npmjs.com/package/@pawells/nestjs-prometheus)
-[![Node](https://img.shields.io/badge/node-%3E%3D24-brightgreen)](https://nodejs.org)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
-[![GitHub Sponsors](https://img.shields.io/github/sponsors/PhillipAWells?style=social)](https://github.com/sponsors/PhillipAWells)
-
-Prometheus metrics exporter for NestJS with `/metrics` endpoint, integrated with `@pawells/nestjs-shared` InstrumentationRegistry for event-based metric collection.
-
-## Installation
-
-```bash
-yarn add @pawells/nestjs-prometheus prom-client
-```
-
-## Requirements
-
-- **Node.js**: >= 24.0.0
-- **NestJS**: >= 10.0.0
-- **prom-client**: >= 15.0.0
-- **@pawells/nestjs-shared**: same version
-
-## Peer Dependencies
-
-```json
-{
-  "@nestjs/common": ">=10.0.0",
-  "prom-client": ">=15.0.0"
-}
-```
-
-## Quick Start
-
-### Module Setup
-
-Import `PrometheusModule` in your application module:
-
-```typescript
-import { Module } from '@nestjs/common';
-import { PrometheusModule } from '@pawells/nestjs-prometheus';
-
-@Module({
-  imports: [PrometheusModule.forRoot()],
-})
-export class AppModule {}
-```
-
-This automatically registers the PrometheusExporter globally and exposes metrics at `GET /metrics` in Prometheus text format.
-
-## How It Works
-
-The module integrates with `@pawells/nestjs-shared`'s `InstrumentationRegistry` to:
-
-1. **Register descriptors**: When a metric is registered with the InstrumentationRegistry, PrometheusExporter pre-creates the corresponding prom-client instrument (Counter, Gauge, or Histogram)
-2. **Buffer values**: Metric values are buffered in memory as they are recorded
-3. **Flush on pull**: When the `/metrics` endpoint is scraped, all pending values are flushed into prom-client instruments and returned in Prometheus text format
-4. **Cleanup**: On shutdown, the registry and internal caches are cleared
-
-This event-based design decouples metric recording from Prometheus scraping, preventing performance overhead on high-frequency metrics.
-
-## The /metrics Endpoint
-
-The module automatically exposes:
-
-- **Endpoint**: `GET /metrics`
-- **Content-Type**: `text/plain; version=0.0.4; charset=utf-8`
-- **Headers**: `X-Robots-Tag: noindex, nofollow` (prevents indexing)
-- **Authentication**: Protected by `MetricsGuard` from `@pawells/nestjs-shared`
-
-### Authentication
-
-The `/metrics` endpoint respects the optional `METRICS_API_KEY` environment variable:
-
-- If **not set**: All requests are allowed
-- If **set**: Requires Bearer token, X-API-Key header, or `?key=` query parameter
-
-```bash
-# With METRICS_API_KEY=secret123
-curl -H "Authorization: Bearer secret123" http://localhost:3000/metrics
-curl -H "X-API-Key: secret123" http://localhost:3000/metrics
-curl "http://localhost:3000/metrics?key=secret123"
-```
-
-## Exported Metrics
-
-The exporter provides three types of metrics:
-
-### Node.js Default Metrics
-Automatically collected via `prom-client`:
-- `process_cpu_user_seconds_total` - User CPU time
-- `process_cpu_system_seconds_total` - System CPU time
-- `process_resident_memory_bytes` - RSS memory usage
-- `nodejs_eventloop_delay_seconds` - Event loop delay
-- `nodejs_gc_duration_seconds` - Garbage collection duration
-- And many more...
-
-### Custom Metrics
-Applications can register custom metrics with the InstrumentationRegistry and they will be exported automatically.
-
-### Example Metrics Output
-
-```
-# HELP process_cpu_user_seconds_total Total user CPU time spent in seconds.
-# TYPE process_cpu_user_seconds_total counter
-process_cpu_user_seconds_total 12.345
-
-# HELP http_request_duration_seconds HTTP request duration in seconds
-# TYPE http_request_duration_seconds histogram
-http_request_duration_seconds_bucket{le="0.001",method="GET",route="/api/users"} 0
-http_request_duration_seconds_bucket{le="0.01",method="GET",route="/api/users"} 5
-http_request_duration_seconds_bucket{le="0.1",method="GET",route="/api/users"} 42
-```
-
-## Accessing Metrics
-
-### Via Prometheus Scraper
-
-Configure Prometheus to scrape your application:
-
-```yaml
-# prometheus.yml
-scrape_configs:
-  - job_name: 'my-app'
-    static_configs:
-      - targets: ['localhost:3000']
-    metrics_path: '/metrics'
-    scrape_interval: 15s
-    # Optional: Add auth if METRICS_API_KEY is set
-    authorization:
-      credentials: 'secret123'
-      type: Bearer
-```
-
-### Manual HTTP Request
-
-```bash
-curl http://localhost:3000/metrics
-
-# With authentication
-curl -H "Authorization: Bearer secret123" http://localhost:3000/metrics
-```
-
-## Integration with @pawells/nestjs-shared HTTPMetricsInterceptor
-
-Combine PrometheusModule with HTTPMetricsInterceptor for automatic HTTP metrics:
-
-```typescript
-import { Module } from '@nestjs/common';
-import { APP_INTERCEPTOR } from '@nestjs/core';
-import { PrometheusModule } from '@pawells/nestjs-prometheus';
-import { HTTPMetricsInterceptor } from '@pawells/nestjs-shared';
-
-@Module({
-  imports: [PrometheusModule.forRoot()],
-  providers: [
-    {
-      provide: APP_INTERCEPTOR,
-      useClass: HTTPMetricsInterceptor,
-    },
-  ],
-})
-export class AppModule {}
-```
-
-This automatically tracks:
-- **Request count** by method and route
-- **Request duration** (histogram with default buckets)
-- **Response status codes**
-- **Path normalization** (dynamic segments like UUIDs are normalized to `:id`)
-
-## Module API
-
-### PrometheusModule.forRoot()
-
-Returns a DynamicModule configured as global, enabling single import at the top level:
-
-```typescript
-@Module({
-  imports: [PrometheusModule.forRoot()],
-})
-export class AppModule {}
-```
-
-## Class Reference
-
-### PrometheusModule
-
-The main NestJS module. Implements `OnModuleInit` and `OnApplicationShutdown`.
-
-**Static Methods:**
-- `forRoot()` - Create global module with automatic registration
-
-**Lifecycle Methods:**
-- `onModuleInit()` - Registers the exporter with InstrumentationRegistry
-- `onApplicationShutdown()` - Calls exporter.shutdown() to clean up resources
-
-### PrometheusExporter
-
-Implements `IMetricsExporter` from `@pawells/nestjs-shared`.
-
-**Properties:**
-- `supportsEventBased` - `true` (buffers metric values)
-- `supportsPull` - `true` (supports pull-based retrieval)
-
-**Methods:**
-- `onDescriptorRegistered(descriptor: MetricDescriptor)` - Called when a metric is registered; creates the appropriate prom-client instrument
-- `onMetricRecorded(value: MetricValue)` - Buffers a metric value to be flushed on next pull
-- `getMetrics(): Promise<string>` - Flushes pending values and returns metrics in Prometheus text format
-- `shutdown(): Promise<void>` - Clears registry and releases resources
-
-**Internals:**
-- Maintains a prom-client `Registry` for instrument management
-- Buffers metric values per metric (max 1000 per metric to prevent unbounded memory growth)
-- Atomically swaps pending arrays during flush to prevent data loss on concurrent records
-
-### MetricsController
-
-HTTP controller with single endpoint.
-
-**Methods:**
-- `getMetrics(response: Response): Promise<void>` - GET /metrics, protected by MetricsGuard
-
-## Advanced Patterns
-
-### Custom Metrics via InstrumentationRegistry
-
-Register custom metrics with `@pawells/nestjs-shared`:
-
-```typescript
-import { Injectable } from '@nestjs/common';
-import { InstrumentationRegistry } from '@pawells/nestjs-shared';
-
-@Injectable()
-export class OrderService {
-  constructor(private readonly registry: InstrumentationRegistry) {}
-
-  trackOrderCreation(status: string) {
-    // Register descriptor (once)
-    this.registry.registerDescriptor({
-      name: 'orders_created_total',
-      type: 'counter',
-      help: 'Total orders created',
-      labelNames: ['status'],
-    });
-
-    // Record value
-    this.registry.recordMetric({
-      descriptor: { name: 'orders_created_total' } as MetricDescriptor,
-      value: 1,
-      labels: { status },
-    });
-  }
-}
-```
-
-When metrics are pulled from `/metrics`, they are automatically exported in Prometheus format.
-
-## Metric Types
-
-The PrometheusExporter supports these metric types (as defined in MetricDescriptor):
-
-| Type | Mapping | Usage |
-|------|---------|-------|
-| `counter` | prom-client Counter | Monotonically increasing values (e.g., request count) |
-| `gauge` | prom-client Gauge | Point-in-time values (e.g., memory usage) |
-| `updown_counter` | prom-client Gauge | Values that can increase or decrease |
-| `histogram` | prom-client Histogram | Distribution of values (e.g., request latency) |
-
-### Gauge and UpDownCounter Accumulation Behavior
-
-**Gauge (`gauge`)**: Records a point-in-time snapshot value. Each recorded value overwrites the previous one for a given label set.
-
-**UpDownCounter (`updown_counter`)**: Accumulates values across scrapes. The PrometheusExporter maintains a running-total Map (`gaugeValues`) for each updown_counter metric, keyed by normalized label set. When a value is recorded:
-1. All values for the same label set within a single scrape interval are accumulated together
-2. The accumulated sum is then added to the persistent running total
-3. This running total persists across Prometheus scrapes (resets only on exporter shutdown)
-
-Example: If you record `+5` then `+3` for the same labels in one scrape cycle, the running total increases by `8` (not just `3`). On the next scrape, if you record `+2`, the running total increases by another `2`.
-
-## Related Packages
-
-- **[@pawells/nestjs-shared](https://www.npmjs.com/package/@pawells/nestjs-shared)** - Foundation: InstrumentationRegistry, HTTPMetricsInterceptor, MetricsGuard
-- **[@pawells/nestjs-open-telemetry](https://www.npmjs.com/package/@pawells/nestjs-open-telemetry)** - OpenTelemetry tracing and metrics integration
-- **[prom-client](https://github.com/siimon/prom-client)** - Official Prometheus client library for Node.js
-
-## License
-
-MIT

package/build/package.json

@@ -1,63 +0,0 @@
-{
-  "name": "@pawells/nestjs-prometheus",
-  "displayName": "@pawells/nestjs-prometheus",
-  "version": "1.0.0-dev.dd031b4",
-  "description": "NestJS Prometheus metrics module with endpoint controller",
-  "type": "module",
-  "main": "./build/index.js",
-  "types": "./build/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./build/index.d.ts",
-      "import": "./build/index.js"
-    }
-  },
-  "scripts": {
-    "build": "tsc --project tsconfig.build.json",
-    "typecheck": "tsc --noEmit",
-    "lint": "eslint src/",
-    "lint:fix": "eslint src/ --fix",
-    "test": "vitest run",
-    "test:coverage": "vitest --coverage",
-    "pipeline": "yarn typecheck && yarn lint && yarn test && yarn build"
-  },
-  "peerDependencies": {
-    "@nestjs/common": ">=10.0.0",
-    "@nestjs/config": ">=3.0.0",
-    "@nestjs/core": ">=10.0.0",
-    "@nestjs/throttler": ">=5.0.0",
-    "@opentelemetry/api": ">=1.0.0",
-    "class-transformer": ">=0.5.0",
-    "class-validator": ">=0.14.0",
-    "compression": ">=1.0.0",
-    "csrf-csrf": ">=3.0.0",
-    "express": ">=4.0.0",
-    "helmet": ">=7.0.0",
-    "joi": ">=17.0.0",
-    "prom-client": ">=15.0.0",
-    "rxjs": ">=7.0.0",
-    "xss": ">=1.0.0"
-  },
-  "dependencies": {
-    "@pawells/nestjs-shared": "^1.0.0"
-  },
-  "engines": {
-    "node": ">=22.0.0"
-  },
-  "packageManager": "yarn@4.12.0",
-  "author": "Aaron Wells <69355326+PhillipAWells@users.noreply.github.com>",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/PhillipAWells/nestjs-common"
-  },
-  "files": [
-    "build/",
-    "README.md",
-    "LICENSE"
-  ],
-  "publishConfig": {
-    "access": "public"
-  },
-  "module": "./index.js"
-}