Skip to main content
Version: 3.5

Events

ForesightManager emits various events during to provide insight into element registration, prediction activities, and callback executions. These events are primarily used by the ForesightJS DevTools for visual debugging and monitoring, but can also be leveraged for telemetry, analytics, and performance monitoring in your applications.

Usage​

All events are visible in the logs tab of the devtools. However for tracking/analytics in production, implementing them in your own code is straightforward with the standard addEventListener pattern.

import { ForesightManager } from "js.foresight"

// Define handler as const for removal
const handleCallbackInvoked = event => {
  console.log(
    `Callback executed for ${event.elementData.name} in ${event.hitType.kind} mode, which took ${event.elapsed} ms`
  )
}

// Add the event
ForesightManager.instance.addEventListener("callbackInvoked", handleCallbackInvoked)

// Later, remove the listener using the same reference
ForesightManager.instance.removeEventListener("callbackInvoked", handleCallbackInvoked)

AbortController support​

Event listeners support AbortController signals for easy cleanup.

const controller = new AbortController()

manager.addEventListener("callbackInvoked", handleCallbackInvoked, { signal: controller.signal })

controller.abort()

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
  elementData: ForesightElementData
  hitType: CallbackHitType
}

Related Types: CallbackHitType • ForesightElementData

callbackCompleted​

Fired after an element's callback is executed

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

Related Types: CallbackHitType • ForesightElementData

Element Lifecycle Events​

Events fired during element registration, updates, and cleanup.

elementRegistered​

Fired when an element is successfully registered with ForesightManager using ForesightManager.instance.register(element).

type ElementRegisteredEvent = {
  type: "elementRegistered"
  timestamp: number
  elementData: ForesightElementData
}

Related Types: ForesightElementData

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
  elementData: ForesightElementData
  unregisterReason: "disconnected" | "apiCall" | "devtools" | (string & {})
  wasLastRegisteredElement: boolean
}

Related Types: ForesightElementData

Prediction Events​

Events fired during movement prediction calculations.

mouseTrajectoryUpdate​

Fired during mouse movement for trajectory calculations

type MouseTrajectoryUpdateEvent = {
  type: "mouseTrajectoryUpdate"
  trajectoryPositions: {
    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[]
}

Extra Type Info​

ForesightElementData

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"
}