@tstdl/base 0.93.77 → 0.93.78

package/queue/postgres/queue.provider.d.ts

@@ -3,5 +3,5 @@ import type { ObjectLiteral } from '../../types/index.js';
 import { PostgresQueue } from './queue.js';
 export declare class PostgresQueueProvider extends QueueProvider {
     #private;
-    get<T extends ObjectLiteral>(name: string, config?: QueueConfig): PostgresQueue<T>;
+    get<Data extends ObjectLiteral, State extends ObjectLiteral, Result extends ObjectLiteral>(name: string, config?: QueueConfig): PostgresQueue<Data, State, Result>;
 }

package/queue/postgres/schemas.d.ts

@@ -1,3 +1,14 @@
-import { PostgresJob } from './job.model.js';
+import { PostgresTask } from './task.model.js';
 export declare const queueSchema: import("../../orm/server/index.js").DatabaseSchema<"queue">;
-export declare const job: import("../../orm/server/types.js").PgTableFromType<typeof PostgresJob, "queue">;
+export declare const taskState: import("../../orm/enums.js").PgEnumFromEnumeration<{
+    readonly Pending: "pending";
+    readonly Running: "running";
+    readonly Completed: "completed";
+    readonly Cancelled: "cancelled";
+    readonly Waiting: "waiting";
+    readonly Dead: "dead";
+}>;
+export declare const task: import("../../orm/server/types.js").PgTableFromType<{
+    new (): PostgresTask<any, any, any>;
+    readonly entityName: "Task";
+}, "queue">;

package/queue/postgres/schemas.js

@@ -1,4 +1,6 @@
 import { databaseSchema } from '../../orm/server/index.js';
-import { PostgresJob } from './job.model.js';
+import { TaskState } from '../queue.js';
+import { PostgresTask } from './task.model.js';
 export const queueSchema = databaseSchema('queue');
-export const job = queueSchema.getTable(PostgresJob);
+export const taskState = queueSchema.getEnum(TaskState);
+export const task = queueSchema.getTable((PostgresTask));

package/queue/postgres/task.model.d.ts

@@ -0,0 +1,24 @@
+import { BaseEntity, type Json, type Timestamp } from '../../orm/index.js';
+import type { ObjectLiteral } from '../../types/types.js';
+import { type Task, TaskState } from '../queue.js';
+export declare class PostgresTask<Data extends ObjectLiteral = ObjectLiteral, State extends ObjectLiteral = ObjectLiteral, Result extends ObjectLiteral = ObjectLiteral> extends BaseEntity implements Task<Data, State, Result> {
+    static readonly entityName = "Task";
+    queue: string;
+    status: TaskState;
+    tag: string | null;
+    priority: number;
+    parentId: string | null;
+    lease: string | null;
+    enqueueTimestamp: Timestamp;
+    scheduleTimestamp: Timestamp;
+    startTimestamp: Timestamp | null;
+    expirationTimestamp: Timestamp | null;
+    lockExpirationTimestamp: Timestamp | null;
+    completeTimestamp: Timestamp | null;
+    tries: number;
+    progress: number;
+    data: Json<Data>;
+    state: Json<State> | null;
+    result: Json<Result> | null;
+    error: Json<ObjectLiteral> | null;
+}

package/queue/postgres/task.model.js

@@ -0,0 +1,115 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+import { BaseEntity, Index, JsonProperty, Reference, Table, TimestampProperty, Unique, UuidProperty } from '../../orm/index.js';
+import { Enumeration, Integer, NumberProperty, StringProperty } from '../../schema/index.js';
+import { TaskState } from '../queue.js';
+let PostgresTask = class PostgresTask extends BaseEntity {
+    static entityName = 'Task';
+    queue;
+    status;
+    tag;
+    priority;
+    parentId;
+    lease;
+    enqueueTimestamp;
+    scheduleTimestamp;
+    startTimestamp;
+    expirationTimestamp;
+    lockExpirationTimestamp;
+    completeTimestamp;
+    tries;
+    progress;
+    data;
+    state;
+    result;
+    error;
+};
+__decorate([
+    StringProperty(),
+    __metadata("design:type", String)
+], PostgresTask.prototype, "queue", void 0);
+__decorate([
+    Enumeration(TaskState),
+    __metadata("design:type", String)
+], PostgresTask.prototype, "status", void 0);
+__decorate([
+    StringProperty({ nullable: true }),
+    __metadata("design:type", Object)
+], PostgresTask.prototype, "tag", void 0);
+__decorate([
+    Integer(),
+    __metadata("design:type", Number)
+], PostgresTask.prototype, "priority", void 0);
+__decorate([
+    Reference(() => PostgresTask),
+    UuidProperty({ nullable: true }),
+    __metadata("design:type", Object)
+], PostgresTask.prototype, "parentId", void 0);
+__decorate([
+    UuidProperty({ nullable: true }),
+    __metadata("design:type", Object)
+], PostgresTask.prototype, "lease", void 0);
+__decorate([
+    TimestampProperty(),
+    __metadata("design:type", Number)
+], PostgresTask.prototype, "enqueueTimestamp", void 0);
+__decorate([
+    TimestampProperty(),
+    __metadata("design:type", Number)
+], PostgresTask.prototype, "scheduleTimestamp", void 0);
+__decorate([
+    TimestampProperty({ nullable: true }),
+    __metadata("design:type", Object)
+], PostgresTask.prototype, "startTimestamp", void 0);
+__decorate([
+    TimestampProperty({ nullable: true }),
+    __metadata("design:type", Object)
+], PostgresTask.prototype, "expirationTimestamp", void 0);
+__decorate([
+    TimestampProperty({ nullable: true }),
+    __metadata("design:type", Object)
+], PostgresTask.prototype, "lockExpirationTimestamp", void 0);
+__decorate([
+    TimestampProperty({ nullable: true }),
+    __metadata("design:type", Object)
+], PostgresTask.prototype, "completeTimestamp", void 0);
+__decorate([
+    Integer(),
+    __metadata("design:type", Number)
+], PostgresTask.prototype, "tries", void 0);
+__decorate([
+    NumberProperty(),
+    __metadata("design:type", Number)
+], PostgresTask.prototype, "progress", void 0);
+__decorate([
+    JsonProperty({ nullable: true }),
+    __metadata("design:type", Object)
+], PostgresTask.prototype, "data", void 0);
+__decorate([
+    JsonProperty({ nullable: true }),
+    __metadata("design:type", Object)
+], PostgresTask.prototype, "state", void 0);
+__decorate([
+    JsonProperty({ nullable: true }),
+    __metadata("design:type", Object)
+], PostgresTask.prototype, "result", void 0);
+__decorate([
+    JsonProperty({ nullable: true }),
+    __metadata("design:type", Object)
+], PostgresTask.prototype, "error", void 0);
+PostgresTask = __decorate([
+    Table('task', { schema: 'queue' }),
+    Unique(['queue', 'tag']),
+    Index(['queue', 'status', 'priority', 'scheduleTimestamp']),
+    Index(['queue', 'status', 'lockExpirationTimestamp']),
+    Index(['queue', 'completeTimestamp']),
+    Index(['parentId', 'status'])
+], PostgresTask);
+export { PostgresTask };

package/queue/provider.d.ts

@@ -1,5 +1,5 @@
 import type { ObjectLiteral } from '../types/index.js';
 import type { Queue, QueueConfig } from './queue.js';
 export declare abstract class QueueProvider {
-    abstract get<T extends ObjectLiteral>(key: string, config?: QueueConfig): Queue<T>;
+    abstract get<Data extends ObjectLiteral, State extends ObjectLiteral, Result extends ObjectLiteral>(key: string, config?: QueueConfig): Queue<Data, State, Result>;
 }

package/queue/queue.d.ts

@@ -2,90 +2,211 @@ import type { CancellationSignal } from '../cancellation/token.js';
 import { type EnumType } from '../enumeration/enumeration.js';
 import type { Resolvable, resolveArgumentType } from '../injector/interfaces.js';
 import type { Logger } from '../logger/logger.js';
+import type { Transaction } from '../orm/server/transaction.js';
+import type { UndefinableJson } from '../types/types.js';
 import { QueueEnqueueBatch } from './enqueue-batch.js';
-export type ProcessWorker<T> = (job: Job<T>) => void | Promise<void>;
-export type ProcessBatchWorker<T> = (jobs: Job<T>[]) => void | Promise<void>;
-export type JobTag = string | null;
-export type Job<T> = {
+import { BatchTaskContext, type TaskContext } from './task-context.js';
+export interface ProcessWorker<Data, State, Result> {
+    /**
+     * A worker function that processes a single task.
+     * @param context The task context providing data, logger, and orchestration helpers.
+     */
+    (context: TaskContext<Data, State, Result>): void | Result | Promise<void | Result>;
+}
+export interface ProcessBatchWorker<Data, State, Result> {
+    /**
+     * A worker function that processes a batch of tasks.
+     * @param context The batch context providing tasks and helpers.
+     */
+    (context: BatchTaskContext<Data, State, Result>): void | Result[] | Promise<void | Result[]>;
+}
+export type TaskTag = string | null;
+export declare const TaskState: {
+    /**
+     * The task is waiting to be processed.
+     */
+    readonly Pending: "pending";
+    /**
+     * The task is currently being processed.
+     */
+    readonly Running: "running";
+    /**
+     * The task has been completed successfully.
+     */
+    readonly Completed: "completed";
+    /**
+     * The task has been cancelled and will not be processed.
+     */
+    readonly Cancelled: "cancelled";
+    /**
+     * The task is scheduled to be processed in the future when all children have completed.
+     */
+    readonly Waiting: "waiting";
+    /**
+     * The task has failed and will not be retried.
+     */
+    readonly Dead: "dead";
+};
+export type TaskState = EnumType<typeof TaskState>;
+export type Task<Data = unknown, State = unknown, Result = unknown> = {
     id: string;
+    queue: string;
+    status: TaskState;
+    lease: string | null;
     /**
      * The lower the number, the higher the priority.
      * @default 1000
      */
     priority: number;
-    tag: JobTag;
-    data: T;
-    enqueueTimestamp: number;
-    lastDequeueTimestamp: number | null;
+    tag: TaskTag;
+    data: Data;
+    parentId: string | null;
     tries: number;
+    enqueueTimestamp: number;
+    scheduleTimestamp: number;
+    /**
+     * Timestamp when the task most recently switched to Running state.
+     * Used for Hard Execution Timeouts.
+     */
+    startTimestamp: number | null;
+    /**
+     * Timestamp after which the task is considered expired if it hasn't started Running.
+     * If null, the task never expires in the queue.
+     */
+    expirationTimestamp: number | null;
+    lockExpirationTimestamp: number | null;
+    completeTimestamp: number | null;
+    /** A number between 0 and 1 indicating the progress of the task. */
+    progress: number;
+    /** A snapshot of the current state of the task. */
+    state: State | null;
+    result: Result | null;
+    error: UndefinableJson | null;
 };
-export declare const defaultJobPriority = 1000;
+export declare const defaultTaskPriority = 1000;
 export declare const UniqueTagStrategy: {
     readonly KeepOld: 0;
     readonly TakeNew: 1;
 };
 export type UniqueTagStrategy = EnumType<typeof UniqueTagStrategy>;
 export type EnqueueOptions = {
-    tag?: JobTag;
+    tag?: TaskTag;
     priority?: number;
+    parentId?: string;
+    scheduleTimestamp?: number;
+    expirationTimestamp?: number;
+    transaction?: Transaction;
 };
-export type EnqueueOneOptions = {
-    tag?: JobTag;
+export type EnqueueOneOptions = EnqueueOptions & {
     uniqueTag?: UniqueTagStrategy;
-    priority?: number;
 };
 export type EnqueueManyItem<T> = EnqueueOptions & {
     data: T;
 };
 export type EnqueueManyOptions = {
     uniqueTag?: UniqueTagStrategy;
-    returnJobs?: boolean;
+    returnTasks?: boolean;
+    transaction?: Transaction;
 };
 export type QueueConfig = {
+    /**
+     * Duration in ms for the worker lease. The worker must heartbeat within this window.
+     */
     processTimeout?: number;
+    /**
+     * Maximum duration a task is allowed to run (in ms) before being forcefully killed.
+     * This protects against infinite loops even if the worker keeps heartbeating.
+     * **WARN:** CancellationSignal must still be observed by the worker!
+     * Default: 15 minutes
+     */
+    executionTimeout?: number;
+    /** Maximum number of attempts to process a task before marking it as failed. Default 3 */
     maxTries?: number;
+    /** Milliseconds to keep completed tasks */
+    retentionPeriod?: number;
+    /** Maximum number of running tasks across all workers (`null` = unlimited) */
+    globalConcurrency?: number | null;
+    /** Number of consecutive failures before tripping the circuit breaker */
+    circuitBreakerThreshold?: number;
+    /** Milliseconds to wait before trying to close the circuit breaker */
+    circuitBreakerResetTimeout?: number;
+    /** Minimum delay for retries (the floor). Default: 5 seconds */
+    retryDelayMinimum?: number;
+    /** Maximum delay for retries (the ceiling). Default: 5 minutes */
+    retryDelayMaximum?: number;
+    /** Base for exponential backoff (delay = min * (base ^ tries)). Default: 2 */
+    retryDelayGrowth?: number;
 };
 export type QueueArgument = string | (QueueConfig & {
     name: string;
 });
 export declare const defaultQueueConfig: Required<QueueConfig>;
-export declare abstract class Queue<T> implements Resolvable<QueueArgument> {
+export declare abstract class Queue<Data, State = unknown, Result = unknown> implements Resolvable<QueueArgument> {
     readonly [resolveArgumentType]: QueueArgument;
     abstract readonly processTimeout: number;
     abstract readonly maxTries: number;
-    batch(): QueueEnqueueBatch<T>;
-    abstract enqueue(data: T, options?: EnqueueOneOptions): Promise<Job<T>>;
-    abstract enqueueMany(items: EnqueueManyItem<T>[], options?: EnqueueManyOptions & {
-        returnJobs?: false;
+    batch(): QueueEnqueueBatch<Data, State, Result>;
+    abstract enqueue(data: Data, options?: EnqueueOneOptions): Promise<Task<Data, State, Result>>;
+    abstract enqueueMany(items: EnqueueManyItem<Data>[], options?: EnqueueManyOptions & {
+        returnTasks?: false;
     }): Promise<void>;
-    abstract enqueueMany(items: EnqueueManyItem<T>[], options: EnqueueManyOptions & {
-        returnJobs: true;
-    }): Promise<Job<T>[]>;
-    abstract enqueueMany(items: EnqueueManyItem<T>[], options?: EnqueueManyOptions): Promise<Job<T>[] | undefined>;
+    abstract enqueueMany(items: EnqueueManyItem<Data>[], options: EnqueueManyOptions & {
+        returnTasks: true;
+    }): Promise<Task<Data, State, Result>[]>;
+    abstract enqueueMany(items: EnqueueManyItem<Data>[], options?: EnqueueManyOptions): Promise<Task<Data, State, Result>[] | undefined>;
     abstract has(id: string): Promise<boolean>;
-    abstract countByTag(tag: JobTag): Promise<number>;
-    abstract get(id: string): Promise<Job<T> | undefined>;
-    abstract getByTag(tag: JobTag): Promise<Job<T>[]>;
-    abstract getByTags(tags: JobTag[]): Promise<Job<T>[]>;
+    abstract get(id: string): Promise<Task<Data, State, Result> | undefined>;
+    abstract getByTag(tag: TaskTag): Promise<Task<Data, State, Result>[]>;
+    abstract getByTags(tags: TaskTag[]): Promise<Task<Data, State, Result>[]>;
+    abstract countByTag(tag: TaskTag): Promise<number>;
+    abstract getTree(rootId: string | string[]): Promise<Task<unknown, unknown, unknown>[]>;
     abstract cancel(id: string): Promise<void>;
     abstract cancelMany(ids: string[]): Promise<void>;
-    abstract cancelByTag(tag: JobTag): Promise<void>;
-    abstract cancelByTags(tags: JobTag[]): Promise<void>;
-    abstract dequeue(): Promise<Job<T> | undefined>;
-    abstract dequeueMany(count: number): Promise<Job<T>[]>;
-    abstract acknowledge(job: Job<T>): Promise<void>;
-    abstract acknowledgeMany(jobs: Job<T>[]): Promise<void>;
-    abstract getConsumer(cancellationSignal: CancellationSignal): AsyncIterableIterator<Job<T>>;
-    abstract getBatchConsumer(size: number, cancellationSignal: CancellationSignal): AsyncIterableIterator<Job<T>[]>;
+    abstract cancelByTag(tag: TaskTag): Promise<void>;
+    abstract cancelManyByTag(tags: TaskTag[]): Promise<void>;
+    /** Clears all tasks from the queue. Use with caution! */
+    abstract clear(): Promise<void>;
+    abstract dequeue(): Promise<Task<Data, State, Result> | undefined>;
+    abstract dequeueMany(count: number): Promise<Task<Data, State, Result>[]>;
+    /**
+     * Reschedules a task to run at a specific time.
+     * NOTE: If the task is currently running, its retry count is decremented (refunded) so this attempt doesn't count against maxTries.
+     */
+    abstract reschedule(id: string, timestamp: number, transaction?: Transaction): Promise<void>;
+    abstract rescheduleMany(ids: string[], timestamp: number, transaction?: Transaction): Promise<void>;
+    abstract rescheduleByTag(tag: TaskTag, timestamp: number, transaction?: Transaction): Promise<void>;
+    abstract rescheduleManyByTag(tags: TaskTag[], timestamp: number, transaction?: Transaction): Promise<void>;
+    /**
+     * Updates task progress, state and lock.
+     * Returns the updated task if successful, `undefined` if task is lost/cancelled/timed out.
+     */
+    abstract touch(task: Task, options?: {
+        progress?: number;
+        state?: State;
+        transaction?: Transaction;
+    }): Promise<Task<Data, State, Result> | undefined>;
+    /**
+     * Updates multiple tasks' progress, state and lock.
+     * Returns the IDs of the successfully updated tasks.
+     */
+    abstract touchMany(tasks: Task[], progresses?: number[], states?: State[], transaction?: Transaction): Promise<string[]>;
+    abstract acknowledge<R>(task: Task<any, any, R>, result?: R, transaction?: Transaction): Promise<void>;
+    abstract acknowledgeMany<R>(tasks: Task<any, any, R>[], results?: R[], transaction?: Transaction): Promise<void>;
+    abstract fail(task: Task, error: any, fatal?: boolean, transaction?: Transaction): Promise<void>;
+    abstract failMany(tasks: Task[], error: any, transaction?: Transaction): Promise<void>;
+    abstract prune(): Promise<void>;
+    abstract restart(id: string, transaction?: Transaction): Promise<void>;
+    abstract getConsumer(cancellationSignal: CancellationSignal): AsyncIterableIterator<Task<Data, State, Result>>;
+    abstract getBatchConsumer(size: number, cancellationSignal: CancellationSignal): AsyncIterableIterator<Task<Data, State, Result>[]>;
     process({ concurrency, cancellationSignal }: {
         concurrency?: number;
         cancellationSignal: CancellationSignal;
-    }, handler: ProcessWorker<T>, logger: Logger): void;
+    }, handler: ProcessWorker<Data, State, Result>, logger: Logger): void;
     processBatch({ batchSize, concurrency, cancellationSignal }: {
         batchSize?: number;
         concurrency?: number;
         cancellationSignal: CancellationSignal;
-    }, handler: ProcessBatchWorker<T>, logger: Logger): void;
+    }, handler: ProcessBatchWorker<Data, State, Result>, logger: Logger): void;
     private processWorker;
     private processBatchWorker;
 }

package/queue/queue.js

@@ -1,14 +1,52 @@
 import { defineEnum } from '../enumeration/enumeration.js';
-import { millisecondsPerMinute } from '../utils/units.js';
+import { createArray } from '../utils/array/array.js';
+import { cancelableTimeout } from '../utils/timing.js';
+import { isDefined } from '../utils/type-guards.js';
+import { millisecondsPerDay, millisecondsPerMinute, millisecondsPerSecond } from '../utils/units.js';
 import { QueueEnqueueBatch } from './enqueue-batch.js';
-export const defaultJobPriority = 1000;
+import { BatchTaskContext } from './task-context.js';
+export const TaskState = defineEnum('TaskState', {
+    /**
+     * The task is waiting to be processed.
+     */
+    Pending: 'pending',
+    /**
+     * The task is currently being processed.
+     */
+    Running: 'running',
+    /**
+     * The task has been completed successfully.
+     */
+    Completed: 'completed',
+    /**
+     * The task has been cancelled and will not be processed.
+     */
+    Cancelled: 'cancelled',
+    /**
+     * The task is scheduled to be processed in the future when all children have completed.
+     */
+    Waiting: 'waiting',
+    /**
+     * The task has failed and will not be retried.
+     */
+    Dead: 'dead',
+});
+export const defaultTaskPriority = 1000;
 export const UniqueTagStrategy = defineEnum('UniqueTagStrategy', {
     KeepOld: 0,
     TakeNew: 1,
 });
 export const defaultQueueConfig = {
-    processTimeout: millisecondsPerMinute,
+    processTimeout: millisecondsPerMinute * 5,
+    executionTimeout: millisecondsPerMinute * 60,
     maxTries: 3,
+    retentionPeriod: 30 * millisecondsPerDay,
+    globalConcurrency: null,
+    circuitBreakerThreshold: 5,
+    circuitBreakerResetTimeout: 30 * millisecondsPerSecond,
+    retryDelayMinimum: 5 * millisecondsPerSecond,
+    retryDelayMaximum: 5 * millisecondsPerMinute,
+    retryDelayGrowth: 2,
 };
 export class Queue {
     batch() {
@@ -25,28 +63,68 @@ export class Queue {
         }
     }
     async processWorker(cancellationSignal, handler, logger) {
-        for await (const job of this.getConsumer(cancellationSignal)) {
-            logger?.verbose(`Processing job ${job.id}`);
-            try {
-                await handler(job);
-                logger?.verbose(`Acknowledge job ${job.id}`);
-                await this.acknowledge(job);
-            }
-            catch (error) {
-                logger?.error(error);
+        await this.processBatchWorker(1, cancellationSignal, async (batchContext) => {
+            const task = batchContext.tasks[0];
+            const context = batchContext.for(task);
+            const result = await handler(context);
+            if (isDefined(result)) {
+                return [result];
             }
-        }
+            return undefined;
+        }, logger);
     }
     async processBatchWorker(size, cancellationSignal, handler, logger) {
-        for await (const jobs of this.getBatchConsumer(size, cancellationSignal)) {
-            logger?.verbose(`Processing ${jobs.length} jobs`);
+        for await (const tasks of this.getBatchConsumer(size, cancellationSignal)) {
+            const batchToken = cancellationSignal.createChild();
+            const context = new BatchTaskContext(this, tasks, batchToken, logger);
+            let activeTaskIds = new Set(tasks.map((t) => t.id));
+            context.logger.verbose(`Processing batch of ${tasks.length}`);
+            void (async () => {
+                while (batchToken.isUnset) {
+                    await cancelableTimeout(Math.min(this.processTimeout / 2, 5000), batchToken);
+                    if (batchToken.isSet) {
+                        break;
+                    }
+                    try {
+                        const tasksToTouch = tasks.filter((t) => activeTaskIds.has(t.id));
+                        if (tasksToTouch.length > 0) {
+                            const touchedIds = await this.touchMany(tasksToTouch);
+                            if (touchedIds.length != tasksToTouch.length) {
+                                const lostCount = tasksToTouch.length - touchedIds.length;
+                                context.logger.warn(`Batch integrity compromised: ${lostCount} tasks lost lease. Aborting batch.`);
+                                activeTaskIds = new Set(touchedIds);
+                                batchToken.set();
+                            }
+                            else {
+                                activeTaskIds = new Set(touchedIds);
+                            }
+                        }
+                        if (activeTaskIds.size == 0 && batchToken.isUnset) {
+                            context.logger.warn(`All tasks in batch lost lease. Stopping worker.`);
+                            batchToken.set();
+                        }
+                    }
+                    catch (error) {
+                        context.logger.error(error);
+                    }
+                }
+            })();
             try {
-                await handler(jobs);
-                logger?.verbose(`Acknowledge ${jobs.length} jobs`);
-                await this.acknowledgeMany(jobs);
+                if (batchToken.isSet) {
+                    throw new Error('Tasks cancelled before start');
+                }
+                const results = await handler(context);
+                if (isDefined(results)) {
+                    context.logger.verbose(`Acknowledging batch`);
+                    await this.acknowledgeMany(tasks, results);
+                }
             }
             catch (error) {
-                logger?.error(error);
+                context.logger.error(error);
+                await this.failMany(tasks, createArray(tasks.length, () => error));
+            }
+            finally {
+                batchToken.set();
             }
         }
     }

package/queue/task-context.d.ts

@@ -0,0 +1,38 @@
+import type { CancellationSignal, CancellationToken } from '../cancellation/index.js';
+import type { Logger } from '../logger/index.js';
+import type { Transaction } from '../orm/server/index.js';
+import { type EnqueueManyItem, type EnqueueOptions, Queue, type Task } from './queue.js';
+export declare class TaskContext<Data, State = unknown, Result = unknown> {
+    #private;
+    constructor(queue: Queue<Data, State, Result>, task: Task<Data, State, Result>, signal: CancellationToken, logger: Logger);
+    get id(): string;
+    get data(): Data;
+    get attempt(): number;
+    get triesLeft(): number;
+    get signal(): CancellationSignal;
+    get logger(): Logger;
+    acknowledge(result?: Result, transaction?: Transaction): Promise<void>;
+    checkpoint(options: {
+        progress?: number;
+        state?: State;
+    }): Promise<void>;
+    spawn(data: Data, options?: Omit<EnqueueOptions, 'parentId'>): Promise<Task<Data, State, Result>>;
+    spawn<D, S, R>(queue: Queue<D, S, R>, data: D, options?: Omit<EnqueueOptions, 'parentId'>): Promise<Task<D, S, R>>;
+    spawnMany(items: EnqueueManyItem<Data>[]): Promise<Task<Data, State, Result>[]>;
+    spawnMany<D = Data, S = any, R = any>(queue: Queue<D, S, R>, items: EnqueueManyItem<D>[]): Promise<Task<D, S, R>[]>;
+    /** Stop execution and reschedule the task for later without incrementing tries if possible */
+    reschedule(timestamp: number): Promise<void>;
+    reschedule(options: {
+        delay: number;
+    }): Promise<void>;
+    fail(error: any, fatal?: boolean, transaction?: Transaction): Promise<void>;
+}
+export declare class BatchTaskContext<Data, State, Result> {
+    #private;
+    constructor(queue: Queue<Data, State, Result>, tasks: Task<Data, State, Result>[], signal: CancellationToken, logger: Logger);
+    get tasks(): Task<Data, State, Result>[];
+    get signal(): CancellationSignal;
+    get logger(): Logger;
+    for(task: Task<Data, State, Result>): TaskContext<Data, State, Result>;
+    checkpointAll(progresses?: number[], states?: State[]): Promise<void>;
+}