Skip to main content
Version: 4.x

Events

ForesightManager emits events to provide insight into element registration, prediction activity, and callback execution. These events are primarily used by the ForesightJS DevTools, but can also power telemetry, analytics, and counters in your Angular app.

Usage​

In Angular the easiest way to listen to events from a component, directive, or injectable context is injectForesightEvent:

import { Component, signal } from "@angular/core"
import { injectForesightEvent } from "@foresightjs/angular"

@Component({
  selector: "app-prefetch-counter",
  standalone: true,
  template: `<p>{{ hits() }} prefetches triggered</p>`,
})
export class PrefetchCounterComponent {
  readonly hits = signal(0)

  constructor() {
    injectForesightEvent("callbackInvoked", () => {
      this.hits.update(count => count + 1)
    })
  }
}

The standard ForesightManager.instance.addEventListener / removeEventListener pattern is also available if you want to listen outside Angular.

Available Events​

Interaction Events​

Events fired when user interactions trigger callbacks.

callbackInvoked​

Fired before an element's callback is executed

type CallbackInvokedEvent = {
  type: "callbackInvoked"
  timestamp: number
  element: ForesightElement
  state: ForesightElementState
  hitType: CallbackHitType
}

Related Types: CallbackHitType • ForesightElementState

callbackCompleted​

Fired after an element's callback is executed

type CallbackCompletedEvent = {
  type: "callbackCompleted"
  timestamp: number
  element: ForesightElement
  state: ForesightElementState
  hitType: CallbackHitType
  elapsed: number // Time between callbackInvoked and callbackCompleted
  status: "success" | "error" | undefined
  errorMessage: string | null
  wasLastActiveElement: boolean
}

Related Types: CallbackHitType • ForesightElementState

Element Lifecycle Events​

Events fired during element registration, updates, and cleanup.

elementRegistered​

Fired when a new element is registered with ForesightManager using ForesightManager.instance.register({ element, callback }). Registering an already-tracked element updates its options without emitting another elementRegistered event.

type ElementRegisteredEvent = {
  type: "elementRegistered"
  timestamp: number
  element: ForesightElement
  state: ForesightElementState
}

Related Types: ForesightElementState

elementUnregistered​

Fired when an element is removed from ForesightManager's tracking via ForesightManager.instance.unregister(element). Detaching an element from the DOM no longer unregisters it. It is parked (kept registered but inactive) and resumed on reattach, so no elementUnregistered event fires for that. The "disconnected" reason is therefore no longer emitted.

type ElementUnregisteredEvent = {
  type: "elementUnregistered"
  timestamp: number
  element: ForesightElement
  state: ForesightElementState
  unregisterReason: "disconnected" | "apiCall" | "devtools" | (string & {})
  wasLastRegisteredElement: boolean
}

Related Types: ForesightElementState

Prediction Events​

Events fired during movement prediction calculations.

mouseTrajectoryUpdate​

Fired during mouse movement for trajectory calculations

type MouseTrajectoryUpdateEvent = {
  type: "mouseTrajectoryUpdate"
  trajectoryPositions: {
    positions: CircularBuffer<MousePosition> // mouse position history
    currentPoint: { x: number; y: number }
    predictedPoint: { x: number; y: number }
  }
  predictionEnabled: boolean
}

scrollTrajectoryUpdate​

Fired during scroll events when scroll prediction is active

type ScrollTrajectoryUpdateEvent = {
  type: "scrollTrajectoryUpdate"
  currentPoint: Point // { x: number; y: number }
  predictedPoint: Point // { x: number; y: number }
  scrollDirection: ScrollDirection // "down" | "up" | "left" | "right"
}

Configuration Events​

Events fired when ForesightManager configuration changes.

managerSettingsChanged​

Fired when global ForesightManager settings are updated via the devtools or via ForesightManager.instance.alterGlobalSettings().

type ManagerSettingsChangedEvent = {
  type: "managerSettingsChanged"
  timestamp: number
  managerData: Readonly<ForesightManagerData>
  updatedSettings: UpdatedManagerSetting[]
}

Related Types: ForesightManagerData

deviceStrategyChanged​

Fired when user switches between input methods (mouse, touch, or pen).

type DeviceStrategyChangedEvent = {
  type: "deviceStrategyChanged"
  timestamp: number
  newStrategy: CurrentDeviceStrategy // "mouse" | "touch" | "pen"
  oldStrategy: CurrentDeviceStrategy // "mouse" | "touch" | "pen"
}