@lensjs/express 1.1.0 → 1.2.1

package/README.md

@@ -0,0 +1,93 @@
+# @lensjs/express
+
+Express.js adapter for Lens. This package provides middleware and integration points to connect your Express application with the Lens monitoring and debugging tool. It enables automatic logging of requests, queries (via `@lensjs/watchers`), and cache events.
+
+## Features
+
+*   **`lens(config: ExpressAdapterConfig)` function**: The main entry point to initialize and integrate Lens with an Express application.
+*   **`ExpressAdapter` class**: Extends `LensAdapter` from `@lensjs/core` to provide Express-specific implementations for setting up watchers, registering routes, and serving the Lens UI.
+*   **Request Watching**: Automatically captures incoming request details (method, path, headers, body, status, duration, IP) and logs them.
+*   **Query Watching**: Integrates with `@lensjs/watchers` to capture database queries from various ORMs (Kysely, Prisma, Sequelize) if configured.
+*   **Cache Watching**: Integrates with `@lensjs/watchers` to capture cache events if configured.
+*   **Exception Watching**: Captures and logs unhandled exceptions and errors within your Express application.
+*   **UI Serving**: Serves the Lens UI within your Express application at a configurable path.
+*   **Configurable Paths**: Allows specifying base paths, ignored paths, and only paths for request watching.
+*   **Body Purging**: Prevents sensitive information from being logged in responses by purging certain body types (e.g., file paths, binary data).
+*   **Authentication/User Context**: Supports optional `isAuthenticated` and `getUser` functions to associate request logs with authenticated users.
+
+## Installation
+
+```bash
+pnpm add @lensjs/express
+```
+
+## Usage Example
+
+```typescript
+import express from 'express';
+import { lens } from '@lensjs/express';
+import { createKyselyHandler } from '@lensjs/watchers/query/kysely'; // Example for Kysely
+
+const app = express();
+app.use(express.json()); // Enable JSON body parsing
+
+// Example Kysely setup (replace with your actual Kysely instance)
+const db = {
+  // ... your Kysely instance methods
+  // Mocking a Kysely-like interface for demonstration
+  on: (event: string, callback: (payload: any) => void) => {
+    if (event === 'query') {
+      // Simulate a query event
+      setTimeout(() => {
+        callback({
+          level: 'query',
+          query: { sql: 'SELECT * FROM users', parameters: [] },
+          queryDurationMillis: 15.2,
+          error: undefined,
+        });
+      }, 100);
+    }
+  },
+};
+
+// Initialize Lens with Express
+lens({
+  app,
+  appName: 'My Express App',
+  enabled: true, // Set to false in production
+  path: '/lens-dashboard', // Access Lens UI at /lens-dashboard
+  requestWatcherEnabled: true,
+  cacheWatcherEnabled: true,
+  exceptionWatcherEnabled: true,
+  queryWatcher: {
+    enabled: true,
+    handler: createKyselyHandler({ provider: 'sqlite' }), // Or createPrismaHandler, createSequelizeHandler
+  },
+  // Optional: Integrate with your authentication system
+  isAuthenticated: async (req) => {
+    return !!req.headers.authorization;
+  },
+  getUser: async (req) => {
+    // Return user details based on your auth system
+    return { id: '1', name: 'Authenticated User' };
+  },
+});
+
+// Your Express routes
+app.get('/', (req, res) => {
+  res.send('Hello World!');
+});
+
+app.get('/users', async (req, res) => {
+  // Simulate a database query
+  db.on('query', ({ query, queryDurationMillis }) => {
+    console.log(`Simulated query: ${query.sql}, Duration: ${queryDurationMillis}ms`);
+  });
+  res.json([{ id: 1, name: 'Alice' }]);
+});
+
+app.listen(3000, () => {
+  console.log('Express app listening on port 3000');
+  console.log('Lens UI available at http://localhost:3000/lens-dashboard');
+});
+```

package/dist/adapter.cjs

@@ -53,13 +53,19 @@ var ExpressAdapter = class extends import_core.LensAdapter {
     for (const watcher of this.getWatchers()) {
       switch (watcher.name) {
         case import_core.WatcherTypeEnum.REQUEST:
-          this.watchRequests(watcher);
+          if (this.config.requestWatcherEnabled) {
+            this.watchRequests(watcher);
+          }
           break;
         case import_core.WatcherTypeEnum.QUERY:
-          void this.watchQueries(watcher);
+          if (this.config.queryWatcher.enabled) {
+            void this.watchQueries(watcher);
+          }
           break;
         case import_core.WatcherTypeEnum.CACHE:
-          void this.watchCache(watcher);
+          if (this.config.cacheWatcherEnabled) {
+            void this.watchCache(watcher);
+          }
           break;
       }
     }
@@ -119,11 +125,11 @@ var ExpressAdapter = class extends import_core.LensAdapter {
   watchRequests(requestWatcher) {
     if (!this.config.requestWatcherEnabled) return;
     this.app.use((req, res, next) => {
+      if (this.shouldIgnorePath(req.path)) return next();
       const context = {
         requestId: import_core.lensUtils.generateRandomUuid()
       };
       import_core.lensContext.run(context, () => {
-        if (this.shouldIgnorePath(req.path)) return next();
         const start = process.hrtime();
         this.patchResponseMethods(res);
         res.on("finish", async () => {

package/dist/adapter.js

@@ -25,13 +25,19 @@ var ExpressAdapter = class extends LensAdapter {
     for (const watcher of this.getWatchers()) {
       switch (watcher.name) {
         case WatcherTypeEnum.REQUEST:
-          this.watchRequests(watcher);
+          if (this.config.requestWatcherEnabled) {
+            this.watchRequests(watcher);
+          }
           break;
         case WatcherTypeEnum.QUERY:
-          void this.watchQueries(watcher);
+          if (this.config.queryWatcher.enabled) {
+            void this.watchQueries(watcher);
+          }
           break;
         case WatcherTypeEnum.CACHE:
-          void this.watchCache(watcher);
+          if (this.config.cacheWatcherEnabled) {
+            void this.watchCache(watcher);
+          }
           break;
       }
     }
@@ -91,11 +97,11 @@ var ExpressAdapter = class extends LensAdapter {
   watchRequests(requestWatcher) {
     if (!this.config.requestWatcherEnabled) return;
     this.app.use((req, res, next) => {
+      if (this.shouldIgnorePath(req.path)) return next();
       const context = {
         requestId: lensUtils.generateRandomUuid()
       };
       lensContext.run(context, () => {
-        if (this.shouldIgnorePath(req.path)) return next();
         const start = process.hrtime();
         this.patchResponseMethods(res);
         res.on("finish", async () => {

package/dist/index.cjs

@@ -30,6 +30,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  handleExceptions: () => handleExceptions,
   lens: () => lens
 });
 module.exports = __toCommonJS(index_exports);
@@ -56,13 +57,19 @@ var ExpressAdapter = class extends import_core.LensAdapter {
     for (const watcher of this.getWatchers()) {
       switch (watcher.name) {
         case import_core.WatcherTypeEnum.REQUEST:
-          this.watchRequests(watcher);
+          if (this.config.requestWatcherEnabled) {
+            this.watchRequests(watcher);
+          }
           break;
         case import_core.WatcherTypeEnum.QUERY:
-          void this.watchQueries(watcher);
+          if (this.config.queryWatcher.enabled) {
+            void this.watchQueries(watcher);
+          }
           break;
         case import_core.WatcherTypeEnum.CACHE:
-          void this.watchCache(watcher);
+          if (this.config.cacheWatcherEnabled) {
+            void this.watchCache(watcher);
+          }
           break;
       }
     }
@@ -122,11 +129,11 @@ var ExpressAdapter = class extends import_core.LensAdapter {
   watchRequests(requestWatcher) {
     if (!this.config.requestWatcherEnabled) return;
     this.app.use((req, res, next) => {
+      if (this.shouldIgnorePath(req.path)) return next();
       const context = {
         requestId: import_core.lensUtils.generateRandomUuid()
       };
       import_core.lensContext.run(context, () => {
-        if (this.shouldIgnorePath(req.path)) return next();
         const start = process.hrtime();
         this.patchResponseMethods(res);
         res.on("finish", async () => {
@@ -212,6 +219,10 @@ var ExpressAdapter = class extends import_core.LensAdapter {
 };
 
 // src/index.ts
+var import_core3 = require("@lensjs/core");
+var import_core4 = require("@lensjs/core");
+var import_core5 = require("@lensjs/core");
+var import_core6 = require("@lensjs/core");
 var defaultConfig = {
   appName: "Lens",
   enabled: true,
@@ -219,7 +230,8 @@ var defaultConfig = {
   ignoredPaths: [],
   onlyPaths: [],
   requestWatcherEnabled: true,
-  cacheWatcherEnabled: false
+  cacheWatcherEnabled: false,
+  exceptionWatcherEnabled: true
 };
 var lens = async (config) => {
   const adapter = new ExpressAdapter({ app: config.app });
@@ -240,6 +252,10 @@ var lens = async (config) => {
     {
       enabled: mergedConfig.queryWatcher?.enabled,
       watcher: new import_core2.QueryWatcher()
+    },
+    {
+      enabled: mergedConfig.exceptionWatcherEnabled,
+      watcher: new import_core2.ExceptionWatcher()
     }
   ];
   defaultWatchers.forEach((watcher) => {
@@ -247,7 +263,6 @@ var lens = async (config) => {
       watchers.push(watcher.watcher);
     }
   });
-  console.log("currentWatchers", watchers);
   const { ignoredPaths, normalizedPath } = import_core2.lensUtils.prepareIgnoredPaths(
     mergedConfig.path,
     mergedConfig.ignoredPaths
@@ -258,8 +273,31 @@ var lens = async (config) => {
     enabled: mergedConfig.enabled,
     basePath: normalizedPath
   });
+  return {
+    handleExceptions: (app) => handleExceptions({
+      app,
+      enabled: mergedConfig.exceptionWatcherEnabled,
+      watcher: watchers.find((w) => w.name === import_core3.WatcherTypeEnum.EXCEPTION)
+    })
+  };
 };
+function handleExceptions({
+  app,
+  enabled,
+  watcher
+}) {
+  if (!enabled || !watcher) return;
+  app.use(async (err, _, __, next) => {
+    await watcher.log({
+      ...import_core6.lensExceptionUtils.constructErrorObject(err),
+      requestId: import_core4.lensContext.getStore()?.requestId
+    });
+    next(err);
+  });
+  (0, import_core5.handleUncaughExceptions)(watcher);
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  handleExceptions,
   lens
 });

package/dist/index.d.cts

@@ -1,8 +1,15 @@
+import { ExceptionWatcher } from '@lensjs/core';
 import { ExpressAdapterConfig } from './types/index.cjs';
-import 'express';
+import { Application } from 'express';
 import '@lensjs/watchers';
-import '@lensjs/core';
 
-declare const lens: (config: ExpressAdapterConfig) => Promise<void>;
+declare const lens: (config: ExpressAdapterConfig) => Promise<{
+    handleExceptions: (app: Application) => void;
+}>;
+declare function handleExceptions({ app, enabled, watcher, }: {
+    app: Application;
+    enabled: boolean;
+    watcher?: ExceptionWatcher;
+}): void;
 
-export { lens };
+export { handleExceptions, lens };

package/dist/index.d.ts

@@ -1,8 +1,15 @@
+import { ExceptionWatcher } from '@lensjs/core';
 import { ExpressAdapterConfig } from './types/index.js';
-import 'express';
+import { Application } from 'express';
 import '@lensjs/watchers';
-import '@lensjs/core';
 
-declare const lens: (config: ExpressAdapterConfig) => Promise<void>;
+declare const lens: (config: ExpressAdapterConfig) => Promise<{
+    handleExceptions: (app: Application) => void;
+}>;
+declare function handleExceptions({ app, enabled, watcher, }: {
+    app: Application;
+    enabled: boolean;
+    watcher?: ExceptionWatcher;
+}): void;
 
-export { lens };
+export { handleExceptions, lens };

package/dist/index.js

@@ -1,6 +1,7 @@
 // src/index.ts
 import {
   CacheWatcher as CacheWatcher2,
+  ExceptionWatcher,
   Lens,
   lensUtils as lensUtils2,
   QueryWatcher as QueryWatcher2,
@@ -34,13 +35,19 @@ var ExpressAdapter = class extends LensAdapter {
     for (const watcher of this.getWatchers()) {
       switch (watcher.name) {
         case WatcherTypeEnum.REQUEST:
-          this.watchRequests(watcher);
+          if (this.config.requestWatcherEnabled) {
+            this.watchRequests(watcher);
+          }
           break;
         case WatcherTypeEnum.QUERY:
-          void this.watchQueries(watcher);
+          if (this.config.queryWatcher.enabled) {
+            void this.watchQueries(watcher);
+          }
           break;
         case WatcherTypeEnum.CACHE:
-          void this.watchCache(watcher);
+          if (this.config.cacheWatcherEnabled) {
+            void this.watchCache(watcher);
+          }
           break;
       }
     }
@@ -100,11 +107,11 @@ var ExpressAdapter = class extends LensAdapter {
   watchRequests(requestWatcher) {
     if (!this.config.requestWatcherEnabled) return;
     this.app.use((req, res, next) => {
+      if (this.shouldIgnorePath(req.path)) return next();
       const context = {
         requestId: lensUtils.generateRandomUuid()
       };
       lensContext.run(context, () => {
-        if (this.shouldIgnorePath(req.path)) return next();
         const start = process.hrtime();
         this.patchResponseMethods(res);
         res.on("finish", async () => {
@@ -190,6 +197,10 @@ var ExpressAdapter = class extends LensAdapter {
 };
 
 // src/index.ts
+import { WatcherTypeEnum as WatcherTypeEnum2 } from "@lensjs/core";
+import { lensContext as lensContext2 } from "@lensjs/core";
+import { handleUncaughExceptions } from "@lensjs/core";
+import { lensExceptionUtils } from "@lensjs/core";
 var defaultConfig = {
   appName: "Lens",
   enabled: true,
@@ -197,7 +208,8 @@ var defaultConfig = {
   ignoredPaths: [],
   onlyPaths: [],
   requestWatcherEnabled: true,
-  cacheWatcherEnabled: false
+  cacheWatcherEnabled: false,
+  exceptionWatcherEnabled: true
 };
 var lens = async (config) => {
   const adapter = new ExpressAdapter({ app: config.app });
@@ -218,6 +230,10 @@ var lens = async (config) => {
     {
       enabled: mergedConfig.queryWatcher?.enabled,
       watcher: new QueryWatcher2()
+    },
+    {
+      enabled: mergedConfig.exceptionWatcherEnabled,
+      watcher: new ExceptionWatcher()
     }
   ];
   defaultWatchers.forEach((watcher) => {
@@ -225,7 +241,6 @@ var lens = async (config) => {
       watchers.push(watcher.watcher);
     }
   });
-  console.log("currentWatchers", watchers);
   const { ignoredPaths, normalizedPath } = lensUtils2.prepareIgnoredPaths(
     mergedConfig.path,
     mergedConfig.ignoredPaths
@@ -236,7 +251,30 @@ var lens = async (config) => {
     enabled: mergedConfig.enabled,
     basePath: normalizedPath
   });
+  return {
+    handleExceptions: (app) => handleExceptions({
+      app,
+      enabled: mergedConfig.exceptionWatcherEnabled,
+      watcher: watchers.find((w) => w.name === WatcherTypeEnum2.EXCEPTION)
+    })
+  };
 };
+function handleExceptions({
+  app,
+  enabled,
+  watcher
+}) {
+  if (!enabled || !watcher) return;
+  app.use(async (err, _, __, next) => {
+    await watcher.log({
+      ...lensExceptionUtils.constructErrorObject(err),
+      requestId: lensContext2.getStore()?.requestId
+    });
+    next(err);
+  });
+  handleUncaughExceptions(watcher);
+}
 export {
+  handleExceptions,
   lens
 };

package/dist/types/index.d.cts

@@ -11,6 +11,7 @@ type ExpressAdapterConfig = {
     onlyPaths?: RegExp[];
     requestWatcherEnabled?: boolean;
     cacheWatcherEnabled?: boolean;
+    exceptionWatcherEnabled?: boolean;
     queryWatcher?: {
         enabled: boolean;
         handler: QueryWatcherHandler;

package/dist/types/index.d.ts

@@ -11,6 +11,7 @@ type ExpressAdapterConfig = {
     onlyPaths?: RegExp[];
     requestWatcherEnabled?: boolean;
     cacheWatcherEnabled?: boolean;
+    exceptionWatcherEnabled?: boolean;
     queryWatcher?: {
         enabled: boolean;
         handler: QueryWatcherHandler;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lensjs/express",
-  "version": "1.1.0",
+  "version": "1.2.1",
   "description": "Express adapter for LensJs",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -20,14 +20,17 @@
   "dependencies": {
     "express": "^5.1.0",
     "@lensjs/date": "1.0.12",
-    "@lensjs/watchers": "1.0.13",
-    "@lensjs/core": "2.0.0",
-    "@lensjs/typescript-config": "1.0.12"
+    "@lensjs/typescript-config": "1.0.12",
+    "@lensjs/watchers": "1.0.15",
+    "@lensjs/core": "2.1.1"
   },
   "devDependencies": {
-    "@types/express": "^5.0.3"
+    "@types/express": "^5.0.3",
+    "supertest": "^7.1.4",
+    "vitest": "^3.2.4"
   },
   "scripts": {
-    "build": "tsup --clean"
+    "build": "tsup --clean",
+    "test": "vitest run"
   }
 }