express-sequelize-traffic 0.2.0 → 0.4.0

package/README.md

@@ -30,9 +30,9 @@ npm install
 npm run build
 ```
 
-## Sequelize Setup
+## Quick Setup
 
-The package defines a `TrafficLog` model for you. You can either manage the table through your own migrations or call `traffic.sync()` for quick setup.
+The package defines a `TrafficLog` model for you. You can either manage the table through your own migrations or call `traffic.sync()` for quick setup. `traffic.sync()` wraps Sequelize model sync and creates the `traffic_logs` table if it does not already exist.
 
 ```js
 import { Sequelize } from "sequelize";
@@ -46,7 +46,9 @@ await sequelize.authenticate();
 await traffic.sync();
 ```
 
-## Express Usage
+## ES Module Setup
+
+Use this form when the target app uses `"type": "module"` or native ESM imports.
 
 ```js
 import express from "express";
@@ -63,6 +65,7 @@ const traffic = createTrafficTracker({
   getUserId: (req) => req.user?.id || req.headers["x-user-id"],
   getSessionId: (req) => req.sessionID || req.headers["x-session-id"],
   slowRouteThresholdMs: 1000,
+  includeRoutes: ["/api/*"],
   trackIp: false,
   trackUserAgent: true,
   ignoredRoutes: ["/health", "/favicon.ico"],
@@ -83,15 +86,186 @@ app.use("/traffic-dashboard", traffic.dashboard);
 server.listen(3000);
 ```
 
-CommonJS applications can use the published `require(...)` entry:
+## CommonJS Setup
+
+The package also publishes a CommonJS entry, so `require(...)` works directly.
 
 ```js
 const express = require("express");
 const http = require("node:http");
 const { Sequelize } = require("sequelize");
 const { createTrafficTracker } = require("express-sequelize-traffic");
+
+const app = express();
+const server = http.createServer(app);
+
+const sequelize = new Sequelize(process.env.DB_URL, {
+  logging: false,
+});
+
+async function start() {
+  const traffic = createTrafficTracker({
+    sequelize,
+    getUserId: (req) => req.user?.id || req.headers["x-user-id"] || null,
+    getSessionId: (req) => req.sessionID || req.headers["x-session-id"] || null,
+    slowRouteThresholdMs: 1000,
+    includeRoutes: ["/api/*"],
+    ignoredRoutes: ["/health", "/favicon.ico"],
+    trackIp: false,
+    trackUserAgent: true,
+    dashboard: {
+      enabled: true,
+      mountPath: "/traffic-dashboard",
+      username: process.env.TRAFFIC_ADMIN_USER,
+      password: process.env.TRAFFIC_ADMIN_PASS,
+    },
+  });
+
+  await sequelize.authenticate();
+  await traffic.sync();
+
+  app.use(traffic.middleware);
+  traffic.attachRealtime(server);
+  app.use("/traffic-dashboard", traffic.dashboard);
+
+  app.get("/health", (_req, res) => {
+    res.json({ ok: true });
+  });
+
+  server.listen(3000);
+}
+
+start().catch((error) => {
+  console.error("Startup failed:", error);
+  process.exit(1);
+});
+```
+
+## Passing User Details
+
+The package does not assume how authentication works in your app. You pass user and session details through resolver functions.
+
+```js
+const traffic = createTrafficTracker({
+  sequelize,
+  getUserId: (req) =>
+    req.user?.id || req.auth?.sub || req.headers["x-user-id"] || null,
+  getSessionId: (req) =>
+    req.sessionID || req.cookies?.sessionId || req.headers["x-session-id"] || null,
+});
+```
+
+Common sources are:
+
+- `req.user.id` from Passport or your own auth middleware
+- `req.auth.sub` from JWT middleware
+- `req.sessionID` from `express-session`
+- custom request headers in internal systems
+
+Rules to follow:
+
+- Register auth and session middleware before `traffic.middleware`
+- Return `null` when user or session data is unavailable
+- If you omit `getUserId` or `getSessionId`, those fields are stored as `NULL`
+
+## Why It Tracks More Than Application Routes
+
+This package is request middleware. If you mount it globally with:
+
+```js
+app.use(traffic.middleware);
+```
+
+it will see every request that reaches that point in the Express stack, not just your business endpoints.
+
+That includes:
+
+- API routes
+- page routes
+- health checks
+- static files
+- 404 requests
+- dashboard API requests
+- dashboard frontend asset requests
+
+Internally, the tracker records the route from `req.route?.path`, then falls back to `req.path`, then `req.originalUrl`. That is why it can still log requests even when Express does not resolve them to a named application route.
+
+## How To Track Only Application Routes
+
+If you want to limit tracking to business endpoints, start with `includeRoutes`. It is usually easier than maintaining a long `ignoredRoutes` list.
+
+Track only route families you want:
+
+```js
+const traffic = createTrafficTracker({
+  sequelize,
+  includeRoutes: ["/api/*", "/admin/*"],
+});
+```
+
+String matchers support:
+
+- exact matches like `"/health"`
+- prefix-style wildcards like `"/api/*"`
+- regex matchers like `/^\/v[0-9]+\//`
+- custom functions
+
+If `includeRoutes` is provided, only matching requests are tracked. You can still use `ignoredRoutes` to exclude specific subsets from a broader include rule.
+
+Example:
+
+```js
+const traffic = createTrafficTracker({
+  sequelize,
+  includeRoutes: ["/api/*"],
+  ignoredRoutes: ["/api/internal/*"],
+});
+```
+
+You can also use one or more of these mounting patterns.
+
+Mount the tracker only on the route prefix you care about:
+
+```js
+app.use("/api", traffic.middleware);
 ```
 
+Register static assets or health checks before the tracker:
+
+```js
+app.use("/public", express.static("public"));
+app.get("/health", (_req, res) => res.json({ ok: true }));
+
+app.use(traffic.middleware);
+```
+
+Ignore route groups with regex:
+
+```js
+const traffic = createTrafficTracker({
+  sequelize,
+  ignoredRoutes: [
+    "/health",
+    "/favicon.ico",
+    /^\/traffic-dashboard(\/|$)/,
+    /^\/public(\/|$)/,
+  ],
+});
+```
+
+Use a function when the skip logic depends on route naming conventions:
+
+```js
+const traffic = createTrafficTracker({
+  sequelize,
+  ignoredRoutes: [
+    (route) => route.startsWith("/internal/"),
+  ],
+});
+```
+
+If you mount the tracker globally, global tracking is expected behavior.
+
 ## Dashboard Usage
 
 The dashboard is optional. Set `dashboard.enabled` to `true`, build the frontend assets, attach realtime support, and mount the provided router.
@@ -110,6 +284,7 @@ npm run build:dashboard
 | `getUserId` | `(req) => string \| null` | `undefined` | Custom resolver for `userId` |
 | `getSessionId` | `(req) => string \| null` | `undefined` | Custom resolver for `sessionId` |
 | `slowRouteThresholdMs` | `number` | `1000` | Marks requests as slow when duration meets or exceeds this value |
+| `includeRoutes` | `Array<string \| RegExp \| Function>` | `[]` | If set, only matching routes or URLs are tracked |
 | `ignoredRoutes` | `Array<string \| RegExp \| Function>` | `[]` | Routes or URLs to skip |
 | `trackIp` | `boolean` | `false` | Persist `req.ip` when enabled |
 | `trackUserAgent` | `boolean` | `true` | Persist the request `user-agent` header when enabled |

package/dist/index.cjs

@@ -147,7 +147,7 @@ function resolveTrackedRoute(req) {
   }
   return routePath || req.path || req.originalUrl || "/";
 }
-function matchesIgnoredRoute(matcher, candidate) {
+function matchesRouteMatcher(matcher, candidate) {
   if (!candidate) {
     return false;
   }
@@ -158,18 +158,32 @@ function matchesIgnoredRoute(matcher, candidate) {
     return Boolean(matcher(candidate));
   }
   if (typeof matcher === "string") {
+    if (matcher.endsWith("/*")) {
+      const prefix = matcher.slice(0, -2);
+      if (!prefix || prefix === "/") {
+        return true;
+      }
+      return candidate === prefix || candidate.startsWith(`${prefix}/`) || candidate.startsWith(`${prefix}?`);
+    }
     return candidate === matcher || candidate.startsWith(`${matcher}?`);
   }
   return false;
 }
-function shouldIgnoreRoute({
+function matchesRouteList(matchers, route, originalUrl) {
+  return matchers.some(
+    (matcher) => matchesRouteMatcher(matcher, route) || matchesRouteMatcher(matcher, originalUrl)
+  );
+}
+function shouldTrackRoute({
   route,
   originalUrl,
+  includeRoutes = [],
   ignoredRoutes = []
 }) {
-  return ignoredRoutes.some(
-    (matcher) => matchesIgnoredRoute(matcher, route) || matchesIgnoredRoute(matcher, originalUrl)
-  );
+  if (includeRoutes.length > 0 && !matchesRouteList(includeRoutes, route, originalUrl)) {
+    return false;
+  }
+  return !matchesRouteList(ignoredRoutes, route, originalUrl);
 }
 
 // src/middleware.js
@@ -223,6 +237,7 @@ function createTrackingMiddleware({
   getUserId,
   getSessionId,
   slowRouteThresholdMs = 1e3,
+  includeRoutes = [],
   ignoredRoutes = [],
   trackIp = false,
   trackUserAgent = true,
@@ -235,7 +250,12 @@ function createTrackingMiddleware({
       const endedAt = /* @__PURE__ */ new Date();
       const route = resolveTrackedRoute(req);
       const originalUrl = req.originalUrl || route;
-      if (shouldIgnoreRoute({ route, originalUrl, ignoredRoutes })) {
+      if (!shouldTrackRoute({
+        route,
+        originalUrl,
+        includeRoutes,
+        ignoredRoutes
+      })) {
         return;
       }
       void safeAsync(
@@ -828,6 +848,7 @@ function createTrafficTracker(options = {}) {
     getUserId,
     getSessionId,
     slowRouteThresholdMs = 1e3,
+    includeRoutes = [],
     ignoredRoutes = [],
     trackIp = false,
     trackUserAgent = true,
@@ -848,6 +869,7 @@ function createTrafficTracker(options = {}) {
       getUserId,
       getSessionId,
       slowRouteThresholdMs,
+      includeRoutes,
       ignoredRoutes,
       trackIp,
       trackUserAgent,

package/dist/index.js

@@ -112,7 +112,7 @@ function resolveTrackedRoute(req) {
   }
   return routePath || req.path || req.originalUrl || "/";
 }
-function matchesIgnoredRoute(matcher, candidate) {
+function matchesRouteMatcher(matcher, candidate) {
   if (!candidate) {
     return false;
   }
@@ -123,18 +123,32 @@ function matchesIgnoredRoute(matcher, candidate) {
     return Boolean(matcher(candidate));
   }
   if (typeof matcher === "string") {
+    if (matcher.endsWith("/*")) {
+      const prefix = matcher.slice(0, -2);
+      if (!prefix || prefix === "/") {
+        return true;
+      }
+      return candidate === prefix || candidate.startsWith(`${prefix}/`) || candidate.startsWith(`${prefix}?`);
+    }
     return candidate === matcher || candidate.startsWith(`${matcher}?`);
   }
   return false;
 }
-function shouldIgnoreRoute({
+function matchesRouteList(matchers, route, originalUrl) {
+  return matchers.some(
+    (matcher) => matchesRouteMatcher(matcher, route) || matchesRouteMatcher(matcher, originalUrl)
+  );
+}
+function shouldTrackRoute({
   route,
   originalUrl,
+  includeRoutes = [],
   ignoredRoutes = []
 }) {
-  return ignoredRoutes.some(
-    (matcher) => matchesIgnoredRoute(matcher, route) || matchesIgnoredRoute(matcher, originalUrl)
-  );
+  if (includeRoutes.length > 0 && !matchesRouteList(includeRoutes, route, originalUrl)) {
+    return false;
+  }
+  return !matchesRouteList(ignoredRoutes, route, originalUrl);
 }
 
 // src/middleware.js
@@ -188,6 +202,7 @@ function createTrackingMiddleware({
   getUserId,
   getSessionId,
   slowRouteThresholdMs = 1e3,
+  includeRoutes = [],
   ignoredRoutes = [],
   trackIp = false,
   trackUserAgent = true,
@@ -200,7 +215,12 @@ function createTrackingMiddleware({
       const endedAt = /* @__PURE__ */ new Date();
       const route = resolveTrackedRoute(req);
       const originalUrl = req.originalUrl || route;
-      if (shouldIgnoreRoute({ route, originalUrl, ignoredRoutes })) {
+      if (!shouldTrackRoute({
+        route,
+        originalUrl,
+        includeRoutes,
+        ignoredRoutes
+      })) {
         return;
       }
       void safeAsync(
@@ -793,6 +813,7 @@ function createTrafficTracker(options = {}) {
     getUserId,
     getSessionId,
     slowRouteThresholdMs = 1e3,
+    includeRoutes = [],
     ignoredRoutes = [],
     trackIp = false,
     trackUserAgent = true,
@@ -813,6 +834,7 @@ function createTrafficTracker(options = {}) {
       getUserId,
       getSessionId,
       slowRouteThresholdMs,
+      includeRoutes,
       ignoredRoutes,
       trackIp,
       trackUserAgent,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "express-sequelize-traffic",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Privacy-first, self-hosted Express request analytics with Sequelize storage and an optional realtime dashboard.",
   "type": "module",
   "main": "./dist/index.cjs",