@zintrust/workers 0.4.50 → 0.4.61

package/dist/WorkerFactory.js

@@ -23,6 +23,7 @@ import { WorkerMetrics } from './WorkerMetrics.js';
 import { WorkerRegistry } from './WorkerRegistry.js';
 import { WorkerVersioning } from './WorkerVersioning.js';
 import { keyPrefix } from './config/workerConfig.js';
+import { recordQueueMonitorJob } from './queueMonitorHistory.js';
 import { DbWorkerStore, InMemoryWorkerStore, RedisWorkerStore, } from './storage/WorkerStore.js';
 const path = NodeSingletons.path;
 const isNodeRuntime = () => typeof process !== 'undefined' && Boolean(process.versions?.node);
@@ -1905,10 +1906,15 @@ const initializeDatacenter = (config) => {
         },
     });
 };
-const setupWorkerEventListeners = (worker, workerName, workerVersion, features) => {
+const setupWorkerEventListeners = (worker, workerName, queueName, workerVersion, features) => {
     worker.on('completed', (job) => {
         try {
             Logger.debug(`Job completed: ${workerName}`, { jobId: job.id });
+            void recordQueueMonitorJob({
+                queueName,
+                status: 'completed',
+                job,
+            });
             if (features?.observability === true) {
                 Observability.incrementCounter('worker.jobs.completed', 1, {
                     worker: workerName,
@@ -1924,6 +1930,14 @@ const setupWorkerEventListeners = (worker, workerName, workerVersion, features)
     worker.on('failed', (job, error) => {
         try {
             Logger.error(`Job failed: ${workerName}`, { error, jobId: job?.id }, 'workers');
+            if (job) {
+                void recordQueueMonitorJob({
+                    queueName,
+                    status: 'failed',
+                    job,
+                    error,
+                });
+            }
             if (features?.observability === true) {
                 Observability.incrementCounter('worker.jobs.failed', 1, {
                     worker: workerName,
@@ -2087,7 +2101,7 @@ export const WorkerFactory = Object.freeze({
             // Create BullMQ worker
             const resolvedOptions = resolveWorkerOptions(config, autoStart);
             const worker = new Worker(queueName, enhancedProcessor, resolvedOptions);
-            setupWorkerEventListeners(worker, name, workerVersion, features);
+            setupWorkerEventListeners(worker, name, queueName, workerVersion, features);
             // Update status to "starting"
             await store.update(name, {
                 status: WorkerCreationStatus.STARTING,

package/dist/build-manifest.json

@@ -1,14 +1,14 @@
 {
   "name": "@zintrust/workers",
-  "version": "0.4.43",
-  "buildDate": "2026-04-01T18:18:47.850Z",
+  "version": "0.4.60",
+  "buildDate": "2026-04-05T07:03:43.939Z",
   "buildEnvironment": {
     "node": "v22.22.1",
     "platform": "darwin",
     "arch": "arm64"
   },
   "git": {
-    "commit": "57e4d1b5",
+    "commit": "be058c1d",
     "branch": "release"
   },
   "package": {
@@ -178,8 +178,8 @@
       "sha256": "3869f960c87260588e40941ff91bffcfa0757be7a04815fd28b57dd4840c51df"
     },
     "WorkerFactory.js": {
-      "size": 102863,
-      "sha256": "1024756e603ca67461a955723dc004de9395267e50c7f59c9f8f0c13b2f0f7d8"
+      "size": 105839,
+      "sha256": "b26135593d6e3849f5540d74d097082d8186b50c72a456722f83d624141c42c8"
     },
     "WorkerInit.d.ts": {
       "size": 3284,
@@ -231,7 +231,7 @@
     },
     "build-manifest.json": {
       "size": 19594,
-      "sha256": "ddb01f1c22cddfc1201631a2774726d0134407e811359eed517bf36b508d829c"
+      "sha256": "7402721e5f5a98fb988fa78f5ee49b6e82f2f3fab1c3cfb8ca2bf8116012169f"
     },
     "config/workerConfig.d.ts": {
       "size": 132,
@@ -246,8 +246,8 @@
       "sha256": "dacd49f6c112eba439bdd9bb457eea90daedbf32efc381cd3189ce562fa5b0a8"
     },
     "createQueueWorker.js": {
-      "size": 14702,
-      "sha256": "69bf07658c185ad5b4bafd064bfc64ea257c769809b6d4811a274020b4a5a8e7"
+      "size": 15594,
+      "sha256": "0710f2fb6936a326cdbe6fa6a2b8acfb60f7c6b27acb2aed0b98bf2402fc67f4"
     },
     "dashboard/index.d.ts": {
       "size": 109,
@@ -270,8 +270,8 @@
       "sha256": "8e0e04329e1119d8ae835dd4458efead084293bcc2c263c09dd5a19d467e5ca4"
     },
     "dashboard/workers-api.js": {
-      "size": 28207,
-      "sha256": "ae1ff0e962b1f64e6d200a35c3b8b1de968341d8df6283625a3efce50a23826c"
+      "size": 28568,
+      "sha256": "c28f0d4b8134337a2cc71f1ce2f1d6195f44ccd9bb0b8fa26a4edaed88ee4fc0"
     },
     "helper/index.d.ts": {
       "size": 159,
@@ -415,7 +415,15 @@
     },
     "index.js": {
       "size": 2337,
-      "sha256": "698bb78d6613e898a60f390ca1766071324e3ec3a726184c35f174ea64cadb99"
+      "sha256": "85a789d0f2ed71dde649f59658827ff16eaf2c1bc77df99b2297c7eb7e340108"
+    },
+    "queueMonitorHistory.d.ts": {
+      "size": 433,
+      "sha256": "1ba25cf47b0cad83e92c7b6481d12de974b921d0e01fc4cf17fc833acdf8b8c8"
+    },
+    "queueMonitorHistory.js": {
+      "size": 2194,
+      "sha256": "03d406adc046e18c3526837a654fae93b112fb6010ddc1163b129d10e934c4d4"
     },
     "register.d.ts": {
       "size": 256,

package/dist/createQueueWorker.js

@@ -1,5 +1,6 @@
 import * as Core from '@zintrust/core';
 import { Env, Logger, Queue } from '@zintrust/core';
+import { recordQueueMonitorJob } from './queueMonitorHistory.js';
 const TypedQueue = Queue;
 const RETRY_BASE_DELAY_MS = 1000;
 const RETRY_MAX_DELAY_MS = 30000;
@@ -168,6 +169,18 @@ const checkAndRequeueIfNotDue = async (options, queueName, driverName, message,
 };
 const onProcessSuccess = async (input) => {
     await TypedQueue.ack(input.queueName, input.message.id, input.driverName);
+    await recordQueueMonitorJob({
+        queueName: input.queueName,
+        status: 'completed',
+        job: {
+            id: input.message.id,
+            name: `${input.queueName}-job`,
+            data: input.message.payload,
+            attemptsMade: getAttemptsFromMessage(input.message),
+            processedOn: input.startedAtMs,
+            finishedOn: Date.now(),
+        },
+    });
     if (typeof input.trackerApi.completed === 'function') {
         await input.trackerApi.completed({
             queueName: input.queueName,
@@ -217,6 +230,20 @@ const onProcessFailure = async (input) => {
         });
     }
     await TypedQueue.ack(input.queueName, input.message.id, input.driverName);
+    await recordQueueMonitorJob({
+        queueName: input.queueName,
+        status: 'failed',
+        job: {
+            id: input.message.id,
+            name: `${input.queueName}-job`,
+            data: input.message.payload,
+            attemptsMade: nextAttempts,
+            failedReason: failure.message,
+            processedOn: Date.now(),
+            finishedOn: Date.now(),
+        },
+        error: failure,
+    });
     await removeHeartbeatIfSupported(input.queueName, input.message.id);
     if (typeof input.trackerApi.failed === 'function') {
         await input.trackerApi.failed({

package/dist/queueMonitorHistory.d.ts

@@ -0,0 +1,17 @@
+type QueueMonitorStatus = 'completed' | 'failed';
+type QueueMonitorJobLike = {
+    id?: string;
+    name?: string;
+    data?: unknown;
+    attemptsMade?: number;
+    failedReason?: string;
+    processedOn?: number;
+    finishedOn?: number;
+};
+export declare const recordQueueMonitorJob: (input: {
+    queueName: string;
+    status: QueueMonitorStatus;
+    job: QueueMonitorJobLike;
+    error?: Error;
+}) => Promise<void>;
+export {};

package/dist/queueMonitorHistory.js

@@ -0,0 +1,62 @@
+import { isNonEmptyString, isObject, Logger, queueConfig } from '@zintrust/core';
+let queueMonitorMetricsPromise = null;
+const toFiniteInteger = (value, fallback) => {
+    if (typeof value === 'number' && Number.isFinite(value)) {
+        return Math.floor(value);
+    }
+    if (typeof value === 'string' && value.trim() !== '') {
+        const parsed = Number(value);
+        if (Number.isFinite(parsed)) {
+            return Math.floor(parsed);
+        }
+    }
+    return fallback;
+};
+const resolveQueueMonitorRedisConfig = () => {
+    const redisConfig = queueConfig?.drivers?.redis;
+    if (!isObject(redisConfig) || redisConfig['driver'] !== 'redis') {
+        return null;
+    }
+    const host = isNonEmptyString(redisConfig['host']) ? redisConfig['host'].trim() : '127.0.0.1';
+    const port = toFiniteInteger(redisConfig['port'], 6379);
+    const db = toFiniteInteger(redisConfig['database'], 0);
+    const password = isNonEmptyString(redisConfig['password']) ? redisConfig['password'] : undefined;
+    return { host, port, password, db };
+};
+const loadQueueMonitorMetrics = async () => {
+    const redisConfig = resolveQueueMonitorRedisConfig();
+    if (redisConfig === null) {
+        return null;
+    }
+    try {
+        const module = (await import('@zintrust/queue-monitor'));
+        if (typeof module.createMetrics !== 'function') {
+            return null;
+        }
+        return module.createMetrics(redisConfig);
+    }
+    catch (error) {
+        Logger.debug('Queue monitor metrics are unavailable for worker history recording', error);
+        return null;
+    }
+};
+const getQueueMonitorMetrics = async () => {
+    queueMonitorMetricsPromise ??= loadQueueMonitorMetrics();
+    return queueMonitorMetricsPromise;
+};
+export const recordQueueMonitorJob = async (input) => {
+    const metrics = await getQueueMonitorMetrics();
+    if (metrics === null) {
+        return;
+    }
+    try {
+        await metrics.recordJob(input.queueName, input.status, input.job, input.error);
+    }
+    catch (error) {
+        Logger.debug('Queue monitor history write failed', {
+            queueName: input.queueName,
+            status: input.status,
+            error,
+        });
+    }
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zintrust/workers",
-  "version": "0.4.50",
+  "version": "0.4.61",
   "description": "Worker orchestration and background job management for ZinTrust.",
   "private": false,
   "type": "module",

package/src/WorkerFactory.ts

@@ -47,6 +47,7 @@ import { WorkerMetrics } from './WorkerMetrics';
 import { WorkerRegistry, type WorkerInstance as RegistryWorkerInstance } from './WorkerRegistry';
 import { WorkerVersioning } from './WorkerVersioning';
 import { keyPrefix } from './config/workerConfig';
+import { recordQueueMonitorJob } from './queueMonitorHistory';
 import {
   DbWorkerStore,
   InMemoryWorkerStore,
@@ -2685,12 +2686,18 @@ const initializeDatacenter = (config: WorkerFactoryConfig): void => {
 const setupWorkerEventListeners = (
   worker: Worker,
   workerName: string,
+  queueName: string,
   workerVersion: string,
   features?: WorkerFactoryConfig['features']
 ): void => {
   worker.on('completed', (job: Job) => {
     try {
       Logger.debug(`Job completed: ${workerName}`, { jobId: job.id });
+      void recordQueueMonitorJob({
+        queueName,
+        status: 'completed',
+        job,
+      });
 
       if (features?.observability === true) {
         Observability.incrementCounter('worker.jobs.completed', 1, {
@@ -2707,6 +2714,14 @@ const setupWorkerEventListeners = (
   worker.on('failed', (job: Job | undefined, error: Error) => {
     try {
       Logger.error(`Job failed: ${workerName}`, { error, jobId: job?.id }, 'workers');
+      if (job) {
+        void recordQueueMonitorJob({
+          queueName,
+          status: 'failed',
+          job,
+          error,
+        });
+      }
 
       if (features?.observability === true) {
         Observability.incrementCounter('worker.jobs.failed', 1, {
@@ -2900,7 +2915,7 @@ export const WorkerFactory = Object.freeze({
       const resolvedOptions = resolveWorkerOptions(config, autoStart);
       const worker = new Worker(queueName, enhancedProcessor, resolvedOptions);
 
-      setupWorkerEventListeners(worker, name, workerVersion, features);
+      setupWorkerEventListeners(worker, name, queueName, workerVersion, features);
 
       // Update status to "starting"
       await store.update(name, {

package/src/createQueueWorker.ts

@@ -1,6 +1,7 @@
 import type { BullMQPayload, QueueMessage } from '@zintrust/core';
 import * as Core from '@zintrust/core';
 import { Env, Logger, Queue } from '@zintrust/core';
+import { recordQueueMonitorJob } from './queueMonitorHistory';
 
 type QueueApi = Readonly<{
   enqueue: (queue: string, payload: BullMQPayload, driverName?: string) => Promise<string>;
@@ -320,6 +321,19 @@ const onProcessSuccess = async <TPayload>(input: {
 }): Promise<boolean> => {
   await TypedQueue.ack(input.queueName, input.message.id, input.driverName);
 
+  await recordQueueMonitorJob({
+    queueName: input.queueName,
+    status: 'completed',
+    job: {
+      id: input.message.id,
+      name: `${input.queueName}-job`,
+      data: input.message.payload,
+      attemptsMade: getAttemptsFromMessage(input.message),
+      processedOn: input.startedAtMs,
+      finishedOn: Date.now(),
+    },
+  });
+
   if (typeof input.trackerApi.completed === 'function') {
     await input.trackerApi.completed({
       queueName: input.queueName,
@@ -386,6 +400,22 @@ const onProcessFailure = async <TPayload>(input: {
   }
 
   await TypedQueue.ack(input.queueName, input.message.id, input.driverName);
+
+  await recordQueueMonitorJob({
+    queueName: input.queueName,
+    status: 'failed',
+    job: {
+      id: input.message.id,
+      name: `${input.queueName}-job`,
+      data: input.message.payload,
+      attemptsMade: nextAttempts,
+      failedReason: failure.message,
+      processedOn: Date.now(),
+      finishedOn: Date.now(),
+    },
+    error: failure,
+  });
+
   await removeHeartbeatIfSupported(input.queueName, input.message.id);
 
   if (typeof input.trackerApi.failed === 'function') {

package/src/queueMonitorHistory.ts

@@ -0,0 +1,114 @@
+import { isNonEmptyString, isObject, Logger, queueConfig } from '@zintrust/core';
+
+type QueueMonitorStatus = 'completed' | 'failed';
+
+type QueueMonitorJobLike = {
+  id?: string;
+  name?: string;
+  data?: unknown;
+  attemptsMade?: number;
+  failedReason?: string;
+  processedOn?: number;
+  finishedOn?: number;
+};
+
+type QueueMonitorMetrics = {
+  recordJob: (
+    queueName: string,
+    status: QueueMonitorStatus,
+    job: QueueMonitorJobLike,
+    error?: Error
+  ) => Promise<void>;
+};
+
+type QueueMonitorModule = {
+  createMetrics?: (config: {
+    host: string;
+    port: number;
+    password?: string;
+    db: number;
+  }) => QueueMonitorMetrics;
+};
+
+let queueMonitorMetricsPromise: Promise<QueueMonitorMetrics | null> | null = null;
+
+const toFiniteInteger = (value: unknown, fallback: number): number => {
+  if (typeof value === 'number' && Number.isFinite(value)) {
+    return Math.floor(value);
+  }
+
+  if (typeof value === 'string' && value.trim() !== '') {
+    const parsed = Number(value);
+    if (Number.isFinite(parsed)) {
+      return Math.floor(parsed);
+    }
+  }
+
+  return fallback;
+};
+
+const resolveQueueMonitorRedisConfig = (): {
+  host: string;
+  port: number;
+  password?: string;
+  db: number;
+} | null => {
+  const redisConfig = queueConfig?.drivers?.redis;
+
+  if (!isObject(redisConfig) || redisConfig['driver'] !== 'redis') {
+    return null;
+  }
+
+  const host = isNonEmptyString(redisConfig['host']) ? redisConfig['host'].trim() : '127.0.0.1';
+  const port = toFiniteInteger(redisConfig['port'], 6379);
+  const db = toFiniteInteger(redisConfig['database'], 0);
+  const password = isNonEmptyString(redisConfig['password']) ? redisConfig['password'] : undefined;
+
+  return { host, port, password, db };
+};
+
+const loadQueueMonitorMetrics = async (): Promise<QueueMonitorMetrics | null> => {
+  const redisConfig = resolveQueueMonitorRedisConfig();
+  if (redisConfig === null) {
+    return null;
+  }
+
+  try {
+    const module = (await import('@zintrust/queue-monitor')) as QueueMonitorModule;
+    if (typeof module.createMetrics !== 'function') {
+      return null;
+    }
+
+    return module.createMetrics(redisConfig);
+  } catch (error) {
+    Logger.debug('Queue monitor metrics are unavailable for worker history recording', error);
+    return null;
+  }
+};
+
+const getQueueMonitorMetrics = async (): Promise<QueueMonitorMetrics | null> => {
+  queueMonitorMetricsPromise ??= loadQueueMonitorMetrics();
+  return queueMonitorMetricsPromise;
+};
+
+export const recordQueueMonitorJob = async (input: {
+  queueName: string;
+  status: QueueMonitorStatus;
+  job: QueueMonitorJobLike;
+  error?: Error;
+}): Promise<void> => {
+  const metrics = await getQueueMonitorMetrics();
+  if (metrics === null) {
+    return;
+  }
+
+  try {
+    await metrics.recordJob(input.queueName, input.status, input.job, input.error);
+  } catch (error) {
+    Logger.debug('Queue monitor history write failed', {
+      queueName: input.queueName,
+      status: input.status,
+      error,
+    });
+  }
+};

package/src/types/queue-monitor.d.ts

@@ -1,4 +1,43 @@
 declare module '@zintrust/queue-monitor' {
+  export type JobStatus = 'completed' | 'failed';
+
+  export type JobSummary = {
+    id: string | undefined;
+    name: string;
+    queue?: string;
+    data: unknown;
+    attempts: number;
+    status?: string;
+    failedReason?: string;
+    timestamp: number;
+    processedOn?: number;
+    finishedOn?: number;
+  };
+
+  export type Metrics = {
+    recordJob: (
+      queue: string,
+      status: JobStatus,
+      job: {
+        id?: string;
+        name?: string;
+        data?: unknown;
+        attemptsMade?: number;
+        failedReason?: string;
+        processedOn?: number;
+        finishedOn?: number;
+      },
+      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 type QueueCounts = {
     waiting: number;
     active: number;
@@ -34,6 +73,13 @@ declare module '@zintrust/queue-monitor' {
     getSnapshot: () => Promise<QueueMonitorSnapshot>;
   };
 
+  export const createMetrics: (config: {
+    host: string;
+    port: number;
+    password?: string;
+    db: number;
+  }) => Metrics;
+
   export const QueueMonitor: Readonly<{
     create: (config: QueueMonitorConfig) => QueueMonitorApi;
   }>;