@push.rocks/taskbuffer 4.0.0 → 4.1.1

package/readme.md

@@ -1,163 +1,169 @@
 # @push.rocks/taskbuffer 🚀
 
-> **Modern TypeScript task orchestration with smart buffering, scheduling, and real-time progress tracking**
+> **Modern TypeScript task orchestration with smart buffering, scheduling, labels, and real-time event streaming**
 
 [![npm version](https://img.shields.io/npm/v/@push.rocks/taskbuffer.svg)](https://www.npmjs.com/package/@push.rocks/taskbuffer)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue.svg)](https://www.typescriptlang.org/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
+## Issue Reporting and Security
+
+For reporting bugs, issues, or security vulnerabilities, please visit [community.foss.global/](https://community.foss.global/). This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a [code.foss.global/](https://code.foss.global/) account to submit Pull Requests directly.
+
 ## 🌟 Features
 
-- **🎯 Type-Safe Task Management** - Full TypeScript support with generics and type inference
-- **📊 Real-Time Progress Tracking** - Step-based progress with percentage weights
-- **⚡ Smart Buffering** - Intelligent request debouncing and batching
-- **⏰ Cron Scheduling** - Schedule tasks with cron expressions
-- **🔄 Task Chains & Parallel Execution** - Sequential and parallel task orchestration
-- **🎨 Web Component Dashboard** - Real-time visualization of task execution
-- **📈 Comprehensive Metadata** - Track execution history, duration, and status
-- **🔒 Thread-Safe Operations** - Concurrency control and execution limits
-- **🎭 Event-Driven Architecture** - Observable task lifecycle events
+- **🎯 Type-Safe Task Management** — Full TypeScript support with generics and type inference
+- **📊 Real-Time Progress Tracking** — Step-based progress with percentage weights
+- **⚡ Smart Buffering** — Intelligent request debouncing and batching
+- **⏰ Cron Scheduling** — Schedule tasks with cron expressions
+- **🔗 Task Chains & Parallel Execution** — Sequential and parallel task orchestration
+- **🏷️ Labels** — Attach arbitrary `Record<string, string>` metadata (userId, tenantId, etc.) for multi-tenant filtering
+- **📡 Push-Based Events** — rxjs `Subject<ITaskEvent>` on every Task and TaskManager for real-time state change notifications
+- **🛡️ Error Handling** — Configurable error propagation with `catchErrors`, error tracking, and clear error state
+- **🎨 Web Component Dashboard** — Built-in Lit-based dashboard for real-time task visualization
+- **🌐 Distributed Coordination** — Abstract coordinator for multi-instance task deduplication
 
 ## 📦 Installation
 
 ```bash
-npm install @push.rocks/taskbuffer
-# or
 pnpm add @push.rocks/taskbuffer
 # or
-yarn add @push.rocks/taskbuffer
+npm install @push.rocks/taskbuffer
 ```
 
 ## 🚀 Quick Start
 
-### Basic Task Creation
+### Basic Task
 
 ```typescript
-import { Task, TaskManager } from '@push.rocks/taskbuffer';
+import { Task } from '@push.rocks/taskbuffer';
 
-// Create a simple task
-const dataProcessor = new Task({
-  name: 'ProcessData',
-  taskFunction: async (data) => {
-    console.log(`Processing: ${data}`);
-    // Your async logic here
-    return `Processed: ${data}`;
-  }
+const greetTask = new Task({
+  name: 'Greet',
+  taskFunction: async (name) => {
+    return `Hello, ${name}!`;
+  },
 });
 
-// Execute the task
-const result = await dataProcessor.trigger('my-data');
-console.log(result); // "Processed: my-data"
+const result = await greetTask.trigger('World');
+console.log(result); // "Hello, World!"
 ```
 
-### Tasks with Progress Tracking 📊
+### Task with Steps & Progress 📊
 
 ```typescript
-const deploymentTask = new Task({
-  name: 'DeployApplication',
+const deployTask = new Task({
+  name: 'Deploy',
   steps: [
-    { name: 'build', description: 'Building application', percentage: 30 },
+    { name: 'build', description: 'Building app', percentage: 30 },
     { name: 'test', description: 'Running tests', percentage: 20 },
     { name: 'deploy', description: 'Deploying to server', percentage: 40 },
-    { name: 'verify', description: 'Verifying deployment', percentage: 10 }
-  ] as const, // Use 'as const' for type inference
-  taskFunction: async function() {
-    // TypeScript knows these step names!
-    this.notifyStep('build');
-    await buildApplication();
-    
-    this.notifyStep('test');
+    { name: 'verify', description: 'Verifying deployment', percentage: 10 },
+  ] as const,
+  taskFunction: async () => {
+    deployTask.notifyStep('build');
+    await buildApp();
+
+    deployTask.notifyStep('test');
     await runTests();
-    
-    this.notifyStep('deploy');
+
+    deployTask.notifyStep('deploy');
     await deployToServer();
-    
-    this.notifyStep('verify');
+
+    deployTask.notifyStep('verify');
     await verifyDeployment();
-    
+
     return 'Deployment successful!';
-  }
+  },
 });
 
-// Monitor progress
-console.log(deploymentTask.getProgress()); // 0-100
-console.log(deploymentTask.getStepsMetadata()); // Detailed step info
+await deployTask.trigger();
+console.log(deployTask.getProgress()); // 100
+console.log(deployTask.getStepsMetadata()); // Step details with status
 ```
 
+> **Note:** `notifyStep()` is fully type-safe — TypeScript only accepts step names you declared in the `steps` array when you use `as const`.
+
 ## 🎯 Core Concepts
 
-### Task Buffering - Intelligent Request Management
+### Task Buffering — Intelligent Request Management
 
-TaskBuffer's buffering system prevents overwhelming your system with rapid-fire requests:
+Prevent overwhelming your system with rapid-fire requests:
 
 ```typescript
 const apiTask = new Task({
   name: 'APIRequest',
+  buffered: true,
+  bufferMax: 5, // Maximum 5 concurrent executions
+  execDelay: 100, // Minimum 100ms between executions
   taskFunction: async (endpoint) => {
-    return await fetch(endpoint).then(r => r.json());
+    return await fetch(endpoint).then((r) => r.json());
   },
-  buffered: true,
-  bufferMax: 5,  // Maximum 5 concurrent executions
-  execDelay: 100 // Minimum 100ms between executions
 });
 
-// Rapid fire 100 calls - only 5 will execute concurrently
+// Rapid fire 100 calls — only bufferMax execute concurrently
 for (let i = 0; i < 100; i++) {
   apiTask.trigger(`/api/data/${i}`);
 }
 ```
 
 **Buffer Behavior:**
+
 - First `bufferMax` calls execute immediately
 - Additional calls are queued
 - When buffer is full, new calls overwrite the last queued item
 - Perfect for real-time data streams where only recent data matters
 
-### Task Chains - Sequential Workflows
+### Task Chains — Sequential Workflows 🔗
 
-Build complex workflows with automatic data flow:
+Build complex workflows with automatic data flow between tasks:
 
 ```typescript
-import { Task, Taskchain } from '@push.rocks/taskbuffer';
+import { Taskchain } from '@push.rocks/taskbuffer';
 
 const fetchTask = new Task({
-  name: 'FetchData',
+  name: 'Fetch',
   taskFunction: async () => {
-    const response = await fetch('/api/data');
-    return response.json();
-  }
+    const res = await fetch('/api/data');
+    return res.json();
+  },
 });
 
 const transformTask = new Task({
-  name: 'TransformData',
+  name: 'Transform',
   taskFunction: async (data) => {
-    return data.map(item => ({
-      ...item,
-      transformed: true,
-      timestamp: Date.now()
-    }));
-  }
+    return data.map((item) => ({ ...item, transformed: true }));
+  },
 });
 
 const saveTask = new Task({
-  name: 'SaveData',
+  name: 'Save',
   taskFunction: async (transformedData) => {
     await database.save(transformedData);
     return transformedData.length;
-  }
+  },
 });
 
-// Create and execute chain
-const dataChain = new Taskchain({
+const pipeline = new Taskchain({
   name: 'DataPipeline',
-  tasks: [fetchTask, transformTask, saveTask]
+  taskArray: [fetchTask, transformTask, saveTask],
 });
 
-const savedCount = await dataChain.trigger();
+const savedCount = await pipeline.trigger();
 console.log(`Saved ${savedCount} items`);
 ```
 
-### Parallel Execution - Concurrent Processing
+Taskchain also supports dynamic mutation:
+
+```typescript
+pipeline.addTask(newTask); // Append to chain
+pipeline.removeTask(oldTask); // Remove by reference (returns boolean)
+pipeline.shiftTask(); // Remove & return first task
+```
+
+Error context is rich — a chain failure includes the chain name, failing task name, task index, and preserves the original error as `.cause`.
+
+### Parallel Execution — Concurrent Processing ⚡
 
 Execute multiple tasks simultaneously:
 
@@ -165,21 +171,13 @@ Execute multiple tasks simultaneously:
 import { Taskparallel } from '@push.rocks/taskbuffer';
 
 const parallel = new Taskparallel({
-  name: 'ParallelProcessor',
-  tasks: [
-    emailTask,
-    smsTask,
-    pushNotificationTask,
-    webhookTask
-  ]
+  taskArray: [emailTask, smsTask, pushNotificationTask, webhookTask],
 });
 
-// All tasks execute concurrently
-const results = await parallel.trigger(notificationData);
-// results = [emailResult, smsResult, pushResult, webhookResult]
+await parallel.trigger(notificationData);
 ```
 
-### Debounced Tasks - Smart Trigger Coalescing
+### Debounced Tasks — Smart Trigger Coalescing 🕐
 
 Coalesce rapid triggers into a single execution after a quiet period:
 
@@ -187,441 +185,573 @@ Coalesce rapid triggers into a single execution after a quiet period:
 import { TaskDebounced } from '@push.rocks/taskbuffer';
 
 const searchTask = new TaskDebounced({
-  name: 'SearchQuery',
-  debounceTimeInMillis: 300, // Wait 300ms after last trigger
+  name: 'Search',
+  debounceTimeInMillis: 300,
   taskFunction: async (query) => {
-    const results = await searchAPI(query);
-    return results;
-  }
+    return await searchAPI(query);
+  },
 });
 
-// Rapid typing - only the last query executes
+// Rapid calls — only the last triggers after 300ms of quiet
 searchTask.trigger('h');
 searchTask.trigger('he');
 searchTask.trigger('hel');
-searchTask.trigger('hello'); // Only this one executes after 300ms pause
+searchTask.trigger('hello'); // ← this one fires
 ```
 
-### TaskManager - Centralized Orchestration
+### TaskOnce — Single-Execution Guard
 
-Manage all your tasks from a single point:
+Ensure a task only runs once, regardless of how many times it's triggered:
 
 ```typescript
-const taskManager = new TaskManager();
+import { TaskOnce } from '@push.rocks/taskbuffer';
 
-// Add tasks
-taskManager.addTask(dataProcessor);
-taskManager.addTask(deploymentTask);
+const initTask = new TaskOnce({
+  name: 'Init',
+  taskFunction: async () => {
+    await setupDatabase();
+    console.log('Initialized!');
+  },
+});
 
-// Schedule tasks with cron
-taskManager.addAndScheduleTask(backupTask, '0 2 * * *'); // Daily at 2 AM
-taskManager.addAndScheduleTask(healthCheck, '*/5 * * * *'); // Every 5 minutes
+await initTask.trigger(); // Runs
+await initTask.trigger(); // No-op
+await initTask.trigger(); // No-op
+console.log(initTask.hasTriggered); // true
+```
 
-// Get task metadata
-const metadata = taskManager.getTaskMetadata('DeployApplication');
-console.log(metadata);
-// {
-//   name: 'DeployApplication',
-//   status: 'idle' | 'running' | 'completed' | 'failed',
-//   steps: [...],
-//   currentProgress: 75,
-//   runCount: 12,
-//   lastRun: Date,
-//   buffered: false,
-//   bufferMax: undefined,
-//   version: '1.0.0',
-//   timeout: 30000
-// }
+### TaskRunner — Managed Queue with Concurrency Control
 
-// Get all scheduled tasks
-const scheduled = taskManager.getScheduledTasks();
-scheduled.forEach(task => {
-  console.log(`${task.name}: Next run at ${task.nextRun}`);
-});
+Process a queue of tasks with a configurable parallelism limit:
 
-// Execute and remove pattern
-const report = await taskManager.addExecuteRemoveTask(temporaryTask, {
-  trackProgress: true
-});
-console.log(report);
-// {
-//   taskName: 'TempTask',
-//   startTime: Date,
-//   endTime: Date,
-//   duration: 1523,
-//   steps: [...],
-//   stepsCompleted: ['step1', 'step2'],
-//   progress: 100,
-//   result: any,
-//   error?: Error
-// }
-```
+```typescript
+import { TaskRunner } from '@push.rocks/taskbuffer';
 
-## 🎨 Web Component Dashboard
+const runner = new TaskRunner();
+runner.setMaxParallelJobs(3); // Run up to 3 tasks concurrently
 
-Visualize your tasks in real-time with the included web component:
+await runner.start();
 
-```html
-<!DOCTYPE html>
-<html>
-<head>
-  <script type="module">
-    import { TaskManager } from '@push.rocks/taskbuffer';
-    import '@push.rocks/taskbuffer/dist_ts_web/taskbuffer-dashboard.js';
-    
-    const taskManager = new TaskManager();
-    
-    // Attach to dashboard
-    const dashboard = document.querySelector('taskbuffer-dashboard');
-    dashboard.taskManager = taskManager;
-    dashboard.refreshInterval = 500; // Update every 500ms
-  </script>
-</head>
-<body>
-  <taskbuffer-dashboard></taskbuffer-dashboard>
-</body>
-</html>
+runner.addTask(taskA);
+runner.addTask(taskB);
+runner.addTask(taskC);
+runner.addTask(taskD); // Queued until a slot opens
+
+// When done:
+await runner.stop();
 ```
 
-The dashboard provides:
-- 📊 Real-time progress bars with step indicators
-- 📈 Task execution history
-- ⏰ Scheduled task information
-- 🎯 Interactive task controls
-- 🌓 Light/dark theme support
+## 🏷️ Labels — Multi-Tenant Task Filtering
 
-## 🧩 Advanced Patterns
+Attach arbitrary key-value labels to any task for filtering, grouping, or multi-tenant isolation:
 
-### Dynamic Task Routing
+```typescript
+const task = new Task({
+  name: 'ProcessOrder',
+  labels: { userId: 'u-42', tenantId: 'acme-corp', priority: 'high' },
+  taskFunction: async (order) => {
+    /* ... */
+  },
+});
+
+// Manipulate labels at runtime
+task.setLabel('region', 'eu-west');
+task.getLabel('userId'); // 'u-42'
+task.hasLabel('tenantId', 'acme-corp'); // true
+task.removeLabel('priority'); // true
+
+// Labels are included in metadata snapshots
+const meta = task.getMetadata();
+console.log(meta.labels); // { userId: 'u-42', tenantId: 'acme-corp', region: 'eu-west' }
+```
 
-Route tasks based on conditions:
+### Filtering Tasks by Label in TaskManager
 
 ```typescript
-const routerTask = new Task({
-  name: 'Router',
-  taskFunction: async (request) => {
-    if (request.priority === 'high') {
-      return await expressProcessor.trigger(request);
-    } else if (request.size > 1000000) {
-      return await bulkProcessor.trigger(request);
-    } else {
-      return await standardProcessor.trigger(request);
-    }
-  }
-});
+const manager = new TaskManager();
+manager.addTask(orderTask1); // labels: { tenantId: 'acme' }
+manager.addTask(orderTask2); // labels: { tenantId: 'globex' }
+manager.addTask(orderTask3); // labels: { tenantId: 'acme' }
+
+const acmeTasks = manager.getTasksByLabel('tenantId', 'acme');
+// → [orderTask1, orderTask3]
+
+const acmeMetadata = manager.getTasksMetadataByLabel('tenantId', 'acme');
+// → [ITaskMetadata, ITaskMetadata]
 ```
 
-### Task Pools
+## 📡 Push-Based Events — Real-Time Task Lifecycle
 
-Create reusable task pools for load distribution:
+Every `Task` exposes an rxjs `Subject<ITaskEvent>` that emits events as the task progresses through its lifecycle:
 
 ```typescript
-class TaskPool {
-  private tasks: Task[] = [];
-  private currentIndex = 0;
-  
-  constructor(poolSize: number, taskConfig: any) {
-    for (let i = 0; i < poolSize; i++) {
-      this.tasks.push(new Task({
-        ...taskConfig,
-        name: `${taskConfig.name}_${i}`
-      }));
-    }
-  }
-  
-  async execute(data: any) {
-    const task = this.tasks[this.currentIndex];
-    this.currentIndex = (this.currentIndex + 1) % this.tasks.length;
-    return await task.trigger(data);
-  }
-}
+import type { ITaskEvent } from '@push.rocks/taskbuffer';
 
-const processorPool = new TaskPool(5, {
-  name: 'DataProcessor',
-  taskFunction: async (data) => processData(data)
+const task = new Task({
+  name: 'DataSync',
+  steps: [
+    { name: 'fetch', description: 'Fetching data', percentage: 50 },
+    { name: 'save', description: 'Saving data', percentage: 50 },
+  ] as const,
+  taskFunction: async () => {
+    task.notifyStep('fetch');
+    const data = await fetchData();
+    task.notifyStep('save');
+    await saveData(data);
+  },
 });
+
+// Subscribe to individual task events
+task.eventSubject.subscribe((event: ITaskEvent) => {
+  console.log(`[${event.type}] ${event.task.name} @ ${new Date(event.timestamp).toISOString()}`);
+  if (event.type === 'step') console.log(`  Step: ${event.stepName}`);
+  if (event.type === 'failed') console.log(`  Error: ${event.error}`);
+});
+
+await task.trigger();
+// [started] DataSync @ 2025-01-26T...
+// [step] DataSync @ 2025-01-26T...
+//   Step: fetch
+// [step] DataSync @ 2025-01-26T...
+//   Step: save
+// [completed] DataSync @ 2025-01-26T...
 ```
 
-### Error Recovery & Retry
+### Event Types
 
-Implement robust error handling:
+| Type | When | Extra Fields |
+| --- | --- | --- |
+| `'started'` | Task begins execution | — |
+| `'step'` | `notifyStep()` is called | `stepName` |
+| `'completed'` | Task finishes successfully | — |
+| `'failed'` | Task throws an error | `error` (message string) |
+
+Every event includes a full `ITaskMetadata` snapshot (including labels) at the time of emission.
+
+### Aggregated Events on TaskManager
+
+`TaskManager` automatically aggregates events from all added tasks into a single `taskSubject`:
 
 ```typescript
-const resilientTask = new Task({
-  name: 'ResilientTask',
-  taskFunction: async (data, retryCount = 0) => {
-    try {
-      return await riskyOperation(data);
-    } catch (error) {
-      if (retryCount < 3) {
-        console.log(`Retry ${retryCount + 1}/3`);
-        await new Promise(r => setTimeout(r, 1000 * Math.pow(2, retryCount)));
-        return await resilientTask.trigger(data, retryCount + 1);
-      }
-      throw error;
-    }
-  }
+const manager = new TaskManager();
+manager.addTask(syncTask);
+manager.addTask(reportTask);
+manager.addTask(cleanupTask);
+
+// Single subscription for ALL task events
+manager.taskSubject.subscribe((event) => {
+  sendToMonitoringDashboard(event);
 });
+
+// Events stop flowing for a task after removal
+manager.removeTask(syncTask);
 ```
 
-### Task Composition
+`manager.stop()` automatically cleans up all event subscriptions.
+
+## 🛡️ Error Handling
 
-Compose complex behaviors from simple tasks:
+By default, `trigger()` **rejects** when the task function throws — errors propagate naturally:
 
 ```typescript
-const compositeTask = new Task({
-  name: 'CompositeOperation',
-  steps: [
-    { name: 'validate', description: 'Validating input', percentage: 20 },
-    { name: 'process', description: 'Processing data', percentage: 60 },
-    { name: 'notify', description: 'Sending notifications', percentage: 20 }
-  ] as const,
-  taskFunction: async function(data) {
-    this.notifyStep('validate');
-    const validated = await validationTask.trigger(data);
-    
-    this.notifyStep('process');
-    const processed = await processingTask.trigger(validated);
-    
-    this.notifyStep('notify');
-    await notificationTask.trigger(processed);
-    
-    return processed;
-  }
+const task = new Task({
+  name: 'RiskyOp',
+  taskFunction: async () => {
+    throw new Error('something broke');
+  },
 });
+
+try {
+  await task.trigger();
+} catch (err) {
+  console.error(err.message); // "something broke"
+}
 ```
 
-## 🔧 Configuration
+### Swallowing Errors with `catchErrors`
 
-### Task Options
+Set `catchErrors: true` to swallow errors and return `undefined` instead of rejecting:
 
 ```typescript
-interface TaskOptions<T = undefined, TSteps = []> {
-  name?: string;              // Task identifier
-  taskFunction: Function;     // Async function to execute
-  buffered?: boolean;         // Enable buffering
-  bufferMax?: number;         // Max concurrent executions
-  execDelay?: number;         // Min delay between executions
-  timeout?: number;           // Task timeout in ms
-  version?: string;           // Task version
-  steps?: TSteps;            // Progress steps configuration
-  taskSetup?: Function;       // One-time setup function
-  beforeTask?: Function;      // Runs before each execution
-  afterTask?: Function;       // Runs after each execution
-}
+const task = new Task({
+  name: 'BestEffort',
+  catchErrors: true,
+  taskFunction: async () => {
+    throw new Error('non-critical');
+  },
+});
+
+const result = await task.trigger(); // undefined (no throw)
 ```
 
-### TaskManager Options
+### Error State Tracking
+
+Regardless of `catchErrors`, the task tracks errors:
 
 ```typescript
-const taskManager = new TaskManager({
-  maxConcurrentTasks: 10,    // Global concurrency limit
-  defaultTimeout: 30000,      // Default task timeout
-  logLevel: 'info'          // Logging verbosity
-});
+console.log(task.lastError); // Error object (or undefined)
+console.log(task.errorCount); // Number of failures across all runs
+console.log(task.getMetadata().status); // 'failed'
+
+task.clearError(); // Resets lastError to undefined (errorCount stays)
 ```
 
-## 📊 Monitoring & Observability
+On a subsequent successful run, `lastError` is automatically cleared.
 
-### Task Events
+## 📋 TaskManager — Centralized Orchestration
 
 ```typescript
-task.on('started', () => console.log('Task started'));
-task.on('completed', (result) => console.log('Task completed:', result));
-task.on('failed', (error) => console.error('Task failed:', error));
-task.on('stepChange', (step) => console.log('Step:', step.name));
+const manager = new TaskManager();
+
+// Add tasks
+manager.addTask(dataProcessor);
+manager.addTask(deployTask);
+
+// Schedule with cron expressions
+manager.addAndScheduleTask(backupTask, '0 2 * * *'); // Daily at 2 AM
+manager.addAndScheduleTask(healthCheck, '*/5 * * * *'); // Every 5 minutes
+
+// Query metadata
+const meta = manager.getTaskMetadata('Deploy');
+console.log(meta);
+// {
+//   name: 'Deploy',
+//   status: 'completed',
+//   steps: [...],
+//   currentProgress: 100,
+//   runCount: 3,
+//   labels: { env: 'production' },
+//   lastError: undefined,
+//   errorCount: 0,
+//   ...
+// }
+
+// All tasks at once
+const allMeta = manager.getAllTasksMetadata();
+
+// Scheduled task info
+const scheduled = manager.getScheduledTasks();
+const nextRuns = manager.getNextScheduledRuns(5);
+
+// Trigger by name
+await manager.triggerTaskByName('Deploy');
+
+// One-shot: add, execute, collect report, remove
+const report = await manager.addExecuteRemoveTask(temporaryTask);
+console.log(report);
+// {
+//   taskName: 'TempTask',
+//   startTime: 1706284800000,
+//   endTime: 1706284801523,
+//   duration: 1523,
+//   steps: [...],
+//   stepsCompleted: ['step1', 'step2'],
+//   progress: 100,
+//   result: any
+// }
+
+// Lifecycle
+await manager.start(); // Starts cron scheduling + distributed coordinator
+await manager.stop(); // Stops scheduling, cleans up event subscriptions
 ```
 
-### Execution Metrics
+### Remove Tasks
 
 ```typescript
-const metrics = task.getMetrics();
-console.log({
-  totalRuns: metrics.runCount,
-  averageDuration: metrics.avgDuration,
-  successRate: metrics.successRate,
-  lastError: metrics.lastError
+manager.removeTask(task); // Removes from map and unsubscribes event forwarding
+manager.descheduleTaskByName('Deploy'); // Remove cron schedule only
+```
+
+## 🎨 Web Component Dashboard
+
+Visualize your tasks in real-time with the included Lit-based web component:
+
+```html
+<script type="module">
+  import { TaskManager } from '@push.rocks/taskbuffer';
+  import '@push.rocks/taskbuffer/dist_ts_web/taskbuffer-dashboard.js';
+
+  const manager = new TaskManager();
+  // ... add and schedule tasks ...
+
+  const dashboard = document.querySelector('taskbuffer-dashboard');
+  dashboard.taskManager = manager;
+  dashboard.refreshInterval = 500; // Poll every 500ms
+</script>
+
+<taskbuffer-dashboard></taskbuffer-dashboard>
+```
+
+The dashboard provides:
+
+- 📊 Real-time progress bars with step indicators
+- 📈 Task execution history and metadata
+- ⏰ Scheduled task information with next-run times
+- 🌓 Light/dark theme support
+
+## 🌐 Distributed Coordination
+
+For multi-instance deployments, extend `AbstractDistributedCoordinator` to prevent duplicate task execution:
+
+```typescript
+import { TaskManager, distributedCoordination } from '@push.rocks/taskbuffer';
+
+class RedisCoordinator extends distributedCoordination.AbstractDistributedCoordinator {
+  async fireDistributedTaskRequest(request) {
+    // Implement leader election / distributed lock via Redis
+    return { shouldTrigger: true, considered: true, rank: 1, reason: 'elected', ...request };
+  }
+  async updateDistributedTaskRequest(request) {
+    /* update status */
+  }
+  async start() {
+    /* connect */
+  }
+  async stop() {
+    /* disconnect */
+  }
+}
+
+const manager = new TaskManager({
+  distributedCoordinator: new RedisCoordinator(),
 });
 ```
 
-## 🧪 Testing
+When a distributed coordinator is configured, scheduled tasks consult it before executing — only the elected instance runs the task.
+
+## 🧩 Advanced Patterns
+
+### Pre-Task & After-Task Hooks
+
+Run setup/teardown tasks automatically:
 
 ```typescript
-import { expect, tap } from '@git.zone/tstest';
-import { Task } from '@push.rocks/taskbuffer';
+const mainTask = new Task({
+  name: 'MainWork',
+  preTask: new Task({
+    name: 'Setup',
+    taskFunction: async () => {
+      console.log('Setting up...');
+    },
+  }),
+  afterTask: new Task({
+    name: 'Cleanup',
+    taskFunction: async () => {
+      console.log('Cleaning up...');
+    },
+  }),
+  taskFunction: async () => {
+    console.log('Doing work...');
+    return 'done';
+  },
+});
 
-tap.test('Task should execute with progress tracking', async () => {
-  const task = new Task({
-    name: 'TestTask',
-    steps: [
-      { name: 'step1', description: 'Step 1', percentage: 50 },
-      { name: 'step2', description: 'Step 2', percentage: 50 }
-    ] as const,
-    taskFunction: async function() {
-      this.notifyStep('step1');
-      await new Promise(r => setTimeout(r, 100));
-      this.notifyStep('step2');
-      return 'done';
-    }
-  });
-  
-  const result = await task.trigger();
-  expect(result).toEqual('done');
-  expect(task.getProgress()).toEqual(100);
+await mainTask.trigger();
+// Setting up... → Doing work... → Cleaning up...
+```
+
+### One-Time Setup Functions
+
+Run an expensive initialization exactly once, before the first execution:
+
+```typescript
+const task = new Task({
+  name: 'DBQuery',
+  taskSetup: async () => {
+    const pool = await createConnectionPool();
+    return pool; // This becomes `setupValue`
+  },
+  taskFunction: async (input, pool) => {
+    return await pool.query(input);
+  },
 });
+
+await task.trigger('SELECT * FROM users'); // Setup runs here
+await task.trigger('SELECT * FROM orders'); // Setup skipped, pool reused
 ```
 
-## 🌐 Real-World Examples
+### Blocking Tasks
 
-### API Rate Limiter
+Make one task wait for another to finish before executing:
 
 ```typescript
-const apiLimiter = new Task({
-  name: 'APIRateLimiter',
-  buffered: true,
-  bufferMax: 10,  // Max 10 requests per second
-  execDelay: 100, // 100ms between requests
-  taskFunction: async (endpoint, data) => {
-    return await fetch(endpoint, {
-      method: 'POST',
-      body: JSON.stringify(data)
-    });
-  }
+const initTask = new Task({
+  name: 'Init',
+  taskFunction: async () => {
+    await initializeSystem();
+  },
 });
+
+const workerTask = new Task({
+  name: 'Worker',
+  taskFunction: async () => {
+    await doWork();
+  },
+});
+
+workerTask.blockingTasks.push(initTask);
+
+// Triggering worker will automatically wait for init to complete
+initTask.trigger();
+workerTask.trigger(); // Waits until initTask.finished resolves
 ```
 
 ### Database Migration Pipeline
 
 ```typescript
-const migrationChain = new Taskchain({
+const migration = new Taskchain({
   name: 'DatabaseMigration',
-  tasks: [
-    backupDatabaseTask,
-    validateSchemaTask,
-    runMigrationsTask,
-    verifyIntegrityTask,
-    updateIndexesTask
-  ]
+  taskArray: [backupTask, validateSchemaTask, runMigrationsTask, verifyIntegrityTask],
 });
 
-// Execute with rollback on failure
 try {
-  await migrationChain.trigger();
+  await migration.trigger();
   console.log('Migration successful!');
 } catch (error) {
+  // error includes chain name, failing task name, index, and original cause
+  console.error(error.message);
   await rollbackTask.trigger();
-  throw error;
 }
 ```
 
-### Distributed Job Queue
+### Multi-Tenant SaaS Monitoring
+
+Combine labels + events for a real-time multi-tenant dashboard:
 
 ```typescript
-const jobQueue = new TaskManager();
+const manager = new TaskManager();
 
-// Worker tasks
-const imageProcessor = new Task({
-  name: 'ImageProcessor',
-  buffered: true,
-  bufferMax: 5,
-  steps: [
-    { name: 'download', description: 'Downloading', percentage: 20 },
-    { name: 'resize', description: 'Resizing', percentage: 40 },
-    { name: 'optimize', description: 'Optimizing', percentage: 30 },
-    { name: 'upload', description: 'Uploading', percentage: 10 }
-  ] as const,
-  taskFunction: async function(job) {
-    this.notifyStep('download');
-    const image = await downloadImage(job.url);
-    
-    this.notifyStep('resize');
-    const resized = await resizeImage(image, job.dimensions);
-    
-    this.notifyStep('optimize');
-    const optimized = await optimizeImage(resized);
-    
-    this.notifyStep('upload');
-    return await uploadToCDN(optimized);
-  }
-});
+// Create tenant-scoped tasks
+function createTenantTask(tenantId: string, taskName: string, fn: () => Promise<any>) {
+  const task = new Task({
+    name: `${tenantId}:${taskName}`,
+    labels: { tenantId },
+    taskFunction: fn,
+  });
+  manager.addTask(task);
+  return task;
+}
 
-jobQueue.addTask(imageProcessor);
+createTenantTask('acme', 'sync', async () => syncData('acme'));
+createTenantTask('globex', 'sync', async () => syncData('globex'));
 
-// Process incoming jobs
-messageQueue.on('job', async (job) => {
-  const result = await jobQueue.getTaskByName('ImageProcessor').trigger(job);
-  await messageQueue.ack(job.id, result);
+// Stream events to tenant-specific WebSocket channels
+manager.taskSubject.subscribe((event) => {
+  const tenantId = event.task.labels?.tenantId;
+  if (tenantId) {
+    wss.broadcast(tenantId, JSON.stringify(event));
+  }
 });
-```
 
-## 🚀 Performance Tips
-
-1. **Use Buffering Wisely** - Enable buffering for I/O-bound tasks
-2. **Set Appropriate Delays** - Use `execDelay` to prevent API rate limits
-3. **Leverage Task Pools** - Distribute load across multiple task instances
-4. **Monitor Progress** - Use step tracking for long-running operations
-5. **Clean Up** - Use `addExecuteRemoveTask` for one-time operations
+// Query tasks for a specific tenant
+const acmeTasks = manager.getTasksMetadataByLabel('tenantId', 'acme');
+```
 
-## 🔍 Debugging
+## 📚 API Reference
 
-Enable detailed logging:
+### Classes
+
+| Class | Description |
+| --- | --- |
+| `Task<T, TSteps>` | Core task unit with optional step tracking, labels, and event streaming |
+| `TaskManager` | Centralized orchestrator with scheduling, label queries, and aggregated events |
+| `Taskchain` | Sequential task executor with data flow between tasks |
+| `Taskparallel` | Concurrent task executor via `Promise.all()` |
+| `TaskOnce` | Single-execution guard |
+| `TaskDebounced` | Debounced task using rxjs |
+| `TaskRunner` | Sequential queue with configurable parallelism |
+| `TaskStep` | Step tracking unit (internal, exposed via metadata) |
+
+### Task Methods
+
+| Method | Returns | Description |
+| --- | --- | --- |
+| `trigger(input?)` | `Promise<any>` | Execute the task |
+| `notifyStep(name)` | `void` | Advance to named step (type-safe) |
+| `getProgress()` | `number` | Current progress 0–100 |
+| `getStepsMetadata()` | `ITaskStep[]` | Step details with status |
+| `getMetadata()` | `ITaskMetadata` | Full task metadata snapshot |
+| `setLabel(key, value)` | `void` | Set a label |
+| `getLabel(key)` | `string \| undefined` | Get a label value |
+| `removeLabel(key)` | `boolean` | Remove a label |
+| `hasLabel(key, value?)` | `boolean` | Check label existence / value |
+| `clearError()` | `void` | Reset `lastError` to undefined |
+
+### Task Properties
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `name` | `string` | Task identifier |
+| `running` | `boolean` | Whether the task is currently executing |
+| `idle` | `boolean` | Inverse of `running` |
+| `labels` | `Record<string, string>` | Attached labels |
+| `eventSubject` | `Subject<ITaskEvent>` | rxjs Subject emitting lifecycle events |
+| `lastError` | `Error \| undefined` | Last error encountered |
+| `errorCount` | `number` | Total error count across all runs |
+| `runCount` | `number` | Total execution count |
+| `lastRun` | `Date \| undefined` | Timestamp of last execution |
+| `blockingTasks` | `Task[]` | Tasks that must finish before this one starts |
+
+### TaskManager Methods
+
+| Method | Returns | Description |
+| --- | --- | --- |
+| `addTask(task)` | `void` | Register a task (wires event forwarding) |
+| `removeTask(task)` | `void` | Remove task and unsubscribe events |
+| `getTaskByName(name)` | `Task \| undefined` | Look up by name |
+| `triggerTaskByName(name)` | `Promise<any>` | Trigger by name |
+| `addAndScheduleTask(task, cron)` | `void` | Register + schedule |
+| `scheduleTaskByName(name, cron)` | `void` | Schedule existing task |
+| `descheduleTaskByName(name)` | `void` | Remove schedule |
+| `getTaskMetadata(name)` | `ITaskMetadata \| null` | Single task metadata |
+| `getAllTasksMetadata()` | `ITaskMetadata[]` | All tasks metadata |
+| `getScheduledTasks()` | `IScheduledTaskInfo[]` | Scheduled task info |
+| `getNextScheduledRuns(limit?)` | `Array<{...}>` | Upcoming scheduled runs |
+| `getTasksByLabel(key, value)` | `Task[]` | Filter tasks by label |
+| `getTasksMetadataByLabel(key, value)` | `ITaskMetadata[]` | Filter metadata by label |
+| `addExecuteRemoveTask(task, opts?)` | `Promise<ITaskExecutionReport>` | One-shot execution with report |
+| `start()` | `Promise<void>` | Start cron + coordinator |
+| `stop()` | `Promise<void>` | Stop cron + clean up subscriptions |
+
+### TaskManager Properties
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `taskSubject` | `Subject<ITaskEvent>` | Aggregated events from all added tasks |
+| `taskMap` | `ObjectMap<Task>` | Internal task registry |
+
+### Exported Types
 
 ```typescript
-import { logger } from '@push.rocks/smartlog';
-
-logger.enableConsole();
-logger.level = 'debug';
-
-// Tasks will now output detailed execution logs
+import type {
+  ITaskMetadata,
+  ITaskExecutionReport,
+  IScheduledTaskInfo,
+  ITaskEvent,
+  TTaskEventType,
+  ITaskStep,
+  ITaskFunction,
+  StepNames,
+} from '@push.rocks/taskbuffer';
 ```
 
-## 📚 API Reference
-
-### Core Classes
-
-- **`Task<T, TSteps>`** - Basic task unit with optional step tracking
-- **`TaskManager`** - Central orchestrator for task management
-- **`Taskchain`** - Sequential task executor
-- **`Taskparallel`** - Concurrent task executor
-- **`TaskOnce`** - Single-execution task
-- **`TaskDebounced`** - Debounced task that waits for a pause in triggers
-- **`TaskRunner`** - Sequential task runner with scheduling support
-- **`distributedCoordination`** - Namespace for distributed task coordination
-
-### Key Methods
-
-#### Task Methods
-- `trigger(input?: T): Promise<any>` - Execute the task
-- `notifyStep(stepName: StepNames<TSteps>): void` - Update current step
-- `getProgress(): number` - Get progress percentage (0-100)
-- `getStepsMetadata(): ITaskStep[]` - Get detailed step information
-- `getMetadata(): ITaskMetadata` - Get complete task metadata
-
-#### TaskManager Methods
-- `addTask(task: Task): void` - Register a task
-- `getTaskByName(name: string): Task | undefined` - Retrieve task by name
-- `addAndScheduleTask(task: Task, cronExpression: string): void` - Schedule task
-- `descheduleTaskByName(name: string): void` - Remove scheduling
-- `getTaskMetadata(name: string): ITaskMetadata | null` - Get task metadata
-- `getAllTasksMetadata(): ITaskMetadata[]` - Get all tasks metadata
-- `getScheduledTasks(): IScheduledTaskInfo[]` - List scheduled tasks
-- `addExecuteRemoveTask(task, options?): Promise<ITaskExecutionReport>` - Execute once
-
 ## License and Legal Information
 
-This repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the [license](license) file within this repository. 
+This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [LICENSE](./LICENSE) file.
 
 **Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.
 
 ### Trademarks
 
-This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH and are not included within the scope of the MIT license granted herein. Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines, and any usage must be approved in writing by Task Venture Capital GmbH.
+This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.
+
+Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.
 
 ### Company Information
 
-Task Venture Capital GmbH  
-Registered at District court Bremen HRB 35230 HB, Germany
+Task Venture Capital GmbH
+Registered at District Court Bremen HRB 35230 HB, Germany
 
-For any legal inquiries or if you require further information, please contact us via email at hello@task.vc.
+For any legal inquiries or further information, please contact us via email at hello@task.vc.
 
-By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.
+By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.