@zintrust/core 0.1.42 → 0.1.43

package/packages/queue-monitor/src/driver.d.ts

@@ -0,0 +1,15 @@
+import type { Job, JobsOptions } from 'bullmq';
+import { type RedisConfig } from './connection';
+export type JobPayload<T = unknown> = T;
+export type JobCounts = Record<string, number>;
+export type QueueDriver = {
+    enqueue<T>(name: string, payload: T, options?: JobsOptions): Promise<string>;
+    getJob(queueName: string, jobId: string): Promise<Job | undefined>;
+    getJobCounts(queueName: string): Promise<JobCounts>;
+    getRecentJobs(queueName: string, limit?: number): Promise<Job[]>;
+    retryJob(queueName: string, jobId: string): Promise<boolean>;
+    getQueues(): Promise<string[]>;
+    close(): Promise<void>;
+};
+export declare const createBullMQDriver: (config: RedisConfig) => QueueDriver;
+//# sourceMappingURL=driver.d.ts.map

package/packages/queue-monitor/src/driver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"driver.d.ts","sourceRoot":"","sources":["../../../../packages/queue-monitor/src/driver.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAqB,GAAG,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAC;AAElE,OAAO,EAAyB,KAAK,WAAW,EAAE,MAAM,cAAc,CAAC;AAEvE,MAAM,MAAM,UAAU,CAAC,CAAC,GAAG,OAAO,IAAI,CAAC,CAAC;AAExC,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAE/C,MAAM,MAAM,WAAW,GAAG;IACxB,OAAO,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC7E,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,GAAG,SAAS,CAAC,CAAC;IACnE,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;IACpD,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;IACjE,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC7D,SAAS,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAC/B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB,CAAC;AAgDF,eAAO,MAAM,kBAAkB,GAAI,QAAQ,WAAW,KAAG,WAqFxD,CAAC"}

package/packages/queue-monitor/src/driver.js

@@ -0,0 +1,115 @@
+import { ErrorFactory, getBullMQSafeQueueName } from '../../../src/index.js';
+import { Queue } from 'bullmq';
+import { createRedisConnection } from './connection.js';
+async function enrichJobsWithState(jobs) {
+    await Promise.all(jobs.map(async (job) => {
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            job._state = await job.getState();
+        }
+        catch {
+            // Ignore errors fetching state
+        }
+    }));
+}
+async function discoverQueuesFromRedis(redis, inMemoryQueues) {
+    const found = new Set(Array.from(inMemoryQueues.keys()));
+    try {
+        let cursor = '0';
+        let shouldContinue = true;
+        const prefix = getBullMQSafeQueueName();
+        const scanAsync = (cur) => redis.scan(cur, 'MATCH', prefix + ':*', 'COUNT', '100');
+        while (shouldContinue) {
+            // Redis scan must be sequential as it depends on the cursor from previous result
+            // eslint-disable-next-line no-await-in-loop
+            const result = await scanAsync(cursor);
+            cursor = result[0];
+            const keys = result[1] ?? [];
+            keys.forEach((k) => {
+                const parts = k.split(':');
+                if (parts.length >= 2 && k.startsWith(prefix + ':')) {
+                    const name = parts[1];
+                    if (name)
+                        found.add(name);
+                }
+            });
+            shouldContinue = cursor !== '0';
+        }
+    }
+    catch {
+        // ignore discovery errors
+    }
+    return Array.from(found.values());
+}
+export const createBullMQDriver = (config) => {
+    const queues = new Map();
+    const redis = createRedisConnection(config);
+    const getQueue = (name) => {
+        if (!queues.has(name)) {
+            const prefix = getBullMQSafeQueueName();
+            const connection = createRedisConnection(config);
+            const queue = new Queue(name, { prefix, connection: connection });
+            queues.set(name, queue);
+        }
+        const queue = queues.get(name);
+        if (!queue) {
+            throw ErrorFactory.createTryCatchError(`Queue initialization failed for ${name}`);
+        }
+        return queue;
+    };
+    const enqueue = async (name, payload, options) => {
+        const queue = getQueue(name);
+        const job = await queue.add('default', payload, {
+            removeOnComplete: true,
+            removeOnFail: false,
+            ...options,
+        });
+        if (job.id === undefined || job.id === null) {
+            throw ErrorFactory.createTryCatchError(`Queue job id missing for ${name}`);
+        }
+        return String(job.id);
+    };
+    const getJob = async (queueName, jobId) => {
+        const queue = getQueue(queueName);
+        return (await queue.getJob(jobId)) || undefined;
+    };
+    const getJobCounts = async (queueName) => {
+        const queue = getQueue(queueName);
+        return queue.getJobCounts();
+    };
+    const getRecentJobs = async (queueName, limit = 100) => {
+        const queue = getQueue(queueName);
+        const jobs = await queue.getJobs(['completed', 'failed', 'active', 'waiting', 'delayed', 'paused'], 0, Math.max(0, limit - 1), true);
+        // Fetch state for each job to ensure accurate status detection
+        await enrichJobsWithState(jobs);
+        return jobs;
+    };
+    const retryJob = async (queueName, jobId) => {
+        const job = await getJob(queueName, jobId);
+        if (!job)
+            return false;
+        try {
+            await job.retry();
+            return true;
+        }
+        catch {
+            return false;
+        }
+    };
+    const getQueues = async () => {
+        return discoverQueuesFromRedis(redis, queues);
+    };
+    const close = async () => {
+        const closes = Array.from(queues.values()).map((q) => q.close());
+        await Promise.all(closes);
+    };
+    return Object.freeze({
+        enqueue,
+        getJob,
+        getJobCounts,
+        getRecentJobs,
+        retryJob,
+        getQueues,
+        close,
+    });
+};

package/packages/queue-monitor/src/index.d.ts

@@ -0,0 +1,71 @@
+import { type IRouter } from '../../../src/index.js';
+import { type RedisConfig } from './connection';
+import { type QueueDriver } from './driver';
+import { type Metrics } from './metrics';
+export type { JobPayload } from './driver';
+export { createWorker as createQueueWorker, type QueueWorker } from './worker';
+export type QueueMonitorConfig = {
+    enabled?: boolean;
+    basePath?: string;
+    middleware?: ReadonlyArray<string>;
+    autoRefresh?: boolean;
+    refreshIntervalMs?: number;
+    redis?: RedisConfig;
+};
+export type QueueCounts = {
+    waiting: number;
+    active: number;
+    completed: number;
+    failed: number;
+    delayed: number;
+    paused: number;
+};
+export type QueueMonitorSnapshot = {
+    status: 'ok';
+    startedAt: string;
+    queues: Array<{
+        name: string;
+        counts: QueueCounts;
+    }>;
+};
+export type LockSummary = {
+    key: string;
+    ttl?: number;
+    expires?: string;
+};
+export type LockMetrics = {
+    active: number;
+    attempts: number;
+    acquired: number;
+    collisions: number;
+    collisionRate: number;
+};
+export type LockHistogramBucket = {
+    label: string;
+    count: number;
+};
+export type LockAnalytics = {
+    locks: LockSummary[];
+    metrics: LockMetrics;
+    histogram: LockHistogramBucket[];
+};
+export type QueueMonitorApi = {
+    registerRoutes: (router: IRouter) => void;
+    getSnapshot: () => Promise<QueueMonitorSnapshot>;
+    getLocks: (pattern?: string) => Promise<LockAnalytics>;
+    driver: QueueDriver;
+    metrics: Metrics;
+    close: () => Promise<void>;
+};
+export declare const QueueMonitor: Readonly<{
+    create(config: QueueMonitorConfig): QueueMonitorApi;
+}>;
+export default QueueMonitor;
+export { createBullMQDriver } from './driver';
+/**
+ * Package version and build metadata
+ * Available at runtime for debugging and health checks
+ */
+export declare const _ZINTRUST_QUEUE_MONITOR_VERSION = "0.1.0";
+export declare const _ZINTRUST_QUEUE_MONITOR_BUILD_DATE = "__BUILD_DATE__";
+//# sourceMappingURL=index.d.ts.map

package/packages/queue-monitor/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../packages/queue-monitor/src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAOL,KAAK,OAAO,EAEb,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAyB,KAAK,WAAW,EAAE,MAAM,cAAc,CAAC;AAEvE,OAAO,EAAsB,KAAK,WAAW,EAAE,MAAM,UAAU,CAAC;AAChE,OAAO,EAAiB,KAAK,OAAO,EAAE,MAAM,WAAW,CAAC;AAGxD,YAAY,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAC3C,OAAO,EAAE,YAAY,IAAI,iBAAiB,EAAE,KAAK,WAAW,EAAE,MAAM,UAAU,CAAC;AAE/E,MAAM,MAAM,kBAAkB,GAAG;IAC/B,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACnC,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,KAAK,CAAC,EAAE,WAAW,CAAC;CACrB,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,MAAM,EAAE,IAAI,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,KAAK,CAAC;QACZ,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,EAAE,WAAW,CAAC;KACrB,CAAC,CAAC;CACJ,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG;IACxB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC1B,KAAK,EAAE,WAAW,EAAE,CAAC;IACrB,OAAO,EAAE,WAAW,CAAC;IACrB,SAAS,EAAE,mBAAmB,EAAE,CAAC;CAClC,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B,cAAc,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;IAC1C,WAAW,EAAE,MAAM,OAAO,CAAC,oBAAoB,CAAC,CAAC;IACjD,QAAQ,EAAE,CAAC,OAAO,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,aAAa,CAAC,CAAC;IACvD,MAAM,EAAE,WAAW,CAAC;IACpB,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5B,CAAC;AA+aF,eAAO,MAAM,YAAY;mBACR,kBAAkB,GAAG,eAAe;EAmCnD,CAAC;AAEH,eAAe,YAAY,CAAC;AAE5B,OAAO,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAE9C;;;GAGG;AACH,eAAO,MAAM,+BAA+B,UAAU,CAAC;AACvD,eAAO,MAAM,kCAAkC,mBAAmB,CAAC"}

package/packages/queue-monitor/src/index.js

@@ -0,0 +1,296 @@
+import { Logger, queueConfig, resolveLockPrefix, Router, } from '../../../src/index.js';
+import { createRedisConnection } from './connection.js';
+import { getDashboardHtml } from './dashboard-ui.js';
+import { createBullMQDriver } from './driver.js';
+import { createMetrics } from './metrics.js';
+import { getRecentJobsForQueue, QueueMonitoringStream } from './QueueMonitoringService.js';
+export { createWorker as createQueueWorker } from './worker.js';
+const DEFAULTS = {
+    enabled: true,
+    basePath: '/queue-monitor',
+    middleware: [],
+    autoRefresh: true,
+    refreshIntervalMs: 5000,
+};
+function extractQueueParam(req) {
+    if (typeof req.getParam === 'function') {
+        return (req.getParam('queue') || (req && req.params !== undefined ? req?.params['queue'] : undefined));
+    }
+    return req && req.params !== undefined ? req?.params['queue'] : undefined;
+}
+function fieldError(key, message) {
+    return { error: `[${key}] ${message}` };
+}
+const METRICS_KEYS = {
+    attempts: 'metrics:attempts',
+    acquired: 'metrics:acquired',
+    collisions: 'metrics:collisions',
+};
+const HISTOGRAM_BUCKETS = [
+    { label: '<30s', max: 30_000 },
+    { label: '30s-2m', max: 120_000 },
+    { label: '2-10m', max: 600_000 },
+    { label: '10-60m', max: 3_600_000 },
+    { label: '>60m', min: 3_600_000 },
+];
+const MAX_LOCK_KEYS = 10_000;
+// Helper function to scan lock keys with pagination
+const scanLockKeys = async (client, searchPattern, maxKeys) => {
+    const keys = [];
+    let cursor = '0';
+    do {
+        // Redis scan must be sequential
+        // eslint-disable-next-line no-await-in-loop
+        const [nextCursor, batch] = await client.scan(cursor, 'MATCH', searchPattern, 'COUNT', '200');
+        cursor = nextCursor;
+        keys.push(...batch);
+        if (keys.length >= maxKeys) {
+            Logger.warn('Lock scan limit reached', {
+                pattern: searchPattern,
+                keysFound: keys.length,
+            });
+            break;
+        }
+    } while (cursor !== '0');
+    return keys;
+};
+// Helper function to get TTL statuses for keys
+const getLockStatuses = async (client, keys) => {
+    return Promise.all(keys.map((key) => client.pttl(key)));
+};
+// Helper function to build lock objects from keys and statuses
+const buildLockObjects = (keys, statuses, prefixLock) => {
+    return keys.map((key, index) => {
+        const ttl = statuses[index];
+        const exists = typeof ttl === 'number' && ttl > 0;
+        return {
+            key: key.replace(prefixLock, ''),
+            ttl: exists ? ttl : undefined,
+            expires: exists ? new Date(Date.now() + ttl).toISOString() : undefined,
+        };
+    });
+};
+// Helper function to calculate lock metrics
+const calculateLockMetrics = async (client, prefixLock) => {
+    const metricsKeys = [
+        `${prefixLock}${METRICS_KEYS.attempts}`,
+        `${prefixLock}${METRICS_KEYS.acquired}`,
+        `${prefixLock}${METRICS_KEYS.collisions}`,
+    ];
+    const [attemptsRaw, acquiredRaw, collisionsRaw] = await client.mget(...metricsKeys);
+    const parseMetric = (value) => Number.isFinite(Number(value)) ? Number(value) : 0;
+    const attempts = parseMetric(attemptsRaw);
+    const acquired = parseMetric(acquiredRaw);
+    const collisions = parseMetric(collisionsRaw);
+    const collisionRate = attempts > 0 ? collisions / attempts : 0;
+    return { attempts, acquired, collisions, collisionRate };
+};
+// Helper function to build histogram from locks
+const buildLockHistogram = (locks) => {
+    const histogram = HISTOGRAM_BUCKETS.map((bucket) => ({
+        label: bucket.label,
+        count: 0,
+    }));
+    locks.forEach((lock) => {
+        if (typeof lock.ttl !== 'number')
+            return;
+        const ttl = lock.ttl;
+        const idx = HISTOGRAM_BUCKETS.findIndex((bucket) => {
+            if (typeof bucket.min === 'number')
+                return ttl >= bucket.min;
+            if (typeof bucket.max === 'number')
+                return ttl < bucket.max;
+            return false;
+        });
+        if (idx >= 0)
+            histogram[idx].count += 1;
+    });
+    return histogram;
+};
+function createGetLocks(redisConfig) {
+    return async (pattern = '*') => {
+        const client = createRedisConnection(redisConfig);
+        const prefix_lock = resolveLockPrefix();
+        const searchPattern = `${prefix_lock}${pattern}`;
+        try {
+            // Scan for lock keys
+            const keys = await scanLockKeys(client, searchPattern, MAX_LOCK_KEYS);
+            // Get TTL statuses
+            const statuses = await getLockStatuses(client, keys);
+            // Build lock objects
+            const locks = buildLockObjects(keys, statuses, prefix_lock);
+            // Calculate metrics
+            const metrics = await calculateLockMetrics(client, prefix_lock);
+            // Build histogram
+            const histogram = buildLockHistogram(locks);
+            return {
+                locks,
+                metrics: {
+                    active: locks.length,
+                    ...metrics,
+                },
+                histogram,
+            };
+        }
+        finally {
+            if (typeof client.quit === 'function') {
+                await client.quit();
+            }
+            else if (typeof client.disconnect === 'function') {
+                client.disconnect();
+            }
+        }
+    };
+}
+async function handleJobsEndpoint(req, res, metrics, driver) {
+    const queueName = extractQueueParam(req);
+    if (!queueName) {
+        res.status(400).json(fieldError('queue_name', 'Queue name must be provided'));
+        return;
+    }
+    const jobs = await getRecentJobsForQueue(queueName, metrics, driver);
+    res.json(jobs);
+}
+async function handleRetryEndpoint(req, res, driver) {
+    const queueName = extractQueueParam(req);
+    const jobId = typeof req.getParam === 'function' ? req.getParam?.('jobId') : req.params?.['jobId'];
+    if (!queueName || !jobId) {
+        res.status(400).json(fieldError('queue_name,job_id', 'Queue name and job ID must be provided'));
+        return;
+    }
+    const success = await driver.retryJob(queueName, jobId);
+    if (success) {
+        res.json({ ok: true, message: `Job ${jobId} queued for retry` });
+    }
+    else {
+        res.status(404).json({ error: 'Job not found or cannot be retried' });
+    }
+}
+function buildSettings(config) {
+    return {
+        enabled: config.enabled ?? DEFAULTS.enabled,
+        basePath: config.basePath ?? DEFAULTS.basePath,
+        middleware: config.middleware ?? DEFAULTS.middleware,
+        autoRefresh: config.autoRefresh ?? DEFAULTS.autoRefresh,
+        refreshIntervalMs: typeof config.refreshIntervalMs === 'number' && Number.isFinite(config.refreshIntervalMs)
+            ? Math.max(1000, Math.floor(config.refreshIntervalMs))
+            : DEFAULTS.refreshIntervalMs,
+    };
+}
+function createGetSnapshot(driver, startedAt) {
+    return async () => {
+        const queues = await driver.getQueues();
+        const stats = await Promise.all(queues.map(async (name) => {
+            const counts = await driver.getJobCounts(name);
+            return { name, counts: counts };
+        }));
+        return {
+            status: 'ok',
+            startedAt,
+            queues: stats,
+        };
+    };
+}
+function createRegisterRoutes(settings, metrics, driver, getSnapshot, getLocks) {
+    return (router) => {
+        if (!settings.enabled)
+            return;
+        const routeOptions = settings.middleware.length > 0
+            ? { middleware: settings.middleware }
+            : { ...queueConfig.monitor };
+        registerDashboardRoutes(router, settings, routeOptions);
+        registerApiRoutes(router, settings, routeOptions, metrics, driver, getSnapshot, getLocks);
+    };
+}
+function registerDashboardRoutes(router, settings, routeOptions) {
+    const renderDashboard = (_req, res) => {
+        res.html(getDashboardHtml({
+            basePath: settings.basePath,
+            autoRefresh: settings.autoRefresh,
+            refreshIntervalMs: settings.refreshIntervalMs,
+        }));
+    };
+    // Dashboard HTML
+    Router.get(router, settings.basePath, renderDashboard, routeOptions);
+    Router.get(router, `${settings.basePath}/`, renderDashboard, routeOptions);
+}
+function registerApiRoutes(router, settings, routeOptions, metrics, driver, getSnapshot, getLocks) {
+    registerSnapshotApi(router, settings, routeOptions, getSnapshot);
+    registerJobsApi(router, settings, routeOptions, metrics, driver);
+    registerLocksApi(router, settings, routeOptions, getLocks);
+    registerRetryApi(router, settings, routeOptions, driver);
+    registerEventsApi(router, settings, routeOptions, getSnapshot, getLocks, metrics, driver);
+}
+function registerSnapshotApi(router, settings, routeOptions, getSnapshot) {
+    Router.get(router, `${settings.basePath}/api/snapshot`, async (_req, res) => {
+        const data = await getSnapshot();
+        res.json(data);
+    }, routeOptions);
+}
+function registerJobsApi(router, settings, routeOptions, metrics, driver) {
+    Router.get(router, `${settings.basePath}/api/jobs/:queue`, async (req, res) => {
+        await handleJobsEndpoint(req, res, metrics, driver);
+    }, routeOptions);
+}
+function registerLocksApi(router, settings, routeOptions, getLocks) {
+    Router.get(router, `${settings.basePath}/api/locks`, async (req, res) => {
+        const query = typeof req.getQuery === 'function'
+            ? req.getQuery()
+            : (req.query ?? {});
+        const pattern = query['pattern'] ?? '*';
+        const locks = await getLocks(pattern);
+        res.json(locks);
+    }, routeOptions);
+}
+function registerRetryApi(router, settings, routeOptions, driver) {
+    Router.post(router, `${settings.basePath}/api/retry/:queue/:jobId`, async (req, res) => {
+        await handleRetryEndpoint(req, res, driver);
+    }, routeOptions);
+}
+function registerEventsApi(router, settings, routeOptions, getSnapshot, getLocks, metrics, driver) {
+    Router.get(router, `${settings.basePath}/api/events`, async (req, res) => {
+        QueueMonitoringStream(res, req, getSnapshot, getLocks, metrics, driver, settings);
+    }, routeOptions);
+}
+export const QueueMonitor = Object.freeze({
+    create(config) {
+        const settings = buildSettings(config);
+        let redisConfig;
+        if (config?.redis) {
+            redisConfig = config?.redis;
+        }
+        else {
+            redisConfig = {
+                host: queueConfig.drivers.redis.host,
+                port: queueConfig.drivers.redis.port,
+                password: queueConfig.drivers.redis.password ?? '',
+                db: queueConfig.drivers.redis.database,
+            };
+        }
+        const driver = createBullMQDriver(redisConfig);
+        const metrics = createMetrics(redisConfig);
+        const startedAt = new Date().toISOString();
+        const getSnapshot = createGetSnapshot(driver, startedAt);
+        const getLocks = createGetLocks(redisConfig);
+        const registerRoutes = createRegisterRoutes(settings, metrics, driver, getSnapshot, getLocks);
+        const close = async () => {
+            await Promise.all([driver.close(), metrics.close()]);
+        };
+        return Object.freeze({
+            registerRoutes,
+            getSnapshot,
+            getLocks,
+            driver,
+            metrics,
+            close,
+        });
+    },
+});
+export default QueueMonitor;
+export { createBullMQDriver } from './driver.js';
+/**
+ * Package version and build metadata
+ * Available at runtime for debugging and health checks
+ */
+export const _ZINTRUST_QUEUE_MONITOR_VERSION = '0.1.0';
+export const _ZINTRUST_QUEUE_MONITOR_BUILD_DATE = '__BUILD_DATE__';

package/packages/queue-monitor/src/metrics.d.ts

@@ -0,0 +1,27 @@
+import { type Job } from 'bullmq';
+import { type RedisConfig } from './connection';
+export type JobStatus = 'completed' | 'failed';
+export type JobSummary = {
+    id: string | undefined;
+    name: string;
+    data: unknown;
+    attempts: number;
+    status?: string;
+    failedReason?: string;
+    timestamp: number;
+    processedOn?: number;
+    finishedOn?: number;
+};
+export type Metrics = {
+    recordJob(queue: string, status: JobStatus, job: Job, error?: Error): Promise<void>;
+    getStats(queue: string, minutes?: number): Promise<Array<{
+        time: string;
+        completed: number;
+        failed: number;
+    }>>;
+    getRecentJobs(queue: string): Promise<JobSummary[]>;
+    getFailedJobs(queue: string): Promise<JobSummary[]>;
+    close: () => Promise<void>;
+};
+export declare const createMetrics: (config: RedisConfig) => Metrics;
+//# sourceMappingURL=metrics.d.ts.map

package/packages/queue-monitor/src/metrics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.d.ts","sourceRoot":"","sources":["../../../../packages/queue-monitor/src/metrics.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,GAAG,EAAE,MAAM,QAAQ,CAAC;AAClC,OAAO,EAAyB,KAAK,WAAW,EAAE,MAAM,cAAc,CAAC;AAEvE,MAAM,MAAM,SAAS,GAAG,WAAW,GAAG,QAAQ,CAAC;AAE/C,MAAM,MAAM,UAAU,GAAG;IACvB,EAAE,EAAE,MAAM,GAAG,SAAS,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,OAAO,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,MAAM,MAAM,OAAO,GAAG;IACpB,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,GAAG,EAAE,GAAG,EAAE,KAAK,CAAC,EAAE,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpF,QAAQ,CACN,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC,CAAC;IACvE,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAAC;IACpD,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAAC;IACpD,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5B,CAAC;AAyFF,eAAO,MAAM,aAAa,GAAI,QAAQ,WAAW,KAAG,OA0BnD,CAAC"}

package/packages/queue-monitor/src/metrics.js

@@ -0,0 +1,92 @@
+import { RedisKeys } from '../../../src/index.js';
+import { createRedisConnection } from './connection.js';
+/**
+ * Creates a queue monitoring key using singleton RedisKeys
+ * @param type - Type of monitoring key (stats, recent, failed)
+ * @param parts - Additional key parts
+ * @returns Prefixed Redis key for queue monitoring
+ */
+const getKey = (type, ...parts) => {
+    const suffix = parts.length > 0 ? `:${parts.join(':')}` : '';
+    return `${RedisKeys.queuePrefix}monitor:${type}${suffix}`;
+};
+const recordJobImpl = async (redis, queue, status, job, error) => {
+    const minute = Math.floor(Date.now() / 60000);
+    const dateKey = getKey('stats', queue, minute.toString());
+    await redis.hincrby(dateKey, status, 1);
+    await redis.expire(dateKey, 86400);
+    const jobData = {
+        id: job.id,
+        name: job.name,
+        data: job.data,
+        attempts: job.attemptsMade,
+        failedReason: job.failedReason || error?.message,
+        timestamp: Date.now(),
+        processedOn: job.processedOn,
+        finishedOn: job.finishedOn,
+    };
+    const listKey = getKey('recent', queue);
+    await redis.lpush(listKey, JSON.stringify(jobData));
+    await redis.ltrim(listKey, 0, 99);
+    if (status === 'failed') {
+        const failedKey = getKey('failed', queue);
+        await redis.lpush(failedKey, JSON.stringify(jobData));
+        await redis.ltrim(failedKey, 0, 99);
+    }
+};
+const getStatsImpl = async (redis, queue, minutes) => {
+    const currentMinute = Math.floor(Date.now() / 60000);
+    const keys = [];
+    const timestamps = [];
+    for (let i = 0; i < minutes; i++) {
+        const m = currentMinute - i;
+        timestamps.push(m);
+        keys.push(getKey('stats', queue, m.toString()));
+    }
+    if (keys.length === 0)
+        return [];
+    const pipeline = redis.pipeline();
+    keys.forEach((k) => pipeline.hgetall(k));
+    const results = await pipeline.exec();
+    if (!results)
+        return [];
+    return results
+        .map((result, i) => {
+        const [err, data] = result;
+        if (err || !data)
+            return {
+                time: new Date(timestamps[i] * 60000).toISOString(),
+                completed: 0,
+                failed: 0,
+            };
+        return {
+            time: new Date(timestamps[i] * 60000).toISOString(),
+            completed: Number.parseInt(data['completed'] || '0', 10),
+            failed: Number.parseInt(data['failed'] || '0', 10),
+        };
+    })
+        .reverse();
+};
+export const createMetrics = (config) => {
+    const redis = createRedisConnection(config);
+    return Object.freeze({
+        recordJob: (queue, status, job, error) => recordJobImpl(redis, queue, status, job, error),
+        getStats: (queue, minutes = 60) => getStatsImpl(redis, queue, minutes),
+        getRecentJobs: async (queue) => {
+            const list = await redis.lrange(getKey('recent', queue), 0, -1);
+            return list.map((item) => JSON.parse(item));
+        },
+        getFailedJobs: async (queue) => {
+            const list = await redis.lrange(getKey('failed', queue), 0, -1);
+            return list.map((item) => JSON.parse(item));
+        },
+        close: async () => {
+            if (typeof redis.quit === 'function') {
+                await redis.quit();
+            }
+            else if (typeof redis.disconnect === 'function') {
+                redis.disconnect();
+            }
+        },
+    });
+};

package/packages/queue-monitor/src/worker.d.ts

@@ -0,0 +1,8 @@
+import { type Processor } from 'bullmq';
+import { type RedisConfig } from './connection';
+import type { Metrics } from './metrics';
+export type QueueWorker = {
+    close: () => Promise<void>;
+};
+export declare const createWorker: (queueName: string, processor: Processor, redisConfig: RedisConfig, metrics: Metrics) => QueueWorker;
+//# sourceMappingURL=worker.d.ts.map

package/packages/queue-monitor/src/worker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker.d.ts","sourceRoot":"","sources":["../../../../packages/queue-monitor/src/worker.ts"],"names":[],"mappings":"AACA,OAAO,EAAoB,KAAK,SAAS,EAAE,MAAM,QAAQ,CAAC;AAC1D,OAAO,EAAyB,KAAK,WAAW,EAAE,MAAM,cAAc,CAAC;AACvE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,MAAM,MAAM,WAAW,GAAG;IACxB,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5B,CAAC;AAEF,eAAO,MAAM,YAAY,GACvB,WAAW,MAAM,EACjB,WAAW,SAAS,EACpB,aAAa,WAAW,EACxB,SAAS,OAAO,KACf,WAoCF,CAAC"}

package/packages/queue-monitor/src/worker.js

@@ -0,0 +1,35 @@
+import { getBullMQSafeQueueName } from '../../../src/index.js';
+import { Worker } from 'bullmq';
+import { createRedisConnection } from './connection.js';
+export const createWorker = (queueName, processor, redisConfig, metrics) => {
+    const connection = createRedisConnection(redisConfig);
+    const prefix = getBullMQSafeQueueName();
+    const worker = new Worker(queueName, processor, {
+        connection: connection,
+        prefix,
+    });
+    const onCompleted = async (job) => {
+        await metrics.recordJob(queueName, 'completed', job);
+    };
+    const onFailed = async (job, err) => {
+        if (job) {
+            await metrics.recordJob(queueName, 'failed', job, err);
+        }
+    };
+    worker.on('completed', onCompleted);
+    worker.on('failed', onFailed);
+    const close = async () => {
+        worker.off('completed', onCompleted);
+        worker.off('failed', onFailed);
+        await worker.close();
+        if (typeof connection.quit === 'function') {
+            await connection.quit();
+        }
+        else if (typeof connection.disconnect === 'function') {
+            connection.disconnect();
+        }
+    };
+    return Object.freeze({
+        close,
+    });
+};