express-sequelize-traffic 0.3.0 → 0.4.0

package/README.md

@@ -65,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"],
@@ -108,6 +109,7 @@ async function start() {
     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,
@@ -190,7 +192,37 @@ Internally, the tracker records the route from `req.route?.path`, then falls bac
 
 ## How To Track Only Application Routes
 
-If you want to limit tracking to business endpoints, use one or more of these patterns.
+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:
 
@@ -252,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.3.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",