A Scheduler is the hidden commander of a reactivity system. It decides not whether something should run, but when it should run. New article: Building a Signal Scheduler

endingFlush) return; this.pendingFlush = Promise.resolve().then(() => { this.flush(); this.pendingFlush = null; }); }

// Process the queue
flush(): void {
    if (this.isFlushing) return;
    this.isFlushing = true;

    try {
        while (!this.queue.isEmpty()) {
            const task = this.queue.dequeue();
            if (!task) break;

            // Skip if not dirty or lazy and not needed
            if (!task.isDirty) continue;
            
            // Execute effect
            task.fn();
            task.isDirty = false;
            task.lastRunGeneration = performance.now(); // Simplified generation tracking
        }
    } finally {
        this.isFlushing = false;
    }
}

}

// Signal Implementation class ReactiveSignal<T> implements Signal<T> { value: T; generation: number = 0; subscribers: Set<EffectTask> = new Set(); private currentEffect: EffectTask | null = null;

constructor(initialValue: T) {
    this.value = initialValue;
}

read(): T {
    if (this.currentEffect) {
        this.subscribers.add(this.currentEffect);
        this.currentEffect.dependencies.add(this);
    }
    return this.value;
}

write(nextValue: T): void {
    if (Object.is(this.value, nextValue)) return;
    this.value = nextValue;
    this.generation++;
    this.notifySubscribers();
}

private notifySubscribers(): void {
    for (const effect of this.subscribers) {
        if (effect.isLazy) {
            // Lazy effects mark dirty but don't schedule immediately
            effect.isDirty = true;
        } else {
            orchestrator.schedule(effect);
        }
    }
}

}

// Effect Registration function createEffect( fn: () => void, options: { priority?: PriorityLevel; lazy?: boolean } = {} ): EffectTask { const task: EffectTask = { id: Symbol('effect'), fn, priority: options.priority || 'normal', dependencies: new Set(), isDirty: false, isLazy: !!options.lazy, lastRunGeneration: 0, };

// Initial run
const prevEffect = getCurrentEffect();
setCurrentEffect(task);
try {
    fn();
} finally {
    setCurrentEffect(prevEffect);
}

return task;

}

// Global state for dependency tracking let currentEffect: EffectTask | null = null; function getCurrentEffect(): EffectTask | null { return currentEffect; } function setCurrentEffect(e: EffectTask | null): void { currentEffect = e; }

const orchestrator = new ExecutionOrchestrator();

#### Rationale

*   **`TaskQueue` with Buckets:** Using separate arrays per priority avoids sorting overhead during enqueue. Dequeue checks buckets in order, ensuring O(1) access to the highest priority task.
*   **Microtask Flushing:** `Promise.resolve().then()` schedules the flush as a microtask. This allows multiple synchronous writes to a signal to coalesce into a single flush, effectively providing automatic batching without explicit API calls for every scenario.
*   **Lazy Signals:** When `isLazy` is true, the signal marks the effect as dirty but does not enqueue it. The effect only runs when the lazy value is read, preventing computation of unused derived state.
*   **Generation Tracking:** The `generation` counter on signals allows effects to detect actual changes versus redundant notifications, though the simplified implementation above relies on the `isDirty` flag for correctness. In production, generation counters prevent re-execution if dependencies haven't changed.

### Pitfall Guide

1.  **The Cascade Trap (Infinite Loops)**
    *   *Explanation:* An effect reads a signal, computes a new value, and writes it back to the same signal, triggering itself again.
    *   *Fix:* Implement strict dependency tracking and dirty checking. Ensure effects only write to signals they do not depend on, or use a generation counter to skip execution if the value hasn't actually changed.

2.  **Priority Starvation**
    *   *Explanation:* Continuous high-priority tasks prevent low-priority tasks from ever running.
    *   *Fix:* Implement aging. If a low-priority task remains in the queue beyond a threshold, promote its priority. Alternatively, use time-slicing to guarantee a slice of execution for lower tiers.

3.  **Nested Batch Scope Errors**
    *   *Explanation:* Calling `startBatch` multiple times without matching `endBatch` calls, or failing to handle exceptions within a batch, leaves the scheduler in a perpetual batched state.
    *   *Fix:* Use a reference counter for batch depth. Wrap batch callbacks in try/finally blocks to guarantee `endBatch` is called. Consider a `withBatch` helper that manages scope automatically.

4.  **Memory Leaks via Subscribers**
    *   *Explanation:* Effects are added to signal subscribers but never removed when the effect is disposed or the component unmounts.
    *   *Fix:* Every effect must have a disposal mechanism that iterates over its `dependencies` and removes itself from their `subscribers` sets. Use `WeakRef` for subscribers if appropriate, though explicit disposal is safer for deterministic cleanup.

5.  **Lazy Staleness**
    *   *Explanation:* A lazy signal is read, but its dependencies have changed since the last computation, yet it returns a cached value.
    *   *Fix:* Lazy signals must check the generation of their dependencies upon read. If any dependency has a newer generation, the signal must recompute before returning the value.

6.  **Microtask vs Macrotask Confusion**
    *   *Explanation:* Using `setTimeout` (macrotask) for flushing introduces visible latency, while microtasks may delay rendering if the flush is too heavy.
    *   *Fix:* Use microtasks for standard flushing to maintain responsiveness. For extremely heavy computations, consider yielding to the main thread using `requestIdleCallback` or splitting work across multiple frames.

7.  **Race Conditions in Async Effects**
    *   *Explanation:* An async effect starts, but the signal updates again before the async operation completes, leading to stale closures or out-of-order updates.
    *   *Fix:* Use a cancellation token or version counter within the effect. Discard results from older invocations if a newer update has occurred.

### Production Bundle

#### Action Checklist

- [ ] **Implement Dirty Flags:** Ensure every effect tracks whether it needs to run. Prevent duplicate enqueues.
- [ ] **Add Disposal Logic:** Create a `dispose()` method for effects that cleans up all subscriber relationships.
- [ ] **Configure Flush Strategy:** Decide between microtask (default) and sync flush based on latency requirements.
- [ ] **Stress Test Batching:** Write tests that trigger 100+ rapid updates to verify coalescing behavior.
- [ ] **Add Error Boundaries:** Wrap effect execution in try/catch to prevent one failing effect from halting the scheduler.
- [ ] **Profile Memory Usage:** Monitor subscriber sets for leaks during component lifecycle transitions.
- [ ] **Define Priority Tiers:** Map application concerns to `critical`, `normal`, and `low` priorities explicitly.

#### Decision Matrix

| Scenario | Recommended Approach | Why | Cost Impact |
| :--- | :--- | :--- | :--- |
| **High-frequency Input** | Microtask Flush + Batching | Coalesces rapid updates, prevents frame drops. | Low CPU, High UX |
| **Critical UI Render** | Priority: `critical` | Ensures visual updates run before background tasks. | Negligible overhead |
| **Expensive Derived State** | Lazy Evaluation | Defers computation until value is actually read. | High CPU savings |
| **Background Sync** | Priority: `low` + Macrotask | Prevents blocking main thread; runs when idle. | Low priority, safe |
| **Unit Testing** | Sync Flush Mode | Makes effects run immediately for deterministic assertions. | Dev-only config |

#### Configuration Template

Use this configuration to initialize the scheduler with production-safe defaults.

```typescript
interface SchedulerConfig {
    flushStrategy: 'microtask' | 'sync' | 'raf';
    enableLazyEvaluation: boolean;
    errorHandling: 'throw' | 'log' | 'ignore';
    maxBatchSize?: number; // Limit batch depth to prevent OOM
}

const defaultConfig: SchedulerConfig = {
    flushStrategy: 'microtask',
    enableLazyEvaluation: true,
    errorHandling: 'log',
    maxBatchSize: 100,
};

// Usage
const scheduler = new ExecutionOrchestrator(defaultConfig);

Quick Start Guide

1. Define Signals: Create ReactiveSignal instances for your state.

   const count = new ReactiveSignal(0);
   

2. Create Effects: Register side effects with priorities.

   createEffect(() => {
       console.log('Count changed:', count.read());
   }, { priority: 'normal' });
   

3. Batch Mutations: Wrap multiple writes in a batch.

   orchestrator.startBatch();
   count.write(1);
   count.write(2);
   orchestrator.endBatch(); // Triggers single flush
   

4. Dispose: Clean up when no longer needed.

   const effect = createEffect(() => { /* ... */ });
   // Later...
   effect.dispose(); // Removes subscribers
   

5. Verify: Check that updates are coalesced and priorities are respected in your logs or performance profiler.