From 28f372e989d4b2056f38d375bcfd93fc5e9ec248 Mon Sep 17 00:00:00 2001 From: Luke Edwards Date: Sun, 8 Sep 2019 15:24:47 -0700 Subject: [PATCH] docs: format API docs differently --- README.md | 121 ++++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 104 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index c75742fc..182ab96a 100644 --- a/README.md +++ b/README.md @@ -72,26 +72,110 @@ The above options are best for multi-page sites. Single-page apps have a few opt ## API -The `quicklink.listen` method accepts an optional options object with the following parameters: +### quicklink.listen(options) +Returns: `Function` -* `el`: DOM element to observe for in-viewport links to prefetch -* `urls`: Static array of URLs to prefetch (instead of observing `document` or a DOM element links in the viewport) -* `limit`: An integer representing the _total_ requests that can be prefetched. Defaults to `Infinity` -* `throttle`: An integer representing the _concurrency limit_ for simultaneous requests. Defaults to `Infinity` -* `timeout`: Integer for the `requestIdleCallback` timeout. A time in milliseconds by which the browser must execute prefetching. Defaults to 2 seconds. -* `timeoutFn`: Function for specifying a timeout. Defaults to `requestIdleCallback`. Can also be swapped out for a custom function like [networkIdleCallback](https://github.com/pastelsky/network-idle-callback) (see demos) -* `priority`: Boolean specifying preferred priority for fetches. Defaults to `false`. `true` will attempt to use the `fetch()` API where supported (rather than rel=prefetch) -* `origins`: Static array of URL hostname strings that are allowed to be prefetched. Defaults to the same domain origin, which prevents _any_ cross-origin requests. -* `ignores`: A RegExp, Function, or Array that further determines if a URL should be prefetched. These execute _after_ origin matching. -* `onError`: An optional Function that will handle errors from prefetched requests. By default, these errors are silently ignored +A "reset" function is returned, which will empty the active `IntersectionObserver` and the cache of URLs that have already been prefetched. This can be used between page navigations and/or when significant DOM changes have occurred. -The `quicklink.prefetch` method accepts one or more URL strings and an `isPriority` toggle.
-A `Promise` is returned that always resolves to an array of results (if desired) and requires that you `catch` your own reuest error(s). +#### options.el +Type: `HTMLElement`
+Default: `document.body` -> **Note:** Calls to `prefetch` are "low-priority" by default. This behaves identically to `listen()`'s `priority` option. +The DOM element to observe for in-viewport links to prefetch. +#### options.limit +Type: `Number`
+Default: `Infinity` + +The _total_ requests that can be prefetched while observing the `options.el` container. + +#### options.throttle +Type: `Number`
+Default: `Infinity` + +The _concurrency limit_ for simultaneous requests while observing the `options.el` container. + +#### options.timeout +Type: `Number`
+Default: `2000` + +The `requestIdleCallback` timeout, in milliseconds. + +> **Note:** The browser must be idle for the configured duration before prefetching. + +#### options.timeoutFn +Type: `Function`
+Default: `requestIdleCallback` + +A function used for specifying a `timeout` delay.
+This can be swapped out for a custom function like [networkIdleCallback](https://github.com/pastelsky/network-idle-callback) (see demos). + +By default, this uses [`requestIdleCallback`](https://developer.mozilla.org/en-US/docs/Web/API/Window/requestIdleCallback) or the embedded polyfill. + +#### options.priority +Type: `Boolean`
+Default: `false` + +Whether or not the URLs within the `options.el` container should be treated as high priority. + +When `true`, quicklink will attempt to use the `fetch()` API if supported (rather than `link[rel=prefetch]`). + +#### options.origins +Type: `Array`
+Default: `[location.hostname]` + +A static array of URL hostnames that are allowed to be prefetched.
+Defaults to the same domain origin, which prevents _any_ cross-origin requests. + +**Important:** An empty array (`[]`) allows ***all origins*** to be prefetched. + +#### options.ignores +Type: `RegExp` or `Function` or `Array`
+Default: `[]` + +Determine if a URL should be prefetched. + +When a `RegExp` tests positive, a `Function` returns `true`, or an `Array` contains the string, then the URL is _not_ prefetched. + +> **Note:** An `Array` may contain `String`, `RegExp`, or `Function` values. + +> **Important:** This logic is executed _after_ origin matching! + +#### options.onError +Type: `Function`
+Default: None + +An optional error handler that will receive any errors from prefetched requests.
+By default, these errors are silently ignored. + + +### quicklink.prefetch(urls, isPriority) +Returns: `Promise` + +The `urls` provided are always passed through `Promise.all`, which means the result will always resolve to an Array. + +> **Important:** You much `catch` you own request error(s). + +#### urls +Type: `String` or `Array`
+Required: `true` + +One or many URLs to be prefetched. + +> **Note:** Each `url` value is resolved from the current location. + +#### isPriority +Type: `Boolean`
+Default: `false` + +Whether or not the URL(s) should be treated as "high priority" targets.
+By default, calls to `prefetch()` are low priority. + +> **Note:** This behaves identically to `listen()`'s `priority` option. + + +## TODO -TODO: * Explore detecting file-extension of resources and using [rel=preload](https://w3c.github.io/preload/) for high priority fetches * Explore using [Priority Hints](https://github.com/WICG/priority-hints) for importance hinting @@ -225,7 +309,7 @@ quicklink.listen({ }); ``` -## Browser support +## Browser Support The prefetching provided by `quicklink` can be viewed as a [progressive enhancement](https://www.smashingmagazine.com/2009/04/progressive-enhancement-what-it-is-and-how-to-use-it/). Cross-browser support is as follows: @@ -240,7 +324,10 @@ Certain features have layered support: ## Using the prefetcher directly -`quicklink` includes a prefetcher that can be individually imported for use in other projects. After installing `quicklink` as a dependency, you can use it as follows: +A `prefetch` method can be individually imported for use in other projects.
+This method includes the logic to respect Data Saver and 2G connections. It also issues requests thru `fetch()`, XHRs, or `link[rel=prefetch]` depending on (a) the `isPriority` value and (b) the current browser's support. + +After installing `quicklink` as a dependency, you can use it as follows: ```html