Improve speculation rules handling based on element visibility (#446)

* added logic to add and remove speculation in viewport

* Removal of unnecessary checks to save space

* added condition for unobserver if it is not prerender immediate

* fix immediate condition on unobserver call

* Update src/prerender.mjs

Changed "urlsToPrerender" property type on JSDoc

Co-authored-by: Weston Ruter <[email protected]>

* Update src/prerender.mjs

Error return type object

Co-authored-by: Weston Ruter <[email protected]>

* Update src/index.mjs

const variable specRulesInViewport

Co-authored-by: Weston Ruter <[email protected]>

* Update README.md

Added functionality to the listen({ prerender: true }) method to allow prerendering only of content within the viewport, and introduced the eagerness property to the prerender method.

* Update README.md

Co-authored-by: Weston Ruter <[email protected]>

* Update src/prerender.mjs

Co-authored-by: Weston Ruter <[email protected]>

* Update src/prerender.mjs

Co-authored-by: Weston Ruter <[email protected]>

* Update src/index.mjs

Co-authored-by: Weston Ruter <[email protected]>

* Update README.md

Co-authored-by: Weston Ruter <[email protected]>

* Update README.md

Co-authored-by: Weston Ruter <[email protected]>

---------

Co-authored-by: XhmikosR <[email protected]>
Co-authored-by: Weston Ruter <[email protected]>

Author: 3 people

README.md

@@ -126,6 +126,14 @@ A "reset" function is returned, which will empty the active `IntersectionObserve
 Whether to switch from the default prefetching mode to the prerendering mode for the links inside the viewport.
 
 > **Note:** The prerendering mode (when this option is set to true) will fallback to the prefetching mode if the browser does not support prerender.
+> Once the element exits the viewport, the `speculationrules` script is removed from the DOM. This approach makes it possible to exceed the limit of 10 prerenders imposed for the 'immediate' and 'eager' settings for eagerness.
+
+#### options.eagerness
+
+- Type: `String`
+- Default: `immediate`
+
+Determines the mode to be used for prerendering specified within the speculation rules.
 
 #### options.prerenderAndPrefetch
 
@@ -266,7 +274,7 @@ By default, calls to `prefetch()` are low priority.
 
 > **Note:** This behaves identically to `listen()`'s `priority` option.
 
-### quicklink.prerender(urls)
+### quicklink.prerender(urls, eagerness)
 
 Returns: `Promise`
 
@@ -281,6 +289,13 @@ One or many URLs to be prerendered.
 
 > **Note:** Speculative Rules API supports same-site cross origin Prerendering with [opt-in header](https://bit.ly/ss-cross-origin-pre).
 
+#### eagerness
+
+- Type: `String`
+- Default: `immediate`
+
+Determines the mode to be used for prerendering specified within the speculation rules.
+
 ## Polyfills
 
 `quicklink`:

src/index.mjs

@@ -17,7 +17,7 @@
 import throttle from 'throttles';
 import {prefetchOnHover, supported, viaFetch} from './prefetch.mjs';
 import requestIdleCallback from './request-idle-callback.mjs';
-import {addSpeculationRules, hasSpecRulesSupport} from './prerender.mjs';
+import {addSpeculationRules, removeSpeculationRule, hasSpecRulesSupport} from './prerender.mjs';
 
 // Cache of URLs we've prefetched
 // Its `size` is compared against `opts.limit` value.
@@ -102,6 +102,7 @@ export function listen(options = {}) {
   const ignores = options.ignores || [];
   const delay = options.delay || 0;
   const hrefsInViewport = [];
+  const specRulesInViewport = new Map();
 
   const timeoutFn = options.timeoutFn || requestIdleCallback;
   const hrefFn = typeof options.hrefFn === 'function' && options.hrefFn;
@@ -131,19 +132,28 @@ export function listen(options = {}) {
           // Do not prefetch if not found in viewport
           if (!hrefsInViewport.includes(entry.href)) return;
 
-          observer.unobserve(entry);
+          if (!shouldOnlyPrerender && !shouldPrerenderAndPrefetch) {
+            observer.unobserve(entry);
+          }
 
           // prerender, if..
           // either it's the prerender + prefetch mode or it's prerender *only* mode
           // Prerendering limit is following options.limit. UA may impose arbitraty numeric limit
-          if ((shouldPrerenderAndPrefetch || shouldOnlyPrerender) && toPrerender.size < limit) {
-            prerender(hrefFn ? hrefFn(entry) : entry.href, options.eagerness).catch(error => {
-              if (options.onError) {
-                options.onError(error);
-              } else {
-                throw error;
-              }
-            });
+          // The same URL is not already present as a speculation rule
+          if ((shouldPrerenderAndPrefetch || shouldOnlyPrerender) && toPrerender.size < limit && !specRulesInViewport.has(entry.href)) {
+            prerender(hrefFn ? hrefFn(entry) : entry.href, options.eagerness)
+                .then(specMap => {
+                  for (const [key, value] of specMap) {
+                    specRulesInViewport.set(key, value);
+                  }
+                })
+                .catch(error => {
+                  if (options.onError) {
+                    options.onError(error);
+                  } else {
+                    throw error;
+                  }
+                });
 
             return;
           }
@@ -168,6 +178,9 @@ export function listen(options = {}) {
         if (index > -1) {
           hrefsInViewport.splice(index);
         }
+        if (specRulesInViewport.has(entry.href)) {
+          specRulesInViewport = removeSpeculationRule(specRulesInViewport, entry.href);
+        }
       }
     });
   }, {
@@ -245,6 +258,8 @@ export function prefetch(urls, isPriority, checkAccessControlAllowOrigin, checkA
 * @return {Object} a Promise
 */
 export function prerender(urls, eagerness = 'immediate') {
+  urls = [].concat(urls);
+
   const chkConn = checkConnection(navigator.connection);
   if (chkConn instanceof Error) {
     return Promise.reject(new Error(`Cannot prerender, ${chkConn.message}`));
@@ -258,7 +273,7 @@ export function prerender(urls, eagerness = 'immediate') {
     return Promise.reject(new Error('This browser does not support the speculation rules API. Falling back to prefetch.'));
   }
 
-  for (const url of [].concat(urls)) {
+  for (const url of urls) {
     toPrerender.add(url);
   }
 
@@ -267,6 +282,6 @@ export function prerender(urls, eagerness = 'immediate') {
     console.warn('[Warning] You are using both prefetching and prerendering on the same document');
   }
 
-  const addSpecRules = addSpeculationRules(toPrerender, eagerness);
-  return addSpecRules === true ? Promise.resolve() : Promise.reject(addSpecRules);
+  const specMap = addSpeculationRules(urls, eagerness);
+  return specMap.size > 0 ? Promise.resolve(specMap) : Promise.reject(specMap);
 }

src/prerender.mjs

@@ -19,23 +19,52 @@
 
 /**
  * Add a given set of urls to the speculation rules
- * @param {Set} urlsToPrerender - the URLs to add to speculation rules
+ * @param {String[]} urlsToPrerender - the URLs to add to speculation rules
  * @param {String} eagerness - prerender eagerness mode
- * @return {Boolean|Object}  boolean or Error Object
+ * @return {Map<HTMLScriptElement, string>|Error}  Map of script elements to their URLs or Error Object
  */
 export function addSpeculationRules(urlsToPrerender, eagerness) {
-  const specScript = document.createElement('script');
-  specScript.type = 'speculationrules';
-  specScript.text = `{"prerender":[{"source": "list",
-                      "urls": ["${Array.from(urlsToPrerender).join('","')}"],
-                      "eagerness": "${eagerness}"}]}`;
+  const specMap = new Map();
+
+  try {
+    for (const url of urlsToPrerender) {
+      const specScript = document.createElement('script');
+      specScript.type = 'speculationrules';
+      specScript.text = JSON.stringify({
+        prerender: [{
+          source: 'list',
+          urls: [url],
+          eagerness,
+        }],
+      });
+
+      document.head.appendChild(specScript);
+      specMap.set(url, specScript);
+    }
+  } catch (error) {
+    return error;
+  }
+
+  return specMap;
+}
+
+/**
+ * Removes a speculation rule script associated with a given URL
+ * @param {Map<string, HTMLScriptElement>} specMap - Map of URLs to their script elements
+ * @param {string} url - The URL whose speculation rule should be removed
+ * @return {Map<string, HTMLScriptElement>|Error} The updated map after removal or Error Object
+ */
+export function removeSpeculationRule(specMap, url) {
+  const specScript = specMap.get(url);
+
   try {
-    document.head.appendChild(specScript);
+    specScript.remove();
+    specMap.delete(url);
   } catch (error) {
     return error;
   }
 
-  return true;
+  return specMap;
 }
 
 /**