adonisjs-server-stats 1.9.0 → 1.10.3

package/dist/src/debug/route_inspector.js

@@ -1,46 +1,64 @@
 import { log } from '../utils/logger.js';
+/** Resolve middleware items from a MiddlewareStore or array. */
+function resolveMiddlewareItems(middleware) {
+    if (!middleware)
+        return [];
+    if (Array.isArray(middleware))
+        return middleware;
+    if (typeof middleware.all === 'function')
+        return middleware.all();
+    return [];
+}
+/** Resolve a single middleware item to its display name. */
+function resolveMiddlewareName(m) {
+    if (typeof m === 'string')
+        return m;
+    if (typeof m === 'function')
+        return m.name || null;
+    if (m?.name) {
+        const args = m.args?.length ? `(${JSON.stringify(m.args).slice(1, -1)})` : '';
+        return m.name + args;
+    }
+    return null;
+}
 /**
  * Reads the router's route table at boot time and caches it.
- * Static data computed once — routes don't change after boot.
  */
 export class RouteInspector {
     routes = [];
-    /**
-     * Inspect the router and cache all routes.
-     * Call this in the provider's `ready()` hook.
-     */
     inspect(router) {
         try {
-            // AdonisJS router exposes routes via toJSON()
             const routeData = router.toJSON();
             this.routes = [];
-            // routeData is a map of domains -> routes
             for (const domain in routeData) {
                 const domainRoutes = routeData[domain];
                 if (!Array.isArray(domainRoutes))
                     continue;
-                for (const route of domainRoutes) {
-                    const methods = Array.isArray(route.methods)
-                        ? route.methods.filter((m) => m !== 'HEAD')
-                        : [];
-                    const handler = this.resolveHandler(route.handler);
-                    const middlewareList = this.resolveMiddleware(route.middleware);
-                    for (const method of methods) {
-                        this.routes.push({
-                            method,
-                            pattern: route.pattern || '/',
-                            name: route.name || null,
-                            handler,
-                            middleware: middlewareList,
-                        });
-                    }
-                }
+                this.#processDomainRoutes(domainRoutes);
             }
         }
         catch (err) {
             log.warn(`route inspector: could not read routes — ${err?.message || 'unknown error'}`);
         }
     }
+    #processDomainRoutes(domainRoutes) {
+        for (const route of domainRoutes) {
+            const methods = Array.isArray(route.methods)
+                ? route.methods.filter((m) => m !== 'HEAD')
+                : [];
+            const handler = this.resolveHandler(route.handler);
+            const middlewareList = this.resolveMiddleware(route.middleware);
+            for (const method of methods) {
+                this.routes.push({
+                    method,
+                    pattern: route.pattern || '/',
+                    name: route.name || null,
+                    handler,
+                    middleware: middlewareList,
+                });
+            }
+        }
+    }
     resolveHandler(handler) {
         if (!handler)
             return 'unknown';
@@ -48,44 +66,25 @@ export class RouteInspector {
             return handler;
         if (typeof handler === 'function')
             return handler.name || 'closure';
-        // Lazy import handler
+        return this.#resolveObjectHandler(handler);
+    }
+    #resolveObjectHandler(handler) {
         if (handler.reference) {
             const ref = handler.reference;
             if (typeof ref === 'string')
                 return ref;
-            if (Array.isArray(ref) && ref.length >= 2) {
+            if (Array.isArray(ref) && ref.length >= 2)
                 return `${ref[0]}#${ref[1]}`;
-            }
         }
-        // Handle object with name
-        if (handler.name)
-            return handler.name;
-        return 'unknown';
+        return handler.name || 'unknown';
     }
     resolveMiddleware(middleware) {
-        if (!middleware)
-            return [];
-        // AdonisJS v6 middleware is a Middleware instance from @poppinss/middleware.
-        // Call .all() to get the Set of middleware items.
-        const items = !Array.isArray(middleware) && typeof middleware.all === 'function'
-            ? middleware.all()
-            : Array.isArray(middleware)
-                ? middleware
-                : [];
+        const items = resolveMiddlewareItems(middleware);
         const result = [];
         for (const m of items) {
-            if (typeof m === 'string') {
-                result.push(m);
-            }
-            else if (typeof m === 'function') {
-                if (m.name)
-                    result.push(m.name);
-            }
-            else if (m?.name) {
-                const args = m.args?.length ? `(${JSON.stringify(m.args).slice(1, -1)})` : '';
-                result.push(m.name + args);
-            }
-            // Skip unnamed global middleware (router.use lazy imports) — same for every route
+            const name = resolveMiddlewareName(m);
+            if (name)
+                result.push(name);
         }
         return result;
     }

package/dist/src/debug/trace_collector.d.ts

@@ -1,4 +1,12 @@
 import type { TraceSpan, TraceRecord, Emitter } from './types.js';
+/** Input for adding a span to the current trace. */
+export interface AddSpanInput {
+    label: string;
+    category: TraceSpan['category'];
+    startOffset: number;
+    duration: number;
+    metadata?: Record<string, unknown>;
+}
 /**
  * Wrap an async function in a traced span.
  *
@@ -32,9 +40,9 @@ export declare class TraceCollector {
     /** Start a new trace context for an HTTP request. */
     startTrace(callback: () => Promise<void>): Promise<void>;
     /** Finish the current trace and save it to the ring buffer. Returns the record, or null if no context. */
-    finishTrace(method: string, url: string, statusCode: number): TraceRecord | null;
+    finishTrace(method: string, url: string, statusCode: number, httpRequestId?: string): TraceRecord | null;
     /** Add a span to the current trace (if active). */
-    addSpan(label: string, category: TraceSpan['category'], startOffset: number, duration: number, metadata?: Record<string, unknown>): void;
+    addSpan(input: AddSpanInput): void;
     /** Wrap a function in a traced span with automatic nesting. */
     span<T>(label: string, category: TraceSpan['category'], fn: () => Promise<T>): Promise<T>;
     /** Hook into db:query events and console.warn to auto-create spans. */

package/dist/src/debug/trace_collector.js

@@ -5,7 +5,7 @@ import { RingBuffer } from './ring_buffer.js';
 /**
  * Module-level singleton reference for the `trace()` helper.
  */
-let globalTraceCollector = null;
+const globalRef = { current: null };
 /**
  * Wrap an async function in a traced span.
  *
@@ -22,9 +22,9 @@ let globalTraceCollector = null;
  * ```
  */
 export async function trace(label, fn) {
-    if (!globalTraceCollector)
+    if (!globalRef.current)
         return fn();
-    return globalTraceCollector.span(label, 'custom', fn);
+    return globalRef.current.span(label, 'custom', fn);
 }
 /**
  * Collects per-request traces using AsyncLocalStorage.
@@ -41,7 +41,7 @@ export class TraceCollector {
     originalConsoleWarn = null;
     constructor(maxTraces = 200) {
         this.buffer = new RingBuffer(maxTraces);
-        globalTraceCollector = this; // eslint-disable-line @typescript-eslint/no-this-alias
+        globalRef.current = this;
     }
     /** Start a new trace context for an HTTP request. */
     startTrace(callback) {
@@ -55,7 +55,7 @@ export class TraceCollector {
         return this.als.run(ctx, callback);
     }
     /** Finish the current trace and save it to the ring buffer. Returns the record, or null if no context. */
-    finishTrace(method, url, statusCode) {
+    finishTrace(method, url, statusCode, httpRequestId) {
         const ctx = this.als.getStore();
         if (!ctx)
             return null;
@@ -70,12 +70,13 @@ export class TraceCollector {
             spans: ctx.spans,
             warnings: ctx.warnings,
             timestamp: Date.now(),
+            httpRequestId: httpRequestId ?? undefined,
         };
         this.buffer.push(record);
         return record;
     }
     /** Add a span to the current trace (if active). */
-    addSpan(label, category, startOffset, duration, metadata) {
+    addSpan(input) {
         const ctx = this.als.getStore();
         if (!ctx)
             return;
@@ -84,11 +85,11 @@ export class TraceCollector {
         ctx.spans.push({
             id: String(ctx.nextSpanId++),
             parentId: ctx.currentSpanId,
-            label,
-            category,
-            startOffset: round(startOffset),
-            duration: round(duration),
-            metadata,
+            label: input.label,
+            category: input.category,
+            startOffset: round(input.startOffset),
+            duration: round(input.duration),
+            metadata: input.metadata,
         });
     }
     /** Wrap a function in a traced span with automatic nesting. */
@@ -130,10 +131,16 @@ export class TraceCollector {
                         ? data.duration[0] * 1e3 + data.duration[1] / 1e6
                         : 0;
                 const offset = performance.now() - ctx.requestStart - duration;
-                this.addSpan(data.sql || 'query', 'db', offset, duration, {
-                    method: data.method,
-                    model: data.model,
-                    connection: data.connection,
+                this.addSpan({
+                    label: data.sql || 'query',
+                    category: 'db',
+                    startOffset: offset,
+                    duration,
+                    metadata: {
+                        method: data.method,
+                        model: data.model,
+                        connection: data.connection,
+                    },
                 });
             };
             emitter.on('db:query', this.dbHandler);
@@ -159,7 +166,7 @@ export class TraceCollector {
         this.dbHandler = null;
         this.emitter = null;
         this.originalConsoleWarn = null;
-        globalTraceCollector = null;
+        globalRef.current = null;
     }
     getTraces() {
         return this.buffer.toArray().reverse();

package/dist/src/debug/types.d.ts

@@ -1,5 +1,5 @@
 /** Callback type for emitter event handlers. */
-export type EmitterHandler = (...args: any[]) => void;
+export type EmitterHandler = (...args: unknown[]) => void;
 /**
  * Minimal interface for the AdonisJS event emitter.
  *
@@ -246,6 +246,10 @@ export interface TraceRecord {
     spans: TraceSpan[];
     /** Warnings captured via `console.warn` during this request. */
     warnings: string[];
+    /** Log entries correlated to this request. */
+    logs?: Record<string, unknown>[];
+    /** Unique HTTP request identifier used for log correlation. */
+    httpRequestId?: string;
     /** Unix timestamp in **milliseconds** when the request started. */
     timestamp: number;
 }

package/dist/src/define_config.d.ts

@@ -1,67 +1,2 @@
 import type { ResolvedServerStatsConfig, ServerStatsConfig } from './types.js';
-/**
- * Define the server stats configuration with full type safety.
- *
- * All top-level fields are optional. Sensible defaults are applied
- * for any omitted fields:
- *
- * | Field         | Default                        |
- * |---------------|--------------------------------|
- * | `intervalMs`  | `3000`                         |
- * | `transport`   | `'transmit'`                   |
- * | `channelName` | `'admin/server-stats'`         |
- * | `endpoint`    | `'/admin/api/server-stats'`    |
- * | `collectors`  | `'auto'`                       |
- * | `skipInTest`  | `true`                         |
- *
- * New simplified aliases (Phase 1) are also supported. When both the
- * old name and its alias are provided, the **new name takes precedence**.
- *
- * | Alias            | Resolves to      |
- * |------------------|------------------|
- * | `pollInterval`   | `intervalMs`     |
- * | `realtime`       | `transport`      |
- * | `statsEndpoint`  | `endpoint`       |
- * | `authorize`      | `shouldShow`     |
- * | `toolbar`        | `devToolbar`     |
- * | `dashboard`      | `devToolbar`     |
- * | `advanced`       | various          |
- *
- * This is the main entry point for configuring `adonisjs-server-stats`.
- * Call it in `config/server_stats.ts` and export the result as default.
- *
- * @example
- * ```ts
- * // config/server_stats.ts — minimal (all defaults)
- * import { defineConfig } from 'adonisjs-server-stats'
- *
- * export default defineConfig({})
- * ```
- *
- * @example
- * ```ts
- * // config/server_stats.ts — explicit collectors
- * import { defineConfig } from 'adonisjs-server-stats'
- * import { processCollector, httpCollector } from 'adonisjs-server-stats/collectors'
- *
- * export default defineConfig({
- *   intervalMs: 3000,
- *   transport: 'transmit',
- *   collectors: [processCollector(), httpCollector()],
- * })
- * ```
- *
- * @example
- * ```ts
- * // config/server_stats.ts — new simplified aliases
- * import { defineConfig } from 'adonisjs-server-stats'
- *
- * export default defineConfig({
- *   pollInterval: 3000,
- *   realtime: true,
- *   toolbar: true,
- *   dashboard: true,
- * })
- * ```
- */
 export declare function defineConfig(config: ServerStatsConfig): ResolvedServerStatsConfig;