@iskra-bun/worker-kit 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# @iskra-bun/worker-kit
+
+## 0.1.0
+
+### Minor Changes
+
+- Initial public release.

package/README.md

@@ -0,0 +1,31 @@
+# @iskra-bun/worker-kit
+
+Cola de jobs en segundo plano para Iskra basada en [BullMQ](https://docs.bullmq.io). Maneja handlers, reintentos, backoff y concurrencia.
+
+## Instalacion
+
+```bash
+bun add @iskra-bun/worker-kit @iskra-bun/core
+```
+
+Requiere un Redis accesible (BullMQ).
+
+## Uso rapido
+
+```typescript
+import { App } from '@iskra-bun/core'
+import { WorkerManager } from '@iskra-bun/worker-kit'
+
+const app = new App({ name: 'mi-worker' })
+app.register(new WorkerManager({ queue: 'mis-jobs', concurrency: 2 }))
+
+await app.start()
+```
+
+## Documentacion
+
+Guia completa: [docs/worker-kit.md](../../docs/worker-kit.md)
+
+## Licencia
+
+AGPL-3.0-or-later

package/dist/index.d.ts

@@ -0,0 +1,82 @@
+import { IskraError, Driver, App } from '@iskra-bun/core';
+
+interface WorkerManagerOptions {
+    /** URL de conexión a Redis (ej: 'redis://localhost:6379') */
+    connection: string | {
+        host: string;
+        port: number;
+        password?: string;
+        db?: number;
+    };
+    /** Cantidad de jobs que se procesan en paralelo (default: 1) */
+    concurrency?: number;
+    /** Nombre de la queue en Redis (default: 'iskra-jobs') */
+    queueName?: string;
+    /** Opciones por defecto para cada job */
+    defaultJobOptions?: JobOptions;
+}
+interface JobOptions {
+    /** Reintentos en caso de fallo */
+    attempts?: number;
+    /** Delay antes de procesar el job (ms) */
+    delay?: number;
+    /** Prioridad (menor = mayor prioridad) */
+    priority?: number;
+    /** Estrategia de backoff entre reintentos */
+    backoff?: {
+        type: 'fixed' | 'exponential';
+        delay: number;
+    };
+    /** Eliminar el job de Redis al completarse */
+    removeOnComplete?: boolean | number;
+    /** Eliminar el job de Redis al fallar */
+    removeOnFail?: boolean | number;
+}
+type JobHandler = (job: {
+    id: string;
+    name: string;
+    data: any;
+    attemptsMade: number;
+}) => Promise<void>;
+
+declare class QueueError extends IskraError {
+    constructor(message: string, options?: {
+        cause?: Error;
+        context?: Record<string, unknown>;
+    });
+}
+declare class JobError extends IskraError {
+    constructor(message: string, options?: {
+        cause?: Error;
+        context?: Record<string, unknown>;
+    });
+}
+
+declare class WorkerManager implements Driver {
+    name: string;
+    private app;
+    private handlers;
+    private queue;
+    private worker;
+    private options;
+    constructor(options: WorkerManagerOptions);
+    init(app: App): Promise<void>;
+    /**
+     * Registra un handler para un tipo de job.
+     */
+    register(jobName: string, handler: JobHandler): this;
+    /**
+     * Encola un job para ser procesado.
+     */
+    enqueue(name: string, data: any, opts?: JobOptions): Promise<{
+        id: string;
+        name: string;
+        data: any;
+    }>;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    private parseConnection;
+    private mapJobOptions;
+}
+
+export { JobError, type JobHandler, type JobOptions, QueueError, WorkerManager, type WorkerManagerOptions };

package/dist/index.js

@@ -0,0 +1,147 @@
+// src/index.ts
+import { Queue, Worker } from "bullmq";
+
+// src/errors.ts
+import { IskraError, ErrorCodes } from "@iskra-bun/core";
+var QueueError = class extends IskraError {
+  constructor(message, options) {
+    super(message, { code: ErrorCodes.QUEUE_ERROR, ...options });
+    this.name = "QueueError";
+  }
+};
+var JobError = class extends IskraError {
+  constructor(message, options) {
+    super(message, { code: ErrorCodes.JOB_ERROR, ...options });
+    this.name = "JobError";
+  }
+};
+
+// src/index.ts
+var WorkerManager = class {
+  name = "WorkerManager";
+  app = null;
+  handlers = /* @__PURE__ */ new Map();
+  queue = null;
+  worker = null;
+  options;
+  constructor(options) {
+    this.options = options;
+  }
+  async init(app) {
+    this.app = app;
+    const connection = this.parseConnection();
+    try {
+      this.queue = new Queue(this.options.queueName || "iskra-jobs", {
+        connection,
+        defaultJobOptions: this.mapJobOptions(this.options.defaultJobOptions)
+      });
+    } catch (err) {
+      throw new QueueError("Failed to initialize BullMQ queue", {
+        cause: err instanceof Error ? err : new Error(String(err)),
+        context: { queueName: this.options.queueName || "iskra-jobs" }
+      });
+    }
+  }
+  /**
+   * Registra un handler para un tipo de job.
+   */
+  register(jobName, handler) {
+    this.handlers.set(jobName, handler);
+    return this;
+  }
+  /**
+   * Encola un job para ser procesado.
+   */
+  async enqueue(name, data, opts) {
+    if (!this.queue) {
+      throw new QueueError("Queue not initialized. Did you call init()?", {
+        context: { jobName: name }
+      });
+    }
+    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 };
+  }
+  async start() {
+    const connection = this.parseConnection();
+    this.worker = new Worker(
+      this.options.queueName || "iskra-jobs",
+      async (job) => {
+        const handler = this.handlers.get(job.name);
+        if (!handler) {
+          this.app?.logger.warn({ jobName: job.name, jobId: job.id }, "No handler registered for job");
+          return;
+        }
+        try {
+          await handler({
+            id: job.id,
+            name: job.name,
+            data: job.data,
+            attemptsMade: job.attemptsMade
+          });
+        } catch (err) {
+          const jobErr = new JobError(`Job "${job.name}" failed`, {
+            cause: err instanceof Error ? err : new Error(String(err)),
+            context: { jobId: job.id, jobName: job.name, attemptsMade: job.attemptsMade }
+          });
+          this.app?.logger.error({ err: jobErr }, jobErr.message);
+          throw err;
+        }
+      },
+      {
+        connection,
+        concurrency: this.options.concurrency || 1
+      }
+    );
+    this.worker.on("completed", (job) => {
+      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.app?.logger.info({
+      queue: this.options.queueName || "iskra-jobs",
+      concurrency: this.options.concurrency || 1
+    }, "WorkerManager started");
+  }
+  async stop() {
+    const closePromises = [];
+    if (this.worker) {
+      closePromises.push(this.worker.close());
+    }
+    if (this.queue) {
+      closePromises.push(this.queue.close());
+    }
+    await Promise.all(closePromises);
+    this.app?.logger.info("WorkerManager stopped");
+  }
+  parseConnection() {
+    if (typeof this.options.connection === "string") {
+      const url = new URL(this.options.connection);
+      return {
+        host: url.hostname,
+        port: Number(url.port) || 6379,
+        password: url.password || void 0,
+        db: url.pathname ? Number(url.pathname.slice(1)) || 0 : 0
+      };
+    }
+    return this.options.connection;
+  }
+  mapJobOptions(opts) {
+    if (!opts) return void 0;
+    return {
+      attempts: opts.attempts,
+      delay: opts.delay,
+      priority: opts.priority,
+      backoff: opts.backoff,
+      removeOnComplete: opts.removeOnComplete,
+      removeOnFail: opts.removeOnFail
+    };
+  }
+};
+export {
+  JobError,
+  QueueError,
+  WorkerManager
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +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":[]}

package/package.json

@@ -0,0 +1,56 @@
+{
+    "name": "@iskra-bun/worker-kit",
+    "version": "0.1.0",
+    "description": "Cola de jobs en segundo plano para Iskra con BullMQ.",
+    "keywords": [
+        "iskra",
+        "bun",
+        "typescript",
+        "bullmq",
+        "jobs",
+        "queue",
+        "worker"
+    ],
+    "author": "Joan Lascano",
+    "license": "AGPL-3.0-or-later",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/fearful/iskra.git",
+        "directory": "packages/worker-kit"
+    },
+    "homepage": "https://github.com/fearful/iskra/tree/main/packages/worker-kit#readme",
+    "bugs": "https://github.com/fearful/iskra/issues",
+    "type": "module",
+    "main": "./dist/index.js",
+    "module": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+        ".": {
+            "source": "./src/index.ts",
+            "bun": "./src/index.ts",
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.js",
+            "default": "./dist/index.js"
+        }
+    },
+    "files": [
+        "dist",
+        "src",
+        "README.md",
+        "CHANGELOG.md"
+    ],
+    "publishConfig": {
+        "access": "public"
+    },
+    "scripts": {
+        "test": "bun test",
+        "build": "tsup --config ../../tsup.config.ts"
+    },
+    "dependencies": {
+        "@iskra-bun/core": "0.1.0",
+        "bullmq": "^5.0.0"
+    },
+    "devDependencies": {
+        "@types/node": "^22.10.2"
+    }
+}

package/src/errors.ts

@@ -0,0 +1,19 @@
+import { IskraError, ErrorCodes } from '@iskra-bun/core';
+
+// ─── Queue Error ─────────────────────────────────────────────────────────────
+
+export class QueueError extends IskraError {
+    constructor(message: string, options?: { cause?: Error; context?: Record<string, unknown> }) {
+        super(message, { code: ErrorCodes.QUEUE_ERROR, ...options });
+        this.name = 'QueueError';
+    }
+}
+
+// ─── Job Error ───────────────────────────────────────────────────────────────
+
+export class JobError extends IskraError {
+    constructor(message: string, options?: { cause?: Error; context?: Record<string, unknown> }) {
+        super(message, { code: ErrorCodes.JOB_ERROR, ...options });
+        this.name = 'JobError';
+    }
+}

package/src/index.ts

@@ -0,0 +1,148 @@
+import type { Driver, App } from '@iskra-bun/core';
+import { Queue, Worker, type Job as BullJob } from 'bullmq';
+import { QueueError, JobError } from './errors';
+import type { WorkerManagerOptions, JobOptions, JobHandler } from './types';
+
+export type { WorkerManagerOptions, JobOptions, JobHandler } from './types';
+export * from './errors';
+
+export class WorkerManager implements Driver {
+    name = 'WorkerManager';
+    private app: App | null = null;
+    private handlers: Map<string, JobHandler> = new Map();
+    private queue: Queue | null = null;
+    private worker: Worker | null = null;
+    private options: WorkerManagerOptions;
+
+    constructor(options: WorkerManagerOptions) {
+        this.options = options;
+    }
+
+    async init(app: App) {
+        this.app = app;
+
+        const connection = this.parseConnection();
+
+        try {
+            this.queue = new Queue(this.options.queueName || 'iskra-jobs', {
+                connection,
+                defaultJobOptions: this.mapJobOptions(this.options.defaultJobOptions),
+            });
+        } catch (err) {
+            throw new QueueError('Failed to initialize BullMQ queue', {
+                cause: err instanceof Error ? err : new Error(String(err)),
+                context: { queueName: this.options.queueName || 'iskra-jobs' },
+            });
+        }
+    }
+
+    /**
+     * Registra un handler para un tipo de job.
+     */
+    register(jobName: string, handler: JobHandler) {
+        this.handlers.set(jobName, handler);
+        return this;
+    }
+
+    /**
+     * Encola un job para ser procesado.
+     */
+    async enqueue(name: string, data: any, opts?: JobOptions) {
+        if (!this.queue) {
+            throw new QueueError('Queue not initialized. Did you call init()?', {
+                context: { jobName: name },
+            });
+        }
+
+        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 };
+    }
+
+    async start() {
+        const connection = this.parseConnection();
+
+        this.worker = new Worker(
+            this.options.queueName || 'iskra-jobs',
+            async (job: BullJob) => {
+                const handler = this.handlers.get(job.name);
+                if (!handler) {
+                    this.app?.logger.warn({ jobName: job.name, jobId: job.id }, 'No handler registered for job');
+                    return;
+                }
+
+                try {
+                    await handler({
+                        id: job.id!,
+                        name: job.name,
+                        data: job.data,
+                        attemptsMade: job.attemptsMade,
+                    });
+                } catch (err) {
+                    const jobErr = new JobError(`Job "${job.name}" failed`, {
+                        cause: err instanceof Error ? err : new Error(String(err)),
+                        context: { jobId: job.id, jobName: job.name, attemptsMade: job.attemptsMade },
+                    });
+                    this.app?.logger.error({ err: jobErr }, jobErr.message);
+                    throw err; // Re-throw para que BullMQ maneje el retry
+                }
+            },
+            {
+                connection,
+                concurrency: this.options.concurrency || 1,
+            },
+        );
+
+        this.worker.on('completed', (job) => {
+            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.app?.logger.info({
+            queue: this.options.queueName || 'iskra-jobs',
+            concurrency: this.options.concurrency || 1,
+        }, 'WorkerManager started');
+    }
+
+    async stop() {
+        const closePromises: Promise<void>[] = [];
+
+        if (this.worker) {
+            closePromises.push(this.worker.close());
+        }
+        if (this.queue) {
+            closePromises.push(this.queue.close());
+        }
+
+        await Promise.all(closePromises);
+        this.app?.logger.info('WorkerManager stopped');
+    }
+
+    private parseConnection() {
+        if (typeof this.options.connection === 'string') {
+            const url = new URL(this.options.connection);
+            return {
+                host: url.hostname,
+                port: Number(url.port) || 6379,
+                password: url.password || undefined,
+                db: url.pathname ? Number(url.pathname.slice(1)) || 0 : 0,
+            };
+        }
+        return this.options.connection;
+    }
+
+    private mapJobOptions(opts?: JobOptions) {
+        if (!opts) return undefined;
+        return {
+            attempts: opts.attempts,
+            delay: opts.delay,
+            priority: opts.priority,
+            backoff: opts.backoff,
+            removeOnComplete: opts.removeOnComplete,
+            removeOnFail: opts.removeOnFail,
+        };
+    }
+}

package/src/types.ts

@@ -0,0 +1,34 @@
+export interface WorkerManagerOptions {
+    /** URL de conexión a Redis (ej: 'redis://localhost:6379') */
+    connection: string | { host: string; port: number; password?: string; db?: number };
+    /** Cantidad de jobs que se procesan en paralelo (default: 1) */
+    concurrency?: number;
+    /** Nombre de la queue en Redis (default: 'iskra-jobs') */
+    queueName?: string;
+    /** Opciones por defecto para cada job */
+    defaultJobOptions?: JobOptions;
+}
+
+export interface JobOptions {
+    /** Reintentos en caso de fallo */
+    attempts?: number;
+    /** Delay antes de procesar el job (ms) */
+    delay?: number;
+    /** Prioridad (menor = mayor prioridad) */
+    priority?: number;
+    /** Estrategia de backoff entre reintentos */
+    backoff?: {
+        type: 'fixed' | 'exponential';
+        delay: number;
+    };
+    /** Eliminar el job de Redis al completarse */
+    removeOnComplete?: boolean | number;
+    /** Eliminar el job de Redis al fallar */
+    removeOnFail?: boolean | number;
+}
+
+export interface JobData {
+    [key: string]: any;
+}
+
+export type JobHandler = (job: { id: string; name: string; data: any; attemptsMade: number }) => Promise<void>;