feat: add flexible filter option;

- accepts RegExp, Function, or Array of either
- 776 gz / 648 br

Author: lukeed

src/index.mjs

@@ -38,6 +38,21 @@ function prefetcher(url) {
   prefetch(new URL(url, location.href).toString(), observer.priority);
 }
 
+/**
+ * Determine if the anchor tag can be prefetched.
+ * A filter can be a RegExp, Function, or Array of both.
+ *   - Function receives `node.href, node` arguments
+ *   - RegExp receives `node.href` only (the full URL)
+ * @param  {Element}  node    The anchor (<a>) tag.
+ * @param  {Mixed}    filter  The custom filter(s)
+ * @return {Boolean}          If true, then it was allowed.
+ */
+function isAllowed(node, filter) {
+  return Array.isArray(filter)
+    ? filter.every(x => isAllowed(node, x))
+    : (filter.test || filter)(node.href, node);
+}
+
 /**
  * Prefetch an array of URLs if the user's effective
  * connection type and data-saver preferences suggests
@@ -49,6 +64,7 @@ function prefetcher(url) {
  * @param {Object} options.el - DOM element to prefetch in-viewport links of
  * @param {Boolean} options.priority - Attempt higher priority fetch (low or high)
  * @param {Array} options.origins - Allowed origins to prefetch (empty allows all)
+ * @param {Array|RegExp|Function} options.filter - Custom filter(s) that run after origin checks
  * @param {Number} options.timeout - Timeout after which prefetching will occur
  * @param {Function} options.timeoutFn - Custom timeout function
  */
@@ -63,6 +79,7 @@ export default function (options) {
   observer.priority = options.priority;
 
   const allowed = options.origins || [location.hostname];
+  const filter = options.filter;
 
   options.timeoutFn(() => {
     // If URLs are given, prefetch them.
@@ -73,9 +90,10 @@ export default function (options) {
       Array.from(options.el.querySelectorAll('a'), link => {
         observer.observe(link);
         // If the anchor matches a permitted origin
-        // ~> An empty list means everything is allowed
+        // ~> A `[]` or `true` means everything is allowed
         if (!allowed.length || allowed.includes(link.hostname)) {
-          toPrefetch.add(link.href);
+          // If there are any filters, they must also return true
+          if (!filter || isAllowed(link, filter)) toPrefetch.add(link.href);
         }
       });
     }