@tstdl/base 0.93.140 → 0.93.142

package/task-queue/task-queue.js

@@ -1,3 +1,4 @@
+/** biome-ignore-all lint/nursery/noExcessiveClassesPerFile: <explanation> */
 var __addDisposableResource = (this && this.__addDisposableResource) || function (env, value, async) {
     if (value !== null && value !== void 0) {
         if (typeof value !== "object" && typeof value !== "function") throw new TypeError("Object expected.");
@@ -55,67 +56,131 @@ import { inject, injectArgument, Injector } from '../injector/index.js';
 import { Logger } from '../logger/logger.js';
 import { Transactional } from '../orm/server/transactional.js';
 import { currentTimestamp } from '../utils/date-time.js';
-import { cancelableTimeout } from '../utils/timing.js';
-import { isDefined, isString, isUndefined } from '../utils/type-guards.js';
+import { isDefined, isError, isString } from '../utils/type-guards.js';
 import { millisecondsPerDay, millisecondsPerMinute, millisecondsPerSecond } from '../utils/units.js';
 import { TaskQueueEnqueueBatch } from './enqueue-batch.js';
 import { TaskContext } from './task-context.js';
+/**
+ * Represents the result of processing a task.
+ * @template Result The type of the result data.
+ */
 export class TaskProcessResult {
     payload;
     constructor(payload) {
         this.payload = payload;
     }
+    /**
+     * Creates a successful process result.
+     * @param result The optional result data.
+     */
     static Complete(result) {
         return new TaskProcessResult({ action: 'complete', result });
     }
+    /**
+     * Creates a failed process result.
+     * @param error The error that occurred.
+     * @param fatal Whether the error is fatal and the task should not be retried.
+     */
     static Fail(error, fatal = false) {
         return new TaskProcessResult({ action: 'fail', error, fatal });
     }
+    /**
+     * Creates a result that reschedules the task to a specific timestamp.
+     * @param timestamp The timestamp to reschedule to.
+     */
     static RescheduleTo(timestamp) {
         return new TaskProcessResult({ action: 'reschedule', timestamp });
     }
+    /**
+     * Creates a result that reschedules the task by a specific number of milliseconds.
+     * @param milliseconds The number of milliseconds to reschedule by.
+     */
     static RescheduleBy(milliseconds) {
         const timestamp = currentTimestamp() + milliseconds;
         return this.RescheduleTo(timestamp);
     }
 }
+/**
+ * Represents the status of a task in the queue.
+ */
 export const TaskStatus = defineEnum('TaskStatus', {
     /**
-     * The task is waiting to be processed.
+     * The task is ready to be processed and is waiting for a worker.
      */
     Pending: 'pending',
     /**
-     * The task is currently being processed.
+     * The task is currently being processed by a worker.
      */
     Running: 'running',
     /**
-     * The task has been completed successfully.
+     * The task has been completed successfully and all its lifecycle requirements met.
      */
     Completed: 'completed',
     /**
-     * The task has been cancelled and will not be processed.
+     * The task has been cancelled and will not be processed further.
      */
     Cancelled: 'cancelled',
     /**
-     * The task is scheduled to be processed in the future when all children have completed.
+     * The task has failed and will not be retried.
+     */
+    Dead: 'dead',
+    /**
+     * The task is waiting for its pre-execution (schedule) dependencies to be met.
      */
     Waiting: 'waiting',
     /**
-     * The task has failed and will not be retried.
+     * The task has finished execution but is waiting for its completion dependencies (children) to finish.
      */
-    Dead: 'dead',
+    WaitingChildren: 'waiting-children',
+    /**
+     * The task has been manually paused and will not be dequeued until resumed.
+     */
+    Paused: 'paused',
+    /**
+     * The task has failed but has remaining attempts and is waiting for its next scheduled attempt.
+     */
+    Retrying: 'retrying',
+    /**
+     * The task was forcefully terminated because its execution time exceeded maxExecutionTime.
+     */
+    TimedOut: 'timed-out',
+    /**
+     * The task expired in the queue before it could be picked up by a worker.
+     */
+    Expired: 'expired',
+    /**
+     * The task was never attempted because one of its prerequisites failed or was cancelled.
+     */
+    Skipped: 'skipped',
+    /**
+     * The task was abandoned by a worker and has exhausted all retry attempts.
+     */
+    Orphaned: 'orphaned',
 });
-export const DependencyJoinMode = defineEnum('DependencyJoinMode', {
-    And: 'and',
-    Or: 'or',
+/**
+ * Represents the type of dependency between tasks.
+ */
+export const TaskDependencyType = defineEnum('TaskDependencyType', {
+    /**
+     * The task should only be scheduled after the dependency has reached a specific status.
+     */
+    Schedule: 'schedule',
+    /**
+     * The task is only considered complete after the dependency has reached a specific status.
+     */
+    Complete: 'complete',
+    /**
+     * The task is only considered complete after the child task has reached a specific status.
+     */
+    Child: 'child',
 });
+/** Default priority for tasks. */
 export const defaultTaskPriority = 1000;
 export const defaultQueueConfig = {
     visibilityTimeout: millisecondsPerMinute * 5,
     maxExecutionTime: millisecondsPerMinute * 60,
     maxTries: 3,
     retention: 30 * millisecondsPerDay,
-    globalConcurrency: null,
     circuitBreakerThreshold: 5,
     circuitBreakerResetTimeout: 30 * millisecondsPerSecond,
     retryDelayMinimum: 5 * millisecondsPerSecond,
@@ -129,15 +194,30 @@ export const defaultQueueConfig = {
     rateInterval: 1000,
     idempotencyWindow: millisecondsPerMinute * 60,
 };
+/**
+ * Abstract base class for task queues.
+ * @template Definitions The type map of task definitions.
+ */
 export class TaskQueue extends Transactional {
+    #activeTasks = new Map();
+    #heartbeatLoopRunning = false;
     injector = inject(Injector);
     config = this.transactionalContextData ?? (() => { const arg = injectArgument(this); return isString(arg) ? { namespace: arg } : arg; })();
     logger = inject(Logger, TaskQueue.name).with({ namespace: this.config.namespace });
+    get namespace() {
+        return this.config.namespace;
+    }
+    /**
+     * Starts a new batch operation for enqueuing multiple tasks.
+     * @returns A TaskQueueEnqueueBatch instance.
+     */
     batch() {
         return new TaskQueueEnqueueBatch(this);
     }
     /**
-     * Starts processing tasks with the provided worker function in the background until the cancellation signal is triggered.
+     * Starts processing tasks with the provided worker function.
+     * @param options Concurrency, cancellation signal, task types, and forceDequeue flag.
+     * @param handler The worker function to process tasks.
      */
     process({ concurrency = 1, cancellationSignal, types, forceDequeue }, handler) {
         const promises = [];
@@ -151,7 +231,10 @@ export class TaskQueue extends Transactional {
         return this.config;
     }
     /**
-     * Starts processing tasks with the provided worker function in the foreground until the cancellation signal is triggered.
+     * Internal method to process tasks using a worker function.
+     * @param cancellationSignal A signal to stop processing tasks.
+     * @param handler The worker function.
+     * @param options Dequeue options.
      */
     async processWorker(cancellationSignal, handler, options) {
         for await (const task of this.getConsumer(cancellationSignal, options)) {
@@ -159,54 +242,50 @@ export class TaskQueue extends Transactional {
             try {
                 const taskToken = __addDisposableResource(env_1, cancellationSignal.fork(), false);
                 const context = new TaskContext(this, task, taskToken, this.logger.with({ type: task.type }));
-                let isTaskActive = true;
-                context.logger.verbose(`Processing task`);
-                void (async () => {
-                    while (taskToken.isUnset) {
-                        await cancelableTimeout(Math.min(this.visibilityTimeout / 2, 5000), taskToken);
-                        if (taskToken.isSet) {
-                            break;
-                        }
-                        try {
-                            const touchedTask = await this.touch(task);
-                            if (isUndefined(touchedTask) && taskToken.isUnset) {
-                                context.logger.warn(`Task lost lease. Aborting.`);
-                                isTaskActive = false;
-                                taskToken.set();
-                            }
-                        }
-                        catch (error) {
-                            context.logger.error('Error touching task', error);
-                        }
-                    }
-                })();
+                const isTaskActiveObj = { value: true };
+                this.#activeTasks.set(task.id, {
+                    task: task,
+                    taskToken,
+                    logger: context.logger,
+                    isTaskActive: isTaskActiveObj,
+                });
+                if (!this.#heartbeatLoopRunning) {
+                    void this.#runHeartbeatLoop();
+                }
+                context.logger.verbose('Processing task');
                 try {
                     if (taskToken.isSet) {
                         throw new Error('Task cancelled before start');
                     }
                     const result = await handler(context);
-                    if (isDefined(result) && isTaskActive) {
+                    if (isDefined(result) && isTaskActiveObj.value) {
                         switch (result.payload.action) {
                             case 'complete':
-                                context.logger.verbose(`Completing task`);
+                                context.logger.verbose('Completing task');
                                 await this.complete(task, { result: result.payload.result });
                                 break;
                             case 'fail':
-                                context.logger.verbose(`Failing task`);
+                                context.logger.verbose('Failing task');
                                 await this.fail(task, result.payload.error, { fatal: result.payload.fatal });
                                 break;
                             case 'reschedule':
-                                context.logger.verbose(`Rescheduling task`);
+                                context.logger.verbose('Rescheduling task');
                                 await this.reschedule(task.id, result.payload.timestamp);
                                 break;
                             default:
-                                throw new Error(`Unsupported task result action.`);
+                                throw new Error('Unsupported task result action.');
                         }
                     }
                 }
                 catch (error) {
                     context.logger.error('Error processing task', error);
                     await this.fail(task, error);
+                    if (isError(error) && ((error.message === 'Task cancelled before start') || (error.message == 'Unsupported task result action.'))) {
+                        throw error;
+                    }
+                }
+                finally {
+                    this.#activeTasks.delete(task.id);
                 }
             }
             catch (e_1) {
@@ -218,4 +297,37 @@ export class TaskQueue extends Transactional {
             }
         }
     }
+    async #runHeartbeatLoop() {
+        if (this.#heartbeatLoopRunning) {
+            return;
+        }
+        this.#heartbeatLoopRunning = true;
+        try {
+            while (this.#activeTasks.size > 0) {
+                await new Promise((resolve) => setTimeout(resolve, Math.min(this.visibilityTimeout / 2, 5000)));
+                if (this.#activeTasks.size === 0) {
+                    break;
+                }
+                const entries = Array.from(this.#activeTasks.values());
+                const tasks = entries.map((e) => e.task);
+                try {
+                    const touchedIds = await this.touchMany(tasks);
+                    const touchedSet = new Set(touchedIds);
+                    for (const entry of entries) {
+                        if (entry.taskToken.isUnset && !touchedSet.has(entry.task.id)) {
+                            entry.logger.warn(`Task lost lease. Aborting.`);
+                            entry.isTaskActive.value = false;
+                            entry.taskToken.set();
+                        }
+                    }
+                }
+                catch (error) {
+                    this.logger.error('Error touching tasks', error);
+                }
+            }
+        }
+        finally {
+            this.#heartbeatLoopRunning = false;
+        }
+    }
 }

package/task-queue/tests/coverage-branch.test.d.ts

@@ -0,0 +1 @@
+export {};