@iskra-bun/worker-kit 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # @iskra-bun/worker-kit
 
+## 0.2.0
+
+### Minor Changes
+
+- f9654df: New worker features:
+
+    - Scheduled/repeat jobs: a `repeat` option on `JobOptions` plus a `schedule(name, data, repeat, opts?)` convenience for cron/interval jobs.
+    - Dead-letter handling: opt-in `deadLetter` emits a `worker:dead-letter` event with the job and `failedReason` once retries are exhausted.
+    - Job results: handlers may return a value (`JobHandler<T, R>`); the enqueue descriptor exposes a `result()` helper backed by BullMQ `QueueEvents`.
+
+### Patch Changes
+
+- f9654df: `register`, `enqueue`, and `JobHandler` are now generic over the job payload type, so a handler's `job.data` and the enqueued payload are typed instead of `any`. Defaults to `unknown`, so existing call sites compile unchanged.
+- f9654df: `stop()` now drains in-flight jobs by fully closing the worker before closing the queue, instead of closing both concurrently (which could leave a running job stuck in the `active` state).
+- Fix a connection leak after `stop()`. `stop()` now sets the stopped flag first, and `getQueueEvents()` throws `WorkerManager is stopped; cannot open QueueEvents` rather than lazily opening a new orphaned connection. Job descriptors created after stop reject instead of silently holding an open connection.
+- Updated dependencies [f9654df]
+- Updated dependencies
+- Updated dependencies [f9654df]
+    - @iskra-bun/core@0.1.1
+
 ## 0.1.0
 
 ### Minor Changes

package/dist/index.d.ts

@@ -14,7 +14,28 @@ interface WorkerManagerOptions {
     queueName?: string;
     /** Opciones por defecto para cada job */
     defaultJobOptions?: JobOptions;
+    /**
+     * Activa el ruteo a dead-letter: cuando un job agota todos sus reintentos
+     * se emite el evento `worker:dead-letter` en el bus de eventos de la App.
+     * Opt-in para no cambiar el comportamiento existente (default: false).
+     */
+    deadLetter?: boolean;
 }
+/**
+ * Especificación de repetición para jobs programados.
+ *
+ * - Un string se interpreta como un patrón cron (ej: '0 0 * * *').
+ * - `{ every: ms }` repite cada `ms` milisegundos.
+ * - `{ pattern: cron }` repite según el patrón cron, con opciones extra.
+ */
+type RepeatSpec = string | {
+    every: number;
+    limit?: number;
+} | {
+    pattern: string;
+    limit?: number;
+    tz?: string;
+};
 interface JobOptions {
     /** Reintentos en caso de fallo */
     attempts?: number;
@@ -31,13 +52,48 @@ interface JobOptions {
     removeOnComplete?: boolean | number;
     /** Eliminar el job de Redis al fallar */
     removeOnFail?: boolean | number;
+    /**
+     * Programa el job como repetible (cron o intervalo).
+     * Se reenvía a la opción `repeat` de BullMQ.
+     */
+    repeat?: RepeatSpec;
 }
-type JobHandler = (job: {
+/**
+ * Handler de un job. Puede devolver un valor `R` que queda disponible como
+ * resultado del job (recuperable vía `job.waitUntilFinished`). Devolver `void`
+ * sigue siendo válido (R por defecto es `void`).
+ */
+type JobHandler<T = unknown, R = void> = (job: {
     id: string;
     name: string;
-    data: any;
+    data: T;
+    attemptsMade: number;
+}) => Promise<R>;
+/**
+ * Payload del evento `worker:dead-letter`, emitido cuando un job agota todos
+ * sus reintentos y `deadLetter` está activado.
+ */
+interface DeadLetterPayload {
+    jobId: string | undefined;
+    name: string | undefined;
+    data: unknown;
+    failedReason: string | undefined;
     attemptsMade: number;
-}) => Promise<void>;
+}
+/**
+ * Descriptor devuelto por `enqueue`/`schedule`. Además de los datos del job,
+ * expone `result()` para esperar el valor de retorno del handler.
+ */
+interface JobDescriptor<T = unknown, R = unknown> {
+    id: string;
+    name: string;
+    data: T;
+    /**
+     * Espera a que el job termine y resuelve con el valor que devolvió el
+     * handler. Lanza si el job falló. Requiere una conexión a Redis viva.
+     */
+    result(ttlMs?: number): Promise<R>;
+}
 
 declare class QueueError extends IskraError {
     constructor(message: string, options?: {
@@ -58,25 +114,68 @@ declare class WorkerManager implements Driver {
     private handlers;
     private queue;
     private worker;
+    private queueEvents;
+    private stopped;
     private options;
+    /** Tope de tamaño (bytes) del payload serializado de un job. */
+    private static readonly MAX_PAYLOAD_BYTES;
     constructor(options: WorkerManagerOptions);
     init(app: App): Promise<void>;
     /**
-     * Registra un handler para un tipo de job.
+     * Registra un handler para un tipo de job. El handler puede devolver un
+     * valor `R` que queda disponible como resultado del job.
      */
-    register(jobName: string, handler: JobHandler): this;
+    register<T = unknown, R = void>(jobName: string, handler: JobHandler<T, R>): this;
     /**
-     * Encola un job para ser procesado.
+     * Encola un job para ser procesado. Devuelve un descriptor que, además de
+     * los datos del job, expone `result()` para esperar el valor de retorno del
+     * handler.
      */
-    enqueue(name: string, data: any, opts?: JobOptions): Promise<{
-        id: string;
-        name: string;
-        data: any;
-    }>;
+    enqueue<T = unknown, R = unknown>(name: string, data: T, opts?: JobOptions): Promise<JobDescriptor<T, R>>;
+    /**
+     * Programa un job repetible (cron o intervalo). Conveniencia sobre
+     * `enqueue` con la opción `repeat` ya configurada.
+     *
+     * @param repeat patrón cron (string) o `{ every: ms }`/`{ pattern: cron }`.
+     */
+    schedule<T = unknown, R = unknown>(name: string, data: T, repeat: RepeatSpec, opts?: JobOptions): Promise<JobDescriptor<T, R>>;
     start(): Promise<void>;
     stop(): Promise<void>;
     private parseConnection;
     private mapJobOptions;
+    /**
+     * Normaliza una RepeatSpec a la forma `repeat` de BullMQ:
+     * - string  → `{ pattern: cron }`
+     * - `{ every }` / `{ pattern }` → se reenvían tal cual.
+     */
+    private mapRepeat;
+    /**
+     * Valida la entrada de `enqueue` ANTES de tocar Redis, para evitar que
+     * entrada no confiable inunde la queue, almacene payloads gigantes o
+     * programe repeticiones malformadas. Lanza `QueueError` ante cualquier
+     * problema; no muta nada.
+     */
+    private validateEnqueue;
+    /** Rechaza payloads cuya serialización JSON excede el tope configurado. */
+    private validatePayloadSize;
+    /** Rechaza specs de repetición vacías, intervalos no positivos o crons en blanco. */
+    private validateRepeat;
+    /**
+     * Maneja el evento `failed` del worker. Loggea el fallo y, si el job agotó
+     * todos sus reintentos y `deadLetter` está activado, emite
+     * `worker:dead-letter` en el bus de eventos de la App.
+     */
+    private onFailed;
+    /**
+     * Construye el descriptor de un job, incluyendo el helper `result()` que
+     * espera el valor de retorno del handler vía `job.waitUntilFinished`.
+     */
+    private buildDescriptor;
+    /**
+     * Devuelve (creando perezosamente) una instancia compartida de QueueEvents
+     * usada para esperar resultados de jobs.
+     */
+    private getQueueEvents;
 }
 
-export { JobError, type JobHandler, type JobOptions, QueueError, WorkerManager, type WorkerManagerOptions };
+export { type DeadLetterPayload, type JobDescriptor, JobError, type JobHandler, type JobOptions, QueueError, type RepeatSpec, WorkerManager, type WorkerManagerOptions };

package/dist/index.js

@@ -1,5 +1,5 @@
 // src/index.ts
-import { Queue, Worker } from "bullmq";
+import { Queue, QueueEvents, Worker } from "bullmq";
 
 // src/errors.ts
 import { IskraError, ErrorCodes } from "@iskra-bun/core";
@@ -17,13 +17,19 @@ var JobError = class extends IskraError {
 };
 
 // src/index.ts
-var WorkerManager = class {
+var WorkerManager = class _WorkerManager {
   name = "WorkerManager";
   app = null;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
   handlers = /* @__PURE__ */ new Map();
   queue = null;
   worker = null;
+  queueEvents = null;
+  stopped = false;
   options;
+  /** Tope de tamaño (bytes) del payload serializado de un job. */
+  static MAX_PAYLOAD_BYTES = 1024 * 1024;
+  // 1 MB
   constructor(options) {
     this.options = options;
   }
@@ -43,14 +49,17 @@ var WorkerManager = class {
     }
   }
   /**
-   * Registra un handler para un tipo de job.
+   * Registra un handler para un tipo de job. El handler puede devolver un
+   * valor `R` que queda disponible como resultado del job.
    */
   register(jobName, handler) {
     this.handlers.set(jobName, handler);
     return this;
   }
   /**
-   * Encola un job para ser procesado.
+   * Encola un job para ser procesado. Devuelve un descriptor que, además de
+   * los datos del job, expone `result()` para esperar el valor de retorno del
+   * handler.
    */
   async enqueue(name, data, opts) {
     if (!this.queue) {
@@ -58,9 +67,19 @@ var WorkerManager = class {
         context: { jobName: name }
       });
     }
+    this.validateEnqueue(name, data, opts);
     const job = await this.queue.add(name, data, this.mapJobOptions(opts));
     this.app?.logger.debug({ jobId: job.id, jobName: name }, "Job enqueued");
-    return { id: job.id, name, data };
+    return this.buildDescriptor(job, name, data);
+  }
+  /**
+   * Programa un job repetible (cron o intervalo). Conveniencia sobre
+   * `enqueue` con la opción `repeat` ya configurada.
+   *
+   * @param repeat patrón cron (string) o `{ every: ms }`/`{ pattern: cron }`.
+   */
+  async schedule(name, data, repeat, opts) {
+    return this.enqueue(name, data, { ...opts, repeat });
   }
   async start() {
     const connection = this.parseConnection();
@@ -73,7 +92,7 @@ var WorkerManager = class {
           return;
         }
         try {
-          await handler({
+          return await handler({
             id: job.id,
             name: job.name,
             data: job.data,
@@ -97,7 +116,7 @@ var WorkerManager = class {
       this.app?.logger.debug({ jobId: job.id, jobName: job.name }, "Job completed");
     });
     this.worker.on("failed", (job, err) => {
-      this.app?.logger.error({ jobId: job?.id, jobName: job?.name, err }, "Job failed");
+      this.onFailed(job, err);
     });
     this.app?.logger.info({
       queue: this.options.queueName || "iskra-jobs",
@@ -105,14 +124,37 @@ var WorkerManager = class {
     }, "WorkerManager started");
   }
   async stop() {
-    const closePromises = [];
+    this.stopped = true;
     if (this.worker) {
-      closePromises.push(this.worker.close());
+      try {
+        await this.worker.close();
+      } catch (err) {
+        this.app?.logger.error(
+          { err: err instanceof Error ? err : new Error(String(err)) },
+          "WorkerManager: error while closing worker"
+        );
+      }
+    }
+    if (this.queueEvents) {
+      try {
+        await this.queueEvents.close();
+      } catch (err) {
+        this.app?.logger.error(
+          { err: err instanceof Error ? err : new Error(String(err)) },
+          "WorkerManager: error while closing queue events"
+        );
+      }
     }
     if (this.queue) {
-      closePromises.push(this.queue.close());
+      try {
+        await this.queue.close();
+      } catch (err) {
+        this.app?.logger.error(
+          { err: err instanceof Error ? err : new Error(String(err)) },
+          "WorkerManager: error while closing queue"
+        );
+      }
     }
-    await Promise.all(closePromises);
     this.app?.logger.info("WorkerManager stopped");
   }
   parseConnection() {
@@ -129,7 +171,7 @@ var WorkerManager = class {
   }
   mapJobOptions(opts) {
     if (!opts) return void 0;
-    return {
+    const mapped = {
       attempts: opts.attempts,
       delay: opts.delay,
       priority: opts.priority,
@@ -137,6 +179,149 @@ var WorkerManager = class {
       removeOnComplete: opts.removeOnComplete,
       removeOnFail: opts.removeOnFail
     };
+    if (opts.repeat !== void 0) {
+      mapped.repeat = this.mapRepeat(opts.repeat);
+    }
+    return mapped;
+  }
+  /**
+   * Normaliza una RepeatSpec a la forma `repeat` de BullMQ:
+   * - string  → `{ pattern: cron }`
+   * - `{ every }` / `{ pattern }` → se reenvían tal cual.
+   */
+  mapRepeat(repeat) {
+    if (typeof repeat === "string") {
+      return { pattern: repeat };
+    }
+    return { ...repeat };
+  }
+  /**
+   * Valida la entrada de `enqueue` ANTES de tocar Redis, para evitar que
+   * entrada no confiable inunde la queue, almacene payloads gigantes o
+   * programe repeticiones malformadas. Lanza `QueueError` ante cualquier
+   * problema; no muta nada.
+   */
+  validateEnqueue(name, data, opts) {
+    if (!this.handlers.has(name)) {
+      throw new QueueError(`No handler registered for job "${name}"`, {
+        context: { jobName: name }
+      });
+    }
+    this.validatePayloadSize(name, data);
+    if (opts?.repeat !== void 0) {
+      this.validateRepeat(name, opts.repeat);
+    }
+  }
+  /** Rechaza payloads cuya serialización JSON excede el tope configurado. */
+  validatePayloadSize(name, data) {
+    let serialized;
+    try {
+      serialized = JSON.stringify(data ?? null);
+    } catch (err) {
+      throw new QueueError(`Job "${name}" data is not serializable`, {
+        cause: err instanceof Error ? err : new Error(String(err)),
+        context: { jobName: name }
+      });
+    }
+    const size = Buffer.byteLength(serialized, "utf8");
+    if (size > _WorkerManager.MAX_PAYLOAD_BYTES) {
+      throw new QueueError(
+        `Job "${name}" payload too large: ${size} bytes (max ${_WorkerManager.MAX_PAYLOAD_BYTES})`,
+        { context: { jobName: name, size, max: _WorkerManager.MAX_PAYLOAD_BYTES } }
+      );
+    }
+  }
+  /** Rechaza specs de repetición vacías, intervalos no positivos o crons en blanco. */
+  validateRepeat(name, repeat) {
+    if (typeof repeat === "string") {
+      if (repeat.trim().length === 0) {
+        throw new QueueError(`Job "${name}" has an empty cron repeat pattern`, {
+          context: { jobName: name }
+        });
+      }
+      return;
+    }
+    const hasEvery = "every" in repeat;
+    const hasPattern = "pattern" in repeat;
+    if (!hasEvery && !hasPattern) {
+      throw new QueueError(`Job "${name}" repeat spec must define "every" or "pattern"`, {
+        context: { jobName: name }
+      });
+    }
+    if (hasEvery && !(typeof repeat.every === "number" && repeat.every > 0)) {
+      throw new QueueError(`Job "${name}" repeat "every" must be a positive number`, {
+        context: { jobName: name, every: repeat.every }
+      });
+    }
+    if (hasPattern && (typeof repeat.pattern !== "string" || repeat.pattern.trim().length === 0)) {
+      throw new QueueError(`Job "${name}" repeat "pattern" must be a non-empty cron string`, {
+        context: { jobName: name }
+      });
+    }
+  }
+  /**
+   * Maneja el evento `failed` del worker. Loggea el fallo y, si el job agotó
+   * todos sus reintentos y `deadLetter` está activado, emite
+   * `worker:dead-letter` en el bus de eventos de la App.
+   */
+  onFailed(job, err) {
+    this.app?.logger.error({ jobId: job?.id, jobName: job?.name, err }, "Job failed");
+    if (!this.options.deadLetter || !job) return;
+    const maxAttempts = job.opts?.attempts ?? 1;
+    if (job.attemptsMade < maxAttempts) return;
+    const payload = {
+      jobId: job.id,
+      name: job.name,
+      data: job.data,
+      failedReason: job.failedReason ?? err?.message,
+      attemptsMade: job.attemptsMade
+    };
+    this.app?.events.emit("worker:dead-letter", payload);
+    this.app?.logger.warn(
+      { jobId: job.id, jobName: job.name, attemptsMade: job.attemptsMade },
+      "Job routed to dead-letter"
+    );
+  }
+  /**
+   * Construye el descriptor de un job, incluyendo el helper `result()` que
+   * espera el valor de retorno del handler vía `job.waitUntilFinished`.
+   */
+  buildDescriptor(job, name, data) {
+    return {
+      id: job.id,
+      name,
+      data,
+      // async so a post-stop getQueueEvents() throw surfaces as a rejected
+      // promise rather than a synchronous throw.
+      result: async (ttlMs) => {
+        const queueEvents = this.getQueueEvents();
+        return job.waitUntilFinished(queueEvents, ttlMs);
+      }
+    };
+  }
+  /**
+   * Devuelve (creando perezosamente) una instancia compartida de QueueEvents
+   * usada para esperar resultados de jobs.
+   */
+  getQueueEvents() {
+    if (this.stopped) {
+      throw new QueueError("WorkerManager is stopped; cannot open QueueEvents", {
+        context: { queueName: this.options.queueName || "iskra-jobs" }
+      });
+    }
+    if (!this.queueEvents) {
+      try {
+        this.queueEvents = new QueueEvents(this.options.queueName || "iskra-jobs", {
+          connection: this.parseConnection()
+        });
+      } catch (err) {
+        throw new QueueError("Failed to initialize BullMQ QueueEvents", {
+          cause: err instanceof Error ? err : new Error(String(err)),
+          context: { queueName: this.options.queueName || "iskra-jobs" }
+        });
+      }
+    }
+    return this.queueEvents;
   }
 };
 export {

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts","../src/errors.ts"],"sourcesContent":["import type { Driver, App } from '@iskra-bun/core';\nimport { Queue, Worker, type Job as BullJob } from 'bullmq';\nimport { QueueError, JobError } from './errors';\nimport type { WorkerManagerOptions, JobOptions, JobHandler } from './types';\n\nexport type { WorkerManagerOptions, JobOptions, JobHandler } from './types';\nexport * from './errors';\n\nexport class WorkerManager implements Driver {\n    name = 'WorkerManager';\n    private app: App | null = null;\n    private handlers: Map<string, JobHandler> = new Map();\n    private queue: Queue | null = null;\n    private worker: Worker | null = null;\n    private options: WorkerManagerOptions;\n\n    constructor(options: WorkerManagerOptions) {\n        this.options = options;\n    }\n\n    async init(app: App) {\n        this.app = app;\n\n        const connection = this.parseConnection();\n\n        try {\n            this.queue = new Queue(this.options.queueName || 'iskra-jobs', {\n                connection,\n                defaultJobOptions: this.mapJobOptions(this.options.defaultJobOptions),\n            });\n        } catch (err) {\n            throw new QueueError('Failed to initialize BullMQ queue', {\n                cause: err instanceof Error ? err : new Error(String(err)),\n                context: { queueName: this.options.queueName || 'iskra-jobs' },\n            });\n        }\n    }\n\n    /**\n     * Registra un handler para un tipo de job.\n     */\n    register(jobName: string, handler: JobHandler) {\n        this.handlers.set(jobName, handler);\n        return this;\n    }\n\n    /**\n     * Encola un job para ser procesado.\n     */\n    async enqueue(name: string, data: any, opts?: JobOptions) {\n        if (!this.queue) {\n            throw new QueueError('Queue not initialized. Did you call init()?', {\n                context: { jobName: name },\n            });\n        }\n\n        const job = await this.queue.add(name, data, this.mapJobOptions(opts));\n        this.app?.logger.debug({ jobId: job.id, jobName: name }, 'Job enqueued');\n        return { id: job.id!, name, data };\n    }\n\n    async start() {\n        const connection = this.parseConnection();\n\n        this.worker = new Worker(\n            this.options.queueName || 'iskra-jobs',\n            async (job: BullJob) => {\n                const handler = this.handlers.get(job.name);\n                if (!handler) {\n                    this.app?.logger.warn({ jobName: job.name, jobId: job.id }, 'No handler registered for job');\n                    return;\n                }\n\n                try {\n                    await handler({\n                        id: job.id!,\n                        name: job.name,\n                        data: job.data,\n                        attemptsMade: job.attemptsMade,\n                    });\n                } catch (err) {\n                    const jobErr = new JobError(`Job \"${job.name}\" failed`, {\n                        cause: err instanceof Error ? err : new Error(String(err)),\n                        context: { jobId: job.id, jobName: job.name, attemptsMade: job.attemptsMade },\n                    });\n                    this.app?.logger.error({ err: jobErr }, jobErr.message);\n                    throw err; // Re-throw para que BullMQ maneje el retry\n                }\n            },\n            {\n                connection,\n                concurrency: this.options.concurrency || 1,\n            },\n        );\n\n        this.worker.on('completed', (job) => {\n            this.app?.logger.debug({ jobId: job.id, jobName: job.name }, 'Job completed');\n        });\n\n        this.worker.on('failed', (job, err) => {\n            this.app?.logger.error({ jobId: job?.id, jobName: job?.name, err }, 'Job failed');\n        });\n\n        this.app?.logger.info({\n            queue: this.options.queueName || 'iskra-jobs',\n            concurrency: this.options.concurrency || 1,\n        }, 'WorkerManager started');\n    }\n\n    async stop() {\n        const closePromises: Promise<void>[] = [];\n\n        if (this.worker) {\n            closePromises.push(this.worker.close());\n        }\n        if (this.queue) {\n            closePromises.push(this.queue.close());\n        }\n\n        await Promise.all(closePromises);\n        this.app?.logger.info('WorkerManager stopped');\n    }\n\n    private parseConnection() {\n        if (typeof this.options.connection === 'string') {\n            const url = new URL(this.options.connection);\n            return {\n                host: url.hostname,\n                port: Number(url.port) || 6379,\n                password: url.password || undefined,\n                db: url.pathname ? Number(url.pathname.slice(1)) || 0 : 0,\n            };\n        }\n        return this.options.connection;\n    }\n\n    private mapJobOptions(opts?: JobOptions) {\n        if (!opts) return undefined;\n        return {\n            attempts: opts.attempts,\n            delay: opts.delay,\n            priority: opts.priority,\n            backoff: opts.backoff,\n            removeOnComplete: opts.removeOnComplete,\n            removeOnFail: opts.removeOnFail,\n        };\n    }\n}\n","import { IskraError, ErrorCodes } from '@iskra-bun/core';\n\n// ─── Queue Error ─────────────────────────────────────────────────────────────\n\nexport class QueueError extends IskraError {\n    constructor(message: string, options?: { cause?: Error; context?: Record<string, unknown> }) {\n        super(message, { code: ErrorCodes.QUEUE_ERROR, ...options });\n        this.name = 'QueueError';\n    }\n}\n\n// ─── Job Error ───────────────────────────────────────────────────────────────\n\nexport class JobError extends IskraError {\n    constructor(message: string, options?: { cause?: Error; context?: Record<string, unknown> }) {\n        super(message, { code: ErrorCodes.JOB_ERROR, ...options });\n        this.name = 'JobError';\n    }\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../src/index.ts","../src/errors.ts"],"sourcesContent":["import type { Driver, App } from '@iskra-bun/core';\nimport { Queue, QueueEvents, Worker, type Job as BullJob } from 'bullmq';\nimport { QueueError, JobError } from './errors';\nimport type {\n    WorkerManagerOptions,\n    JobOptions,\n    JobHandler,\n    RepeatSpec,\n    JobDescriptor,\n    DeadLetterPayload,\n} from './types';\n\nexport type {\n    WorkerManagerOptions,\n    JobOptions,\n    JobHandler,\n    RepeatSpec,\n    JobDescriptor,\n    DeadLetterPayload,\n} from './types';\nexport * from './errors';\n\nexport class WorkerManager implements Driver {\n    name = 'WorkerManager';\n    private app: App | null = null;\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any\n    private handlers: Map<string, JobHandler<any, any>> = new Map();\n    private queue: Queue | null = null;\n    private worker: Worker | null = null;\n    private queueEvents: QueueEvents | null = null;\n    private stopped = false;\n    private options: WorkerManagerOptions;\n\n    /** Tope de tamaño (bytes) del payload serializado de un job. */\n    private static readonly MAX_PAYLOAD_BYTES = 1024 * 1024; // 1 MB\n\n    constructor(options: WorkerManagerOptions) {\n        this.options = options;\n    }\n\n    async init(app: App) {\n        this.app = app;\n\n        const connection = this.parseConnection();\n\n        try {\n            this.queue = new Queue(this.options.queueName || 'iskra-jobs', {\n                connection,\n                defaultJobOptions: this.mapJobOptions(this.options.defaultJobOptions),\n            });\n        } catch (err) {\n            throw new QueueError('Failed to initialize BullMQ queue', {\n                cause: err instanceof Error ? err : new Error(String(err)),\n                context: { queueName: this.options.queueName || 'iskra-jobs' },\n            });\n        }\n    }\n\n    /**\n     * Registra un handler para un tipo de job. El handler puede devolver un\n     * valor `R` que queda disponible como resultado del job.\n     */\n    register<T = unknown, R = void>(jobName: string, handler: JobHandler<T, R>) {\n        this.handlers.set(jobName, handler);\n        return this;\n    }\n\n    /**\n     * Encola un job para ser procesado. Devuelve un descriptor que, además de\n     * los datos del job, expone `result()` para esperar el valor de retorno del\n     * handler.\n     */\n    async enqueue<T = unknown, R = unknown>(\n        name: string,\n        data: T,\n        opts?: JobOptions,\n    ): Promise<JobDescriptor<T, R>> {\n        if (!this.queue) {\n            throw new QueueError('Queue not initialized. Did you call init()?', {\n                context: { jobName: name },\n            });\n        }\n\n        this.validateEnqueue(name, data, opts);\n\n        const job = await this.queue.add(name, data, this.mapJobOptions(opts));\n        this.app?.logger.debug({ jobId: job.id, jobName: name }, 'Job enqueued');\n        return this.buildDescriptor<T, R>(job, name, data);\n    }\n\n    /**\n     * Programa un job repetible (cron o intervalo). Conveniencia sobre\n     * `enqueue` con la opción `repeat` ya configurada.\n     *\n     * @param repeat patrón cron (string) o `{ every: ms }`/`{ pattern: cron }`.\n     */\n    async schedule<T = unknown, R = unknown>(\n        name: string,\n        data: T,\n        repeat: RepeatSpec,\n        opts?: JobOptions,\n    ): Promise<JobDescriptor<T, R>> {\n        return this.enqueue<T, R>(name, data, { ...opts, repeat });\n    }\n\n    async start() {\n        const connection = this.parseConnection();\n\n        this.worker = new Worker(\n            this.options.queueName || 'iskra-jobs',\n            async (job: BullJob) => {\n                const handler = this.handlers.get(job.name);\n                if (!handler) {\n                    this.app?.logger.warn({ jobName: job.name, jobId: job.id }, 'No handler registered for job');\n                    return;\n                }\n\n                try {\n                    return await handler({\n                        id: job.id!,\n                        name: job.name,\n                        data: job.data,\n                        attemptsMade: job.attemptsMade,\n                    });\n                } catch (err) {\n                    const jobErr = new JobError(`Job \"${job.name}\" failed`, {\n                        cause: err instanceof Error ? err : new Error(String(err)),\n                        context: { jobId: job.id, jobName: job.name, attemptsMade: job.attemptsMade },\n                    });\n                    this.app?.logger.error({ err: jobErr }, jobErr.message);\n                    throw err; // Re-throw para que BullMQ maneje el retry\n                }\n            },\n            {\n                connection,\n                concurrency: this.options.concurrency || 1,\n            },\n        );\n\n        this.worker.on('completed', (job) => {\n            this.app?.logger.debug({ jobId: job.id, jobName: job.name }, 'Job completed');\n        });\n\n        this.worker.on('failed', (job, err) => {\n            this.onFailed(job, err);\n        });\n\n        this.app?.logger.info({\n            queue: this.options.queueName || 'iskra-jobs',\n            concurrency: this.options.concurrency || 1,\n        }, 'WorkerManager started');\n    }\n\n    async stop() {\n        // Mark as stopped first so any in-flight result()/getQueueEvents() call\n        // throws instead of lazily opening a fresh, never-closed QueueEvents.\n        this.stopped = true;\n\n        // Close the worker first (without force) so BullMQ waits for any\n        // in-flight job to finish before tearing down its Redis connections.\n        // Only then close the queue — closing them concurrently can cut the\n        // queue connection out from under a still-draining worker.\n        if (this.worker) {\n            try {\n                await this.worker.close();\n            } catch (err) {\n                this.app?.logger.error(\n                    { err: err instanceof Error ? err : new Error(String(err)) },\n                    'WorkerManager: error while closing worker',\n                );\n            }\n        }\n\n        if (this.queueEvents) {\n            try {\n                await this.queueEvents.close();\n            } catch (err) {\n                this.app?.logger.error(\n                    { err: err instanceof Error ? err : new Error(String(err)) },\n                    'WorkerManager: error while closing queue events',\n                );\n            }\n        }\n\n        if (this.queue) {\n            try {\n                await this.queue.close();\n            } catch (err) {\n                this.app?.logger.error(\n                    { err: err instanceof Error ? err : new Error(String(err)) },\n                    'WorkerManager: error while closing queue',\n                );\n            }\n        }\n\n        this.app?.logger.info('WorkerManager stopped');\n    }\n\n    private parseConnection() {\n        if (typeof this.options.connection === 'string') {\n            const url = new URL(this.options.connection);\n            return {\n                host: url.hostname,\n                port: Number(url.port) || 6379,\n                password: url.password || undefined,\n                db: url.pathname ? Number(url.pathname.slice(1)) || 0 : 0,\n            };\n        }\n        return this.options.connection;\n    }\n\n    private mapJobOptions(opts?: JobOptions) {\n        if (!opts) return undefined;\n        const mapped: Record<string, unknown> = {\n            attempts: opts.attempts,\n            delay: opts.delay,\n            priority: opts.priority,\n            backoff: opts.backoff,\n            removeOnComplete: opts.removeOnComplete,\n            removeOnFail: opts.removeOnFail,\n        };\n        if (opts.repeat !== undefined) {\n            mapped.repeat = this.mapRepeat(opts.repeat);\n        }\n        return mapped;\n    }\n\n    /**\n     * Normaliza una RepeatSpec a la forma `repeat` de BullMQ:\n     * - string  → `{ pattern: cron }`\n     * - `{ every }` / `{ pattern }` → se reenvían tal cual.\n     */\n    private mapRepeat(repeat: RepeatSpec) {\n        if (typeof repeat === 'string') {\n            return { pattern: repeat };\n        }\n        return { ...repeat };\n    }\n\n    /**\n     * Valida la entrada de `enqueue` ANTES de tocar Redis, para evitar que\n     * entrada no confiable inunde la queue, almacene payloads gigantes o\n     * programe repeticiones malformadas. Lanza `QueueError` ante cualquier\n     * problema; no muta nada.\n     */\n    private validateEnqueue(name: string, data: unknown, opts?: JobOptions) {\n        if (!this.handlers.has(name)) {\n            throw new QueueError(`No handler registered for job \"${name}\"`, {\n                context: { jobName: name },\n            });\n        }\n\n        this.validatePayloadSize(name, data);\n\n        if (opts?.repeat !== undefined) {\n            this.validateRepeat(name, opts.repeat);\n        }\n    }\n\n    /** Rechaza payloads cuya serialización JSON excede el tope configurado. */\n    private validatePayloadSize(name: string, data: unknown) {\n        let serialized: string;\n        try {\n            serialized = JSON.stringify(data ?? null);\n        } catch (err) {\n            throw new QueueError(`Job \"${name}\" data is not serializable`, {\n                cause: err instanceof Error ? err : new Error(String(err)),\n                context: { jobName: name },\n            });\n        }\n\n        const size = Buffer.byteLength(serialized, 'utf8');\n        if (size > WorkerManager.MAX_PAYLOAD_BYTES) {\n            throw new QueueError(\n                `Job \"${name}\" payload too large: ${size} bytes (max ${WorkerManager.MAX_PAYLOAD_BYTES})`,\n                { context: { jobName: name, size, max: WorkerManager.MAX_PAYLOAD_BYTES } },\n            );\n        }\n    }\n\n    /** Rechaza specs de repetición vacías, intervalos no positivos o crons en blanco. */\n    private validateRepeat(name: string, repeat: RepeatSpec) {\n        if (typeof repeat === 'string') {\n            if (repeat.trim().length === 0) {\n                throw new QueueError(`Job \"${name}\" has an empty cron repeat pattern`, {\n                    context: { jobName: name },\n                });\n            }\n            return;\n        }\n\n        const hasEvery = 'every' in repeat;\n        const hasPattern = 'pattern' in repeat;\n        if (!hasEvery && !hasPattern) {\n            throw new QueueError(`Job \"${name}\" repeat spec must define \"every\" or \"pattern\"`, {\n                context: { jobName: name },\n            });\n        }\n\n        if (hasEvery && !(typeof repeat.every === 'number' && repeat.every > 0)) {\n            throw new QueueError(`Job \"${name}\" repeat \"every\" must be a positive number`, {\n                context: { jobName: name, every: repeat.every },\n            });\n        }\n\n        if (hasPattern && (typeof repeat.pattern !== 'string' || repeat.pattern.trim().length === 0)) {\n            throw new QueueError(`Job \"${name}\" repeat \"pattern\" must be a non-empty cron string`, {\n                context: { jobName: name },\n            });\n        }\n    }\n\n    /**\n     * Maneja el evento `failed` del worker. Loggea el fallo y, si el job agotó\n     * todos sus reintentos y `deadLetter` está activado, emite\n     * `worker:dead-letter` en el bus de eventos de la App.\n     */\n    private onFailed(job: BullJob | undefined, err: Error) {\n        this.app?.logger.error({ jobId: job?.id, jobName: job?.name, err }, 'Job failed');\n\n        if (!this.options.deadLetter || !job) return;\n\n        // BullMQ default attempts is 1 when unspecified.\n        //\n        // Assumed BullMQ `attemptsMade` semantics at the `failed` event: on a\n        // job's TERMINAL failure (all retries exhausted) BullMQ reports\n        // `attemptsMade == opts.attempts`, so `attemptsMade < maxAttempts`\n        // identifies a non-terminal failure with a retry still pending. This is\n        // verified against bullmq 5.78 (see test/dead-letter-attempts*.test.ts);\n        // a future bump that changes `attemptsMade` reporting will fail those\n        // tests loudly rather than silently skip dead-lettering.\n        const maxAttempts = job.opts?.attempts ?? 1;\n        if (job.attemptsMade < maxAttempts) return;\n\n        const payload: DeadLetterPayload = {\n            jobId: job.id,\n            name: job.name,\n            data: job.data,\n            failedReason: job.failedReason ?? err?.message,\n            attemptsMade: job.attemptsMade,\n        };\n        this.app?.events.emit('worker:dead-letter', payload);\n        this.app?.logger.warn(\n            { jobId: job.id, jobName: job.name, attemptsMade: job.attemptsMade },\n            'Job routed to dead-letter',\n        );\n    }\n\n    /**\n     * Construye el descriptor de un job, incluyendo el helper `result()` que\n     * espera el valor de retorno del handler vía `job.waitUntilFinished`.\n     */\n    private buildDescriptor<T, R>(job: BullJob, name: string, data: T): JobDescriptor<T, R> {\n        return {\n            id: job.id!,\n            name,\n            data,\n            // async so a post-stop getQueueEvents() throw surfaces as a rejected\n            // promise rather than a synchronous throw.\n            result: async (ttlMs?: number): Promise<R> => {\n                const queueEvents = this.getQueueEvents();\n                return job.waitUntilFinished(queueEvents, ttlMs) as Promise<R>;\n            },\n        };\n    }\n\n    /**\n     * Devuelve (creando perezosamente) una instancia compartida de QueueEvents\n     * usada para esperar resultados de jobs.\n     */\n    private getQueueEvents(): QueueEvents {\n        if (this.stopped) {\n            throw new QueueError('WorkerManager is stopped; cannot open QueueEvents', {\n                context: { queueName: this.options.queueName || 'iskra-jobs' },\n            });\n        }\n        if (!this.queueEvents) {\n            try {\n                this.queueEvents = new QueueEvents(this.options.queueName || 'iskra-jobs', {\n                    connection: this.parseConnection(),\n                });\n            } catch (err) {\n                throw new QueueError('Failed to initialize BullMQ QueueEvents', {\n                    cause: err instanceof Error ? err : new Error(String(err)),\n                    context: { queueName: this.options.queueName || 'iskra-jobs' },\n                });\n            }\n        }\n        return this.queueEvents;\n    }\n}\n","import { IskraError, ErrorCodes } from '@iskra-bun/core';\n\n// ─── Queue Error ─────────────────────────────────────────────────────────────\n\nexport class QueueError extends IskraError {\n    constructor(message: string, options?: { cause?: Error; context?: Record<string, unknown> }) {\n        super(message, { code: ErrorCodes.QUEUE_ERROR, ...options });\n        this.name = 'QueueError';\n    }\n}\n\n// ─── Job Error ───────────────────────────────────────────────────────────────\n\nexport class JobError extends IskraError {\n    constructor(message: string, options?: { cause?: Error; context?: Record<string, unknown> }) {\n        super(message, { code: ErrorCodes.JOB_ERROR, ...options });\n        this.name = 'JobError';\n    }\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@iskra-bun/worker-kit",
-    "version": "0.1.0",
+    "version": "0.2.0",
     "description": "Cola de jobs en segundo plano para Iskra con BullMQ.",
     "keywords": [
         "iskra",
@@ -47,7 +47,7 @@
         "build": "tsup --config ../../tsup.config.ts"
     },
     "dependencies": {
-        "@iskra-bun/core": "0.1.0",
+        "@iskra-bun/core": "0.1.1",
         "bullmq": "^5.0.0"
     },
     "devDependencies": {

package/src/index.ts

@@ -1,19 +1,39 @@
 import type { Driver, App } from '@iskra-bun/core';
-import { Queue, Worker, type Job as BullJob } from 'bullmq';
+import { Queue, QueueEvents, Worker, type Job as BullJob } from 'bullmq';
 import { QueueError, JobError } from './errors';
-import type { WorkerManagerOptions, JobOptions, JobHandler } from './types';
+import type {
+    WorkerManagerOptions,
+    JobOptions,
+    JobHandler,
+    RepeatSpec,
+    JobDescriptor,
+    DeadLetterPayload,
+} from './types';
 
-export type { WorkerManagerOptions, JobOptions, JobHandler } from './types';
+export type {
+    WorkerManagerOptions,
+    JobOptions,
+    JobHandler,
+    RepeatSpec,
+    JobDescriptor,
+    DeadLetterPayload,
+} from './types';
 export * from './errors';
 
 export class WorkerManager implements Driver {
     name = 'WorkerManager';
     private app: App | null = null;
-    private handlers: Map<string, JobHandler> = new Map();
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    private handlers: Map<string, JobHandler<any, any>> = new Map();
     private queue: Queue | null = null;
     private worker: Worker | null = null;
+    private queueEvents: QueueEvents | null = null;
+    private stopped = false;
     private options: WorkerManagerOptions;
 
+    /** Tope de tamaño (bytes) del payload serializado de un job. */
+    private static readonly MAX_PAYLOAD_BYTES = 1024 * 1024; // 1 MB
+
     constructor(options: WorkerManagerOptions) {
         this.options = options;
     }
@@ -37,26 +57,50 @@ export class WorkerManager implements Driver {
     }
 
     /**
-     * Registra un handler para un tipo de job.
+     * Registra un handler para un tipo de job. El handler puede devolver un
+     * valor `R` que queda disponible como resultado del job.
      */
-    register(jobName: string, handler: JobHandler) {
+    register<T = unknown, R = void>(jobName: string, handler: JobHandler<T, R>) {
         this.handlers.set(jobName, handler);
         return this;
     }
 
     /**
-     * Encola un job para ser procesado.
+     * Encola un job para ser procesado. Devuelve un descriptor que, además de
+     * los datos del job, expone `result()` para esperar el valor de retorno del
+     * handler.
      */
-    async enqueue(name: string, data: any, opts?: JobOptions) {
+    async enqueue<T = unknown, R = unknown>(
+        name: string,
+        data: T,
+        opts?: JobOptions,
+    ): Promise<JobDescriptor<T, R>> {
         if (!this.queue) {
             throw new QueueError('Queue not initialized. Did you call init()?', {
                 context: { jobName: name },
             });
         }
 
+        this.validateEnqueue(name, data, opts);
+
         const job = await this.queue.add(name, data, this.mapJobOptions(opts));
         this.app?.logger.debug({ jobId: job.id, jobName: name }, 'Job enqueued');
-        return { id: job.id!, name, data };
+        return this.buildDescriptor<T, R>(job, name, data);
+    }
+
+    /**
+     * Programa un job repetible (cron o intervalo). Conveniencia sobre
+     * `enqueue` con la opción `repeat` ya configurada.
+     *
+     * @param repeat patrón cron (string) o `{ every: ms }`/`{ pattern: cron }`.
+     */
+    async schedule<T = unknown, R = unknown>(
+        name: string,
+        data: T,
+        repeat: RepeatSpec,
+        opts?: JobOptions,
+    ): Promise<JobDescriptor<T, R>> {
+        return this.enqueue<T, R>(name, data, { ...opts, repeat });
     }
 
     async start() {
@@ -72,7 +116,7 @@ export class WorkerManager implements Driver {
                 }
 
                 try {
-                    await handler({
+                    return await handler({
                         id: job.id!,
                         name: job.name,
                         data: job.data,
@@ -98,7 +142,7 @@ export class WorkerManager implements Driver {
         });
 
         this.worker.on('failed', (job, err) => {
-            this.app?.logger.error({ jobId: job?.id, jobName: job?.name, err }, 'Job failed');
+            this.onFailed(job, err);
         });
 
         this.app?.logger.info({
@@ -108,16 +152,47 @@ export class WorkerManager implements Driver {
     }
 
     async stop() {
-        const closePromises: Promise<void>[] = [];
+        // Mark as stopped first so any in-flight result()/getQueueEvents() call
+        // throws instead of lazily opening a fresh, never-closed QueueEvents.
+        this.stopped = true;
 
+        // Close the worker first (without force) so BullMQ waits for any
+        // in-flight job to finish before tearing down its Redis connections.
+        // Only then close the queue — closing them concurrently can cut the
+        // queue connection out from under a still-draining worker.
         if (this.worker) {
-            closePromises.push(this.worker.close());
+            try {
+                await this.worker.close();
+            } catch (err) {
+                this.app?.logger.error(
+                    { err: err instanceof Error ? err : new Error(String(err)) },
+                    'WorkerManager: error while closing worker',
+                );
+            }
+        }
+
+        if (this.queueEvents) {
+            try {
+                await this.queueEvents.close();
+            } catch (err) {
+                this.app?.logger.error(
+                    { err: err instanceof Error ? err : new Error(String(err)) },
+                    'WorkerManager: error while closing queue events',
+                );
+            }
         }
+
         if (this.queue) {
-            closePromises.push(this.queue.close());
+            try {
+                await this.queue.close();
+            } catch (err) {
+                this.app?.logger.error(
+                    { err: err instanceof Error ? err : new Error(String(err)) },
+                    'WorkerManager: error while closing queue',
+                );
+            }
         }
 
-        await Promise.all(closePromises);
         this.app?.logger.info('WorkerManager stopped');
     }
 
@@ -136,7 +211,7 @@ export class WorkerManager implements Driver {
 
     private mapJobOptions(opts?: JobOptions) {
         if (!opts) return undefined;
-        return {
+        const mapped: Record<string, unknown> = {
             attempts: opts.attempts,
             delay: opts.delay,
             priority: opts.priority,
@@ -144,5 +219,173 @@ export class WorkerManager implements Driver {
             removeOnComplete: opts.removeOnComplete,
             removeOnFail: opts.removeOnFail,
         };
+        if (opts.repeat !== undefined) {
+            mapped.repeat = this.mapRepeat(opts.repeat);
+        }
+        return mapped;
+    }
+
+    /**
+     * Normaliza una RepeatSpec a la forma `repeat` de BullMQ:
+     * - string  → `{ pattern: cron }`
+     * - `{ every }` / `{ pattern }` → se reenvían tal cual.
+     */
+    private mapRepeat(repeat: RepeatSpec) {
+        if (typeof repeat === 'string') {
+            return { pattern: repeat };
+        }
+        return { ...repeat };
+    }
+
+    /**
+     * Valida la entrada de `enqueue` ANTES de tocar Redis, para evitar que
+     * entrada no confiable inunde la queue, almacene payloads gigantes o
+     * programe repeticiones malformadas. Lanza `QueueError` ante cualquier
+     * problema; no muta nada.
+     */
+    private validateEnqueue(name: string, data: unknown, opts?: JobOptions) {
+        if (!this.handlers.has(name)) {
+            throw new QueueError(`No handler registered for job "${name}"`, {
+                context: { jobName: name },
+            });
+        }
+
+        this.validatePayloadSize(name, data);
+
+        if (opts?.repeat !== undefined) {
+            this.validateRepeat(name, opts.repeat);
+        }
+    }
+
+    /** Rechaza payloads cuya serialización JSON excede el tope configurado. */
+    private validatePayloadSize(name: string, data: unknown) {
+        let serialized: string;
+        try {
+            serialized = JSON.stringify(data ?? null);
+        } catch (err) {
+            throw new QueueError(`Job "${name}" data is not serializable`, {
+                cause: err instanceof Error ? err : new Error(String(err)),
+                context: { jobName: name },
+            });
+        }
+
+        const size = Buffer.byteLength(serialized, 'utf8');
+        if (size > WorkerManager.MAX_PAYLOAD_BYTES) {
+            throw new QueueError(
+                `Job "${name}" payload too large: ${size} bytes (max ${WorkerManager.MAX_PAYLOAD_BYTES})`,
+                { context: { jobName: name, size, max: WorkerManager.MAX_PAYLOAD_BYTES } },
+            );
+        }
+    }
+
+    /** Rechaza specs de repetición vacías, intervalos no positivos o crons en blanco. */
+    private validateRepeat(name: string, repeat: RepeatSpec) {
+        if (typeof repeat === 'string') {
+            if (repeat.trim().length === 0) {
+                throw new QueueError(`Job "${name}" has an empty cron repeat pattern`, {
+                    context: { jobName: name },
+                });
+            }
+            return;
+        }
+
+        const hasEvery = 'every' in repeat;
+        const hasPattern = 'pattern' in repeat;
+        if (!hasEvery && !hasPattern) {
+            throw new QueueError(`Job "${name}" repeat spec must define "every" or "pattern"`, {
+                context: { jobName: name },
+            });
+        }
+
+        if (hasEvery && !(typeof repeat.every === 'number' && repeat.every > 0)) {
+            throw new QueueError(`Job "${name}" repeat "every" must be a positive number`, {
+                context: { jobName: name, every: repeat.every },
+            });
+        }
+
+        if (hasPattern && (typeof repeat.pattern !== 'string' || repeat.pattern.trim().length === 0)) {
+            throw new QueueError(`Job "${name}" repeat "pattern" must be a non-empty cron string`, {
+                context: { jobName: name },
+            });
+        }
+    }
+
+    /**
+     * Maneja el evento `failed` del worker. Loggea el fallo y, si el job agotó
+     * todos sus reintentos y `deadLetter` está activado, emite
+     * `worker:dead-letter` en el bus de eventos de la App.
+     */
+    private onFailed(job: BullJob | undefined, err: Error) {
+        this.app?.logger.error({ jobId: job?.id, jobName: job?.name, err }, 'Job failed');
+
+        if (!this.options.deadLetter || !job) return;
+
+        // BullMQ default attempts is 1 when unspecified.
+        //
+        // Assumed BullMQ `attemptsMade` semantics at the `failed` event: on a
+        // job's TERMINAL failure (all retries exhausted) BullMQ reports
+        // `attemptsMade == opts.attempts`, so `attemptsMade < maxAttempts`
+        // identifies a non-terminal failure with a retry still pending. This is
+        // verified against bullmq 5.78 (see test/dead-letter-attempts*.test.ts);
+        // a future bump that changes `attemptsMade` reporting will fail those
+        // tests loudly rather than silently skip dead-lettering.
+        const maxAttempts = job.opts?.attempts ?? 1;
+        if (job.attemptsMade < maxAttempts) return;
+
+        const payload: DeadLetterPayload = {
+            jobId: job.id,
+            name: job.name,
+            data: job.data,
+            failedReason: job.failedReason ?? err?.message,
+            attemptsMade: job.attemptsMade,
+        };
+        this.app?.events.emit('worker:dead-letter', payload);
+        this.app?.logger.warn(
+            { jobId: job.id, jobName: job.name, attemptsMade: job.attemptsMade },
+            'Job routed to dead-letter',
+        );
+    }
+
+    /**
+     * Construye el descriptor de un job, incluyendo el helper `result()` que
+     * espera el valor de retorno del handler vía `job.waitUntilFinished`.
+     */
+    private buildDescriptor<T, R>(job: BullJob, name: string, data: T): JobDescriptor<T, R> {
+        return {
+            id: job.id!,
+            name,
+            data,
+            // async so a post-stop getQueueEvents() throw surfaces as a rejected
+            // promise rather than a synchronous throw.
+            result: async (ttlMs?: number): Promise<R> => {
+                const queueEvents = this.getQueueEvents();
+                return job.waitUntilFinished(queueEvents, ttlMs) as Promise<R>;
+            },
+        };
+    }
+
+    /**
+     * Devuelve (creando perezosamente) una instancia compartida de QueueEvents
+     * usada para esperar resultados de jobs.
+     */
+    private getQueueEvents(): QueueEvents {
+        if (this.stopped) {
+            throw new QueueError('WorkerManager is stopped; cannot open QueueEvents', {
+                context: { queueName: this.options.queueName || 'iskra-jobs' },
+            });
+        }
+        if (!this.queueEvents) {
+            try {
+                this.queueEvents = new QueueEvents(this.options.queueName || 'iskra-jobs', {
+                    connection: this.parseConnection(),
+                });
+            } catch (err) {
+                throw new QueueError('Failed to initialize BullMQ QueueEvents', {
+                    cause: err instanceof Error ? err : new Error(String(err)),
+                    context: { queueName: this.options.queueName || 'iskra-jobs' },
+                });
+            }
+        }
+        return this.queueEvents;
     }
 }

package/src/types.ts

@@ -7,8 +7,26 @@ export interface WorkerManagerOptions {
     queueName?: string;
     /** Opciones por defecto para cada job */
     defaultJobOptions?: JobOptions;
+    /**
+     * Activa el ruteo a dead-letter: cuando un job agota todos sus reintentos
+     * se emite el evento `worker:dead-letter` en el bus de eventos de la App.
+     * Opt-in para no cambiar el comportamiento existente (default: false).
+     */
+    deadLetter?: boolean;
 }
 
+/**
+ * Especificación de repetición para jobs programados.
+ *
+ * - Un string se interpreta como un patrón cron (ej: '0 0 * * *').
+ * - `{ every: ms }` repite cada `ms` milisegundos.
+ * - `{ pattern: cron }` repite según el patrón cron, con opciones extra.
+ */
+export type RepeatSpec =
+    | string
+    | { every: number; limit?: number }
+    | { pattern: string; limit?: number; tz?: string };
+
 export interface JobOptions {
     /** Reintentos en caso de fallo */
     attempts?: number;
@@ -25,10 +43,48 @@ export interface JobOptions {
     removeOnComplete?: boolean | number;
     /** Eliminar el job de Redis al fallar */
     removeOnFail?: boolean | number;
+    /**
+     * Programa el job como repetible (cron o intervalo).
+     * Se reenvía a la opción `repeat` de BullMQ.
+     */
+    repeat?: RepeatSpec;
 }
 
-export interface JobData {
-    [key: string]: any;
+/**
+ * Handler de un job. Puede devolver un valor `R` que queda disponible como
+ * resultado del job (recuperable vía `job.waitUntilFinished`). Devolver `void`
+ * sigue siendo válido (R por defecto es `void`).
+ */
+export type JobHandler<T = unknown, R = void> = (job: {
+    id: string;
+    name: string;
+    data: T;
+    attemptsMade: number;
+}) => Promise<R>;
+
+/**
+ * Payload del evento `worker:dead-letter`, emitido cuando un job agota todos
+ * sus reintentos y `deadLetter` está activado.
+ */
+export interface DeadLetterPayload {
+    jobId: string | undefined;
+    name: string | undefined;
+    data: unknown;
+    failedReason: string | undefined;
+    attemptsMade: number;
 }
 
-export type JobHandler = (job: { id: string; name: string; data: any; attemptsMade: number }) => Promise<void>;
+/**
+ * Descriptor devuelto por `enqueue`/`schedule`. Además de los datos del job,
+ * expone `result()` para esperar el valor de retorno del handler.
+ */
+export interface JobDescriptor<T = unknown, R = unknown> {
+    id: string;
+    name: string;
+    data: T;
+    /**
+     * Espera a que el job termine y resuelve con el valor que devolvió el
+     * handler. Lanza si el job falló. Requiere una conexión a Redis viva.
+     */
+    result(ttlMs?: number): Promise<R>;
+}