{{ hits() }} prefetches triggered
`, }) 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[](#available-events "Direct link to Available Events") ### Interaction Events[](#interaction-events "Direct link to Interaction Events") Events fired when user interactions trigger callbacks. *** #### `callbackInvoked`[](#callbackinvoked "Direct link to callbackinvoked") Fired **before** an element's callback is executed ``` type CallbackInvokedEvent = { type: "callbackInvoked" timestamp: number element: ForesightElement state: ForesightElementState hitType: CallbackHitType } ``` **Related Types:** [`CallbackHitType`](/docs/getting-started/typescript.md#callbackhittype) • [`ForesightElementState`](/docs/getting-started/typescript.md#foresightelementstate) *** #### `callbackCompleted`[](#callbackcompleted "Direct link to 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`](/docs/getting-started/typescript.md#callbackhittype) • [`ForesightElementState`](/docs/getting-started/typescript.md#foresightelementstate) ### Element Lifecycle Events[](#element-lifecycle-events "Direct link to Element Lifecycle Events") Events fired during element registration, updates, and cleanup. *** #### `elementRegistered`[](#elementregistered "Direct link to 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`](/docs/getting-started/typescript.md#foresightelementstate) *** #### `elementUnregistered`[](#elementunregistered "Direct link to 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`](/docs/getting-started/typescript.md#foresightelementstate) *** ### Prediction Events[](#prediction-events "Direct link to Prediction Events") Events fired during movement prediction calculations. *** #### `mouseTrajectoryUpdate`[](#mousetrajectoryupdate "Direct link to mousetrajectoryupdate") Fired during mouse movement for trajectory calculations ``` type MouseTrajectoryUpdateEvent = { type: "mouseTrajectoryUpdate" trajectoryPositions: { positions: CircularBuffer{{ hits() }} prefetches triggered
`, }) export class PrefetchCounterComponent { readonly hits = signal(0) constructor() { injectForesightEvent("callbackInvoked", () => { this.hits.update(count => count + 1) }) } } ``` You don't need to remove the listener yourself. Angular destroys the subscription with the component, directive, service, or other injection context where the helper was called. ## Dynamic event type[](#dynamic-event-type "Direct link to Dynamic event type") Pass an Angular signal when the event type needs to change over time. The subscription re-binds automatically: ``` readonly eventType = signal<"callbackInvoked" | "callbackCompleted">("callbackInvoked") constructor() { injectForesightEvent(this.eventType, event => { console.log(event.type) }) } ``` For listeners outside an injection context, use [`ForesightService.listen`](/docs/angular/foresight-service.md#listen-to-manager-events). --- # Installation [](https://www.npmjs.com/package/@foresightjs/angular) [](https://www.npmjs.com/package/@foresightjs/angular) `@foresightjs/angular` is the official Angular package for ForesightJS. It ships the standalone [`[fsForesight]`](/docs/angular/directive.md) directive for the common case, plus [`ForesightService`](/docs/angular/foresight-service.md), [`ForesightComponent`](/docs/angular/foresight-component.md), and [`injectForesightEvent`](/docs/angular/injectForesightEvent.md) for manual registration and event listeners. ``` npm install @foresightjs/angular js.foresight # or pnpm add @foresightjs/angular js.foresight # or yarn add @foresightjs/angular js.foresight ``` ``` import { ForesightDirective, ForesightManager, ForesightService } from "@foresightjs/angular" ``` ## Configuring the manager[](#configuring-the-manager "Direct link to Configuring the manager") You don't have to configure anything. The manager auto-initializes with sensible defaults the first time you register an element. If you want to tweak global behavior, call `ForesightManager.initialize()` once in your `main.ts` before your app renders. See [Initialize the Manager](/docs/angular/initialize-the-manager.md) and [Global Settings](/docs/angular/configuration/global-settings.md). ## Devtools[](#devtools "Direct link to Devtools") The visual [Development Tools](/docs/angular/devtools.md) live in their own package (`js.foresight-devtools`) and work the same regardless of framework. --- # Migrating to v4 In v3 the Angular docs handed you a directive to copy into your own project. v4 replaces that with the official [`@foresightjs/angular`](/docs/angular/installation.md) package. Install it, delete your copied directive, and import the standalone directive from the package. ``` npm install @foresightjs/angular js.foresight ``` ``` - import { ForesightDirective } from "./directives/foresight.directive" + import { ForesightDirective } from "@foresightjs/angular" ``` The directive selector is `[fsForesight]`: ``` Pricing ``` For reactive state, export the directive as `foresight` and read its signal: ``` ``` ## Core changes[](#core-changes "Direct link to Core changes") The core `js.foresight` library also has a few breaking changes. The package handles most of these for you, but they matter if you call `register()` or listen to events directly. The `register()` call itself is unchanged, but element data is now an immutable state snapshot you can subscribe to - the foundation the wrapper packages are built on: * **`ForesightElementData` is now `ForesightElementState`.** Your callback receives the flat state snapshot: `callback: (state: ForesightElementState) => void`. See [TypeScript](/docs/getting-started/typescript.md). * **`register()` returns the state plus `unregister`, `subscribe` and `getSnapshot`.** `isTouchDevice` is gone from the result; touch devices are handled internally by the configured `touchDeviceStrategy` global setting. * **The `elementDataUpdated`, `elementOptionsUpdated` and `elementReactivated` events are removed.** Per-element changes are now observed through the `subscribe`/`getSnapshot` pair returned by `register()`. The remaining events carry the state in a `state` field instead of `elementData`. * **Detached elements are parked, not unregistered.** Removing an element from the DOM no longer emits `elementUnregistered` with reason `disconnected`; the element stays registered but inactive and resumes when it reconnects. * **New `enabled` element option.** Set it to `false` to keep an element registered but excluded from prediction. --- # Quick Start This guide walks through registering your first element with ForesightJS in Angular and reading its prediction state. ## Basic Usage Example[](#basic-usage-example "Direct link to Basic Usage Example") The simplest way to register an element is the [`[fsForesight]`](/docs/angular/directive.md) directive. Import the standalone directive, put it on an element, and give it a callback: ``` import { Component } from "@angular/core" import { ForesightDirective } from "@foresightjs/angular" @Component({ selector: "app-nav", standalone: true, imports: [ForesightDirective], template: ` `, }) export class NavComponent { readonly prefetchPricing = () => { void fetch("/api/pricing") } } ``` That's it. Unregistration is automatic The directive registers the element when it appears and unregisters it when it is destroyed, so you never have to call `unregister()` yourself. The same applies to [`ForesightComponent`](/docs/angular/foresight-component.md). ## Provide registration options[](#provide-registration-options "Direct link to Provide registration options") If you want more control, pass a full options object instead of just a callback: ``` ``` See [registration options](/docs/angular/configuration/registration-options.md) for the full list. ## Reading prediction state[](#reading-prediction-state "Direct link to Reading prediction state") Export the directive as `foresight` to read its Angular signal state in the template: ``` {{ foresight.state().isPredicted ? "Pricing ready" : "Pricing" }} ``` ## Development Tools[](#development-tools "Direct link to Development Tools") ForesightJS has dedicated [Development Tools](/docs/angular/devtools.md) that help you understand and tune how prediction is working in your application: ``` pnpm add js.foresight-devtools # or npm install js.foresight-devtools # or yarn add js.foresight-devtools ``` ``` import { ForesightDevtools } from "js.foresight-devtools" ForesightDevtools.initialize({ // optional props }) ``` --- # Static Properties The directive and component handle registering and unregistering for you; the properties below are escape hatches for debugging and inspecting the manager state. ``` import { ForesightManager } from "@foresightjs/angular" ``` The ForesightManager exposes static properties and instance APIs for accessing and controlling manager state. ***All properties are read-only*** ## ForesightManager.instance[](#foresightmanagerinstance "Direct link to ForesightManager.instance") Gets the singleton instance of ForesightManager, initializing it if necessary. This is the primary way to access the manager throughout your application. **Returns:** `ForesightManager` **Example:** ``` const manager = ForesightManager.instance // Register a single element manager.register({ element: myButton, callback: () => console.log("Predicted interaction!"), }) // Register multiple elements via NodeList const navLinks = document.querySelectorAll("nav a") manager.register({ element: navLinks, callback: state => console.log(`Predicted: ${state.name}`), }) ``` ## ForesightManager.instance.registeredElements[](#foresightmanagerinstanceregisteredelements "Direct link to ForesightManager.instance.registeredElements") Gets a Map of all currently registered elements and their associated [`ForesightElementState`](/docs/getting-started/typescript.md#foresightelementstate). This is useful for debugging or inspecting the current state of registered elements. **Returns:** `ReadonlyMap{{ hits }} prefetches triggered
``` The standard `ForesightManager.instance.addEventListener` / `removeEventListener` pattern is also available if you want to listen outside of a component. ## Available Events[](#available-events "Direct link to Available Events") ### Interaction Events[](#interaction-events "Direct link to Interaction Events") Events fired when user interactions trigger callbacks. *** #### `callbackInvoked`[](#callbackinvoked "Direct link to callbackinvoked") Fired **before** an element's callback is executed ``` type CallbackInvokedEvent = { type: "callbackInvoked" timestamp: number element: ForesightElement state: ForesightElementState hitType: CallbackHitType } ``` **Related Types:** [`CallbackHitType`](/docs/getting-started/typescript.md#callbackhittype) • [`ForesightElementState`](/docs/getting-started/typescript.md#foresightelementstate) *** #### `callbackCompleted`[](#callbackcompleted "Direct link to 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`](/docs/getting-started/typescript.md#callbackhittype) • [`ForesightElementState`](/docs/getting-started/typescript.md#foresightelementstate) ### Element Lifecycle Events[](#element-lifecycle-events "Direct link to Element Lifecycle Events") Events fired during element registration, updates, and cleanup. *** #### `elementRegistered`[](#elementregistered "Direct link to 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`](/docs/getting-started/typescript.md#foresightelementstate) *** #### `elementUnregistered`[](#elementunregistered "Direct link to 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`](/docs/getting-started/typescript.md#foresightelementstate) *** ### Prediction Events[](#prediction-events "Direct link to Prediction Events") Events fired during movement prediction calculations. *** #### `mouseTrajectoryUpdate`[](#mousetrajectoryupdate "Direct link to mousetrajectoryupdate") Fired during mouse movement for trajectory calculations ``` type MouseTrajectoryUpdateEvent = { type: "mouseTrajectoryUpdate" trajectoryPositions: { positions: CircularBuffer{{ hits }} prefetches triggered
``` You don't need to remove the listener yourself, the composable does it for you when the component is disposed. See [Events](/docs/vue/events.md) for the full list of event names and their payloads. --- # What is ForesightJS [](https://www.npmjs.com/package/js.foresight) [](https://www.npmjs.com/package/js.foresight) [](https://bundlejs.com/?q=js.foresight) [](https://github.com/spaansba/ForesightJS) [](https://bestofjs.org/projects/foresightjs) [](https://foresightjs.com#playground) ForesightJS is a lightweight JavaScript library that predicts user intent to prefetch content before it's needed. It works completely out of the box without configuration, supporting both desktop and mobile devices with different prediction strategies. ## Understanding ForesightJS's Role[](#understanding-foresightjss-role "Direct link to Understanding ForesightJS's Role") When you over simplify prefetching it exists of three parts: * **What** resource or data to load * **How** the loading method and caching strategy is * **When** the optimal moment to start fetching is ForesightJS takes care of the **When** by predicting user intent with mouse trajectory and tab navigation. You supply the **What** and **How** inside your `callback` when you register an element. In Vue you use ForesightJS through the official `@foresightjs/vue` package: the `v-foresight` directive registers your elements, and composables expose their reactive prediction state. ## Installation[](#installation "Direct link to Installation") ``` npm install @foresightjs/vue js.foresight ``` Continue with [Installation](/docs/vue/installation.md) and the [Quick Start](/docs/vue/quick-start.md). ## Prediction Strategies[](#prediction-strategies "Direct link to Prediction Strategies") ForesightJS uses different prediction strategies depending on the device type. For limited connections (slower than the minimum connection type - default: 3G - or [data-saver mode](https://developer.mozilla.org/en-US/docs/Web/API/NetworkInformation/saveData)), we respect the user's preference to minimize data usage: the element is still registered but stays inactive, so it is never predicted and never prefetches. Foresight automatically detects mouse, pen, or touch input, and updates its strategy if the input method changes. ### Keyboard/Mouse Users[](#keyboardmouse-users "Direct link to Keyboard/Mouse Users") Pick and choose multiple prediction strategies. All are enabled by default, but you can disable any of them when initializing the `ForesightManager`. * **Mouse Trajectory** default - Analyzes cursor movement patterns to predict which links users are heading towards and prefetches content before they arrive * **Keyboard Navigation** default - Tracks tab key usage to prefetch when the user is N tab stops away from your registered element * **Scroll** default - Prefetches content when users scroll towards registered elements, predicting which elements will be reached based on scroll direction ### Touch Devices[](#touch-devices "Direct link to Touch Devices") While desktop systems use multiple concurrent prediction strategies, touch devices operate with a single active strategy that can be configured while initializing the `ForesightManager`. * **onTouchStart** default - Captures the initial touch event to begin prefetching when users start interacting with registered elements * **Viewport Enter** - Detects when registered elements enter the viewport and prefetches their content based on scroll behavior and visibility * **None** - Disables ForesightJS on touch devices (previous behavior) ## Why ForesightJS?[](#why-foresightjs "Direct link to Why ForesightJS?") ForesightJS is a specialized performance tool, not something to drop into every project. ### Which problems does ForesightJS solve?[](#which-problems-does-foresightjs-solve "Direct link to Which problems does ForesightJS solve?") #### Problem 1: On-Hover Prefetching Still Has Latency[](#problem-1-on-hover-prefetching-still-has-latency "Direct link to Problem 1: On-Hover Prefetching Still Has Latency") Traditional hover-based prefetching only triggers after the user's cursor reaches an element. This approach wastes the critical 100-200ms window between when a user begins moving toward a target and when the hover event actually fires-time that could be used for prefetching. #### Problem 2: Viewport-Based Prefetching is Wasteful[](#problem-2-viewport-based-prefetching-is-wasteful "Direct link to Problem 2: Viewport-Based Prefetching is Wasteful") Many modern frameworks (like Next.js) automatically prefetch resources for all links that enter the viewport. While well-intentioned, this creates significant overhead since users typically interact with only a small fraction of visible elements. Simply scrolling up and down the Next.js homepage can trigger ***1.59MB*** of unnecessary prefetch requests. #### Problem 3: Hover-Based Prefetching Excludes Keyboard Users[](#problem-3-hover-based-prefetching-excludes-keyboard-users "Direct link to Problem 3: Hover-Based Prefetching Excludes Keyboard Users") Many routers rely on hover-based prefetching, but this approach completely excludes keyboard users since keyboard navigation never triggers hover events. This means keyboard users miss out on the performance benefits that mouse users get from hover-based prefetching. ## Lightweight[](#lightweight "Direct link to Lightweight") The full library is **\~32 KB** minified, and code splitting means you only ship the parts you actually use. See [Behind the Scenes](/docs/Behind_the_Scenes.md#bundle-optimization) for the per-chunk breakdown. ---