Skip to main content
Version: Next

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: HitType
}

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

elementReactivated​

Fired when an element is reactivated after its callback was triggered. This happends after reactivateAfter ms (default infinity) or with foresightmanager.instance.reactivate(element).

type ElementReactivatedEvent = {
  type: "elementReactivated"
  timestamp: number
  elementData: ForesightElementData
}

Related Types: ForesightElementData

elementUnregistered​

Fired when an element is removed from ForesightManager's tracking. This only happends when the element is removed from the DOM or via developer actions like foresightmanar.instance.unregister(element)

type ElementUnregisteredEvent = {
  type: "elementUnregistered"
  timestamp: number
  elementData: ForesightElementData
  unregisterReason: "disconnected" | "apiCall" | "devtools" | (string & {})
  wasLastRegisteredElement: boolean
}

Related Types: ForesightElementData

elementDataUpdated​

Fired when tracked element data changes (bounds/visibility only). Does not fire on any updates regarding callback data.

type ElementDataUpdatedEvent = {
  type: "elementDataUpdated"
  elementData: ForesightElementData
  updatedProps: UpdatedDataPropertyNames[] // "bounds" | "visibility"
}

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 from mouse+keyboard setup to pen/touch or vice versa.

type ManagerSettingsChangedEvent = {
  type: "deviceStrategyChanged"
  timestamp: number
  newStrategy: CurrentDeviceStrategy
  oldStrategy: CurrentDeviceStrategy
}