@eighty4/dank 0.0.4-1 → 0.0.4-3

package/lib/flags.ts

@@ -1,84 +1,21 @@
-import { join, resolve } from 'node:path'
-import { cwd } from 'node:process'
-import type { DankConfig } from './dank.ts'
-
-export type DankBuild = {
-    dirs: ProjectDirs
-    minify: boolean
-    production: boolean
-}
-
-export type ProjectDirs = {
-    buildRoot: string
-    buildWatch: string
-    buildDist: string
-    pages: string
-    pagesResolved: string
-    projectResolved: string
-    projectRootAbs: string
-    public: string
-}
-
-export function resolveBuildFlags(): DankBuild {
-    const flags: DankBuild = {
-        dirs: defaultProjectDirs(cwd()),
-        minify: willMinify(),
-        production: isProductionBuild(),
-    }
-    return {
-        get dirs(): ProjectDirs {
-            return flags.dirs
-        },
-        get minify(): boolean {
-            return flags.minify
-        },
-        get production(): boolean {
-            return flags.production
-        },
-    }
-}
-
-export type DankServe = DankBuild & {
-    dankPort: number
-    esbuildPort: number
+export type DankFlags = {
+    dankPort?: number
+    esbuildPort?: number
     logHttp: boolean
+    minify: boolean
     preview: boolean
+    production: boolean
 }
 
-export function resolveServeFlags(c: DankConfig): DankServe {
-    const preview = isPreviewBuild()
-    const flags: DankServe = {
-        dirs: defaultProjectDirs(cwd()),
-        dankPort: dankPort(c, preview),
-        esbuildPort: esbuildPort(c),
+export function resolveFlags(): Readonly<DankFlags> {
+    return Object.freeze({
+        dankPort: resolveDankPort(),
+        esbuildPort: resolveEsbuildPort(),
         logHttp: willLogHttp(),
         minify: willMinify(),
-        preview,
+        preview: isPreviewBuild(),
         production: isProductionBuild(),
-    }
-    return {
-        get dirs(): ProjectDirs {
-            return flags.dirs
-        },
-        get dankPort(): number {
-            return flags.dankPort
-        },
-        get esbuildPort(): number {
-            return flags.esbuildPort
-        },
-        get logHttp(): boolean {
-            return flags.logHttp
-        },
-        get minify(): boolean {
-            return flags.minify
-        },
-        get preview(): boolean {
-            return flags.preview
-        },
-        get production(): boolean {
-            return flags.production
-        },
-    }
+    })
 }
 
 // `dank serve` will pre-bundle and use service worker
@@ -90,21 +27,18 @@ const isPreviewBuild = () =>
 const isProductionBuild = () =>
     process.env.PRODUCTION === 'true' || process.argv.includes('--production')
 
-// `dank serve` dank port for frontend webserver
-// alternate --preview port for service worker builds
-function dankPort(c: DankConfig, preview: boolean): number {
+// `dank serve` port for frontend webserver
+function resolveDankPort(): number | undefined {
     if (process.env.DANK_PORT?.length) {
         return parsePortEnvVar('DANK_PORT')
     }
-    return preview ? c.previewPort || c.port || 4000 : c.port || 3000
 }
 
-// `dank serve` esbuild port for bundler integration
-function esbuildPort(c: DankConfig): number {
+// `dank serve` port for esbuild bundler integration
+function resolveEsbuildPort(): number | undefined {
     if (process.env.ESBUILD_PORT?.length) {
         return parsePortEnvVar('ESBUILD_PORT')
     }
-    return c.esbuild?.port || 3995
 }
 
 function parsePortEnvVar(name: string): number {
@@ -116,46 +50,6 @@ function parsePortEnvVar(name: string): number {
     }
 }
 
-export function defaultProjectDirs(projectRootAbs: string): ProjectDirs {
-    const pages = 'pages'
-    const dirs: ProjectDirs = {
-        buildRoot: 'build',
-        buildDist: join('build', 'dist'),
-        buildWatch: join('build', 'watch'),
-        pages,
-        pagesResolved: resolve(join(projectRootAbs, pages)),
-        projectResolved: resolve(projectRootAbs),
-        projectRootAbs,
-        public: 'public',
-    }
-    return {
-        get buildRoot(): string {
-            return dirs.buildRoot
-        },
-        get buildDist(): string {
-            return dirs.buildDist
-        },
-        get buildWatch(): string {
-            return dirs.buildWatch
-        },
-        get pages(): string {
-            return dirs.pages
-        },
-        get pagesResolved(): string {
-            return dirs.pagesResolved
-        },
-        get projectResolved(): string {
-            return dirs.projectResolved
-        },
-        get projectRootAbs(): string {
-            return dirs.projectRootAbs
-        },
-        get public(): string {
-            return dirs.public
-        },
-    }
-}
-
 const willMinify = () =>
     isProductionBuild() ||
     process.env.MINIFY === 'true' ||

package/lib/html.ts

@@ -1,6 +1,6 @@
 import EventEmitter from 'node:events'
 import { readFile } from 'node:fs/promises'
-import { dirname, join, relative } from 'node:path'
+import { dirname, isAbsolute, join, relative, resolve } from 'node:path'
 import { extname } from 'node:path/posix'
 import {
     defaultTreeAdapter,
@@ -9,9 +9,11 @@ import {
     parseFragment,
     serialize,
 } from 'parse5'
+import type { ResolvedDankConfig } from './config.ts'
+import { LOG } from './developer.ts'
+import type { Resolver } from './dirs.ts'
+import { DankError } from './errors.ts'
 import type { EntryPoint } from './esbuild.ts'
-import type { DankBuild } from './flags.ts'
-import type { Resolver } from './metadata.ts'
 
 type CommentNode = DefaultTreeAdapterTypes.CommentNode
 type Document = DefaultTreeAdapterTypes.Document
@@ -28,6 +30,8 @@ type PartialReference = {
     commentNode: CommentNode
     // path within pages dir omitting pages/ segment
     fsPath: string
+    // unresolved partial path read from commentNode text
+    specifier: string
 }
 
 type PartialContent = PartialReference & {
@@ -44,7 +48,7 @@ type ImportedScript = {
     entrypoint: EntryPoint
 }
 
-export type HtmlDecoration = {
+type HtmlDecoration = {
     type: 'script'
     js: string
 }
@@ -61,86 +65,103 @@ export type HtmlEntrypointEvents = {
     // Dispatched from HtmlEntrypoint to notify `dank serve` of changes to esbuild entrypoints
     // Parameter `entrypoints` is the esbuild mappings of the input and output paths
     entrypoints: [entrypoints: Array<EntryPoint>]
+    // Dispatched from HtmlEntrypoint when processing HTML is aborted on error
+    error: [e: Error]
     // Dispatched from HtmlEntrypoint to notify when new HtmlEntrypoint.#document output is ready for write
     // Parameter `html` is the updated html content of the page ready to be output to the build dir
     output: [html: string]
-    // Dispatched from HtmlEntrypoint to notify `dank serve` of a partial dependency for an HtmlEntrypoint
-    // Seemingly a duplicate of event `partials` but it keeps relevant state in sync during async io
-    // Parameter `partial` is the fs path to the partial
-    partial: [partial: string]
-    // Dispatched from HtmlEntrypoint to notify `dank serve` of completely resolved imported partials
-    // Parameter `partials` are the fs paths to the partials
-    partials: [partials: Array<string>]
 }
 
 export class HtmlEntrypoint extends EventEmitter<HtmlEntrypointEvents> {
-    #build: DankBuild
-    #decorations?: Array<HtmlDecoration>
+    #c: ResolvedDankConfig
+    #clientJS: ClientJS | null
     #document: Document = defaultTreeAdapter.createDocument()
-    // todo cache entrypoints set for quicker diffing
-    // #entrypoints: Set<string> = new Set()
+    #entrypoints: Set<string> = new Set()
     // path within pages dir omitting pages/ segment
     #fsPath: string
     #partials: Array<PartialContent> = []
     #resolver: Resolver
     #scripts: Array<ImportedScript> = []
     #update: Object = Object()
-    #url: string
+    #url: `/${string}`
 
     constructor(
-        build: DankBuild,
+        c: ResolvedDankConfig,
         resolver: Resolver,
-        url: string,
+        url: `/${string}`,
         fsPath: string,
-        decorations?: Array<HtmlDecoration>,
     ) {
         super({ captureRejections: true })
-        this.#build = build
+        this.#c = c
+        this.#clientJS = ClientJS.initialize(c)
         this.#resolver = resolver
-        this.#decorations = decorations
         this.#url = url
         this.#fsPath = fsPath
         this.on('change', this.#onChange)
-        this.emit('change')
     }
 
     get fsPath(): string {
         return this.#fsPath
     }
 
-    get url(): string {
+    get url(): `/${string}` {
         return this.#url
     }
 
-    async #html(): Promise<string> {
-        try {
-            return await readFile(
-                join(this.#build.dirs.pages, this.#fsPath),
-                'utf8',
-            )
-        } catch (e) {
-            // todo error handling
-            errorExit(this.#fsPath + ' does not exist')
-        }
+    async process() {
+        await this.#onChange()
+    }
+
+    output(hrefs?: HtmlHrefs): string {
+        this.#injectPartials()
+        this.#rewriteHrefs(hrefs)
+        return serialize(this.#document)
+    }
+
+    usesPartial(fsPath: string): boolean {
+        return this.#partials.some(partial => partial.fsPath === fsPath)
     }
 
-    // todo if partial changes, hot swap content in page
-    #onChange = async (_partial?: string) => {
+    #onChange = async () => {
         const update = (this.#update = Object())
-        const html = await this.#html()
+        let html: string
+        try {
+            html = await this.#readFromPages(this.#fsPath)
+        } catch (e) {
+            this.#error(
+                `url \`${this.#url}\` html file \`${join(this.#c.dirs.pages, this.#fsPath)}\` does not exist`,
+            )
+            return
+        }
         const document = parse(html)
         const imports: CollectedImports = {
             partials: [],
             scripts: [],
         }
+        let partials: Array<PartialContent>
         this.#collectImports(document, imports)
-        const partials = await this.#resolvePartialContent(imports.partials)
+        const partialResults = await this.#resolvePartialContent(
+            imports.partials,
+        )
+        partials = partialResults.filter(p => p !== false)
+        // `dank serve` will not throw an error during a partial error, so this emits error and breaks out of `change` event handler
+        if (partials.length !== partialResults.length) {
+            this.#error(
+                `update to \`${join(this.#c.dirs.pages, this.#fsPath)}\` did not update to \`${this.#url}\` because of unresolved partials`,
+            )
+            return
+        }
+        if (this.#clientJS !== null) {
+            const decoration = await this.#clientJS.retrieve(
+                this.#c.esbuildPort,
+            )
+            this.#addScriptDecoration(document, decoration.js)
+        }
         if (update !== this.#update) {
             // another update has started so aborting this one
+            // only do synchronous work after this check
             return
         }
-        this.#addDecorations(document)
-        this.#update = update
         this.#document = document
         this.#partials = partials
         this.#scripts = imports.scripts
@@ -148,30 +169,93 @@ export class HtmlEntrypoint extends EventEmitter<HtmlEntrypointEvents> {
             imports,
             ...partials.map(p => p.imports),
         )
-        // this.#entrypoints = new Set(entrypoints.map(entrypoint => entrypoint.in))
-        this.emit('entrypoints', entrypoints)
-        this.emit(
-            'partials',
-            this.#partials.map(p => p.fsPath),
-        )
+        LOG({
+            realm: 'html',
+            message: 'processed html entrypoint',
+            data: {
+                url: this.#url,
+                html: this.#fsPath,
+                entrypoints: entrypoints.map(ep => ep.in),
+                partials: partials.map(p => p.fsPath),
+            },
+        })
+        if (this.#haveEntrypointsChanged(entrypoints)) {
+            this.emit('entrypoints', entrypoints)
+        }
         if (this.listenerCount('output')) {
             this.emit('output', this.output())
         }
     }
 
-    // Emits `partial` on detecting a partial reference for `dank serve` file watches
-    // to respond to dependent changes
-    // todo safeguard recursive partials that cause circular imports
+    #error(e: DankError | Error | string) {
+        let message: string
+        let error: Error
+        if (typeof e === 'string') {
+            message = e
+            error = new DankError(e)
+        } else {
+            message = e.message
+            error = e
+        }
+        LOG({
+            realm: 'html',
+            message: 'error processing html',
+            data: {
+                url: this.#url,
+                html: this.#fsPath,
+                error: message,
+            },
+        })
+        if (this.listenerCount('error')) {
+            this.emit('error', error)
+        } else {
+            throw error
+        }
+    }
+
+    #haveEntrypointsChanged(entrypoints: Array<EntryPoint>) {
+        const set = new Set(entrypoints.map(entrypoint => entrypoint.in))
+        const changed = set.symmetricDifference(this.#entrypoints).size > 0
+        this.#entrypoints = set
+        return changed
+    }
+
+    async #readFromPages(p: string): Promise<string> {
+        return await readFile(this.#resolver.absPagesPath(p), 'utf8')
+    }
+
     async #resolvePartialContent(
         partials: Array<PartialReference>,
-    ): Promise<Array<PartialContent>> {
+    ): Promise<Array<PartialContent | false>> {
         return await Promise.all(
             partials.map(async p => {
-                this.emit('partial', p.fsPath)
-                const html = await readFile(
-                    join(this.#build.dirs.pages, p.fsPath),
-                    'utf8',
-                )
+                let html: string
+                if (isAbsolute(p.specifier)) {
+                    this.#error(
+                        `partials cannot be referenced with an absolute path like \`${p.specifier}\` in webpage \`${join(this.#c.dirs.pages, this.#fsPath)}\``,
+                    )
+                    return false
+                }
+                if (!this.#resolver.isPagesSubpathInPagesDir(p.fsPath)) {
+                    this.#error(
+                        `partials cannot be referenced from outside the pages dir like \`${p.specifier}\` in webpage \`${join(this.#c.dirs.pages, this.#fsPath)}\``,
+                    )
+                    return false
+                }
+                if (extname(p.fsPath) !== '.html') {
+                    this.#error(
+                        `partial path \`${p.fsPath}\` referenced by \`${this.#fsPath}\` is not a valid partial path`,
+                    )
+                    return false
+                }
+                try {
+                    html = await this.#readFromPages(p.fsPath)
+                } catch (e) {
+                    this.#error(
+                        `partial \`${join('pages', p.fsPath)}\` imported by \`${join('pages', this.#fsPath)}\` does not exist`,
+                    )
+                    return false
+                }
                 const fragment = parseFragment(html)
                 const imports: CollectedImports = {
                     partials: [],
@@ -181,10 +265,8 @@ export class HtmlEntrypoint extends EventEmitter<HtmlEntrypointEvents> {
                     this.#rewritePartialRelativePaths(node, p.fsPath)
                 })
                 if (imports.partials.length) {
-                    // todo recursive partials?
-                    // await this.#resolvePartialContent(imports.partials)
-                    errorExit(
-                        `partial ${p.fsPath} cannot recursively import partials`,
+                    this.#error(
+                        `partials cannot import another partial like \`${join(this.#c.dirs.pages, p.fsPath)}\``,
                     )
                 }
                 const content: PartialContent = {
@@ -219,35 +301,16 @@ export class HtmlEntrypoint extends EventEmitter<HtmlEntrypointEvents> {
         }
     }
 
-    #addDecorations(document: Document) {
-        if (!this.#decorations?.length) {
-            return
-        }
-        for (const decoration of this.#decorations) {
-            switch (decoration.type) {
-                case 'script':
-                    const scriptNode = parseFragment(
-                        `<script type="module">${decoration.js}</script>`,
-                    ).childNodes[0]
-                    const htmlNode = document.childNodes.find(
-                        node => node.nodeName === 'html',
-                    ) as ParentNode
-                    const headNode = htmlNode.childNodes.find(
-                        node => node.nodeName === 'head',
-                    ) as ParentNode | undefined
-                    defaultTreeAdapter.appendChild(
-                        headNode || htmlNode,
-                        scriptNode,
-                    )
-                    break
-            }
-        }
-    }
-
-    output(hrefs?: HtmlHrefs): string {
-        this.#injectPartials()
-        this.#rewriteHrefs(hrefs)
-        return serialize(this.#document)
+    #addScriptDecoration(document: Document, js: string) {
+        const scriptNode = parseFragment(`<script type="module">${js}</script>`)
+            .childNodes[0]
+        const htmlNode = document.childNodes.find(
+            node => node.nodeName === 'html',
+        ) as ParentNode
+        const headNode = htmlNode.childNodes.find(
+            node => node.nodeName === 'head',
+        ) as ParentNode | undefined
+        defaultTreeAdapter.appendChild(headNode || htmlNode, scriptNode)
     }
 
     // rewrites hrefs to content hashed urls
@@ -261,7 +324,7 @@ export class HtmlEntrypoint extends EventEmitter<HtmlEntrypointEvents> {
 
     async #injectPartials() {
         for (const { commentNode, fragment } of this.#partials) {
-            if (!this.#build.production) {
+            if (!this.#c.flags.production) {
                 defaultTreeAdapter.insertBefore(
                     commentNode.parentNode!,
                     defaultTreeAdapter.createCommentNode(commentNode.data),
@@ -275,7 +338,7 @@ export class HtmlEntrypoint extends EventEmitter<HtmlEntrypointEvents> {
                     commentNode,
                 )
             }
-            if (this.#build.production) {
+            if (this.#c.flags.production) {
                 defaultTreeAdapter.detachNode(commentNode)
             }
         }
@@ -293,24 +356,11 @@ export class HtmlEntrypoint extends EventEmitter<HtmlEntrypointEvents> {
             if (childNode.nodeName === '#comment' && 'data' in childNode) {
                 const partialMatch = childNode.data.match(/\{\{(?<pp>.+)\}\}/)
                 if (partialMatch) {
-                    const partialSpecifier = partialMatch.groups!.pp.trim()
-                    if (partialSpecifier.startsWith('/')) {
-                        errorExit(
-                            `partial ${partialSpecifier} in webpage ${this.#fsPath} cannot be an absolute path`,
-                        )
-                    }
-                    const partialPath = join(
-                        dirname(this.#fsPath),
-                        partialSpecifier,
-                    )
-                    if (!this.#resolver.isPagesSubpathInPagesDir(partialPath)) {
-                        errorExit(
-                            `partial ${partialSpecifier} in webpage ${this.#fsPath} cannot be outside of the pages directory`,
-                        )
-                    }
+                    const specifier = partialMatch.groups!.pp.trim()
                     collection.partials.push({
-                        fsPath: partialPath,
                         commentNode: childNode,
+                        fsPath: join(dirname(this.#fsPath), specifier),
+                        specifier: specifier,
                     })
                 }
             } else if (childNode.nodeName === 'script') {
@@ -343,10 +393,10 @@ export class HtmlEntrypoint extends EventEmitter<HtmlEntrypointEvents> {
         href: string,
         elem: Element,
     ): ImportedScript {
-        const inPath = join(this.#build.dirs.pages, dirname(this.#fsPath), href)
+        const inPath = join(this.#c.dirs.pages, dirname(this.#fsPath), href)
         if (!this.#resolver.isProjectSubpathInPagesDir(inPath)) {
-            errorExit(
-                `href ${href} in webpage ${this.#fsPath} cannot reference sources outside of the pages directory`,
+            throw new DankError(
+                `href \`${href}\` in webpage \`${join(this.#c.dirs.pages, this.#fsPath)}\` cannot reference sources outside of the pages directory`,
             )
         }
         let outPath = join(dirname(this.#fsPath), href)
@@ -406,8 +456,42 @@ function rewriteHrefs(scripts: Array<ImportedScript>, hrefs?: HtmlHrefs) {
     }
 }
 
-// todo evented error handling so HtmlEntrypoint can be unit tested
-function errorExit(msg: string): never {
-    console.log(`\u001b[31merror:\u001b[0m`, msg)
-    process.exit(1)
+class ClientJS {
+    static #instance: ClientJS | null = null
+
+    static initialize(c: ResolvedDankConfig): ClientJS | null {
+        if (c.mode === 'build' || c.flags.preview) {
+            return null
+        } else if (!ClientJS.#instance) {
+            ClientJS.#instance = new ClientJS(c.esbuildPort)
+        }
+        return ClientJS.#instance
+    }
+
+    #esbuildPort: number
+    #read: Promise<string>
+    #result: Promise<HtmlDecoration>
+
+    private constructor(esbuildPort: number) {
+        this.#esbuildPort = esbuildPort
+        this.#read = readFile(
+            resolve(import.meta.dirname, join('..', 'client', 'client.js')),
+            'utf-8',
+        )
+        this.#result = this.#read.then(this.#transform)
+    }
+
+    async retrieve(esbuildPort: number): Promise<HtmlDecoration> {
+        if (esbuildPort !== this.#esbuildPort) {
+            this.#result = this.#read.then(this.#transform)
+        }
+        return await this.#result
+    }
+
+    #transform = (js: string): HtmlDecoration => {
+        return {
+            type: 'script',
+            js: js.replace('3995', '' + this.#esbuildPort),
+        }
+    }
 }