sidequest/dist/operations/queue.d.ts

Sidequest is a modern, scalable background job processor for Node.js applications.

import { Backend, NewQueueData } from '@sidequest/backend';
import { QueueConfig } from '@sidequest/core';

/**
 * Entry point for managing queues in Sidequest.
 *
 * Provides high-level methods for queue management operations including
 * state changes, concurrency updates, priority adjustments, and listing.
 */
declare class QueueOperations {
    /**
     * Backend instance from the Sidequest engine.
     * @returns The backend instance.
     * @throws Error if the engine is not configured.
     */
    private backend?;
    /**
     * Singleton instance of QueueOperations.
     * This allows for easy access to queue management methods without needing to instantiate the class.
     */
    static readonly instance: QueueOperations;
    /**
     * Private constructor to enforce singleton pattern.
     * Prevents instantiation from outside the class.
     */
    private constructor();
    /**
     * Sets the backend instance for the JobOperations.
     * This is typically called by the Sidequest engine during configuration.
     *
     * @param backend - The backend instance to set
     */
    setBackend(backend: Backend | undefined): void;
    /**
     * Gets the backend instance from the engine.
     * @returns The backend instance.
     * @throws Error if the engine is not configured.
     */
    private getBackend;
    /**
     * Toggles the queue state between active and paused.
     * If the queue is active, it will be paused. If it's paused, it will be activated.
     *
     * @param queueName - The name of the queue to toggle
     * @returns Promise resolving to the updated queue configuration
     * @throws Error if the queue is not found
     */
    toggle(queueName: string): Promise<QueueConfig>;
    /**
     * Pauses the specified queue.
     * Jobs already running will continue, but no new jobs will be started.
     *
     * @param queueName - The name of the queue to pause
     * @returns Promise resolving to the updated queue configuration
     * @throws Error if the queue is not found
     */
    pause(queueName: string): Promise<QueueConfig>;
    /**
     * Activates the specified queue.
     * The queue will resume processing jobs normally.
     *
     * @param queueName - The name of the queue to activate
     * @returns Promise resolving to the updated queue configuration
     * @throws Error if the queue is not found
     */
    activate(queueName: string): Promise<QueueConfig>;
    /**
     * Sets the concurrency limit for the specified queue.
     * This controls the maximum number of jobs that can run concurrently in this queue.
     *
     * @param queueName - The name of the queue to update
     * @param concurrency - The new concurrency limit (must be positive)
     * @returns Promise resolving to the updated queue configuration
     * @throws Error if the queue is not found or concurrency is invalid
     */
    setConcurrency(queueName: string, concurrency: number): Promise<QueueConfig>;
    /**
     * Sets the priority for the specified queue.
     * Higher priority queues are processed before lower priority ones.
     *
     * @param queueName - The name of the queue to update
     * @param priority - The new priority value (higher values = higher priority)
     * @returns Promise resolving to the updated queue configuration
     * @throws Error if the queue is not found
     */
    setPriority(queueName: string, priority: number): Promise<QueueConfig>;
    /**
     * Creates a new queue with the specified configuration.
     *
     * @param queueData - The queue configuration data
     * @param queueData.name - The unique name for the queue (required)
     * @param queueData.concurrency - The maximum number of concurrent jobs (optional, defaults to backend fallback)
     * @param queueData.priority - The queue priority (optional, defaults to backend fallback)
     * @param queueData.state - The initial queue state (optional, defaults to backend fallback)
     * @returns Promise resolving to the created queue configuration
     * @throws Error if a queue with the same name already exists
     */
    create(queueData: NewQueueData): Promise<QueueConfig>;
    /**
     * Gets the configuration for a specific queue by name.
     *
     * @param queueName - The name of the queue to retrieve
     * @returns Promise resolving to the queue configuration if found, undefined otherwise
     */
    get(queueName: string): Promise<QueueConfig | undefined>;
    /**
     * Lists all queues with optional ordering.
     *
     * @param orderBy - Optional ordering configuration
     * @param orderBy.column - The column to order by (defaults to 'priority')
     * @param orderBy.order - The order direction (defaults to 'desc')
     * @returns Promise resolving to an array of queue configurations
     */
    list(orderBy?: {
        column?: keyof QueueConfig;
        order?: "asc" | "desc";
    }): Promise<QueueConfig[]>;
}

export { QueueOperations };