@tstdl/base 0.93.138 → 0.93.140

package/sse/README.md

@@ -0,0 +1,278 @@
+# @tstdl/base/sse
+
+A comprehensive module for Server-Sent Events (SSE) that provides both a low-level reactive client for discrete events and a high-level, delta-capable data streaming abstraction for synchronizing complex objects efficiently.
+
+## Table of Contents
+
+- [✨ Features](#-features)
+- [Core Concepts](#core-concepts)
+  - [High-Level: Data Streaming](#high-level-data-streaming)
+  - [Low-Level: Event Pushing](#low-level-event-pushing)
+- [🚀 Basic Usage](#-basic-usage)
+  - [Server-Side Data Streaming](#server-side-data-streaming)
+  - [Client-Side Data Consumption](#client-side-data-consumption)
+- [🔧 Advanced Topics](#-advanced-topics)
+  - [Low-Level Event Pushing](#low-level-event-pushing-1)
+  - [Handling Errors](#handling-errors)
+- [📚 API](#-api)
+
+## ✨ Features
+
+- **Isomorphic Design**: Type-safe utilities for both server (Node.js/Edge) and client (Browser) environments.
+- **Smart Data Synchronization**: `DataStreamSource` automatically calculates JSON diffs (deltas) between updates to minimize bandwidth usage. For optimal array synchronization, ensure your objects have an `id` property.
+- **Automatic State Reconstruction**: The client-side `DataStream` utility automatically patches the local state with incoming deltas, exposing a seamless RxJS Observable of the full object.
+- **Reactive Client**: A robust RxJS wrapper around the native `EventSource` API (`ServerSentEvents`) for handling connection states and events.
+- **Web Streams Support**: Server-side implementation uses standard `ReadableStream`, making it compatible with modern runtimes.
+- **Full SSE Specification**: Supports named events, custom IDs, retry intervals, and comments.
+
+## Core Concepts
+
+### High-Level: Data Streaming
+
+The **Data Streaming** abstraction is designed for synchronizing a single, potentially complex state object between the server and client.
+
+- **Server (`DataStreamSource`)**: You simply pass the full object to the source whenever it changes. The source uses `jsondiffpatch` to calculate the difference between the current and previous object. It sends the full object initially, and then only the small deltas for subsequent updates.
+- **Client (`DataStream`)**: Consumes the stream, listening for `data` (full snapshot) and `delta` (patch) events. It maintains the local state by applying patches automatically and emits the fully updated object to subscribers.
+
+### Low-Level: Event Pushing
+
+The **Event Pushing** layer provides direct control over the SSE protocol, suitable for sending discrete notifications (e.g., "OrderShipped", "NewMessage").
+
+- **Server (`ServerSentEventsSource`)**: A wrapper around a `TransformStream` that formats messages according to the SSE spec.
+- **Client (`ServerSentEvents`)**: Wraps the browser's `EventSource` to provide RxJS Observables for messages, connection status, and errors.
+
+## 🚀 Basic Usage
+
+### Server-Side Data Streaming
+
+Use `DataStreamSource` to stream state changes. The most convenient way is `DataStreamSource.fromIterable`.
+
+```typescript
+import { apiController, type ApiServerResult } from '@tstdl/base/api/server';
+import { defineApi } from '@tstdl/base/api';
+import { DataStream, DataStreamSource } from '@tstdl/base/sse';
+import { CancellationSignal } from '@tstdl/base/cancellation';
+import { inject } from '@tstdl/base/injector';
+import { timeout } from '@tstdl/base/utils/timing';
+import { object, string, number } from '@tstdl/base/schema';
+
+// 1. Define the data shape
+const StockPrice = object({
+  symbol: string(),
+  price: number(),
+  timestamp: number(),
+});
+type StockPrice = typeof StockPrice.T;
+
+// 2. Define the API
+const stockApi = defineApi({
+  resource: 'stocks',
+  endpoints: {
+    track: {
+      resource: ':symbol/stream',
+      method: 'GET',
+      parameters: object({ symbol: string() }),
+      result: DataStream<StockPrice>, // Type hint for the client
+    },
+  },
+});
+
+// 3. Implement the Controller
+@apiController(stockApi)
+class StockApiController {
+  #cancellationSignal = inject(CancellationSignal);
+
+  track({ parameters }: any): ApiServerResult<typeof stockApi, 'track'> {
+    // Create an async generator that yields data updates
+    const ticker = this.createTicker(parameters.symbol, this.#cancellationSignal);
+
+    // Create a source that automatically handles diffing and serialization
+    return DataStreamSource.fromIterable(ticker, { delta: true });
+  }
+
+  async *createTicker(symbol: string, signal: CancellationSignal): AsyncIterable<StockPrice> {
+    let price = 100;
+    while (signal.isUnset) {
+      price += (Math.random() - 0.5) * 2;
+      yield { symbol, price, timestamp: Date.now() };
+      await timeout(1000, signal);
+    }
+  }
+}
+```
+
+### Client-Side Data Consumption
+
+Use `DataStream.parse` to transform the raw SSE connection into a stream of your data objects.
+
+```typescript
+import { DataStream, ServerSentEvents } from '@tstdl/base/sse';
+import { type Observable } from 'rxjs';
+
+type StockPrice = {
+  symbol: string;
+  price: number;
+  timestamp: number;
+};
+
+// 1. Establish the connection
+const sse = new ServerSentEvents('/api/stocks/AAPL/stream');
+
+// 2. Parse the data stream
+// This handles the initial full load and all subsequent delta patches automatically
+const stock$: Observable<StockPrice> = DataStream.parse<StockPrice>(sse);
+
+// 3. Subscribe to updates
+const subscription = stock$.subscribe({
+  next: (stock) => {
+    console.log(`Update for ${stock.symbol}: $${stock.price.toFixed(2)}`);
+  },
+  error: (err) => console.error('Stream error:', err),
+  complete: () => console.log('Stream closed'),
+});
+
+// Cleanup when done
+// subscription.unsubscribe();
+```
+
+## 🔧 Advanced Topics
+
+### Low-Level Event Pushing
+
+If you don't need object synchronization and just want to send named events, use `ServerSentEventsSource` directly.
+
+**Server:**
+
+```typescript
+import { ServerSentEventsSource } from '@tstdl/base/sse';
+import { timeout } from '@tstdl/base/utils/timing';
+
+async function notificationStream(): Promise<ServerSentEventsSource> {
+  const source = new ServerSentEventsSource();
+
+  // Run in background
+  (async () => {
+    await timeout(1000);
+    if (source.closed()) return;
+
+    // Send a named JSON event
+    await source.sendJson({
+      name: 'notification',
+      id: '1',
+      data: { message: 'Hello World' },
+    });
+
+    await timeout(2000);
+    if (source.closed()) return;
+
+    // Send a text event
+    await source.sendText({
+      name: 'ping',
+      data: 'keep-alive',
+    });
+
+    await source.close();
+  })();
+
+  return source;
+}
+```
+
+**Client:**
+
+```typescript
+import { ServerSentEvents } from '@tstdl/base/sse';
+import { filter, map } from 'rxjs';
+
+const sse = new ServerSentEvents('/api/notifications');
+
+// Listen specifically for 'notification' events
+const notifications$ = sse.message$('notification').pipe(map((event) => JSON.parse(event.data)));
+
+notifications$.subscribe((data) => console.log('New notification:', data));
+```
+
+### Handling Errors
+
+The `DataStreamSource` has a built-in mechanism to send errors to the client before closing the stream.
+
+```typescript
+// Server
+const source = new DataStreamSource();
+try {
+  // ... logic
+} catch (err) {
+  // Sends an 'error' event with the formatted error and closes the connection
+  await source.error(err);
+}
+```
+
+On the client side, `DataStream.parse` will listen for these `error` events and error out the Observable stream accordingly.
+
+## 📚 API
+
+### `DataStreamSource<T>`
+
+Server-side class for streaming data objects with optional delta compression.
+
+| Member         | Signature                                                    | Description                                                                         |
+| :------------- | :----------------------------------------------------------- | :---------------------------------------------------------------------------------- |
+| `constructor`  | `(options?: DataStreamSourceOptions)`                        | Creates a new source. Options include `delta` (boolean) and `errorFormatter`.       |
+| `fromIterable` | `static fromIterable<T>(iterable: AnyIterable<T>, options?)` | Creates a source that automatically pulls from an async iterable and sends updates. |
+| `send`         | `send(data: T): Promise<void>`                               | Sends a data update. If `delta` is enabled, calculates diff from previous data.     |
+| `error`        | `error(error: unknown): Promise<void>`                       | Sends an error event to the client and closes the stream.                           |
+| `close`        | `close(): Promise<void>`                                     | Closes the underlying stream.                                                       |
+| `closed`       | `ReadonlySignal<boolean>`                                    | Signal indicating if the stream is closed.                                          |
+| `eventSource`  | `ServerSentEventsSource`                                     | Access to the underlying SSE source.                                                |
+
+### `DataStream<T>`
+
+Client-side utility for reconstructing data streams.
+
+| Member  | Signature                                                       | Description                                                                          |
+| :------ | :-------------------------------------------------------------- | :----------------------------------------------------------------------------------- |
+| `parse` | `static parse<T>(eventSource: ServerSentEvents): Observable<T>` | Transforms an SSE connection into an Observable of the synchronized data object `T`. |
+
+### `ServerSentEventsSource`
+
+Low-level server-side SSE writer.
+
+| Member        | Signature                                             | Description                                                               |
+| :------------ | :---------------------------------------------------- | :------------------------------------------------------------------------ |
+| `readable`    | `ReadableStream<string>`                              | The Web Stream to return in the HTTP response body.                       |
+| `sendJson`    | `sendJson(event: ServerSentJsonEvent): Promise<void>` | Sends a named event with JSON data.                                       |
+| `sendText`    | `sendText(event: ServerSentTextEvent): Promise<void>` | Sends a named event with raw text data.                                   |
+| `sendComment` | `sendComment(comment: string): Promise<void>`         | Sends an SSE comment (ignored by browser clients, useful for keep-alive). |
+| `close`       | `close(): Promise<void>`                              | Closes the stream.                                                        |
+| `closed`      | `ReadonlySignal<boolean>`                             | Signal indicating if the stream is closed.                                |
+| `error`       | `ReadonlySignal<Error \| undefined>`                  | Signal containing the error if the stream failed.                         |
+
+### `ServerSentEvents`
+
+Client-side reactive wrapper for `EventSource`.
+
+| Member          | Signature                                            | Description                                                                            |
+| :-------------- | :--------------------------------------------------- | :------------------------------------------------------------------------------------- |
+| `constructor`   | `(url: string, options?: EventSourceInit)`           | Initiates the connection.                                                              |
+| `message$`      | `message$(event?: string): Observable<MessageEvent>` | Returns an Observable of messages. If `event` is provided, filters by that event name. |
+| `state$`        | `Observable<ServerSentEventsState>`                  | Emits connection state changes (`Connecting`, `Open`, `Closed`).                       |
+| `open$`         | `Observable<void>`                                   | Emits when the connection is open.                                                     |
+| `close$`        | `Observable<void>`                                   | Emits when the connection is closed.                                                   |
+| `error$`        | `Observable<Event>`                                  | Emits on connection errors.                                                            |
+| `isOpen$`       | `Observable<boolean>`                                | Emits `true` when connected.                                                           |
+| `isConnecting$` | `Observable<boolean>`                                | Emits `true` when connecting.                                                          |
+| `isClosed$`     | `Observable<boolean>`                                | Emits `true` when closed.                                                              |
+| `state`         | `ServerSentEventsState`                              | Gets the current connection state.                                                     |
+| `close`         | `close(): void`                                      | Manually closes the connection.                                                        |
+
+### Types
+
+| Type                        | Description                                                                       |
+| :-------------------------- | :-------------------------------------------------------------------------------- |
+| `DataStreamSourceOptions`   | Options for `DataStreamSource`: `delta` (boolean) and `errorFormatter` (function). |
+| `DataStreamErrorFormatter`  | Function type: `(error: unknown) => UndefinableJson`.                             |
+| `ServerSentEventBase<Data>` | Base interface for events with `name`, `data`, `id`, and `retry`.                 |
+| `ServerSentJsonEvent`       | Event where `data` is any JSON-serializable value.                                |
+| `ServerSentTextEvent`       | Event where `data` is a string.                                                   |
+| `ServerSentEvent`           | Union of `ServerSentTextEvent` and `ServerSentJsonEvent`.                         |
+| `ServerSentEventsState`     | Enum: `Connecting` (0), `Open` (1), `Closed` (2).                                 |

package/task-queue/README.md

@@ -0,0 +1,300 @@
+# 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, migratePostgresTaskQueueSchema } from '@tstdl/base/task-queue/postgres';
+import { runInInjectionContext, inject } from '@tstdl/base/injector';
+import { Injector } from '@tstdl/base/injector';
+
+export async function bootstrap() {
+  const injector = inject(Injector);
+
+  // Configure the module (uses default DatabaseConfig from context)
+  configurePostgresTaskQueue();
+
+  // Run migrations to create the 'task_queue.task' table
+  await runInInjectionContext(injector, migratePostgresTaskQueueSchema);
+}
+```
+
+### 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/task-queue.d.ts

@@ -3,7 +3,7 @@ import { afterResolve } from '../../injector/index.js';
 import type { Query } from '../../orm/index.js';
 import { type Transaction } from '../../orm/server/index.js';
 import type { OneOrMany } from '../../schema/index.js';
-import { TaskQueue, type EnqueueManyItem, type EnqueueManyOptions, type EnqueueOneOptions, type Task } from '../task-queue.js';
+import { TaskQueue, type EnqueueManyItem, type EnqueueManyOptions, type EnqueueOneOptions, type Task, type TaskQueueWaitOptions, type TaskQueueWaitResult } from '../task-queue.js';
 import type { TaskData, TaskDefinitionMap, TaskOfType, TaskResult, TasksResults, TasksStates, TaskState, TaskTypes } from '../types.js';
 export declare class PostgresTaskQueue<Definitions extends TaskDefinitionMap = TaskDefinitionMap> extends TaskQueue<Definitions> {
     #private;
@@ -49,6 +49,7 @@ export declare class PostgresTaskQueue<Definitions extends TaskDefinitionMap = T
     getTreeByQuery(query: Query<Task>, options?: {
         transaction?: Transaction;
     }): Promise<Task[]>;
+    waitForTasks(ids: string[], options?: TaskQueueWaitOptions): Promise<TaskQueueWaitResult>;
     cancel(id: string, options?: {
         transaction?: Transaction;
     }): Promise<void>;

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

@@ -57,10 +57,10 @@ var __disposeResources = (this && this.__disposeResources) || (function (Suppres
     return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
 });
 import { and, asc, count, eq, gt, gte, inArray, lt, lte, notInArray, or, sql, isNull as sqlIsNull } from 'drizzle-orm';
-import { merge } from 'rxjs';
+import { merge, throttleTime } from 'rxjs';
 import { CancellationSignal } from '../../cancellation/index.js';
 import { CircuitBreaker, CircuitBreakerState } from '../../circuit-breaker/index.js';
-import { serializeError } from '../../errors/index.js';
+import { serializeError, TimeoutError } from '../../errors/index.js';
 import { afterResolve, inject, provide, Singleton } from '../../injector/index.js';
 import { Logger } from '../../logger/index.js';
 import { MessageBus } from '../../message-bus/index.js';
@@ -70,6 +70,7 @@ import { RateLimiter } from '../../rate-limit/index.js';
 import { createArray, distinct, toArray } from '../../utils/array/array.js';
 import { digest } from '../../utils/cryptography.js';
 import { currentTimestamp } from '../../utils/date-time.js';
+import { Timer } from '../../utils/timer.js';
 import { cancelableTimeout } from '../../utils/timing.js';
 import { isDefined, isNotNull, isNull, isString, isUndefined } from '../../utils/type-guards.js';
 import { millisecondsPerSecond } from '../../utils/units.js';
@@ -304,6 +305,35 @@ let PostgresTaskQueue = class PostgresTaskQueue extends TaskQueue {
             return await repositoryWithTransaction.mapManyToEntity(rows);
         });
     }
+    async waitForTasks(ids, options) {
+        if (ids.length == 0) {
+            return { cancelled: false };
+        }
+        const timeout = options?.timeout ?? Infinity;
+        const interval = options?.interval ?? 1000;
+        const cancellationSignal = this.#cancellationSignal.optionallyInherit(options?.cancellationSignal);
+        const continue$ = merge(this.#messageBus.allMessages$.pipe(throttleTime(50, undefined, { leading: true, trailing: true })), cancellationSignal);
+        const timer = Timer.startNew();
+        const finalizedStatuses = [TaskStatus.Completed, TaskStatus.Cancelled, TaskStatus.Dead];
+        while (true) {
+            if (cancellationSignal.isSet) {
+                return { cancelled: true };
+            }
+            if (timer.milliseconds > timeout) {
+                throw new TimeoutError('Timeout while waiting for tasks to complete');
+            }
+            const hasNonFinalized = await this.#repository.hasByQuery({
+                id: { $in: ids },
+                status: { $nin: finalizedStatuses },
+            });
+            if (!hasNonFinalized) {
+                return { cancelled: false };
+            }
+            const remainingTimeout = timeout - timer.milliseconds;
+            const waitTime = Math.min(interval, remainingTimeout);
+            await cancelableTimeout(waitTime, continue$);
+        }
+    }
     async cancel(id, options) {
         await this.cancelMany([id], options);
     }

package/task-queue/task-context.js

@@ -46,7 +46,7 @@ export class TaskContext {
         return this.triesLeft <= 0;
     }
     get signal() {
-        return this.#signal.signal;
+        return this.#signal;
     }
     get logger() {
         return this.#logger;