@m16khb/nestjs-sidequest 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,900 @@
+import { ModuleMetadata, InjectionToken, OptionalFactoryDependency, Type, DynamicModule, OnModuleInit, OnModuleDestroy } from '@nestjs/common';
+import { Job } from 'sidequest';
+export { Job } from 'sidequest';
+
+/**
+ * 데이터베이스 백엔드 설정
+ */
+interface BackendConfig {
+    /**
+     * 백엔드 드라이버
+     * @example '@sidequest/postgres-backend', '@sidequest/mysql-backend', '@sidequest/sqlite-backend', '@sidequest/mongo-backend'
+     */
+    driver: string;
+    /**
+     * 연결 설정 (연결 문자열 또는 설정 객체)
+     * @example 'postgresql://user:pass@localhost:5432/db'
+     */
+    config: string | Record<string, unknown>;
+}
+/**
+ * 큐 설정
+ */
+interface QueueConfig {
+    /** 큐 이름 */
+    name: string;
+    /** 동시 처리 작업 수 (기본값: 10) */
+    concurrency?: number;
+    /** 우선순위 (높을수록 먼저 처리, 기본값: 50) */
+    priority?: number;
+    /** 초기 상태 */
+    state?: 'active' | 'paused';
+}
+/**
+ * 대시보드 설정
+ */
+interface DashboardConfig {
+    /** 활성화 여부 (기본값: false) */
+    enabled?: boolean;
+    /** 포트 (기본값: 8678) */
+    port?: number;
+    /** 경로 (기본값: '/') */
+    path?: string;
+    /** 기본 인증 */
+    auth?: {
+        user: string;
+        password: string;
+    };
+}
+/**
+ * 로거 설정
+ */
+interface LoggerConfig {
+    /** 로그 레벨 */
+    level?: 'debug' | 'info' | 'warn' | 'error';
+    /** JSON 형식 출력 여부 */
+    json?: boolean;
+}
+/**
+ * Graceful Shutdown 설정
+ */
+interface GracefulShutdownConfig {
+    /** 활성화 여부 (기본값: true) */
+    enabled?: boolean;
+    /** 타임아웃 (ms, 기본값: 30000) */
+    timeout?: number;
+}
+/**
+ * SidequestModule 옵션
+ */
+interface SidequestModuleOptions {
+    /**
+     * 전역 모듈 여부 (기본값: true)
+     */
+    isGlobal?: boolean;
+    /**
+     * 데이터베이스 백엔드 설정
+     */
+    backend: BackendConfig;
+    /**
+     * 큐 설정 목록
+     */
+    queues?: QueueConfig[];
+    /**
+     * 최대 동시 작업 수 (전체, 기본값: 10)
+     */
+    maxConcurrentJobs?: number;
+    /**
+     * 최소 워커 스레드 수 (기본값: CPU 코어 수)
+     */
+    minThreads?: number;
+    /**
+     * 최대 워커 스레드 수 (기본값: minThreads * 2)
+     */
+    maxThreads?: number;
+    /**
+     * Job 폴링 간격 (ms, 기본값: 100)
+     */
+    jobPollingInterval?: number;
+    /**
+     * 오래된 Job 해제 간격 (분, 기본값: 60)
+     */
+    releaseStaleJobsIntervalMin?: number;
+    /**
+     * 완료된 Job 정리 간격 (분, 기본값: 60)
+     */
+    cleanupFinishedJobsIntervalMin?: number;
+    /**
+     * 로거 설정
+     */
+    logger?: LoggerConfig;
+    /**
+     * 대시보드 설정
+     */
+    dashboard?: DashboardConfig;
+    /**
+     * Graceful Shutdown 설정
+     */
+    gracefulShutdown?: GracefulShutdownConfig;
+    /**
+     * CLS(Continuation Local Storage) 통합 활성화 (기본값: false)
+     * nestjs-cls가 설치되어 있어야 함
+     */
+    enableCls?: boolean;
+}
+/**
+ * SidequestModule 비동기 옵션
+ */
+interface SidequestModuleAsyncOptions extends Pick<ModuleMetadata, 'imports'> {
+    /**
+     * 전역 모듈 여부 (기본값: true)
+     */
+    isGlobal?: boolean;
+    /**
+     * 팩토리 함수
+     */
+    useFactory?: (...args: unknown[]) => Promise<SidequestModuleOptions> | SidequestModuleOptions;
+    /**
+     * 주입할 프로바이더
+     */
+    inject?: (InjectionToken | OptionalFactoryDependency)[];
+    /**
+     * 옵션 팩토리 클래스
+     */
+    useClass?: Type<SidequestOptionsFactory>;
+    /**
+     * 기존 옵션 팩토리 사용
+     */
+    useExisting?: Type<SidequestOptionsFactory>;
+}
+/**
+ * SidequestModule 옵션 팩토리 인터페이스
+ */
+interface SidequestOptionsFactory {
+    createSidequestOptions(): Promise<SidequestModuleOptions> | SidequestModuleOptions;
+}
+
+/**
+ * SidequestModule
+ *
+ * NestJS에서 Sidequest.js를 사용하기 위한 메인 모듈입니다.
+ *
+ * @example
+ * ```typescript
+ * // 동기 설정
+ * @Module({
+ *   imports: [
+ *     SidequestModule.forRoot({
+ *       backend: {
+ *         driver: '@sidequest/postgres-backend',
+ *         config: process.env.DATABASE_URL,
+ *       },
+ *       queues: [
+ *         { name: 'email', concurrency: 5 },
+ *         { name: 'report', concurrency: 2 },
+ *       ],
+ *     }),
+ *   ],
+ * })
+ * export class AppModule {}
+ *
+ * // 비동기 설정 (ConfigService 사용)
+ * @Module({
+ *   imports: [
+ *     SidequestModule.forRootAsync({
+ *       imports: [ConfigModule],
+ *       useFactory: (config: ConfigService) => ({
+ *         backend: {
+ *           driver: '@sidequest/postgres-backend',
+ *           config: config.get('DATABASE_URL'),
+ *         },
+ *         queues: [{ name: 'default' }],
+ *       }),
+ *       inject: [ConfigService],
+ *     }),
+ *   ],
+ * })
+ * export class AppModule {}
+ * ```
+ */
+declare class SidequestModule {
+    /**
+     * 동기 설정으로 모듈 등록
+     */
+    static forRoot(options: SidequestModuleOptions): DynamicModule;
+    /**
+     * 비동기 설정으로 모듈 등록
+     */
+    static forRootAsync(asyncOptions: SidequestModuleAsyncOptions): DynamicModule;
+    /**
+     * 큐별 DI 프로바이더 생성
+     */
+    private static createQueueProviders;
+    /**
+     * 비동기 프로바이더 생성
+     */
+    private static createAsyncProviders;
+}
+
+/**
+ * @Processor 데코레이터 옵션
+ */
+interface ProcessorOptions {
+    /**
+     * 동시 처리 작업 수 (큐 설정 오버라이드)
+     */
+    concurrency?: number;
+}
+/**
+ * 프로세서 메타데이터
+ */
+interface ProcessorMetadata {
+    /** 큐 이름 */
+    queueName: string;
+    /** 프로세서 옵션 */
+    options?: ProcessorOptions;
+}
+/**
+ * @OnJob 데코레이터 옵션
+ */
+interface OnJobOptions {
+    /**
+     * Job 우선순위 (높을수록 먼저 처리)
+     */
+    priority?: number;
+    /**
+     * 최대 실행 시간 (ms)
+     */
+    timeout?: number;
+}
+/**
+ * OnJob 핸들러 메타데이터
+ */
+interface OnJobMetadata {
+    /** Job 이름 */
+    jobName: string;
+    /** Job 옵션 */
+    options?: OnJobOptions;
+}
+/**
+ * 등록된 핸들러 정보
+ */
+interface RegisteredHandler {
+    /** 메서드 이름 */
+    methodName: string;
+    /** Job 이름 */
+    jobName: string;
+    /** Job 옵션 */
+    options?: OnJobOptions;
+    /** 재시도 옵션 */
+    retryOptions?: RetryOptions;
+}
+/**
+ * 재시도 옵션
+ */
+interface RetryOptions {
+    /**
+     * 최대 시도 횟수 (기본값: 3)
+     */
+    maxAttempts?: number;
+    /**
+     * 재시도 지연 시간 (ms, 기본값: 1000)
+     */
+    delay?: number;
+    /**
+     * 백오프 전략 (기본값: 'exponential')
+     */
+    backoff?: 'fixed' | 'exponential';
+}
+/**
+ * 등록된 프로세서 정보
+ */
+interface RegisteredProcessor {
+    /** 큐 이름 */
+    queueName: string;
+    /** 프로세서 인스턴스 */
+    instance: unknown;
+    /** 프로세서 클래스 */
+    metatype: Function;
+    /** 등록된 핸들러 맵 (jobName -> handler) */
+    handlers: Map<string, RegisteredHandler>;
+    /** 완료 이벤트 핸들러 맵 (jobName -> methodName) */
+    completeHandlers: Map<string, string>;
+    /** 실패 이벤트 핸들러 맵 (jobName -> methodName) */
+    failedHandlers: Map<string, string>;
+}
+
+/**
+ * 클래스를 Sidequest Job Processor로 지정합니다.
+ *
+ * @Processor 데코레이터가 붙은 클래스는 모듈 초기화 시 자동으로 스캔되어
+ * 해당 큐의 Job 핸들러로 등록됩니다.
+ *
+ * @param queueName - 처리할 큐 이름
+ * @param options - 프로세서 옵션
+ *
+ * @example
+ * ```typescript
+ * @Processor('email')
+ * export class EmailProcessor {
+ *   @OnJob('send-welcome-email')
+ *   async handleWelcomeEmail(job: JobContext) {
+ *     const { to, subject, body } = job.data;
+ *     await this.mailer.send({ to, subject, body });
+ *   }
+ * }
+ *
+ * // 동시성 설정과 함께
+ * @Processor('report', { concurrency: 2 })
+ * export class ReportProcessor {
+ *   @OnJob('generate-daily-report')
+ *   async handleDailyReport(job: JobContext) {
+ *     // 리포트 생성 로직
+ *   }
+ * }
+ * ```
+ */
+declare function Processor(queueName: string, options?: ProcessorOptions): ClassDecorator;
+
+/**
+ * 메서드를 특정 Job 타입의 핸들러로 지정합니다.
+ *
+ * @Processor 데코레이터가 붙은 클래스 내부에서 사용합니다.
+ * 해당 Job이 큐에서 처리될 때 이 메서드가 호출됩니다.
+ *
+ * @param jobName - Job 이름 (일반적으로 Job 클래스명)
+ * @param options - Job 실행 옵션 (우선순위, 타임아웃 등)
+ *
+ * @example
+ * ```typescript
+ * @Processor('email')
+ * export class EmailProcessor {
+ *   @OnJob('SendWelcomeEmailJob')
+ *   async handleWelcomeEmail(job: JobContext) {
+ *     const { to, subject, body } = job.data;
+ *     await this.mailer.send({ to, subject, body });
+ *   }
+ *
+ *   // 우선순위와 타임아웃 설정
+ *   @OnJob('SendPriorityEmailJob', { priority: 100, timeout: 5000 })
+ *   async handlePriorityEmail(job: JobContext) {
+ *     // 우선순위가 높은 이메일 처리
+ *   }
+ * }
+ * ```
+ */
+declare function OnJob(jobName: string, options?: OnJobOptions): MethodDecorator;
+
+/**
+ * Job 재시도 정책을 설정합니다.
+ *
+ * @OnJob 데코레이터와 함께 사용하여 Job 실패 시 재시도 동작을 정의합니다.
+ *
+ * @param options - 재시도 옵션
+ *
+ * @example
+ * ```typescript
+ * @Processor('payment')
+ * export class PaymentProcessor {
+ *   // 고정 지연 재시도
+ *   @OnJob('ProcessPaymentJob')
+ *   @Retry({ maxAttempts: 3, delay: 1000 })
+ *   async handlePayment(job: JobContext) {
+ *     // 결제 처리 로직
+ *   }
+ *
+ *   // 지수 백오프 재시도
+ *   @OnJob('RefundJob')
+ *   @Retry({ maxAttempts: 5, delay: 500, backoff: 'exponential' })
+ *   async handleRefund(job: JobContext) {
+ *     // 환불 처리 로직
+ *   }
+ * }
+ * ```
+ */
+declare function Retry(options: RetryOptions): MethodDecorator;
+
+/**
+ * Queue 인스턴스를 주입합니다.
+ *
+ * SidequestModule.forRoot()에서 등록된 큐를 서비스에 주입받아 사용할 수 있습니다.
+ *
+ * @param queueName - 주입받을 큐 이름
+ *
+ * @example
+ * ```typescript
+ * @Injectable()
+ * export class UserService {
+ *   constructor(
+ *     @InjectQueue('email') private emailQueue: IQueueService,
+ *     @InjectQueue('notification') private notificationQueue: IQueueService,
+ *   ) {}
+ *
+ *   async createUser(email: string, name: string) {
+ *     // 사용자 생성 로직...
+ *
+ *     // 환영 이메일 발송
+ *     await this.emailQueue.add(SendWelcomeEmailJob, email, `Welcome, ${name}!`);
+ *
+ *     // 알림 발송
+ *     await this.notificationQueue.add(SendNotificationJob, email, 'new-user');
+ *   }
+ * }
+ * ```
+ */
+declare function InjectQueue(queueName: string): ParameterDecorator;
+
+/**
+ * Job 완료 이벤트 핸들러를 지정합니다.
+ *
+ * @Processor 클래스 내부에서 사용하며, Job이 성공적으로 완료되면 호출됩니다.
+ *
+ * @param jobName - 대상 Job 이름 (생략 시 모든 Job에 대해 호출)
+ *
+ * @example
+ * ```typescript
+ * @Processor('email')
+ * export class EmailProcessor {
+ *   @OnJob('SendWelcomeEmailJob')
+ *   async handleWelcomeEmail(job: JobContext) {
+ *     await this.mailer.send(job.data);
+ *   }
+ *
+ *   // 특정 Job 완료 이벤트
+ *   @OnJobComplete('SendWelcomeEmailJob')
+ *   async onWelcomeEmailComplete(event: JobCompleteEvent) {
+ *     this.logger.log(`환영 이메일 발송 완료: ${event.result}`);
+ *     await this.analytics.track('email_sent', { type: 'welcome' });
+ *   }
+ *
+ *   // 모든 Job 완료 이벤트 (jobName 생략)
+ *   @OnJobComplete()
+ *   async onAnyJobComplete(event: JobCompleteEvent) {
+ *     this.logger.log(`Job 완료: ${event.jobName}`);
+ *   }
+ * }
+ * ```
+ */
+declare function OnJobComplete(jobName?: string): MethodDecorator;
+/**
+ * Job 완료 이벤트 데이터
+ */
+interface JobCompleteEvent {
+    /** Job 이름 */
+    jobName: string;
+    /** Job 실행 인자 */
+    args: unknown[];
+    /** Job 실행 결과 */
+    result: unknown;
+}
+
+/**
+ * Job 실패 이벤트 핸들러를 지정합니다.
+ *
+ * @Processor 클래스 내부에서 사용하며, Job 실행이 실패하면 호출됩니다.
+ * 재시도 횟수를 모두 소진한 후 최종 실패 시에만 호출됩니다.
+ *
+ * @param jobName - 대상 Job 이름 (생략 시 모든 Job에 대해 호출)
+ *
+ * @example
+ * ```typescript
+ * @Processor('payment')
+ * export class PaymentProcessor {
+ *   @OnJob('ProcessPaymentJob')
+ *   @Retry({ maxAttempts: 3 })
+ *   async handlePayment(job: JobContext) {
+ *     await this.paymentService.process(job.data);
+ *   }
+ *
+ *   // 특정 Job 실패 이벤트
+ *   @OnJobFailed('ProcessPaymentJob')
+ *   async onPaymentFailed(event: JobFailedEvent) {
+ *     this.logger.error(`결제 처리 실패: ${event.error.message}`);
+ *     await this.alertService.notify('payment-failure', {
+ *       orderId: event.args[0],
+ *       error: event.error.message,
+ *     });
+ *   }
+ *
+ *   // 모든 Job 실패 이벤트 (jobName 생략)
+ *   @OnJobFailed()
+ *   async onAnyJobFailed(event: JobFailedEvent) {
+ *     this.logger.error(`Job 실패: ${event.jobName}`, event.error);
+ *   }
+ * }
+ * ```
+ */
+declare function OnJobFailed(jobName?: string): MethodDecorator;
+/**
+ * Job 실패 이벤트 데이터
+ */
+interface JobFailedEvent {
+    /** Job 이름 */
+    jobName: string;
+    /** Job 실행 인자 */
+    args: unknown[];
+    /** 발생한 에러 */
+    error: Error;
+}
+
+/**
+ * Queue 서비스 인터페이스
+ * @InjectQueue()로 주입되는 객체의 타입
+ */
+interface IQueueService {
+    /** 큐 이름 */
+    readonly name: string;
+    /**
+     * Job 추가
+     *
+     * @param JobClass - Job 클래스
+     * @param args - Job 실행 인자
+     * @returns Job ID
+     *
+     * @example
+     * ```typescript
+     * await this.emailQueue.add(SendEmailJob, 'user@example.com', 'Welcome!');
+     * ```
+     */
+    add<T>(JobClass: new (...args: unknown[]) => T, ...args: unknown[]): Promise<string>;
+    /**
+     * Job 추가 (옵션 포함)
+     *
+     * @param JobClass - Job 클래스
+     * @param options - Job 옵션
+     * @param args - Job 실행 인자
+     * @returns Job ID
+     *
+     * @example
+     * ```typescript
+     * await this.emailQueue.addWithOptions(
+     *   SendEmailJob,
+     *   { priority: 10, timeout: 5000 },
+     *   'user@example.com',
+     *   'Welcome!'
+     * );
+     * ```
+     */
+    addWithOptions<T>(JobClass: new (...args: unknown[]) => T, options: JobAddOptions, ...args: unknown[]): Promise<string>;
+    /**
+     * 예약된 Job 추가
+     *
+     * @param JobClass - Job 클래스
+     * @param scheduledAt - 실행 예정 시간
+     * @param args - Job 실행 인자
+     * @returns Job ID
+     *
+     * @example
+     * ```typescript
+     * const tomorrow = new Date();
+     * tomorrow.setDate(tomorrow.getDate() + 1);
+     * await this.emailQueue.addScheduled(SendEmailJob, tomorrow, 'user@example.com');
+     * ```
+     */
+    addScheduled<T>(JobClass: new (...args: unknown[]) => T, scheduledAt: Date, ...args: unknown[]): Promise<string>;
+    /**
+     * Bulk Job 추가
+     *
+     * @param jobs - Job 목록
+     * @returns Job ID 배열
+     */
+    addBulk<T>(jobs: Array<{
+        JobClass: new (...args: unknown[]) => T;
+        args: unknown[];
+        options?: JobAddOptions;
+    }>): Promise<string[]>;
+}
+/**
+ * Job 추가 옵션
+ */
+interface JobAddOptions {
+    /**
+     * 우선순위 (높을수록 먼저 처리)
+     */
+    priority?: number;
+    /**
+     * 최대 실행 시간 (ms)
+     */
+    timeout?: number;
+    /**
+     * 최대 시도 횟수
+     */
+    maxAttempts?: number;
+    /**
+     * 재시도 간격 (ms, 기본값: 1000)
+     */
+    retryDelay?: number;
+    /**
+     * 백오프 전략
+     */
+    backoffStrategy?: 'fixed' | 'exponential';
+    /**
+     * 고유성 키 (중복 방지)
+     */
+    uniqueKey?: string;
+    /**
+     * 예약 실행 시간
+     */
+    scheduledAt?: Date;
+    /**
+     * 메타데이터 (traceId 등)
+     */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * 에러 데이터
+ */
+interface ErrorData {
+    /** 에러 이름 */
+    name?: string | null;
+    /** 에러 메시지 */
+    message?: string | null;
+    /** 스택 트레이스 */
+    stack?: string | null;
+    /** 추가 데이터 */
+    [key: string]: unknown;
+}
+/**
+ * Job 정보
+ */
+interface JobInfo {
+    /** Job ID */
+    id: string;
+    /** 큐 이름 */
+    queue: string;
+    /** Job 이름 */
+    name?: string;
+    /** 현재 상태 */
+    state: JobState;
+    /** 시도 횟수 */
+    attempt: number;
+    /** 최대 시도 횟수 */
+    maxAttempts: number;
+    /** 실행 인자 */
+    args?: unknown[];
+    /** 실행 결과 */
+    result?: unknown;
+    /** 발생한 에러 목록 */
+    errors?: ErrorData[] | null;
+    /** 생성 시간 */
+    insertedAt: Date;
+    /** 시도 시간 */
+    attemptedAt?: Date;
+    /** 완료 시간 */
+    completedAt?: Date;
+    /** 메타데이터 */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Job 상태
+ */
+type JobState = 'available' | 'scheduled' | 'executing' | 'completed' | 'failed' | 'discarded' | 'cancelled';
+
+type JobClassType = new (...args: unknown[]) => Job;
+/**
+ * Sidequest.js API Adapter
+ *
+ * Sidequest.js의 API를 NestJS와 통합합니다.
+ * 실제 sidequest 패키지를 사용하여 Job 처리를 수행합니다.
+ */
+declare class SidequestAdapter {
+    private readonly logger;
+    private isStarted;
+    private readonly registeredJobs;
+    /**
+     * Sidequest 엔진 시작
+     */
+    start(options: SidequestModuleOptions): Promise<void>;
+    /**
+     * Sidequest 엔진 종료
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Job 클래스 등록
+     */
+    registerJob(jobName: string, JobClass: JobClassType): void;
+    /**
+     * Job 추가
+     */
+    addJob(queueName: string, jobName: string, args: unknown[], options?: JobAddOptions): Promise<string>;
+    /**
+     * Bulk Job 추가
+     */
+    addBulkJobs(queueName: string, jobs: Array<{
+        jobName: string;
+        args: unknown[];
+        options?: JobAddOptions;
+    }>): Promise<string[]>;
+    /**
+     * Job 조회
+     */
+    getJob(jobId: string | number): Promise<JobInfo | undefined>;
+    /**
+     * 엔진 시작 여부
+     */
+    get started(): boolean;
+    /**
+     * 등록된 Job 클래스 반환
+     */
+    getRegisteredJob(jobName: string): JobClassType | undefined;
+    /**
+     * 모든 등록된 Job 클래스 반환
+     */
+    getAllRegisteredJobs(): Map<string, JobClassType>;
+}
+
+/**
+ * Sidequest 엔진 관리 서비스
+ *
+ * Sidequest.js 엔진의 라이프사이클을 관리합니다.
+ * 모듈 초기화 시 엔진을 시작하고, 종료 시 graceful shutdown을 수행합니다.
+ */
+declare class SidequestEngineService implements OnModuleInit, OnModuleDestroy {
+    private readonly options;
+    private readonly adapter;
+    private readonly logger;
+    constructor(options: SidequestModuleOptions, adapter: SidequestAdapter);
+    /**
+     * 모듈 초기화 시 엔진 시작
+     */
+    onModuleInit(): Promise<void>;
+    /**
+     * 모듈 종료 시 엔진 종료
+     */
+    onModuleDestroy(): Promise<void>;
+    /**
+     * 엔진 시작 여부
+     */
+    get isStarted(): boolean;
+    /**
+     * Adapter 인스턴스 반환
+     */
+    getAdapter(): SidequestAdapter;
+}
+
+/**
+ * Queue 레지스트리 서비스
+ *
+ * 큐 인스턴스를 관리하고 @InjectQueue()를 위한 DI 프로바이더를 제공합니다.
+ */
+declare class QueueRegistryService {
+    private readonly options;
+    private readonly adapter;
+    private readonly logger;
+    private readonly queueServices;
+    constructor(options: SidequestModuleOptions, adapter: SidequestAdapter);
+    /**
+     * 설정된 큐 초기화
+     */
+    private initializeQueues;
+    /**
+     * 큐 등록
+     */
+    registerQueue(config: QueueConfig): void;
+    /**
+     * 큐 서비스 조회
+     */
+    getQueue(name: string): IQueueService | undefined;
+    /**
+     * 큐 서비스 조회 (없으면 에러)
+     */
+    getQueueOrThrow(name: string): IQueueService;
+    /**
+     * 모든 큐 조회
+     */
+    getAllQueues(): Map<string, IQueueService>;
+    /**
+     * 큐 서비스 인스턴스 생성
+     */
+    private createQueueService;
+}
+
+interface ClsService {
+    getId(): string | undefined;
+    get<T>(key: string): T | undefined;
+    set<T>(key: string, value: T): void;
+    run<T>(callback: () => T): T;
+}
+/**
+ * CLS(Continuation Local Storage) 통합 서비스
+ *
+ * nestjs-cls가 설치되어 있을 경우 Job 실행 시 context를 전파합니다.
+ * nestjs-cls가 없으면 no-op으로 동작합니다.
+ */
+declare class ClsIntegrationService {
+    private readonly logger;
+    private readonly enabled;
+    private clsService;
+    constructor(options: SidequestModuleOptions, clsService?: ClsService);
+    /**
+     * CLS context 내에서 콜백 실행
+     */
+    runInContext<T>(metadata: Record<string, unknown>, callback: () => Promise<T>): Promise<T>;
+    /**
+     * 현재 traceId 조회
+     */
+    getTraceId(): string | undefined;
+    /**
+     * traceId 설정
+     */
+    setTraceId(traceId: string): void;
+    /**
+     * CLS에서 값 조회
+     */
+    get<T>(key: string): T | undefined;
+    /**
+     * CLS에 값 설정
+     */
+    set<T>(key: string, value: T): void;
+    /**
+     * CLS 통합 활성화 여부
+     */
+    isEnabled(): boolean;
+}
+
+/**
+ * Processor 레지스트리 서비스
+ *
+ * @Processor 데코레이터로 등록된 프로세서와 핸들러를 관리합니다.
+ */
+declare class ProcessorRegistryService {
+    private readonly clsService?;
+    private readonly logger;
+    private readonly processors;
+    constructor(clsService?: ClsIntegrationService | undefined);
+    /**
+     * 프로세서 등록
+     */
+    register(processor: RegisteredProcessor): void;
+    /**
+     * 프로세서 조회
+     */
+    getProcessor(queueName: string): RegisteredProcessor | undefined;
+    /**
+     * 모든 프로세서 조회
+     */
+    getAllProcessors(): Map<string, RegisteredProcessor>;
+    /**
+     * Job 핸들러 조회
+     */
+    getJobHandler(queueName: string, jobName: string): RegisteredHandler | undefined;
+    /**
+     * Job 완료 핸들러 조회
+     */
+    getCompleteHandler(queueName: string, jobName: string): string | undefined;
+    /**
+     * Job 실패 핸들러 조회
+     */
+    getFailedHandler(queueName: string, jobName: string): string | undefined;
+    /**
+     * Job 디스패치 (실행)
+     *
+     * @param queueName - 큐 이름
+     * @param jobName - Job 이름
+     * @param args - Job 인자
+     * @param metadata - Job 메타데이터 (traceId 등)
+     */
+    dispatch(queueName: string, jobName: string, args: unknown[], metadata?: Record<string, unknown>): Promise<unknown>;
+}
+
+/**
+ * SidequestModule 상수
+ */
+declare const SIDEQUEST_MODULE_OPTIONS: unique symbol;
+declare const SIDEQUEST_ENGINE: unique symbol;
+declare const PROCESSOR_METADATA_KEY: unique symbol;
+declare const ON_JOB_METADATA_KEY: unique symbol;
+declare const RETRY_OPTIONS_METADATA_KEY: unique symbol;
+declare const ON_JOB_COMPLETE_METADATA_KEY: unique symbol;
+declare const ON_JOB_FAILED_METADATA_KEY: unique symbol;
+declare const QUEUE_TOKEN_PREFIX = "SIDEQUEST_QUEUE_";
+/**
+ * Queue DI 토큰 생성
+ */
+declare function getQueueToken(queueName: string): string;
+declare const DEFAULT_QUEUE_NAME = "default";
+declare const DEFAULT_MAX_ATTEMPTS = 3;
+declare const DEFAULT_TIMEOUT = 30000;
+declare const DEFAULT_CONCURRENCY = 10;
+
+export { type BackendConfig, ClsIntegrationService, DEFAULT_CONCURRENCY, DEFAULT_MAX_ATTEMPTS, DEFAULT_QUEUE_NAME, DEFAULT_TIMEOUT, type DashboardConfig, type GracefulShutdownConfig, type IQueueService, InjectQueue, type JobAddOptions, type JobCompleteEvent, type JobFailedEvent, type JobInfo, type JobState, ON_JOB_COMPLETE_METADATA_KEY, ON_JOB_FAILED_METADATA_KEY, ON_JOB_METADATA_KEY, OnJob, OnJobComplete, OnJobFailed, type OnJobMetadata, type OnJobOptions, PROCESSOR_METADATA_KEY, Processor, type ProcessorMetadata, type ProcessorOptions, ProcessorRegistryService, QUEUE_TOKEN_PREFIX, type QueueConfig, QueueRegistryService, RETRY_OPTIONS_METADATA_KEY, type RegisteredHandler, type RegisteredProcessor, Retry, type RetryOptions, SIDEQUEST_ENGINE, SIDEQUEST_MODULE_OPTIONS, SidequestAdapter, SidequestEngineService, SidequestModule, type SidequestModuleAsyncOptions, type SidequestModuleOptions, type SidequestOptionsFactory, getQueueToken };