@igniter-js/jobs 0.1.0

package/dist/index.js

@@ -0,0 +1,1137 @@
+'use strict';
+
+var core = require('@igniter-js/core');
+
+// src/errors/igniter-jobs.error.ts
+var IGNITER_JOBS_ERROR_CODES = {
+  // Configuration errors
+  JOBS_ADAPTER_REQUIRED: "JOBS_ADAPTER_REQUIRED",
+  JOBS_CONTEXT_REQUIRED: "JOBS_CONTEXT_REQUIRED",
+  JOBS_QUEUE_REQUIRED: "JOBS_QUEUE_REQUIRED",
+  JOBS_CONFIGURATION_INVALID: "JOBS_CONFIGURATION_INVALID",
+  // Queue errors
+  JOBS_QUEUE_NOT_FOUND: "JOBS_QUEUE_NOT_FOUND",
+  JOBS_QUEUE_ALREADY_EXISTS: "JOBS_QUEUE_ALREADY_EXISTS",
+  JOBS_QUEUE_NAME_INVALID: "JOBS_QUEUE_NAME_INVALID",
+  JOBS_QUEUE_PAUSE_FAILED: "JOBS_QUEUE_PAUSE_FAILED",
+  JOBS_QUEUE_RESUME_FAILED: "JOBS_QUEUE_RESUME_FAILED",
+  JOBS_QUEUE_DRAIN_FAILED: "JOBS_QUEUE_DRAIN_FAILED",
+  JOBS_QUEUE_CLEAN_FAILED: "JOBS_QUEUE_CLEAN_FAILED",
+  JOBS_QUEUE_OBLITERATE_FAILED: "JOBS_QUEUE_OBLITERATE_FAILED",
+  // Job definition errors
+  JOBS_JOB_NOT_FOUND: "JOBS_JOB_NOT_FOUND",
+  JOBS_JOB_ALREADY_EXISTS: "JOBS_JOB_ALREADY_EXISTS",
+  JOBS_JOB_NAME_INVALID: "JOBS_JOB_NAME_INVALID",
+  JOBS_JOB_HANDLER_REQUIRED: "JOBS_JOB_HANDLER_REQUIRED",
+  // Cron errors
+  JOBS_CRON_NOT_FOUND: "JOBS_CRON_NOT_FOUND",
+  JOBS_CRON_ALREADY_EXISTS: "JOBS_CRON_ALREADY_EXISTS",
+  JOBS_CRON_EXPRESSION_INVALID: "JOBS_CRON_EXPRESSION_INVALID",
+  JOBS_CRON_HANDLER_REQUIRED: "JOBS_CRON_HANDLER_REQUIRED",
+  // Dispatch errors
+  JOBS_DISPATCH_FAILED: "JOBS_DISPATCH_FAILED",
+  JOBS_SCHEDULE_FAILED: "JOBS_SCHEDULE_FAILED",
+  JOBS_INPUT_REQUIRED: "JOBS_INPUT_REQUIRED",
+  JOBS_INPUT_VALIDATION_FAILED: "JOBS_INPUT_VALIDATION_FAILED",
+  // Scope errors
+  JOBS_SCOPE_REQUIRED: "JOBS_SCOPE_REQUIRED",
+  JOBS_SCOPE_ALREADY_DEFINED: "JOBS_SCOPE_ALREADY_DEFINED",
+  JOBS_SCOPE_INVALID: "JOBS_SCOPE_INVALID",
+  // Actor errors
+  JOBS_ACTOR_ALREADY_DEFINED: "JOBS_ACTOR_ALREADY_DEFINED",
+  JOBS_ACTOR_INVALID: "JOBS_ACTOR_INVALID",
+  // Job management errors
+  JOBS_GET_FAILED: "JOBS_GET_FAILED",
+  JOBS_RETRY_FAILED: "JOBS_RETRY_FAILED",
+  JOBS_REMOVE_FAILED: "JOBS_REMOVE_FAILED",
+  JOBS_PROMOTE_FAILED: "JOBS_PROMOTE_FAILED",
+  JOBS_MOVE_FAILED: "JOBS_MOVE_FAILED",
+  JOBS_STATE_FAILED: "JOBS_STATE_FAILED",
+  JOBS_PROGRESS_FAILED: "JOBS_PROGRESS_FAILED",
+  JOBS_LOGS_FAILED: "JOBS_LOGS_FAILED",
+  // Worker errors
+  JOBS_WORKER_CREATE_FAILED: "JOBS_WORKER_CREATE_FAILED",
+  JOBS_WORKER_START_FAILED: "JOBS_WORKER_START_FAILED",
+  JOBS_WORKER_STOP_FAILED: "JOBS_WORKER_STOP_FAILED",
+  JOBS_WORKER_NOT_FOUND: "JOBS_WORKER_NOT_FOUND",
+  JOBS_WORKER_ALREADY_RUNNING: "JOBS_WORKER_ALREADY_RUNNING",
+  // Event/Subscribe errors
+  JOBS_SUBSCRIBE_FAILED: "JOBS_SUBSCRIBE_FAILED",
+  JOBS_UNSUBSCRIBE_FAILED: "JOBS_UNSUBSCRIBE_FAILED",
+  JOBS_EVENT_EMIT_FAILED: "JOBS_EVENT_EMIT_FAILED",
+  // Search errors
+  JOBS_SEARCH_FAILED: "JOBS_SEARCH_FAILED",
+  JOBS_SEARCH_INVALID_TARGET: "JOBS_SEARCH_INVALID_TARGET",
+  // Shutdown errors
+  JOBS_SHUTDOWN_FAILED: "JOBS_SHUTDOWN_FAILED",
+  // Handler errors
+  JOBS_HANDLER_FAILED: "JOBS_HANDLER_FAILED",
+  JOBS_HANDLER_TIMEOUT: "JOBS_HANDLER_TIMEOUT"
+};
+var IgniterJobsError = class _IgniterJobsError extends core.IgniterError {
+  constructor(options) {
+    super({
+      code: options.code,
+      message: options.message,
+      statusCode: options.statusCode ?? 500,
+      causer: "@igniter-js/jobs",
+      cause: options.cause,
+      details: options.details,
+      logger: options.logger
+    });
+    this.code = options.code;
+    this.details = options.details;
+    this.name = "IgniterJobsError";
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, _IgniterJobsError);
+    }
+  }
+  /**
+   * Convert error to a plain object for serialization.
+   */
+  toJSON() {
+    return {
+      name: this.name,
+      code: this.code,
+      message: this.message,
+      statusCode: this.statusCode,
+      details: this.details,
+      stack: this.stack
+    };
+  }
+};
+
+// src/builders/igniter-worker.builder.ts
+var IgniterWorkerBuilder = class {
+  constructor(adapter, jobHandler, availableQueues) {
+    this.adapter = adapter;
+    this.jobHandler = jobHandler;
+    this.availableQueues = availableQueues;
+    this.state = {
+      queues: [],
+      concurrency: 1
+    };
+  }
+  /**
+   * Specify which queues this worker should process.
+   * If not called, worker processes all queues.
+   *
+   * @param queues - Queue names to process
+   * @returns The builder for chaining
+   *
+   * @example
+   * ```typescript
+   * .forQueues('email', 'payment')
+   * ```
+   */
+  forQueues(...queues) {
+    for (const queue of queues) {
+      if (!this.availableQueues.includes(queue)) {
+        throw new IgniterJobsError({
+          code: "JOBS_QUEUE_NOT_FOUND",
+          message: `Queue "${queue}" is not registered. Available queues: ${this.availableQueues.join(", ")}`,
+          statusCode: 400,
+          details: { queue, availableQueues: this.availableQueues }
+        });
+      }
+    }
+    this.state.queues = queues;
+    return this;
+  }
+  /**
+   * Set the concurrency level (jobs processed in parallel per queue).
+   *
+   * @param concurrency - Number of parallel jobs
+   * @returns The builder for chaining
+   *
+   * @example
+   * ```typescript
+   * .withConcurrency(10)
+   * ```
+   */
+  withConcurrency(concurrency) {
+    if (concurrency < 1) {
+      throw new IgniterJobsError({
+        code: "JOBS_CONFIGURATION_INVALID",
+        message: "Concurrency must be at least 1",
+        statusCode: 400,
+        details: { concurrency }
+      });
+    }
+    this.state.concurrency = concurrency;
+    return this;
+  }
+  /**
+   * Set the lock duration in milliseconds.
+   * Jobs are locked for this duration while being processed.
+   *
+   * @param duration - Lock duration in milliseconds
+   * @returns The builder for chaining
+   *
+   * @example
+   * ```typescript
+   * .withLockDuration(30000) // 30 seconds
+   * ```
+   */
+  withLockDuration(duration) {
+    if (duration < 1e3) {
+      throw new IgniterJobsError({
+        code: "JOBS_CONFIGURATION_INVALID",
+        message: "Lock duration must be at least 1000ms",
+        statusCode: 400,
+        details: { duration }
+      });
+    }
+    this.state.lockDuration = duration;
+    return this;
+  }
+  /**
+   * Configure rate limiting for the worker.
+   *
+   * @param config - Rate limiter configuration
+   * @returns The builder for chaining
+   *
+   * @example
+   * ```typescript
+   * .withLimiter({ max: 100, duration: 60000 }) // 100 jobs per minute
+   * ```
+   */
+  withLimiter(config) {
+    if (config.max < 1) {
+      throw new IgniterJobsError({
+        code: "JOBS_CONFIGURATION_INVALID",
+        message: "Limiter max must be at least 1",
+        statusCode: 400,
+        details: { max: config.max }
+      });
+    }
+    if (config.duration < 1) {
+      throw new IgniterJobsError({
+        code: "JOBS_CONFIGURATION_INVALID",
+        message: "Limiter duration must be at least 1ms",
+        statusCode: 400,
+        details: { duration: config.duration }
+      });
+    }
+    this.state.limiter = config;
+    return this;
+  }
+  /**
+   * Set a callback to be called when the worker becomes idle.
+   *
+   * @param callback - Idle callback
+   * @returns The builder for chaining
+   *
+   * @example
+   * ```typescript
+   * .onIdle(() => console.log('Worker is idle'))
+   * ```
+   */
+  onIdle(callback) {
+    this.state.onIdle = callback;
+    return this;
+  }
+  /**
+   * Start the worker.
+   *
+   * @returns Worker handle for management
+   *
+   * @example
+   * ```typescript
+   * const worker = await jobs.worker
+   *   .create()
+   *   .forQueues('email')
+   *   .start()
+   *
+   * // Later
+   * await worker.pause()
+   * await worker.close()
+   * ```
+   */
+  async start() {
+    const queuesToProcess = this.state.queues.length > 0 ? this.state.queues : this.availableQueues;
+    try {
+      const handle = await this.adapter.createWorker(
+        {
+          queues: queuesToProcess,
+          concurrency: this.state.concurrency,
+          lockDuration: this.state.lockDuration,
+          limiter: this.state.limiter,
+          onIdle: this.state.onIdle
+        },
+        this.jobHandler
+      );
+      return {
+        id: handle.id,
+        pause: () => handle.pause(),
+        resume: () => handle.resume(),
+        close: () => handle.close(),
+        isRunning: () => handle.isRunning(),
+        isPaused: () => handle.isPaused(),
+        getMetrics: () => handle.getMetrics()
+      };
+    } catch (error) {
+      throw new IgniterJobsError({
+        code: "JOBS_WORKER_START_FAILED",
+        message: "Failed to start worker",
+        statusCode: 500,
+        cause: error instanceof Error ? error : void 0,
+        details: { queues: queuesToProcess }
+      });
+    }
+  }
+};
+
+// src/core/igniter-jobs.ts
+var IGNITER_JOBS_PREFIX = "igniter:jobs";
+function getFullQueueName(queueName) {
+  return `${IGNITER_JOBS_PREFIX}:${queueName}`;
+}
+var IgniterJobsRuntime = class {
+  constructor(config) {
+    this.config = config;
+    this.queueNames = Object.keys(config.queues);
+    return this.createProxy();
+  }
+  /**
+   * Create the main proxy that provides queue access and global methods.
+   */
+  createProxy() {
+    const self = this;
+    return new Proxy({}, {
+      get(_, prop) {
+        if (prop === "subscribe") {
+          return self.createGlobalSubscribe();
+        }
+        if (prop === "search") {
+          return self.createSearch();
+        }
+        if (prop === "worker") {
+          return self.createWorkerBuilder();
+        }
+        if (prop === "shutdown") {
+          return () => self.shutdown();
+        }
+        if (self.queueNames.includes(prop)) {
+          return self.createQueueProxy(prop);
+        }
+        return void 0;
+      },
+      has(_, prop) {
+        return ["subscribe", "search", "worker", "shutdown", ...self.queueNames].includes(prop);
+      },
+      ownKeys() {
+        return ["subscribe", "search", "worker", "shutdown", ...self.queueNames];
+      },
+      getOwnPropertyDescriptor(_, prop) {
+        if (["subscribe", "search", "worker", "shutdown", ...self.queueNames].includes(prop)) {
+          return { configurable: true, enumerable: true };
+        }
+        return void 0;
+      }
+    });
+  }
+  /**
+   * Create a proxy for a specific queue.
+   */
+  createQueueProxy(queueName) {
+    const self = this;
+    const queueConfig = this.config.queues[queueName];
+    const jobNames = Object.keys(queueConfig.jobs);
+    return new Proxy({}, {
+      get(_, prop) {
+        if (prop === "subscribe") {
+          return self.createQueueSubscribe(queueName);
+        }
+        if (prop === "list") {
+          return (options) => self.listQueueJobs(queueName, options);
+        }
+        if (prop === "get") {
+          return () => self.createQueueManagement(queueName);
+        }
+        if (jobNames.includes(prop)) {
+          return self.createJobProxy(queueName, prop);
+        }
+        return void 0;
+      }
+    });
+  }
+  /**
+   * Create a proxy for a specific job.
+   */
+  createJobProxy(queueName, jobName) {
+    const self = this;
+    return {
+      dispatch: (input, options) => self.dispatchJob(queueName, jobName, input, options),
+      schedule: (params) => self.scheduleJob(queueName, jobName, params),
+      get: (jobId) => self.createJobManagement(queueName, jobId),
+      many: (jobIds) => self.createJobBatchManagement(queueName, jobIds),
+      pause: () => self.pauseJobType(queueName, jobName),
+      resume: () => self.resumeJobType(queueName, jobName),
+      subscribe: (handler) => self.subscribeToJob(queueName, jobName, handler)
+    };
+  }
+  /**
+   * Dispatch a job.
+   */
+  async dispatchJob(queueName, jobName, input, options) {
+    const queueConfig = this.config.queues[queueName];
+    const jobDef = queueConfig.jobs[jobName];
+    if (jobDef.input) {
+      try {
+        const result = await jobDef.input["~standard"].validate(input);
+        if (result.issues) {
+          throw new IgniterJobsError({
+            code: "JOBS_INPUT_VALIDATION_FAILED",
+            message: `Input validation failed for job "${jobName}"`,
+            statusCode: 400,
+            details: { issues: result.issues }
+          });
+        }
+        input = result.value;
+      } catch (error) {
+        if (error instanceof IgniterJobsError) throw error;
+        if (typeof jobDef.input.parse === "function") {
+          input = jobDef.input.parse(input);
+        }
+      }
+    }
+    if (this.config.scope?.options?.required && !options?.scope) {
+      throw new IgniterJobsError({
+        code: "JOBS_SCOPE_REQUIRED",
+        message: `Scope "${this.config.scope.key}" is required for job dispatch`,
+        statusCode: 400,
+        details: { queue: queueName, job: jobName }
+      });
+    }
+    const params = {
+      queue: getFullQueueName(queueName),
+      name: jobName,
+      data: input,
+      jobId: options?.jobId,
+      delay: options?.delay,
+      priority: options?.priority ?? jobDef.priority,
+      attempts: jobDef.retry?.attempts ?? this.config.defaults?.retry?.attempts ?? 3,
+      backoff: jobDef.retry?.backoff ?? this.config.defaults?.retry?.backoff,
+      removeOnComplete: jobDef.removeOnComplete ?? this.config.defaults?.removeOnComplete,
+      removeOnFail: jobDef.removeOnFail ?? this.config.defaults?.removeOnFail,
+      scope: options?.scope,
+      actor: options?.actor
+    };
+    try {
+      const jobId = await this.config.adapter.dispatch(params);
+      if (this.config.telemetry) {
+      }
+      return jobId;
+    } catch (error) {
+      throw new IgniterJobsError({
+        code: "JOBS_DISPATCH_FAILED",
+        message: `Failed to dispatch job "${jobName}" to queue "${queueName}"`,
+        statusCode: 500,
+        cause: error instanceof Error ? error : void 0,
+        details: { queue: queueName, job: jobName }
+      });
+    }
+  }
+  /**
+   * Schedule a job for future execution.
+   */
+  async scheduleJob(queueName, jobName, params) {
+    const queueConfig = this.config.queues[queueName];
+    const jobDef = queueConfig.jobs[jobName];
+    let validatedInput = params.input;
+    if (jobDef.input) {
+      try {
+        const result = await jobDef.input["~standard"].validate(params.input);
+        if (result.issues) {
+          throw new IgniterJobsError({
+            code: "JOBS_INPUT_VALIDATION_FAILED",
+            message: `Input validation failed for job "${jobName}"`,
+            statusCode: 400,
+            details: { issues: result.issues }
+          });
+        }
+        validatedInput = result.value;
+      } catch (error) {
+        if (error instanceof IgniterJobsError) throw error;
+        if (typeof jobDef.input.parse === "function") {
+          validatedInput = jobDef.input.parse(params.input);
+        }
+      }
+    }
+    const scheduleParams = {
+      queue: getFullQueueName(queueName),
+      name: jobName,
+      data: validatedInput,
+      jobId: params.jobId,
+      at: params.at,
+      cron: params.cron,
+      every: params.every,
+      timezone: params.timezone,
+      attempts: jobDef.retry?.attempts ?? this.config.defaults?.retry?.attempts ?? 3,
+      backoff: jobDef.retry?.backoff ?? this.config.defaults?.retry?.backoff,
+      removeOnComplete: jobDef.removeOnComplete ?? this.config.defaults?.removeOnComplete,
+      removeOnFail: jobDef.removeOnFail ?? this.config.defaults?.removeOnFail,
+      scope: params.scope,
+      actor: params.actor
+    };
+    try {
+      return await this.config.adapter.schedule(scheduleParams);
+    } catch (error) {
+      throw new IgniterJobsError({
+        code: "JOBS_SCHEDULE_FAILED",
+        message: `Failed to schedule job "${jobName}" in queue "${queueName}"`,
+        statusCode: 500,
+        cause: error instanceof Error ? error : void 0,
+        details: { queue: queueName, job: jobName }
+      });
+    }
+  }
+  /**
+   * Create job management methods.
+   */
+  createJobManagement(queueName, jobId) {
+    const adapter = this.config.adapter;
+    const fullQueueName = getFullQueueName(queueName);
+    return {
+      retrieve: () => adapter.getJob(fullQueueName, jobId),
+      retry: () => adapter.retryJob(fullQueueName, jobId),
+      remove: () => adapter.removeJob(fullQueueName, jobId),
+      state: () => adapter.getJobState(fullQueueName, jobId),
+      progress: () => adapter.getJobProgress(fullQueueName, jobId),
+      logs: () => adapter.getJobLogs(fullQueueName, jobId),
+      promote: () => adapter.promoteJob(fullQueueName, jobId),
+      move: (state, reason) => adapter.moveJob(fullQueueName, jobId, state, reason)
+    };
+  }
+  /**
+   * Create batch job management methods.
+   */
+  createJobBatchManagement(queueName, jobIds) {
+    const adapter = this.config.adapter;
+    const fullQueueName = getFullQueueName(queueName);
+    return {
+      retry: () => adapter.retryJobs(fullQueueName, jobIds),
+      remove: () => adapter.removeJobs(fullQueueName, jobIds)
+    };
+  }
+  /**
+   * Create queue management methods.
+   */
+  createQueueManagement(queueName) {
+    const adapter = this.config.adapter;
+    const fullQueueName = getFullQueueName(queueName);
+    return {
+      retrieve: () => adapter.getQueue(fullQueueName),
+      pause: () => adapter.pauseQueue(fullQueueName),
+      resume: () => adapter.resumeQueue(fullQueueName),
+      drain: () => adapter.drainQueue(fullQueueName),
+      clean: (options) => adapter.cleanQueue(fullQueueName, {
+        status: options.status,
+        olderThan: options.olderThan,
+        limit: options.limit
+      }),
+      obliterate: (options) => adapter.obliterateQueue(fullQueueName, options),
+      retryAll: () => adapter.retryAllFailed(fullQueueName)
+    };
+  }
+  /**
+   * Pause a specific job type.
+   */
+  async pauseJobType(queueName, jobName) {
+    const fullQueueName = getFullQueueName(queueName);
+    await this.config.adapter.pauseJobType(fullQueueName, jobName);
+  }
+  /**
+   * Resume a specific job type.
+   */
+  async resumeJobType(queueName, jobName) {
+    const fullQueueName = getFullQueueName(queueName);
+    await this.config.adapter.resumeJobType(fullQueueName, jobName);
+  }
+  /**
+   * Subscribe to events for a specific job.
+   */
+  async subscribeToJob(queueName, jobName, handler) {
+    const pattern = `${queueName}:${jobName}:*`;
+    return this.config.adapter.subscribe(pattern, handler);
+  }
+  /**
+   * Create queue-level subscribe.
+   */
+  createQueueSubscribe(queueName) {
+    return async (handler) => {
+      const pattern = `${queueName}:*`;
+      return this.config.adapter.subscribe(pattern, handler);
+    };
+  }
+  /**
+   * List jobs in a queue.
+   */
+  async listQueueJobs(queueName, options) {
+    const fullQueueName = getFullQueueName(queueName);
+    return this.config.adapter.listJobs(fullQueueName, {
+      status: options?.status,
+      end: options?.limit
+    });
+  }
+  /**
+   * Create global subscribe.
+   */
+  createGlobalSubscribe() {
+    return async (handler) => {
+      return this.config.adapter.subscribe("*", handler);
+    };
+  }
+  /**
+   * Create search function.
+   */
+  createSearch() {
+    const adapter = this.config.adapter;
+    return async (target, filter) => {
+      switch (target) {
+        case "queues":
+          return adapter.searchQueues(filter || {});
+        case "jobs":
+          return adapter.searchJobs(filter || {});
+        case "workers":
+          return [];
+        default:
+          throw new IgniterJobsError({
+            code: "JOBS_SEARCH_INVALID_TARGET",
+            message: `Invalid search target "${target}". Use "queues", "jobs", or "workers".`,
+            statusCode: 400
+          });
+      }
+    };
+  }
+  /**
+   * Create worker builder.
+   */
+  createWorkerBuilder() {
+    return {
+      create: () => new IgniterWorkerBuilder(
+        this.config.adapter,
+        this.createJobHandler(),
+        this.queueNames.map((q) => getFullQueueName(q))
+      )
+    };
+  }
+  /**
+   * Create the job handler function for workers.
+   */
+  createJobHandler() {
+    const self = this;
+    return async (job) => {
+      const queueName = job.queue.replace(`${IGNITER_JOBS_PREFIX}:`, "");
+      const queueConfig = self.config.queues[queueName];
+      if (!queueConfig) {
+        throw new IgniterJobsError({
+          code: "JOBS_QUEUE_NOT_FOUND",
+          message: `Queue "${queueName}" not found`,
+          statusCode: 404
+        });
+      }
+      const jobDef = queueConfig.jobs[job.name];
+      if (!jobDef) {
+        throw new IgniterJobsError({
+          code: "JOBS_JOB_NOT_FOUND",
+          message: `Job "${job.name}" not found in queue "${queueName}"`,
+          statusCode: 404
+        });
+      }
+      const context = await self.config.context();
+      const ctx = {
+        input: job.data,
+        context,
+        job: {
+          id: job.id,
+          name: job.name,
+          queue: queueName,
+          timestamp: job.timestamp
+        },
+        attempt: job.attempt,
+        scope: job.scope,
+        actor: job.actor,
+        log: job.log,
+        updateProgress: job.updateProgress
+      };
+      try {
+        const result = await jobDef.handler(ctx);
+        if (jobDef.onComplete) {
+          await jobDef.onComplete(ctx, result);
+        }
+        return result;
+      } catch (error) {
+        if (jobDef.onFailure) {
+          await jobDef.onFailure(ctx, error instanceof Error ? error : new Error(String(error)));
+        }
+        throw error;
+      }
+    };
+  }
+  /**
+   * Shutdown the jobs instance.
+   */
+  async shutdown() {
+    try {
+      await this.config.adapter.shutdown();
+    } catch (error) {
+      throw new IgniterJobsError({
+        code: "JOBS_SHUTDOWN_FAILED",
+        message: "Failed to shutdown jobs instance",
+        statusCode: 500,
+        cause: error instanceof Error ? error : void 0
+      });
+    }
+  }
+};
+
+// src/builders/igniter-jobs.builder.ts
+var IgniterJobsBuilder = class _IgniterJobsBuilder {
+  constructor(state) {
+    this.state = state;
+  }
+  /**
+   * Create a new IgniterJobs builder.
+   *
+   * @returns A new IgniterJobsBuilder instance
+   *
+   * @example
+   * ```typescript
+   * const jobs = IgniterJobs.create<AppContext>()
+   *   .withAdapter(...)
+   *   .build()
+   * ```
+   */
+  static create() {
+    return new _IgniterJobsBuilder({
+      queues: {}
+    });
+  }
+  /**
+   * Configure the queue adapter (required).
+   *
+   * @param adapter - The queue adapter (e.g., BullMQAdapter)
+   * @returns The builder with adapter configured
+   *
+   * @example
+   * ```typescript
+   * .withAdapter(BullMQAdapter.create({ redis }))
+   * ```
+   */
+  withAdapter(adapter) {
+    return new _IgniterJobsBuilder({
+      ...this.state,
+      adapter
+    });
+  }
+  /**
+   * Configure the application context provider (required).
+   * This function is called for each job to provide the application context.
+   *
+   * @param contextFn - Function that returns the application context
+   * @returns The builder with context configured
+   *
+   * @example
+   * ```typescript
+   * .withContext(() => ({
+   *   db: prisma,
+   *   mailer: mailerService,
+   *   cache: redis,
+   * }))
+   * ```
+   */
+  withContext(contextFn) {
+    return new _IgniterJobsBuilder({
+      ...this.state,
+      context: contextFn
+    });
+  }
+  /**
+   * Add a queue to the jobs instance.
+   *
+   * @param queue - Queue configuration from IgniterQueue.create().build()
+   * @returns The builder with the queue added
+   *
+   * @example
+   * ```typescript
+   * const emailQueue = IgniterQueue.create<AppContext>('email')
+   *   .addJob('sendWelcome', { ... })
+   *   .build()
+   *
+   * const jobs = IgniterJobs.create<AppContext>()
+   *   .addQueue(emailQueue)
+   *   .build()
+   * ```
+   */
+  addQueue(queue) {
+    const queueName = queue.name;
+    if (queueName in this.state.queues) {
+      throw new IgniterJobsError({
+        code: "JOBS_QUEUE_ALREADY_EXISTS",
+        message: `Queue "${queueName}" has already been added`,
+        statusCode: 400,
+        details: { queue: queueName }
+      });
+    }
+    return new _IgniterJobsBuilder({
+      ...this.state,
+      queues: {
+        ...this.state.queues,
+        [queueName]: queue
+      }
+    });
+  }
+  /**
+   * Add a scope for multi-tenancy (only one scope allowed).
+   * Scopes are used to isolate jobs by organization, tenant, etc.
+   *
+   * @param key - Scope key (e.g., 'organization', 'tenant')
+   * @param options - Optional scope configuration
+   * @returns The builder with scope configured
+   *
+   * @example
+   * ```typescript
+   * .addScope('organization', { required: true })
+   * ```
+   */
+  addScope(key, options) {
+    if (this.state.scope) {
+      throw new IgniterJobsError({
+        code: "JOBS_SCOPE_ALREADY_DEFINED",
+        message: `Scope "${this.state.scope.key}" is already defined. Only one scope is allowed.`,
+        statusCode: 400,
+        details: { existingScope: this.state.scope.key, newScope: key }
+      });
+    }
+    return new _IgniterJobsBuilder({
+      ...this.state,
+      scope: { key, options }
+    });
+  }
+  /**
+   * Add an actor for auditing (only one actor type allowed).
+   * Actors are used to track who initiated jobs.
+   *
+   * @param key - Actor key (e.g., 'user', 'system')
+   * @param options - Optional actor configuration
+   * @returns The builder with actor configured
+   *
+   * @example
+   * ```typescript
+   * .addActor('user', { description: 'The user who initiated the job' })
+   * ```
+   */
+  addActor(key, options) {
+    if (this.state.actor) {
+      throw new IgniterJobsError({
+        code: "JOBS_ACTOR_ALREADY_DEFINED",
+        message: `Actor "${this.state.actor.key}" is already defined. Only one actor is allowed.`,
+        statusCode: 400,
+        details: { existingActor: this.state.actor.key, newActor: key }
+      });
+    }
+    return new _IgniterJobsBuilder({
+      ...this.state,
+      actor: { key, options }
+    });
+  }
+  /**
+   * Configure telemetry for observability (optional).
+   *
+   * @param telemetry - IgniterTelemetry instance
+   * @returns The builder with telemetry configured
+   *
+   * @example
+   * ```typescript
+   * .withTelemetry(telemetry)
+   * ```
+   */
+  withTelemetry(telemetry) {
+    return new _IgniterJobsBuilder({
+      ...this.state,
+      telemetry
+    });
+  }
+  /**
+   * Configure a custom logger (optional).
+   *
+   * @param logger - Logger instance
+   * @returns The builder with logger configured
+   *
+   * @example
+   * ```typescript
+   * .withLogger(customLogger)
+   * ```
+   */
+  withLogger(logger) {
+    return new _IgniterJobsBuilder({
+      ...this.state,
+      logger
+    });
+  }
+  /**
+   * Configure default job options applied to all jobs.
+   *
+   * @param defaults - Default job configuration
+   * @returns The builder with defaults configured
+   *
+   * @example
+   * ```typescript
+   * .withDefaults({
+   *   retry: { attempts: 3, backoff: { type: 'exponential', delay: 1000 } },
+   *   timeout: 30000,
+   *   removeOnComplete: { count: 1000 },
+   * })
+   * ```
+   */
+  withDefaults(defaults) {
+    return new _IgniterJobsBuilder({
+      ...this.state,
+      defaults
+    });
+  }
+  /**
+   * Build the IgniterJobs instance.
+   * Validates configuration and returns a fully typed jobs instance.
+   *
+   * @returns The IgniterJobs instance with proxy for typed access
+   *
+   * @throws {IgniterJobsError} If adapter is not configured
+   * @throws {IgniterJobsError} If context is not configured
+   * @throws {IgniterJobsError} If no queues are defined
+   *
+   * @example
+   * ```typescript
+   * const jobs = IgniterJobs.create<AppContext>()
+   *   .withAdapter(adapter)
+   *   .withContext(() => context)
+   *   .addQueue(emailQueue)
+   *   .build()
+   *
+   * // Now use with full type safety
+   * await jobs.email.sendWelcome.dispatch({ userId: '123' })
+   * ```
+   */
+  build() {
+    if (!this.state.adapter) {
+      throw new IgniterJobsError({
+        code: "JOBS_ADAPTER_REQUIRED",
+        message: "Adapter is required. Use .withAdapter() to configure.",
+        statusCode: 400
+      });
+    }
+    if (!this.state.context) {
+      throw new IgniterJobsError({
+        code: "JOBS_CONTEXT_REQUIRED",
+        message: "Context provider is required. Use .withContext() to configure.",
+        statusCode: 400
+      });
+    }
+    if (Object.keys(this.state.queues).length === 0) {
+      throw new IgniterJobsError({
+        code: "JOBS_QUEUE_REQUIRED",
+        message: "At least one queue is required. Use .addQueue() to add queues.",
+        statusCode: 400
+      });
+    }
+    return new IgniterJobsRuntime(
+      this.state
+    );
+  }
+};
+var IgniterJobs = {
+  create: IgniterJobsBuilder.create
+};
+
+// src/builders/igniter-queue.builder.ts
+function validateQueueName(name) {
+  if (!name || typeof name !== "string") {
+    throw new IgniterJobsError({
+      code: "JOBS_QUEUE_NAME_INVALID",
+      message: "Queue name must be a non-empty string",
+      statusCode: 400
+    });
+  }
+  if (!/^[a-z][a-z0-9-]*$/.test(name)) {
+    throw new IgniterJobsError({
+      code: "JOBS_QUEUE_NAME_INVALID",
+      message: `Queue name "${name}" must start with a lowercase letter and contain only lowercase letters, numbers, and hyphens`,
+      statusCode: 400,
+      details: { name }
+    });
+  }
+}
+function validateJobName(name) {
+  if (!name || typeof name !== "string") {
+    throw new IgniterJobsError({
+      code: "JOBS_JOB_NAME_INVALID",
+      message: "Job name must be a non-empty string",
+      statusCode: 400
+    });
+  }
+  if (!/^[a-zA-Z][a-zA-Z0-9]*$/.test(name)) {
+    throw new IgniterJobsError({
+      code: "JOBS_JOB_NAME_INVALID",
+      message: `Job name "${name}" must start with a letter and contain only letters and numbers (camelCase recommended)`,
+      statusCode: 400,
+      details: { name }
+    });
+  }
+}
+var IgniterQueueBuilder = class _IgniterQueueBuilder {
+  constructor(state) {
+    this.state = state;
+  }
+  /**
+   * Create a new queue builder.
+   *
+   * @param name - Queue name (kebab-case, e.g., 'email', 'payment-processing')
+   * @returns A new IgniterQueueBuilder instance
+   *
+   * @example
+   * ```typescript
+   * const emailQueue = IgniterQueue.create<AppContext>('email')
+   * ```
+   */
+  static create(name) {
+    validateQueueName(name);
+    return new _IgniterQueueBuilder({
+      name,
+      jobs: {},
+      crons: {}
+    });
+  }
+  /**
+   * Add a job definition to the queue.
+   *
+   * @param name - Job name (camelCase, e.g., 'sendWelcome', 'processPayment')
+   * @param definition - Job definition with input schema, handler, retry config, etc.
+   * @returns The builder with the new job added
+   *
+   * @example
+   * ```typescript
+   * .addJob('sendWelcome', {
+   *   input: z.object({
+   *     userId: z.string(),
+   *     email: z.string().email(),
+   *   }),
+   *   retry: { attempts: 3, backoff: { type: 'exponential', delay: 1000 } },
+   *   handler: async (ctx) => {
+   *     await ctx.context.mailer.send({
+   *       to: ctx.input.email,
+   *       template: 'welcome',
+   *     })
+   *   },
+   * })
+   * ```
+   */
+  addJob(name, definition) {
+    validateJobName(name);
+    if (name in this.state.jobs) {
+      throw new IgniterJobsError({
+        code: "JOBS_JOB_ALREADY_EXISTS",
+        message: `Job "${name}" already exists in queue "${this.state.name}"`,
+        statusCode: 400,
+        details: { queue: this.state.name, job: name }
+      });
+    }
+    if (!definition.handler || typeof definition.handler !== "function") {
+      throw new IgniterJobsError({
+        code: "JOBS_JOB_HANDLER_REQUIRED",
+        message: `Job "${name}" must have a handler function`,
+        statusCode: 400,
+        details: { queue: this.state.name, job: name }
+      });
+    }
+    return new _IgniterQueueBuilder({
+      ...this.state,
+      jobs: {
+        ...this.state.jobs,
+        [name]: definition
+      }
+    });
+  }
+  /**
+   * Add a cron job definition to the queue.
+   *
+   * @param name - Cron job name (camelCase)
+   * @param definition - Cron definition with expression, handler, etc.
+   * @returns The builder with the new cron added
+   *
+   * @example
+   * ```typescript
+   * .addCron('cleanupExpired', {
+   *   expression: '0 0 * * *', // Every day at midnight
+   *   timezone: 'America/New_York',
+   *   handler: async (ctx) => {
+   *     await ctx.context.db.cleanup.expiredSessions()
+   *   },
+   * })
+   * ```
+   */
+  addCron(name, definition) {
+    validateJobName(name);
+    if (name in this.state.crons) {
+      throw new IgniterJobsError({
+        code: "JOBS_CRON_ALREADY_EXISTS",
+        message: `Cron "${name}" already exists in queue "${this.state.name}"`,
+        statusCode: 400,
+        details: { queue: this.state.name, cron: name }
+      });
+    }
+    if (!definition.expression || typeof definition.expression !== "string") {
+      throw new IgniterJobsError({
+        code: "JOBS_CRON_EXPRESSION_INVALID",
+        message: `Cron "${name}" must have a valid expression`,
+        statusCode: 400,
+        details: { queue: this.state.name, cron: name }
+      });
+    }
+    if (!definition.handler || typeof definition.handler !== "function") {
+      throw new IgniterJobsError({
+        code: "JOBS_CRON_HANDLER_REQUIRED",
+        message: `Cron "${name}" must have a handler function`,
+        statusCode: 400,
+        details: { queue: this.state.name, cron: name }
+      });
+    }
+    return new _IgniterQueueBuilder({
+      ...this.state,
+      crons: {
+        ...this.state.crons,
+        [name]: definition
+      }
+    });
+  }
+  /**
+   * Build the queue configuration.
+   *
+   * @returns The queue configuration ready to be registered with IgniterJobs
+   *
+   * @example
+   * ```typescript
+   * const emailQueue = IgniterQueue.create<AppContext>('email')
+   *   .addJob('sendWelcome', { ... })
+   *   .build()
+   * ```
+   */
+  build() {
+    return { ...this.state };
+  }
+};
+var IgniterQueue = {
+  create: IgniterQueueBuilder.create
+};
+
+exports.IGNITER_JOBS_ERROR_CODES = IGNITER_JOBS_ERROR_CODES;
+exports.IgniterJobs = IgniterJobs;
+exports.IgniterJobsBuilder = IgniterJobsBuilder;
+exports.IgniterJobsError = IgniterJobsError;
+exports.IgniterJobsRuntime = IgniterJobsRuntime;
+exports.IgniterQueue = IgniterQueue;
+exports.IgniterQueueBuilder = IgniterQueueBuilder;
+exports.IgniterWorkerBuilder = IgniterWorkerBuilder;
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map