@eighty4/dank 0.0.5-3 → 0.0.5-5

package/client/ServiceWorker.ts

@@ -0,0 +1,89 @@
+import website from 'DANK:sw'
+
+declare const self: ServiceWorkerGlobalScope
+
+self.addEventListener('install', (e: ExtendableEvent) =>
+    e.waitUntil(populateCache()),
+)
+
+self.addEventListener('activate', (e: ExtendableEvent) =>
+    e.waitUntil(cleanupCaches()),
+)
+
+self.addEventListener('fetch', (e: FetchEvent) =>
+    e.respondWith(handleRequest(e.request)),
+)
+
+const PREFIX_APP_CACHE_KEY = 'DANK-website-'
+const APP_CACHE_KEY: string = PREFIX_APP_CACHE_KEY + website.cacheKey
+
+async function populateCache() {
+    const cache = await self.caches.open(APP_CACHE_KEY)
+    const previousCacheKey = await swapCurrentCacheKey()
+    if (!previousCacheKey) {
+        await cache.addAll(website.files)
+    } else {
+        const previousCache = await self.caches.open(previousCacheKey)
+        await Promise.all(
+            website.files.map(async f => {
+                const previouslyCached = await previousCache.match(f)
+                if (previouslyCached) {
+                    await cache.put(f, previouslyCached)
+                } else {
+                    await cache.add(f)
+                }
+            }),
+        )
+    }
+}
+
+async function swapCurrentCacheKey(): Promise<string | null> {
+    const META_CACHE_KEY = 'DANK-meta'
+    const CACHE_KEY_URL = '/DANK/current'
+    const metaCache = await self.caches.open(META_CACHE_KEY)
+    const previousCacheKeyResponse = await metaCache.match(CACHE_KEY_URL)
+    const previousCacheKey = previousCacheKeyResponse
+        ? await previousCacheKeyResponse.text()
+        : null
+    await metaCache.put(
+        CACHE_KEY_URL,
+        new Response(APP_CACHE_KEY, {
+            headers: {
+                'Content-Type': 'text/plain',
+            },
+        }),
+    )
+    return previousCacheKey
+}
+
+async function cleanupCaches() {
+    const cacheKeys = await self.caches.keys()
+    for (const cacheKey of cacheKeys) {
+        if (cacheKey !== APP_CACHE_KEY) {
+            await self.caches.delete(cacheKey)
+        }
+    }
+}
+
+// todo implement page mapping url rewrites here
+// url.pathname = mappedUrlPath
+async function handleRequest(req: Request): Promise<Response> {
+    const url = new URL(req.url)
+    if (req.method === 'GET' && !bypassCache(url)) {
+        const cache = await caches.open(APP_CACHE_KEY)
+        const fromCache = await cache.match(url)
+        if (fromCache) {
+            return fromCache
+        }
+    }
+    return fetch(req)
+}
+
+// todo support RegExp
+function bypassCache(url: URL): boolean {
+    return (
+        website.bypassCache?.hosts?.includes(url.host) ||
+        website.bypassCache?.paths?.includes(url.pathname as `/${string}`) ||
+        false
+    )
+}

package/lib/bin.ts

@@ -6,20 +6,21 @@ import { serveWebsite } from './serve.ts'
 
 function printHelp(task?: 'build' | 'serve'): never {
     if (!task || task === 'build') {
-        console.log('dank build [--minify] [--production]')
+        console.log('dank build [--minify] [--production] [--service-worker]')
     }
     if (!task || task === 'serve') {
         console.log(
             // 'dank serve [--minify] [--preview] [--production]',
-            'dank serve [--minify] [--production]',
+            'dank serve [--minify] [--production] [--service-worker]',
         )
     }
     console.log('\nOPTIONS:')
     if (!task || task === 'serve')
-        console.log('  --log-http     print access logs')
-    console.log('  --minify       minify sources')
+        console.log('  --log-http        print access logs')
+    console.log('  --minify          minify sources')
     // if (!task || task === 'serve') console.log('  --preview      pre-bundle and build ServiceWorker')
-    console.log('  --production   build for production release')
+    console.log('  --production      build for production release')
+    console.log('  --service-worker  build service worker')
     if (task) {
         console.log()
         console.log('use `dank -h` for details on all commands')

package/lib/build.ts

@@ -1,11 +1,12 @@
 import { mkdir, readFile, rm, writeFile } from 'node:fs/promises'
 import { join } from 'node:path'
 import { loadConfig, type ResolvedDankConfig } from './config.ts'
+import type { ServiceWorkerBuild, WebsiteManifest } from './dank.ts'
 import { type DefineDankGlobal, createGlobalDefinitions } from './define.ts'
 import type { DankDirectories } from './dirs.ts'
 import { esbuildWebpages, esbuildWorkers } from './esbuild.ts'
 import { copyAssets } from './public.ts'
-import { type WebsiteManifest, WebsiteRegistry } from './registry.ts'
+import { WebsiteRegistry } from './registry.ts'
 
 export async function buildWebsite(
     c?: ResolvedDankConfig,
@@ -13,7 +14,6 @@ export async function buildWebsite(
     if (!c) {
         c = await loadConfig('build', process.cwd())
     }
-    const buildTag = await c.buildTag()
     console.log(
         c.flags.minify
             ? c.flags.production
@@ -21,7 +21,7 @@ export async function buildWebsite(
                 : 'minified'
             : 'unminified',
         'build',
-        buildTag,
+        await c.buildTag(),
         'building in ./build/dist',
     )
     await rm(c.dirs.buildRoot, { recursive: true, force: true })
@@ -31,7 +31,7 @@ export async function buildWebsite(
     }
     await mkdir(join(c.dirs.buildRoot, 'metafiles'), { recursive: true })
     const registry = await buildWebpages(c, createGlobalDefinitions(c))
-    return await registry.writeManifest(buildTag)
+    return await registry.writeManifest()
 }
 
 // builds all webpage entrypoints in one esbuild.build context to support code splitting
@@ -62,6 +62,7 @@ async function buildWebpages(
             )
         }),
     )
+    await buildServiceWorker(registry)
     return registry
 }
 
@@ -127,3 +128,55 @@ export function createWorkerRegex(
         'g',
     )
 }
+
+async function buildServiceWorker(registry: WebsiteRegistry) {
+    const serviceWorkerBuilder = registry.config.serviceWorkerBuilder
+    if (serviceWorkerBuilder) {
+        const website = await registry.manifest()
+        const serviceWorkerBuild = await serviceWorkerBuilder({ website })
+        validateServiceWorkerBuild(serviceWorkerBuild)
+        serviceWorkerBuild.outputs.map(async (output, i) => {
+            try {
+                return await registry.addBuildOutput(output.url, output.content)
+            } catch {
+                console.log(
+                    `ServiceWorkerBuild.outputs[${i}].url \`${output.url}\` is already a url in the build output.`,
+                )
+                process.exit(1)
+            }
+        })
+    }
+}
+
+function validateServiceWorkerBuild(
+    serviceWorkerBuild: ServiceWorkerBuild,
+): void | never {
+    if (
+        serviceWorkerBuild === null ||
+        typeof serviceWorkerBuild === 'undefined'
+    ) {
+        console.log(`ServiceWorkerBuild is ${serviceWorkerBuild}.`)
+        console.log(
+            '\nMake sure the builder function \`serviceWorker\` in \`dank.config.ts\` is returning a ServiceWorkerBuild.',
+        )
+        process.exit(1)
+    }
+    const testUrlPattern = /^\/.*\.js$/
+    const valid = true
+    serviceWorkerBuild.outputs.forEach((output, i) => {
+        if (!output.content?.length) {
+            console.log(`ServiceWorkerBuild.outputs[${i}].content is empty.`)
+        }
+        if (!output.url?.length || !testUrlPattern.test(output.url)) {
+            console.log(
+                `ServiceWorkerBuild.outputs[${i}].url is not a valid \`/*.js\` path.`,
+            )
+        }
+    })
+    if (!valid) {
+        console.log(
+            '\nCheck your \`serviceWorker\` config in \`dank.config.ts\`.',
+        )
+        process.exit(1)
+    }
+}

package/lib/config.ts

@@ -3,8 +3,10 @@ import { createBuildTag } from './build_tag.ts'
 import type {
     DankConfig,
     DankDetails,
+    DevPageMapping,
     EsbuildConfig,
     PageMapping,
+    ServiceWorkerBuilder,
 } from './dank.ts'
 import { LOG } from './developer.ts'
 import { defaultProjectDirs, type DankDirectories } from './dirs.ts'
@@ -22,7 +24,7 @@ const DEFAULT_CONFIG_PATH = './dank.config.ts'
 export type { DevService } from './dank.ts'
 
 export type ResolvedDankConfig = {
-    // static from process boot
+    // static config that does not hot reload during `dank serve`
     get dirs(): Readonly<DankDirectories>
     get flags(): Readonly<Omit<DankFlags, 'dankPort' | 'esbuildPort'>>
     get mode(): 'build' | 'serve'
@@ -32,11 +34,16 @@ export type ResolvedDankConfig = {
     get esbuildPort(): number
     get esbuild(): Readonly<Omit<EsbuildConfig, 'port'>> | undefined
     get pages(): Readonly<Record<`/${string}`, PageMapping>>
-    get devPages(): Readonly<DankConfig['devPages']>
+    get devPages(): Readonly<
+        Record<`/${string}`, Omit<DevPageMapping & PageMapping, 'pattern'>>
+    >
     get services(): Readonly<DankConfig['services']>
+    get serviceWorkerBuilder(): DankConfig['serviceWorker']
 
     buildTag(): Promise<string>
 
+    pageMappings(): Record<`/${string}`, PageMapping>
+
     reload(): Promise<void>
 }
 
@@ -63,17 +70,19 @@ export async function loadConfig(
 }
 
 class DankConfigInternal implements ResolvedDankConfig {
-    #buildTag: DankConfig['buildTag']
+    #buildTag: Promise<string> | null = null
+    #buildTagBuilder: DankConfig['buildTag']
     #dirs: Readonly<DankDirectories>
     #flags: Readonly<DankFlags>
     #mode: 'build' | 'serve'
     #modulePath: string
+    #serviceWorkerBuilder?: ServiceWorkerBuilder
 
     #dankPort: number = DEFAULT_DEV_PORT
     #esbuildPort: number = DEFAULT_ESBUILD_PORT
     #esbuild: Readonly<Omit<EsbuildConfig, 'port'>> | undefined
     #pages: Readonly<Record<`/${string}`, PageMapping>> = {}
-    #devPages: Readonly<DankConfig['devPages']>
+    #devPages: Readonly<ResolvedDankConfig['devPages']> = {}
     #services: Readonly<DankConfig['services']>
 
     constructor(
@@ -115,7 +124,7 @@ class DankConfigInternal implements ResolvedDankConfig {
         return this.#pages
     }
 
-    get devPages(): Readonly<DankConfig['devPages']> {
+    get devPages(): Readonly<ResolvedDankConfig['devPages']> {
         return this.#devPages
     }
 
@@ -123,12 +132,30 @@ class DankConfigInternal implements ResolvedDankConfig {
         return this.#services
     }
 
-    async buildTag(): Promise<string> {
-        return await createBuildTag(
-            this.#dirs.projectRootAbs,
-            this.#flags,
-            this.#buildTag,
-        )
+    get serviceWorkerBuilder(): DankConfig['serviceWorker'] {
+        return this.#serviceWorkerBuilder
+    }
+
+    buildTag(): Promise<string> {
+        if (this.#buildTag === null) {
+            this.#buildTag = createBuildTag(
+                this.#dirs.projectRootAbs,
+                this.#flags,
+                this.#buildTagBuilder,
+            )
+        }
+        return this.#buildTag
+    }
+
+    pageMappings(): ResolvedDankConfig['pages'] {
+        if (this.#mode === 'serve') {
+            return {
+                ...this.#pages,
+                ...this.#devPages,
+            }
+        } else {
+            return this.#pages
+        }
     }
 
     async reload() {
@@ -136,13 +163,15 @@ class DankConfigInternal implements ResolvedDankConfig {
             this.#modulePath,
             resolveDankDetails(this.#mode, this.#flags),
         )
-        this.#buildTag = userConfig.buildTag
+        this.#buildTag = null
+        this.#buildTagBuilder = userConfig.buildTag
         this.#dankPort = resolveDankPort(this.#flags, userConfig)
         this.#esbuildPort = resolveEsbuildPort(this.#flags, userConfig)
         this.#esbuild = Object.freeze(userConfig.esbuild)
         this.#pages = Object.freeze(normalizePages(userConfig.pages))
-        this.#devPages = Object.freeze(userConfig.devPages)
+        this.#devPages = Object.freeze(normalizeDevPages(userConfig.devPages))
         this.#services = Object.freeze(userConfig.services)
+        this.#serviceWorkerBuilder = userConfig.serviceWorker
     }
 }
 
@@ -191,6 +220,7 @@ function validateDankConfig(c: Partial<DankConfig>) {
         validateDevPages(c.devPages)
         validateDevServices(c.services)
         validateEsbuildConfig(c.esbuild)
+        validateServiceWorker(c.serviceWorker)
     } catch (e: any) {
         LOG({
             realm: 'config',
@@ -230,6 +260,19 @@ function validateBuildTag(buildTag: DankConfig['buildTag']) {
     }
 }
 
+function validateServiceWorker(serviceWorker: DankConfig['serviceWorker']) {
+    if (serviceWorker === null) {
+        return
+    }
+    switch (typeof serviceWorker) {
+        case 'undefined':
+        case 'function':
+            return
+        default:
+            throw Error('DankConfig.serviceWorker must be a function')
+    }
+}
+
 function validateEsbuildConfig(esbuild?: EsbuildConfig) {
     if (esbuild?.loaders !== null && typeof esbuild?.loaders !== 'undefined') {
         if (typeof esbuild.loaders !== 'object') {
@@ -406,3 +449,27 @@ function normalizePages(
     }
     return result
 }
+
+function normalizeDevPages(
+    pages: DankConfig['devPages'],
+): Record<string, Omit<DevPageMapping & PageMapping, 'pattern'>> {
+    if (pages) {
+        const result: Record<
+            string,
+            Omit<DevPageMapping & PageMapping, 'pattern'>
+        > = {}
+        for (const [url, mapping] of Object.entries(pages)) {
+            if (typeof mapping === 'string') {
+                result[url] = {
+                    label: '',
+                    webpage: mapping,
+                }
+            } else {
+                result[url] = mapping
+            }
+        }
+        return result
+    } else {
+        return {}
+    }
+}

package/lib/dank.ts

@@ -24,6 +24,10 @@ export type DankConfig = {
 
     // dev services launched during `dank serve`
     services?: Array<DevService>
+
+    // generate a service worker for `dank build --production`
+    // and when previewing with `dank serve --preview`
+    serviceWorker?: ServiceWorkerBuilder
 }
 
 export type BuildTagParams = {
@@ -99,3 +103,33 @@ export function defineConfig(
 ): Partial<DankConfig> | DankConfigFunction {
     return config
 }
+
+// summary of a website build, written to `build` dir
+// and provided via ServiceWorkerParams to build a service worker from
+export type WebsiteManifest = {
+    buildTag: string
+    files: Array<`/${string}`>
+    pageUrls: Array<`/${string}`>
+}
+
+export type ServiceWorkerParams = {
+    website: WebsiteManifest
+}
+
+export type ServiceWorkerBuild = {
+    // outputs will be written to the build's dist
+    // and added to the manifest written to website.json
+    outputs: Array<{
+        url: `/${string}.js`
+        content: string
+    }>
+}
+
+export type ServiceWorkerBuilder = (
+    params: ServiceWorkerParams,
+) => ServiceWorkerBuild | Promise<ServiceWorkerBuild>
+
+export {
+    createServiceWorker,
+    type ServiceWorkerCaching,
+} from './service_worker.ts'

package/lib/esbuild.ts

@@ -75,6 +75,7 @@ export async function esbuildWorkers(
 function commonBuildOptions(r: WebsiteRegistry): BuildOptions {
     const p = workersPlugin(r.buildRegistry())
     return {
+        absWorkingDir: r.config.dirs.projectRootAbs,
         assetNames: 'assets/[name]-[hash]',
         bundle: true,
         format: 'esm',

package/lib/http.ts

@@ -10,12 +10,12 @@ import {
 import { extname, join } from 'node:path'
 import { Readable } from 'node:stream'
 import mime from 'mime'
+import type { WebsiteManifest } from './dank.ts'
 import type { DankDirectories } from './dirs.ts'
 import type { DankFlags } from './flags.ts'
 import type {
     UrlRewrite,
     UrlRewriteProvider,
-    WebsiteManifest,
     WebsiteRegistry,
 } from './registry.ts'
 import type { DevServices } from './services.ts'
@@ -194,7 +194,7 @@ export function createBuiltDistFilesFetcher(
         res: ServerResponse,
         notFound: () => void,
     ) => {
-        if (manifest.pageUrls.has(url.pathname)) {
+        if (manifest.pageUrls.includes(url.pathname as `/${string}`)) {
             streamFile(
                 join(
                     dirs.projectRootAbs,
@@ -204,7 +204,7 @@ export function createBuiltDistFilesFetcher(
                 ),
                 res,
             )
-        } else if (manifest.files.has(url.pathname)) {
+        } else if (manifest.files.includes(url.pathname as `/${string}`)) {
             streamFile(
                 join(dirs.projectRootAbs, dirs.buildDist, url.pathname),
                 res,

package/lib/public.ts

@@ -5,7 +5,7 @@ import type { DankDirectories } from './dirs.ts'
 
 export async function copyAssets(
     dirs: DankDirectories,
-): Promise<Array<string> | null> {
+): Promise<Array<`/${string}`> | null> {
     try {
         const stats = await stat(dirs.public)
         if (stats.isDirectory()) {
@@ -24,8 +24,8 @@ const IGNORE = platform() === 'darwin' ? ['.DS_Store'] : []
 async function recursiveCopyAssets(
     dirs: DankDirectories,
     dir: string = '',
-): Promise<Array<string>> {
-    const copied: Array<string> = []
+): Promise<Array<`/${string}`>> {
+    const copied: Array<`/${string}`> = []
     const to = join(dirs.buildDist, dir)
     let madeDir = dir === ''
     const listingDir = join(dirs.public, dir)
@@ -45,7 +45,7 @@ async function recursiveCopyAssets(
                     madeDir = true
                 }
                 await copyFile(join(listingDir, p), join(to, p))
-                copied.push('/' + join(dir, p).replaceAll('\\', '/'))
+                copied.push(`/${join(dir, p).replaceAll('\\', '/')}`)
             }
         } catch (e) {
             console.error('stat error', e)

package/lib/registry.ts

@@ -3,19 +3,12 @@ import { writeFile } from 'node:fs/promises'
 import { join } from 'node:path/posix'
 import type { BuildResult } from 'esbuild'
 import type { ResolvedDankConfig } from './config.ts'
-import type { PageMapping } from './dank.ts'
+import type { PageMapping, WebsiteManifest } from './dank.ts'
 import { LOG } from './developer.ts'
 import { Resolver, type DankDirectories } from './dirs.ts'
 import type { EntryPoint } from './esbuild.ts'
 import { HtmlEntrypoint } from './html.ts'
 
-// summary of a website build
-export type WebsiteManifest = {
-    buildTag: string
-    files: Set<string>
-    pageUrls: Set<string>
-}
-
 // result of an esbuild build from the context of the config's entrypoints
 // path of entrypoint is the reference point to lookup from a dependent page
 export type BuildManifest = {
@@ -67,12 +60,13 @@ export type UrlRewriteProvider = {
 // manages website resources during `dank build` and `dank serve`
 export class WebsiteRegistry extends EventEmitter<WebsiteRegistryEvents> {
     // paths of bundled esbuild outputs, as built by esbuild
-    #bundles: Set<string> = new Set()
+    #bundles: Set<`/${string}`> = new Set()
     #c: ResolvedDankConfig
     // public dir assets
-    #copiedAssets: Set<string> | null = null
+    #copiedAssets: Set<`/${string}`> | null = null
     // map of entrypoints to their output path
     #entrypointHrefs: Record<string, string | null> = {}
+    #otherOutputs: Set<`/${string}`> | null = null
     #pages: Record<`/${string}`, WebpageRegistration> = {}
     readonly #resolver: Resolver
     #workers: Array<WorkerManifest> | null = null
@@ -87,7 +81,7 @@ export class WebsiteRegistry extends EventEmitter<WebsiteRegistryEvents> {
         return this.#c
     }
 
-    set copiedAssets(copiedAssets: Array<string> | null) {
+    set copiedAssets(copiedAssets: Array<`/${string}`> | null) {
         this.#copiedAssets =
             copiedAssets === null ? null : new Set(copiedAssets)
     }
@@ -96,6 +90,14 @@ export class WebsiteRegistry extends EventEmitter<WebsiteRegistryEvents> {
         return Object.values(this.#pages).map(p => p.html)
     }
 
+    async manifest(): Promise<WebsiteManifest> {
+        return {
+            buildTag: await this.#c.buildTag(),
+            files: this.files(),
+            pageUrls: Object.keys(this.#pages) as Array<`/${string}`>,
+        }
+    }
+
     get pageUrls(): Array<string> {
         return Object.keys(this.#pages)
     }
@@ -159,6 +161,27 @@ export class WebsiteRegistry extends EventEmitter<WebsiteRegistryEvents> {
         return this.#workers
     }
 
+    // add a build output that does is manually injected into build output,
+    // not from HTML processing, public directory, or esbuild entrypoints
+    async addBuildOutput(url: `/${string}`, content: string) {
+        if (
+            this.#pages[url] ||
+            this.#bundles.has(url) ||
+            this.#otherOutputs?.has(url) ||
+            this.#copiedAssets?.has(url)
+        ) {
+            throw Error('build already has a ' + url)
+        }
+        if (this.#otherOutputs === null) this.#otherOutputs = new Set()
+        this.#otherOutputs.add(url)
+        const outputPath = join(
+            this.#c.dirs.projectRootAbs,
+            this.#c.dirs.buildDist,
+            url,
+        )
+        await writeFile(outputPath, content)
+    }
+
     buildRegistry(): BuildRegistry {
         return new BuildRegistry(
             this.#c.dirs,
@@ -171,13 +194,18 @@ export class WebsiteRegistry extends EventEmitter<WebsiteRegistryEvents> {
         this.#configDiff()
     }
 
-    files(): Set<string> {
-        const files = new Set<string>()
+    files(): Array<`/${string}`> {
+        const files = new Set<`/${string}`>()
         for (const pageUrl of Object.keys(this.#pages))
-            files.add(pageUrl === '/' ? '/index.html' : `${pageUrl}/index.html`)
+            files.add(
+                pageUrl === '/'
+                    ? '/index.html'
+                    : (`${pageUrl}/index.html` as `/${string}`),
+            )
         for (const f of this.#bundles) files.add(f)
         if (this.#copiedAssets) for (const f of this.#copiedAssets) files.add(f)
-        return files
+        if (this.#otherOutputs) for (const f of this.#otherOutputs) files.add(f)
+        return Array.from(files)
     }
 
     mappedHref(lookup: string): string {
@@ -189,33 +217,24 @@ export class WebsiteRegistry extends EventEmitter<WebsiteRegistryEvents> {
         }
     }
 
-    async writeManifest(buildTag: string): Promise<WebsiteManifest> {
-        const manifest = this.#manifest(buildTag)
+    async writeManifest(): Promise<WebsiteManifest> {
+        const manifest = await this.#manifest()
         await writeFile(
             join(
                 this.#c.dirs.projectRootAbs,
                 this.#c.dirs.buildRoot,
                 'website.json',
             ),
-            JSON.stringify(
-                {
-                    buildTag,
-                    files: Array.from(manifest.files),
-                    pageUrls: Array.from(manifest.pageUrls),
-                },
-                null,
-                4,
-            ),
+            JSON.stringify(manifest, null, 4),
         )
         return manifest
     }
 
     #configDiff() {
-        const updatePages: ResolvedDankConfig['pages'] = this.#c.devPages
-            ? { ...this.#c.pages, ...this.#c.devPages }
-            : { ...this.#c.pages }
         const prevPages = new Set(Object.keys(this.#pages))
-        for (const [urlPath, mapping] of Object.entries(updatePages)) {
+        for (const [urlPath, mapping] of Object.entries(
+            this.#c.pageMappings(),
+        )) {
             const existingPage = prevPages.delete(urlPath as `/${string}`)
             if (existingPage) {
                 this.#configPageUpdate(urlPath as `/${string}`, mapping)
@@ -303,18 +322,18 @@ export class WebsiteRegistry extends EventEmitter<WebsiteRegistryEvents> {
         delete this.#pages[urlPath]
     }
 
-    #manifest(buildTag: string): WebsiteManifest {
+    async #manifest(): Promise<WebsiteManifest> {
         return {
-            buildTag,
+            buildTag: await this.#c.buildTag(),
             files: this.files(),
-            pageUrls: new Set(Object.keys(this.#pages)),
+            pageUrls: Object.keys(this.#pages) as Array<`/${string}`>,
         }
     }
 
     #onBuildManifest: OnBuildComplete = (build: BuildManifest) => {
         // collect built bundle entrypoint hrefs
         for (const [outPath, entrypoint] of Object.entries(build.bundles)) {
-            this.#bundles.add(outPath)
+            this.#bundles.add(ensurePath(outPath))
             if (entrypoint) {
                 this.#entrypointHrefs[entrypoint] = outPath
             }
@@ -413,7 +432,7 @@ export class BuildRegistry {
         for (const [outPath, output] of Object.entries(
             result.metafile.outputs,
         )) {
-            bundles[outPath.replace(/^build[/\\]dist/, '')] =
+            bundles[outPath.replace(/^build[/\\](dist|watch)/, '')] =
                 output.entryPoint || null
         }
         let workers: BuildManifest['workers'] = null
@@ -438,3 +457,11 @@ export class BuildRegistry {
         })
     }
 }
+
+function ensurePath(path: string): `/${string}` {
+    if (path.startsWith('/')) {
+        return path as `/${string}`
+    } else {
+        throw Error(`expect build dist path ${path} to start with /`)
+    }
+}

package/lib/service_worker.ts

@@ -0,0 +1,63 @@
+import { join } from 'node:path'
+import esbuild from 'esbuild'
+import type { ServiceWorkerBuild } from './dank.ts'
+
+export type ServiceWorkerCaching = {
+    cacheKey: string
+    bypassCache?: {
+        hosts?: Array<string>
+        paths?: Array<`/${string}`>
+    }
+    files: Array<`/${string}`>
+}
+
+export async function createServiceWorker(
+    caching: ServiceWorkerCaching,
+): Promise<ServiceWorkerBuild> {
+    return {
+        outputs: [
+            {
+                content: await buildServiceWorkerBackend(caching),
+                url: '/sw.js',
+            },
+        ],
+    }
+}
+
+async function buildServiceWorkerBackend(
+    caching: ServiceWorkerCaching,
+): Promise<string> {
+    const result = await esbuild.build({
+        logLevel: 'silent',
+        absWorkingDir: join(import.meta.dirname, '../client'),
+        entryPoints: ['ServiceWorker.ts'],
+        treeShaking: true,
+        target: 'ES2022',
+        bundle: true,
+        minify: true,
+        format: 'iife',
+        platform: 'browser',
+        write: false,
+        metafile: true,
+        plugins: [
+            {
+                name: 'DANK:sw',
+                setup(build: esbuild.PluginBuild) {
+                    build.onResolve({ filter: /DANK:sw/ }, () => {
+                        return {
+                            path: join(import.meta.dirname, 'DANK.sw.json'),
+                        }
+                    })
+                    build.onLoad(
+                        { filter: /DANK\.sw\.json$/, namespace: 'file' },
+                        async () => ({
+                            contents: JSON.stringify(caching),
+                            loader: 'json',
+                        }),
+                    )
+                },
+            },
+        ],
+    })
+    return new TextDecoder().decode(result.outputFiles[0].contents)
+}

package/lib_js/bin.js

@@ -4,19 +4,20 @@ import { DankError } from "./errors.js";
 import { serveWebsite } from "./serve.js";
 function printHelp(task2) {
   if (!task2 || task2 === "build") {
-    console.log("dank build [--minify] [--production]");
+    console.log("dank build [--minify] [--production] [--service-worker]");
   }
   if (!task2 || task2 === "serve") {
     console.log(
       // 'dank serve [--minify] [--preview] [--production]',
-      "dank serve [--minify] [--production]"
+      "dank serve [--minify] [--production] [--service-worker]"
     );
   }
   console.log("\nOPTIONS:");
   if (!task2 || task2 === "serve")
-    console.log("  --log-http     print access logs");
-  console.log("  --minify       minify sources");
-  console.log("  --production   build for production release");
+    console.log("  --log-http        print access logs");
+  console.log("  --minify          minify sources");
+  console.log("  --production      build for production release");
+  console.log("  --service-worker  build service worker");
   if (task2) {
     console.log();
     console.log("use `dank -h` for details on all commands");

package/lib_js/build.js

@@ -9,8 +9,7 @@ async function buildWebsite(c) {
   if (!c) {
     c = await loadConfig("build", process.cwd());
   }
-  const buildTag = await c.buildTag();
-  console.log(c.flags.minify ? c.flags.production ? "minified production" : "minified" : "unminified", "build", buildTag, "building in ./build/dist");
+  console.log(c.flags.minify ? c.flags.production ? "minified production" : "minified" : "unminified", "build", await c.buildTag(), "building in ./build/dist");
   await rm(c.dirs.buildRoot, { recursive: true, force: true });
   await mkdir(c.dirs.buildDist, { recursive: true });
   for (const subdir of Object.keys(c.pages).filter((url) => url !== "/")) {
@@ -18,7 +17,7 @@ async function buildWebsite(c) {
   }
   await mkdir(join(c.dirs.buildRoot, "metafiles"), { recursive: true });
   const registry = await buildWebpages(c, createGlobalDefinitions(c));
-  return await registry.writeManifest(buildTag);
+  return await registry.writeManifest();
 }
 async function buildWebpages(c, define) {
   const registry = new WebsiteRegistry(c);
@@ -34,6 +33,7 @@ async function buildWebpages(c, define) {
   await Promise.all(registry.htmlEntrypoints.map(async (html) => {
     await writeFile(join(c.dirs.buildDist, html.url, "index.html"), html.output(registry));
   }));
+  await buildServiceWorker(registry);
   return registry;
 }
 async function rewriteWorkerUrls(dirs, registry) {
@@ -64,6 +64,43 @@ async function rewriteWorkerUrls(dirs, registry) {
 function createWorkerRegex(workerCtor, workerUrl) {
   return new RegExp(`new(?:\\s|\\r?\\n)+${workerCtor}(?:\\s|\\r?\\n)*\\((?:\\s|\\r?\\n)*['"]${workerUrl}['"](?:\\s|\\r?\\n)*\\)`, "g");
 }
+async function buildServiceWorker(registry) {
+  const serviceWorkerBuilder = registry.config.serviceWorkerBuilder;
+  if (serviceWorkerBuilder) {
+    const website = await registry.manifest();
+    const serviceWorkerBuild = await serviceWorkerBuilder({ website });
+    validateServiceWorkerBuild(serviceWorkerBuild);
+    serviceWorkerBuild.outputs.map(async (output, i) => {
+      try {
+        return await registry.addBuildOutput(output.url, output.content);
+      } catch {
+        console.log(`ServiceWorkerBuild.outputs[${i}].url \`${output.url}\` is already a url in the build output.`);
+        process.exit(1);
+      }
+    });
+  }
+}
+function validateServiceWorkerBuild(serviceWorkerBuild) {
+  if (serviceWorkerBuild === null || typeof serviceWorkerBuild === "undefined") {
+    console.log(`ServiceWorkerBuild is ${serviceWorkerBuild}.`);
+    console.log("\nMake sure the builder function `serviceWorker` in `dank.config.ts` is returning a ServiceWorkerBuild.");
+    process.exit(1);
+  }
+  const testUrlPattern = /^\/.*\.js$/;
+  const valid = true;
+  serviceWorkerBuild.outputs.forEach((output, i) => {
+    if (!output.content?.length) {
+      console.log(`ServiceWorkerBuild.outputs[${i}].content is empty.`);
+    }
+    if (!output.url?.length || !testUrlPattern.test(output.url)) {
+      console.log(`ServiceWorkerBuild.outputs[${i}].url is not a valid \`/*.js\` path.`);
+    }
+  });
+  if (!valid) {
+    console.log("\nCheck your `serviceWorker` config in `dank.config.ts`.");
+    process.exit(1);
+  }
+}
 export {
   buildWebsite,
   createWorkerRegex,

package/lib_js/config.js

@@ -25,16 +25,18 @@ async function loadConfig(mode, projectRootAbs) {
   return c;
 }
 class DankConfigInternal {
-  #buildTag;
+  #buildTag = null;
+  #buildTagBuilder;
   #dirs;
   #flags;
   #mode;
   #modulePath;
+  #serviceWorkerBuilder;
   #dankPort = DEFAULT_DEV_PORT;
   #esbuildPort = DEFAULT_ESBUILD_PORT;
   #esbuild;
   #pages = {};
-  #devPages;
+  #devPages = {};
   #services;
   constructor(mode, modulePath, dirs) {
     this.#dirs = dirs;
@@ -69,18 +71,36 @@ class DankConfigInternal {
   get services() {
     return this.#services;
   }
-  async buildTag() {
-    return await createBuildTag(this.#dirs.projectRootAbs, this.#flags, this.#buildTag);
+  get serviceWorkerBuilder() {
+    return this.#serviceWorkerBuilder;
+  }
+  buildTag() {
+    if (this.#buildTag === null) {
+      this.#buildTag = createBuildTag(this.#dirs.projectRootAbs, this.#flags, this.#buildTagBuilder);
+    }
+    return this.#buildTag;
+  }
+  pageMappings() {
+    if (this.#mode === "serve") {
+      return {
+        ...this.#pages,
+        ...this.#devPages
+      };
+    } else {
+      return this.#pages;
+    }
   }
   async reload() {
     const userConfig = await resolveConfig(this.#modulePath, resolveDankDetails(this.#mode, this.#flags));
-    this.#buildTag = userConfig.buildTag;
+    this.#buildTag = null;
+    this.#buildTagBuilder = userConfig.buildTag;
     this.#dankPort = resolveDankPort(this.#flags, userConfig);
     this.#esbuildPort = resolveEsbuildPort(this.#flags, userConfig);
     this.#esbuild = Object.freeze(userConfig.esbuild);
     this.#pages = Object.freeze(normalizePages(userConfig.pages));
-    this.#devPages = Object.freeze(userConfig.devPages);
+    this.#devPages = Object.freeze(normalizeDevPages(userConfig.devPages));
     this.#services = Object.freeze(userConfig.services);
+    this.#serviceWorkerBuilder = userConfig.serviceWorker;
   }
 }
 function resolveDankPort(flags, userConfig) {
@@ -110,6 +130,7 @@ function validateDankConfig(c) {
     validateDevPages(c.devPages);
     validateDevServices(c.services);
     validateEsbuildConfig(c.esbuild);
+    validateServiceWorker(c.serviceWorker);
   } catch (e) {
     throw e;
   }
@@ -139,6 +160,18 @@ function validateBuildTag(buildTag) {
       throw Error("DankConfig.buildTag must be a string or function");
   }
 }
+function validateServiceWorker(serviceWorker) {
+  if (serviceWorker === null) {
+    return;
+  }
+  switch (typeof serviceWorker) {
+    case "undefined":
+    case "function":
+      return;
+    default:
+      throw Error("DankConfig.serviceWorker must be a function");
+  }
+}
 function validateEsbuildConfig(esbuild) {
   if (esbuild?.loaders !== null && typeof esbuild?.loaders !== "undefined") {
     if (typeof esbuild.loaders !== "object") {
@@ -257,6 +290,24 @@ function normalizePages(pages) {
   }
   return result;
 }
+function normalizeDevPages(pages) {
+  if (pages) {
+    const result = {};
+    for (const [url, mapping] of Object.entries(pages)) {
+      if (typeof mapping === "string") {
+        result[url] = {
+          label: "",
+          webpage: mapping
+        };
+      } else {
+        result[url] = mapping;
+      }
+    }
+    return result;
+  } else {
+    return {};
+  }
+}
 export {
   loadConfig
 };

package/lib_js/dank.js

@@ -1,6 +1,8 @@
+import { createServiceWorker } from "./service_worker.js";
 function defineConfig(config) {
   return config;
 }
 export {
+  createServiceWorker,
   defineConfig
 };

package/lib_js/esbuild.js

@@ -44,6 +44,7 @@ async function esbuildWorkers(r, define, entryPoints) {
 function commonBuildOptions(r) {
   const p = workersPlugin(r.buildRegistry());
   return {
+    absWorkingDir: r.config.dirs.projectRootAbs,
     assetNames: "assets/[name]-[hash]",
     bundle: true,
     format: "esm",

package/lib_js/http.js

@@ -92,9 +92,9 @@ function createLogWrapper(handler) {
 }
 function createBuiltDistFilesFetcher(dirs, manifest) {
   return (url, _headers, res, notFound) => {
-    if (manifest.pageUrls.has(url.pathname)) {
+    if (manifest.pageUrls.includes(url.pathname)) {
       streamFile(join(dirs.projectRootAbs, dirs.buildDist, url.pathname, "index.html"), res);
-    } else if (manifest.files.has(url.pathname)) {
+    } else if (manifest.files.includes(url.pathname)) {
       streamFile(join(dirs.projectRootAbs, dirs.buildDist, url.pathname), res);
     } else {
       notFound();

package/lib_js/public.js

@@ -36,7 +36,7 @@ async function recursiveCopyAssets(dirs, dir = "") {
           madeDir = true;
         }
         await copyFile(join(listingDir, p), join(to, p));
-        copied.push("/" + join(dir, p).replaceAll("\\", "/"));
+        copied.push(`/${join(dir, p).replaceAll("\\", "/")}`);
       }
     } catch (e) {
       console.error("stat error", e);

package/lib_js/registry.js

@@ -11,6 +11,7 @@ class WebsiteRegistry extends EventEmitter {
   #copiedAssets = null;
   // map of entrypoints to their output path
   #entrypointHrefs = {};
+  #otherOutputs = null;
   #pages = {};
   #resolver;
   #workers = null;
@@ -28,6 +29,13 @@ class WebsiteRegistry extends EventEmitter {
   get htmlEntrypoints() {
     return Object.values(this.#pages).map((p) => p.html);
   }
+  async manifest() {
+    return {
+      buildTag: await this.#c.buildTag(),
+      files: this.files(),
+      pageUrls: Object.keys(this.#pages)
+    };
+  }
   get pageUrls() {
     return Object.keys(this.#pages);
   }
@@ -71,6 +79,18 @@ class WebsiteRegistry extends EventEmitter {
   get workers() {
     return this.#workers;
   }
+  // add a build output that does is manually injected into build output,
+  // not from HTML processing, public directory, or esbuild entrypoints
+  async addBuildOutput(url, content) {
+    if (this.#pages[url] || this.#bundles.has(url) || this.#otherOutputs?.has(url) || this.#copiedAssets?.has(url)) {
+      throw Error("build already has a " + url);
+    }
+    if (this.#otherOutputs === null)
+      this.#otherOutputs = /* @__PURE__ */ new Set();
+    this.#otherOutputs.add(url);
+    const outputPath = join(this.#c.dirs.projectRootAbs, this.#c.dirs.buildDist, url);
+    await writeFile(outputPath, content);
+  }
   buildRegistry() {
     return new BuildRegistry(this.#c.dirs, this.#resolver, this.#onBuildManifest);
   }
@@ -86,7 +106,10 @@ class WebsiteRegistry extends EventEmitter {
     if (this.#copiedAssets)
       for (const f of this.#copiedAssets)
         files.add(f);
-    return files;
+    if (this.#otherOutputs)
+      for (const f of this.#otherOutputs)
+        files.add(f);
+    return Array.from(files);
   }
   mappedHref(lookup) {
     const found = this.#entrypointHrefs[lookup];
@@ -96,19 +119,14 @@ class WebsiteRegistry extends EventEmitter {
       throw Error(`mapped href for ${lookup} not found`);
     }
   }
-  async writeManifest(buildTag) {
-    const manifest = this.#manifest(buildTag);
-    await writeFile(join(this.#c.dirs.projectRootAbs, this.#c.dirs.buildRoot, "website.json"), JSON.stringify({
-      buildTag,
-      files: Array.from(manifest.files),
-      pageUrls: Array.from(manifest.pageUrls)
-    }, null, 4));
+  async writeManifest() {
+    const manifest = await this.#manifest();
+    await writeFile(join(this.#c.dirs.projectRootAbs, this.#c.dirs.buildRoot, "website.json"), JSON.stringify(manifest, null, 4));
     return manifest;
   }
   #configDiff() {
-    const updatePages = this.#c.devPages ? { ...this.#c.pages, ...this.#c.devPages } : { ...this.#c.pages };
     const prevPages = new Set(Object.keys(this.#pages));
-    for (const [urlPath, mapping] of Object.entries(updatePages)) {
+    for (const [urlPath, mapping] of Object.entries(this.#c.pageMappings())) {
       const existingPage = prevPages.delete(urlPath);
       if (existingPage) {
         this.#configPageUpdate(urlPath, mapping);
@@ -155,16 +173,16 @@ class WebsiteRegistry extends EventEmitter {
     registration.html.removeAllListeners();
     delete this.#pages[urlPath];
   }
-  #manifest(buildTag) {
+  async #manifest() {
     return {
-      buildTag,
+      buildTag: await this.#c.buildTag(),
       files: this.files(),
-      pageUrls: new Set(Object.keys(this.#pages))
+      pageUrls: Object.keys(this.#pages)
     };
   }
   #onBuildManifest = (build) => {
     for (const [outPath, entrypoint] of Object.entries(build.bundles)) {
-      this.#bundles.add(outPath);
+      this.#bundles.add(ensurePath(outPath));
       if (entrypoint) {
         this.#entrypointHrefs[entrypoint] = outPath;
       }
@@ -229,7 +247,7 @@ class BuildRegistry {
   completeBuild(result) {
     const bundles = {};
     for (const [outPath, output] of Object.entries(result.metafile.outputs)) {
-      bundles[outPath.replace(/^build[/\\]dist/, "")] = output.entryPoint || null;
+      bundles[outPath.replace(/^build[/\\](dist|watch)/, "")] = output.entryPoint || null;
     }
     let workers = null;
     if (this.#workers) {
@@ -254,6 +272,13 @@ class BuildRegistry {
     });
   }
 }
+function ensurePath(path) {
+  if (path.startsWith("/")) {
+    return path;
+  } else {
+    throw Error(`expect build dist path ${path} to start with /`);
+  }
+}
 export {
   BuildRegistry,
   WebsiteRegistry

package/lib_js/service_worker.js

@@ -0,0 +1,47 @@
+import { join } from "node:path";
+import esbuild from "esbuild";
+async function createServiceWorker(caching) {
+  return {
+    outputs: [
+      {
+        content: await buildServiceWorkerBackend(caching),
+        url: "/sw.js"
+      }
+    ]
+  };
+}
+async function buildServiceWorkerBackend(caching) {
+  const result = await esbuild.build({
+    logLevel: "silent",
+    absWorkingDir: join(import.meta.dirname, "../client"),
+    entryPoints: ["ServiceWorker.ts"],
+    treeShaking: true,
+    target: "ES2022",
+    bundle: true,
+    minify: true,
+    format: "iife",
+    platform: "browser",
+    write: false,
+    metafile: true,
+    plugins: [
+      {
+        name: "DANK:sw",
+        setup(build) {
+          build.onResolve({ filter: /DANK:sw/ }, () => {
+            return {
+              path: join(import.meta.dirname, "DANK.sw.json")
+            };
+          });
+          build.onLoad({ filter: /DANK\.sw\.json$/, namespace: "file" }, async () => ({
+            contents: JSON.stringify(caching),
+            loader: "json"
+          }));
+        }
+      }
+    ]
+  });
+  return new TextDecoder().decode(result.outputFiles[0].contents);
+}
+export {
+  createServiceWorker
+};

package/lib_types/dank.d.ts

@@ -7,6 +7,7 @@ export type DankConfig = {
     port?: number;
     previewPort?: number;
     services?: Array<DevService>;
+    serviceWorker?: ServiceWorkerBuilder;
 };
 export type BuildTagParams = {
     production: boolean;
@@ -42,3 +43,19 @@ export type DankDetails = {
 export type DankConfigFunction = (dank: DankDetails) => Partial<DankConfig> | Promise<Partial<DankConfig>>;
 export declare function defineConfig(config: Partial<DankConfig>): Partial<DankConfig>;
 export declare function defineConfig(config: DankConfigFunction): DankConfigFunction;
+export type WebsiteManifest = {
+    buildTag: string;
+    files: Array<`/${string}`>;
+    pageUrls: Array<`/${string}`>;
+};
+export type ServiceWorkerParams = {
+    website: WebsiteManifest;
+};
+export type ServiceWorkerBuild = {
+    outputs: Array<{
+        url: `/${string}.js`;
+        content: string;
+    }>;
+};
+export type ServiceWorkerBuilder = (params: ServiceWorkerParams) => ServiceWorkerBuild | Promise<ServiceWorkerBuild>;
+export { createServiceWorker, type ServiceWorkerCaching, } from './service_worker.ts';

package/lib_types/service_worker.d.ts

@@ -0,0 +1,10 @@
+import type { ServiceWorkerBuild } from './dank.ts';
+export type ServiceWorkerCaching = {
+    cacheKey: string;
+    bypassCache?: {
+        hosts?: Array<string>;
+        paths?: Array<`/${string}`>;
+    };
+    files: Array<`/${string}`>;
+};
+export declare function createServiceWorker(caching: ServiceWorkerCaching): Promise<ServiceWorkerBuild>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eighty4/dank",
-  "version": "0.0.5-3",
+  "version": "0.0.5-5",
   "type": "module",
   "license": "MIT",
   "author": "Adam McKee Bennett <adam.be.g84d@gmail.com>",
@@ -38,6 +38,7 @@
   },
   "files": [
     "client/client.js",
+    "client/ServiceWorker.ts",
     "lib/*.ts",
     "lib_js/*.js",
     "lib_types/*.d.ts"
@@ -45,7 +46,7 @@
   "scripts": {
     "build": "pnpm build:client && pnpm build:lib",
     "build:client": "node scripts/build_client.ts",
-    "build:lib": "tsc && tsc -p tsconfig.exports.json",
+    "build:lib": "tsc && tsc -p tsconfig.exports.json && tsc -p tsconfig.sw.json",
     "build:release": "pnpm build && node scripts/prepare_release.ts",
     "fmt": "prettier --write .",
     "fmtcheck": "prettier --check .",