} else { this.macroQueue.push(task); } }

private flushMicroQueue(): void { while (this.microQueue.length > 0) { const task = this.microQueue.shift()!; try { task.callback(); } catch (error) { console.error(Microtask ${task.id} failed:, error); } } }

cancel(taskId: string): boolean { const timer = this.activeTimers.get(taskId); if (timer) { clearTimeout(timer); this.activeTimers.delete(taskId); return true; } return false; } }

### Step 3: Architecture Decisions & Rationale
**Queue Separation**: Microtasks and macrotasks serve different purposes. Microtasks (Promise resolutions, `queueMicrotask`) execute immediately after the current synchronous code finishes, before rendering or I/O callbacks. Macrotasks (`setTimeout`, `setInterval`, I/O) yield to the event loop, allowing UI updates and other pending operations. Separating them prevents priority inversion and ensures critical state updates don't get delayed by heavy I/O callbacks.

**Explicit Timer Tracking**: Native timers are opaque. By maintaining a `Map` of active timers, you gain cancellation control, memory leak prevention, and debugging visibility. This is critical in long-running server processes or SPA navigation cycles where orphaned timers cause state corruption.

**Error Boundary Execution**: Wrapping callback execution in try/catch prevents a single failing task from crashing the event loop. In production, this maps to unhandled rejection handlers and process-level error boundaries.

**Why This Works**: The architecture mirrors the actual runtime pipeline. Instead of fighting the event loop, it cooperates with it. By explicitly managing queue insertion and respecting the single-threaded constraint, you eliminate race conditions caused by implicit execution order and reduce event loop starvation.

## Pitfall Guide

### 1. Timer Precision Fallacy
**Explanation**: Developers assume `setTimeout(fn, 100)` executes exactly at 100ms. In reality, browsers throttle background tabs to 1000ms intervals, and Node.js timer resolution depends on libuv's heap implementation and OS scheduler ticks.
**Fix**: Never use timers for strict timing requirements. Use `performance.now()` for measurements, and implement tolerance windows (`±50ms`) for business logic. For precision scheduling, consider Web Workers or native addons.

### 2. Microtask vs Macrotask Confusion
**Explanation**: Mixing Promise chains with `setTimeout` creates unpredictable execution order. Microtasks drain completely before the event loop processes macrotasks, which can delay UI rendering or I/O callbacks.
**Fix**: Reserve microtasks for state synchronization and immediate follow-ups. Use macrotasks for deferring work to allow rendering or I/O processing. Explicitly document queue expectations in team conventions.

### 3. CPU-Bound Work in Callback Chains
**Explanation**: JavaScript's single thread executes callbacks synchronously. Heavy computation inside a timer or I/O callback blocks the event loop, freezing UI and stalling network responses.
**Fix**: Offload computation to Web Workers, `worker_threads` in Node.js, or chunk processing with `requestIdleCallback`/`setImmediate`. Keep callbacks under 16ms for 60fps targets.

### 4. Cross-Runtime API Drift
**Explanation**: `setTimeout`, `fetch`, and `console` behave differently across browsers, Node.js, Deno, and React Native. Relying on undocumented behavior causes production failures during environment migrations.
**Fix**: Abstract runtime APIs behind interface contracts. Use polyfills or feature detection for missing capabilities. Test across target runtimes in CI pipelines.

### 5. Assuming Timers Create Threads
**Explanation**: `setTimeout` does not spawn threads. It registers a callback with the host scheduler. The callback still executes on the main thread when the event loop picks it up.
**Fix**: Design for single-threaded execution. Use explicit concurrency primitives (`Promise.all`, worker pools, async iterators) for parallel work. Never assume background execution from timer APIs.

### 6. Timer Coalescing & Throttling
**Explanation**: Browsers coalesce rapid timers to save battery. Node.js optimizes libuv timer heaps by batching nearby deadlines. This causes apparent "skipped" or "delayed" executions.
**Fix**: Avoid scheduling dozens of timers in tight loops. Use a single interval with batch processing, or leverage `requestAnimationFrame` for visual updates. Monitor event loop lag with `perf_hooks`.

### 7. Memory Leaks from Uncancelled Timers
**Explanation**: Timers hold references to closures and DOM nodes. In SPAs or long-running servers, orphaned timers prevent garbage collection, causing gradual memory growth.
**Fix**: Always pair `setTimeout` with `clearTimeout` in cleanup routines. Use `AbortController` for cancellable operations. Implement timer lifecycle tracking in component unmount or request teardown hooks.

## Production Bundle

### Action Checklist
- [ ] Audit timer usage: Replace implicit `setTimeout` chains with explicit queue management
- [ ] Implement cleanup routines: Ensure every scheduled task has a corresponding cancellation path
- [ ] Separate microtask/macrotask logic: Document queue expectations and enforce via linting rules
- [ ] Add event loop monitoring: Track lag with `perf_hooks.monitorEventLoopDelay()` in Node.js or `requestIdleCallback` in browsers
- [ ] Abstract runtime APIs: Create interface layers for `setTimeout`, `fetch`, and I/O to isolate environment differences
- [ ] Chunk CPU-bound work: Break heavy operations into ≤16ms slices or delegate to workers
- [ ] Test cross-runtime behavior: Validate timer precision, queue order, and error handling across target environments

### Decision Matrix

| Scenario | Recommended Approach | Why | Cost Impact |
|----------|---------------------|-----|-------------|
| UI animation scheduling | `requestAnimationFrame` | Syncs with display refresh rate, avoids jank | Low (native optimization) |
| Background data polling | Single `setInterval` + batch processing | Reduces timer coalescing, lowers CPU overhead | Medium (requires batching logic) |
| High-precision timing | Web Workers + `performance.now()` | Bypasses main thread throttling, accurate deltas | High (worker setup, message passing) |
| Server I/O coordination | libuv-aware async/await + connection pooling | Leverages native thread pool, prevents event loop starvation | Low (standard Node.js pattern) |
| Cross-environment compatibility | Runtime abstraction layer + feature detection | Isolates API drift, enables graceful degradation | Medium (abstraction overhead) |

### Configuration Template

```typescript
// runtime-orchestrator.config.ts
import { AsyncOrchestrator, ScheduledTask } from './AsyncOrchestrator';

export const createProductionScheduler = () => {
  const scheduler = new AsyncOrchestrator();

  // Global error boundary for task execution
  const originalSchedule = scheduler.schedule.bind(scheduler);
  scheduler.schedule = (task: ScheduledTask) => {
    const wrappedCallback = () => {
      try {
        task.callback();
      } catch (err) {
        // Route to monitoring system instead of crashing event loop
        process.emit('uncaughtException', err as Error);
      }
    };
    return originalSchedule({ ...task, callback: wrappedCallback });
  };

  // Auto-cleanup on process exit / page unload
  const cleanup = () => {
    scheduler.activeTimers.forEach((timer) => clearTimeout(timer));
    scheduler.activeTimers.clear();
  };

  if (typeof window !== 'undefined') {
    window.addEventListener('beforeunload', cleanup);
  } else {
    process.on('SIGTERM', cleanup);
    process.on('SIGINT', cleanup);
  }

  return scheduler;
};

Quick Start Guide

1. Initialize the orchestrator: Import createProductionScheduler and instantiate it in your application entry point. This establishes queue management and cleanup hooks.
2. Replace direct timer calls: Swap setTimeout(fn, delay) with scheduler.schedule({ id: crypto.randomUUID(), callback: fn, priority: 'macro', delayMs: delay }).
3. Implement cancellation paths: Store returned task IDs in component state or request context. Call scheduler.cancel(taskId) during unmount, route change, or request teardown.
4. Monitor event loop health: In Node.js, add perf_hooks.monitorEventLoopDelay({ resolution: 10 }) to track lag. In browsers, use requestIdleCallback to defer non-critical work when the main thread is busy.
5. Validate cross-runtime behavior: Run integration tests across target environments. Assert queue execution order, timer tolerance windows, and cleanup behavior before deploying to production.