Merge pull request #25 from BreizhHardware/dev

chore(deps): Update qs to fix security issue

.devcontainer/devcontainer.json

@@ -0,0 +1,12 @@
+{
+    "name": "Node.js 24",
+    "image": "mcr.microsoft.com/devcontainers/base:ubuntu",
+    "features": {
+        "ghcr.io/devcontainers/features/node:1": {
+            "nodeGypDependencies": true,
+            "version": "lts",
+            "nvmVersion": "latest"
+        },
+        "ghcr.io/devcontainers/features/git-lfs:1": {}
+    }
+}

.eslintrc

@@ -1,42 +0,0 @@
-{
-    "env": {
-        "node": true,
-        "es6": true
-    },
-
-    "extends": "eslint:recommended",
-
-    "rules": {
-        "no-cond-assign": 0,
-        "no-constant-condition": 0,
-        "no-empty": 0,
-        "no-fallthrough": 0,
-        "no-unused-vars": 1,
-        "no-console": 1,
-
-        "semi": 2,
-        "curly": 2,
-        "consistent-this": [2, "self"],
-        "indent": [ 2, 4, { "SwitchCase": 1 } ],
-        "linebreak-style": [2, "unix"],
-        "no-nested-ternary": 2,
-
-        "new-parens": 2,
-        "no-dupe-class-members": 2,
-        "require-yield": 2,
-        "arrow-spacing": 1,
-        "no-var": 2,
-
-        "no-multi-spaces": 1,
-        "space-return-throw-case": 0,
-        "space-infix-ops": [1, {"int32Hint": false}],
-        "brace-style": 1,
-        "space-before-blocks": 1,
-        "operator-linebreak": [1, "before"],
-        "no-unneeded-ternary": 1,
-        "no-lonely-if": 1,
-        "key-spacing": 1,
-        "quotes": [1, "double", "avoid-escape"],
-        "no-trailing-spaces": [1, { "skipBlankLines": true }]
-    }
-}

.github/dependabot.yml

@@ -0,0 +1,12 @@
+version: 2
+updates:
+  - package-ecosystem: "npm" 
+    directory: "/" 
+    schedule:
+      interval: "weekly"
+    target-branch: "dev"
+  - package-ecosystem: "github-actions" 
+    directory: "/.github/workflows" 
+    schedule:
+      interval: "weekly"
+    target-branch: "dev"

.github/workflows/audit.yml

@@ -0,0 +1,42 @@
+name: Security Audit
+
+on:
+  push:
+    branches: [main, dev]
+  pull_request:
+    branches:
+      - '**'
+  schedule:
+    - cron: '0 8 * * *' 
+  workflow_dispatch: 
+
+jobs:
+  audit:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      issues: write
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Run security audit
+        id: audit
+        run: npm audit --audit-level moderate
+        continue-on-error: true
+
+      - name: Create issue on failure
+        if: steps.audit.outcome == 'failure'
+        uses: actions/github-script@v8
+        with:
+          script: |
+            github.rest.issues.create({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              title: 'Security Audit Failed',
+              body: 'The daily security audit has failed. Please check the workflow run for details: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}',
+              labels: ['security', 'audit']
+            });

.github/workflows/release.yml

@@ -0,0 +1,72 @@
+name: Release
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [18, 20, 22, 24, latest]
+    steps:
+      - uses: actions/checkout@v6
+      - name: Use Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v6
+        with:
+          node-version: ${{ matrix.node-version }}
+      - run: npm install prom-client
+      - run: npm install
+      - run: npm run lint
+      - run: npm test
+      - run: npm run test-types
+      - name: Generate coverage
+        run: make coverage
+      - name: Upload coverage to Coveralls
+        uses: coverallsapp/github-action@v2
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          file: coverage/lcov.info
+
+  publish:
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - name: Use Node.js 18
+        uses: actions/setup-node@v6
+        with:
+          node-version: 18
+          registry-url: 'https://registry.npmjs.org'
+      - run: npm install
+      - run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+  release:
+    needs: publish
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+      - name: Get version
+        id: get_version
+        run: echo "version=$(node -p "require('./package.json').version")" >> $GITHUB_OUTPUT
+      - name: Generate Changelog
+        run: |
+          # Simple changelog generation
+          echo "# Changelog" > CHANGELOG.md
+          git log --oneline --pretty=format:"- %s" $(git describe --tags --abbrev=0 2>/dev/null || echo "HEAD~1")..HEAD >> CHANGELOG.md
+      - name: Create Release
+        uses: actions/create-release@v1
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          tag_name: v${{ steps.get_version.outputs.version }}
+          release_name: Release v${{ steps.get_version.outputs.version }}
+          body_path: CHANGELOG.md
+          draft: false
+          prerelease: false

.github/workflows/test.yml

@@ -0,0 +1,54 @@
+name: CI-Tests
+
+on:
+  push:
+    branches:
+      - main
+      - dev
+  pull_request:
+    branches:
+      - main
+      - dev
+
+jobs:
+    test:
+        runs-on: ubuntu-latest
+        strategy:
+            matrix:
+                node-version: [18, 20, 22, 24, latest]
+        steps:
+            - uses: actions/checkout@v6
+            - name: Use Node.js ${{ matrix.node-version }}
+              uses: actions/setup-node@v6
+              with:
+                  node-version: ${{ matrix.node-version }}
+            - run: npm install prom-client
+            - run: npm install
+            - run: npm run lint
+            - run: npm test
+            - run: npm run test-types
+
+    codeql:
+        name: CodeQL Analysis
+        runs-on: ubuntu-latest
+        steps:
+            - uses: actions/checkout@v6
+            - name: Initialize CodeQL
+              uses: github/codeql-action/init@v4
+              with:
+                  languages: javascript
+            - name: Perform CodeQL Analysis
+              uses: github/codeql-action/analyze@v4
+
+    audit:
+        name: Audit Dependencies
+        runs-on: ubuntu-latest
+        steps:
+            - uses: actions/checkout@v6
+            - name: Use Node.js 18
+              uses: actions/setup-node@v6
+              with:
+                node-version: 18
+            - run: npm install
+            - name: Audit Dependencies
+              run: npm audit --audit-level=moderate

.gitignore

@@ -1,3 +1,6 @@
 .npmrc
 node_modules
 coverage
+/.vscode
+.env
+.nyc_output

.npmignore

@@ -1,6 +0,0 @@
-advanced-example.js
-docker-compose.yml
-spec
-.travis.yml
-.eslintrc
-coverage

.travis.yml

@@ -1,5 +1,11 @@
 language: node_js
 node_js:
-    - "6"
-    - "5"
-    - "4"
+    - "18"
+notifications:
+    email: false
+before_install:
+    - npm install prom-client
+script:
+    - npm run lint
+    - npm test
+    - npm run test-types

Makefile

@@ -1,18 +1,12 @@
 .PHONY: coverage
 
 test:
-	./node_modules/jasme/run.js
+	npm test
 lint:
-	node_modules/eslint/bin/eslint.js src
+	npx eslint src
+	npm run dtslint-next
 coverage:
-	node_modules/istanbul/lib/cli.js cover \
-		-i 'src/*' \
-		--include-all-sources \
-		--dir coverage \
-		node_modules/jasme/run.js
+	npx nyc --include src --reporter=lcov --reporter=text node_modules/jasme/run.js
 
 coveralls: coverage
-ifndef COVERALLS_REPO_TOKEN
-	$(error COVERALLS_REPO_TOKEN is undefined)
-endif
-	node_modules/coveralls/bin/coveralls.js < coverage/lcov.info
+	npx nyc report --reporter=text-lcov | npx coveralls

README.md

@@ -1,28 +1,31 @@
-[![build status](https://travis-ci.org/jochen-schweizer/express-prom-bundle.png)](https://travis-ci.org/jochen-schweizer/express-prom-bundle) [![Coverage Status](https://coveralls.io/repos/github/jochen-schweizer/express-prom-bundle/badge.svg?branch=master)](https://coveralls.io/github/jochen-schweizer/express-prom-bundle?branch=master) [![license](https://img.shields.io/github/license/mashape/apistatus.svg?maxAge=2592000)](https://www.tldrlegal.com/l/mit)
+[![CI](https://github.com/BreizhHardware/express-prom-bundle/actions/workflows/release.yml/badge.svg)](https://github.com/BreizhHardware/express-prom-bundle/actions/workflows/release.yml) [![Coverage Status](https://coveralls.io/repos/github/BreizhHardware/express-prom-bundle/badge.svg?branch=main)](https://coveralls.io/github/BreizhHardware/express-prom-bundle?branch=main) [![license](https://img.shields.io/github/license/mashape/apistatus.svg?maxAge=2592000)](https://www.tldrlegal.com/l/mit) [![NPM version](https://badge.fury.io/js/%40breizhhardware%2Fexpress-prom-bundle.png)](http://badge.fury.io/js/%40breizhhardware%2Fexpress-prom-bundle)
 
 # express prometheus bundle
 
-express middleware with popular prometheus metrics in one bundle.
+Express middleware with popular prometheus metrics in one bundle. It's also compatible with koa v1 and v2 (see below). This package is a fork from the one from 
+[Jochen Schweizer](https://github.com/jochen-schweizer/express-prom-bundle).
 
-Internally it uses **prom-client**. See: https://github.com/siimon/prom-client
+This library uses **prom-client v15+** as a peer dependency. See: https://github.com/siimon/prom-client
+
+If you need a support for older versions of prom-client (v12-v14), downgrade to express-prom-bundle v6.6.0
 
 Included metrics:
-    
+
 * `up`: normally is just 1
-* `nodejs_memory_heap_total_bytes` and `nodejs_memory_heap_used_bytes`
-* `http_request_seconds`: http latency histogram labeled with `status_code`
+* `http_request_duration_seconds`: http latency histogram/summary labeled with `status_code`, `method` and `path`
 
 ## Install
 
 ```
-npm install express-prom-bundle
+npm install prom-client @breizhhardware/express-prom-bundle
 ```
 
-## Usage
+## Sample Usage
 
 ```javascript
-const promBundle = require("express-prom-bundle"),
-const metricsMiddleware = promBundle({/* options */ });
+const promBundle = require("@breizhhardware/express-prom-bundle");
+const app = require("express")();
+const metricsMiddleware = promBundle({includeMethod: true});
 
 app.use(metricsMiddleware);
 app.use(/* your middleware */);
@@ -34,7 +37,7 @@ app.listen(3000);
 
 **ALERT!**
 
-The order in wich the routes are registered is important, since
+The order in which the routes are registered is important, since
 **only the routes registered after the express-prom-bundle will be measured**
 
 You can use this to your advantage to bypass some of the routes.
@@ -42,33 +45,155 @@ See the example below.
 
 ## Options
 
- * **prefix**:  prefix added to every metric name
- * **whitelist**, **blacklist**: array of strings or regexp specifying which metrics to include/exclude
- * **buckets**: buckets used for `http_request_seconds` histogram
- * **excludeRoutes**: array of strings or regexp specifying which routes should be skipped for `http_request_seconds` metric. It uses `req.path` as subject when checking
+Which labels to include in `http_request_duration_seconds` metric:
 
-## Example
+* **includeStatusCode**: HTTP status code (200, 400, 404 etc.), default: **true**
+* **includeMethod**: HTTP method (GET, PUT, ...), default: **false**
+* **includePath**: URL path (see important details below), default: **false**
+* **customLabels**: an object containing extra labels, e.g. ```{project_name: 'hello_world'}```.
+  Most useful together with **transformLabels** callback, otherwise it's better to use native Prometheus relabeling.
+* **includeUp**: include an auxiliary "up"-metric which always returns 1, default: **true**
+* **metricsPath**: replace the `/metrics` route with a **regex** or exact **string**. Note: it is highly recommended to just stick to the default
+* **metricType**: histogram/summary selection. See more details below
+* **httpDurationMetricName**: Allows you change the name of HTTP duration metric, default: **`http_request_duration_seconds`**.
+* **upMetricName**: Allows you change the name of up metric, default: **`up`**.
+
+### metricType option ###
+
+Two metric types are supported for `http_request_duration_seconds` metric:
+* [histogram](https://prometheus.io/docs/concepts/metric_types/#histogram) (default)
+* [summary](https://prometheus.io/docs/concepts/metric_types/#summary)
+
+Additional options for **histogram**:
+* **buckets**: buckets used for the `http_request_duration_seconds` histogram
+
+Additional options for **summary**:
+* **percentiles**: percentiles used for `http_request_duration_seconds` summary
+* **ageBuckets**: ageBuckets configures how many buckets we have in our sliding window for the summary
+* **maxAgeSeconds**: the maxAgeSeconds will tell how old a bucket can be before it is reset
+* **pruneAgedBuckets**: When enabled, timed out buckets will be removed entirely. By default, buckets are reset to 0.
+
+### Transformation callbacks ###
+
+* **normalizePath**: `function(req)`  or `Array`
+  * if function is provided, then it should generate path value from express `req`
+  * if array is provided, then it should be an array of tuples `[regex, replacement]`. The `regex` can be a string and is automatically converted into JS regex.
+  * ... see more details in the section below
+* **urlValueParser**: options passed when instantiating [url-value-parser](https://github.com/disjunction/url-value-parser).
+  This is the easiest way to customize which parts of the URL should be replaced with "#val".
+  See the [docs](https://github.com/disjunction/url-value-parser) of url-value-parser module for details.
+* **formatStatusCode**: `function(res)` producing final status code from express `res` object, e.g. you can combine `200`, `201` and `204` to just `2xx`.
+* **transformLabels**: `function(labels, req, res)` transforms the **labels** object, e.g. setting dynamic values to **customLabels**
+* **urlPathReplacement**: replacement string for the values (default: "#val")
+
+### Other options ###
+
+* **autoregister**: if `/metrics` endpoint should be registered (default: **true**)
+* **promClient**: options for promClient startup, e.g. **collectDefaultMetrics**. This option was added
+  to keep `express-prom-bundle` runnable using confit (e.g. with kraken.js) without writing any JS code,
+  see [advanced example](https://github.com/jochen-schweizer/express-prom-bundle/blob/master/advanced-example.js)
+* **promRegistry**: Optional `promClient.Registry` instance to attach metrics to. Defaults to global `promClient.register`.
+* **metricsApp**: Allows you to attach the metrics endpoint to a different express app. You probably want to use it in combination with `autoregister: false`.
+* **bypass**: An object that takes onRequest and onFinish callbacks that determines whether the given request should be excluded in the metrics. Default:
+
+  ```js
+  {
+    onRequest: (req) => false,
+    onFinish: (req, res) => false
+  }
+  ```
+
+  `onRequest` is run directly in the middleware chain, before the request is processed. `onFinish` is run after the request has been processed, and has access to the express response object in addition to the request object. Both callbacks are optional, and if one or both returns true the request is excluded.
+
+  As a shorthand, just the onRequest callback can be used instead of the object.
+
+
+### More details on includePath option
+
+Let's say you want to have  latency statistics by URL path,
+e.g. separate metrics for `/my-app/user/`, `/products/by-category` etc.
+
+Just taking `req.path` as a label value won't work as IDs are often part of the URL,
+like `/user/12352/profile`. So what we actually need is a path template.
+The module tries to figure out what parts of the path are values or IDs,
+and what is an actual path. The example mentioned before would be
+normalized to `/user/#val/profile` and that will become the value for the label.
+These conversions are handled by `normalizePath` function.
+
+You can extend this magical behavior by providing
+additional RegExp rules to be performed,
+or override `normalizePath` with your own function.
+
+#### Example 1 (add custom RegExp):
+
+```javascript
+app.use(promBundle({
+  normalizePath: [
+    // collect paths like "/customer/johnbobson" as just one "/custom/#name"
+    ['^/customer/.*', '/customer/#name'],
+
+    // collect paths like "/bobjohnson/order-list" as just one "/#name/order-list"
+    ['^.*/order-list', '/#name/order-list']
+  ],
+  urlValueParser: {
+    minHexLength: 5,
+    extraMasks: [
+      'ORD[0-9]{5,}' // replace strings like ORD1243423, ORD673562 as #val
+    ]
+  }
+}));
+```
+
+#### Example 2 (override normalizePath function):
+
+```javascript
+app.use(promBundle(/* options? */));
+
+// let's reuse the existing one and just add some
+// functionality on top
+const originalNormalize = promBundle.normalizePath;
+promBundle.normalizePath = (req, opts) => {
+  const path = originalNormalize(req, opts);
+  // count all docs as one path, but /docs/login as a separate one
+  return (path.match(/^\/docs/) && !path.match(/^\/login/)) ? '/docs/*' : path;
+};
+```
+
+For more details:
+ * [url-value-parser](https://www.npmjs.com/package/url-value-parser) - magic behind automatic path normalization
+ * [normalizePath.js](https://github.com/jochen-schweizer/express-prom-bundle/blob/master/src/normalizePath.js) - source code for path processing
+
+
+#### Example 3 (return express route definition):
+
+```javascript
+app.use(promBundle(/* options? */));
+
+promBundle.normalizePath = (req, opts) => {
+  // Return the path of the express route (i.e. /v1/user/:id or /v1/timer/automated/:userid/:timerid")
+  return req.route?.path ?? "NULL";
+};
+```
+
+## express example
 
 setup std. metrics but exclude `up`-metric:
 
 ```javascript
-"use strict";
-
-const express = require("express"),
-    app = express(),
-    promBundle = require("express-prom-bundle");
-
+const express = require("express");
+const app = express();
+const promBundle = require("@breizhhardware/express-prom-bundle");
 
 // calls to this route will not appear in metrics
 // because it's applied before promBundle
 app.get("/status", (req, res) => res.send("i am healthy"));
 
-app.use(promBundle({
-    prefix: "demo_app:something",
-    excludeRoutes: ["/foo"]
-}));
+// register metrics collection for all routes
+// ... except those starting with /foo
+app.use("/((?!foo))*", promBundle({includePath: true}));
 
-// this call will NOT appear in metrics, because it matches excludeRoutes
+// this call will NOT appear in metrics,
+// because express will skip the metrics middleware
 app.get("/foo", (req, res) => res.send("bar"));
 
 // calls to this route will appear in metrics
@@ -79,6 +204,96 @@ app.listen(3000);
 
 See an [advanced example on github](https://github.com/jochen-schweizer/express-prom-bundle/blob/master/advanced-example.js)
 
+## koa v2 example
+
+```javascript
+const promBundle = require("@breizhhardware/express-prom-bundle");
+const Koa = require("koa");
+const c2k = require("koa-connect");
+const metricsMiddleware = promBundle({/* options */ });
+
+const app = new Koa();
+
+app.use(c2k(metricsMiddleware));
+app.use(/* your middleware */);
+app.listen(3000);
+```
+
+## using with cluster
+
+You'll need to use an additional **clusterMetrics()** middleware.
+
+In the example below the master process will expose an API with a single endpoint `/metrics`
+which returns an aggregate of all metrics from all the workers.
+
+``` javascript
+const cluster = require('cluster');
+const promBundle = require('@breizhhardware/express-prom-bundle');
+const promClient = require('prom-client');
+const numCPUs = Math.max(2, require('os').cpus().length);
+const express = require('express');
+
+if (cluster.isMaster) {
+    for (let i = 1; i < numCPUs; i++) {
+        cluster.fork();
+    }
+
+    const metricsApp = express();
+    metricsApp.use('/metrics', promBundle.clusterMetrics());
+    metricsApp.listen(9999);
+
+    console.log('cluster metrics listening on 9999');
+    console.log('call localhost:9999/metrics for aggregated metrics');
+} else {
+    new promClient.AggregatorRegistry();
+    const app = express();
+    app.use(promBundle({
+        autoregister: false, // disable /metrics for single workers
+        includeMethod: true
+    }));
+    app.use((req, res) => res.send(`hello from pid ${process.pid}\n`));
+    app.listen(3000);
+    console.log(`worker ${process.pid} listening on 3000`);
+}
+```
+
+## using with kraken.js
+
+Here is meddleware config sample, which can be used in a standard **kraken.js** application.
+In this case the stats for URI paths and HTTP methods are collected separately,
+while replacing all HEX values starting from 5 characters and all IP addresses in the path as #val.
+
+```json
+{
+  "middleware": {
+    "expressPromBundle": {
+      "route": "/((?!status|favicon.ico|robots.txt))*",
+      "priority": 0,
+      "module": {
+        "name": "express-prom-bundle",
+        "arguments": [
+          {
+            "includeMethod": true,
+            "includePath": true,
+            "buckets": [0.1, 1, 5],
+            "promClient": {
+              "collectDefaultMetrics": {
+              }
+            },
+            "urlValueParser": {
+              "minHexLength": 5,
+              "extraMasks": [
+                "^[0-9]+\\.[0-9]+\\.[0-9]+\\.[0-9]+$"
+              ]
+            }
+          }
+        ]
+      }
+    }
+  }
+}
+```
+
 ## License
 
-MIT
+MIT

SECURITY.md

@@ -0,0 +1,12 @@
+# Security Policy
+
+## Supported Versions
+
+| Version | Supported          |
+| ------- | ------------------ |
+| >= 8.0.x| :white_check_mark: |
+| < 8.0.0 | :x:                |
+
+## Reporting a Vulnerability
+
+Please use [GitHub's private vulnerability reporting](https://github.com/breizhhardware/express-prom-bundle/security/advisories/new) to report a vulnerability.

advanced-example.js

@@ -1,38 +1,61 @@
-"use strict";
+'use strict';
 
-const express = require("express");
+const express = require('express');
 const app = express();
-const promBundle = require("express-prom-bundle");
+const promClient = require('prom-client');
+
+// replace this with require('.') when running from library code
+const promBundle = require('express-prom-bundle');
 
 const bundle = promBundle({
-    prefix: "demo_app:something:",
-    blacklist: [/up/],
-    buckets: [0.1, 0.4, 0.7]
+  buckets: [0.1, 0.4, 0.7],
+  includeMethod: true,
+  includePath: true,
+  customLabels: {year: null},
+  transformLabels: labels => Object.assign(labels, {year: new Date().getFullYear()}),
+  metricsPath: '/prometheus',
+  promClient: {
+    collectDefaultMetrics: {
+    }
+  },
+  urlValueParser: {
+    minHexLength: 5,
+    extraMasks: [
+      "^[0-9]+\\.[0-9]+\\.[0-9]+$", // replace dot-separated dates with #val, (regex as string)
+      /^[0-9]+\-[0-9]+\-[0-9]+$/ // replace dash-separated dates with #val (actual regex)
+    ]
+  },
+  normalizePath: [
+    ['^/foo', '/example'] // replace /foo with /example
+  ]
 });
 
 app.use(bundle);
 
 // native prom-client metric (no prefix)
-const c1 = new bundle.promClient.Counter("c1", "c1 help");
+const c1 = new promClient.Counter({name: 'c1', help: 'c1 help'});
 c1.inc(10);
 
-// create metric using factory (w/ prefix)
-const c2 = bundle.factory.newCounter("c2", "c2 help");
-c2.inc(20);
-
-app.get("/foo", (req, res) => {
-    setTimeout(() => {
-        res.send("foo response\n");
-    }, 500);
+app.get('/foo/:id', (req, res) => {
+  setTimeout(() => {
+    res.send('foo response\n');
+  }, 500);
 });
-app.get("/bar", (req, res) => res.send("bar response\n"));
+app.delete('/foo/:id', (req, res) => {
+  setTimeout(() => {
+    res.send('foo deleted\n');
+  }, 300);
+});
+app.get('/bar', (req, res) => res.send('bar response\n'));
 
-app.listen(3000, () => console.log("listening on 3000")); // eslint-disable-line
-
-/*
+app.listen(3000, () => console.info(  // eslint-disable-line
+  `listening on 3000
 test in shell console:
 
-curl localhost:3000/foo
+curl localhost:3000/foo/1234
+curl localhost:3000/foo/09.08.2018
+curl -X DELETE localhost:3000/foo/5432
 curl localhost:3000/bar
-curl localhost:3000/metrics
-*/
+curl localhost:3000/prometheus
+`
+));

eslint.config.mjs

@@ -0,0 +1,77 @@
+import { defineConfig } from "eslint/config";
+import globals from "globals";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import js from "@eslint/js";
+import { FlatCompat } from "@eslint/eslintrc";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const compat = new FlatCompat({
+    baseDirectory: __dirname,
+    recommendedConfig: js.configs.recommended,
+    allConfig: js.configs.all
+});
+
+export default defineConfig([{
+    extends: compat.extends("eslint:recommended"),
+
+    languageOptions: {
+        globals: {
+            ...globals.node,
+            app: true,
+            fetch: true,
+        },
+
+        ecmaVersion: 6,
+        sourceType: "module",
+    },
+
+    rules: {
+        indent: [1, 2],
+        "array-bracket-spacing": [2, "never"],
+        "block-scoped-var": 2,
+        "brace-style": [2, "1tbs"],
+        "computed-property-spacing": [2, "never"],
+        curly: 2,
+        "eol-last": 2,
+        eqeqeq: [2, "smart"],
+        "max-depth": [1, 3],
+        "new-cap": 1,
+        "no-extend-native": 2,
+        "no-mixed-spaces-and-tabs": 2,
+        "no-trailing-spaces": 1,
+        "no-unused-vars": 1,
+        "no-use-before-define": [2, "nofunc"],
+        "object-curly-spacing": [2, "never"],
+        quotes: [1, "single", "avoid-escape"],
+        semi: [2, "always"],
+
+        "keyword-spacing": [2, {
+            before: true,
+            after: true,
+        }],
+
+        "space-unary-ops": 2,
+
+        "no-console": [1, {
+            allow: ["info", "warn", "error"],
+        }],
+
+        "max-len": [1, 120],
+        "max-statements": [1, 50],
+        "consistent-this": [2, "self"],
+        "no-var": 2,
+        "no-dupe-class-members": 2,
+        "operator-linebreak": [1, "before"],
+
+        "no-unneeded-ternary": [1, {
+            defaultAssignment: false,
+        }],
+
+        "no-lonely-if": 1,
+        "linebreak-style": [2, "unix"],
+        "no-nested-ternary": 2,
+        "require-yield": 2,
+    },
+}]);

package.json

@@ -1,33 +1,58 @@
 {
-  "name": "express-prom-bundle",
-  "version": "1.1.6",
+  "name": "@breizhhardware/express-prom-bundle",
+  "version": "8.0.7",
   "description": "express middleware with popular prometheus metrics in one bundle",
   "main": "src/index.js",
   "keywords": [
     "prometheus",
     "metrics",
     "express",
-    "bundle"
+    "path",
+    "method"
   ],
+  "files": [
+    "src",
+    "types/index.d.ts"
+  ],
+  "types": "types/index.d.ts",
   "scripts": {
-    "test": "node_modules/jasme/run.js"
+    "test": "NODE_ENV=test node_modules/jasme/run.js",
+    "lint": "eslint src",
+    "coverage": "make coverage",
+    "test-types": "tsd"
   },
-  "author": "Konstantin Pogorelov <or@pluseq.com>",
+  "author": "BreizhHardware <felix.marquet@horoquartz.com>",
   "license": "MIT",
   "dependencies": {
+    "@types/express": "^5.0.0",
     "on-finished": "^2.3.0",
-    "prom-client": "^3.4.6"
+    "url-value-parser": "^2.0.0"
   },
   "devDependencies": {
-    "coveralls": "^2.11.12",
-    "eslint": "^2.13.1",
-    "express": "^4.13.4",
-    "istanbul": "^0.4.4",
-    "jasme": "^4.1.2",
-    "supertest": "^1.2.0"
+    "@eslint/eslintrc": "^3.3.1",
+    "@eslint/js": "^9.38.0",
+    "dts": "^0.1.1",
+    "eslint": "^9.38.0",
+    "express": "^5.1.0",
+    "globals": "^16.4.0",
+    "jasme": "^6.0.0",
+    "koa": "^3.0.1",
+    "koa-connect": "^2.0.1",
+    "prom-client": "^15.0.0",
+    "supertest": "^7.1.4",
+    "supertest-koa-agent": "^0.3.0",
+    "tsd": "^0.33.0",
+    "typescript": "^5.9.3",
+    "nyc": "^17.1.0"
+  },
+  "peerDependencies": {
+    "prom-client": ">=15.0.0"
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/jochen-schweizer/express-prom-bundle.git"
+    "url": "git+https://github.com/breizhhardware/express-prom-bundle.git"
+  },
+  "engines": {
+    "node": ">=18"
   }
 }

spec/PromFactorySpec.js

@@ -1,57 +0,0 @@
-"use strict";
-/* eslint-env jasmine */
-const PromFactory = require("../src/PromFactory");
-
-describe("PromFactory", () => {
-    let factory;
-    beforeEach(() => {
-        factory = new PromFactory();
-    });
-    it("creates Counter", () => {
-        const metric = factory.newCounter(
-            "test1",
-            "help for test1",
-            ["label1", "label2"]
-        );
-        expect(metric.name).toBe("test1");
-        expect(metric.help).toBe("help for test1");
-        expect(metric.labelNames).toEqual(["label1", "label2"]);
-    });
-    it("throws on duplicate names", () => {
-        factory.newCounter("n","h");
-        expect(() => factory.newCounter("n","h2")).toThrow();
-    });
-    it("creates Gauge", () => {
-        const metric = factory.newGauge(
-            "test2",
-            "help for test2",
-            ["label1", "label2"]
-        );
-        expect(metric.name).toBe("test2");
-        expect(metric.help).toBe("help for test2");
-        expect(metric.labelNames).toEqual(["label1", "label2"]);
-    });
-    it("creates Histogram with labels", () => {
-        const metric = factory.newHistogram(
-            "test3",
-            "help for test3",
-            ["label1", "label2"],
-            {buckets: [1, 2, 3]}
-        );
-        expect(metric.name).toBe("test3");
-        expect(metric.help).toBe("help for test3");
-        expect(metric.labelNames).toEqual(["label1", "label2"]);
-        expect(metric.bucketValues).toEqual({"1": 0, "2": 0, "3": 0});
-    });
-    it("creates Summary without labels", () => {
-        const metric = factory.newSummary(
-            "test4",
-            "help for test4",
-            {percentiles: [0.1, 0.5]}
-        );
-        expect(metric.name).toBe("test4");
-        expect(metric.help).toBe("help for test4");
-        expect(metric.percentiles).toEqual([0.1, 0.5]);
-    });
-
-});

spec/index.spec.js

@@ -0,0 +1,719 @@
+'use strict';
+/* eslint-env jasmine */
+
+const express = require('express');
+const supertest = require('supertest');
+const bundle = require('../');
+const Koa = require('koa');
+const c2k = require('koa-connect');
+const supertestKoa = require('supertest-koa-agent');
+const promClient = require('prom-client');
+const cluster = require('cluster');
+
+// for some reason in prom-client 15 the hashmap has a trailing comma
+function extractBucket (instance, key) {
+  const hashmap = instance.metrics.http_request_duration_seconds.hashMap;
+  if (hashmap[key]) {
+    return hashmap[key];
+  } else {
+    return hashmap[key + ','];
+  }
+}
+
+function getMetricCount (s) {
+  return s.replace(/^#.*$\n|^$\n/gm, '').trim().split('\n').length;
+}
+
+describe('index', () => {
+  beforeEach(() => {
+    promClient.register.clear();
+  });
+
+  it('metrics returns up=1', done => {
+    const app = express();
+    const bundled = bundle({
+      excludeRoutes: ['/irrelevant', /at.all/]
+    });
+    app.use(bundled);
+    app.use('/test', (req, res) => res.send('it worked'));
+
+    const agent = supertest(app);
+    agent.get('/test').end(() => {
+      agent
+        .get('/metrics')
+        .end((err, res) => {
+          expect(res.status).toBe(200);
+          expect(res.text).toMatch(/up\s1/);
+          done();
+        });
+    });
+  });
+
+  it('"up"-metric can be excluded', done => {
+    const app = express();
+    const bundled = bundle({
+      includeUp: false
+    });
+    app.use(bundled);
+    app.use('/test', (req, res) => res.send('it worked'));
+
+    const agent = supertest(app);
+    agent.get('/test').end(() => {
+      agent
+        .get('/metrics')
+        .end((err, res) => {
+          expect(res.status).toBe(200);
+          expect(res.text).not.toMatch(/up\s1/);
+          done();
+        });
+    });
+  });
+
+  it('metrics path can be defined with a regex', done => {
+    const app = express();
+    const bundled = bundle({
+      metricsPath: /^\/prometheus$/
+    });
+    app.use(bundled);
+    app.use('/test', (req, res) => res.send('it worked'));
+
+    const agent = supertest(app);
+    agent.get('/test').end(() => {
+      agent
+        .get('/prometheus')
+        .end((err, res) => {
+          expect(res.status).toBe(200);
+          expect(res.text).toMatch(/up\s1/);
+          done();
+        });
+    });
+  });
+
+  it('metrics path can be defined as regexp', done => {
+    const app = express();
+    const bundled = bundle();
+    app.use(bundled);
+    app.use('/test', (req, res) => res.send('it worked'));
+
+    const agent = supertest(app);
+    agent.get('/test').end(() => {
+      agent
+        .get('/metrics')
+        .end((err, res) => {
+          expect(res.status).toBe(200);
+          expect(res.text).toMatch(/up\s1/);
+          done();
+        });
+    });
+  });
+
+  it('httpDurationMetricName overrides histogram metric name', done => {
+    const app = express();
+    const bundled = bundle({
+      httpDurationMetricName: 'my_http_duration'
+    });
+    app.use(bundled);
+
+    const agent = supertest(app);
+    agent.get('/metrics')
+      .end((err, res) => {
+        expect(res.text).toMatch(/my_http_duration/m);
+        done();
+      });
+  });
+
+  it('metrics should be attached to /metrics by default', done => {
+    const app = express();
+    const bundled = bundle();
+    app.use(bundled);
+
+    const agent = supertest(app);
+    agent.get('/metrics')
+      .end((err, res) => {
+        expect(res.status).toBe(200);
+        done();
+      });
+  });
+
+  it('metrics can be attached to /metrics programatically', done => {
+    const app = express();
+    const bundled = bundle({
+      autoregister: false
+    });
+    app.use(bundled.metricsMiddleware);
+    app.use(bundled);
+
+    app.use('/test', (req, res) => res.send('it worked'));
+
+    const agent = supertest(app);
+    agent.get('/metrics')
+      .end((err, res) => {
+        expect(res.status).toBe(200);
+        done();
+      });
+  });
+
+  it('returns error 500 on incorrect middleware usage', done => {
+    const app = express();
+    app.use(bundle);
+    supertest(app)
+      .get('/metrics')
+      .end((err, res) => {
+        expect(res.status).toBe(500);
+        done();
+      });
+  });
+  it('http latency gets counted', done => {
+    const app = express();
+    const instance = bundle();
+    app.use(instance);
+    app.use('/test', (req, res) => res.send('it worked'));
+    const agent = supertest(app);
+    agent
+      .get('/test')
+      .end(() => {
+        const bucket = extractBucket(instance, 'status_code:200');
+        expect(bucket).toBeDefined();
+        expect(bucket.count).toBe(1);
+
+        agent
+          .get('/metrics')
+          .end((err, res) => {
+            expect(res.status).toBe(200);
+            done();
+          });
+      });
+  });
+
+  it('filters out the excludeRoutes', done => {
+    const app = express();
+    const instance = bundle({
+      excludeRoutes: ['/test', /bad.word/]
+    });
+    app.use(instance);
+    app.use('/test', (req, res) => res.send('it worked'));
+    app.use('/some/bad-word', (req, res) => res.send('it worked too'));
+    const agent = supertest(app);
+    agent
+      .get('/test')
+      .end(() => {
+        agent
+          .get('/some/bad-word')
+          .end(() => {
+            const metricHashMap = instance.metrics.http_request_duration_seconds.hashMap;
+            expect(metricHashMap['status_code:200']).not.toBeDefined();
+
+            agent
+              .get('/metrics')
+              .end((err, res) => {
+                expect(res.status).toBe(200);
+                done();
+              });
+          });
+      });
+  });
+
+  it('bypass requests', done => {
+    const app = express();
+    const instance = bundle({
+      bypass: (req)=> {
+        // metrics added here to attempt skipping /metrics
+        // this should fail though, because serving /metrics preceeds bypassing
+        return !!req.url.match(/test|bad.word|metrics/);
+      }
+    });
+    app.use(instance);
+    app.use('/test', (req, res) => res.send('it worked'));
+    app.use('/some/bad-word', (req, res) => res.send('it worked too'));
+    app.use('/good-word', (req, res) => res.send('this will be counted'));
+    const agent = supertest(app);
+    agent
+      .get('/test')
+      .end(() => {
+        agent
+          .get('/some/bad-word')
+          .end(() => {
+            agent
+              .get('/good-word')
+              .end(() => {
+                const bucket = extractBucket(instance, 'status_code:200');
+                expect(bucket).toBeDefined();
+
+                // only /good-word should be counted
+                expect(bucket.count).toBe(1);
+
+                agent
+                  .get('/metrics')
+                  .end((err, res) => {
+                    expect(res.status).toBe(200);
+                    done();
+                  });
+              });
+          });
+      });
+  });
+
+  it('bypass requests, checking res', done => {
+    const app = express();
+    const instance = bundle({
+      bypass: {
+        onFinish: (req, res) => res.statusCode === 404
+      }
+    });
+    app.use(instance);
+    app.use('/200', (req, res) => res.send(''));
+    app.use('/404', (req, res) => res.status(404).send(''));
+    app.use('/500', (req, res) => res.status(500).send(''));
+
+    const agent = supertest(app);
+    agent.get('/200')
+      .expect(200)
+      .then(() => {
+        return agent
+          .get('/404')
+          .expect(404);
+      })
+      .then(() => {
+        return agent
+          .get('/500')
+          .expect(500);
+      })
+      .then(() => {
+        // only /200 and /500 should be counted
+        expect(extractBucket(instance, 'status_code:200').count).toBe(1);
+        expect(extractBucket(instance, 'status_code:404')).not.toBeDefined();
+        expect(extractBucket(instance, 'status_code:500').count).toBe(1);
+
+        return agent
+          .get('/metrics')
+          .expect(200);
+      })
+      .then(done);
+  });
+
+  it('complains about deprecated options', () => {
+    expect(() => bundle({prefix: 'hello'})).toThrow();
+  });
+
+  it('tolerates includePath, includeMethod, includeCustomLabels', done => {
+    const app = express();
+    const instance = bundle({
+      includePath: true,
+      includeMethod: true,
+      includeCustomLabels: {foo: 'bar'}
+    });
+    app.use(instance);
+    app.use('/test', (req, res) => res.send('it worked'));
+    const agent = supertest(app);
+    agent
+      .get('/test')
+      .end(() => {
+        agent
+          .get('/metrics')
+          .end((err, res) => {
+            expect(res.status).toBe(200);
+            done();
+          });
+      });
+  });
+
+  it('metric type histogram works', done => {
+    const app = express();
+    const bundled = bundle({
+      metricType: 'histogram',
+      buckets: [10, 100],
+    });
+    app.use(bundled);
+    app.use('/test', (req, res) => res.send('it worked'));
+
+    const agent = supertest(app);
+    agent.get('/test').end(() => {
+      agent
+        .get('/metrics')
+        .end((err, res) => {
+          expect(res.status).toBe(200);
+          expect(res.text).toMatch(/le="100"/);
+          done();
+        });
+    });
+  });
+
+  it('throws on unknown metricType ', () => {
+    expect(() => {
+      bundle({metricType: 'hello'});
+    }).toThrow();
+  });
+
+  describe('usage of normalizePath()', () => {
+
+    it('normalizePath can be replaced globally', done => {
+      const app = express();
+      const original = bundle.normalizePath;
+      bundle.normalizePath = () => 'dummy';
+      const instance = bundle({
+        includePath: true,
+      });
+      app.use(instance);
+      app.use('/test', (req, res) => res.send('it worked'));
+      const agent = supertest(app);
+      agent
+        .get('/test')
+        .end(() => {
+          agent
+            .get('/metrics')
+            .end((err, res) => {
+              expect(res.status).toBe(200);
+              expect(res.text).toMatch(/"dummy"/m);
+              bundle.normalizePath = original;
+              done();
+            });
+        });
+    });
+
+    it('respects pruneAgedBuckets', done => {
+      const app = express();
+      const metricsApp = express();
+      const bundled = bundle({
+        metricsApp,
+        metricType: 'summary',
+        includePath: true,
+        maxAgeSeconds: 1,
+        percentiles: [0.5],
+        ageBuckets: 1,
+        pruneAgedBuckets: true,
+      });
+
+      app.use(bundled);
+
+      const agent = supertest(app);
+      const metricsAgent = supertest(metricsApp);
+      agent.get('/foo')
+        .then(() => metricsAgent.get('/metrics'))
+        .then(response => {
+          expect(response.status).toBe(200);
+          // up + bucket, sum, count
+          expect(getMetricCount(response.text)).toBe(4);
+        })
+        .then(() => new Promise(r => setTimeout(r, 1010)))
+        .then(() => metricsAgent.get('/metrics'))
+        .then(response => {
+          expect(response.status).toBe(200);
+          // only up
+          expect(getMetricCount(response.text)).toBe(1);
+        })
+        .finally(done);
+    });
+
+    it('normalizePath function can be overridden', done => {
+      const app = express();
+      const instance = bundle({
+        includePath: true,
+        normalizePath: req => req.originalUrl + '-suffixed'
+      });
+      app.use(instance);
+      app.use('/test', (req, res) => res.send('it worked'));
+      const agent = supertest(app);
+      agent
+        .get('/test')
+        .end(() => {
+          agent
+            .get('/metrics')
+            .end((err, res) => {
+              expect(res.status).toBe(200);
+              expect(res.text).toMatch(/"\/test-suffixed"/m);
+              done();
+            });
+        });
+    });
+
+    it('normalizePath can be passed as an array of [regex, replacement]', done => {
+      const app = express();
+      const instance = bundle({
+        includePath: true,
+        normalizePath: [
+          ['^/docs/whatever/.*$', '/docs'],
+          [/^\/docs$/, '/mocks']
+        ]
+      });
+      app.use(instance);
+      app.use('/docs/whatever/:andmore', (req, res) => res.send('it worked'));
+      const agent = supertest(app);
+      agent
+        .get('/docs/whatever/unimportant')
+        .end(() => {
+          agent
+            .get('/metrics')
+            .end((err, res) => {
+              expect(res.status).toBe(200);
+              expect(res.text).toMatch(/"\/mocks"/m);
+              done();
+            });
+        });
+    });
+  });
+
+  it('formatStatusCode can be overridden', done => {
+    const app = express();
+    const instance = bundle({
+      formatStatusCode: () => 555
+    });
+    app.use(instance);
+    app.use('/test', (req, res) => res.send('it worked'));
+    const agent = supertest(app);
+    agent
+      .get('/test')
+      .end(() => {
+        agent
+          .get('/metrics')
+          .end((err, res) => {
+            expect(res.status).toBe(200);
+            expect(res.text).toMatch(/555/);
+            done();
+          });
+      });
+  });
+
+  it('includeStatusCode=false removes status_code label from metrics', done => {
+    const app = express();
+    const instance = bundle({
+      includeStatusCode: false
+    });
+    app.use(instance);
+    app.use('/test', (req, res) => res.send('it worked'));
+    const agent = supertest(app);
+    agent
+      .get('/test')
+      .end(() => {
+        agent
+          .get('/metrics')
+          .end((err, res) => {
+            expect(res.status).toBe(200);
+            expect(res.text).not.toMatch(/="200"/);
+            done();
+          });
+      });
+  });
+
+  it('handles errors in collectors', done => {
+    const app = express();
+    const instance = bundle({});
+    app.use(instance);
+
+    new promClient.Gauge({
+      name: 'kaboom',
+      help: 'this metric explodes',
+      collect() {
+        throw new Error('kaboom!');
+      }
+    });
+
+    // the error will NOT be displayed if NODE_ENV=test (as defined in package.json)
+
+    supertest(app)
+      .get('/metrics')
+      .expect(500)
+      .end((err) => done(err));
+  });
+
+  it('customLabels={foo: "bar"} adds foo="bar" label to metrics', done => {
+    const app = express();
+    const instance = bundle({
+      customLabels: {foo: 'bar'}
+    });
+    app.use(instance);
+    app.use('/test', (req, res) => res.send('it worked'));
+    const agent = supertest(app);
+    agent
+      .get('/test')
+      .end(() => {
+        agent
+          .get('/metrics')
+          .end((err, res) => {
+            expect(res.status).toBe(200);
+            expect(res.text).toMatch(/foo="bar"/);
+            done();
+          });
+      });
+  });
+
+  it('tarnsformLabels can set label values', done => {
+    const app = express();
+    const instance = bundle({
+      includePath: true,
+      customLabels: {foo: 'bar'},
+      transformLabels: labels => {
+        labels.foo = 'baz';
+        labels.path += '/ok';
+      }
+    });
+    app.use(instance);
+    app.use('/test', (req, res) => res.send('it worked'));
+    const agent = supertest(app);
+    agent
+      .get('/test')
+      .end(() => {
+        agent
+          .get('/metrics')
+          .end((err, res) => {
+            expect(res.status).toBe(200);
+            expect(res.text).toMatch(/foo="baz"/);
+            expect(res.text).toMatch(/path="\/test\/ok"/);
+            done();
+          });
+      });
+  });
+
+  it('Koa: metrics returns up=1', done => {
+    const app = new Koa();
+    const bundled = bundle();
+    app.use(c2k(bundled));
+
+    app.use(function(ctx, next) {
+      return next().then(() => ctx.body = 'it worked');
+    });
+
+    const agent = supertestKoa(app);
+    agent.get('/test').end(() => {
+      agent
+        .get('/metrics')
+        .end((err, res) => {
+          expect(res.status).toBe(200);
+          expect(res.text).toMatch(/^up\s1/m);
+          done();
+        });
+    });
+  });
+
+  describe('option collectDefaultMetrics', () => {
+    it('it gets called', () => {
+      const spy = spyOn(promClient, 'collectDefaultMetrics');
+      bundle({
+        promClient: {
+          collectDefaultMetrics: {
+          }
+        }
+      });
+      expect(spy).toHaveBeenCalledWith({});
+    });
+
+    it('prefix is used for up metric', (done) => {
+      const instance = bundle({
+        promClient: {
+          collectDefaultMetrics: {
+            prefix: 'hello_'
+          }
+        }
+      });
+      const app = express();
+      app.use(instance);
+      const agent = supertest(app);
+      agent
+        .get('/metrics')
+        .end((err, res) => {
+          expect(res.status).toBe(200);
+          expect(res.text).toMatch(/^hello_up\s1/m);
+          done();
+        });
+    });
+  });
+
+  describe('usage of clusterMetrics()', () => {
+    it('clusterMetrics returns 200 even without a cluster', (done) => {
+      const app = express();
+
+      cluster.workers = [];
+
+      app.use('/cluster_metrics', bundle.clusterMetrics());
+      const agent = supertest(app);
+      agent
+        .get('/cluster_metrics')
+        .end((err, res) => {
+          expect(res.status).toBe(200);
+          done();
+        });
+    });
+
+    it('clusterMetrics returns 500 in case of an error', (done) => {
+      const app = express();
+      app.use('/cluster_metrics', bundle.clusterMetrics());
+      const agent = supertest(app);
+
+      // create a fake worker, which would not respond in time
+      cluster.workers = [{
+        isConnected: () => true,
+        send: () => {}
+      }];
+
+      const errorSpy = spyOn(console, 'error'); // mute console.error
+
+      agent
+        .get('/cluster_metrics')
+        .end((err, res) => {
+          expect(res.status).toBe(500);
+          expect(errorSpy).toHaveBeenCalled();
+          done();
+        });
+    }, 6000);
+  });
+
+  describe('metricType: summary', () => {
+    it('metric type summary works', done => {
+      const app = express();
+      const bundled = bundle({
+        metricType: 'summary'
+      });
+      app.use(bundled);
+      app.use('/test', (req, res) => res.send('it worked'));
+
+      const agent = supertest(app);
+      agent.get('/test').end(() => {
+        agent
+          .get('/metrics')
+          .end((err, res) => {
+            expect(res.status).toBe(200);
+            expect(res.text).toMatch(/quantile="0.98"/);
+            done();
+          });
+      });
+    });
+
+    it('custom pecentiles work', done => {
+      const app = express();
+      const bundled = bundle({
+        metricType: 'summary',
+        percentiles: [0.5, 0.85, 0.99],
+      });
+      app.use(bundled);
+      app.use('/test', (req, res) => res.send('it worked'));
+
+      const agent = supertest(app);
+      agent.get('/test').end(() => {
+        agent
+          .get('/metrics')
+          .end((err, res) => {
+            expect(res.status).toBe(200);
+            expect(res.text).toMatch(/quantile="0.85"/);
+            done();
+          });
+      });
+    });
+
+    it('additional metricsApp can be used', done => {
+      const app = express();
+      const metricsApp = express();
+      const bundled = bundle({metricsApp});
+
+      app.use(bundled);
+
+      const agent = supertest(app);
+      const metricsAgent = supertest(metricsApp);
+      agent.get('/').end(() => {
+        metricsAgent.get('/metrics').end((err, res) => {
+          expect(res.status).toBe(200);
+          expect(res.text).toMatch(/status_code="404"/);
+          done();
+        });
+      });
+    });
+  });
+});

spec/indexSpec.js

@@ -1,103 +0,0 @@
-"use strict";
-/* eslint-env jasmine */
-
-let express = require("express"),
-    supertest = require("supertest"),
-    bundle = require("../");
-
-describe("index", () => {
-    it("/metrics returns up=1", done => {
-        const app = express();
-        app.use(bundle({
-            prefix: "hello:",
-            whitelist: ["up"]
-        }));
-        app.use("/test", (req, res) => res.send("it worked"));
-        
-        const agent = supertest(app);
-        agent.get("/test").end(() => {
-            agent
-                .get("/metrics")
-                .end((err, res) => {
-                    expect(res.status).toBe(200);
-                    expect(res.text).toMatch(/hello:up\s1/);
-                    done();
-                });
-        });
-    });
-    it("metrics can be filtered using exect match", () => {
-        const instance = bundle({blacklist: ["up"]});
-        expect(instance.metrics.up).not.toBeDefined();
-        expect(instance.metrics.nodejs_memory_heap_total_bytes).toBeDefined();
-    });
-    it("metrics can be filtered using regex", () => {
-        const instance = bundle({blacklist: [/memory/]});
-        expect(instance.metrics.up).toBeDefined();
-        expect(instance.metrics.nodejs_memory_heap_total_bytes).not.toBeDefined();
-    });
-    it("metrics can be whitelisted", () => {
-        const instance = bundle({whitelist: [/^up$/]});
-        expect(instance.metrics.up).toBeDefined();
-        expect(instance.metrics.nodejs_memory_heap_total_bytes).not.toBeDefined();
-        expect(instance.metrics.http_request_seconds).not.toBeDefined();
-    });
-    it("throws on both white and blacklist", () => {
-        expect(() => {
-            bundle({whitelist: [/up/], blacklist: [/up/]});
-        }).toThrow();
-    });
-    it("returns error 500 on incorrect middleware usage", done => {
-        const app = express();
-        app.use(bundle);
-        supertest(app)
-            .get("/metrics")
-            .end((err, res) => {
-                expect(res.status).toBe(500);
-                done();
-            });
-    });
-    it("http latency gets counted", done => {
-        const app = express();
-        const instance = bundle();
-        app.use(instance);
-        app.use("/test", (req, res) => res.send("it worked"));
-        const agent = supertest(app);
-        agent
-            .get("/test")
-            .end(() => {
-                const metricHashMap = instance.metrics.http_request_seconds.hashMap;
-                expect(metricHashMap["status_code:200"]).toBeDefined();
-                const labeled = metricHashMap["status_code:200"];
-                expect(labeled.count).toBe(1);
-
-                agent
-                    .get("/metrics")
-                    .end((err, res) => {
-                        expect(res.status).toBe(200);
-                        done();
-                    });
-            });
-    });
-    it("filters out the excludeRoutes", done => {
-       const app = express();
-        const instance = bundle({
-            excludeRoutes: ["/test"]
-        });
-        app.use(instance);
-        app.use("/test", (req, res) => res.send("it worked"));
-        const agent = supertest(app);
-        agent
-            .get("/test")
-            .end(() => {
-                const metricHashMap = instance.metrics.http_request_seconds.hashMap;
-                expect(metricHashMap["status_code:200"]).not.toBeDefined();
-
-                agent
-                    .get("/metrics")
-                    .end((err, res) => {
-                        expect(res.status).toBe(200);
-                        done();
-                    });
-            });
-    });
-});

spec/normalizePath.spec.js

@@ -0,0 +1,36 @@
+'use strict';
+/* eslint-env jasmine */
+
+const normalizePath = require('../src/normalizePath');
+
+describe('normalizePath', () => {
+  it('uses UrlValueParser by default', () => {
+    expect(normalizePath({url: '/a/12345'}))
+      .toBe('/a/#val');
+  });
+
+  it('uses normalizePath option', () => {
+    const url = '/hello/world/i/am/finally/free!!!';
+    const result = normalizePath({url}, {
+      normalizePath: [
+        ['/hello','/goodbye'],
+        ['[^/]+$','happy'],
+      ]
+    });
+    expect(result).toBe('/goodbye/world/i/am/finally/happy');
+  });
+
+  it('throws error is bad tuples provided as normalizePath', () => {
+    const subject = () => normalizePath({url: '/test'}, {
+      normalizePath: [
+        ['/hello','/goodbye', 'test']
+      ]
+    });
+    expect(subject).toThrow();
+  });
+
+  it('uses urlPathReplacement when passed to transform the path', () => {
+    expect(normalizePath({url: '/a/12345'}, {urlPathReplacement: ':id'}))
+      .toBe('/a/:id');
+  });
+});

spec/normalizeStatusCode.spec.js

@@ -0,0 +1,16 @@
+'use strict';
+/* eslint-env jasmine */
+
+const normalizeStatusCode = require('../src/normalizeStatusCode');
+
+describe('normalizeStatusCode', () => {
+  it('returns run callback if configured', () => {
+    expect(
+      normalizeStatusCode({status_code: 500, headersSent: true})
+    ).toBe(500);
+  });
+
+  it('returns 499 if headers are not sent', () => {
+    expect(normalizeStatusCode({statusCode: 200, headersSent: false})).toBe(499);
+  });
+});

src/PromFactory.js

@@ -1,53 +0,0 @@
-"use strict";
-
-module.exports = class {
-    constructor(opts) {
-        this.opts = opts || {};
-        this.promClient = this.opts.promClient || require("prom-client");
-        this.metrics = {};
-    }
-
-    metricExists(name) {
-        return !!this.metrics[name];
-    }
-
-    checkDuplicate(name) {
-        if (this.metricExists(name)) {
-            throw new Error("trying to add already existing metric: " + name);
-        }
-    }
-
-    makeRealName(name) {
-        return (this.opts.prefix || "") + name;
-    }
-
-    makeMetric(TheClass, args) {
-        // convert pseudo-array
-        const applyParams = Array.prototype.slice.call(args);
-        const name = applyParams[0];
-        this.checkDuplicate(name);
-        const realName = this.makeRealName(name);
-        applyParams[0] = realName;
-        applyParams.unshift(null); // add some dummy context for apply
-
-        // call constructor with variable params
-        this.metrics[name] = new (Function.prototype.bind.apply(TheClass, applyParams));
-        return this.metrics[name];
-    }
-
-    newCounter() {
-        return this.makeMetric(this.promClient.Counter, arguments);
-    }
-
-    newGauge() {
-        return this.makeMetric(this.promClient.Gauge, arguments);
-    }
-
-    newHistogram() {
-        return this.makeMetric(this.promClient.Histogram, arguments);
-    }
-
-    newSummary() {
-        return this.makeMetric(this.promClient.Summary, arguments);
-    }
-};

src/index.js

@@ -1,134 +1,246 @@
-"use strict";
-
-const
-    PromFactory = require("./PromFactory"),
-    onFinished = require("on-finished");
+const onFinished = require('on-finished');
+const promClient = require('prom-client');
+const normalizePath = require('./normalizePath');
+const normalizeStatusCode = require('./normalizeStatusCode');
 
 function matchVsRegExps(element, regexps) {
-    for (let regexp of regexps) {
-        if (regexp instanceof RegExp) {
-            if (element.match(regexp)) {
-                return true;
-            }
-        } else if (element == regexp) {
-            return true;
-        }
+  for (const regexp of regexps) {
+    if (regexp instanceof RegExp) {
+      if (element.match(regexp)) {
+        return true;
+      }
+    } else if (element === regexp) {
+      return true;
     }
-    return false;
+  }
+  return false;
 }
 
+function clusterMetrics() {
+  const aggregatorRegistry = new promClient.AggregatorRegistry();
 
-function filterArrayByRegExps(array, regexps) {
-    return array.filter(element => {
-        return matchVsRegExps(element, regexps);
+  const metricsMiddleware = function(req, res) {
+    function sendClusterMetrics(clusterMetrics) {
+      res.set('Content-Type', aggregatorRegistry.contentType);
+      res.send(clusterMetrics);
+    }
+
+    function sendClusterMetricsError(err) {
+      console.error(err);
+      return res.sendStatus(500);
+    }
+
+    // since prom-client@13 clusterMetrics() method doesn't take cb param,
+    // but we provide it anyway, as at this stage it's unknown which version of prom-client is used
+    const response = aggregatorRegistry.clusterMetrics((err, clusterMetrics) => {
+      if (err) {
+        return sendClusterMetricsError(err);
+      }
+      sendClusterMetrics(clusterMetrics);
     });
-}
 
-function prepareMetricNames(opts, metricTemplates) {
-    const names = Object.keys(metricTemplates);
-    if (opts.whitelist) {
-        if (opts.blacklist) {
-            throw new Error("you cannot have whitelist and blacklist at the same time");
-        }
-        return filterArrayByRegExps(names, opts.whitelist);
+    // if we find out that it was a promise and our cb was useless...
+    if (response && response.then) {
+      response
+        .then(result => sendClusterMetrics(result))
+        .catch(err => sendClusterMetricsError(err));
     }
-    if (opts.blacklist) {
-        const blacklisted = filterArrayByRegExps(names, opts.blacklist);
-        return names.filter(name => blacklisted.indexOf(name) === -1);
-    }
-    return names;
+  };
+
+  return metricsMiddleware;
 }
 
 function main(opts) {
-    opts = opts === undefined ? {} : opts;
-    if (arguments[2] && arguments[1] && arguments[1].send) {
-        arguments[1].status(500)
-            .send("<h1>500 Error</h1>\n"
-                + "<p>Unexapected 3d param in express-prom-bundle.\n"
-                + "<p>Did you just put express-prom-bundle into app.use "
-                + "without calling it as a function first?");
+  if (arguments[2] && arguments[1] && arguments[1].send) {
+    arguments[1].status(500)
+      .send('<h1>500 Error</h1>\n'
+        + '<p>Unexpected 3rd param in express-prom-bundle.\n'
+        + '<p>Did you just put express-prom-bundle into app.use '
+        + 'without calling it as a function first?');
+    return;
+  }
+
+  opts = Object.assign(
+    {
+      autoregister: true,
+      includeStatusCode: true,
+      normalizePath: main.normalizePath,
+      formatStatusCode: main.normalizeStatusCode,
+      metricType: 'histogram',
+      promClient: {},
+      promRegistry: promClient.register,
+      metricsApp: null,
+    }, opts
+  );
+
+  if (opts.prefix
+    || opts.keepDefaultMetrics !== undefined
+    || opts.whitelist !== undefined
+    || opts.blacklist !== undefined
+  ) {
+    throw new Error(
+      'express-prom-bundle detected one of the obsolete options: '
+      + 'prefix, keepDefaultMetrics, whitelist, blacklist. '
+      + 'Please refer to oficial docs. '
+      + 'Most likely you upgraded the module without the necessary code changes'
+    );
+  }
+
+  if (opts.promClient.collectDefaultMetrics) {
+    promClient.collectDefaultMetrics(opts.promClient.collectDefaultMetrics);
+  }
+
+  const httpMetricName = opts.httpDurationMetricName || 'http_request_duration_seconds';
+  const upMetricName = opts.upMetricName || 'up';
+
+  function makeHttpMetric() {
+    const labels = ['status_code'];
+    if (opts.includeMethod) {
+      labels.push('method');
+    }
+    if (opts.includePath) {
+      labels.push('path');
+    }
+    if (opts.customLabels) {
+      labels.push.apply(labels, Object.keys(opts.customLabels));
+    }
+
+    if (opts.metricType === 'summary') {
+      return new promClient.Summary({
+        name: httpMetricName,
+        help: 'duration summary of http responses labeled with: ' + labels.join(', '),
+        labelNames: labels,
+        percentiles: opts.percentiles || [0.5, 0.75, 0.95, 0.98, 0.99, 0.999],
+        maxAgeSeconds:  opts.maxAgeSeconds,
+        ageBuckets: opts.ageBuckets,
+        registers: [opts.promRegistry],
+        pruneAgedBuckets: opts.pruneAgedBuckets
+      });
+    } else if (opts.metricType === 'histogram' || !opts.metricType) {
+      return new promClient.Histogram({
+        name: httpMetricName,
+        help: 'duration histogram of http responses labeled with: ' + labels.join(', '),
+        labelNames: labels,
+        buckets: opts.buckets || [0.003, 0.03, 0.1, 0.3, 1.5, 10],
+        registers: [opts.promRegistry]
+      });
+    } else {
+      throw new Error('metricType option must be histogram or summary');
+    }
+  }
+
+  const metrics = {
+    [httpMetricName]: makeHttpMetric()
+  };
+
+  if (opts.includeUp !== false) {
+    let prefix = '';
+    if (opts.promClient && opts.promClient.collectDefaultMetrics) {
+      prefix = opts.promClient.collectDefaultMetrics.prefix || '';
+    }
+    metrics.up = new promClient.Gauge({
+      name: prefix + upMetricName,
+      help: '1 = up, 0 = not up',
+      registers: [opts.promRegistry]
+    });
+    metrics.up.set(1);
+  }
+
+  const metricsMiddleware = function(req, res, next) {
+    const sendSuccesss = (output) => {
+      res.writeHead(200, {'Content-Type': 'text/plain'});
+      res.end(output);
+    };
+
+    const metricsResponse = opts.promRegistry.metrics();
+    // starting from prom-client@13 .metrics() returns a Promise
+    if (metricsResponse.then) {
+      metricsResponse
+        .then(output => sendSuccesss(output))
+        .catch(err => next(err));
+    } else {
+      // compatibility fallback for previous versions of prom-client@<=12
+      sendSuccesss(metricsResponse);
+    }
+  };
+
+  const metricsMatch = opts.metricsPath instanceof RegExp ? opts.metricsPath
+    : new RegExp('^' + (opts.metricsPath || '/metrics') + '/?$');
+
+  if (typeof opts.bypass === 'function') {
+    opts.bypass = {
+      onRequest: opts.bypass
+    };
+  } else if (!opts.bypass) {
+    opts.bypass = {};
+  }
+
+  const middleware = function (req, res, next) {
+    const path = req.originalUrl || req.url; // originalUrl gets lost in koa-connect?
+
+    if (opts.autoregister && path.match(metricsMatch)) {
+      return metricsMiddleware(req, res, next);
+    }
+
+    // bypass() is checked only after /metrics was processed
+    // if you wish to disable /metrics use autoregister:false instead
+    if (opts.bypass.onRequest && opts.bypass.onRequest(req)) {
+      return next();
+    }
+
+    if (opts.excludeRoutes && matchVsRegExps(path, opts.excludeRoutes)) {
+      return next();
+    }
+
+    const labels = {};
+    const timer = metrics[httpMetricName].startTimer(labels);
+
+    onFinished(res, () => {
+      if (opts.bypass.onFinish && opts.bypass.onFinish(req, res)) {
         return;
-    }
+      }
 
-    const factory = new PromFactory(opts);
+      if (opts.includeStatusCode) {
+        labels.status_code = opts.formatStatusCode(res, opts);
+      }
+      if (opts.includeMethod) {
+        labels.method = req.method;
+      }
+      if (opts.includePath) {
+        labels.path = opts.normalizePath instanceof Function
+          ? opts.normalizePath(req, opts)
+          : main.normalizePath(req, opts);
+      }
+      if (opts.customLabels) {
+        Object.assign(labels, opts.customLabels);
+      }
+      if (opts.transformLabels) {
+        opts.transformLabels(labels, req, res);
+      }
+      timer();
+    });
 
-    const metricTemplates = {
-        "up": () => factory.newGauge(
-            "up",
-            "1 = up, 0 = not up"
-        ),
-        "nodejs_memory_heap_total_bytes": () => factory.newGauge(
-            "nodejs_memory_heap_total_bytes",
-            "value of process.memoryUsage().heapTotal"
-        ),
-        "nodejs_memory_heap_used_bytes": () => factory.newGauge(
-            "nodejs_memory_heap_used_bytes",
-            "value of process.memoryUsage().heapUsed"
-        ),
-        "http_request_seconds": () => {
-            const metric = factory.newHistogram(
-                "http_request_seconds",
-                "number of http responses labeled with status code",
-                ["status_code"],
-                {
-                    buckets: opts.buckets || [0.003, 0.03, 0.1, 0.3, 1.5, 10]
-                }
-            );
-            return metric;
-        }
-    };
+    next();
+  };
 
-    const
-        metrics = {},
-        names = prepareMetricNames(opts, metricTemplates);
+  if (opts.metricsApp) {
+    opts.metricsApp.get(opts.metricsPath || '/metrics', (req, res) => {
+      res.set('Content-Type', opts.promRegistry.contentType);
+      opts.promRegistry.metrics()
+        .then(metrics => res.end(metrics));
+    });
+  }
 
-
-    for (let name of names) {
-        metrics[name] = metricTemplates[name]();
-    }
-
-    if (metrics.up) {
-        metrics.up.set(1);
-    }
-
-    const middleware = function (req, res, next) {
-        if (req.path == "/metrics") {
-            let memoryUsage = process.memoryUsage();
-            if (metrics["nodejs_memory_heap_total_bytes"]) {
-                metrics["nodejs_memory_heap_total_bytes"].set(memoryUsage.heapTotal);
-            }
-            if (metrics["nodejs_memory_heap_used_bytes"]) {
-                metrics["nodejs_memory_heap_used_bytes"].set(memoryUsage.heapUsed);
-            }
-
-            res.contentType("text/plain")
-                .send(factory.promClient.register.metrics());
-            return;
-        }
-
-        if (opts.excludeRoutes && matchVsRegExps(req.path, opts.excludeRoutes)) {
-            return next();
-        }
-
-        let labels;
-        if (metrics["http_request_seconds"]) {
-            labels = {"status_code": 0};
-            let timer = metrics["http_request_seconds"].startTimer(labels);
-            onFinished(res, () => {
-                labels["status_code"] = res.statusCode;
-                timer();
-            });
-        }
-
-        next();
-    };
-
-    middleware.factory = factory;
-    middleware.metricTemplates = metricTemplates;
-    middleware.metrics = metrics;
-    middleware.promClient = factory.promClient;
-
-    return middleware;
+  middleware.metrics = metrics;
+  middleware.promClient = promClient;
+  middleware.metricsMiddleware = metricsMiddleware;
+  return middleware;
 }
 
-module.exports = main;
+// this is kept only for compatibility with the code relying on older version
+main.promClient = promClient;
+
+main.normalizePath = normalizePath;
+main.normalizeStatusCode = normalizeStatusCode;
+main.clusterMetrics = clusterMetrics;
+module.exports = main;

src/normalizePath.js

@@ -0,0 +1,31 @@
+'use strict';
+
+const UrlValueParser = require('url-value-parser');
+const url = require('url');
+
+// ATTENTION! urlValueParser is a singleton!
+let urlValueParser;
+
+module.exports = function(req, opts) {
+  // originalUrl is taken, because url and path can be changed
+  // by middlewares such as 'router'. Note: this function is called onFinish
+  /// i.e. always in the tail of the middleware chain
+  let path = url.parse(req.originalUrl || req.url).pathname;
+  const urlPathReplacement = opts ? opts.urlPathReplacement : '#val';
+
+  const normalizePath = opts && opts.normalizePath;
+  if (Array.isArray(normalizePath)) {
+    for (const tuple of normalizePath) {
+      if (!Array.isArray(tuple) || tuple.length !== 2) {
+        throw new Error('Bad tuple provided in normalizePath option, expected: [regex, replacement]');
+      }
+      const regex = typeof tuple[0] === 'string' ? RegExp(tuple[0]) : tuple[0];
+      path = path.replace(regex, tuple[1]);
+    }
+  }
+
+  if (!urlValueParser) {
+    urlValueParser = new UrlValueParser(opts && opts.urlValueParser);
+  }
+  return urlValueParser.replacePathValues(path, urlPathReplacement);
+};

src/normalizeStatusCode.js

@@ -0,0 +1,11 @@
+'use strict';
+
+const CLIENT_CLOSED_REQUEST_CODE = 499;
+
+module.exports = function(res) {
+  if (res.headersSent) {
+    return res.status_code || res.statusCode;
+  } else {
+    return CLIENT_CLOSED_REQUEST_CODE;
+  }
+};

types/index.d.ts

@@ -0,0 +1,91 @@
+// TypeScript Version: 2.8
+
+import { Request, RequestHandler, Response, Express } from 'express';
+import { DefaultMetricsCollectorConfiguration, Registry, RegistryContentType } from 'prom-client';
+
+export {};
+
+export = express_prom_bundle;
+
+declare namespace express_prom_bundle {
+  interface Labels {
+    [key: string]: string | number;
+  }
+
+  type NormalizePathEntry = [string | RegExp, string];
+  type NormalizePathFn = (req: Request, opts: Opts) => string;
+  type NormalizeStatusCodeFn = (res: Response) => number | string;
+  type TransformLabelsFn = (labels: Labels, req: Request, res: Response) => void;
+
+  interface BaseOptions {
+    autoregister?: boolean;
+
+    customLabels?: { [key: string]: any };
+
+    includeStatusCode?: boolean;
+    includeMethod?: boolean;
+    includePath?: boolean;
+    includeUp?: boolean;
+
+    bypass?:
+      | ((req: Request) => boolean)
+      | {
+          onRequest?: (req: Request) => boolean;
+          onFinish?: (req: Request, res: Response) => boolean;
+        };
+
+    excludeRoutes?: Array<string | RegExp>;
+
+    metricsPath?: string;
+    httpDurationMetricName?: string;
+    upMetricName?: string;
+    promClient?: { collectDefaultMetrics?: DefaultMetricsCollectorConfiguration<RegistryContentType> };
+    promRegistry?: Registry;
+    normalizePath?: NormalizePathEntry[] | NormalizePathFn;
+    formatStatusCode?: NormalizeStatusCodeFn;
+    transformLabels?: TransformLabelsFn;
+    urlPathReplacement?: string;
+    metricsApp?: Express;
+
+    // https://github.com/disjunction/url-value-parser#options
+    urlValueParser?: {
+      minHexLength?: number;
+      minBase64Length?: number;
+      replaceMasks?: Array<RegExp | string>;
+      extraMasks?: Array<RegExp | string>;
+    };
+  }
+
+  /** @see https://github.com/siimon/prom-client#summary */
+  type SummaryOptions = BaseOptions & {
+    metricType?: 'summary';
+    percentiles?: number[];
+    maxAgeSeconds?: number;
+    ageBuckets?: number;
+    pruneAgedBuckets?: boolean;
+  }
+
+  /** @see https://github.com/siimon/prom-client#histogram */
+  type HistogramOptions = BaseOptions & {
+    metricType?: 'histogram';
+    buckets?: number[];
+  }
+
+  type Opts = SummaryOptions | HistogramOptions;
+
+  interface Middleware extends RequestHandler {
+    metricsMiddleware: RequestHandler;
+  }
+
+  const normalizePath: NormalizePathFn;
+  const normalizeStatusCode: NormalizeStatusCodeFn;
+
+  function clusterMetrics(): RequestHandler;
+}
+
+interface express_prom_bundle {
+  normalizePath: express_prom_bundle.NormalizePathFn;
+  normalizeStatusCode: express_prom_bundle.NormalizeStatusCodeFn;
+}
+
+declare function express_prom_bundle(opts: express_prom_bundle.Opts): express_prom_bundle.Middleware;

types/index.test-d.ts

@@ -0,0 +1,91 @@
+import express, { RequestHandler } from 'express';
+import { expectType } from 'tsd'
+import * as promClient from 'prom-client';
+import promBundle, {
+  type Middleware
+} from '..';
+
+const middleware: express.RequestHandler = promBundle({ includeMethod: true });
+
+expectType<string>(middleware.name);
+
+promClient.register.clear();
+
+expectType<Middleware>(promBundle({
+  normalizePath: [
+    // collect paths like "/customer/johnbobson" as just one "/custom/#name"
+    ['^/customer/.*', '/customer/#name'],
+
+    // collect paths like "/bobjohnson/order-list" as just one "/#name/order-list"
+    ['^.*/order-list', '/#name/order-list']
+  ],
+  urlValueParser: {
+    minHexLength: 5,
+    extraMasks: [
+      'ORD[0-9]{5,}' // replace strings like ORD1243423, ORD673562 as #val
+    ]
+  }
+}));
+
+promClient.register.clear();
+
+expectType<Middleware>(promBundle({
+  buckets: [0.1, 0.4, 0.7],
+  includeMethod: true,
+  includePath: true,
+  excludeRoutes: ['/foo', /^\/bar\/?$/],
+  customLabels: { year: null },
+  transformLabels: (labels: promBundle.Labels) => ({
+    ...labels,
+    year: new Date().getFullYear()
+  }),
+  metricType: 'histogram',
+  metricsPath: '/prometheus',
+  promClient: {
+    collectDefaultMetrics: {
+    }
+  },
+  promRegistry: new promClient.Registry(),
+  urlValueParser: {
+    minHexLength: 5,
+    extraMasks: [
+      '^[0-9]+\\.[0-9]+\\.[0-9]+$' // replace dot-separated dates with #val
+    ]
+  },
+  normalizePath: [
+    ['^/foo', '/example'] // replace /foo with /example
+  ],
+  formatStatusCode: (res: express.Response) => res.statusCode + 100,
+  metricsApp: express()
+}));
+
+promClient.register.clear();
+
+promBundle({
+  metricType: 'summary',
+  maxAgeSeconds: 600,
+  ageBuckets: 5
+});
+
+promClient.register.clear();
+
+promBundle({
+  metricType: 'summary',
+  percentiles: [0.01, 0.1, 0.9, 0.99]
+});
+
+// TypeScript workaround to write a readonly field
+type Writable<T> = { -readonly [K in keyof T]: T[K] };
+const wPromBundle: Writable<promBundle> = promBundle;
+
+wPromBundle.normalizePath = (req: express.Request, opts: promBundle.Opts) => {
+  const path = promBundle.normalizePath(req, opts);
+
+  // count all docs as one path, but /docs/login as a separate one
+  return path.match(/^\/docs/) && !path.match(/^\/login/) ? '/docs/*' : path;
+};
+
+wPromBundle.normalizeStatusCode = (res: express.Response) => res.statusCode.toString();
+
+expectType<RequestHandler>(promBundle.clusterMetrics());
+