@penkov/tasks_queue/dist/manage.model.d.ts

A lightweight PostgreSQL-backed task queue system with scheduling, retries, backoff strategies, and priority handling. Designed for efficiency and observability in modern Node.js applications.

import { Collection, Option } from "scats";
import { BackoffType, MissedRunStrategy, TaskPeriodType, TaskStatus } from "./tasks-model.js";
/**
 * Rich management DTO representing a single task row.
 *
 * This shape is used by {@link ManageTasksQueueService} and preserves optional
 * database fields as `Option` values for server-side consumers.
 *
 * See also {@link TaskView} for a plain JSON / Swagger-friendly representation.
 */
export declare class TaskDto {
    /**
     * Persistent task id.
     */
    readonly id: number;
    /**
     * Parent task id for child tasks, otherwise `none`.
     */
    readonly parentId: Option<number>;
    /**
     * Queue name the task belongs to.
     */
    readonly queue: string;
    /**
     * Row creation time.
     */
    readonly created: Date;
    /**
     * Original schedule anchor used for periodic tasks and wait-time metrics.
     */
    readonly initialStart: Date;
    /**
     * Start time of the currently persisted attempt, if any.
     */
    readonly started: Option<Date>;
    /**
     * Last heartbeat time for the currently persisted attempt, if any.
     */
    readonly lastHeartbeat: Option<Date>;
    /**
     * Terminal or retry-transition finish time, if the task is not currently active.
     */
    readonly finished: Option<Date>;
    /**
     * Current persistent task status.
     */
    readonly status: TaskStatus;
    /**
     * Periodic missed-run strategy in effect for this task.
     */
    readonly missedRunStrategy: MissedRunStrategy;
    /**
     * Queue priority used among eligible pending tasks.
     */
    readonly priority: number;
    /**
     * Last persisted error message, if any.
     */
    readonly error: Option<string>;
    /**
     * Base retry backoff in milliseconds.
     */
    readonly backoff: number;
    /**
     * Retry backoff formula.
     */
    readonly backoffType: BackoffType;
    /**
     * Attempt timeout in milliseconds.
     */
    readonly timeout: number;
    /**
     * Unique periodic task name, if this task is periodic.
     */
    readonly name: Option<string>;
    /**
     * Earliest time when the task may start again.
     */
    readonly startAfter: Option<Date>;
    /**
     * Repeat interval in milliseconds for interval-based periodic tasks.
     */
    readonly repeatInterval: Option<number>;
    /**
     * Cron expression for cron-based periodic tasks.
     */
    readonly cronExpression: Option<string>;
    /**
     * Periodic scheduling mode, if any.
     */
    readonly repeatType: Option<TaskPeriodType>;
    /**
     * Maximum attempts allowed for this task.
     */
    readonly maxAttempts: number;
    /**
     * Persisted attempt counter.
     */
    readonly attempt: number;
    /**
     * Persisted worker input and runtime state.
     */
    readonly payload: any;
    /**
     * Persisted final result, if any.
     */
    readonly result: any;
    constructor(
    /**
     * Persistent task id.
     */
    id: number, 
    /**
     * Parent task id for child tasks, otherwise `none`.
     */
    parentId: Option<number>, 
    /**
     * Queue name the task belongs to.
     */
    queue: string, 
    /**
     * Row creation time.
     */
    created: Date, 
    /**
     * Original schedule anchor used for periodic tasks and wait-time metrics.
     */
    initialStart: Date, 
    /**
     * Start time of the currently persisted attempt, if any.
     */
    started: Option<Date>, 
    /**
     * Last heartbeat time for the currently persisted attempt, if any.
     */
    lastHeartbeat: Option<Date>, 
    /**
     * Terminal or retry-transition finish time, if the task is not currently active.
     */
    finished: Option<Date>, 
    /**
     * Current persistent task status.
     */
    status: TaskStatus, 
    /**
     * Periodic missed-run strategy in effect for this task.
     */
    missedRunStrategy: MissedRunStrategy, 
    /**
     * Queue priority used among eligible pending tasks.
     */
    priority: number, 
    /**
     * Last persisted error message, if any.
     */
    error: Option<string>, 
    /**
     * Base retry backoff in milliseconds.
     */
    backoff: number, 
    /**
     * Retry backoff formula.
     */
    backoffType: BackoffType, 
    /**
     * Attempt timeout in milliseconds.
     */
    timeout: number, 
    /**
     * Unique periodic task name, if this task is periodic.
     */
    name: Option<string>, 
    /**
     * Earliest time when the task may start again.
     */
    startAfter: Option<Date>, 
    /**
     * Repeat interval in milliseconds for interval-based periodic tasks.
     */
    repeatInterval: Option<number>, 
    /**
     * Cron expression for cron-based periodic tasks.
     */
    cronExpression: Option<string>, 
    /**
     * Periodic scheduling mode, if any.
     */
    repeatType: Option<TaskPeriodType>, 
    /**
     * Maximum attempts allowed for this task.
     */
    maxAttempts: number, 
    /**
     * Persisted attempt counter.
     */
    attempt: number, 
    /**
     * Persisted worker input and runtime state.
     */
    payload: any, 
    /**
     * Persisted final result, if any.
     */
    result: any);
}
/**
 * Paginated collection returned by {@link ManageTasksQueueService.findByParameters}.
 */
export declare class TasksResult {
    /**
     * Page items in the requested order.
     */
    readonly items: Collection<TaskDto>;
    /**
     * Total number of matching rows before pagination.
     */
    readonly total: number;
    constructor(
    /**
     * Page items in the requested order.
     */
    items: Collection<TaskDto>, 
    /**
     * Total number of matching rows before pagination.
     */
    total: number);
}
/**
 * Fields supported by {@link FindTasksParameters.sortBy}.
 */
export declare enum TaskDateSortField {
    id = "id",
    created = "created",
    initialStart = "initial_start",
    started = "started",
    lastHeartbeat = "last_heartbeat",
    finished = "finished",
    startAfter = "start_after"
}
/**
 * Sort direction supported by task search.
 */
export declare enum TaskSortDirection {
    asc = "asc",
    desc = "desc"
}
/**
 * Search parameters for listing tasks from the management API.
 */
export interface FindTasksParameters {
    /**
     * Optional task status filter.
     */
    status?: TaskStatus;
    /**
     * Optional queue name filter.
     */
    queue?: string;
    /**
     * Optional periodic task filter.
     *
     * Periodic tasks are identified by a non-null unique `name`.
     */
    isPeriodic?: boolean;
    /**
     * Optional field to order the result by.
     *
     * Defaults to {@link TaskDateSortField.created}.
     */
    sortBy?: TaskDateSortField;
    /**
     * Optional sort direction.
     *
     * Defaults to {@link TaskSortDirection.desc}.
     */
    sortDirection?: TaskSortDirection;
    /**
     * Pagination offset.
     */
    offset: number;
    /**
     * Pagination limit.
     */
    limit: number;
}
/**
 * Full editable configuration for a pending task.
 *
 * This model is intended for "read task -> modify fields -> submit updated state"
 * workflows, so all values are required explicitly instead of being patch-style optional.
 */
export interface UpdatePendingTaskDetails {
    /**
     * Earliest time when the task may be picked up by a worker.
     * Set to null to make the task eligible immediately.
     */
    startAfter: Date | null;
    /**
     * Higher values are fetched first among pending tasks.
     */
    priority: number;
    /**
     * Maximum execution time in milliseconds before the task is considered stalled.
     */
    timeout: number;
    /**
     * Payload to pass to the worker. Can be null to clear the payload.
     */
    payload: any;
    /**
     * Maximum number of processing attempts for the task.
     */
    retries: number;
    /**
     * Base delay in milliseconds before retrying a failed task.
     */
    backoff: number;
    /**
     * Strategy used to calculate retry delay.
     */
    backoffType: BackoffType;
}
/**
 * Full editable periodic schedule for a pending periodic task.
 *
 * The shape is discriminated by repeat type so interval-based and cron-based
 * schedules remain mutually exclusive.
 */
export type UpdatePendingPeriodicScheduleDetails = {
    /**
     * Earliest time for the next execution according to the edited schedule.
     */
    startAfter: Date;
    /**
     * Fixed schedule anchor used by periodic scheduling logic.
     */
    initialStart: Date;
    /**
     * Periodic mode that uses a repeat interval in milliseconds.
     */
    repeatType: TaskPeriodType.fixed_rate | TaskPeriodType.fixed_delay;
    /**
     * Interval in milliseconds between task executions.
     */
    period: number;
    /**
     * Strategy for handling runs missed while the task could not execute.
     */
    missedRunStrategy: MissedRunStrategy;
} | {
    /**
     * Earliest time for the next execution according to the edited schedule.
     */
    startAfter: Date;
    /**
     * Fixed schedule anchor used by periodic scheduling logic.
     */
    initialStart: Date;
    /**
     * Periodic mode that uses a cron expression.
     */
    repeatType: TaskPeriodType.cron;
    /**
     * Cron expression in 5-field or 6-field format.
     */
    cronExpression: string;
    /**
     * Strategy for handling runs missed while the task could not execute.
     */
    missedRunStrategy: MissedRunStrategy;
};
/**
 * Plain JSON representation of {@link TaskDto} intended for HTTP APIs and Swagger schemas.
 */
export declare class TaskView {
    id: number;
    parentId?: number;
    queue: string;
    created: number;
    initialStart: number;
    started?: number;
    lastHeartbeat?: number;
    finished?: number;
    status: TaskStatus;
    missedRunStrategy: MissedRunStrategy;
    priority: number;
    error?: string;
    backoff: number;
    backoffType: BackoffType;
    timeout: number;
    name?: string;
    startAfter?: number;
    repeatInterval?: number;
    cronExpression?: string;
    repeatType?: TaskPeriodType;
    maxAttempts: number;
    attempt: number;
    payload: any;
    result?: any;
    /**
     * Convert a rich DTO into a plain JSON-friendly view.
     *
     * @param dto management DTO
     * @returns converted API view
     */
    static fromDto(dto: TaskDto): TaskView;
}
/**
 * Plain JSON representation of {@link TasksResult}.
 */
export declare class TasksResultView {
    items: TaskView[];
    total: number;
}
/**
 * Queue-level percentile statistics used by operational dashboards.
 *
 * Produced by {@link ManageTasksQueueService.waitTimeByQueue} and
 * {@link ManageTasksQueueService.workTimeByQueue}.
 */
export declare class QueueStat {
    /**
     * Queue name these percentiles belong to.
     */
    readonly queueName: string;
    /**
     * 50th percentile in seconds.
     */
    readonly p50: number;
    /**
     * 75th percentile in seconds.
     */
    readonly p75: number;
    /**
     * 95th percentile in seconds.
     */
    readonly p95: number;
    /**
     * 99th percentile in seconds.
     */
    readonly p99: number;
    /**
     * 99.9th percentile in seconds.
     */
    readonly p999: number;
    constructor(
    /**
     * Queue name these percentiles belong to.
     */
    queueName: string, 
    /**
     * 50th percentile in seconds.
     */
    p50: number, 
    /**
     * 75th percentile in seconds.
     */
    p75: number, 
    /**
     * 95th percentile in seconds.
     */
    p95: number, 
    /**
     * 99th percentile in seconds.
     */
    p99: number, 
    /**
     * 99.9th percentile in seconds.
     */
    p999: number);
}
/**
 * Queue/status aggregate used for management dashboards and metrics sync.
 */
export declare class TasksCount {
    /**
     * Queue name.
     */
    readonly queueName: string;
    /**
     * Task status represented by this count.
     */
    readonly status: TaskStatus;
    /**
     * Number of rows in this queue/status bucket.
     */
    readonly count: number;
    constructor(
    /**
     * Queue name.
     */
    queueName: string, 
    /**
     * Task status represented by this count.
     */
    status: TaskStatus, 
    /**
     * Number of rows in this queue/status bucket.
     */
    count: number);
}
/**
 * Plain JSON view of {@link QueueStat}.
 */
export declare class QueueStatView {
    queueName: string;
    p50: number;
    p75: number;
    p95: number;
    p99: number;
    p999: number;
    /**
     * Convert a queue-stat DTO into a plain API view.
     *
     * @param o queue statistics DTO
     * @returns converted API view
     */
    static fromDto(o: QueueStat): QueueStatView;
}
/**
 * Plain JSON view of {@link TasksCount}.
 */
export declare class TasksCountView {
    queueName: string;
    status: TaskStatus;
    count: number;
    /**
     * Convert a queue-count DTO into a plain API view.
     *
     * @param o tasks-count DTO
     * @returns converted API view
     */
    static fromDto(o: TasksCount): TasksCountView;
}
/**
 * Combined queue statistics response shape used by HTTP APIs.
 */
export declare class QueuesStat {
    waitTime: QueueStatView[];
    workTime: QueueStatView[];
    tasksCount: TasksCountView[];
}