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

tion demonstrates a production-grade scheduler. Note the use of distinct naming conventions and structural choices to ensure robustness.

// Signal Scheduler Architecture
// Types and Interfaces

type PriorityLevel = 'critical' | 'normal' | 'low';

interface EffectTask {
    id: symbol;
    fn: () => void;
    priority: PriorityLevel;
    dependencies: Set<Signal<any>>;
    isDirty: boolean;
    isLazy: boolean;
    lastRunGeneration: number;
}

interface Signal<T> {
    value: T;
    generation: number;
    subscribers: Set<EffectTask>;
    read(): T;
    write(nextValue: T): void;
}

// Priority Queue for Task Management
class TaskQueue {
    private buckets: Map<PriorityLevel, EffectTask[]> = new Map([
        ['critical', []],
        ['normal', []],
        ['low', []],
    ]);

    enqueue(task: EffectTask): void {
        const bucket = this.buckets.get(task.priority)!;
        if (!bucket.includes(task)) {
            bucket.push(task);
        }
    }

    dequeue(): EffectTask | undefined {
        for (const priority of ['critical', 'normal', 'low'] as PriorityLevel[]) {
            const bucket = this.buckets.get(priority)!;
            if (bucket.length > 0) {
                return bucket.shift();
            }
        }
        return undefined;
    }

    isEmpty(): boolean {
        return Array.from(this.buckets.values()).every(b => b.length === 0);
    }
}

// Execution Orchestrator
class ExecutionOrchestrator {
    private queue = new TaskQueue();
    private isFlushing = false;
    private batchDepth = 0;
    private pendingFlush: Promise<void> | null = null;

    // Enqueue an effect for execution
    schedule(task: EffectTask): void {
        if (task.isDirty) return; // Already scheduled
        task.isDirty = true;
        this.queue.enqueue(task);

        if (!this.isFlushing && this.batchDepth === 0) {
            this.requestFlush();
        }
    }

    // Batch mutations to prevent immediate flushing
    startBatch(): void {
        this.batchDepth++;
    }

    endBatch(): void {
        if (this.batchDepth > 0) {
            this.batchDepth--;
            if (this.batchDepth === 0 && !this.isFlushing) {
                this.requestFlush();
            }
        }
    }

    // Request flush via microtask for automatic batching
    private requestFlush(): void {
        if (this.pendingFlush) 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.

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.