Zone Pollution Fixes

## Zones are inherited In a zone-based Angular app, zone.js propagates the **current zone** to everything scheduled from it. A `setTimeout` created inside the Angular zone calls back inside the Angular zone; an event listener added inside it fires inside it. `NgZone` exposes two methods that move code between zones: - **`runOutsideAngular(fn)`** runs `fn` in the Angular zone's parent. Everything `fn` schedules (timers, listeners, promise continuations, library-internal tasks) is also outside, for as long as it lives. - **`run(fn)`** runs `fn` inside the Angular zone. When it finishes, zone.js reports a completed task and Angular runs change detection. The static method **`NgZone.isInAngularZone()`** returns whether the current code is inside the Angular zone, which is the quickest way to check an assumption while debugging. ## The pattern The Angular performance guide's recipe for third-party libraries is: 1. Initialise the library inside `runOutsideAngular()`, so its internal timers and listeners stop triggering checks. 2. Subscribe to the few library events the application cares about. 3. Inside those handlers, wrap the state update in `run()` so Angular checks once. ```ts this.zone.runOutsideAngular(() => { const editor = createEditor(this.host().nativeElement); editor.on('save', (doc) => { this.zone.run(() => this.saved.emit(doc)); // re-enter for the one event that matters }); }); ``` ## What breaks if you forget `run()` The library handler above runs outside the Angular zone because it was registered there. Without `run()`: | Handler does | Result in a zone-based app | |---|---| | Assigns a plain field read by a template | No check is triggered; the screen stays stale | | Emits an `output()` whose parent handler assigns a plain field | The parent handler also runs outside the zone; the parent stays stale | | Calls a service that later makes an `HttpClient` request | The request runs outside the zone too; a plain-field update in its response triggers no check | | Sets a signal read by a template | A check is scheduled anyway (hybrid scheduling, since v18) | | Calls `ChangeDetectorRef.markForCheck()` | A check is scheduled anyway (since v18) | The symptom is typical: the value appears only after the user clicks something else, because that click triggers a check from inside the zone. It looks intermittent, but it is deterministic: nothing notified Angular. ## Signals as the alternative Since v18, a zone-based app's scheduler also listens for Angular's own notifications that come from **outside** the zone: setting a signal that a template reads, or calling `markForCheck()`. So a handler that does `this.selection.set(doc)` renders without `run()`. That is often cleaner: - it expresses what changed rather than where code runs; - it keeps working unchanged if the app later goes zoneless, where `run()` does nothing; - the check it schedules is targeted: views that read the signal are refreshed, rather than every `Eager` view from the root. `run()` is still the right tool when the code inside must run in the Angular zone for other reasons, for example to let zone-based libraries or `HttpClient` calls started from it be tracked. ## Common mistakes 1. **Re-entering too early.** Calling `run()` around the library's initialisation instead of around one callback puts everything back inside the zone. 2. **Assuming outputs are safe.** An `output()` emitted outside the zone runs the parent's handler outside the zone as well; the parent's plain fields stay stale. 3. **Forgetting inherited async work.** A promise chain or an RxJS subscription started from an outside callback continues outside, so a later `.then()` that updates state also needs re-entry or a signal. 4. **Debugging by guesswork.** Logging `NgZone.isInAngularZone()` at the suspicious line answers the question in seconds. ## Keep the re-entry narrow - Wrap only the state update, not the whole handler; heavy work inside `run()` makes the zone treat it all as Angular work. - Do not wrap high-frequency events such as `mousemove` in `run()` unconditionally, or you recreate the pollution you removed. Re-enter only when the value actually changes, or throttle first. - Leave `runOutsideAngular()` and `run()` in place when moving to zoneless: they become plain function calls and the zoneless guide says removing them can regress zone-based consumers.