@igniter-js/jobs 0.1.1 → 0.1.12

package/dist/index.d.ts

@@ -1,8 +1,9 @@
-import { p as IgniterJobsQueue, I as IgniterJobsAdapter, q as IgniterJobsScopeDefinition, c as IgniterJobDefinition, m as IgniterJobsWorkerBuilderConfig, r as IgniterJobsTelemetry, s as IgniterJobsInferSchemaInput, d as IgniterCronDefinition, g as IgniterJobSearchResult, h as IgniterJobStatus, t as IgniterJobsDispatchParams, u as IgniterJobsScheduleParams, n as IgniterJobsEventHandler, j as IgniterJobsQueueInfo, k as IgniterJobsQueueCleanOptions, v as IgniterJobsLimiter, w as IgniterJobsWorkerHandlers, l as IgniterJobsWorkerHandle, x as IgniterJobsScopeOptions, y as IgniterJobsSchema } from './adapter-PiDCQWQd.js';
-export { o as IgniterJobCounts, e as IgniterJobsAdapterDispatchParams, f as IgniterJobsAdapterScheduleParams, b as IgniterJobsBullMQAdapterOptions, z as IgniterJobsEvent, B as IgniterJobsExecutionContext, F as IgniterJobsFailureHook, C as IgniterJobsHookContext, L as IgniterJobsInferSchemaOutput, A as IgniterJobsInvokeOptions, i as IgniterJobsJobLog, G as IgniterJobsProgressHook, a as IgniterJobsQueueManager, J as IgniterJobsScheduleOptions, H as IgniterJobsScopeEntry, D as IgniterJobsStartHook, E as IgniterJobsSuccessHook, K as IgniterJobsWorkerMetrics } from './adapter-PiDCQWQd.js';
-import { IgniterLogger, IgniterError } from '@igniter-js/core';
+import { IgniterLogger, IgniterError } from '@igniter-js/common';
+import { p as IgniterJobsQueue, I as IgniterJobsAdapter, q as IgniterJobsScopeDefinition, c as IgniterJobDefinition, m as IgniterJobsWorkerBuilderConfig, r as IgniterJobsTelemetry, n as IgniterJobsEventHandler, g as IgniterJobSearchResult, j as IgniterJobsQueueInfo, l as IgniterJobsWorkerHandle, s as IgniterJobsLimiter, t as IgniterJobsWorkerHandlers, k as IgniterJobsQueueCleanOptions, h as IgniterJobStatus, u as IgniterJobsDispatchParams, v as IgniterJobsScheduleParams, w as IgniterJobsInferSchemaInput, d as IgniterCronDefinition, x as IgniterJobsScopeEntry, y as IgniterJobsSchema, z as IgniterJobsScopeOptions } from './adapter-CXZxomI9.js';
+export { o as IgniterJobCounts, e as IgniterJobsAdapterDispatchParams, f as IgniterJobsAdapterScheduleParams, b as IgniterJobsBullMQAdapterOptions, A as IgniterJobsEvent, B as IgniterJobsExecutionContext, C as IgniterJobsFailureHook, D as IgniterJobsHookContext, E as IgniterJobsInferSchemaOutput, F as IgniterJobsInvokeOptions, i as IgniterJobsJobLog, G as IgniterJobsProgressHook, a as IgniterJobsQueueManager, H as IgniterJobsScheduleOptions, J as IgniterJobsStartHook, K as IgniterJobsSuccessHook, L as IgniterJobsWorkerMetrics } from './adapter-CXZxomI9.js';
 export { IgniterJobsBullMQAdapter } from './adapters/bullmq.adapter.js';
 export { IgniterJobsMemoryAdapter } from './adapters/memory.adapter.js';
+export { IgniterJobsSQLiteAdapter, IgniterJobsSQLiteAdapterOptions } from './adapters/index.js';
 import 'ioredis';
 
 /**
@@ -134,144 +135,278 @@ type IgniterJobsRuntime<TConfig extends IgniterJobsConfig<any, any, any> = Ignit
 };
 
 /**
- * Canonical error codes for `@igniter-js/jobs`.
+ * @fileoverview Worker builder for @igniter-js/jobs
+ * @module @igniter-js/jobs/builders/igniter-worker
  */
-declare const IGNITER_JOBS_ERROR_CODES: {
-    readonly JOBS_ADAPTER_REQUIRED: "JOBS_ADAPTER_REQUIRED";
-    readonly JOBS_SERVICE_REQUIRED: "JOBS_SERVICE_REQUIRED";
-    readonly JOBS_CONTEXT_REQUIRED: "JOBS_CONTEXT_REQUIRED";
-    readonly JOBS_CONFIGURATION_INVALID: "JOBS_CONFIGURATION_INVALID";
-    readonly JOBS_QUEUE_NOT_FOUND: "JOBS_QUEUE_NOT_FOUND";
-    readonly JOBS_QUEUE_DUPLICATE: "JOBS_QUEUE_DUPLICATE";
-    readonly JOBS_QUEUE_OPERATION_FAILED: "JOBS_QUEUE_OPERATION_FAILED";
-    readonly JOBS_INVALID_DEFINITION: "JOBS_INVALID_DEFINITION";
-    readonly JOBS_HANDLER_REQUIRED: "JOBS_HANDLER_REQUIRED";
-    readonly JOBS_DUPLICATE_JOB: "JOBS_DUPLICATE_JOB";
-    readonly JOBS_NOT_FOUND: "JOBS_NOT_FOUND";
-    readonly JOBS_NOT_REGISTERED: "JOBS_NOT_REGISTERED";
-    readonly JOBS_EXECUTION_FAILED: "JOBS_EXECUTION_FAILED";
-    readonly JOBS_TIMEOUT: "JOBS_TIMEOUT";
-    readonly JOBS_CONTEXT_FACTORY_FAILED: "JOBS_CONTEXT_FACTORY_FAILED";
-    readonly JOBS_VALIDATION_FAILED: "JOBS_VALIDATION_FAILED";
-    readonly JOBS_INVALID_INPUT: "JOBS_INVALID_INPUT";
-    readonly JOBS_INVALID_CRON: "JOBS_INVALID_CRON";
-    readonly JOBS_INVALID_SCHEDULE: "JOBS_INVALID_SCHEDULE";
-    readonly JOBS_SCOPE_ALREADY_DEFINED: "JOBS_SCOPE_ALREADY_DEFINED";
-    readonly JOBS_WORKER_FAILED: "JOBS_WORKER_FAILED";
-    readonly JOBS_ADAPTER_ERROR: "JOBS_ADAPTER_ERROR";
-    readonly JOBS_ADAPTER_CONNECTION_FAILED: "JOBS_ADAPTER_CONNECTION_FAILED";
-    readonly JOBS_SUBSCRIBE_FAILED: "JOBS_SUBSCRIBE_FAILED";
+
+type IgniterJobsWorkerBuilderState<TAllowedQueues extends string> = {
+    queues: TAllowedQueues[];
+    concurrency?: number;
+    limiter?: IgniterJobsLimiter;
+    handlers: IgniterJobsWorkerHandlers;
 };
-type IgniterJobsErrorCode = keyof typeof IGNITER_JOBS_ERROR_CODES;
-interface IgniterJobsErrorOptions {
-    /** Error code scoped to Igniter Jobs. */
-    code: IgniterJobsErrorCode;
-    /** Human-readable message. */
-    message: string;
-    /** HTTP-like status code hint (default: 500). */
-    statusCode?: number;
-    /** Optional structured details for debugging and clients. */
-    details?: unknown;
-    /** Optional metadata for logs and tracing. */
-    metadata?: Record<string, unknown>;
-    /** Optional causer tag used by some Igniter tooling. */
-    causer?: string;
-    /** Underlying cause for debugging (optional). */
-    cause?: Error;
-    /** Optional logger passthrough to align with other Igniter errors. */
-    logger?: any;
+/**
+ * Fluent builder for creating workers tied to registered queues.
+ *
+ * Instances of this builder are created by `jobs.worker.create()` so it can be
+ * automatically scoped to registered queue names.
+ */
+declare class IgniterWorkerBuilder<TAllowedQueues extends string> {
+    private readonly adapter;
+    private readonly allowedQueues;
+    private readonly state;
+    constructor(params: {
+        adapter: IgniterJobsAdapter;
+        allowedQueues: readonly TAllowedQueues[];
+        state?: Partial<IgniterJobsWorkerBuilderState<TAllowedQueues>>;
+    });
+    private clone;
+    /**
+     * Adds a queue to the worker.
+     *
+     * @param queue - Queue name registered on the jobs instance.
+     */
+    addQueue(queue: TAllowedQueues): IgniterWorkerBuilder<TAllowedQueues>;
+    /**
+     * Sets the worker concurrency.
+     */
+    withConcurrency(concurrency: number): IgniterWorkerBuilder<TAllowedQueues>;
+    /**
+     * Sets a worker-level rate limiter.
+     */
+    withLimiter(limiter: IgniterJobsLimiter): IgniterWorkerBuilder<TAllowedQueues>;
+    onActive(handler: NonNullable<IgniterJobsWorkerHandlers['onActive']>): IgniterWorkerBuilder<TAllowedQueues>;
+    onSuccess(handler: NonNullable<IgniterJobsWorkerHandlers['onSuccess']>): IgniterWorkerBuilder<TAllowedQueues>;
+    onFailure(handler: NonNullable<IgniterJobsWorkerHandlers['onFailure']>): IgniterWorkerBuilder<TAllowedQueues>;
+    onIdle(handler: NonNullable<IgniterJobsWorkerHandlers['onIdle']>): IgniterWorkerBuilder<TAllowedQueues>;
+    /**
+     * Builds and starts the worker.
+     *
+     * If no queues are added explicitly, the adapter should interpret it as "all queues".
+     */
+    start(): Promise<IgniterJobsWorkerHandle>;
 }
+
 /**
- * Typed error class for the Jobs package.
+ * @fileoverview Core IgniterJobsManager class with all job operations
+ * @module @igniter-js/jobs/core
+ *
+ * @description
+ * The main IgniterJobsManager class provides a type-safe, scoped API for background job processing.
+ * It supports job dispatching, scheduling, worker management, queue operations, and scoped instances
+ * for multi-tenant applications.
  *
  * @example
  * ```typescript
- * throw new IgniterJobsError({
- *   code: 'JOBS_INVALID_INPUT',
- *   message: 'Input payload failed validation',
- * })
+ * import { IgniterJobs, IgniterJobsMemoryAdapter } from '@igniter-js/jobs'
+ * import { z } from 'zod'
+ *
+ * const emailQueue = IgniterQueue.create('email')
+ *   .addJob('sendWelcome', {
+ *     input: z.object({ to: z.string(), name: z.string() }),
+ *     handler: async (ctx) => {
+ *       await sendEmail(ctx.input.to, `Welcome ${ctx.input.name}!`)
+ *     },
+ *   })
+ *   .build()
+ *
+ * const jobs = IgniterJobs.create()
+ *   .withAdapter(IgniterJobsMemoryAdapter.create())
+ *   .withService('my-api')
+ *   .withEnvironment('production')
+ *   .withContext(async () => ({ db }))
+ *   .addQueue(emailQueue)
+ *   .build()
+ *
+ * // Dispatch a job
+ * await jobs.email.sendWelcome.dispatch({ input: { to: 'user@example.com', name: 'Alice' } })
+ *
+ * // Scoped operations
+ * const orgJobs = jobs.scope('organization', 'org_123')
+ * await orgJobs.email.sendWelcome.dispatch({ input: { to: 'user@example.com', name: 'Bob' } })
  * ```
  */
-declare class IgniterJobsError extends IgniterError {
-    constructor(options: IgniterJobsErrorOptions);
-}
 
 /**
- * Fluent builder responsible for configuring and constructing an `IgniterJobs` instance.
+ * Main IgniterJobsManager class providing background job processing operations.
  *
- * The builder follows the immutable pattern used across Igniter packages: each
- * method returns a new builder with refined types. Only a single scope is
- * supported per the current specification (no actor support).
+ * Features:
+ * - **Job Dispatching**: Enqueue jobs for immediate or delayed processing
+ * - **Job Scheduling**: Schedule jobs with cron expressions or specific times
+ * - **Worker Management**: Create and manage workers with configurable concurrency
+ * - **Queue Operations**: Pause, resume, drain, clean queues
+ * - **Scopes**: Multi-tenant isolation with scoped job instances
+ * - **Telemetry**: Built-in observability with typed telemetry events
+ *
+ * @typeParam TConfig - The jobs configuration type
  */
-declare class IgniterJobsBuilder<TContext, TQueues extends Record<string, IgniterJobsQueue<TContext, any, any>> = {}, TScope extends string = never> {
-    private readonly state;
-    private constructor();
+declare class IgniterJobsManager<TConfig extends IgniterJobsConfig<any, any, any> = IgniterJobsConfig<any, any, any>> {
+    /** @internal */
+    private readonly config;
+    /** @internal */
+    private readonly adapter;
+    /** @internal */
+    private readonly telemetry?;
+    /** @internal */
+    private readonly scopeEntry?;
     /**
-     * Creates the initial builder with no configuration.
+     * @internal
+     * Constructor is internal. Use `IgniterJobs.create()` instead.
      */
-    static create<TContext>(): IgniterJobsBuilder<TContext>;
+    constructor(config: TConfig, scopeEntry?: IgniterJobsScopeEntry);
     /**
-     * Returns a new builder with updated state while preserving generics.
+     * Creates a scoped jobs instance.
+     *
+     * Scopes provide multi-tenant isolation by adding scope metadata to all jobs.
+     * Jobs dispatched from a scoped instance will include scope information in their metadata.
+     *
+     * @param type - The scope type (e.g., 'organization', 'workspace')
+     * @param id - The scope identifier (e.g., 'org_123')
+     * @param tags - Optional additional tags for the scope
+     * @returns A new scoped IgniterJobsManager instance
+     *
+     * @example
+     * ```typescript
+     * const orgJobs = jobs.scope('organization', 'org_123')
+     * await orgJobs.email.sendWelcome.dispatch({ input: { to: 'user@example.com' } })
+     * ```
      */
-    private clone;
+    scope(type: string, id: string | number, tags?: Record<string, unknown>): IgniterJobsManager<TConfig>;
     /**
-     * Attaches the jobs adapter.
+     * Subscribes to all job events from this jobs instance.
      *
-     * @param adapter - Backend adapter implementation (BullMQ, memory, etc.).
+     * @param handler - The event handler function
+     * @returns A function to unsubscribe
+     *
+     * @example
+     * ```typescript
+     * const unsubscribe = await jobs.subscribe((event) => {
+     *   console.log('Job event:', event.type, event.data)
+     * })
+     * // Later: await unsubscribe()
+     * ```
      */
-    withAdapter(adapter: IgniterJobsAdapter): IgniterJobsBuilder<TContext, TQueues, TScope>;
+    subscribe(handler: IgniterJobsEventHandler): Promise<() => Promise<void>>;
     /**
-     * Sets the service identifier for telemetry and metrics.
+     * Searches for jobs, queues, or workers based on filters.
      *
-     * @param service - Service name (e.g., "my-api").
+     * @param target - The target to search ('jobs', 'queues', or 'workers')
+     * @param filter - The filter criteria
+     * @returns The search results
+     *
+     * @example
+     * ```typescript
+     * const failedJobs = await jobs.search('jobs', { status: 'failed', queue: 'email' })
+     * const queues = await jobs.search('queues', {})
+     * ```
      */
-    withService(service: string): IgniterJobsBuilder<TContext, TQueues, TScope>;
+    search(target: "jobs" | "queues" | "workers", filter: Record<string, unknown>): Promise<unknown[]>;
     /**
-     * Sets the environment name (e.g., development, staging, production).
+     * Gracefully shuts down the jobs instance.
+     *
+     * This will close all connections and stop all workers.
+     *
+     * @example
+     * ```typescript
+     * await jobs.shutdown()
+     * ```
      */
-    withEnvironment(environment: string): IgniterJobsBuilder<TContext, TQueues, TScope>;
+    shutdown(): Promise<void>;
     /**
-     * Provides a context factory used when executing jobs.
+     * Creates a new worker builder for processing jobs.
+     *
+     * @returns A new IgniterWorkerBuilder instance
+     *
+     * @example
+     * ```typescript
+     * const worker = await jobs.worker
+     *   .create()
+     *   .addQueue('email')
+     *   .withConcurrency(5)
+     *   .start()
+     * ```
      */
-    withContext(factory: () => TContext | Promise<TContext>): IgniterJobsBuilder<TContext, TQueues, TScope>;
+    get worker(): {
+        create: () => IgniterWorkerBuilder<string>;
+    };
     /**
-     * Adds a scope definition (single scope supported).
+     * Converts the manager to a runtime proxy with typed queue accessors.
+     *
+     * @internal
+     * @returns The runtime proxy
      */
-    addScope<TNewScope extends string>(name: TNewScope, options?: IgniterJobsScopeOptions): IgniterJobsBuilder<TContext, TQueues, TScope | TNewScope>;
+    toRuntime(): IgniterJobsRuntime<TConfig>;
     /**
-     * Registers a queue definition on the builder.
+     * Ensures all jobs and crons are registered with the adapter.
+     * Uses a shared WeakSet to prevent duplicate registration across scoped instances.
+     * @internal
      */
-    addQueue<TName extends string, TQueue extends IgniterJobsQueue<TContext, any, any>>(queue: TQueue & {
-        name: TName;
-    }): IgniterJobsBuilder<TContext, TQueues & Record<TName, TQueue>, TScope>;
+    private ensureRegistered;
     /**
-     * Applies default job options to all queues.
+     * Creates a queue accessor with job accessors and management methods.
+     * @internal
      */
-    withQueueDefaults(defaults: Partial<IgniterJobDefinition<TContext, any, any>>): IgniterJobsBuilder<TContext, TQueues, TScope>;
+    private createQueueAccessor;
     /**
-     * Applies default worker options.
+     * Creates a job accessor with dispatch, schedule, and management methods.
+     * @internal
      */
-    withWorkerDefaults(defaults: Partial<IgniterJobsWorkerBuilderConfig>): IgniterJobsBuilder<TContext, TQueues, TScope>;
+    private createJobAccessor;
     /**
-     * Configures automatic worker startup.
+     * Dispatches a job for immediate or delayed processing.
+     * @internal
      */
-    withAutoStartWorker(config: {
-        queues: (keyof TQueues)[];
-        concurrency?: number;
-        limiter?: IgniterJobsLimiter;
-    }): IgniterJobsBuilder<TContext, TQueues, TScope>;
+    private dispatchJob;
     /**
-     * Attaches telemetry support.
+     * Schedules a job for future processing.
+     * @internal
      */
-    withTelemetry(telemetry: IgniterJobsTelemetry): IgniterJobsBuilder<TContext, TQueues, TScope>;
+    private scheduleJob;
     /**
-     * Attaches a custom logger.
+     * Wraps a job definition with context building, validation, and telemetry.
+     * @internal
      */
-    withLogger(logger: IgniterLogger): IgniterJobsBuilder<TContext, TQueues, TScope>;
+    private wrapJobDefinition;
     /**
-     * Finalizes the configuration and returns the runtime instance.
+     * Wraps a cron definition with context building and lifecycle events.
+     * @internal
      */
-    build(): IgniterJobsRuntime<IgniterJobsConfig<TContext, TQueues, TScope>>;
+    private wrapCronDefinition;
+    /**
+     * Builds the execution context for a job.
+     * @internal
+     */
+    private buildExecutionContext;
+    /**
+     * Builds the execution context for a cron job.
+     * @internal
+     */
+    private buildCronExecutionContext;
+    /**
+     * Gets a job definition by queue and job name.
+     * @internal
+     */
+    private getJobDefinition;
+    /**
+     * Resolves the effective scope for a job operation.
+     * @internal
+     */
+    private resolveScope;
+    /**
+     * Builds the events channel string for subscriptions.
+     * @internal
+     */
+    private buildEventsChannel;
+    /**
+     * Publishes a job lifecycle event.
+     * @internal
+     */
+    private publishJobEvent;
+    /**
+     * Emits a telemetry event if telemetry is configured.
+     * @internal
+     */
+    private emitTelemetry;
 }
 
 /**
@@ -311,19 +446,6 @@ declare class IgniterQueueBuilder<TContext, TJobs extends Record<string, Igniter
      * Creates a new queue builder for the given queue name.
      */
     static create<const TName extends string>(name: TName): IgniterQueueBuilder<unknown, {}, {}, TName>;
-    /**
-     * Re-types this builder with the application context type.
-     *
-     * This is a type-level helper; it does not mutate runtime state.
-     *
-     * @example
-     * ```typescript
-     * const queue = IgniterQueue.create('email')
-     *   .withContext<AppContext>()
-     *   .addJob('send', { handler: async ({ context }) => context.mailer.send() })
-     * ```
-     */
-    withContext<TNewContext>(this: IgniterQueueBuilder<unknown, {}, {}, TName>): IgniterQueueBuilder<TNewContext, {}, {}, TName>;
     private clone;
     /**
      * Registers a job on the queue.
@@ -347,92 +469,6 @@ declare class IgniterQueueBuilder<TContext, TJobs extends Record<string, Igniter
     };
 }
 
-/**
- * @fileoverview Worker builder for @igniter-js/jobs
- * @module @igniter-js/jobs/builders/igniter-worker
- */
-
-type IgniterJobsWorkerBuilderState<TAllowedQueues extends string> = {
-    queues: TAllowedQueues[];
-    concurrency?: number;
-    limiter?: IgniterJobsLimiter;
-    handlers: IgniterJobsWorkerHandlers;
-};
-/**
- * Fluent builder for creating workers tied to registered queues.
- *
- * Instances of this builder are created by `jobs.worker.create()` so it can be
- * automatically scoped to registered queue names.
- */
-declare class IgniterWorkerBuilder<TAllowedQueues extends string> {
-    private readonly adapter;
-    private readonly allowedQueues;
-    private readonly state;
-    constructor(params: {
-        adapter: IgniterJobsAdapter;
-        allowedQueues: readonly TAllowedQueues[];
-        state?: Partial<IgniterJobsWorkerBuilderState<TAllowedQueues>>;
-    });
-    private clone;
-    /**
-     * Adds a queue to the worker.
-     *
-     * @param queue - Queue name registered on the jobs instance.
-     */
-    addQueue(queue: TAllowedQueues): IgniterWorkerBuilder<TAllowedQueues>;
-    /**
-     * Sets the worker concurrency.
-     */
-    withConcurrency(concurrency: number): IgniterWorkerBuilder<TAllowedQueues>;
-    /**
-     * Sets a worker-level rate limiter.
-     */
-    withLimiter(limiter: IgniterJobsLimiter): IgniterWorkerBuilder<TAllowedQueues>;
-    onActive(handler: NonNullable<IgniterJobsWorkerHandlers['onActive']>): IgniterWorkerBuilder<TAllowedQueues>;
-    onSuccess(handler: NonNullable<IgniterJobsWorkerHandlers['onSuccess']>): IgniterWorkerBuilder<TAllowedQueues>;
-    onFailure(handler: NonNullable<IgniterJobsWorkerHandlers['onFailure']>): IgniterWorkerBuilder<TAllowedQueues>;
-    onIdle(handler: NonNullable<IgniterJobsWorkerHandlers['onIdle']>): IgniterWorkerBuilder<TAllowedQueues>;
-    /**
-     * Builds and starts the worker.
-     *
-     * If no queues are added explicitly, the adapter should interpret it as "all queues".
-     */
-    start(): Promise<IgniterJobsWorkerHandle>;
-}
-
-/**
- * @fileoverview Core runtime factory for @igniter-js/jobs
- * @module @igniter-js/jobs/core/igniter-jobs
- */
-
-/**
- * Runtime wrapper produced by `IgniterJobsBuilder`.
- *
- * The concrete implementation will expose queue/job proxies, management APIs,
- * worker builder access, and shutdown handling.
- */
-declare class IgniterJobs {
-    /**
-     * Starts the fluent builder API for jobs.
-     *
-     * @example
-     * ```typescript
-     * const jobs = IgniterJobs.create<AppContext>()
-     *   .withAdapter(IgniterJobsMemoryAdapter.create())
-     *   .withService('my-api')
-     *   .withEnvironment('test')
-     *   .withContext(async () => ({ db }))
-     *   .addQueue(emailQueue)
-     *   .build()
-     * ```
-     */
-    static create<TContext>(): IgniterJobsBuilder<TContext, {}, never>;
-    /**
-     * Creates a runtime instance from a validated configuration.
-     */
-    static fromConfig<TConfig extends IgniterJobsConfig<any, any, any>>(config: TConfig): IgniterJobsRuntime<TConfig>;
-}
-
 /**
  * @fileoverview Public queue entry point for @igniter-js/jobs
  * @module @igniter-js/jobs/core/igniter-queue
@@ -457,178 +493,252 @@ declare class IgniterQueue {
 }
 
 /**
- * @fileoverview Telemetry event definitions for @igniter-js/jobs
- * @module @igniter-js/jobs/telemetry/jobs.telemetry
+ * @fileoverview Builder for creating IgniterJobs instances
+ * @module @igniter-js/jobs/builders/main
  *
  * @description
- * Defines all telemetry events emitted by the jobs package during job
- * lifecycle operations. These events can be consumed by any transport
- * adapter configured on the telemetry instance.
- *
- * Events follow the pattern: igniter.jobs.<group>.<event>
- *
- * Groups:
- * - job: Job lifecycle events (enqueued, started, completed, failed, progress, retrying)
- * - worker: Worker lifecycle events (started, stopped, idle)
- * - queue: Queue management events (paused, resumed, drained, cleaned)
+ * Provides a fluent builder API for configuring and creating IgniterJobs instances.
+ * Supports adapter configuration, service naming, environment settings, queues,
+ * scopes, telemetry, and more.
  *
  * @example
  * ```typescript
- * import { IgniterTelemetry } from '@igniter-js/telemetry'
- * import { IgniterJobsTelemetryEvents } from '@igniter-js/jobs'
+ * import { IgniterJobs, IgniterQueue } from '@igniter-js/jobs'
+ * import { IgniterJobsMemoryAdapter } from '@igniter-js/jobs/adapters'
+ * import { z } from 'zod'
+ *
+ * const emailQueue = IgniterQueue.create('email')
+ *   .addJob('sendWelcome', {
+ *     input: z.object({ to: z.string(), name: z.string() }),
+ *     handler: async (ctx) => {
+ *       await sendEmail(ctx.input.to, `Welcome ${ctx.input.name}!`)
+ *     },
+ *   })
+ *   .build()
  *
- * const telemetry = IgniterTelemetry.create()
+ * const jobs = IgniterJobs.create()
+ *   .withAdapter(IgniterJobsMemoryAdapter.create())
  *   .withService('my-api')
- *   .addEvents(IgniterJobsTelemetryEvents)
+ *   .withEnvironment('production')
+ *   .withContext(async () => ({ db }))
+ *   .addQueue(emailQueue)
  *   .build()
  * ```
  */
+
 /**
- * Telemetry event definitions for @igniter-js/jobs.
+ * Fluent builder responsible for configuring and constructing an `IgniterJobs` instance.
  *
- * This descriptor can be passed to `IgniterTelemetry.addEvents()` to register
- * all job-related telemetry events with proper type inference.
+ * The builder follows the immutable pattern used across Igniter packages: each
+ * method returns a new builder with refined types. Only a single scope is
+ * supported per the current specification (no actor support).
+ */
+declare class IgniterJobsBuilder<TContext, TQueues extends Record<string, IgniterJobsQueue<TContext, any, any>> = {}, TScope extends string = never> {
+    private readonly state;
+    private constructor();
+    /**
+     * Creates the initial builder with no configuration.
+     *
+     * Context type is inferred from `withContext()` - no explicit generic needed.
+     *
+     * @example
+     * ```typescript
+     * // Context is inferred from the factory return type
+     * const jobs = IgniterJobs.create()
+     *   .withContext(async () => ({ db: prisma, cache: redis }))
+     *   // TContext is now { db: PrismaClient, cache: Redis }
+     *   .build()
+     * ```
+     */
+    static create(): IgniterJobsBuilder<unknown>;
+    /**
+     * Returns a new builder with updated state while preserving generics.
+     */
+    private clone;
+    /**
+     * Attaches the jobs adapter.
+     *
+     * @param adapter - Backend adapter implementation (BullMQ, memory, etc.).
+     */
+    withAdapter(adapter: IgniterJobsAdapter): IgniterJobsBuilder<TContext, TQueues, TScope>;
+    /**
+     * Sets the service identifier for telemetry and metrics.
+     *
+     * @param service - Service name (e.g., "my-api").
+     */
+    withService(service: string): IgniterJobsBuilder<TContext, TQueues, TScope>;
+    /**
+     * Sets the environment name (e.g., development, staging, production).
+     */
+    withEnvironment(environment: string): IgniterJobsBuilder<TContext, TQueues, TScope>;
+    /**
+     * Provides a context factory used when executing jobs.
+     *
+     * The context type is inferred from the factory return type, eliminating
+     * the need for explicit generics on `IgniterJobs.create()`.
+     *
+     * **Note:** This must be called before adding any queues, as the context
+     * type affects queue type compatibility.
+     *
+     * @param factory - Function that returns the context (sync or async)
+     * @returns A new builder with the inferred context type
+     *
+     * @example
+     * ```typescript
+     * // Context type is inferred as { db: PrismaClient, cache: Redis }
+     * const jobs = IgniterJobs.create()
+     *   .withContext(async () => ({
+     *     db: new PrismaClient(),
+     *     cache: new Redis(),
+     *   }))
+     *   .addQueue(emailQueue)
+     *   .build()
+     * ```
+     */
+    withContext<TNewContext>(this: IgniterJobsBuilder<unknown, {}, TScope>, factory: () => TNewContext | Promise<TNewContext>): IgniterJobsBuilder<TNewContext, {}, TScope>;
+    /**
+     * Adds a scope definition (single scope supported).
+     */
+    addScope<TNewScope extends string>(name: TNewScope, options?: IgniterJobsScopeOptions): IgniterJobsBuilder<TContext, TQueues, TScope | TNewScope>;
+    /**
+     * Registers a queue definition on the builder.
+     */
+    addQueue<TName extends string, TQueue extends IgniterJobsQueue<TContext, any, any>>(queue: TQueue & {
+        name: TName;
+    }): IgniterJobsBuilder<TContext, TQueues & Record<TName, TQueue>, TScope>;
+    /**
+     * Applies default job options to all queues.
+     */
+    withQueueDefaults(defaults: Partial<IgniterJobDefinition<TContext, any, any>>): IgniterJobsBuilder<TContext, TQueues, TScope>;
+    /**
+     * Applies default worker options.
+     */
+    withWorkerDefaults(defaults: Partial<IgniterJobsWorkerBuilderConfig>): IgniterJobsBuilder<TContext, TQueues, TScope>;
+    /**
+     * Configures automatic worker startup.
+     */
+    withAutoStartWorker(config: {
+        queues: (keyof TQueues)[];
+        concurrency?: number;
+        limiter?: IgniterJobsLimiter;
+    }): IgniterJobsBuilder<TContext, TQueues, TScope>;
+    /**
+     * Attaches telemetry support.
+     */
+    withTelemetry(telemetry: IgniterJobsTelemetry): IgniterJobsBuilder<TContext, TQueues, TScope>;
+    /**
+     * Attaches a custom logger.
+     */
+    withLogger(logger: IgniterLogger): IgniterJobsBuilder<TContext, TQueues, TScope>;
+    /**
+     * Finalizes the configuration and returns the runtime instance.
+     */
+    build(): IgniterJobsRuntime<IgniterJobsConfig<TContext, TQueues, TScope>>;
+}
+/**
+ * Factory for creating and configuring IgniterJobs instances.
  *
- * Event names follow the pattern: `igniter.jobs.<group>.<event>`
+ * This is the main entry point for creating a jobs runtime with a fluent builder API.
+ * It provides type-safe configuration for adapters, queues, scopes, context, and telemetry.
  *
  * @example
  * ```typescript
- * import { IgniterTelemetry } from '@igniter-js/telemetry'
- * import { IgniterJobsTelemetryEvents } from '@igniter-js/jobs'
+ * import { IgniterJobs, IgniterQueue } from '@igniter-js/jobs'
+ * import { IgniterJobsMemoryAdapter } from '@igniter-js/jobs/adapters'
+ * import { z } from 'zod'
+ *
+ * const emailQueue = IgniterQueue.create('email')
+ *   .addJob('sendWelcome', {
+ *     input: z.object({ to: z.string(), name: z.string() }),
+ *     handler: async (ctx) => {
+ *       await sendEmail(ctx.input.to, `Welcome ${ctx.input.name}!`)
+ *     },
+ *   })
+ *   .build()
  *
- * const telemetry = IgniterTelemetry.create()
+ * const jobs = IgniterJobs.create()
+ *   .withAdapter(IgniterJobsMemoryAdapter.create())
  *   .withService('my-api')
- *   .addEvents(IgniterJobsTelemetryEvents)
+ *   .withEnvironment('production')
+ *   .withContext(async () => ({ db }))
+ *   .addQueue(emailQueue)
  *   .build()
  *
- * // Type-safe emit
- * telemetry.emit('igniter.jobs.job.completed', {
- *   attributes: {
- *     'ctx.job.id': 'job_123',
- *     'ctx.job.name': 'sendWelcome',
- *     'ctx.job.queue': 'email',
- *     'ctx.job.duration': 1500,
- *   },
- * })
+ * // Dispatch jobs
+ * await jobs.email.sendWelcome.dispatch({ input: { to: 'user@example.com', name: 'Alice' } })
+ *
+ * // Use scopes for multi-tenancy
+ * const orgJobs = jobs.scope('organization', 'org_123')
+ * await orgJobs.email.sendWelcome.dispatch({ input: { to: 'user@example.com', name: 'Bob' } })
  * ```
+ *
+ * @see {@link IgniterJobsBuilder} for detailed method documentation
  */
-declare const IgniterJobsTelemetryEvents: {
-    readonly namespace: "igniter.jobs";
-    readonly events: {
-        readonly job: {
-            readonly enqueued: {
-                "ctx.job.id": string;
-                "ctx.job.name": string;
-                "ctx.job.queue": string;
-                "ctx.job.priority"?: number;
-                "ctx.job.delay"?: number;
-            };
-            readonly started: {
-                "ctx.job.id": string;
-                "ctx.job.name": string;
-                "ctx.job.queue": string;
-                "ctx.job.attempt": number;
-                "ctx.job.maxAttempts": number;
-            };
-            readonly completed: {
-                "ctx.job.id": string;
-                "ctx.job.name": string;
-                "ctx.job.queue": string;
-                "ctx.job.duration": number;
-            };
-            readonly failed: {
-                "ctx.job.id": string;
-                "ctx.job.name": string;
-                "ctx.job.queue": string;
-                "ctx.job.error.message": string;
-                "ctx.job.error.code"?: string;
-                "ctx.job.attempt": number;
-                "ctx.job.maxAttempts": number;
-                "ctx.job.isFinalAttempt": boolean;
-            };
-            readonly progress: {
-                "ctx.job.id": string;
-                "ctx.job.name": string;
-                "ctx.job.queue": string;
-                "ctx.job.progress": number;
-                "ctx.job.progress.message"?: string;
-            };
-            readonly retrying: {
-                "ctx.job.id": string;
-                "ctx.job.name": string;
-                "ctx.job.queue": string;
-                "ctx.job.attempt": number;
-                "ctx.job.maxAttempts": number;
-                "ctx.job.nextRetryDelay": number;
-            };
-            readonly scheduled: {
-                "ctx.job.id": string;
-                "ctx.job.name": string;
-                "ctx.job.queue": string;
-                "ctx.job.scheduledAt"?: string;
-                "ctx.job.cron"?: string;
-            };
-        };
-        readonly worker: {
-            readonly started: {
-                "ctx.worker.id": string;
-                "ctx.worker.queues": string;
-                "ctx.worker.concurrency": number;
-            };
-            readonly stopped: {
-                "ctx.worker.id": string;
-                "ctx.worker.processed": number;
-                "ctx.worker.failed": number;
-                "ctx.worker.uptime": number;
-            };
-            readonly idle: {
-                "ctx.worker.id": string;
-                "ctx.worker.queues": string;
-            };
-            readonly paused: {
-                "ctx.worker.id": string;
-                "ctx.worker.queues": string;
-            };
-            readonly resumed: {
-                "ctx.worker.id": string;
-                "ctx.worker.queues": string;
-            };
-        };
-        readonly queue: {
-            readonly paused: {
-                "ctx.queue.name": string;
-            };
-            readonly resumed: {
-                "ctx.queue.name": string;
-            };
-            readonly drained: {
-                "ctx.queue.name": string;
-                "ctx.queue.drained.count": number;
-            };
-            readonly cleaned: {
-                "ctx.queue.name": string;
-                "ctx.queue.cleaned.count": number;
-                "ctx.queue.cleaned.status": string;
-            };
-            readonly obliterated: {
-                "ctx.queue.name": string;
-                "ctx.queue.obliterated.force": boolean;
-            };
-        };
-    };
+declare const IgniterJobs: {
+    create: typeof IgniterJobsBuilder.create;
+};
+
+/**
+ * Canonical error codes for `@igniter-js/jobs`.
+ */
+declare const IGNITER_JOBS_ERROR_CODES: {
+    readonly JOBS_ADAPTER_REQUIRED: "JOBS_ADAPTER_REQUIRED";
+    readonly JOBS_SERVICE_REQUIRED: "JOBS_SERVICE_REQUIRED";
+    readonly JOBS_CONTEXT_REQUIRED: "JOBS_CONTEXT_REQUIRED";
+    readonly JOBS_CONFIGURATION_INVALID: "JOBS_CONFIGURATION_INVALID";
+    readonly JOBS_QUEUE_NOT_FOUND: "JOBS_QUEUE_NOT_FOUND";
+    readonly JOBS_QUEUE_DUPLICATE: "JOBS_QUEUE_DUPLICATE";
+    readonly JOBS_QUEUE_OPERATION_FAILED: "JOBS_QUEUE_OPERATION_FAILED";
+    readonly JOBS_INVALID_DEFINITION: "JOBS_INVALID_DEFINITION";
+    readonly JOBS_HANDLER_REQUIRED: "JOBS_HANDLER_REQUIRED";
+    readonly JOBS_DUPLICATE_JOB: "JOBS_DUPLICATE_JOB";
+    readonly JOBS_NOT_FOUND: "JOBS_NOT_FOUND";
+    readonly JOBS_NOT_REGISTERED: "JOBS_NOT_REGISTERED";
+    readonly JOBS_EXECUTION_FAILED: "JOBS_EXECUTION_FAILED";
+    readonly JOBS_TIMEOUT: "JOBS_TIMEOUT";
+    readonly JOBS_CONTEXT_FACTORY_FAILED: "JOBS_CONTEXT_FACTORY_FAILED";
+    readonly JOBS_VALIDATION_FAILED: "JOBS_VALIDATION_FAILED";
+    readonly JOBS_INVALID_INPUT: "JOBS_INVALID_INPUT";
+    readonly JOBS_INVALID_CRON: "JOBS_INVALID_CRON";
+    readonly JOBS_INVALID_SCHEDULE: "JOBS_INVALID_SCHEDULE";
+    readonly JOBS_SCOPE_ALREADY_DEFINED: "JOBS_SCOPE_ALREADY_DEFINED";
+    readonly JOBS_WORKER_FAILED: "JOBS_WORKER_FAILED";
+    readonly JOBS_ADAPTER_ERROR: "JOBS_ADAPTER_ERROR";
+    readonly JOBS_ADAPTER_CONNECTION_FAILED: "JOBS_ADAPTER_CONNECTION_FAILED";
+    readonly JOBS_SUBSCRIBE_FAILED: "JOBS_SUBSCRIBE_FAILED";
 };
+type IgniterJobsErrorCode = keyof typeof IGNITER_JOBS_ERROR_CODES;
+interface IgniterJobsErrorOptions {
+    /** Error code scoped to Igniter Jobs. */
+    code: IgniterJobsErrorCode;
+    /** Human-readable message. */
+    message: string;
+    /** HTTP-like status code hint (default: 500). */
+    statusCode?: number;
+    /** Optional structured details for debugging and clients. */
+    details?: unknown;
+    /** Optional metadata for logs and tracing. */
+    metadata?: Record<string, unknown>;
+    /** Optional causer tag used by some Igniter tooling. */
+    causer?: string;
+    /** Underlying cause for debugging (optional). */
+    cause?: Error;
+    /** Optional logger passthrough to align with other Igniter errors. */
+    logger?: any;
+}
 /**
- * Union type of all job telemetry event names.
+ * Typed error class for the Jobs package.
  *
  * @example
  * ```typescript
- * import type { IgniterJobsTelemetryEventNames } from '@igniter-js/jobs'
- *
- * function handleEvent(name: IgniterJobsTelemetryEventNames) {
- *   // name is type-safe
- * }
+ * throw new IgniterJobsError({
+ *   code: 'JOBS_INVALID_INPUT',
+ *   message: 'Input payload failed validation',
+ * })
  * ```
  */
-type IgniterJobsTelemetryEventNames = "igniter.jobs.job.enqueued" | "igniter.jobs.job.started" | "igniter.jobs.job.completed" | "igniter.jobs.job.failed" | "igniter.jobs.job.progress" | "igniter.jobs.job.retrying" | "igniter.jobs.job.scheduled" | "igniter.jobs.worker.started" | "igniter.jobs.worker.stopped" | "igniter.jobs.worker.idle" | "igniter.jobs.worker.paused" | "igniter.jobs.worker.resumed" | "igniter.jobs.queue.paused" | "igniter.jobs.queue.resumed" | "igniter.jobs.queue.drained" | "igniter.jobs.queue.cleaned" | "igniter.jobs.queue.obliterated";
+declare class IgniterJobsError extends IgniterError {
+    constructor(options: IgniterJobsErrorOptions);
+}
 
-export { IGNITER_JOBS_ERROR_CODES, IgniterCronDefinition, IgniterJobDefinition, IgniterJobSearchResult, IgniterJobStatus, IgniterJobs, IgniterJobsAdapter, type IgniterJobsBaseRuntime, IgniterJobsBuilder, type IgniterJobsBuilderState, type IgniterJobsConfig, IgniterJobsDispatchParams, IgniterJobsError, type IgniterJobsErrorCode, type IgniterJobsErrorOptions, IgniterJobsEventHandler, type IgniterJobsInferCronResult, type IgniterJobsInferInput, type IgniterJobsInferJobInput, IgniterJobsInferSchemaInput, type IgniterJobsJobAccessor, type IgniterJobsJobInstanceAccessor, type IgniterJobsJobManyAccessor, IgniterJobsLimiter, IgniterJobsQueue, type IgniterJobsQueueAccessor, IgniterJobsQueueCleanOptions, IgniterJobsQueueInfo, type IgniterJobsQueueManagerAccessor, type IgniterJobsRuntime, IgniterJobsScheduleParams, IgniterJobsSchema, IgniterJobsScopeDefinition, IgniterJobsScopeOptions, IgniterJobsTelemetry, type IgniterJobsTelemetryEventNames, IgniterJobsTelemetryEvents, type IgniterJobsWorkerBuilderAccessor, IgniterJobsWorkerBuilderConfig, type IgniterJobsWorkerFluentBuilder, IgniterJobsWorkerHandle, IgniterJobsWorkerHandlers, IgniterQueue, IgniterQueueBuilder, IgniterWorkerBuilder };
+export { IGNITER_JOBS_ERROR_CODES, IgniterCronDefinition, IgniterJobDefinition, IgniterJobSearchResult, IgniterJobStatus, IgniterJobs, IgniterJobsAdapter, type IgniterJobsBaseRuntime, IgniterJobsBuilder, type IgniterJobsBuilderState, type IgniterJobsConfig, IgniterJobsDispatchParams, IgniterJobsError, type IgniterJobsErrorCode, type IgniterJobsErrorOptions, IgniterJobsEventHandler, type IgniterJobsInferCronResult, type IgniterJobsInferInput, type IgniterJobsInferJobInput, IgniterJobsInferSchemaInput, type IgniterJobsJobAccessor, type IgniterJobsJobInstanceAccessor, type IgniterJobsJobManyAccessor, IgniterJobsLimiter, IgniterJobsManager, IgniterJobsQueue, type IgniterJobsQueueAccessor, IgniterJobsQueueCleanOptions, IgniterJobsQueueInfo, type IgniterJobsQueueManagerAccessor, type IgniterJobsRuntime, IgniterJobsScheduleParams, IgniterJobsSchema, IgniterJobsScopeDefinition, IgniterJobsScopeEntry, IgniterJobsScopeOptions, IgniterJobsTelemetry, type IgniterJobsWorkerBuilderAccessor, IgniterJobsWorkerBuilderConfig, type IgniterJobsWorkerFluentBuilder, IgniterJobsWorkerHandle, IgniterJobsWorkerHandlers, IgniterQueue, IgniterQueueBuilder, IgniterWorkerBuilder };