@tstdl/base 0.93.139 → 0.93.141

package/task-queue/README.md

@@ -0,0 +1,293 @@
+# Task Queue
+
+A robust, type-safe, and distributed task orchestration system backed by PostgreSQL. It supports prioritization, hierarchical task dependencies, batch operations, circuit breaking, and automatic retries with exponential backoff.
+
+## Table of Contents
+
+- [✨ Features](#-features)
+- [Core Concepts](#core-concepts)
+- [🚀 Basic Usage](#-basic-usage)
+  - [Configuration](#configuration)
+  - [Defining Tasks](#defining-tasks)
+  - [Enqueueing Tasks](#enqueueing-tasks)
+  - [Processing Tasks](#processing-tasks)
+- [🔧 Advanced Topics](#-advanced-topics)
+  - [Task Hierarchies (Parent/Child)](#task-hierarchies-parentchild)
+  - [Batch Operations](#batch-operations)
+  - [Deduplication (Idempotency)](#deduplication-idempotency)
+  - [Prioritization](#prioritization)
+  - [Transactional Enqueueing](#transactional-enqueueing)
+  - [Manual Consumption](#manual-consumption)
+- [📚 API](#-api)
+
+## ✨ Features
+
+- **PostgreSQL Backend**: Reliable persistence using Drizzle ORM with row-level locking (`SKIP LOCKED`) for safe concurrency.
+- **Type-Safe**: Fully typed task data, state, and result payloads using a `TaskDefinitionMap`.
+- **Task Hierarchies**: Support for parent-child relationships where parents wait for children to complete (Fan-Out/Fan-In).
+- **Prioritization**: Integer-based priority system with automatic aging to prevent starvation.
+- **Deduplication**: Idempotency keys with configurable strategies (`replace: true/false`) and retention windows.
+- **Resilience**: Built-in Circuit Breaker, automatic retries with exponential backoff, and zombie task recovery.
+- **Observability**: Tracks progress, state, and detailed error information.
+
+## Core Concepts
+
+### TaskQueue
+
+The `TaskQueue<Definitions>` class is the primary entry point. It manages the lifecycle of tasks, handles persistence, and provides the worker loop abstraction.
+
+### Task
+
+A unit of work defined by its `type`. Key properties include:
+
+- **Status**: `Pending` → `Running` → `Completed` (or `Failed`/`Dead`/`Cancelled`/`Waiting`).
+- **Lease**: A temporary lock (`visibilityDeadline`) held by a worker during execution.
+- **Tries**: Number of attempts made to process the task.
+- **Data/State/Result**: Managed, type-safe JSON payloads.
+
+### Worker
+
+A function that processes tasks. The `TaskQueue` provides a managed loop (`process`) that handles:
+
+1.  **Dequeueing**: Locking tasks from the database.
+2.  **Heartbeating**: Automatically extending the lease (`touch`) while the worker runs.
+3.  **Completion**: Resolving the task state based on the handler's return value.
+
+## 🚀 Basic Usage
+
+### Configuration
+
+Register the PostgreSQL backend in your application bootstrap.
+
+```typescript
+import { configurePostgresTaskQueue } from '@tstdl/base/task-queue/postgres';
+
+export async function bootstrap() {
+  // Configure the module
+  configurePostgresTaskQueue();
+}
+```
+
+### Defining Tasks
+
+Define your task types and their payload shapes using a `TaskDefinitionMap`.
+
+```typescript
+import { TaskDefinitionMap } from '@tstdl/base/task-queue';
+
+export type MyTasks = TaskDefinitionMap<{
+  'send-email': {
+    data: { to: string; subject: string; body: string };
+    state: { sentAt?: number };
+    result: { messageId: string };
+  };
+  'generate-report': {
+    data: { reportId: string };
+    state: { progress: number };
+    result: void;
+  };
+}>;
+```
+
+### Enqueueing Tasks
+
+Inject the `TaskQueue` service.
+
+```typescript
+import { inject, Singleton } from '@tstdl/base/injector';
+import { TaskQueue } from '@tstdl/base/task-queue';
+
+@Singleton()
+export class MailService {
+  // Inject a queue named 'mail-queue' with our definitions
+  readonly #queue = inject<TaskQueue<MyTasks>>(TaskQueue, 'mail-queue');
+
+  async sendLater(to: string, subject: string, body: string): Promise<void> {
+    await this.#queue.enqueue('send-email', { to, subject, body });
+  }
+}
+```
+
+### Processing Tasks
+
+Start a worker to process tasks. The handler receives a `TaskContext` and must return a `TaskProcessResult`.
+
+```typescript
+import { inject, Singleton } from '@tstdl/base/injector';
+import { Logger } from '@tstdl/base/logger';
+import { CancellationSignal } from '@tstdl/base/cancellation';
+import { TaskQueue, TaskProcessResult } from '@tstdl/base/task-queue';
+
+@Singleton()
+export class MailWorker {
+  readonly #queue = inject<TaskQueue<MyTasks>>(TaskQueue, 'mail-queue');
+  readonly #logger = inject(Logger, 'MailWorker');
+
+  start(signal: CancellationSignal): void {
+    this.#queue.process(
+      {
+        cancellationSignal: signal,
+        concurrency: 5, // Process up to 5 tasks concurrently
+      },
+      async (context) => {
+        this.#logger.info(`Sending mail to ${context.data.to}`);
+
+        const messageId = await sendEmail(context.data);
+
+        // Update state periodically if needed
+        await context.checkpoint({ state: { sentAt: Date.now() } });
+
+        return TaskProcessResult.Complete({ messageId });
+      },
+    );
+  }
+}
+```
+
+## 🔧 Advanced Topics
+
+### Task Hierarchies (Parent/Child)
+
+You can spawn child tasks from within a worker. The parent task will enter a `Waiting` state and will only transition back to `Pending` (or `Completed`) once all its children have reached a terminal state.
+
+```typescript
+this.#queue.process({ cancellationSignal }, async (context) => {
+  // 1. Spawn child tasks. These are automatically linked to the current task.
+  await context.spawn('send-email', { to: 'admin@example.com', ... });
+  await context.spawn('send-email', { to: 'user@example.com', ... });
+
+  // 2. Complete the current execution.
+  // The task transitions to 'Waiting' until children finish.
+  return TaskProcessResult.Complete();
+});
+```
+
+### Batch Operations
+
+For high throughput, use batch operations to reduce database round-trips.
+
+**Enqueueing:**
+
+```typescript
+const batch = this.#queue.batch();
+batch.add('send-email', { to: 'user1@example.com', ... });
+batch.add('send-email', { to: 'user2@example.com', ... });
+
+await batch.enqueue();
+```
+
+### Deduplication (Idempotency)
+
+Prevent duplicate tasks using `idempotencyKey`.
+
+```typescript
+// If a task with this key exists, this call does nothing (it returns the existing task).
+await queue.enqueue('generate-report', data, {
+  idempotencyKey: 'report-2023-10',
+});
+
+// Use 'replace: true' to update the existing task and reset it to 'Pending'.
+await queue.enqueue('generate-report', data, {
+  idempotencyKey: 'report-2023-10',
+  replace: true,
+});
+```
+
+### Prioritization
+
+Tasks with lower priority numbers are processed first. The default is `1000`.
+
+```typescript
+await queue.enqueue('type', data, { priority: 1 }); // High priority
+await queue.enqueue('type', data, { priority: 9000 }); // Low priority
+```
+
+### Transactional Enqueueing
+
+Enqueue tasks atomically within an existing database transaction. The task will only be visible to workers if the transaction commits.
+
+```typescript
+import { inject } from '@tstdl/base/injector';
+import { Database } from '@tstdl/base/orm/server';
+
+const database = inject(Database);
+
+await database.transaction(async (tx) => {
+  await userService.create(user, tx);
+
+  // Pass the transaction to the enqueue options
+  await queue.enqueue('welcome-email', { userId: user.id }, { transaction: tx });
+});
+```
+
+### Manual Consumption
+
+If you need full control over the consumption loop (e.g., for custom logic), use the async iterator.
+
+```typescript
+async function runCustomWorker(queue: TaskQueue<any>, signal: CancellationSignal) {
+  for await (const task of queue.getConsumer(signal)) {
+    try {
+      // Manually touch to keep lease alive
+      await queue.touch(task);
+
+      // Do work...
+
+      // Manually complete
+      await queue.complete(task, { result: 'done' });
+    } catch (error) {
+      await queue.fail(task, error);
+    }
+  }
+}
+```
+
+## 📚 API
+
+### `TaskQueue<Definitions>`
+
+| Method                           | Description                                                                            |
+| :------------------------------- | :------------------------------------------------------------------------------------- |
+| `enqueue(type, data, options?)`  | Adds a single task to the queue.                                                       |
+| `enqueueMany(items, options?)`   | Adds multiple tasks efficiently.                                                       |
+| `batch()`                        | Returns a `TaskQueueEnqueueBatch` builder.                                             |
+| `waitForTasks(ids, options?)`    | Reactive waiting for tasks to reach a finalized state (Completed, Dead, or Cancelled). |
+| `process(options, handler)`      | Starts a managed worker loop for single tasks.                                         |
+| `dequeue(options?)`              | Locks and retrieves the next available task(s).                                        |
+| `complete(task, options?)`       | Marks a task as completed.                                                             |
+| `fail(task, error, options?)`    | Marks a task as failed. Retries if `fatal` is false and tries remain.                  |
+| `touch(task, options?)`          | Extends the worker lease and optionally updates progress/state.                        |
+| `cancel(id, options?)`           | Cancels a task and optionally its descendants.                                         |
+| `getTree(id, options?)`          | Retrieves a task and all its descendants.                                              |
+| `reschedule(id, time, options?)` | Sets a new schedule timestamp for a task.                                              |
+
+### `TaskContext<Definitions, Type>`
+
+Passed to the worker handler.
+
+| Property/Method               | Description                                                          |
+| :---------------------------- | :------------------------------------------------------------------- |
+| `data`                        | The input data for the task.                                         |
+| `state`                       | The current state of the task.                                       |
+| `attempt`                     | Current attempt number (starts at 1).                                |
+| `spawn(type, data, options?)` | Creates a child task linked to the current task.                     |
+| `spawnMany(items)`            | Creates multiple child tasks.                                        |
+| `checkpoint(options?)`        | Updates progress/state and extends the lease.                        |
+| `reschedule(time)`            | Stops execution and reschedules for a future time.                   |
+| `complete(result?)`           | Manually completes the task (alternative to returning from handler). |
+| `fail(error, fatal?)`         | Manually fails the task.                                             |
+
+### `QueueConfig`
+
+| Property                  | Default | Description                                        |
+| :------------------------ | :------ | :------------------------------------------------- |
+| `visibilityTimeout`       | `5m`    | Duration before a worker token is considered lost. |
+| `maxExecutionTime`        | `60m`   | Hard limit for `Running` state.                    |
+| `maxTries`                | `3`     | Maximum dequeue attempts allowed.                  |
+| `retention`               | `30d`   | Duration to retain terminal tasks before archival. |
+| `globalConcurrency`       | `null`  | Max simultaneous running tasks across all workers. |
+| `circuitBreakerThreshold` | `5`     | Failures before tripping the circuit breaker.      |
+| `retryDelayMinimum`       | `5s`    | Floor for exponential backoff delay.               |
+| `retryDelayMaximum`       | `5m`    | Ceiling for exponential backoff delay.             |
+| `idempotencyWindow`       | `1h`    | Time to retain non-replaced idempotency keys.      |
+| `priorityAgingInterval`   | `1m`    | Interval for automatic priority promotion.         |

package/task-queue/postgres/drizzle/{0000_simple_invisible_woman.sql → 0000_wakeful_sunspot.sql}

@@ -1,5 +1,5 @@
-CREATE TYPE "task_queue"."dependency_join_mode" AS ENUM('and', 'or');--> statement-breakpoint
-CREATE TYPE "task_queue"."task_status" AS ENUM('pending', 'running', 'completed', 'cancelled', 'waiting', 'dead');--> statement-breakpoint
+CREATE TYPE "task_queue"."task_dependency_type" AS ENUM('schedule', 'complete');--> statement-breakpoint
+CREATE TYPE "task_queue"."task_status" AS ENUM('pending', 'running', 'completed', 'cancelled', 'dead', 'waiting', 'waiting-children', 'paused');--> statement-breakpoint
 CREATE TABLE "task_queue"."task" (
 	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
 	"namespace" text NOT NULL,
@@ -8,12 +8,10 @@ CREATE TABLE "task_queue"."task" (
 	"idempotency_key" text,
 	"trace_id" text,
 	"tags" text[] NOT NULL,
-	"complete_after_tags" text[] NOT NULL,
-	"schedule_after_tags" text[] NOT NULL,
 	"fail_fast" boolean NOT NULL,
-	"dependency_join_mode" "task_queue"."dependency_join_mode" NOT NULL,
-	"dependency_trigger_statuses" "task_queue"."task_status"[] NOT NULL,
 	"priority" integer NOT NULL,
+	"unresolved_schedule_dependencies" integer NOT NULL,
+	"unresolved_complete_dependencies" integer NOT NULL,
 	"token" uuid,
 	"creation_timestamp" timestamp with time zone NOT NULL,
 	"priority_age_timestamp" timestamp with time zone NOT NULL,
@@ -29,6 +27,7 @@ CREATE TABLE "task_queue"."task" (
 	"result" jsonb,
 	"error" jsonb,
 	"parent_id" uuid,
+	CONSTRAINT "task_namespace_id_unique" UNIQUE("namespace","id"),
 	CONSTRAINT "task_namespace_idempotency_key_unique" UNIQUE("namespace","idempotency_key")
 );
 --> statement-breakpoint
@@ -40,12 +39,10 @@ CREATE TABLE "task_queue"."task_archive" (
 	"idempotency_key" text,
 	"trace_id" text,
 	"tags" text[] NOT NULL,
-	"complete_after_tags" text[] NOT NULL,
-	"schedule_after_tags" text[] NOT NULL,
 	"fail_fast" boolean NOT NULL,
-	"dependency_join_mode" "task_queue"."dependency_join_mode" NOT NULL,
-	"dependency_trigger_statuses" "task_queue"."task_status"[] NOT NULL,
 	"priority" integer NOT NULL,
+	"unresolved_schedule_dependencies" integer NOT NULL,
+	"unresolved_complete_dependencies" integer NOT NULL,
 	"token" uuid,
 	"creation_timestamp" timestamp with time zone NOT NULL,
 	"priority_age_timestamp" timestamp with time zone NOT NULL,
@@ -63,12 +60,23 @@ CREATE TABLE "task_queue"."task_archive" (
 	"parent_id" uuid
 );
 --> statement-breakpoint
-ALTER TABLE "task_queue"."task" ADD CONSTRAINT "task_parent_id_task_id_fk" FOREIGN KEY ("parent_id") REFERENCES "task_queue"."task"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
+CREATE TABLE "task_queue"."task_dependency" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"namespace" text NOT NULL,
+	"task_id" uuid NOT NULL,
+	"dependency_task_id" uuid NOT NULL,
+	"type" "task_queue"."task_dependency_type" NOT NULL,
+	"required_statuses" "task_queue"."task_status"[] NOT NULL,
+	CONSTRAINT "td_namespace_task_id_dependency_task_id_type_unique" UNIQUE("namespace","task_id","dependency_task_id","type")
+);
+--> statement-breakpoint
+ALTER TABLE "task_queue"."task" ADD CONSTRAINT "task_namespace_parentId_task_fkey" FOREIGN KEY ("namespace","parent_id") REFERENCES "task_queue"."task"("namespace","id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "task_queue"."task_dependency" ADD CONSTRAINT "task_dependency_namespace_dependencyTaskId_task_fkey" FOREIGN KEY ("namespace","dependency_task_id") REFERENCES "task_queue"."task"("namespace","id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "task_queue"."task_dependency" ADD CONSTRAINT "task_dependency_namespace_taskId_task_fkey" FOREIGN KEY ("namespace","task_id") REFERENCES "task_queue"."task"("namespace","id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
 CREATE INDEX "task_parent_id_idx" ON "task_queue"."task" USING btree ("parent_id");--> statement-breakpoint
 CREATE INDEX "task_status_visibility_deadline_idx" ON "task_queue"."task" USING btree ("status","visibility_deadline");--> statement-breakpoint
 CREATE INDEX "task_status_complete_timestamp_idx" ON "task_queue"."task" USING btree ("status","complete_timestamp");--> statement-breakpoint
-CREATE INDEX "task_schedule_after_tags_idx" ON "task_queue"."task" USING gin ("schedule_after_tags");--> statement-breakpoint
-CREATE INDEX "task_complete_after_tags_idx" ON "task_queue"."task" USING gin ("complete_after_tags");--> statement-breakpoint
 CREATE INDEX "task_tags_idx" ON "task_queue"."task" USING gin ("tags");--> statement-breakpoint
 CREATE INDEX "task_namespace_status_schedule_timestamp_priority_idx" ON "task_queue"."task" USING btree ("namespace","status","schedule_timestamp","priority");--> statement-breakpoint
-CREATE INDEX "task_archive_namespace_complete_timestamp_idx" ON "task_queue"."task_archive" USING btree ("namespace","complete_timestamp");
+CREATE INDEX "task_archive_namespace_complete_timestamp_idx" ON "task_queue"."task_archive" USING btree ("namespace","complete_timestamp");--> statement-breakpoint
+CREATE INDEX "task_dependency_namespace_dependency_task_id_type_idx" ON "task_queue"."task_dependency" USING btree ("namespace","dependency_task_id","type");