Watching Tasks

While Streaming Updates monitors a single task, watchTasks / TaskWatcher lets you subscribe to updates across all tasks — useful for building dashboards, monitoring systems, or audit logs.

Basic Usage

TypeScript
Python

import { watchTasks } from '@requence/task'

const stop = watchTasks({
  since: new Date(),
  onUpdate(update) {
    console.log(`[${update.type}] Task ${update.context.taskId}`)
  },
})

// Later — stop watching
stop()

watchTasks returns a function that stops the watcher when called. It is also an AsyncIterable:

const watcher = watchTasks({ since: new Date() })

for await (const update of watcher) {
  console.log(update.type, update.context.taskId)

  if (shouldStop) {
    watcher() // stop watching
    break
  }
}

from requence.task import TaskWatcher
from datetime import datetime

watcher = TaskWatcher(since=datetime.now())

# Synchronous iteration
for update, incomplete in watcher.sync().updates:
    print(f"[{update['type']}] Task {update['context'].task_id}")

# Async iteration
async for update, incomplete in watcher.updates:
    print(f"[{update['type']}] Task {update['context'].task_id}")

Call watcher.stop() to disconnect:

watcher.stop()

| Option | Type | Description | |--------|------|-------------| | since | Date | Required. Only receive updates after this timestamp. | | accessToken | string | Access token (falls back to env / config file) | | filter.only | string[] | Only receive specific update types (e.g. ['taskEnd', 'taskError']) | | onUpdate | function | Callback for each update | | onConnect | function | Called when the connection is established | | onReconnecting | function | Called when the connection is being re-established | | onError | function | Called on connection errors |

| Option | Type | Description | |--------|------|-------------| | since | date | Required. Only receive updates after this timestamp. | | access_token | str | Access token (falls back to env / config file) | | on_connect | callable | Called when the connection is established |

Incomplete Updates

Each update includes an incomplete flag. When True, it means the watcher connected after the task had already started — the taskStart event was missed. Use this to decide whether to ignore or partially process the update.

Delivery Guarantee

When a task was started with requireAck: true, watchTasks / TaskWatcher automatically sends the ACK as soon as the terminal event (taskEnd, taskError, or taskAborted) is received — no extra code required.

The ACK is sent using the same access token passed to watchTasks, so the backend can confirm the correct subscriber received the result. See Delivery Guarantee for the full explanation.