adonisjs-server-stats 1.9.0 → 1.10.3

package/dist/src/collectors/queue_collector.js

@@ -1,36 +1,67 @@
 import { log, dim, bold } from '../utils/logger.js';
+/** Default metrics returned when queue data is unavailable. */
+const QUEUE_DEFAULTS = {
+    queueActive: 0,
+    queueWaiting: 0,
+    queueDelayed: 0,
+    queueFailed: 0,
+    queueWorkerCount: 0,
+};
+/** Fetch job counts from a BullMQ queue. */
+async function fetchQueueCounts(queueName, connection) {
+    const { Queue } = await import('bullmq');
+    const queue = new Queue(queueName, { connection });
+    const [counts, workers] = await Promise.all([queue.getJobCounts(), queue.getWorkers()]);
+    await queue.close();
+    return {
+        queueActive: counts.active ?? 0,
+        queueWaiting: counts.waiting ?? 0,
+        queueDelayed: counts.delayed ?? 0,
+        queueFailed: counts.failed ?? 0,
+        queueWorkerCount: workers.length,
+    };
+}
+/** Handle queue collection errors with one-time warnings. */
+function handleQueueError(error, queueName, connection, warned) {
+    const message = error instanceof Error ? error.message : String(error);
+    const isImportError = message.includes('Cannot find package') ||
+        message.includes('MODULE_NOT_FOUND') ||
+        message.includes('ERR_MODULE_NOT_FOUND');
+    if (isImportError) {
+        if (!warned.missingBullmq) {
+            warned.missingBullmq = true;
+            log.warn(`Queue collector ${bold(queueName)}: ${bold('bullmq')} is not installed`);
+            log.block('Install the peer dependency to enable queue metrics:', [
+                `${bold('npm install bullmq')}`,
+                dim('Queue metrics will return zeros until bullmq is available.'),
+            ]);
+        }
+    }
+    else if (!warned.connectionError) {
+        warned.connectionError = true;
+        const { host, port } = connection;
+        log.warn(`Queue collector ${bold(queueName)}: cannot connect to Redis at ${bold(`${host}:${port}`)}`);
+        log.block('Connection failed:', [
+            `${dim('Error:')} ${message}`,
+            dim('Is Redis running? Check with: redis-cli ping'),
+            dim('Queue metrics will return zeros until the connection succeeds.'),
+        ]);
+    }
+}
 /**
  * Monitors a BullMQ job queue for active, waiting, delayed, and failed jobs.
  *
- * Creates a temporary BullMQ `Queue` instance each tick to fetch counts,
- * then immediately closes it.
- *
- * **Metrics produced:**
- * - `queueActive` -- jobs being processed
- * - `queueWaiting` -- jobs waiting for a worker
- * - `queueDelayed` -- jobs scheduled for the future
- * - `queueFailed` -- permanently failed jobs
- * - `queueWorkerCount` -- connected worker processes
- *
  * Returns zeros if BullMQ is unavailable or the queue cannot be reached.
  *
  * **Peer dependencies:** `bullmq`
- *
- * @example
- * ```ts
- * import { queueCollector } from 'adonisjs-server-stats/collectors'
- *
- * queueCollector({
- *   queueName: 'default',
- *   connection: { host: 'localhost', port: 6379, password: 'secret' },
- * })
- * ```
  */
 export function queueCollector(opts) {
     const queueName = opts.queueName ?? 'default';
-    let warnedMissingBullmq = false;
-    let warnedConnectionError = false;
-    let warnedMissingConnection = false;
+    const warned = {
+        missingBullmq: false,
+        connectionError: false,
+        missingConnection: false,
+    };
     return {
         name: 'queue',
         label: `queue — ${queueName} @ ${opts.connection?.host ?? '?'}:${opts.connection?.port ?? '?'}`,
@@ -43,68 +74,21 @@ export function queueCollector(opts) {
         },
         async collect() {
             if (!opts.connection) {
-                if (!warnedMissingConnection) {
-                    warnedMissingConnection = true;
+                if (!warned.missingConnection) {
+                    warned.missingConnection = true;
                     log.warn(`Queue collector ${bold(queueName)}: missing ${bold('connection')} option`);
                     log.block('Provide a Redis connection when creating the collector:', [
                         `${dim('queueCollector({ connection: { host: "localhost", port: 6379 } })')}`,
                     ]);
                 }
-                return {
-                    queueActive: 0,
-                    queueWaiting: 0,
-                    queueDelayed: 0,
-                    queueFailed: 0,
-                    queueWorkerCount: 0,
-                };
+                return QUEUE_DEFAULTS;
             }
             try {
-                const { Queue } = await import('bullmq');
-                const queue = new Queue(queueName, { connection: opts.connection });
-                const [counts, workers] = await Promise.all([queue.getJobCounts(), queue.getWorkers()]);
-                await queue.close();
-                return {
-                    queueActive: counts.active ?? 0,
-                    queueWaiting: counts.waiting ?? 0,
-                    queueDelayed: counts.delayed ?? 0,
-                    queueFailed: counts.failed ?? 0,
-                    queueWorkerCount: workers.length,
-                };
+                return await fetchQueueCounts(queueName, opts.connection);
             }
             catch (error) {
-                const message = error instanceof Error ? error.message : String(error);
-                const isImportError = message.includes('Cannot find package') ||
-                    message.includes('MODULE_NOT_FOUND') ||
-                    message.includes('ERR_MODULE_NOT_FOUND');
-                if (isImportError) {
-                    if (!warnedMissingBullmq) {
-                        warnedMissingBullmq = true;
-                        log.warn(`Queue collector ${bold(queueName)}: ${bold('bullmq')} is not installed`);
-                        log.block('Install the peer dependency to enable queue metrics:', [
-                            `${bold('npm install bullmq')}`,
-                            dim('Queue metrics will return zeros until bullmq is available.'),
-                        ]);
-                    }
-                }
-                else {
-                    if (!warnedConnectionError) {
-                        warnedConnectionError = true;
-                        const { host, port } = opts.connection;
-                        log.warn(`Queue collector ${bold(queueName)}: cannot connect to Redis at ${bold(`${host}:${port}`)}`);
-                        log.block('Connection failed:', [
-                            `${dim('Error:')} ${message}`,
-                            dim('Is Redis running? Check with: redis-cli ping'),
-                            dim('Queue metrics will return zeros until the connection succeeds.'),
-                        ]);
-                    }
-                }
-                return {
-                    queueActive: 0,
-                    queueWaiting: 0,
-                    queueDelayed: 0,
-                    queueFailed: 0,
-                    queueWorkerCount: 0,
-                };
+                handleQueueError(error, queueName, opts.connection, warned);
+                return QUEUE_DEFAULTS;
             }
         },
     };

package/dist/src/collectors/redis_collector.d.ts

@@ -1,17 +1,17 @@
 import type { MetricCollector } from './collector.js';
+/** Parse a Redis INFO section into key-value pairs. */
+export declare function parseRedisInfo(info: string): Record<string, string>;
+/** Compute metrics from parsed Redis INFO sections + DBSIZE. */
+export declare function computeRedisMetrics(memParsed: Record<string, string>, statsParsed: Record<string, string>, dbSize: unknown): {
+    redisOk: boolean;
+    redisMemoryUsedMb: number;
+    redisConnectedClients: number;
+    redisKeysCount: number;
+    redisHitRate: number;
+};
 /**
  * Monitors Redis health, memory, connections, keys, and cache hit rate.
  *
- * Uses the AdonisJS Redis service to send `PING`, `INFO`, and `DBSIZE`
- * commands. Returns safe defaults if Redis is unavailable.
- *
- * **Metrics produced:**
- * - `redisOk` -- `true` if PING returned PONG
- * - `redisMemoryUsedMb` -- server memory usage (MB)
- * - `redisConnectedClients` -- connected client count
- * - `redisKeysCount` -- total keys across all databases
- * - `redisHitRate` -- cache hit rate (%)
- *
  * **Peer dependencies:** `@adonisjs/redis`
  */
 export declare function redisCollector(): MetricCollector;

package/dist/src/collectors/redis_collector.js

@@ -3,19 +3,71 @@ import { log, dim, bold } from '../utils/logger.js';
 let warnedNotInstalled = false;
 let warnedPingFailed = false;
 let warnedConnectionError = false;
+/** Default metrics returned when Redis is unavailable. */
+const REDIS_DEFAULTS = {
+    redisOk: false,
+    redisMemoryUsedMb: 0,
+    redisConnectedClients: 0,
+    redisKeysCount: 0,
+    redisHitRate: 0,
+};
+/** Parse a Redis INFO section into key-value pairs. */
+export function parseRedisInfo(info) {
+    const result = {};
+    for (const line of info.split('\r\n')) {
+        const idx = line.indexOf(':');
+        if (idx > 0) {
+            result[line.slice(0, idx)] = line.slice(idx + 1);
+        }
+    }
+    return result;
+}
+/** Compute metrics from parsed Redis INFO sections + DBSIZE. */
+export function computeRedisMetrics(memParsed, statsParsed, dbSize) {
+    const usedMemoryBytes = Number.parseInt(memParsed['used_memory'] ?? '0', 10);
+    const connectedClients = Number.parseInt(memParsed['connected_clients'] ?? statsParsed['connected_clients'] ?? '0', 10);
+    const hits = Number.parseInt(statsParsed['keyspace_hits'] ?? '0', 10);
+    const misses = Number.parseInt(statsParsed['keyspace_misses'] ?? '0', 10);
+    const total = hits + misses;
+    const hitRate = total > 0 ? (hits / total) * 100 : 0;
+    return {
+        redisOk: true,
+        redisMemoryUsedMb: usedMemoryBytes / (1024 * 1024),
+        redisConnectedClients: connectedClients,
+        redisKeysCount: typeof dbSize === 'number' ? dbSize : 0,
+        redisHitRate: hitRate,
+    };
+}
+/** Import Redis service, returning null if unavailable. */
+async function importRedis() {
+    try {
+        const mod = await appImport('@adonisjs/redis/services/main');
+        return mod.default;
+    }
+    catch {
+        if (!warnedNotInstalled) {
+            warnedNotInstalled = true;
+            log.block(`Redis collector ${bold('skipped')} — @adonisjs/redis is not installed`, [
+                dim('Redis metrics will return defaults until the package is added.'),
+                `Run ${bold('node ace add @adonisjs/redis')} to install it.`,
+            ]);
+        }
+        return null;
+    }
+}
+/** Warn once when PING fails. */
+function warnPingFailed(pong) {
+    if (warnedPingFailed)
+        return;
+    warnedPingFailed = true;
+    log.block(`Redis collector ${bold('unhealthy')} — PING returned ${bold(String(pong))} instead of PONG`, [
+        dim('Redis may be down or misconfigured.'),
+        `Check your connection settings in ${bold('config/redis.ts')}.`,
+    ]);
+}
 /**
  * Monitors Redis health, memory, connections, keys, and cache hit rate.
  *
- * Uses the AdonisJS Redis service to send `PING`, `INFO`, and `DBSIZE`
- * commands. Returns safe defaults if Redis is unavailable.
- *
- * **Metrics produced:**
- * - `redisOk` -- `true` if PING returned PONG
- * - `redisMemoryUsedMb` -- server memory usage (MB)
- * - `redisConnectedClients` -- connected client count
- * - `redisKeysCount` -- total keys across all databases
- * - `redisHitRate` -- cache hit rate (%)
- *
  * **Peer dependencies:** `@adonisjs/redis`
  */
 export function redisCollector() {
@@ -26,70 +78,21 @@ export function redisCollector() {
             return {};
         },
         async collect() {
-            const defaults = {
-                redisOk: false,
-                redisMemoryUsedMb: 0,
-                redisConnectedClients: 0,
-                redisKeysCount: 0,
-                redisHitRate: 0,
-            };
-            let redis;
-            try {
-                const mod = await appImport('@adonisjs/redis/services/main');
-                redis = mod.default;
-            }
-            catch {
-                if (!warnedNotInstalled) {
-                    warnedNotInstalled = true;
-                    log.block(`Redis collector ${bold('skipped')} — @adonisjs/redis is not installed`, [
-                        dim('Redis metrics will return defaults until the package is added.'),
-                        `Run ${bold('node ace add @adonisjs/redis')} to install it.`,
-                    ]);
-                }
-                return defaults;
-            }
+            const redis = await importRedis();
+            if (!redis)
+                return REDIS_DEFAULTS;
             try {
                 const pong = await redis.ping();
                 if (pong !== 'PONG') {
-                    if (!warnedPingFailed) {
-                        warnedPingFailed = true;
-                        log.block(`Redis collector ${bold('unhealthy')} — PING returned ${bold(String(pong))} instead of PONG`, [
-                            dim('Redis may be down or misconfigured.'),
-                            `Check your connection settings in ${bold('config/redis.ts')}.`,
-                        ]);
-                    }
-                    return defaults;
+                    warnPingFailed(pong);
+                    return REDIS_DEFAULTS;
                 }
                 const [memoryInfo, statsInfo, dbSize] = await Promise.all([
                     redis.info('memory'),
                     redis.info('stats'),
                     redis.dbsize(),
                 ]);
-                const parseInfo = (info) => {
-                    const result = {};
-                    for (const line of info.split('\r\n')) {
-                        const idx = line.indexOf(':');
-                        if (idx > 0) {
-                            result[line.slice(0, idx)] = line.slice(idx + 1);
-                        }
-                    }
-                    return result;
-                };
-                const memParsed = parseInfo(memoryInfo);
-                const statsParsed = parseInfo(statsInfo);
-                const usedMemoryBytes = Number.parseInt(memParsed['used_memory'] ?? '0', 10);
-                const connectedClients = Number.parseInt(memParsed['connected_clients'] ?? statsParsed['connected_clients'] ?? '0', 10);
-                const hits = Number.parseInt(statsParsed['keyspace_hits'] ?? '0', 10);
-                const misses = Number.parseInt(statsParsed['keyspace_misses'] ?? '0', 10);
-                const total = hits + misses;
-                const hitRate = total > 0 ? (hits / total) * 100 : 0;
-                return {
-                    redisOk: true,
-                    redisMemoryUsedMb: usedMemoryBytes / (1024 * 1024),
-                    redisConnectedClients: connectedClients,
-                    redisKeysCount: typeof dbSize === 'number' ? dbSize : 0,
-                    redisHitRate: hitRate,
-                };
+                return computeRedisMetrics(parseRedisInfo(memoryInfo), parseRedisInfo(statsInfo), dbSize);
             }
             catch (error) {
                 if (!warnedConnectionError) {
@@ -100,7 +103,7 @@ export function redisCollector() {
                         `Make sure Redis is running and accessible. Check ${bold('config/redis.ts')} for connection details.`,
                     ]);
                 }
-                return defaults;
+                return REDIS_DEFAULTS;
             }
         },
     };

package/dist/src/config/deprecation_migration.d.ts

@@ -0,0 +1,7 @@
+import type { ServerStatsConfig } from '../types.js';
+/**
+ * Detect deprecated config names and log a single grouped warning block.
+ *
+ * Only warns for fields the user **actually set** (not undefined).
+ */
+export declare function logDeprecationWarnings(config: ServerStatsConfig): void;

package/dist/src/config/deprecation_migration.js

@@ -0,0 +1,201 @@
+// ---------------------------------------------------------------------------
+// Deprecation warning logic for renamed config fields
+// ---------------------------------------------------------------------------
+//
+// Extracted from define_config.ts to reduce complexity and file length.
+// ---------------------------------------------------------------------------
+import { bold, dim } from '../utils/logger.js';
+const SIMPLE_DEPRECATIONS = [
+    {
+        key: 'intervalMs',
+        old: 'intervalMs',
+        newName: 'pollInterval',
+        before: (c) => [`intervalMs: ${c.intervalMs}`],
+        after: (c) => [`pollInterval: ${c.intervalMs}`],
+    },
+    {
+        key: 'transport',
+        old: 'transport',
+        newName: 'realtime',
+        before: (c) => [`transport: '${c.transport}'`],
+        after: (c) => [`realtime: ${c.transport === 'transmit'}`],
+    },
+    {
+        key: 'endpoint',
+        old: 'endpoint',
+        newName: 'statsEndpoint',
+        before: (c) => {
+            const d = c.endpoint === false ? 'false' : `'${c.endpoint}'`;
+            return [`endpoint: ${d}`];
+        },
+        after: (c) => {
+            const d = c.endpoint === false ? 'false' : `'${c.endpoint}'`;
+            return [`statsEndpoint: ${d}`];
+        },
+    },
+    {
+        key: 'shouldShow',
+        old: 'shouldShow',
+        newName: 'authorize',
+        before: () => ['shouldShow: (ctx) => ...'],
+        after: () => ['authorize: (ctx) => ...'],
+    },
+    {
+        key: 'channelName',
+        old: 'channelName',
+        newName: 'advanced.channelName',
+        before: (c) => [`channelName: '${c.channelName}'`],
+        after: (c) => [`advanced: { channelName: '${c.channelName}' }`],
+    },
+    {
+        key: 'skipInTest',
+        old: 'skipInTest',
+        newName: 'advanced.skipInTest',
+        before: (c) => [`skipInTest: ${c.skipInTest}`],
+        after: (c) => [`advanced: { skipInTest: ${c.skipInTest} }`],
+    },
+];
+/** Fields to include in the "before" snapshot of devToolbar. */
+const BEFORE_FIELDS = [
+    { key: 'enabled', format: (v) => `enabled: ${v}` },
+    { key: 'dashboard', format: (v) => `dashboard: ${v}` },
+    { key: 'dashboardPath', format: (v) => `dashboardPath: '${v}'` },
+    { key: 'retentionDays', format: (v) => `retentionDays: ${v}` },
+    { key: 'slowQueryThresholdMs', format: (v) => `slowQueryThresholdMs: ${v}` },
+    { key: 'tracing', format: (v) => `tracing: ${v}` },
+    { key: 'persistDebugData', format: (v) => `persistDebugData: ${JSON.stringify(v)}` },
+    { key: 'maxQueries', format: (v) => `maxQueries: ${v}` },
+    { key: 'maxEvents', format: (v) => `maxEvents: ${v}` },
+    { key: 'maxEmails', format: (v) => `maxEmails: ${v}` },
+    { key: 'maxTraces', format: (v) => `maxTraces: ${v}` },
+    { key: 'renderer', format: (v) => `renderer: '${v}'` },
+    { key: 'panes', format: () => `panes: [...]` },
+    { key: 'excludeFromTracing', format: () => `excludeFromTracing: [...]` },
+    { key: 'debugEndpoint', format: (v) => `debugEndpoint: '${v}'` },
+    { key: 'dbPath', format: (v) => `dbPath: '${v}'` },
+];
+function buildBeforeParts(dt) {
+    const parts = ['devToolbar: {'];
+    for (const { key, format } of BEFORE_FIELDS) {
+        if (dt[key] !== undefined) {
+            parts.push(`  ${format(dt[key])},`);
+        }
+    }
+    parts.push('}');
+    return parts;
+}
+const TOOLBAR_AFTER_FIELDS = [
+    { key: 'slowQueryThresholdMs', format: (v) => `  slowQueryThreshold: ${v},` },
+    { key: 'tracing', format: (v) => `  tracing: ${v},` },
+    { key: 'persistDebugData', format: (v) => `  persist: ${JSON.stringify(v)},` },
+    { key: 'panes', format: () => `  panes: [...],` },
+    { key: 'excludeFromTracing', format: () => `  excludeFromTracing: [...],` },
+];
+function buildToolbarAfter(dt) {
+    if (!dt.enabled)
+        return [];
+    const details = TOOLBAR_AFTER_FIELDS.filter(({ key }) => dt[key] !== undefined);
+    if (details.length === 0)
+        return ['toolbar: true'];
+    return ['toolbar: {', ...details.map(({ key, format }) => format(dt[key])), '}'];
+}
+function buildDashboardAfter(dt) {
+    if (!dt.dashboard)
+        return [];
+    const hasDetails = dt.dashboardPath !== undefined || dt.retentionDays !== undefined;
+    if (!hasDetails)
+        return ['dashboard: true'];
+    const parts = ['dashboard: {'];
+    if (dt.dashboardPath !== undefined)
+        parts.push(`  path: '${dt.dashboardPath}',`);
+    if (dt.retentionDays !== undefined)
+        parts.push(`  retentionDays: ${dt.retentionDays},`);
+    parts.push('}');
+    return parts;
+}
+function buildAdvancedAfter(dt) {
+    const parts = [];
+    if (dt.maxQueries !== undefined)
+        parts.push(`  maxQueries: ${dt.maxQueries},`);
+    if (dt.maxEvents !== undefined)
+        parts.push(`  maxEvents: ${dt.maxEvents},`);
+    if (dt.maxEmails !== undefined)
+        parts.push(`  maxEmails: ${dt.maxEmails},`);
+    if (dt.maxTraces !== undefined)
+        parts.push(`  maxTraces: ${dt.maxTraces},`);
+    if (dt.renderer !== undefined)
+        parts.push(`  renderer: '${dt.renderer}',`);
+    if (dt.debugEndpoint !== undefined)
+        parts.push(`  debugEndpoint: '${dt.debugEndpoint}',`);
+    if (dt.dbPath !== undefined)
+        parts.push(`  dbPath: '${dt.dbPath}',`);
+    if (parts.length === 0)
+        return [];
+    return ['advanced: {', ...parts, '}'];
+}
+function buildDevToolbarMigration(dt) {
+    const afterParts = [
+        ...buildToolbarAfter(dt),
+        ...buildDashboardAfter(dt),
+        ...buildAdvancedAfter(dt),
+    ];
+    const advancedPresent = buildAdvancedAfter(dt).length > 0;
+    const newLabel = [
+        dt.enabled !== undefined ? 'toolbar' : '',
+        dt.dashboard ? 'dashboard' : '',
+        advancedPresent ? 'advanced' : '',
+    ]
+        .filter(Boolean)
+        .join(' + ') || 'toolbar + dashboard + advanced';
+    return {
+        old: 'devToolbar',
+        new: newLabel,
+        before: buildBeforeParts(dt),
+        after: afterParts,
+    };
+}
+// ---------------------------------------------------------------------------
+// Main export
+// ---------------------------------------------------------------------------
+/**
+ * Detect deprecated config names and log a single grouped warning block.
+ *
+ * Only warns for fields the user **actually set** (not undefined).
+ */
+export function logDeprecationWarnings(config) {
+    const entries = [];
+    for (const dep of SIMPLE_DEPRECATIONS) {
+        if (config[dep.key] !== undefined) {
+            entries.push({
+                old: dep.old,
+                new: dep.newName,
+                before: dep.before(config),
+                after: dep.after(config),
+            });
+        }
+    }
+    if (config.devToolbar !== undefined) {
+        entries.push(buildDevToolbarMigration(config.devToolbar));
+    }
+    if (entries.length === 0)
+        return;
+    const TAG = '\x1b[36m[ \x1b[1m\uD83D\uDD0D server-stats\x1b[0m\x1b[36m ]\x1b[0m';
+    const lines = [''];
+    lines.push(`${TAG} Some config options have been renamed — here's how to update:`);
+    lines.push('');
+    for (const entry of entries) {
+        lines.push(`    ${dim(entry.old)} ${dim('\u2192')} ${bold(entry.new)}`);
+        lines.push('');
+        for (const line of entry.before) {
+            lines.push(`      ${dim('before:')}  ${dim(line)}`);
+        }
+        for (const line of entry.after) {
+            lines.push(`      ${dim('after:')}   ${line}`);
+        }
+        lines.push('');
+    }
+    lines.push(`    ${dim('No rush — the old names still work. They will be removed in the next major version.')}`);
+    lines.push(`    ${dim('Update')} ${bold('config/server_stats.ts')} ${dim('when you get a chance.')}`);
+    lines.push('');
+    console.log(lines.join('\n'));
+}

package/dist/src/controller/debug_controller.d.ts

@@ -19,8 +19,8 @@ export default class DebugController {
     private cachedAdonisVersion;
     constructor(store: DebugStore, serverConfig?: ResolvedServerStatsConfig | undefined, diagnosticsDeps?: DiagnosticsDeps);
     config({ response }: HttpContext): Promise<void>;
-    /** Lazily create a ConfigInspector from the app reference. */
     private getConfigInspector;
+    private cacheVersions;
     diagnostics({ response }: HttpContext): Promise<void>;
 }
 export {};