@eighty4/dank 0.0.5-2 → 0.0.5-4

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,12 +1,12 @@
 import { mkdir, readFile, rm, writeFile } from 'node:fs/promises'
 import { join } from 'node:path'
-import { createBuildTag } from './build_tag.ts'
 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,
@@ -14,7 +14,6 @@ export async function buildWebsite(
     if (!c) {
         c = await loadConfig('build', process.cwd())
     }
-    const buildTag = await createBuildTag(c.flags)
     console.log(
         c.flags.minify
             ? c.flags.production
@@ -22,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 })
@@ -32,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
@@ -63,6 +62,7 @@ async function buildWebpages(
             )
         }),
     )
+    await buildServiceWorker(registry)
     return registry
 }
 
@@ -128,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/build_tag.ts

@@ -1,25 +1,129 @@
 import { exec } from 'node:child_process'
+import type { DankConfig } from './dank.ts'
 import type { DankFlags } from './flags.ts'
 
-export async function createBuildTag(flags: DankFlags): Promise<string> {
+export async function createBuildTag(
+    projectDir: string,
+    flags: DankFlags,
+    buildTagSource?: DankConfig['buildTag'],
+): Promise<string> {
+    if (typeof buildTagSource === 'function') {
+        buildTagSource = await buildTagSource({ production: flags.production })
+    }
+    if (typeof buildTagSource === 'undefined' || buildTagSource === null) {
+        buildTagSource = await resolveExpressionDefault(projectDir)
+    }
+    if (typeof buildTagSource !== 'string') {
+        throw TypeError(
+            'DankConfig.buildTag must resolve to a string expession',
+        )
+    }
+    const params: BuildTagParams = {}
     const now = new Date()
+    const paramPattern = new RegExp(/{{\s*(?<name>[a-z][A-Za-z]+)\s*}}/g)
+    let paramMatch: RegExpExecArray | null
+    let buildTag = buildTagSource
+    let offset = 0
+    while ((paramMatch = paramPattern.exec(buildTagSource)) != null) {
+        const paramName = paramMatch.groups!.name.trim() as keyof BuildTagParams
+        let paramValue: string
+        if (params[paramName]) {
+            paramValue = params[paramName]
+        } else {
+            paramValue = params[paramName] = await getParamValue(
+                projectDir,
+                paramName,
+                now,
+                buildTagSource,
+            )
+        }
+        buildTag =
+            buildTag.substring(0, paramMatch.index + offset) +
+            paramValue +
+            buildTag.substring(paramMatch.index + paramMatch[0].length + offset)
+        offset += paramValue.length - paramMatch[0].length
+    }
+    const validate = /^[A-Za-z\d][A-Za-z\d-_\.]+$/
+    if (!validate.test(buildTag)) {
+        throw Error(
+            `build tag ${buildTag} does not pass pattern ${validate.source} validation`,
+        )
+    }
+    return buildTag
+}
+
+async function resolveExpressionDefault(projectDir: string): Promise<string> {
+    const base = '{{ date }}-{{ timeMS }}'
+    const isGitRepo = await new Promise(res =>
+        exec('git rev-parse --is-inside-work-tree', { cwd: projectDir }, err =>
+            res(!err),
+        ),
+    )
+    return isGitRepo ? base + '-{{ gitHash }}' : base
+}
+
+type BuildTagParams = {
+    date?: string
+    gitHash?: string
+    timeMS?: string
+}
+
+async function getParamValue(
+    projectDir: string,
+    name: keyof BuildTagParams,
+    now: Date,
+    buildTagSource: string,
+): Promise<string> {
+    switch (name) {
+        case 'date':
+            return getDate(now)
+        case 'gitHash':
+            try {
+                return await getGitHash(projectDir)
+            } catch (e) {
+                if (e === 'not-repo') {
+                    throw Error(
+                        `buildTag cannot use \`gitHash\` in \`${buildTagSource}\` outside of a git repository`,
+                    )
+                } else {
+                    throw e
+                }
+            }
+        case 'timeMS':
+            return getTimeMS(now)
+        default:
+            throw Error(name + ' is not a supported build tag param')
+    }
+}
+
+function getDate(now: Date): string {
+    return now.toISOString().substring(0, 10)
+}
+
+async function getGitHash(projectDir: string): Promise<string> {
+    return await new Promise((res, rej) =>
+        exec(
+            'git rev-parse --short HEAD',
+            { cwd: projectDir },
+            (err, stdout, stderr) => {
+                if (err) {
+                    if (stderr.includes('not a git repository')) {
+                        rej('not-repo')
+                    } else {
+                        rej(err)
+                    }
+                }
+                res(stdout.trim())
+            },
+        ),
+    )
+}
+
+function getTimeMS(now: Date): string {
     const ms =
         now.getUTCMilliseconds() +
         now.getUTCSeconds() * 1000 +
         now.getUTCMinutes() * 1000 * 60 +
         now.getUTCHours() * 1000 * 60 * 60
-    const date = now.toISOString().substring(0, 10)
-    const time = String(ms).padStart(8, '0')
-    const when = `${date}-${time}`
-    if (flags.production) {
-        const gitHash = await new Promise((res, rej) =>
-            exec('git rev-parse --short HEAD', (err, stdout) => {
-                if (err) rej(err)
-                res(stdout.trim())
-            }),
-        )
-        return `${when}-${gitHash}`
-    } else {
-        return when
-    }
+    return String(ms).padStart(8, '0')
 }

package/lib/config.ts

@@ -1,9 +1,11 @@
 import { isAbsolute, resolve } from 'node:path'
+import { createBuildTag } from './build_tag.ts'
 import type {
     DankConfig,
     DankDetails,
     EsbuildConfig,
     PageMapping,
+    ServiceWorkerBuilder,
 } from './dank.ts'
 import { LOG } from './developer.ts'
 import { defaultProjectDirs, type DankDirectories } from './dirs.ts'
@@ -21,7 +23,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'
@@ -33,6 +35,9 @@ export type ResolvedDankConfig = {
     get pages(): Readonly<Record<`/${string}`, PageMapping>>
     get devPages(): Readonly<DankConfig['devPages']>
     get services(): Readonly<DankConfig['services']>
+    get serviceWorkerBuilder(): DankConfig['serviceWorker']
+
+    buildTag(): Promise<string>
 
     reload(): Promise<void>
 }
@@ -60,10 +65,13 @@ export async function loadConfig(
 }
 
 class DankConfigInternal implements ResolvedDankConfig {
+    #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
@@ -119,17 +127,35 @@ class DankConfigInternal implements ResolvedDankConfig {
         return this.#services
     }
 
+    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
+    }
+
     async reload() {
         const userConfig = await resolveConfig(
             this.#modulePath,
             resolveDankDetails(this.#mode, this.#flags),
         )
+        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.#services = Object.freeze(userConfig.services)
+        this.#serviceWorkerBuilder = userConfig.serviceWorker
     }
 }
 
@@ -173,10 +199,12 @@ function resolveDankDetails(
 function validateDankConfig(c: Partial<DankConfig>) {
     try {
         validatePorts(c)
+        validateBuildTag(c.buildTag)
         validatePages(c.pages)
         validateDevPages(c.devPages)
         validateDevServices(c.services)
         validateEsbuildConfig(c.esbuild)
+        validateServiceWorker(c.serviceWorker)
     } catch (e: any) {
         LOG({
             realm: 'config',
@@ -202,6 +230,33 @@ function validatePorts(c: Partial<DankConfig>) {
     }
 }
 
+function validateBuildTag(buildTag: DankConfig['buildTag']) {
+    if (buildTag === null) {
+        return
+    }
+    switch (typeof buildTag) {
+        case 'undefined':
+        case 'string':
+        case 'function':
+            return
+        default:
+            throw Error('DankConfig.buildTag must be a string or function')
+    }
+}
+
+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') {

package/lib/dank.ts

@@ -1,8 +1,8 @@
 import type { Plugin as EsbuildPlugin } from 'esbuild'
 
 export type DankConfig = {
-    // used for releases and service worker caching
-    // buildTag?:  (() => Promise<string> | string) | string
+    // used for service worker caching
+    buildTag?: string | BuildTagBuilder
 
     // customize esbuild configs
     esbuild?: EsbuildConfig
@@ -24,8 +24,20 @@ 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 = {
+    production: boolean
 }
 
+export type BuildTagBuilder = (
+    build: BuildTagParams,
+) => Promise<string> | string
+
 // extend an html entrypoint with url rewriting similar to cdn configurations
 // after trying all webpage, bundle and asset paths, mapping patterns
 // will be tested in the alphabetical order of the webpage paths
@@ -91,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)