@push.rocks/taskbuffer 3.2.0 → 3.4.0

package/readme.md

@@ -1,1112 +1,586 @@
 # @push.rocks/taskbuffer 🚀
 
-A **powerful**, **flexible**, and **TypeScript-first** task management library for orchestrating asynchronous operations with style. From simple task execution to complex distributed workflows with real-time progress tracking, taskbuffer has got you covered.
+> **Modern TypeScript task orchestration with smart buffering, scheduling, and real-time progress tracking**
 
-## Install 📦
+[![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)
 
-```bash
-npm install @push.rocks/taskbuffer --save
-```
+## 🌟 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
 
-Or with **pnpm** (recommended):
+## 📦 Installation
 
 ```bash
+npm install @push.rocks/taskbuffer
+# or
 pnpm add @push.rocks/taskbuffer
+# or
+yarn add @push.rocks/taskbuffer
 ```
 
-## Why taskbuffer? 🤔
-
-In the modern JavaScript ecosystem, managing asynchronous tasks efficiently is crucial. Whether you're building a data pipeline, managing API rate limits, or orchestrating complex workflows, **@push.rocks/taskbuffer** provides the tools you need:
-
-- **🎯 TypeScript-first**: Built with TypeScript for TypeScript - enjoy complete type safety and excellent IDE support
-- **⚡ Flexible execution**: From simple tasks to complex parallel workflows with dependencies
-- **🔄 Smart buffering**: Control concurrent executions with intelligent buffer management
-- **⏰ Built-in scheduling**: Cron-based task scheduling without additional dependencies
-- **🎭 Multiple paradigms**: Support for debounced, throttled, and one-time execution patterns
-- **📊 Progress tracking**: Real-time step-by-step progress monitoring for UI integration
-- **🔌 Extensible**: Clean architecture that's easy to extend and customize
-- **🏃 Zero dependencies on external schedulers**: Everything you need is included
-
-## Core Concepts 🎓
-
-### Task
-The fundamental unit of work. A task wraps an asynchronous function and provides powerful execution control, now with step-by-step progress tracking.
-
-### Taskchain
-Sequential task execution - tasks run one after another, with results passed along the chain.
-
-### Taskparallel
-Parallel task execution - multiple tasks run simultaneously for maximum performance.
-
-### TaskManager
-Centralized task scheduling and management using cron expressions, with rich metadata collection.
-
-### TaskDebounced
-Debounced task execution - prevents rapid repeated executions, only running after a quiet period.
+## 🚀 Quick Start
 
-### TaskOnce
-Singleton task execution - ensures a task runs exactly once, perfect for initialization routines.
-
-### TaskStep 🆕
-Granular progress tracking - define named steps with percentage weights for real-time progress monitoring.
-
-## Quick Start 🏁
-
-### Basic Task Execution
+### Basic Task Creation
 
 ```typescript
-import { Task } from '@push.rocks/taskbuffer';
+import { Task, TaskManager } from '@push.rocks/taskbuffer';
 
 // Create a simple task
-const myTask = new Task({
-  name: 'DataProcessor',
-  taskFunction: async () => {
-    const data = await fetchData();
-    return processData(data);
-  },
+const dataProcessor = new Task({
+  name: 'ProcessData',
+  taskFunction: async (data) => {
+    console.log(`Processing: ${data}`);
+    // Your async logic here
+    return `Processed: ${data}`;
+  }
 });
 
 // Execute the task
-const result = await myTask.trigger();
+const result = await dataProcessor.trigger('my-data');
+console.log(result); // "Processed: my-data"
 ```
 
-### Task with Progress Steps 🆕
-
-Track granular progress for complex operations - perfect for UI progress bars:
+### Tasks with Progress Tracking 📊
 
 ```typescript
-const dataProcessingTask = new Task({
-  name: 'DataProcessor',
+const deploymentTask = new Task({
+  name: 'DeployApplication',
   steps: [
-    { name: 'validate', description: 'Validating input data', percentage: 15 },
-    { name: 'fetch', description: 'Fetching external resources', percentage: 25 },
-    { name: 'transform', description: 'Transforming data', percentage: 35 },
-    { name: 'save', description: 'Saving to database', percentage: 25 }
-  ] as const, // Use 'as const' for full type safety
-  taskFunction: async (inputData) => {
+    { name: 'build', description: 'Building application', 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!
-    dataProcessingTask.notifyStep('validate');
-    const validated = await validateData(inputData);
+    this.notifyStep('build');
+    await buildApplication();
     
-    dataProcessingTask.notifyStep('fetch');
-    const external = await fetchExternalData();
+    this.notifyStep('test');
+    await runTests();
     
-    dataProcessingTask.notifyStep('transform');
-    const transformed = await transformData(validated, external);
+    this.notifyStep('deploy');
+    await deployToServer();
     
-    dataProcessingTask.notifyStep('save');
-    const result = await saveToDatabase(transformed);
+    this.notifyStep('verify');
+    await verifyDeployment();
     
-    return result;
+    return 'Deployment successful!';
   }
 });
 
-// Monitor progress in real-time
-const result = await dataProcessingTask.trigger();
-console.log(`Final progress: ${dataProcessingTask.getProgress()}%`); // 100%
+// Monitor progress
+console.log(deploymentTask.getProgress()); // 0-100
+console.log(deploymentTask.getStepsMetadata()); // Detailed step info
 ```
 
-## TypeScript Generics Support 🔬
+## 🎯 Core Concepts
 
-TaskBuffer leverages TypeScript's powerful generics system for complete type safety across your task chains and workflows.
+### Task Buffering - Intelligent Request Management
 
-### Generic Task Functions
-
-Tasks support generic type parameters for both input and output types:
+TaskBuffer's buffering system prevents overwhelming your system with rapid-fire requests:
 
 ```typescript
-import { Task, ITaskFunction } from '@push.rocks/taskbuffer';
-
-// Define typed interfaces
-interface UserData {
-  id: string;
-  name: string;
-  email: string;
-}
-
-interface ProcessedUser {
-  userId: string;
-  displayName: string;
-  normalized: boolean;
-}
-
-// Create strongly typed tasks
-const processUserTask = new Task<ProcessedUser>({
-  name: 'ProcessUser',
-  taskFunction: async (user: UserData): Promise<ProcessedUser> => {
-    return {
-      userId: user.id,
-      displayName: user.name.toUpperCase(),
-      normalized: true
-    };
-  }
-});
-
-// Type safety enforced at compile time
-const result: ProcessedUser = await processUserTask.trigger({
-  id: '123',
-  name: 'John Doe',
-  email: 'john@example.com'
+const apiTask = new Task({
+  name: 'APIRequest',
+  taskFunction: async (endpoint) => {
+    return await fetch(endpoint).then(r => r.json());
+  },
+  buffered: true,
+  bufferMax: 5,  // Maximum 5 concurrent executions
+  execDelay: 100 // Minimum 100ms between executions
 });
-```
-
-### Generic Setup Values
 
-Tasks can accept setup values through generics, perfect for configuration:
-
-```typescript
-interface TaskConfig {
-  apiEndpoint: string;
-  retryCount: number;
-  timeout: number;
+// Rapid fire 100 calls - only 5 will execute concurrently
+for (let i = 0; i < 100; i++) {
+  apiTask.trigger(`/api/data/${i}`);
 }
-
-const configuredTask = new Task<TaskConfig>({
-  name: 'ConfiguredTask',
-  taskSetup: async (): Promise<TaskConfig> => ({
-    apiEndpoint: 'https://api.example.com',
-    retryCount: 3,
-    timeout: 5000
-  }),
-  taskFunction: async (data: any, setupValue: TaskConfig) => {
-    // setupValue is fully typed!
-    for (let i = 0; i < setupValue.retryCount; i++) {
-      try {
-        return await fetchWithTimeout(
-          setupValue.apiEndpoint,
-          setupValue.timeout
-        );
-      } catch (error) {
-        if (i === setupValue.retryCount - 1) throw error;
-      }
-    }
-  }
-});
-```
-
-### Type-Safe Task Chains
-
-Chain tasks with preserved type flow:
-
-```typescript
-// Each task knows its input and output types
-const fetchTask = new Task<void>({
-  name: 'FetchUsers',
-  taskFunction: async (): Promise<UserData[]> => {
-    return await api.getUsers();
-  }
-});
-
-const filterTask = new Task<void>({
-  name: 'FilterActive',
-  taskFunction: async (users: UserData[]): Promise<UserData[]> => {
-    return users.filter(user => user.isActive);
-  }
-});
-
-const mapTask = new Task<void>({
-  name: 'MapToProcessed',
-  taskFunction: async (users: UserData[]): Promise<ProcessedUser[]> => {
-    return users.map(transformUser);
-  }
-});
-
-// Type safety flows through the chain
-const chain = new Taskchain({
-  name: 'UserPipeline',
-  taskArray: [fetchTask, filterTask, mapTask]
-});
-
-const finalResult: ProcessedUser[] = await chain.trigger();
 ```
 
-## Progress Tracking & Metadata 📊 🆕
-
-TaskBuffer now provides comprehensive progress tracking and metadata collection, perfect for building dashboards and monitoring systems.
+**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
 
-### Step-by-Step Progress
+### Task Chains - Sequential Workflows
 
-Define weighted steps for accurate progress calculation:
+Build complex workflows with automatic data flow:
 
 ```typescript
-const migrationTask = new Task({
-  name: 'DatabaseMigration',
-  steps: [
-    { name: 'backup', description: 'Backing up database', percentage: 20 },
-    { name: 'schema', description: 'Updating schema', percentage: 30 },
-    { name: 'data', description: 'Migrating data', percentage: 40 },
-    { name: 'validate', description: 'Validating integrity', percentage: 10 }
-  ] as const,
+import { Task, Taskchain } from '@push.rocks/taskbuffer';
+
+const fetchTask = new Task({
+  name: 'FetchData',
   taskFunction: async () => {
-    migrationTask.notifyStep('backup');
-    await backupDatabase();
-    console.log(`Progress: ${migrationTask.getProgress()}%`); // ~20%
-    
-    migrationTask.notifyStep('schema');
-    await updateSchema();
-    console.log(`Progress: ${migrationTask.getProgress()}%`); // ~50%
-    
-    migrationTask.notifyStep('data');
-    await migrateData();
-    console.log(`Progress: ${migrationTask.getProgress()}%`); // ~90%
-    
-    migrationTask.notifyStep('validate');
-    await validateIntegrity();
-    console.log(`Progress: ${migrationTask.getProgress()}%`); // 100%
+    const response = await fetch('/api/data');
+    return response.json();
   }
 });
 
-// Get detailed step information
-const steps = migrationTask.getStepsMetadata();
-steps.forEach(step => {
-  console.log(`${step.name}: ${step.status} (${step.percentage}%)`);
-  if (step.duration) {
-    console.log(`  Duration: ${step.duration}ms`);
+const transformTask = new Task({
+  name: 'TransformData',
+  taskFunction: async (data) => {
+    return data.map(item => ({
+      ...item,
+      transformed: true,
+      timestamp: Date.now()
+    }));
   }
 });
-```
-
-### Task Metadata Collection
 
-Get comprehensive metadata about task execution:
-
-```typescript
-const task = new Task({
-  name: 'DataProcessor',
-  buffered: true,
-  bufferMax: 5,
-  steps: [
-    { name: 'process', description: 'Processing', percentage: 100 }
-  ] as const,
-  taskFunction: async () => {
-    task.notifyStep('process');
-    await processData();
+const saveTask = new Task({
+  name: 'SaveData',
+  taskFunction: async (transformedData) => {
+    await database.save(transformedData);
+    return transformedData.length;
   }
 });
 
-// Get complete task metadata
-const metadata = task.getMetadata();
-console.log({
-  name: metadata.name,
-  status: metadata.status, // 'idle' | 'running' | 'completed' | 'failed'
-  progress: metadata.currentProgress, // 0-100
-  currentStep: metadata.currentStep,
-  runCount: metadata.runCount,
-  lastRun: metadata.lastRun,
-  buffered: metadata.buffered,
-  bufferMax: metadata.bufferMax
+// Create and execute chain
+const dataChain = new Taskchain({
+  name: 'DataPipeline',
+  tasks: [fetchTask, transformTask, saveTask]
 });
+
+const savedCount = await dataChain.trigger();
+console.log(`Saved ${savedCount} items`);
 ```
 
-### TaskManager Enhanced Metadata
+### Parallel Execution - Concurrent Processing
 
-The TaskManager now provides rich metadata for monitoring and dashboards:
+Execute multiple tasks simultaneously:
 
 ```typescript
-const manager = new TaskManager();
-
-// Add tasks with step tracking
-manager.addAndScheduleTask(backupTask, '0 2 * * *'); // 2 AM daily
-manager.addAndScheduleTask(cleanupTask, '0 */6 * * *'); // Every 6 hours
-
-// Get metadata for all tasks
-const allTasksMetadata = manager.getAllTasksMetadata();
-allTasksMetadata.forEach(task => {
-  console.log(`Task: ${task.name}`);
-  console.log(`  Status: ${task.status}`);
-  console.log(`  Progress: ${task.currentProgress}%`);
-  console.log(`  Run count: ${task.runCount}`);
-  console.log(`  Schedule: ${task.cronSchedule}`);
-});
+import { TaskParallel } from '@push.rocks/taskbuffer';
 
-// Get scheduled tasks with next run times
-const scheduledTasks = manager.getScheduledTasks();
-scheduledTasks.forEach(task => {
-  console.log(`${task.name}: Next run at ${task.nextRun}`);
-  if (task.steps) {
-    console.log(`  Steps: ${task.steps.length}`);
-  }
+const parallel = new TaskParallel({
+  name: 'ParallelProcessor',
+  tasks: [
+    emailTask,
+    smsTask,
+    pushNotificationTask,
+    webhookTask
+  ]
 });
 
-// Get upcoming executions
-const nextRuns = manager.getNextScheduledRuns(10);
-console.log('Next 10 scheduled executions:', nextRuns);
+// All tasks execute concurrently
+const results = await parallel.trigger(notificationData);
+// results = [emailResult, smsResult, pushResult, webhookResult]
 ```
 
-### Execute and Track Tasks
+### TaskManager - Centralized Orchestration
 
-Execute tasks with full lifecycle tracking and automatic cleanup:
+Manage all your tasks from a single point:
 
 ```typescript
-const manager = new TaskManager();
-
-const analyticsTask = new Task({
-  name: 'Analytics',
-  steps: [
-    { name: 'collect', description: 'Collecting metrics', percentage: 30 },
-    { name: 'analyze', description: 'Analyzing data', percentage: 50 },
-    { name: 'report', description: 'Generating report', percentage: 20 }
-  ] as const,
-  taskFunction: async () => {
-    analyticsTask.notifyStep('collect');
-    const metrics = await collectMetrics();
-    
-    analyticsTask.notifyStep('analyze');
-    const analysis = await analyzeData(metrics);
-    
-    analyticsTask.notifyStep('report');
-    return await generateReport(analysis);
-  }
+const taskManager = new TaskManager();
+
+// Add tasks
+taskManager.addTask(dataProcessor);
+taskManager.addTask(deploymentTask);
+
+// Schedule tasks with cron
+taskManager.addAndScheduleTask(backupTask, '0 2 * * *'); // Daily at 2 AM
+taskManager.addAndScheduleTask(healthCheck, '*/5 * * * *'); // Every 5 minutes
+
+// 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
+// }
+
+// Get all scheduled tasks
+const scheduled = taskManager.getScheduledTasks();
+scheduled.forEach(task => {
+  console.log(`${task.name}: Next run at ${task.nextRun}`);
 });
 
-// Execute with automatic cleanup and metadata collection
-const report = await manager.addExecuteRemoveTask(analyticsTask, {
+// Execute and remove pattern
+const report = await taskManager.addExecuteRemoveTask(temporaryTask, {
   trackProgress: true
 });
-
-console.log('Execution Report:', {
-  taskName: report.taskName,
-  duration: report.duration,
-  stepsCompleted: report.stepsCompleted,
-  finalProgress: report.progress,
-  result: report.result
-});
+console.log(report);
+// {
+//   taskName: 'TempTask',
+//   startTime: Date,
+//   endTime: Date,
+//   duration: 1523,
+//   steps: [...],
+//   stepsCompleted: ['step1', 'step2'],
+//   progress: 100,
+//   result: any,
+//   error?: Error
+// }
 ```
 
-### Frontend Integration Example
+## 🎨 Web Component Dashboard
 
-Perfect for building real-time progress UIs:
+Visualize your tasks in real-time with the included web component:
 
-```typescript
-// WebSocket server for real-time updates
-io.on('connection', (socket) => {
-  socket.on('startTask', async (taskId) => {
-    const task = new Task({
-      name: taskId,
-      steps: [
-        { name: 'start', description: 'Starting...', percentage: 10 },
-        { name: 'process', description: 'Processing...', percentage: 70 },
-        { name: 'finish', description: 'Finishing...', percentage: 20 }
-      ] as const,
-      taskFunction: async () => {
-        task.notifyStep('start');
-        socket.emit('progress', { 
-          step: 'start', 
-          progress: task.getProgress(),
-          metadata: task.getStepsMetadata()
-        });
-        
-        task.notifyStep('process');
-        socket.emit('progress', { 
-          step: 'process', 
-          progress: task.getProgress(),
-          metadata: task.getStepsMetadata()
-        });
-        
-        task.notifyStep('finish');
-        socket.emit('progress', { 
-          step: 'finish', 
-          progress: task.getProgress(),
-          metadata: task.getStepsMetadata()
-        });
-      }
-    });
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <script type="module">
+    import { TaskManager } from '@push.rocks/taskbuffer';
+    import '@push.rocks/taskbuffer/dist_ts_web/taskbuffer-dashboard.js';
     
-    await task.trigger();
-    socket.emit('complete', task.getMetadata());
-  });
-});
-```
-
-## Buffer Behavior Deep Dive 🌊
-
-The buffer system in TaskBuffer provides intelligent control over concurrent executions, preventing system overload while maximizing throughput.
-
-### How Buffering Works
-
-When a task is buffered, TaskBuffer manages a queue of executions:
-
-```typescript
-const bufferedTask = new Task({
-  name: 'BufferedOperation',
-  taskFunction: async (data) => {
-    console.log(`Processing: ${data}`);
-    await simulateWork();
-    return `Processed: ${data}`;
-  },
-  buffered: true,
-  bufferMax: 3  // Maximum 3 concurrent executions
-});
-
-// Trigger 10 executions rapidly
-for (let i = 0; i < 10; i++) {
-  bufferedTask.trigger(`Item ${i}`);
-}
-
-// What happens:
-// 1. First 3 tasks start immediately
-// 2. Items 4-10 are queued
-// 3. As each task completes, next queued item starts
-// 4. Never more than 3 tasks running simultaneously
-```
-
-### Buffer Truncation Behavior
-
-When buffer limit is reached, new calls are intelligently managed:
-
-```typescript
-const truncatingTask = new Task({
-  name: 'TruncatingBuffer',
-  taskFunction: async (data) => {
-    await processData(data);
-  },
-  buffered: true,
-  bufferMax: 5  // Maximum 5 in buffer
-});
-
-// Rapid fire 100 calls
-for (let i = 0; i < 100; i++) {
-  truncatingTask.trigger(`Data ${i}`);
-}
-
-// Buffer behavior:
-// - First 5 calls: Added to buffer and start processing
-// - Calls 6-100: Each overwrites the 5th buffer slot
-// - Result: Only processes items 0,1,2,3, and 99 (last one)
-// - This prevents memory overflow in high-frequency scenarios
+    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>
 ```
 
-### Advanced Buffer Strategies
-
-#### 1. **Sliding Window Buffer**
-Perfect for real-time data processing where only recent items matter:
+The dashboard provides:
+- 📊 Real-time progress bars with step indicators
+- 📈 Task execution history
+- ⏰ Scheduled task information
+- 🎯 Interactive task controls
+- 🌓 Light/dark theme support
 
-```typescript
-const slidingWindowTask = new Task({
-  name: 'SlidingWindow',
-  taskFunction: async (data) => {
-    return await analyzeRecentData(data);
-  },
-  buffered: true,
-  bufferMax: 10,  // Keep last 10 items
-  execDelay: 100  // Process every 100ms
-});
+## 🧩 Advanced Patterns
 
-// In a real-time stream scenario
-dataStream.on('data', (chunk) => {
-  slidingWindowTask.trigger(chunk);
-  // Older items automatically dropped when buffer full
-});
-```
+### Dynamic Task Routing
 
-#### 2. **Throttled Buffer**
-Combine buffering with execution delays for rate limiting:
+Route tasks based on conditions:
 
 ```typescript
-const apiRateLimiter = new Task({
-  name: 'RateLimitedAPI',
+const routerTask = new Task({
+  name: 'Router',
   taskFunction: async (request) => {
-    return await api.call(request);
-  },
-  buffered: true,
-  bufferMax: 10,     // Max 10 queued requests
-  execDelay: 1000    // 1 second between executions
+    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);
+    }
+  }
 });
-
-// Requests are queued and executed at 1/second
-// Prevents API rate limit violations
 ```
 
-#### 3. **Priority Buffer** (Custom Implementation)
-Implement priority queuing with buffer management:
+### Task Pools
+
+Create reusable task pools for load distribution:
 
 ```typescript
-class PriorityBufferedTask extends Task {
-  private priorityQueue: Array<{data: any, priority: number}> = [];
+class TaskPool {
+  private tasks: Task[] = [];
+  private currentIndex = 0;
   
-  constructor(options) {
-    super({
-      ...options,
-      taskFunction: async (item) => {
-        // Process based on priority
-        return await this.processByPriority(item);
-      }
-    });
+  constructor(poolSize: number, taskConfig: any) {
+    for (let i = 0; i < poolSize; i++) {
+      this.tasks.push(new Task({
+        ...taskConfig,
+        name: `${taskConfig.name}_${i}`
+      }));
+    }
   }
   
-  triggerWithPriority(data: any, priority: number) {
-    if (this.priorityQueue.length >= this.bufferMax) {
-      // Remove lowest priority item if buffer full
-      this.priorityQueue.sort((a, b) => b.priority - a.priority);
-      this.priorityQueue.pop();
-    }
-    this.priorityQueue.push({data, priority});
-    this.priorityQueue.sort((a, b) => b.priority - a.priority);
-    return this.trigger(this.priorityQueue.shift());
+  async execute(data: any) {
+    const task = this.tasks[this.currentIndex];
+    this.currentIndex = (this.currentIndex + 1) % this.tasks.length;
+    return await task.trigger(data);
   }
 }
-```
-
-### Buffer Monitoring
-
-Track buffer utilization and performance:
-
-```typescript
-const monitoredTask = new Task({
-  name: 'MonitoredBuffer',
-  taskFunction: async (data) => {
-    const startTime = Date.now();
-    const result = await processData(data);
-    console.log(`Processing time: ${Date.now() - startTime}ms`);
-    console.log(`Buffer utilization: ${monitoredTask.bufferRunner.bufferCounter}/${monitoredTask.bufferMax}`);
-    return result;
-  },
-  buffered: true,
-  bufferMax: 20
-});
-
-// Monitor buffer saturation
-setInterval(() => {
-  const utilization = (monitoredTask.bufferRunner.bufferCounter / monitoredTask.bufferMax) * 100;
-  if (utilization > 80) {
-    console.warn(`Buffer near capacity: ${utilization.toFixed(1)}%`);
-  }
-}, 1000);
-```
-
-### Buffer Best Practices
-
-1. **Choose appropriate buffer sizes**: 
-   - I/O operations: 5-10 concurrent
-   - CPU-intensive: Number of cores
-   - API calls: Based on rate limits
-
-2. **Handle buffer overflow gracefully**:
-   ```typescript
-   const task = new Task({
-     taskFunction: async (data) => {
-       try {
-         return await process(data);
-       } catch (error) {
-         if (error.code === 'BUFFER_OVERFLOW') {
-           // Implement backoff strategy
-           await delay(1000);
-           return task.trigger(data);
-         }
-         throw error;
-       }
-     },
-     buffered: true,
-     bufferMax: 10
-   });
-   ```
-
-3. **Monitor and adjust dynamically**:
-   ```typescript
-   // Adjust buffer size based on system load
-   const adaptiveTask = new Task({
-     name: 'AdaptiveBuffer',
-     taskFunction: async (data) => {
-       const cpuLoad = await getSystemLoad();
-       if (cpuLoad > 0.8) {
-         adaptiveTask.bufferMax = Math.max(2, adaptiveTask.bufferMax - 1);
-       } else if (cpuLoad < 0.5) {
-         adaptiveTask.bufferMax = Math.min(20, adaptiveTask.bufferMax + 1);
-       }
-       return await process(data);
-     },
-     buffered: true,
-     bufferMax: 10
-   });
-   ```
-
-## Common Patterns 🎨
-
-### Task Chains - Sequential Workflows
-
-Build complex workflows where each step depends on the previous:
-
-```typescript
-import { Task, Taskchain } from '@push.rocks/taskbuffer';
 
-const fetchTask = new Task({
-  name: 'FetchData',
-  taskFunction: async () => {
-    const response = await fetch('/api/data');
-    return response.json();
-  },
-});
-
-const transformTask = new Task({
-  name: 'TransformData',
-  taskFunction: async (data) => {
-    return data.map((item) => ({
-      ...item,
-      processed: true,
-      timestamp: Date.now(),
-    }));
-  },
-});
-
-const saveTask = new Task({
-  name: 'SaveData',
-  taskFunction: async (transformedData) => {
-    await database.bulkInsert(transformedData);
-    return { saved: transformedData.length };
-  },
-});
-
-const workflow = new Taskchain({
-  name: 'DataPipeline',
-  taskArray: [fetchTask, transformTask, saveTask],
+const processorPool = new TaskPool(5, {
+  name: 'DataProcessor',
+  taskFunction: async (data) => processData(data)
 });
-
-// Execute the entire chain
-const result = await workflow.trigger();
-console.log(`Processed ${result.saved} items`);
 ```
 
-### Parallel Execution - Maximum Performance
+### Error Recovery & Retry
 
-Execute multiple independent tasks simultaneously:
+Implement robust error handling:
 
 ```typescript
-import { Task, Taskparallel } from '@push.rocks/taskbuffer';
-
-const tasks = ['user', 'posts', 'comments'].map(
-  (resource) =>
-    new Task({
-      name: `Fetch${resource}`,
-      taskFunction: async () => {
-        const data = await fetch(`/api/${resource}`);
-        return data.json();
-      },
-    }),
-);
-
-const parallelFetch = new Taskparallel({
-  taskArray: tasks,
+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;
+    }
+  }
 });
-
-// All tasks execute simultaneously
-const [users, posts, comments] = await parallelFetch.trigger();
 ```
 
-### Scheduled Tasks with TaskManager
+### Task Composition
 
-Run tasks on a schedule using cron expressions:
+Compose complex behaviors from simple tasks:
 
 ```typescript
-import { Task, TaskManager } from '@push.rocks/taskbuffer';
-
-const backupTask = new Task({
-  name: 'DatabaseBackup',
+const compositeTask = new Task({
+  name: 'CompositeOperation',
   steps: [
-    { name: 'dump', description: 'Creating dump', percentage: 70 },
-    { name: 'upload', description: 'Uploading to S3', percentage: 30 }
+    { 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 () => {
-    backupTask.notifyStep('dump');
-    await performBackup();
+  taskFunction: async function(data) {
+    this.notifyStep('validate');
+    const validated = await validationTask.trigger(data);
     
-    backupTask.notifyStep('upload');
-    await uploadToS3();
+    this.notifyStep('process');
+    const processed = await processingTask.trigger(validated);
     
-    console.log(`Backup completed at ${new Date().toISOString()}`);
-  },
+    this.notifyStep('notify');
+    await notificationTask.trigger(processed);
+    
+    return processed;
+  }
 });
-
-const manager = new TaskManager();
-
-// Add and schedule tasks
-manager.addAndScheduleTask(backupTask, '0 0 * * *'); // Daily at midnight
-
-// Start the scheduler
-manager.start();
-
-// Monitor scheduled tasks
-const scheduled = manager.getScheduledTasks();
-console.log('Scheduled tasks:', scheduled);
-
-// Later... stop if needed
-manager.stop();
 ```
 
-### Debounced Tasks - Smart Throttling
+## 🔧 Configuration
 
-Prevent task spam with intelligent debouncing:
+### Task Options
 
 ```typescript
-import { TaskDebounced } from '@push.rocks/taskbuffer';
-
-const saveTask = new TaskDebounced({
-  name: 'AutoSave',
-  taskFunction: async (content: string) => {
-    await saveToDatabase(content);
-    console.log('Content saved');
-  },
-  debounceTimeInMillis: 2000, // Wait 2 seconds of inactivity
-});
-
-// Rapid calls will be debounced
-input.addEventListener('input', (e) => {
-  saveTask.trigger(e.target.value);
-});
+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
+}
 ```
 
-### One-Time Tasks - Initialize Once
-
-Ensure initialization code runs exactly once:
+### TaskManager Options
 
 ```typescript
-import { TaskOnce } from '@push.rocks/taskbuffer';
-
-const initTask = new TaskOnce({
-  name: 'SystemInitialization',
-  taskFunction: async () => {
-    await database.connect();
-    await cache.initialize();
-    await loadConfiguration();
-    console.log('System initialized');
-  },
+const taskManager = new TaskManager({
+  maxConcurrentTasks: 10,    // Global concurrency limit
+  defaultTimeout: 30000,      // Default task timeout
+  logLevel: 'info'          // Logging verbosity
 });
-
-// Safe to call multiple times - only runs once
-await initTask.trigger();
-await initTask.trigger(); // This won't run again
 ```
 
-## Advanced Features 🔥
-
-### Task Dependencies with Pre/Post Hooks
+## 📊 Monitoring & Observability
 
-Create sophisticated task relationships:
+### Task Events
 
 ```typescript
-const validationTask = new Task({
-  name: 'ValidateInput',
-  taskFunction: async (data) => {
-    if (!isValid(data)) {
-      throw new Error('Validation failed');
-    }
-    return data;
-  },
-});
-
-const mainTask = new Task({
-  name: 'ProcessData',
-  taskFunction: async (data) => {
-    return await complexProcessing(data);
-  },
-  preTask: validationTask, // Runs before main task
-  afterTask: cleanupTask, // Runs after main task
-});
+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));
 ```
 
-### Task Runners - Distributed Execution
-
-The TaskRunner system enables distributed task execution across multiple workers:
+### Execution Metrics
 
 ```typescript
-import { TaskRunner } from '@push.rocks/taskbuffer';
-
-const runner = new TaskRunner({
-  name: 'WorkerNode1',
-  maxConcurrentTasks: 5,
+const metrics = task.getMetrics();
+console.log({
+  totalRuns: metrics.runCount,
+  averageDuration: metrics.avgDuration,
+  successRate: metrics.successRate,
+  lastError: metrics.lastError
 });
-
-// Register tasks this runner can handle
-runner.registerTask(dataProcessingTask);
-runner.registerTask(imageResizeTask);
-
-// Start processing
-runner.start();
-```
-
-### Dynamic Task Creation
-
-Create tasks on-the-fly based on runtime conditions:
-
-```typescript
-const dynamicWorkflow = async (config: Config) => {
-  const tasks = config.steps.map(
-    (step) =>
-      new Task({
-        name: step.name,
-        steps: step.substeps?.map(s => ({
-          name: s.id,
-          description: s.label,
-          percentage: s.weight
-        })) as const,
-        taskFunction: async (input) => {
-          for (const substep of step.substeps || []) {
-            task.notifyStep(substep.id);
-            await processStep(substep, input);
-          }
-          return input;
-        },
-      }),
-  );
-
-  const chain = new Taskchain({
-    name: 'DynamicWorkflow',
-    taskArray: tasks,
-  });
-
-  return await chain.trigger();
-};
 ```
 
-## API Reference 📚
-
-### Task Options
-
-| Option         | Type       | Description                            |
-| -------------- | ---------- | -------------------------------------- |
-| `name`         | `string`   | Unique identifier for the task         |
-| `taskFunction` | `Function` | Async function to execute              |
-| `steps`        | `Array`    | Step definitions with name, description, percentage |
-| `buffered`     | `boolean`  | Enable buffer management               |
-| `bufferMax`    | `number`   | Maximum concurrent executions          |
-| `execDelay`    | `number`   | Delay between executions (ms)          |
-| `timeout`      | `number`   | Task timeout (ms)                      |
-| `preTask`      | `Task`     | Task to run before                     |
-| `afterTask`    | `Task`     | Task to run after                      |
-
-### Task Methods
-
-| Method                    | Description                                    |
-| ------------------------- | ---------------------------------------------- |
-| `trigger(x?)`             | Execute the task                              |
-| `notifyStep(stepName)`    | Mark a step as active (typed step names!)     |
-| `getProgress()`           | Get current progress percentage (0-100)       |
-| `getStepsMetadata()`      | Get all steps with their current status       |
-| `getMetadata()`           | Get complete task metadata                    |
-| `resetSteps()`            | Reset all steps to pending state              |
-
-### TaskManager Methods
-
-| Method                              | Description                            |
-| ----------------------------------- | -------------------------------------- |
-| `addTask(task)`                     | Add a task to the manager              |
-| `addAndScheduleTask(task, cron)`    | Add and schedule a task                |
-| `getTaskByName(name)`               | Get a specific task by name            |
-| `getTaskMetadata(name)`             | Get metadata for a specific task       |
-| `getAllTasksMetadata()`             | Get metadata for all tasks             |
-| `getScheduledTasks()`               | Get all scheduled tasks with info      |
-| `getNextScheduledRuns(limit)`       | Get upcoming scheduled executions      |
-| `addExecuteRemoveTask(task, opts)`  | Execute task with lifecycle tracking   |
-| `triggerTaskByName(name)`           | Trigger a task by its name             |
-| `scheduleTaskByName(name, cron)`    | Schedule a task using cron expression  |
-| `descheduleTaskByName(name)`        | Remove task from schedule              |
-| `start()`                           | Start the scheduler                    |
-| `stop()`                            | Stop the scheduler                     |
-
-### Taskchain Methods
-
-| Method                  | Description            |
-| ----------------------- | ---------------------- |
-| `addTask(task)`         | Add task to chain      |
-| `removeTask(taskName)`  | Remove task from chain |
-| `trigger(initialValue)` | Execute the chain      |
-| `reset()`               | Reset chain state      |
-
-## Performance Tips 🏎️
-
-1. **Use buffering for I/O operations**: Prevents overwhelming external services
-2. **Leverage parallel execution**: When tasks are independent, run them simultaneously
-3. **Implement proper error handling**: Use try-catch in task functions
-4. **Monitor task execution**: Use the built-in stats and logging
-5. **Set appropriate timeouts**: Prevent hanging tasks from blocking your system
-6. **Use step tracking wisely**: Don't create too many granular steps - aim for meaningful progress points
-
-## Error Handling 🛡️
+## 🧪 Testing
 
 ```typescript
-const robustTask = new Task({
-  name: 'RobustOperation',
-  steps: [
-    { name: 'try', description: 'Attempting operation', percentage: 80 },
-    { name: 'retry', description: 'Retrying on failure', percentage: 20 }
-  ] as const,
-  taskFunction: async (input) => {
-    try {
-      robustTask.notifyStep('try');
-      return await riskyOperation(input);
-    } catch (error) {
-      // Log error
-      console.error(`Task failed: ${error.message}`);
-
-      // Optionally retry
-      if (error.retryable) {
-        robustTask.notifyStep('retry');
-        return await riskyOperation(input);
-      }
+import { expect, tap } from '@git.zone/tstest';
+import { Task } from '@push.rocks/taskbuffer';
 
-      // Or return default value
-      return defaultValue;
+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';
     }
-  },
-  timeout: 5000, // Fail if takes longer than 5 seconds
+  });
+  
+  const result = await task.trigger();
+  expect(result).toEqual('done');
+  expect(task.getProgress()).toEqual(100);
 });
 ```
 
-## Real-World Examples 🌍
+## 🌐 Real-World Examples
 
-### API Rate Limiting with Progress
+### API Rate Limiter
 
 ```typescript
-const apiClient = new Task({
-  name: 'RateLimitedAPI',
-  steps: [
-    { name: 'wait', description: 'Rate limit delay', percentage: 10 },
-    { name: 'call', description: 'API call', percentage: 90 }
-  ] as const,
-  taskFunction: async (endpoint: string) => {
-    apiClient.notifyStep('wait');
-    await delay(100); // Rate limiting
-    
-    apiClient.notifyStep('call');
-    return await fetch(`https://api.example.com${endpoint}`);
-  },
+const apiLimiter = new Task({
+  name: 'APIRateLimiter',
   buffered: true,
-  bufferMax: 10, // 10 requests
-  execDelay: 100, // Per 100ms = 100 req/s max
+  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)
+    });
+  }
 });
 ```
 
-### Database Migration Pipeline with Progress
+### Database Migration Pipeline
 
 ```typescript
 const migrationChain = new Taskchain({
   name: 'DatabaseMigration',
-  taskArray: [
-    new Task({
-      name: 'Backup',
-      steps: [{ name: 'backup', description: 'Creating backup', percentage: 100 }] as const,
-      taskFunction: async () => {
-        backupTask.notifyStep('backup');
-        return await createBackup();
-      }
-    }),
-    new Task({
-      name: 'SchemaUpdate',
-      steps: [
-        { name: 'analyze', description: 'Analyzing changes', percentage: 30 },
-        { name: 'apply', description: 'Applying migrations', percentage: 70 }
-      ] as const,
-      taskFunction: async () => {
-        schemaTask.notifyStep('analyze');
-        const changes = await analyzeSchema();
-        
-        schemaTask.notifyStep('apply');
-        return await applyMigrations(changes);
-      }
-    }),
-    // ... more tasks
-  ],
-});
-
-// Execute with progress monitoring
-const result = await migrationChain.trigger();
+  tasks: [
+    backupDatabaseTask,
+    validateSchemaTask,
+    runMigrationsTask,
+    verifyIntegrityTask,
+    updateIndexesTask
+  ]
+});
+
+// Execute with rollback on failure
+try {
+  await migrationChain.trigger();
+  console.log('Migration successful!');
+} catch (error) {
+  await rollbackTask.trigger();
+  throw error;
+}
 ```
 
-### Microservice Health Monitoring Dashboard
+### Distributed Job Queue
 
 ```typescript
-const healthMonitor = new TaskManager();
-
-services.forEach((service) => {
-  const healthCheck = new Task({
-    name: `HealthCheck:${service.name}`,
-    steps: [
-      { name: 'ping', description: 'Pinging service', percentage: 30 },
-      { name: 'check', description: 'Checking health', percentage: 50 },
-      { name: 'report', description: 'Reporting status', percentage: 20 }
-    ] as const,
-    taskFunction: async () => {
-      healthCheck.notifyStep('ping');
-      const responsive = await ping(service.url);
-      
-      healthCheck.notifyStep('check');
-      const healthy = await checkHealth(service.url);
-      
-      healthCheck.notifyStep('report');
-      if (!healthy) {
-        await alertOps(service);
-      }
-      
-      return { service: service.name, healthy, timestamp: Date.now() };
-    },
-  });
+const jobQueue = new TaskManager();
 
-  healthMonitor.addAndScheduleTask(healthCheck, '*/1 * * * *'); // Every minute
+// 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);
+  }
 });
 
-// Dashboard endpoint
-app.get('/api/health/dashboard', (req, res) => {
-  const metadata = healthMonitor.getAllTasksMetadata();
-  res.json({
-    services: metadata.map(task => ({
-      name: task.name.replace('HealthCheck:', ''),
-      status: task.status,
-      lastCheck: task.lastRun,
-      nextCheck: healthMonitor.getScheduledTasks()
-        .find(s => s.name === task.name)?.nextRun,
-      progress: task.currentProgress,
-      currentStep: task.currentStep
-    }))
-  });
+jobQueue.addTask(imageProcessor);
+
+// Process incoming jobs
+messageQueue.on('job', async (job) => {
+  const result = await jobQueue.getTaskByName('ImageProcessor').trigger(job);
+  await messageQueue.ack(job.id, result);
 });
 ```
 
-## Testing 🧪
+## 🚀 Performance Tips
 
-```typescript
-import { expect, tap } from '@git.zone/tstest';
-import { Task, TaskStep } from '@push.rocks/taskbuffer';
+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
 
-tap.test('should track task progress through steps', async () => {
-  const task = new Task({
-    name: 'TestTask',
-    steps: [
-      { name: 'step1', description: 'First step', percentage: 50 },
-      { name: 'step2', description: 'Second step', percentage: 50 }
-    ] as const,
-    taskFunction: async () => {
-      task.notifyStep('step1');
-      expect(task.getProgress()).toBeLessThanOrEqual(50);
-      
-      task.notifyStep('step2');
-      expect(task.getProgress()).toBeLessThanOrEqual(100);
-    }
-  });
-  
-  await task.trigger();
-  expect(task.getProgress()).toEqual(100);
-});
+## 🔍 Debugging
 
-tap.test('should collect execution metadata', async () => {
-  const manager = new TaskManager();
-  const task = new Task({
-    name: 'MetadataTest',
-    taskFunction: async () => 'result'
-  });
-  
-  const report = await manager.addExecuteRemoveTask(task);
-  expect(report.taskName).toEqual('MetadataTest');
-  expect(report.result).toEqual('result');
-  expect(report.duration).toBeGreaterThan(0);
-});
+Enable detailed logging:
 
-tap.start();
-```
+```typescript
+import { logger } from '@push.rocks/smartlog';
 
-## Support 💬
+logger.enableConsole();
+logger.level = 'debug';
+
+// Tasks will now output detailed execution logs
+```
 
-- 📧 Email: [hello@task.vc](mailto:hello@task.vc)
-- 🐛 Issues: [GitHub Issues](https://github.com/push-rocks/taskbuffer/issues)
-- 📖 Docs: [Documentation](https://code.foss.global/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
+- **`TaskLoop`** - Repeating task with conditions
+
+### 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