Skip to main content
Not yet stable
@foresightjs/vue is at 0.1.0 and not yet stable. It works and is fully tested, but the API may still change.
Version: 4.0

Events

ForesightManager emits various events 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​

In Vue the easiest way to listen to events is the useForesightEvent composable, which adds and removes the listener for you:

<script setup lang="ts">
  import { ref } from "vue"
  import { useForesightEvent } from "@foresightjs/vue"

  const hits = ref(0)

  useForesightEvent("callbackInvoked", () => {
    hits.value++
  })
</script>

<template>
  <p>{{ hits }} prefetches triggered</p>
</template>

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

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 an element is successfully registered with ForesightManager using ForesightManager.instance.register(element).

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