@sidequest/engine/dist/engine.d.ts

@sidequest/engine is the core engine of SideQuest, a distributed background job processing system for Node.js and TypeScript.

import { BackendConfig, NewQueueData, Backend } from '@sidequest/backend';
import { LoggerOptions, JobClassType } from '@sidequest/core';
import { JobBuilderDefaults, JobBuilder } from './job/job-builder.js';
import { QueueDefaults } from './queue/grant-queue-config.js';

/**
 * Configuration options for the Sidequest engine.
 */
interface EngineConfig {
    /** Backend configuration. Defaults to `@sidequest/sqlite-backend` and `./sidequest.sqlite` file */
    backend?: BackendConfig;
    /** List of queue configurations. Defaults to `[]` */
    queues?: NewQueueData[];
    /** Logger configuration options. Defaults to `info` and no json */
    logger?: LoggerOptions;
    /** Maximum number of concurrent jobs. Defaults to `10` */
    maxConcurrentJobs?: number;
    /** Whether to skip migration when starting the engine. Defaults to `false` */
    skipMigration?: boolean;
    /** Frequency in minutes for releasing stale jobs. Set to false to disable. Defaults to 60 min */
    releaseStaleJobsIntervalMin?: number | false;
    /** Maximum age in milliseconds a running job must be to be considered a stale job. Defaults to 10 minutes */
    releaseStaleJobsMaxStaleMs?: number;
    /** Maximum age in milliseconds a claimed job must be to be considered stale. Defaults to 1 minute */
    releaseStaleJobsMaxClaimedMs?: number;
    /** Frequency in minutes for cleaning up finished jobs. Set to false to disable. Defaults to 60 min */
    cleanupFinishedJobsIntervalMin?: number | false;
    /** Time in milliseconds to clean up finished jobs older than this value. Defaults to 30 days */
    cleanupFinishedJobsOlderThan?: number;
    /** Whether to enable graceful shutdown handling. Defaults to `true` */
    gracefulShutdown?: boolean;
    /** Minimum number of worker threads to use. Defaults to number of CPUs */
    minThreads?: number;
    /** Maximum number of worker threads to use. Defaults to `minThreads * 2` */
    maxThreads?: number;
    /** Timeout in milliseconds for idle workers before they are terminated. Defaults to 10 seconds */
    idleWorkerTimeout?: number;
    /**
     * Default job builder configuration.
     * This allows setting default values for job properties like queue, timeout, uniqueness, etc.
     * If not provided during job build, defaults will be used.
     *
     * @see {@link JobBuilderDefaults} for more details
     */
    jobDefaults?: JobBuilderDefaults;
    /**
     * Default queue configuration.
     * This allows setting default values for queue properties like concurrency, priority, etc.
     * If not provided during queue creation, defaults will be used.
     *
     * @see {@link QueueDefaults} for more details
     */
    queueDefaults?: QueueDefaults;
}
/**
 * Non-nullable version of the EngineConfig type.
 * Ensures all properties are defined and not null.
 *
 * @see {@link EngineConfig} for the original type.
 */
type NonNullableEngineConfig = {
    [P in keyof EngineConfig]-?: NonNullable<EngineConfig[P]>;
};
/**
 * The main engine for managing job queues and workers in Sidequest.
 */
declare class Engine {
    /**
     * Backend instance used by the engine.
     * This is initialized when the engine is configured or started.
     */
    private backend?;
    /**
     * Current configuration of the engine.
     * This is set when the engine is configured or started.
     * It contains all the necessary settings for the engine to operate, such as backend, queues, logger options, and job defaults.
     */
    private config?;
    /**
     * Main worker process that runs the Sidequest engine.
     * This is created when the engine is started and handles job processing.
     */
    private mainWorker?;
    /**
     * Flag indicating whether the engine is currently shutting down.
     * This is used to prevent multiple shutdown attempts and ensure graceful shutdown behavior.
     */
    private shuttingDown;
    /**
     * Configures the Sidequest engine with the provided configuration.
     * @param config Optional configuration object.
     * @returns The resolved configuration.
     */
    configure(config?: EngineConfig): Promise<NonNullableEngineConfig>;
    /**
     * Starts the Sidequest engine and worker process.
     * @param config Optional configuration object.
     */
    start(config: EngineConfig): Promise<void>;
    /**
     * Gets the current engine configuration.
     * @returns The current configuration, if set.
     */
    getConfig(): NonNullableEngineConfig | undefined;
    /**
     * Gets the backend instance in use by the engine.
     * @returns The backend instance, if set.
     */
    getBackend(): Backend | undefined;
    /**
     * Closes the engine and releases resources.
     */
    close(): Promise<void>;
    /**
     * Builds a job using the provided job class.
     * @param JobClass The job class constructor.
     * @returns A new JobBuilder instance for the job class.
     */
    build<T extends JobClassType>(JobClass: T): JobBuilder<T>;
}

export { Engine };
export type { EngineConfig, NonNullableEngineConfig };