@tstdl/base 0.93.140 → 0.93.141

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

@@ -1,6 +1,7 @@
+/** biome-ignore-all lint/nursery/noExcessiveClassesPerFile: <explanation> */
 import { BaseEntity, type Json, type Timestamp } from '../../orm/index.js';
 import type { ObjectLiteral, TypedOmit } from '../../types/types.js';
-import { DependencyJoinMode, type Task, TaskStatus } from '../task-queue.js';
+import { type Task, TaskDependencyType, TaskStatus } from '../task-queue.js';
 export declare abstract class PostgresTaskBase<Data extends ObjectLiteral = ObjectLiteral, State extends ObjectLiteral = ObjectLiteral, Result extends ObjectLiteral = ObjectLiteral> extends BaseEntity implements TypedOmit<Task, 'parentId'> {
     namespace: string;
     type: string;
@@ -8,12 +9,10 @@ export declare abstract class PostgresTaskBase<Data extends ObjectLiteral = Obje
     idempotencyKey: string | null;
     traceId: string | null;
     tags: string[];
-    completeAfterTags: string[];
-    scheduleAfterTags: string[];
     failFast: boolean;
-    dependencyJoinMode: DependencyJoinMode;
-    dependencyTriggerStatuses: TaskStatus[];
     priority: number;
+    unresolvedScheduleDependencies: number;
+    unresolvedCompleteDependencies: number;
     token: string | null;
     creationTimestamp: Timestamp;
     priorityAgeTimestamp: Timestamp;
@@ -37,3 +36,11 @@ export declare class PostgresTaskArchive<Data extends ObjectLiteral = ObjectLite
     static readonly entityName = "TaskArchive";
     parentId: string | null;
 }
+export declare class PostgresTaskDependency extends BaseEntity {
+    static readonly entityName = "TaskDependency";
+    namespace: string;
+    taskId: string;
+    dependencyTaskId: string;
+    type: TaskDependencyType;
+    requiredStatuses: TaskStatus[];
+}

package/task-queue/postgres/task.model.js

@@ -1,3 +1,4 @@
+/** biome-ignore-all lint/nursery/noExcessiveClassesPerFile: <explanation> */
 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);
@@ -7,9 +8,9 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 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 { BaseEntity, ForeignKey, Index, JsonProperty, Table, TimestampProperty, Unique, UuidProperty } from '../../orm/index.js';
 import { Array as ArrayProperty, BooleanProperty, Enumeration, Integer, NumberProperty, StringProperty } from '../../schema/index.js';
-import { DependencyJoinMode, TaskStatus } from '../task-queue.js';
+import { TaskDependencyType, TaskStatus } from '../task-queue.js';
 export class PostgresTaskBase extends BaseEntity {
     namespace;
     type;
@@ -17,12 +18,10 @@ export class PostgresTaskBase extends BaseEntity {
     idempotencyKey;
     traceId;
     tags;
-    completeAfterTags;
-    scheduleAfterTags;
     failFast;
-    dependencyJoinMode;
-    dependencyTriggerStatuses;
     priority;
+    unresolvedScheduleDependencies;
+    unresolvedCompleteDependencies;
     token;
     creationTimestamp;
     priorityAgeTimestamp;
@@ -62,30 +61,22 @@ __decorate([
     ArrayProperty(String),
     __metadata("design:type", Array)
 ], PostgresTaskBase.prototype, "tags", void 0);
-__decorate([
-    ArrayProperty(String),
-    __metadata("design:type", Array)
-], PostgresTaskBase.prototype, "completeAfterTags", void 0);
-__decorate([
-    ArrayProperty(String),
-    __metadata("design:type", Array)
-], PostgresTaskBase.prototype, "scheduleAfterTags", void 0);
 __decorate([
     BooleanProperty(),
     __metadata("design:type", Boolean)
 ], PostgresTaskBase.prototype, "failFast", void 0);
 __decorate([
-    Enumeration(DependencyJoinMode),
-    __metadata("design:type", String)
-], PostgresTaskBase.prototype, "dependencyJoinMode", void 0);
+    Integer(),
+    __metadata("design:type", Number)
+], PostgresTaskBase.prototype, "priority", void 0);
 __decorate([
-    Enumeration(TaskStatus, { array: true }),
-    __metadata("design:type", Array)
-], PostgresTaskBase.prototype, "dependencyTriggerStatuses", void 0);
+    Integer(),
+    __metadata("design:type", Number)
+], PostgresTaskBase.prototype, "unresolvedScheduleDependencies", void 0);
 __decorate([
     Integer(),
     __metadata("design:type", Number)
-], PostgresTaskBase.prototype, "priority", void 0);
+], PostgresTaskBase.prototype, "unresolvedCompleteDependencies", void 0);
 __decorate([
     UuidProperty({ nullable: true }),
     __metadata("design:type", Object)
@@ -147,20 +138,19 @@ let PostgresTask = class PostgresTask extends PostgresTaskBase {
     parentId;
 };
 __decorate([
-    Reference(() => PostgresTask),
     UuidProperty({ nullable: true }),
     __metadata("design:type", Object)
 ], PostgresTask.prototype, "parentId", void 0);
 PostgresTask = __decorate([
     Table('task', { schema: 'task_queue' }),
     Unique(['namespace', 'idempotencyKey']),
+    Unique(['namespace', 'id']),
     Index(['namespace', 'status', 'scheduleTimestamp', 'priority']),
     Index(['tags'], { using: 'gin' }),
-    Index(['completeAfterTags'], { using: 'gin' }),
-    Index(['scheduleAfterTags'], { using: 'gin' }),
     Index(['status', 'completeTimestamp']),
     Index(['status', 'visibilityDeadline']),
-    Index(['parentId'])
+    Index(['parentId']),
+    ForeignKey(() => PostgresTask, ['namespace', 'parentId'], ['namespace', 'id'])
 ], PostgresTask);
 export { PostgresTask };
 let PostgresTaskArchive = class PostgresTaskArchive extends PostgresTaskBase {
@@ -176,3 +166,39 @@ PostgresTaskArchive = __decorate([
     Index(['namespace', 'completeTimestamp'])
 ], PostgresTaskArchive);
 export { PostgresTaskArchive };
+let PostgresTaskDependency = class PostgresTaskDependency extends BaseEntity {
+    static entityName = 'TaskDependency';
+    namespace;
+    taskId;
+    dependencyTaskId;
+    type;
+    requiredStatuses;
+};
+__decorate([
+    StringProperty(),
+    __metadata("design:type", String)
+], PostgresTaskDependency.prototype, "namespace", void 0);
+__decorate([
+    UuidProperty(),
+    __metadata("design:type", String)
+], PostgresTaskDependency.prototype, "taskId", void 0);
+__decorate([
+    UuidProperty(),
+    __metadata("design:type", String)
+], PostgresTaskDependency.prototype, "dependencyTaskId", void 0);
+__decorate([
+    Enumeration(TaskDependencyType),
+    __metadata("design:type", String)
+], PostgresTaskDependency.prototype, "type", void 0);
+__decorate([
+    Enumeration(TaskStatus, { array: true }),
+    __metadata("design:type", Array)
+], PostgresTaskDependency.prototype, "requiredStatuses", void 0);
+PostgresTaskDependency = __decorate([
+    Table('task_dependency', { schema: 'task_queue' }),
+    Unique(['namespace', 'taskId', 'dependencyTaskId', 'type']),
+    Index(['namespace', 'dependencyTaskId', 'type']),
+    ForeignKey(() => PostgresTask, ['namespace', 'taskId'], ['namespace', 'id'], { onDelete: 'cascade' }),
+    ForeignKey(() => PostgresTask, ['namespace', 'dependencyTaskId'], ['namespace', 'id'], { onDelete: 'cascade' })
+], PostgresTaskDependency);
+export { PostgresTaskDependency };

package/task-queue/task-context.d.ts

@@ -10,8 +10,8 @@ export declare class TaskContext<Definitions extends TaskDefinitionMap, Type ext
     get type(): Type;
     get parentId(): string | null;
     get tags(): string[];
-    get completeAfterTags(): string[];
-    get scheduleAfterTags(): string[];
+    get unresolvedScheduleDependencies(): number;
+    get unresolvedCompleteDependencies(): number;
     get data(): TaskData<Definitions, Type>;
     get state(): TaskState<Definitions, Type> | null;
     get attempt(): number;

package/task-queue/task-context.js

@@ -24,11 +24,11 @@ export class TaskContext {
     get tags() {
         return this.#task.tags;
     }
-    get completeAfterTags() {
-        return this.#task.completeAfterTags;
+    get unresolvedScheduleDependencies() {
+        return this.#task.unresolvedScheduleDependencies;
     }
-    get scheduleAfterTags() {
-        return this.#task.scheduleAfterTags;
+    get unresolvedCompleteDependencies() {
+        return this.#task.unresolvedCompleteDependencies;
     }
     get data() {
         return this.#task.data;
@@ -70,16 +70,16 @@ export class TaskContext {
         const data = isForOtherQueue ? dataOrOptionsOrNothing : typeOrData;
         const options = (isForOtherQueue ? optionsOrNothing : dataOrOptionsOrNothing);
         if (isForOtherQueue) {
-            return await queueOrType.enqueue(type, data, { ...options, parentId: this.#task.id });
+            return await queueOrType.enqueue(type, data, options);
         }
         return await this.#queue.enqueue(type, data, { ...options, parentId: this.#task.id });
     }
     async spawnMany(queueOrItems, itemsOrNothing) {
         const isForOtherQueue = isInstanceOf(queueOrItems, TaskQueue);
-        const items = (isForOtherQueue ? itemsOrNothing : queueOrItems).map((item) => ({ ...item, parentId: this.#task.id }));
         if (isForOtherQueue) {
-            return await queueOrItems.enqueueMany(items, { returnTasks: true });
+            return await queueOrItems.enqueueMany(itemsOrNothing, { returnTasks: true });
         }
+        const items = queueOrItems.map((item) => ({ ...item, parentId: this.#task.id }));
         return await this.#queue.enqueueMany(items, { returnTasks: true });
     }
     async reschedule(timestampOrDelay) {

package/task-queue/task-queue.d.ts

@@ -18,36 +18,44 @@ export declare class TaskProcessResult<Result = unknown> {
 }
 export declare const TaskStatus: {
     /**
-     * The task is waiting to be processed.
+     * The task is ready to be processed and is waiting for a worker.
      */
     readonly Pending: "pending";
     /**
-     * The task is currently being processed.
+     * The task is currently being processed by a worker.
      */
     readonly Running: "running";
     /**
-     * The task has been completed successfully.
+     * The task has been completed successfully and all its lifecycle requirements met.
      */
     readonly Completed: "completed";
     /**
-     * The task has been cancelled and will not be processed.
+     * The task has been cancelled and will not be processed further.
      */
     readonly 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.
+     */
+    readonly Dead: "dead";
+    /**
+     * The task is waiting for its pre-execution (schedule) dependencies to be met.
      */
     readonly 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.
      */
-    readonly Dead: "dead";
+    readonly WaitingChildren: "waiting-children";
+    /**
+     * The task has been manually paused and will not be dequeued until resumed.
+     */
+    readonly Paused: "paused";
 };
 export type TaskStatus = EnumType<typeof TaskStatus>;
-export declare const DependencyJoinMode: {
-    readonly And: "and";
-    readonly Or: "or";
+export declare const TaskDependencyType: {
+    readonly Schedule: "schedule";
+    readonly Complete: "complete";
 };
-export type DependencyJoinMode = EnumType<typeof DependencyJoinMode>;
+export type TaskDependencyType = EnumType<typeof TaskDependencyType>;
 export type Task<Definitions extends TaskDefinitionMap = Record<string, {
     data: unknown;
     state: unknown;
@@ -67,11 +75,9 @@ export type Task<Definitions extends TaskDefinitionMap = Record<string, {
         idempotencyKey: string | null;
         traceId: string | null;
         tags: string[];
-        completeAfterTags: string[];
-        scheduleAfterTags: string[];
+        unresolvedScheduleDependencies: number;
+        unresolvedCompleteDependencies: number;
         failFast: boolean;
-        dependencyJoinMode: DependencyJoinMode;
-        dependencyTriggerStatuses: TaskStatus[];
         data: TaskData<Definitions, Type>;
         parentId: string | null;
         tries: number;
@@ -108,11 +114,16 @@ export type EnqueueOptions = {
     idempotencyKey?: string;
     replace?: boolean;
     tags?: string[];
-    completeAfterTags?: string[];
-    scheduleAfterTags?: string[];
+    scheduleAfter?: (string | {
+        id: string;
+        requiredStatuses?: TaskStatus[];
+    })[];
+    completeAfter?: (string | {
+        id: string;
+        requiredStatuses?: TaskStatus[];
+    })[];
     failFast?: boolean;
-    dependencyJoinMode?: DependencyJoinMode;
-    dependencyTriggerStatuses?: TaskStatus[];
+    waitForCompletion?: boolean;
     scheduleTimestamp?: number;
     timeToLive?: number;
     transaction?: Transaction;
@@ -197,6 +208,12 @@ export declare abstract class TaskQueue<Definitions extends TaskDefinitionMap =
     abstract readonly maxTries: number;
     batch(): TaskQueueEnqueueBatch<Definitions>;
     abstract enqueue<Type extends TaskTypes<Definitions>>(type: Type, data: TaskData<Definitions, Type>, options?: EnqueueOneOptions): Promise<TaskOfType<Definitions, Type>>;
+    /**
+     * Enqueues multiple tasks.
+     * @param items The items to enqueue.
+     * @param options Enqueue options. If `returnTasks` is true, returns the enqueued tasks.
+     * **NOTE:** The order of returned tasks is NOT guaranteed to match the order of input items.
+     */
     abstract enqueueMany<Type extends TaskTypes<Definitions>>(items: EnqueueManyItem<Definitions, Type>[], options?: EnqueueManyOptions & {
         returnTasks?: false;
     }): Promise<void>;

package/task-queue/task-queue.js

@@ -81,33 +81,41 @@ export class TaskProcessResult {
 }
 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',
 });
-export const DependencyJoinMode = defineEnum('DependencyJoinMode', {
-    And: 'and',
-    Or: 'or',
+export const TaskDependencyType = defineEnum('TaskDependencyType', {
+    Schedule: 'schedule',
+    Complete: 'complete',
 });
 export const defaultTaskPriority = 1000;
 export const defaultQueueConfig = {

package/task-queue/tests/cascading-cancellations.test.d.ts

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

package/task-queue/tests/cascading-cancellations.test.js

@@ -0,0 +1,38 @@
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it } from 'vitest';
+import { TaskQueueProvider, TaskStatus } from '../../task-queue/index.js';
+import { setupIntegrationTest } from '../../testing/index.js';
+describe('Cascading Cancellations', () => {
+    let injector;
+    let queue;
+    beforeAll(async () => {
+        ({ injector } = await setupIntegrationTest({ modules: { taskQueue: true } }));
+    });
+    beforeEach(() => {
+        const queueProvider = injector.resolve(TaskQueueProvider);
+        const queueName = `cancellation-queue-${Date.now()}-${Math.random()}`;
+        queue = queueProvider.get(queueName, {
+            visibilityTimeout: 1000,
+        });
+    });
+    afterEach(async () => {
+        await queue.clear();
+    });
+    afterAll(async () => {
+        await injector?.dispose();
+    });
+    it('should recursively cancel children in ownership tree', async () => {
+        const root = await queue.enqueue('root', {});
+        const child1 = await queue.enqueue('child1', {}, { parentId: root.id });
+        const child2 = await queue.enqueue('child2', {}, { parentId: root.id });
+        const grandchild = await queue.enqueue('grandchild', {}, { parentId: child1.id });
+        await queue.cancel(root.id);
+        const uRoot = await queue.getTask(root.id);
+        const uChild1 = await queue.getTask(child1.id);
+        const uChild2 = await queue.getTask(child2.id);
+        const uGrandchild = await queue.getTask(grandchild.id);
+        expect(uRoot?.status).toBe(TaskStatus.Cancelled);
+        expect(uChild1?.status).toBe(TaskStatus.Cancelled);
+        expect(uChild2?.status).toBe(TaskStatus.Cancelled);
+        expect(uGrandchild?.status).toBe(TaskStatus.Cancelled);
+    });
+});