@real-router/preload-plugin 0.1.2 → 0.1.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@real-router/preload-plugin",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "type": "commonjs",
   "description": "Preload plugin — trigger data preloading on navigation intent (hover, touch)",
   "main": "./dist/cjs/index.js",
@@ -8,7 +8,6 @@
   "types": "./dist/esm/index.d.mts",
   "exports": {
     ".": {
-      "development": "./src/index.ts",
       "types": {
         "import": "./dist/esm/index.d.mts",
         "require": "./dist/cjs/index.d.ts"
@@ -18,7 +17,8 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "src"
   ],
   "repository": {
     "type": "git",
@@ -44,7 +44,7 @@
   },
   "sideEffects": false,
   "dependencies": {
-    "@real-router/core": "^0.45.1"
+    "@real-router/core": "^0.45.2"
   },
   "devDependencies": {
     "jsdom": "28.1.0"
@@ -54,7 +54,7 @@
     "build": "tsdown --config-loader unrun",
     "type-check": "tsc --noEmit",
     "lint": "eslint --cache --ext .ts src/ tests/ --fix --max-warnings 0",
-    "lint:package": "bash ../../scripts/publint-filter.sh",
+    "lint:package": "publint",
     "lint:types": "attw --pack .",
     "build:dist-only": "tsdown --config-loader unrun"
   }

package/src/constants.ts

@@ -0,0 +1,12 @@
+import type { PreloadPluginOptions } from "./types";
+
+export const defaultOptions: Required<PreloadPluginOptions> = {
+  delay: 65,
+  networkAware: true,
+};
+
+export const GHOST_EVENT_THRESHOLD = 2500;
+
+export const TOUCH_SCROLL_THRESHOLD = 10;
+
+export const TOUCH_PRELOAD_DELAY = 100;

package/src/factory.ts

@@ -0,0 +1,30 @@
+import { getPluginApi } from "@real-router/core/api";
+
+import { defaultOptions } from "./constants";
+import { PreloadPlugin } from "./plugin";
+
+import type { PreloadPluginOptions } from "./types";
+import type { PluginFactory, Router } from "@real-router/core";
+
+export function preloadPluginFactory(
+  opts?: Partial<PreloadPluginOptions>,
+): PluginFactory {
+  const options: Required<PreloadPluginOptions> = {
+    ...defaultOptions,
+    ...opts,
+  };
+
+  return function preloadPlugin(routerBase) {
+    if (typeof document === "undefined") {
+      return {};
+    }
+
+    const plugin = new PreloadPlugin(
+      routerBase as Router,
+      getPluginApi(routerBase),
+      options,
+    );
+
+    return plugin.getPlugin();
+  };
+}

package/src/index.ts

@@ -0,0 +1,17 @@
+/* eslint-disable @typescript-eslint/method-signature-style -- method syntax required for declaration merging overload (property syntax causes TS2717) */
+import type { PreloadPluginOptions } from "./types";
+import type { Params } from "@real-router/core";
+
+export { preloadPluginFactory } from "./factory";
+
+export type { PreloadPluginOptions } from "./types";
+
+declare module "@real-router/core" {
+  interface Route {
+    preload?: (params: Params) => Promise<unknown>;
+  }
+
+  interface Router {
+    getPreloadSettings(): PreloadPluginOptions;
+  }
+}

package/src/network.ts

@@ -0,0 +1,23 @@
+type NetworkConnection =
+  | { saveData?: boolean; effectiveType?: string }
+  | undefined;
+
+interface NavigatorWithConnection extends Navigator {
+  connection?: NetworkConnection;
+}
+
+export function isSlowConnection(): boolean {
+  const connection = (navigator as NavigatorWithConnection).connection;
+
+  if (!connection) {
+    return false;
+  }
+  if (connection.saveData) {
+    return true;
+  }
+  if (connection.effectiveType?.includes("2g")) {
+    return true;
+  }
+
+  return false;
+}

package/src/plugin.ts

@@ -0,0 +1,227 @@
+import {
+  GHOST_EVENT_THRESHOLD,
+  TOUCH_PRELOAD_DELAY,
+  TOUCH_SCROLL_THRESHOLD,
+} from "./constants";
+import { isSlowConnection } from "./network";
+
+import type { PreloadPluginOptions } from "./types";
+import type { Params, Plugin, Router, State } from "@real-router/core";
+import type { PluginApi } from "@real-router/core/api";
+
+declare module "@real-router/core" {
+  interface Router {
+    matchUrl?: (url: string) => State | undefined;
+  }
+}
+
+export class PreloadPlugin {
+  readonly #router: Router;
+  readonly #api: PluginApi;
+  readonly #options: Required<PreloadPluginOptions>;
+  readonly #removeExtensions: () => void;
+
+  #currentAnchor: HTMLAnchorElement | null = null;
+  #hoverTimer: ReturnType<typeof setTimeout> | null = null;
+  #touchTimer: ReturnType<typeof setTimeout> | null = null;
+  #touchStartY = 0;
+  #lastTouchStartEvent: {
+    target: EventTarget | null;
+    timeStamp: number;
+  } | null = null;
+
+  constructor(
+    router: Router,
+    api: PluginApi,
+    options: Required<PreloadPluginOptions>,
+  ) {
+    this.#router = router;
+    this.#api = api;
+    this.#options = options;
+
+    this.#removeExtensions = api.extendRouter({
+      getPreloadSettings: () => ({ ...options }),
+    });
+  }
+
+  getPlugin(): Plugin {
+    return {
+      onStart: () => {
+        document.addEventListener("mouseover", this.#handleMouseOver, {
+          capture: true,
+          passive: true,
+        });
+        document.addEventListener("touchstart", this.#handleTouchStart, {
+          capture: true,
+          passive: true,
+        });
+        document.addEventListener("touchmove", this.#handleTouchMove, {
+          capture: true,
+          passive: true,
+        });
+      },
+
+      onStop: () => {
+        this.#cleanup();
+      },
+
+      teardown: () => {
+        this.#cleanup();
+        this.#removeExtensions();
+      },
+    };
+  }
+
+  readonly #handleMouseOver = (event: MouseEvent): void => {
+    if (this.#isGhostMouseEvent(event)) {
+      return;
+    }
+
+    const target = event.target as Element | null;
+
+    if (!target || !("closest" in target)) {
+      this.#cancelHover();
+
+      return;
+    }
+
+    const anchor = target.closest<HTMLAnchorElement>("a[href]");
+
+    if (anchor === this.#currentAnchor) {
+      return;
+    }
+
+    this.#cancelHover();
+    this.#currentAnchor = anchor;
+
+    const preload = this.#resolveAnchorPreload(anchor);
+
+    if (!preload) {
+      return;
+    }
+
+    this.#hoverTimer = setTimeout(() => {
+      this.#hoverTimer = null;
+      preload.fn(preload.params).catch(() => {});
+    }, this.#options.delay);
+  };
+
+  readonly #handleTouchStart = (event: TouchEvent): void => {
+    this.#lastTouchStartEvent = {
+      target: event.target,
+      timeStamp: event.timeStamp,
+    };
+
+    this.#cancelTouch();
+
+    const target = event.target as Element | null;
+    const anchor =
+      target && "closest" in target
+        ? target.closest<HTMLAnchorElement>("a[href]")
+        : null;
+    const preload = this.#resolveAnchorPreload(anchor);
+
+    if (!preload) {
+      return;
+    }
+
+    this.#touchStartY = event.touches[0].clientY;
+
+    this.#touchTimer = setTimeout(() => {
+      this.#touchTimer = null;
+      preload.fn(preload.params).catch(() => {});
+    }, TOUCH_PRELOAD_DELAY);
+  };
+
+  readonly #handleTouchMove = (event: TouchEvent): void => {
+    if (this.#touchTimer === null) {
+      return;
+    }
+
+    const deltaY = Math.abs(event.touches[0].clientY - this.#touchStartY);
+
+    if (deltaY > TOUCH_SCROLL_THRESHOLD) {
+      this.#cancelTouch();
+    }
+  };
+
+  #resolveAnchorPreload(
+    anchor: HTMLAnchorElement | null | undefined,
+  ): { fn: (params: Params) => Promise<unknown>; params: Params } | undefined {
+    if (!anchor) {
+      return undefined;
+    }
+
+    if ("noPreload" in anchor.dataset) {
+      return undefined;
+    }
+
+    if (this.#options.networkAware && isSlowConnection()) {
+      return undefined;
+    }
+
+    return this.#resolvePreload(anchor);
+  }
+
+  #resolvePreload(
+    anchor: HTMLAnchorElement,
+  ): { fn: (params: Params) => Promise<unknown>; params: Params } | undefined {
+    const state = this.#router.matchUrl?.(anchor.href);
+
+    if (!state) {
+      return undefined;
+    }
+
+    const config = this.#api.getRouteConfig(state.name);
+
+    if (typeof config?.preload !== "function") {
+      return undefined;
+    }
+
+    return {
+      fn: config.preload as (params: Params) => Promise<unknown>,
+      params: state.params,
+    };
+  }
+
+  #isGhostMouseEvent(event: MouseEvent): boolean {
+    return (
+      this.#lastTouchStartEvent !== null &&
+      event.target === this.#lastTouchStartEvent.target &&
+      event.timeStamp - this.#lastTouchStartEvent.timeStamp <
+        GHOST_EVENT_THRESHOLD
+    );
+  }
+
+  #cancelHover(): void {
+    if (this.#hoverTimer !== null) {
+      clearTimeout(this.#hoverTimer);
+      this.#hoverTimer = null;
+    }
+
+    this.#currentAnchor = null;
+  }
+
+  #cancelTouch(): void {
+    if (this.#touchTimer !== null) {
+      clearTimeout(this.#touchTimer);
+      this.#touchTimer = null;
+    }
+  }
+
+  #cleanup(): void {
+    document.removeEventListener("mouseover", this.#handleMouseOver, {
+      capture: true,
+    });
+    document.removeEventListener("touchstart", this.#handleTouchStart, {
+      capture: true,
+    });
+    document.removeEventListener("touchmove", this.#handleTouchMove, {
+      capture: true,
+    });
+
+    this.#cancelHover();
+    this.#cancelTouch();
+    this.#lastTouchStartEvent = null;
+  }
+}

package/src/types.ts

@@ -0,0 +1,6 @@
+export interface PreloadPluginOptions {
+  /** Hover debounce delay in ms. @default 65 */
+  delay?: number;
+  /** Check saveData/2g and disable preloading on slow connections. @default true */
+  networkAware?: boolean;
+}