@lensjs/adonis 1.0.12 → 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

@@ -15,12 +15,14 @@ import { stubsRoot } from './stubs/main.js';
 const registerEnvValidation = async (codemods) => {
     try {
         await codemods.defineEnvValidations({
-            leadingComment: 'Node lens variables',
+            leadingComment: 'LensJs variables',
             variables: {
                 LENS_BASE_PATH: 'Env.schema.string.optional()',
                 LENS_ENABLED: 'Env.schema.boolean.optional()',
                 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()',
             },
         });
     }
@@ -28,9 +30,22 @@ const registerEnvValidation = async (codemods) => {
         console.error(error);
     }
 };
+const registerMiddleware = async (codemods) => {
+    try {
+        codemods.registerMiddleware('server', [
+            {
+                path: '@lensjs/adonis/lens_middleware',
+            },
+        ]);
+    }
+    catch (error) {
+        console.error(error);
+    }
+};
 export async function configure(command) {
     const codemods = await command.createCodemods();
     await registerEnvValidation(codemods);
+    await registerMiddleware(codemods);
     await codemods.makeUsingStub(stubsRoot, 'config/lens.stub', {});
     await codemods.updateRcFile((rcFile) => {
         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 } 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,17 +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(),
-            };
             const allowedWatchers = Object.keys(config.watchers)
                 .filter((watcher) => config.watchers[watcher])
                 .map((watcher) => watchersMap[watcher])

package/build/src/adapter.d.ts

@@ -1,4 +1,4 @@
-import { RouteDefinition, LensAdapter, RequestWatcher, QueryWatcher } from '@lensjs/core';
+import { RouteDefinition, LensAdapter, RequestWatcher, QueryWatcher, CacheWatcher } from '@lensjs/core';
 import type { ApplicationService, EmitterService, HttpRouterService } from '@adonisjs/core/types';
 import { LensConfig } from './define_config.js';
 export default class AdonisAdapter extends LensAdapter {
@@ -16,6 +16,7 @@ export default class AdonisAdapter extends LensAdapter {
     registerRoutes(routes: RouteDefinition[]): void;
     protected watchRequests(requestWatcher: RequestWatcher): void;
     protected watchQueries(queryWatcher: QueryWatcher): Promise<void>;
+    protected watchCache(watcher: CacheWatcher): Promise<void>;
     serveUI(uiPath: string, spaRoute: string, _dataToInject: Record<string, any>): void;
     private matchStaticFiles;
     private getUserFromContext;

package/build/src/adapter.js

@@ -1,8 +1,10 @@
 import { LensAdapter, WatcherTypeEnum, lensUtils, } from '@lensjs/core';
 import * as path from 'path';
-import { shouldIgnoreLogging } from './utils/index.js';
+import { assertCacheBindingRegistered, shouldIgnoreLogging } from './utils/index.js';
 import string from '@adonisjs/core/helpers/string';
-import { nowISO, sqlDateTime } from '@lensjs/date';
+import { HttpContext } from '@adonisjs/core/http';
+import { nowISO } from '@lensjs/date';
+import emitter from '@adonisjs/core/services/emitter';
 export default class AdonisAdapter extends LensAdapter {
     app;
     router;
@@ -28,6 +30,9 @@ export default class AdonisAdapter extends LensAdapter {
                         this.queryWatcher = watcher;
                         await this.watchQueries(watcher);
                         break;
+                    case WatcherTypeEnum.CACHE:
+                        this.watchCache(watcher);
+                        break;
                 }
             }
         });
@@ -54,7 +59,7 @@ export default class AdonisAdapter extends LensAdapter {
             if (self.shouldIgnorePath(event.ctx.request.url(false)))
                 return;
             const request = event.ctx.request;
-            const requestId = lensUtils.generateRandomUuid();
+            const requestId = event.ctx.request.lensEntry?.requestId ?? lensUtils.generateRandomUuid();
             const logPayload = {
                 request: {
                     id: requestId,
@@ -82,20 +87,89 @@ export default class AdonisAdapter extends LensAdapter {
             if (shouldIgnoreLogging(self.app))
                 return;
             // @ts-ignore
-            this.emitter.on('db:query', async function (query) {
+            emitter.on('db:query', async function (query) {
+                const requestId = HttpContext.get()?.request.lensEntry?.requestId;
                 const duration = query.duration ? string.prettyHrTime(query.duration) : '0 ms';
                 const payload = {
                     query: lensUtils.formatSqlQuery(lensUtils.interpolateQuery(query.sql, query.bindings), self.config.watchers.queries.provider),
                     duration,
-                    createdAt: sqlDateTime(),
+                    createdAt: nowISO(),
                     type: self.config.watchers.queries.provider,
                 };
                 await queryWatcher.log({
                     data: payload,
+                    requestId,
                 });
             });
         });
     }
+    async watchCache(watcher) {
+        if (!this.config.watchers.cache)
+            return;
+        assertCacheBindingRegistered(this.app);
+        // Clear
+        // @ts-expect-error
+        this.emitter.on('cache:cleared', async (event) => {
+            await watcher.log({
+                action: 'clear',
+                data: {
+                    key: event.key,
+                },
+                createdAt: nowISO(),
+                requestId: HttpContext.get()?.request.lensEntry?.requestId,
+            });
+        });
+        // Write
+        // @ts-expect-error
+        this.emitter.on('cache:written', async (event) => {
+            await watcher.log({
+                action: 'write',
+                data: {
+                    key: event.key,
+                    value: event.value,
+                },
+                createdAt: nowISO(),
+                requestId: HttpContext.get()?.request.lensEntry?.requestId,
+            });
+        });
+        // Hit
+        // @ts-expect-error
+        this.emitter.on('cache:hit', async (event) => {
+            await watcher.log({
+                action: 'hit',
+                data: {
+                    key: event.key,
+                    value: event.value,
+                },
+                createdAt: nowISO(),
+                requestId: HttpContext.get()?.request.lensEntry?.requestId,
+            });
+        });
+        // Miss
+        // @ts-expect-error
+        this.emitter.on('cache:miss', async (event) => {
+            await watcher.log({
+                action: 'miss',
+                data: {
+                    key: event.key,
+                },
+                createdAt: nowISO(),
+                requestId: HttpContext.get()?.request.lensEntry?.requestId,
+            });
+        });
+        // Delete
+        // @ts-expect-error
+        this.emitter.on('cache:deleted', async (event) => {
+            await watcher.log({
+                action: 'delete',
+                data: {
+                    key: event.key,
+                },
+                createdAt: nowISO(),
+                requestId: HttpContext.get()?.request.lensEntry?.requestId,
+            });
+        });
+    }
     serveUI(uiPath, spaRoute, _dataToInject) {
         this.app.booted(async () => {
             this.router.get(`/${spaRoute}/favicon.ico`, (ctx) => {

package/build/src/define_config.d.ts

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

package/build/src/middlewares/lens_middleware.d.ts

@@ -0,0 +1,12 @@
+import type { HttpContext } from '@adonisjs/core/http';
+import type { NextFn } from '@adonisjs/core/types/http';
+declare module '@adonisjs/core/http' {
+    interface Request {
+        lensEntry?: {
+            requestId: string;
+        };
+    }
+}
+export default class LensMiddleware {
+    handle(ctx: HttpContext, next: NextFn): Promise<any>;
+}

package/build/src/middlewares/lens_middleware.js

@@ -0,0 +1,10 @@
+import { lensUtils } from '@lensjs/core';
+export default class LensMiddleware {
+    async handle(ctx, next) {
+        const lensEntry = {
+            requestId: lensUtils.generateRandomUuid(),
+        };
+        ctx.request.lensEntry = lensEntry;
+        return await next();
+    }
+}

package/build/src/utils/index.d.ts

@@ -3,6 +3,7 @@ import { HttpContext } from '@adonisjs/core/http';
 import { LensConfig } from '../define_config.js';
 export declare const runningInConsole: (app: ApplicationService) => boolean;
 export declare const getRunningCommand: () => string;
+export declare const assertCacheBindingRegistered: (app: ApplicationService) => void;
 export declare function allowedCommands(): boolean;
 export declare const shouldIgnoreLogging: (app: ApplicationService) => boolean;
 export declare const resolveConfigFromContext: (ctx: HttpContext) => Promise<LensConfig>;

package/build/src/utils/index.js

@@ -20,6 +20,16 @@ before creating a new Ignitor instance in:
     }
     return cmd;
 };
+export const assertCacheBindingRegistered = (app) => {
+    if (!app.container.hasBinding('cache.manager')) {
+        const message = `
+${chalk.red.bold('✖ Cache binding not registered')}
+
+Make sure to install @adonisjs/cache package to use cache watcher.
+`;
+        throw new Error(message);
+    }
+};
 export function allowedCommands() {
     const command = getRunningCommand();
     return ['queue:listen', 'schedule:work'].includes(command ?? 'WRONG');

package/build/stubs/config/lens.stub

@@ -12,6 +12,8 @@ const lensConfig = defineConfig({
   onlyPaths: [],
   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.0.12",
+  "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": "1.0.12",
+    "@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",