@lensjs/adonis 1.1.0 → 1.2.0

package/README.md

@@ -1 +1,68 @@
-- first user should add the running console in bin/console file
+# @lensjs/adonis
+
+AdonisJS adapter for Lens. This package provides a service provider and middleware to seamlessly integrate the Lens monitoring and debugging tool into your AdonisJS applications. It enables automatic logging of requests, database queries, and cache events within the AdonisJS ecosystem.
+
+## Features
+
+*   **`LensServiceProvider`**: Registers the Lens configuration and initializes the Lens core with AdonisJS-specific adapters and watchers during the application boot process.
+*   **`AdonisAdapter` class**: Extends `LensAdapter` from `@lensjs/core`, providing AdonisJS-specific implementations for handling HTTP requests, database queries (via Adonis's `db:query` event), cache events, route registration, and serving the Lens UI.
+*   **`defineConfig` function**: A helper to define the Lens configuration within `config/lens.ts`, ensuring type safety and proper resolution.
+*   **`LensMiddleware`**: An AdonisJS middleware that generates a unique `requestId` for each incoming HTTP request, allowing all subsequent events (queries, cache) within that request's lifecycle to be correlated.
+*   **Request Watching**: Captures detailed information about HTTP requests, including method, URL, headers, body, status code, duration, and associated user (if configured).
+*   **Query Watching**: Hooks into AdonisJS's database query events to log SQL queries, their bindings, duration, and type.
+*   **Cache Watching**: Listens to AdonisJS cache events (read, write, hit, miss, delete, clear) to log cache interactions.
+*   **Exception Watching**: Captures and logs exceptions and errors within your AdonisJS application.
+*   **UI Serving**: Serves the Lens UI within your AdonisJS application at a configurable path.
+*   **Configurable Watchers**: Allows enabling or disabling specific watchers (requests, queries, cache) via the Lens configuration.
+*   **Authentication/User Context**: Supports optional `isAuthenticated` and `getUser` functions in the configuration to associate request logs with authenticated users.
+*   **Console/Command Ignoring**: Provides utilities to ignore logging for console commands or specific environments.
+
+## Installation
+
+```bash
+pnpm add @lensjs/adonis
+node ace configure @lensjs/adonis
+```
+(The `node ace configure` command will typically set up the service provider and config file.)
+
+## Usage Example (config/lens.ts)
+
+```typescript
+import { defineConfig } from '@lensjs/adonis';
+
+export default defineConfig({
+  appName: 'My Adonis App',
+  enabled: true, // Set to false in production
+  path: '/lens', // Access Lens UI at /lens
+  ignoredPaths: [], // Regex patterns for paths to ignore
+  onlyPaths: [],   // Regex patterns for paths to only watch
+  watchers: {
+    queries: {
+      enabled: true,
+      provider: 'sqlite', // or 'postgresql', 'mysql', 'mariadb', 'plsql', 'transactsql'
+    },
+    cache: true,
+    requests: true,
+    exceptions: true,
+  },
+  // Optional: Integrate with your authentication system
+  isAuthenticated: async (ctx) => {
+    return !!ctx.auth.user;
+  },
+  getUser: async (ctx) => {
+    return { id: ctx.auth.user!.id, name: ctx.auth.user!.email };
+  },
+});
+```
+
+## Usage Example (start/kernel.ts - Register Middleware)
+
+```typescript
+// ... other imports
+import LensMiddleware from '@lensjs/adonis/lens_middleware';
+
+Server.middleware.global([
+  // ... other global middleware
+  () => new LensMiddleware(), // Register Lens middleware
+]);
+```

package/build/configure.js

@@ -22,6 +22,7 @@ const registerEnvValidation = async (codemods) => {
                 LENS_ENABLE_QUERY_WATCHER: 'Env.schema.boolean.optional()',
                 LENS_ENABLE_REQUEST_WATCHER: 'Env.schema.boolean.optional()',
                 LENS_ENABLE_CACHE_WATCHER: 'Env.schema.boolean.optional()',
+                LENS_ENABLE_EXCEPTION_WATCHER: 'Env.schema.boolean.optional()',
             },
         });
     }
@@ -31,9 +32,9 @@ const registerEnvValidation = async (codemods) => {
 };
 const registerMiddleware = async (codemods) => {
     try {
-        codemods.registerMiddleware('router', [
+        codemods.registerMiddleware('server', [
             {
-                path: '@lens/adonis/lens_middleware',
+                path: '@lensjs/adonis/lens_middleware',
             },
         ]);
     }
@@ -47,6 +48,6 @@ export async function configure(command) {
     await registerMiddleware(codemods);
     await codemods.makeUsingStub(stubsRoot, 'config/lens.stub', {});
     await codemods.updateRcFile((rcFile) => {
-        rcFile.addProvider('@lens/adonis/lens_provider');
+        rcFile.addProvider('@lensjs/adonis/lens_provider');
     });
 }

package/build/providers/lens_service_provider.d.ts

@@ -1,10 +1,13 @@
+import { Exception } from '@poppinss/utils';
 import type { ApplicationService } from '@adonisjs/core/types';
 import { LensConfig } from '../src/define_config.js';
 import { QueryEntry } from '@lensjs/core';
+import { HttpContext } from '@adonisjs/core/http';
 declare module '@adonisjs/core/types' {
     interface ContainerBindings {
         lensConfig: LensConfig;
         queries?: QueryEntry['data'][];
+        watchExceptions?: (error: Exception, ctx: HttpContext) => Promise<void>;
     }
 }
 export default class LensServiceProvider {

package/build/providers/lens_service_provider.js

@@ -1,6 +1,6 @@
 import { configProvider } from '@adonisjs/core';
 import { RuntimeException } from '@poppinss/utils';
-import { Lens, lensUtils, RequestWatcher, QueryWatcher, CacheWatcher } from '@lensjs/core';
+import { Lens, lensUtils, RequestWatcher, QueryWatcher, CacheWatcher, lensExceptionUtils, ExceptionWatcher, handleUncaughExceptions, } from '@lensjs/core';
 import AdonisAdapter from '../src/adapter.js';
 export default class LensServiceProvider {
     app;
@@ -10,18 +10,30 @@ export default class LensServiceProvider {
     async boot() {
         const lensConfigProvider = this.app.config.get('lens');
         const config = await configProvider.resolve(this.app, lensConfigProvider);
+        const watchersMap = {
+            requests: new RequestWatcher(),
+            queries: new QueryWatcher(),
+            cache: new CacheWatcher(),
+            exceptions: new ExceptionWatcher(),
+        };
         if (!config) {
             throw new RuntimeException('Invalid "config/lens.ts" file. Make sure you are using the "defineConfig" method');
         }
         const { normalizedPath, ignoredPaths } = lensUtils.prepareIgnoredPaths(config.path, config.ignoredPaths);
         config.ignoredPaths = ignoredPaths;
+        if (config.watchers.exceptions) {
+            this.app.container.bindValue('watchExceptions', async (error, ctx) => {
+                const payload = lensExceptionUtils.constructErrorObject(error);
+                const requestId = ctx.request.lensEntry?.requestId;
+                await watchersMap.exceptions?.log({
+                    ...payload,
+                    requestId,
+                });
+            });
+            handleUncaughExceptions(watchersMap.exceptions);
+        }
         this.app.container.bindValue('lensConfig', config);
         this.app.booted(async () => {
-            const watchersMap = {
-                requests: new RequestWatcher(),
-                queries: new QueryWatcher(),
-                cache: new CacheWatcher(),
-            };
             const allowedWatchers = Object.keys(config.watchers)
                 .filter((watcher) => config.watchers[watcher])
                 .map((watcher) => watchersMap[watcher])

package/build/src/define_config.d.ts

@@ -14,6 +14,7 @@ export type LensConfig = {
         };
         cache: boolean;
         requests: boolean;
+        exceptions: boolean;
     };
     isAuthenticated?: (ctx: HttpContext) => Promise<boolean>;
     getUser?: (ctx: HttpContext) => Promise<UserEntry>;

package/build/stubs/config/lens.stub

@@ -13,6 +13,7 @@ const lensConfig = defineConfig({
   watchers: {
     requests: env.get('LENS_ENABLE_REQUEST_WATCHER', true),
     cache: env.get('LENS_ENABLE_CACHE_WATCHER', false),
+    exceptions: env.get('LENS_ENABLE_EXCEPTION_WATCHER', true),
     queries: {
       enabled: env.get('LENS_ENABLE_QUERY_WATCHER', true),
       provider: 'sqlite', // Change to your database provider

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@lensjs/adonis",
   "description": "AdonisJs adapter for lens package",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "engines": {
     "node": ">=20.6.0"
   },
@@ -47,7 +47,7 @@
   "dependencies": {
     "@poppinss/utils": "^6.10.1",
     "chalk": "^5.6.0",
-    "@lensjs/core": "2.0.0",
+    "@lensjs/core": "2.1.0",
     "@lensjs/date": "1.0.12"
   },
   "publishConfig": {
@@ -78,7 +78,6 @@
     "lint": "eslint .",
     "format": "prettier --write .",
     "quick:test": "node --import=./tsnode.esm.js --enable-source-maps bin/test.ts",
-    "pretest": "npm run lint",
     "test": "c8 npm run quick:test",
     "prebuild": "npm run clean",
     "build": "tsc",