jq79 0.5.9 → 0.5.11

package/dev/cli.ts

@@ -1,11 +1,12 @@
-import { devServer } from "./dev"
+import { devServer, type WatchEntry } from "./dev"
 
 // the jq79 command. One subcommand so far:
 //
 //   npx jq79 dev [dir] [--port 4179] [--host localhost]
 //
 // This is the entry point the no-bundle path deserves: someone who chose jq79
-// to avoid a toolchain shouldn't have to write a script to get a dev server.
+// to avoid a toolchain shouldn't have to write a script to get a dev server -
+// which is also why every devServer option is reachable from here.
 
 const USAGE = `jq79 - a mini reactive component library
 
@@ -15,6 +16,9 @@ usage:
 options:
   -p, --port <port>     port to listen on (default: 4179)
   -H, --host <host>     host to bind (default: localhost)
+  -w, --watch <glob>    also watch this path or glob, reloading on a change
+                        (repeatable; handlers need the js api)
+      --header <h>      response header, "name: value" (repeatable)
   -h, --help            show this message
 `
 
@@ -28,13 +32,36 @@ if (command !== "dev" || rest.includes("-h") || rest.includes("--help")) {
   process.exit(unknown ? 1 : 0)
 }
 
-const options: { rootDir?: string; port?: number; host?: string } = {}
+const options: {
+  rootDir?: string
+  port?: number
+  host?: string
+  watch?: WatchEntry[]
+  headers?: Record<string, string>
+} = {}
 
 for (let i = 0; i < rest.length; i++) {
   const arg = rest[i]
   if (arg === "-p" || arg === "--port") options.port = Number(rest[++i])
   else if (arg === "-H" || arg === "--host") options.host = rest[++i]
-  else if (!arg.startsWith("-")) options.rootDir ??= arg // the directory to serve
+  else if (arg === "-w" || arg === "--watch") {
+    // no handler from here: an argument can't carry a function, and an entry
+    // without one reloads the page, which is all a terminal was ever going to ask for
+    const pattern = rest[++i]
+    if (!pattern) {
+      console.error("--watch takes a path or glob")
+      process.exit(1)
+    }
+    ;(options.watch ??= []).push({ pattern })
+  } else if (arg === "--header") {
+    // split on the first colon only: a value can hold one (a url, a port)
+    const [name, ...value] = (rest[++i] ?? "").split(":")
+    if (!name || !value.length) {
+      console.error(`--header takes "name: value"`)
+      process.exit(1)
+    }
+    ;(options.headers ??= {})[name.trim()] = value.join(":").trim()
+  } else if (!arg.startsWith("-")) options.rootDir ??= arg // the directory to serve
   else {
     console.error(`unknown option: ${arg}\n${USAGE}`)
     process.exit(1)
@@ -46,7 +73,12 @@ if (options.port !== undefined && !Number.isInteger(options.port)) {
   process.exit(1)
 }
 
-const server = await devServer(options)
+// a --watch path that isn't there refuses to start; the message names it, and a
+// stack trace over a typo in an argument would only bury it
+const server = await devServer(options).catch((error: unknown) => {
+  console.error(error instanceof Error ? error.message : error)
+  process.exit(1)
+})
 
 console.log(`jq79 dev → ${server.url}`)
 

package/dev/dev.ts

@@ -1,7 +1,7 @@
 import { createServer, type Server, type IncomingMessage, type ServerResponse } from "node:http"
 import { readFile, realpath, stat } from "node:fs/promises"
 import { watch, type FSWatcher } from "node:fs"
-import { basename, extname, join, relative, resolve, sep } from "node:path"
+import { basename, dirname, extname, isAbsolute, join, matchesGlob, relative, resolve, sep } from "node:path"
 
 // A dev server for the no-bundle path: serve a directory of .html components
 // over HTTP, watch it, and hot-reload the components that changed.
@@ -29,6 +29,32 @@ export interface DevServerOptions {
   port?: number
   // default: localhost
   host?: string
+  // response headers to send on everything - a static host is configured, and
+  // these are that configuration (default: none)
+  headers?: Record<string, string>
+  // the same thing per request: a hook gets the request and its response before
+  // anything has been written to it (default: none)
+  beforeResponse?: ResponseHook[]
+  // what to watch on top of rootDir, and what to do about it (default: none)
+  watch?: WatchEntry[]
+}
+
+// runs on every response the server makes - a page, a component, the client,
+// the event stream, a 404 - with nothing written yet, so `res.setHeader` still
+// applies. A hook that answers the request itself (`res.end`) is left alone
+export type ResponseHook = (req: IncomingMessage, res: ServerResponse) => void | Promise<void>
+
+// the handler gets every file of the burst that woke it, absolute, so a save
+// that touches three of them is one build rather than three
+export type WatchHandler = (files: string[]) => void | Promise<void>
+
+export interface WatchEntry {
+  // glob(s) resolved against the cwd, like rootDir: "styles/**/*.scss". A bare
+  // directory means everything under it
+  pattern: string | string[]
+  // what a match runs. Without one, a match outside the served root reloads the
+  // page - which is the only other thing a file served from nowhere can do
+  fn?: WatchHandler
 }
 
 export interface DevServer {
@@ -41,6 +67,10 @@ const CONTENT_TYPES: Record<string, string> = {
   ".html": "text/html; charset=utf-8",
   ".js": "text/javascript; charset=utf-8",
   ".mjs": "text/javascript; charset=utf-8",
+  // the streaming WebAssembly APIs reject every other type, including the
+  // default below - a module served as octet-stream still runs, but it is
+  // buffered whole instead of compiling as it downloads
+  ".wasm": "application/wasm",
   ".json": "application/json; charset=utf-8",
   ".css": "text/css; charset=utf-8",
   ".svg": "image/svg+xml",
@@ -106,6 +136,16 @@ export const devServer = async (options: DevServerOptions = {}): Promise<DevServ
   const root = await realpath(resolve(options.rootDir ?? "."))
   const host = options.host ?? "localhost"
 
+  // a configured header goes on every response, which is the one thing
+  // content-type and content-length cannot do - each describes the bytes of a
+  // single response. Dropped here rather than at write time, so that either of
+  // them still standing by then can only have come from a hook, which saw the
+  // request and is entitled to say
+  const headers = Object.entries(options.headers ?? {}).filter(
+    ([name]) => !["content-type", "content-length"].includes(name.toLowerCase()),
+  )
+  const hooks = options.beforeResponse ?? []
+
   const clients = new Set<ServerResponse>()
 
   const send = (event: string, data: unknown) => {
@@ -115,6 +155,18 @@ export const devServer = async (options: DevServerOptions = {}): Promise<DevServ
 
   // --- serving ---------------------------------------------------------------
 
+  // what the response says about its own bytes, written last so the layers
+  // below can't contradict it. A hook is the one exception: it saw the request,
+  // so it is entitled to an opinion about what these bytes *are* - never about
+  // how many there are, since a wrong content-length truncates the body or
+  // hangs the socket
+  const head = (res: ServerResponse, status: number, own: Record<string, string | number> = {}) => {
+    res.removeHeader("content-length")
+    const write = { ...own }
+    if (res.hasHeader("content-type")) delete write["content-type"]
+    return res.writeHead(status, write)
+  }
+
   const serveStatic = async (req: IncomingMessage, res: ServerResponse, pathname: string) => {
     // a URL path is not a file path: decode it, then keep the result inside the
     // root (".." in a request must not walk out of the served directory)
@@ -122,11 +174,11 @@ export const devServer = async (options: DevServerOptions = {}): Promise<DevServ
     try {
       file = resolve(join(root, decodeURIComponent(pathname)))
     } catch {
-      res.writeHead(400).end("bad request")
+      head(res, 400).end("bad request")
       return
     }
     if (file !== root && !file.startsWith(root + sep)) {
-      res.writeHead(403).end("forbidden")
+      head(res, 403).end("forbidden")
       return
     }
 
@@ -136,7 +188,7 @@ export const devServer = async (options: DevServerOptions = {}): Promise<DevServ
         // static host: /docs rendered as-is would resolve its relative links
         // against the parent ("img.png" -> /img.png instead of /docs/img.png)
         if (!pathname.endsWith("/")) {
-          res.writeHead(301, { location: pathname + "/" }).end()
+          head(res, 301, { location: pathname + "/" }).end()
           return
         }
         file = join(file, "index.html")
@@ -150,39 +202,60 @@ export const devServer = async (options: DevServerOptions = {}): Promise<DevServ
       const html = type.startsWith("text/html") && isDocument(req)
       const payload = html ? Buffer.from(injectClient(body.toString("utf8"))) : body
 
-      res.writeHead(200, {
-        "content-type": type,
-        "content-length": payload.byteLength,
-        "cache-control": "no-store", // the file on disk is always the truth here
-      })
+      head(res, 200, { "content-type": type, "content-length": payload.byteLength })
       res.end(payload)
     } catch {
-      res.writeHead(404, { "content-type": "text/plain; charset=utf-8" }).end("not found")
+      head(res, 404, { "content-type": "text/plain; charset=utf-8" }).end("not found")
     }
   }
 
-  const server: Server = createServer((req, res) => {
+  // three layers, general to specific, each one free to replace the last: the
+  // server's own defaults, the configured headers over them, and a hook - which
+  // saw the request - over those. They go on with setHeader rather than into an
+  // object, because setHeader is case-insensitive where an object is not: a
+  // "Cache-Control" replaces the cache-control below it instead of arriving
+  // beside it, and the same goes for whatever a hook names
+  const handle = async (req: IncomingMessage, res: ServerResponse) => {
+    res.setHeader("cache-control", "no-store") // the file on disk is always the truth here
+    for (const [name, value] of headers) res.setHeader(name, value)
+    for (const hook of hooks) await hook(req, res)
+
+    // a hook can answer the request itself, and one that did needs nothing else
+    if (res.headersSent || res.writableEnded) return
+
     const pathname = (req.url ?? "/").split(/[?#]/)[0]
 
     if (pathname === CLIENT_URL) {
-      res.writeHead(200, { "content-type": "text/javascript; charset=utf-8", "cache-control": "no-store" })
+      head(res, 200, { "content-type": "text/javascript; charset=utf-8" })
       res.end(CLIENT)
       return
     }
 
     if (pathname === EVENTS_URL) {
-      res.writeHead(200, {
-        "content-type": "text/event-stream",
-        "cache-control": "no-store",
-        connection: "keep-alive",
-      })
+      head(res, 200, { "content-type": "text/event-stream", connection: "keep-alive" })
       res.write(": jq79\n\n") // opens the stream, so the browser fires onopen
       clients.add(res)
       req.on("close", () => clients.delete(res))
       return
     }
 
-    void serveStatic(req, res, pathname)
+    await serveStatic(req, res, pathname)
+  }
+
+  const server: Server = createServer((req, res) => {
+    // a hook is someone's code, and the watch handlers already settled what that
+    // means around here: report it and stay up. This one owes the browser a
+    // reply as well, because a socket nobody answers hangs the page
+    void handle(req, res).catch(error => {
+      console.error(`jq79 dev: failed to respond to ${req.url}\n`, error)
+      if (!res.headersSent) {
+        // whatever the hook had said about the bytes, it is not what is being
+        // sent now - and a content-length it set before throwing would hang this
+        res.removeHeader("content-length")
+        res.writeHead(500, { "content-type": "text/plain; charset=utf-8" })
+      }
+      if (!res.writableEnded) res.end("internal error")
+    })
   })
 
   // --- watching --------------------------------------------------------------
@@ -194,8 +267,63 @@ export const devServer = async (options: DevServerOptions = {}): Promise<DevServ
   // atomic write); collapsing per file keeps that down to one push
   const pending = new Map<string, NodeJS.Timeout>()
 
-  const changed = async (rel: string) => {
-    const file = join(root, rel)
+  // a pattern is written against the cwd (`resolve` reads it the same way), and
+  // captured here so a later chdir can't move what the globs mean
+  const cwd = process.cwd()
+
+  type Entry = {
+    patterns: string[]
+    fn?: WatchHandler
+    batch: Set<string>
+    timer?: NodeJS.Timeout
+    running: boolean
+  }
+
+  const entries: Entry[] = (options.watch ?? []).map(entry => ({
+    patterns: [entry.pattern].flat(),
+    fn: entry.fn,
+    batch: new Set(),
+    running: false,
+  }))
+
+  const claims = (entry: Entry, file: string) =>
+    entry.patterns.some(pattern =>
+      matchesGlob(isAbsolute(pattern) ? posix(file) : posix(relative(cwd, file)), pattern),
+    )
+
+  // a burst is one call: the handler is a build step, and building once per file
+  // of a save that touched four is three builds nobody asked for
+  const collect = (entry: Entry, file: string) => {
+    entry.batch.add(file)
+    clearTimeout(entry.timer)
+    entry.timer = setTimeout(() => void fire(entry), 30)
+  }
+
+  const fire = async (entry: Entry) => {
+    if (entry.running || !entry.batch.size) return
+    const files = [...entry.batch]
+    entry.batch.clear()
+    entry.running = true
+    try {
+      await entry.fn?.(files)
+    } catch (error) {
+      // a handler is someone's build script, and a build that fails is a normal
+      // morning. Reporting it and staying up beats taking the server with it
+      console.error(`jq79 dev: watch handler for ${entry.patterns.join(", ")} failed\n`, error)
+    } finally {
+      entry.running = false
+      if (entry.batch.size) void fire(entry) // saved again while it ran
+    }
+  }
+
+  // `dir` is the directory whose watcher reported this - only needed for the
+  // macOS quirk below, and only when the file turns out not to exist
+  const changed = async (file: string, dir: string) => {
+    // where the browser knows the file from, which only exists for a file under
+    // the served root: a watched path outside it is served from nowhere, so
+    // there is no url for the runtime to match an instance against
+    const rel = relative(root, file)
+    const served = !!rel && !rel.startsWith("..")
 
     let src: string | null = null
     try {
@@ -203,33 +331,101 @@ export const devServer = async (options: DevServerOptions = {}): Promise<DevServ
       // the file itself is already on its way - acting on both would reload the
       // page every time a component is saved
       if ((await stat(file)).isDirectory()) return
-      if (rel.endsWith(".html")) src = await readFile(file, "utf8")
+      if (served && file.endsWith(".html")) src = await readFile(file, "utf8")
     } catch {
       // gone: deleted, or renamed away - and there is nothing to swap in, so the
       // page has to reload. Unless it was never there: macOS reports a change to
-      // the watched directory *itself* under its own basename, which resolves to
-      // a path inside it that does not exist
-      if (rel === basename(root)) return
+      // a watched directory *itself* under its own basename, which resolves to a
+      // path inside it that does not exist
+      if (file === join(dir, basename(dir))) return
     }
 
-    // the url is the one the component was served from, because that is what the
-    // runtime resolves its instances' filenames against
-    const url = "/" + posix(rel)
-    if (src === null) send("reload", { url })
-    else send("update", { url, src })
-  }
+    // every entry that names this file gets it, wherever the file lives. What
+    // the root does with its own files is not up for negotiation: no pattern can
+    // switch hot reload off, so a handler can never cost you the thing you came
+    // for by matching more than its author meant it to
+    const claimed = entries.filter(entry => claims(entry, file))
+    claimed.forEach(entry => entry.fn && collect(entry, file))
+
+    if (served) {
+      // the url is the one the component was served from, because that is what
+      // the runtime resolves its instances' filenames against
+      const url = "/" + posix(rel)
+      if (src === null) send("reload", { url })
+      else send("update", { url, src })
+      return
+    }
 
-  const watcher: FSWatcher = watch(root, { recursive: true }, (_event, filename) => {
-    if (!filename) return
-    const rel = relative(root, resolve(root, filename.toString()))
-    if (!rel || rel.startsWith("..") || ignored(rel)) return
+    // outside the root a handler *is* the answer: it ran, and whatever it writes
+    // into the served directory comes back round as a change of its own, with a
+    // url. An entry with no handler is asking for the page, and gets a path
+    // relative to the root - the client only logs it, and an absolute one would
+    // publish the machine's layout to the page
+    if (claimed.some(entry => !entry.fn)) send("reload", { url: posix(rel) })
+  }
 
-    clearTimeout(pending.get(rel))
-    pending.set(rel, setTimeout(() => {
-      pending.delete(rel)
-      void changed(rel)
+  const queue = (file: string, dir: string) => {
+    clearTimeout(pending.get(file))
+    pending.set(file, setTimeout(() => {
+      pending.delete(file)
+      void changed(file, dir)
     }, 30))
-  })
+  }
+
+  const watchers: FSWatcher[] = []
+
+  // a directory is watched whole. A single file is watched through the directory
+  // it sits in (`only` filtering the rest back out), because a watcher on a file
+  // holds its inode, and an editor's atomic save renames a new one over it - the
+  // watcher survives as a handle on a file nothing will ever write to again
+  const watchTree = (dir: string, only?: string) => {
+    watchers.push(watch(dir, { recursive: !only }, (_event, filename) => {
+      if (!filename) return
+      const file = resolve(dir, filename.toString())
+      const rel = relative(dir, file)
+      if (!rel || rel.startsWith("..")) return
+      if (only ? rel !== only : ignored(rel)) return
+      queue(file, dir)
+    }))
+  }
+
+  // a glob is a filter and a watcher needs a directory to open, so the watch
+  // starts at the literal head of the pattern - everything before the first
+  // magic character. "styles/**/*.scss" opens styles/, "**/*.scss" opens the cwd
+  const literalHead = (pattern: string) => {
+    const parts = pattern.split("/")
+    const magic = parts.findIndex(part => /[*?[\]{}!]/.test(part))
+    return resolve(magic === -1 ? pattern : parts.slice(0, magic).join("/") || ".")
+  }
+
+  // the patterns are resolved like rootDir, against the cwd, and all checked
+  // before anything is watched: a path that isn't there is a typo, and a watcher
+  // that silently isn't running is worse than a server that won't start
+  const extra = new Map<string, { dir: string; only?: string }>()
+  for (const entry of entries) {
+    for (const [i, pattern] of entry.patterns.entries()) {
+      const head = literalHead(pattern)
+      const info = await stat(head).catch(() => null)
+      if (!info) throw new Error(`jq79 dev: nothing to watch at ${head}`)
+
+      // a bare directory means everything under it, which is what it looks like
+      // it means - as a pattern it would watch the directory and match nothing
+      // in it, and the mistake is invisible until a save doesn't fire
+      if (info.isDirectory() && head === resolve(pattern)) {
+        entry.patterns[i] = pattern.replace(/\/+$/, "") + "/**"
+      }
+
+      // real paths on both sides, so a symlink pointing out of the root reads as
+      // what it is - outside, and not covered by the recursive watch below
+      const real = await realpath(head)
+      if (real === root || real.startsWith(root + sep)) continue // already watched
+      const watched = info.isDirectory() ? { dir: real } : { dir: dirname(real), only: basename(real) }
+      extra.set(`${watched.dir}\0${watched.only ?? ""}`, watched) // two patterns can share a head
+    }
+  }
+
+  watchTree(root)
+  extra.forEach(({ dir, only }) => watchTree(dir, only))
 
   // proxies and load balancers cut an idle stream; a comment every 30s is the
   // conventional way to keep it open. unref'd, so it never holds the process up
@@ -250,8 +446,9 @@ export const devServer = async (options: DevServerOptions = {}): Promise<DevServ
     close: () =>
       new Promise(done => {
         clearInterval(heartbeat)
-        watcher.close()
+        watchers.forEach(watcher => watcher.close())
         pending.forEach(clearTimeout)
+        entries.forEach(entry => clearTimeout(entry.timer))
         clients.forEach(client => client.end())
         clients.clear()
         server.close(() => done())