ts-service-worker 1.0.31 → 1.0.33

package/README.md

@@ -1,23 +1,21 @@
+## Goals
 
-
-## Why
-
-Service workers are a powerful tool for developers to improve the user experience, providing for fine-grained caching, offline usage and progressive web apps (PWAs). It replaced the coarse-grained _AppCache_, which proved quite hard to effectively use. 
-
-Unfortunately, the service worker API is so low-level it can be hard to use. It requires series of nested promise chains, and quickly grows complicated. In the documentation there are good examples describing single specific strategies. While these are readable, they are minimally useful because real-world usage requires integrating several of these strategies at the same time. This can be error-prone and hard to follow. And as anyone who has developed service workers knows, they are tedious to test because of their more complex lifecycle.
-
-And since service workers run in the browser, they must be written in the browser's version Javascript. If this likely involves transpilation, which will requiring additional complexity in the build process to produce a separate artifact.
-
-There are a [other libraries](#other-libraries) designed to help, which may be useful to you. **TS-Service-worker** aims to solve specific challenges. It:
-
-- is written in Typescript and fully typed
-- avoids nesting and promise chains
-- has a declarative API to _describe_ your webapp caching
+- provide declarative support for the most common caching strategies
 - supports easy integration of multiple caching strategies
-- build a compatible service-worker.js that requires no additional transpilation
+- produces a `service-worker.js` that requires no additional transpilation
+- avoids nesting and promise chains
+- is written in Typescript and fully typed
 - can scan your disk for resources to cache
 - provides built-in debug logging
-- provides simple a simple cache clearing rule
+- provides clear and simple cache purging rules
+
+Copyright (c) 2023 Andrew J. Peterson, dba NDP Software 
+
+#### NOTICE
+This is in testing... It works on two very different projects. I'd love people to try it out and provide feedback.
+
+## Overview
+The idea is simple. You provide TS-Service-Worker with a **Plan** (and options), and it outputs a functional Javascript file that can be sent to the browser. The **Plan** is a series of caching strategies to be applied, along with the paths they should be applied to.
 
 ## Examples
 
@@ -26,22 +24,22 @@ The very simplest service worker might provide an offline backup of the whole si
 import {requestHandler, Origin} from "ts-service-worker";
 
 export const plan: Plan = [
-  {paths: Origin, strategy: "networkFirst"} 
+  {paths: Origin, strategy: "networkFirst"} // don't do this!
 ]
 app.get('/service-worker.js', requestHandler(plan))
 ```
-This plan says, "intercept all the requests from the origin and below (usually everything under `/`), and serve if from the network if available, otherwise, serve from the cache." This is just one of the example caching strategies, and demonstrates:
+This plan says, "intercept all the requests from the root of the site and below (everything under `/`), and serve them from the network if available; otherwise, serve from the cache." This is just one of the example caching strategies, and demonstrates:
 
--  declarative configuration
+- declarative configuration
 - conveniences like `Origin` that make doing simple things simple
-- how a simple caching strategy is insufficent.
+- how a simple caching strategy is insufficent. (shrug)
 
 Some of the deficiences of this strategy:
 - it only caches paths that have been visited
 - provides no way to update cached files
 - caches everything fetched, even unimportant resources
 
-A real caching plan requires more nuance. Here's a slightly more realistic plan:
+A real caching plan requires more nuance. Here is part of a slightly more realistic plan:
 ```ts
 export const plan: Plan = 
   [
@@ -50,10 +48,10 @@ export const plan: Plan =
     {strategy: 'staticOfflineBackup', [/.*\.html/], backup: '/networkDown.html'}
   ]
 ```
-Here, we see multiple strategies in action. Each request is evaluated (sequentially) against the paths, and the first matching strategy is applied. 
+Here, we see multiple strategies in action. Each request is evaluated (sequentially) against the paths, and the first matching strategy is applied. (If not strategy matches, the resource is fetched as normal.)
   - The path `open-search.xml` will never be cached, 
   - `/my-data.json` will be served from the cache and re-fetched in the background, available for a later access. 
-  - Finally, the file `/networkDown.html` will be cached, and served as a replacement for other HTML pages when the network is down.
+  - Finally, the file `/networkDown.html` will be cached, and served as a replacement for other HTML pages when fetching fails.
 
 Another common strategy is to pre-cache some resources on disk. These can be explicitly listed, or dynamically determined from glob matches of files on disk:
 ```ts
@@ -62,19 +60,16 @@ Another common strategy is to pre-cache some resources on disk. These can be exp
     files: { glob: '*.png', dir: 'src/assets/images', prefix: '/img'}
   }
 ```
-These are just some examples. Each app is different and requires careful consideration and crafting. **TS-service-worker** makes developing a custom caching service worker easy and error-free.
+These are just some examples. Each app is different and requires careful consideration and crafting. **TS-Service-Worker** makes developing a custom caching service worker easy and error-free.
 
 ## Usage
 
-There are a few ways to use this:
+After npm installing, there are a few ways to use this:
 
-### CLI
+### Within Express
 
-1. Create a `service-worker.ts` file that exports a `plan` variable
-2. Run `> ts-sw service-worker.ts`
-3. Serve the resultant file as your service worker, editing the Typescript file and regenerating as needed.
+Using directly within Express (or equivalent) will be the most convenient and provides the best Typescript type hints:
 
-### Within Express
 ```ts
 import { requestHandler } from 'ts-service-worker'
 app.get('/service-worker.js', requestHandler([
@@ -82,84 +77,65 @@ app.get('/service-worker.js', requestHandler([
   ]))
 })
 ```
+
+### CLI
+
+The CLI will generate the Javascript file from the specifications in a JSON file. This is nice because it's declarative, but lacks the typing of a Typescript solution.
+
+1. Create a `sw-plan.json` file with `plan` and `options`. See below for available properties.
+2. Run `> npx ts-service-worker sw-plan.json >dist/service-worker.js`
+3. Serve the resultant file (`dist/service-worker.js`) as your service worker, and reference it in your HTML head.
+4. Editing the JSON file and regenerate as needed.
+
 ### Other
 There are other ways to incorporate this into your build cycle. The library exposes a method `generateServiceWorker` which accepts a plan and options and generates the necessary Javascript (text). Let me know how you do it! 
 
-Note that the output of this tool needs no post-processing, so it's best to avoid these tools for the service worker if possible. If the code output isn't compatible, let me know and I'll fix it right away.
+Note that the output of this tool needs _no_ post-processing, so it's best to avoid these tools for the service worker if possible. If the code output isn't compatible, let me know and I'll fix it right away.
 
-## Options
+### Options
 
-The following may be provided as options, and they effect the generation of the Javascript code:
+The following may be provided as options for any usage method, and they effect the generation of the Javascript code:
 
-* version – semantic version of the worker. Major version bump means to reset the cache.
-* skipWaiting – executes the normal skip waiting logic, and allows your service worker to come into play without all the browser windows being closed.
-* debug – outputs log messages as files are fetched. This is too noise for production, but may be useful to figure out what is going on with your service worker.
+* `version` – semantic version of the worker. Major version bump means to reset the cache.
+* `skipWaiting` – executes the normal skip waiting logic, and allows your service worker to come into play without all the browser windows being closed.
+* `debug` – outputs log messages as files are fetched. This is too noise for production, but may be useful to figure out what is going on with your service worker.
 
 ## Paths
 
-Paths can be:
+Paths expressions will match URLs requested from your website, and must be included in each strategy of a plan. The path property can be:
 - a string URL path. This is intepreted as the meaning the URL must END with this pattern
 - a RegExp, matching the full URL
-- an array of strings or RegExp
+- an array of strings or RegExp, following the rules above
 - the symbol `Symbol.for('origin')`, which matches everything under the service worker's domain.
 - the symbol `Symbol.for('scope')`, which matches everything under the service worker's scope, which is the level that a service worker is installed at.
 
 ## Strategies
 
-**ts-service-worker**
-
-### cache-on-install
-
-Tell it paths to cache when the service worker activates.
-
-Also, it can scan directories from resources. This is optional, but for some use cases you will have a whole directory of files you want to pre-cache. Use normal glob patterns to identify these as shown below. 
-```ts
-plan: Plan = [
-  {
-    files: {
-      glob: '**/*.png',
-      dir: 'src/images',
-      prefix: '/assets'
-    },
-    strategy: 'cache on install'
-  }
-]
-```
-The globs are evaluated with the `service-worker.js` file is created, so updating resources will require rebuilding the file.
-
 ### cacheFirst
 
-Ideal for: CSS, images, fonts, JS, templates… basically anything you'd consider static to that "version" of your site.
+This strategy is ideal for CSS, images, fonts, JS, templates… basically anything you'd consider static to that "version" of your site. Per [https://web.dev/learn/pwa/serving/#cache-first]:
 >> Using this strategy, the service worker looks for the matching request in the cache and returns the corresponding Response if it's cached. Otherwise it retrieves the response from the network (~~optionally,~~ updating the cache for future calls). If there is neither a cache response nor a network response, the request will error. Since serving assets without going to the network tends to be faster, this strategy prioritizes performance over freshness.
 
 There is no way to remove files from the cache. For this reason, use only for immutable resources (certain images and fingerprinted assets). If these do need to be updated, you will need to [rebuild the cache (see below)](#Rebuild Cache).
 
-See [https://web.dev/learn/pwa/serving/#cache-first].
-
-
 ### networkFirst
-
-This is most useful to provide the user with a backup in case the network isn't available.
+This is most useful to provide the user with a backup in case the network isn't available. Per [https://web.dev/learn/pwa/serving/#network-first]:
 
 > This strategy is the mirror of the Cache First strategy; it checks if the request can be fulfilled from the network and, if it can't, tries to retrieve it from the cache. If there is neither a network response nor a cache response, the request will error. Getting the response from the network is usually slower than getting it from the cache, this strategy prioritizes updated content instead of performance.
 
-See [https://web.dev/learn/pwa/serving/#network-first].
-
 ### staleWhileRevalidate
 
-This is useful for resources that could be slow to fetch but where freshness is not critical.
+This is useful for resources that could be slow to fetch and whose freshness is not critical. Per [https://web.dev/learn/pwa/serving/#stale-while-revalidate]:
 
 > The stale while revalidate strategy returns a cached response immediately, then checks the network for an update, replacing the cached response if one is found. This strategy always makes a network request, because even if a cached resource is found, it will try to update what was in the cache with what was received from the network, to use the updated version in the next request. This strategy, therefore, provides a way for you to benefit from the quick serving of the cache first strategy and update the cache in the background.
 
 > With this strategy, the assets are updated in the background. This means your users won't get the new version of the assets until the next time that path is requested. At that time the strategy will again check if a new version exists and the cycle repeats.
 
-See https://web.dev/learn/pwa/serving/#stale-while-revalidate
-
 ### networkOnly
 
+Per [https://web.dev/learn/pwa/serving/#network-only]:
+
 > The network only strategy is similar to how browsers behave without a service worker or the Cache Storage API. Requests will only return a resource if it can be fetched from the network. This is often useful for resources like online-only API requests.
-> 
-See https://web.dev/learn/pwa/serving/#network-only
 
 ### staticOfflineBackup
 
@@ -169,53 +145,70 @@ The backup resource is loaded on service worker installation and served as neede
 
 Note: this currently doesn't support inline SVGs that you see in some examples, but requires using a separate file.
 
-Note: this does **not** serve the "backup" file from cache by default. If you want to do that, use another strategy in combination. This likely is `networkFirst`, but it's up to you.
+Note: this does **not** serve the "backup" file from cache by default. If you want to do that, use another strategy like `networkFirst` in combination. 
 
+### cache-on-install
 
-## Rebuild Cache
+Cache specific paths when the service worker installs. Because it needs to know specific resources, path matching wildcards and regular expression will not work. But this strategy has an extra feature that other strategies do not:  it can scan directories for resources. In some cases this, when you have a whole directory of files to pre-cache, this will be the least maintenance. Use normal glob patterns to identify these as shown below. Here's one example:
 
-The browsers will manage the cache, removing items if it becomes too larger.
+```ts
+plan: Plan = [
+  {
+    files: {
+      glob: '**/*.png',
+      dir: 'src/images',  // where to start searching
+      prefix: '/assets'   // prefix applied to any matches
+    },
+    strategy: 'cache on install'
+  }
+]
+```
+The globs are evaluated when the `service-worker.js` file is created, so updating resources will require rebuilding the service worker file.
+
+## Cache and Versioning of Service Workers
+
+When developing service workers, it can take a while to learn service worker behavior, understanding when it re-installs service workers and rebuilds caches. This is worth understanding, but **TS-Service-Worker** tries the appropriate controls.
+
+#### Clearing the Cache
+There are two components that relevant here:
 
-Most of the strategies will replace older assets with newer ones when found.
+- the service worker
+- the cache (of responses)
 
-If you _need_ to reset the cache, simply increment the version number. A major version bump means the whole cache is replaced. See [#versioning] below.
+When building your service worker, provide a `version` string in the options, follow semvar conventions. If you change this at all, the service worker will be re-installed (because it has changed). This, in itself, will _not_ affect the cached files. But, if the _major version_ changes, the cache (of responses) will be deleting and a new one created. _With this library, the way to reset the cache in users' browsers is to bump the major version number._ (To test locally, you can use the browser's developer tools.) 
 
-## Versioning
+That being said, you're not in complete control. Browsers will manage the actual response cache, removing items if it becomes too large. These limits are quite high in modern browsers. Some of the strategies implemented here will replace older assets with newer ones when found; some won't. This should be documented above or obvious.
 
-Service workers themselves have no concept of versioning. The browser manages downloading the service worker on page load, and if it's "out of date", it will notice. It will install the new service worker and then wait until the current one isn't in use, and replace it with the new one. This generally means a new service worker won't come into play until the user closes the windows, so it may be some time. To accelerate this, pass `skipWaiting` in the options, which will activate the service worker as soon as it is downloaded.
+#### Skip Waiting
 
-Service workers themselves don't have the concept of semantic versioning, but this library provides a simple one: you can provide a VERSION string. The first component of it (the major version number), will be used to name the cache. If this changes, the cache is deleting and a new one created. This is the only effective way of resetting the cache from the service worker. (To test locally, you will use the browser's developer tools.) 
+Service workers themselves will re-install when they have changed-- based on the browsers' rules. This wil be confusing at first, though, as new service workers will not normally be installed. The default behavior for service workers is to wait until all the windows associated with the service worker are closed, and then install the new service worker. If this isn't what you want, you can accellerate this by passing `skipWaiting: true` in the options. This will install the service worker as soon as it is download-- but still will not be available as the page loads, but usually it will be ready on the next reload.
 
+## Why TS-Service-Worker?
 
+Service workers are a powerful tool for developers to improve the user experience, providing for fine-grained caching, offline usage and progressive web apps (PWAs). It replaced the coarse-grained _AppCache_, which proved quite hard to effectively use and was retired. 
 
-Strategies:
-precache
-cache
-prefetching (on installation)
-offline responses
-network-first
-cache-first
-offline backup  
+Unfortunately, the service worker API is also hard to use, as it is quite low-level. It requires a series of nested promise chains, and quickly grows complicated. In the documentation there are good examples describing single specific strategies. While these are readable, they are minimally useful because real-world usage requires integrating several of these strategies at the same time. This can be error-prone and hard to follow. And as anyone who has developed service workers knows, they are tedious to test because of the complex lifecycle.
+
+And since service workers run in the browser, they must be written in the browser's version Javascript. This likely involves transpilation, which will requiring additional complexity in the build process to produce a separate artifact. It can be quite challenging in a Typescript project.
+
+There are [other libraries](#other-libraries) designed to help, which may be useful to you. **TS-Service-Worker** aims to solve specific challenges.
 
 ## TODO
-1. Fix backup to ONLY serve backup if network fails.
-2. Command line
-   https://web.dev/learn/pwa/serving/#cache-only
+2. https://web.dev/learn/pwa/serving/#cache-only
 3. filter/only to process only certain types, eg. only: /https?:.*/
 4. allowOnly: /
 5. https://web.dev/learn/pwa/workbox/#offline-fallback
    https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API/Using_Service_Workers#recovering_failed_requests  ALSO offline SVG: https://github.com/veiss-com/sw-tools#offline
 6. https://github.com/veiss-com/sw-tools#limiting-the-cache-size
 7. expiring cache
-8. change name of service worker request handler. requesthandler?
 
-REFERENCE
-https://web.dev/learn/pwa/serving/
-https://web.dev/offline-cookbook/#on-network-response
+## References
+These are the basics of how service workers function:
+- https://web.dev/learn/pwa/serving/
+- https://web.dev/offline-cookbook/#on-network-response
 
 Interesting reference showing the complexities: https://adactio.com/serviceworker.js and https://adactio.medium.com/cache-limiting-in-service-workers-d6741361ca19
 
-
 ## Other Libraries
 - https://web.dev/learn/pwa/workbox/ -- popular and very cool tool. This will work for many projects, but I was looking for something where I had a little more control.
 - https://vite-pwa-org.netlify.app/frameworks/sveltekit.html

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ts-service-worker",
-  "version": "1.0.31",
+  "version": "1.0.33",
   "description": "Generate caching service-worker.js using declarative Typescript.",
   "author": {
     "name": "Andrew Peterson, NDP Software",