ts-service-worker 1.0.31

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "ts-service-worker",
+  "version": "1.0.31",
+  "description": "Generate caching service-worker.js using declarative Typescript.",
+  "author": {
+    "name": "Andrew Peterson, NDP Software",
+    "email": "andy@ndpsoftware.com"
+  },
+  "keywords": [
+    "build",
+    "cache",
+    "declarative configuration",
+    "offline",
+    "progressive web apps",
+    "pwa",
+    "service worker",
+    "sw",
+    "ts",
+    "typescript"
+  ],
+  "license": "Copyright (c) 2023 Andrew J. Peterson, NDP Software",
+  "sideEffects": false,
+
+  "type": "commonjs",
+  "main": "./dist/index.js",
+  "types": "./types/index.d.mts",
+  "bin": {
+    "ts-service-worker": "./dist/cli.mjs"
+  },
+  "files": [
+    "README.md",
+    "dist",
+    "types"
+  ],
+
+  "scripts": {
+    "example1": "node --loader tsx example/amp-what-sw.mts",
+    "example2": "./dist/cli.mjs example/offline-backup.json",
+    "test": "node --test --loader tsx src/specs/*.mts",
+    "build": "yarn clean && yarn build-dist && yarn build-bin && yarn build-types",
+    "clean": "rm -fr ./dist/* ./types/*",
+    "build-dist": "./node_modules/.bin/esbuild --target=esnext --outfile=./dist/index.js --bundle --platform=node --sourcemap --format=cjs src/index.mts",
+    "build-bin": "esbuild --banner:js=\"#!/usr/bin/env node\" --bundle --platform=node --format=esm --target=es2022 src/cli.mts --outfile=dist/cli.mjs && chmod u+x dist/cli.mjs",
+    "build-types": "tsc -p src/tsconfig.json",
+    "prepublishOnly": "yarn build"
+  },
+
+  "engines": {
+    "node": ">=16"
+  },
+  "devDependencies": {
+    "esbuild": "*",
+    "tsx": "*"
+  }
+}

package/types/cli.d.mts

@@ -0,0 +1 @@
+export {};

package/types/fileSpecsToPaths.d.mts

@@ -0,0 +1,9 @@
+export type FilesSpec = string | Array<string> | {
+    glob: string | Array<string>;
+    dir?: string;
+    prefix?: string;
+};
+/**
+ * Convert a messy file spec into an array of paths.
+ */
+export declare function fileSpecsToPaths(files: FilesSpec): Array<string>;

package/types/generate.d.mts

@@ -0,0 +1,27 @@
+import { InputCacheStrategy, InputPaths } from './strategies.mjs';
+export type Plan = Array<InputCacheStrategy>;
+type Version = string;
+export type Options = {
+    version?: Version;
+    debug?: boolean;
+    skipWaiting?: boolean;
+};
+/**
+ * Produce a string that contains Javascript code to implement
+ * the given caching `Plan`, taking into account options.
+ *
+ * Options:
+ * - `version`: a semvar version for the cache in the user's browser. This
+ *    is largely ignored, but importantly a major version bump
+ *    will cause the cache to be rebuilt.
+ * - `debug`: true will generate `console.log` notices for
+ *    all activity in the service worker. It should be turned off in production.
+ * - `skipWaiting`: setting to `true` has the same effect as
+ *    calling the method as described in the service worker documention (but simpler!).
+ */
+export declare function generateServiceWorker(inputSpec: Plan, optionsIn?: Options): string;
+export declare function generateVersion(version: Version): string;
+export declare function generateFlag(name: string, bool: boolean): string;
+export declare function pathsToJS(paths: InputPaths): string;
+export declare function pathToJS(path: string | RegExp | symbol): string;
+export {};

package/types/index.d.mts

@@ -0,0 +1,3 @@
+export { Origin, Scope } from './strategies.mjs';
+export { requestHandler } from './requestHandler.mjs';
+export { generateServiceWorker, type Plan } from './generate.mjs';

package/types/requestHandler.d.mts

@@ -0,0 +1,3 @@
+import { IncomingMessage, ServerResponse } from "http";
+import { Options, Plan } from "./generate.mjs";
+export declare const requestHandler: (plan: Plan, options: Options) => (req: IncomingMessage, res: ServerResponse) => void;

package/types/serviceWorkerTemplate.d.mts

@@ -0,0 +1 @@
+export declare const TEMPLATE: string;

package/types/strategies.d.mts

@@ -0,0 +1,124 @@
+import { FilesSpec } from "./fileSpecsToPaths.mjs";
+/**
+ * Preload and cache any number of files enumerated from disk using globs.
+ *  Implies 'cacheFirst'.
+  */
+export type CacheFileOnInstall = {
+    strategy: 'cache-on-install';
+    files: FilesSpec;
+};
+export declare function isCacheFileOnInstall(s: {
+    strategy: string;
+}): s is CacheFileOnInstall;
+/**
+ *  Preload and cache enumerated paths (not files)
+ *  Implies 'cacheFirst'.
+ */
+export type CachePathOnInstall = {
+    strategy: 'cache-on-install';
+    paths: string | Array<string>;
+};
+export declare function isCachePathOnInstall(s: {
+    strategy: string;
+}): s is CachePathOnInstall;
+/**
+ Serve from the cache if available, otherwise go to the network.
+ Ideal for: CSS, images, fonts, JS, templates… basically anything you'd consider static to that "version" of your site.
+ @see https://web.dev/learn/pwa/serving/#cache-first
+ On its own implies no update to the cache file, so only useful
+ for immutable resources.
+ https://web.dev/offline-cookbook/#on-network-response
+ if retrieved via network, gets cached
+ */
+export type CacheFirstStrategy<Paths> = {
+    readonly strategy: 'cacheFirst';
+    readonly paths: Paths;
+};
+/**
+ * If the network connection is not available, use
+ * the cached version.
+ * Files are cached in the background as they are fetched.
+ * @see https://web.dev/learn/pwa/serving/#network-first
+ */
+export type NetworkFirstStrategy<Paths> = {
+    strategy: 'networkFirst';
+    paths: Paths;
+};
+/**
+ * Serve files from the cache, and then in the background update
+ * with a fresh version.
+ * Useful for potentially slow and non-time-sensitive resources.
+ * @see https://web.dev/learn/pwa/serving/#stale-while-revalidate
+ */
+export type StaleWhileRevalidateStrategy<Paths> = {
+    strategy: 'staleWhileRevalidate';
+    paths: Paths;
+};
+/**
+ * Serve normally (from network) unless not available. If
+ * network is down, use the response from the backup path.
+ * The backup path is cached on service worker installation.
+ */
+export type StaticOfflineBackupStrategy<Paths> = {
+    strategy: 'staticOfflineBackup';
+    paths: Paths;
+    backup: string;
+};
+export declare function isStaticOfflineBackup(s: {
+    strategy: string;
+}): s is StaticOfflineBackupStrategy<unknown>;
+/**
+ * Serve from the network only. No caching.
+ * https://web.dev/learn/pwa/serving/#network-only
+ */
+export type NetworkOnlyStrategy<Paths> = {
+    strategy: 'networkOnly';
+    paths: Paths;
+};
+export type RoutableStrategy<Paths> = CacheFirstStrategy<Paths> | NetworkFirstStrategy<Paths> | StaleWhileRevalidateStrategy<Paths> | NetworkOnlyStrategy<Paths> | StaticOfflineBackupStrategy<Paths>;
+export type CacheOnInstallStrategy = CachePathOnInstall | CacheFileOnInstall;
+export type InputCacheStrategy = RoutableStrategy<InputPaths> | CacheOnInstallStrategy;
+export type InputCacheStrategyAsPaths = RoutableStrategy<InputPaths> | CachePathOnInstall;
+/**
+ * Indicator for all file paths routed from the same origin
+ * as the service worker is served from.
+ */
+export declare const Origin: unique symbol;
+/**
+ * Indicator for all files served within the service worker's
+ * scope. Usually you will want `Origin`, but this is included
+ * for completeness.
+ */
+export declare const Scope: unique symbol;
+export type InputPaths = RegExp | string | OutputPaths | typeof Origin | typeof Scope;
+export type OutputPaths = Array<string | RegExp>;
+export declare function isRoutableStrategy<Paths>(x: {
+    strategy: string;
+}): x is RoutableStrategy<Paths>;
+export declare function convertPreloadFilesToPaths(strategy: CacheFileOnInstall): CachePathOnInstall;
+/**
+ * Converts paths specified by scanning the disk to the paths
+ * that are the result of that scan.
+ * Users may specific some paths as "files", which are
+ * then determined by scanning the disk (with glob patterns.)
+ * Obviously this is useful for certain static resources,
+ * where it might be tedious to keep the service worker spec
+ * up-to-date with resources in a folder.
+ * The downside of this are that it can pick up extra files
+ * without the developer being aware, so it's important to
+ * review either the generated service worker code, or the
+ * cache created in the browser.
+ */
+export declare function convertPreloadFiles(strategy: InputCacheStrategy): InputCacheStrategyAsPaths;
+/**
+ * Run through all the strategies in a plan and extract all
+ * the paths that should be "preloaded" on service worker
+ * installation. This includes explicit preload paths,
+ * preload-files (which have been converted to paths before
+ * this call), and offline backup paths.
+ */
+export declare function extractAllPreloadPaths(plan: Array<{
+    strategy: string;
+}>): OutputPaths;
+export declare function convertPreloadPathsToCacheFirst(spec: Array<InputCacheStrategyAsPaths>): Array<RoutableStrategy<InputPaths>>;
+export declare function convertAllFilesToPaths(spec: Array<InputCacheStrategy>): Array<InputCacheStrategyAsPaths>;