@remix-run/node-hmr 0.0.0 → 0.1.0

package/src/index.ts

@@ -0,0 +1,244 @@
+import { fileURLToPath } from 'node:url'
+import process from 'node:process'
+
+import { createHmrSupervisor } from './lib/runner.ts'
+
+/**
+ * Options for running a Node.js entry module with HMR supervision.
+ */
+export interface RunOptions {
+  /**
+   * Configures the parent-owned EventSource server used to coordinate browser HMR, or disables it
+   * with `false`. Enabled with default options when omitted or set to `true`.
+   */
+  browserHmrChannel?: boolean | BrowserHmrChannelOptions
+  /** Working directory used to resolve the entry path and relative watch options. (`process.cwd()`) */
+  cwd?: string
+  /** Arguments passed to the entry module after the entry path. */
+  entryArgs?: readonly string[]
+  /** Complete environment for the child process. (`process.env`) */
+  env?: NodeJS.ProcessEnv
+  /** Node.js arguments passed before the entry path. */
+  nodeArgs?: readonly string[]
+  /** File watching options for the supervised process. */
+  watch?: NodeHmrWatchOptions
+}
+
+/**
+ * Browser HMR event stream options hosted by the parent process.
+ */
+export interface BrowserHmrChannelOptions {
+  /** Hostname for the browser HMR event server. (`'127.0.0.1'`) */
+  host?: string
+  /** Port for the browser HMR event server. Uses an available ephemeral port when omitted. */
+  port?: number
+  /** URL pathname for the browser HMR event stream. (`'/hmr'`) */
+  pathname?: string
+}
+
+/**
+ * File watching options for a Node HMR runner.
+ */
+export interface NodeHmrWatchOptions {
+  /**
+   * Ignore matching glob patterns or file paths. Relative values are resolved
+   * from the runner's `cwd`.
+   */
+  ignore?: readonly string[]
+  /**
+   * Use polling instead of native filesystem events. Defaults to `true` on
+   * Windows and `false` elsewhere.
+   */
+  poll?: boolean
+  /**
+   * Polling interval in milliseconds when `poll` is enabled. Defaults to `100`.
+   */
+  pollInterval?: number
+}
+
+/**
+ * Handle returned by {@link run} for controlling the supervised process.
+ */
+export interface NodeHmrRunner {
+  /**
+   * Stops the runner and waits for the child process to exit.
+   *
+   * @returns A promise that resolves once the runner has stopped.
+   */
+  close(): Promise<void>
+  /**
+   * Current server generation, incremented after every accepted hot update or process restart.
+   */
+  readonly generation: number
+  /**
+   * Waits until the latest update or restart has settled and the current child process is ready.
+   *
+   * If the app uses `emitServerReady()`, restart readiness also waits for that signal.
+   *
+   * @returns A promise that resolves when the latest requested generation is ready.
+   */
+  ready(): Promise<void>
+}
+
+type HmrReadyFetchRetryContext = {
+  /** Child process lifecycle generation that handled the fetch attempt. */
+  generation: number
+  /** Request passed to the wrapped fetch handler. */
+  request: Request
+} & (
+  | {
+      /** Error thrown by the wrapped fetch handler. */
+      error: unknown
+      /** Response is absent when the wrapped fetch handler throws. */
+      response?: never
+    }
+  | {
+      /** Error is absent when the wrapped fetch handler returns a response. */
+      error?: never
+      /** Response returned by the wrapped fetch handler. */
+      response: Response
+    }
+)
+
+/**
+ * Options for {@link createHmrReadyFetch}.
+ */
+export interface HmrReadyFetchOptions {
+  /**
+   * Determines whether a response or thrown error should be retried if the
+   * runner moves to a new generation while the request is in flight. Defaults
+   * to retrying `GET` and `HEAD` requests when the fetch throws or returns
+   * `502`, `503`, or `504`.
+   */
+  shouldRetry?: (context: HmrReadyFetchRetryContext) => boolean | Promise<boolean>
+}
+
+/**
+ * Wraps a fetch handler so requests wait for the current HMR generation to be ready.
+ *
+ * If the wrapped fetch handler returns a retryable response or throws a retryable error, the
+ * request is attempted again only when the runner moved to a new generation while the request was
+ * in flight.
+ *
+ * @param runner HMR runner that controls server readiness.
+ * @param fetch Fetch handler to call once the runner is ready.
+ * @param options Retry behavior for responses and thrown errors.
+ * @returns A fetch handler that waits for HMR readiness before forwarding requests.
+ */
+export function createHmrReadyFetch(
+  runner: NodeHmrRunner,
+  fetch: (request: Request) => Response | Promise<Response>,
+  options: HmrReadyFetchOptions = {},
+): (request: Request) => Promise<Response> {
+  let shouldRetry = options.shouldRetry ?? shouldRetrySafeUnavailableRequest
+
+  return async (request) => {
+    while (true) {
+      await runner.ready()
+      let generation = runner.generation
+
+      try {
+        let response = await fetch(request)
+
+        if (!(await shouldRetry({ generation, request, response }))) {
+          return response
+        }
+
+        await runner.ready()
+        if (runner.generation !== generation) continue
+        return response
+      } catch (error) {
+        await runner.ready()
+        if (
+          runner.generation !== generation &&
+          (await shouldRetry({ error, generation, request }))
+        ) {
+          continue
+        }
+        throw error
+      }
+    }
+  }
+}
+
+/**
+ * Starts a Node.js entry module in a supervised child process and watches its loaded module graph.
+ *
+ * Accepted module changes are applied in place; unaccepted changes restart the child. The returned
+ * handle exposes readiness across both paths and closes the watcher, child process, and browser HMR
+ * event server when stopped.
+ *
+ * @param entry Entry module path, resolved from `options.cwd`.
+ * @param options Runner options.
+ * @returns A runner handle for the supervised process.
+ */
+export function run(entry: string, options: RunOptions = {}): NodeHmrRunner {
+  let supervisor = createHmrSupervisor({
+    browserHmrChannel: normalizeBrowserHmrChannelOptions(options.browserHmrChannel),
+    cwd: options.cwd ?? process.cwd(),
+    entry,
+    entryArgs: [...(options.entryArgs ?? [])],
+    env: options.env ?? process.env,
+    nodeArgs: [...(options.nodeArgs ?? [])],
+    registerPath: resolveRegisterPath(),
+    watch: options.watch,
+  })
+
+  let closed = supervisor.start()
+  closed.catch((error: unknown) => {
+    console.error(error)
+  })
+
+  return {
+    close() {
+      return supervisor.stop()
+    },
+
+    get generation() {
+      return supervisor.generation
+    },
+
+    ready() {
+      return supervisor.ready()
+    },
+  }
+}
+
+function shouldRetrySafeUnavailableRequest({
+  request,
+  response,
+}: HmrReadyFetchRetryContext): boolean {
+  if (request.method !== 'GET' && request.method !== 'HEAD') return false
+
+  return (
+    response === undefined ||
+    response.status === 502 ||
+    response.status === 503 ||
+    response.status === 504
+  )
+}
+
+function normalizeBrowserHmrChannelOptions(
+  options: RunOptions['browserHmrChannel'],
+): BrowserHmrChannelOptions | null {
+  if (options === false) return null
+  if (options === undefined || options === true) return {}
+
+  if (options.port !== undefined) {
+    assertValidPort(options.port)
+  }
+
+  return options
+}
+
+function resolveRegisterPath(): string {
+  let extension = import.meta.url.endsWith('.ts') ? 'ts' : 'js'
+
+  return fileURLToPath(new URL(`./register.${extension}`, import.meta.url))
+}
+
+function assertValidPort(port: number): void {
+  if (!Number.isInteger(port) || port < 0 || port > 65_535) {
+    throw new TypeError(`Invalid browser HMR channel port: ${port}`)
+  }
+}

package/src/lib/browser-events.ts

@@ -0,0 +1,123 @@
+import process from 'node:process'
+
+import { hasNodeHmrParentProcess } from './process-state.ts'
+
+export const defaultBrowserHmrPathname = '/hmr'
+
+/**
+ * Event payload sent to browser HMR clients.
+ */
+export interface HmrEventPayload {
+  /** Event type string consumed by browser HMR clients. */
+  type: string
+  [key: string]: unknown
+}
+
+/** JavaScript or CSS module update sent to a browser HMR client. */
+export type HmrBrowserUpdate =
+  | {
+      /** Importing module whose dependency-accept handler accepts this update. */
+      acceptedPath?: string
+      /** Public URL of the changed JavaScript module. */
+      path: string
+      /** Identifies a JavaScript module update. */
+      type: 'js'
+    }
+  | {
+      /** Public URL of the changed stylesheet. */
+      path: string
+      /** Identifies a stylesheet update. */
+      type: 'css'
+    }
+
+/**
+ * Browser HMR event emitted to connected clients.
+ */
+export type BrowserHmrEvent =
+  | {
+      /** Absolute source file paths that triggered this update. */
+      files?: string[]
+      /** Update timestamp used to bust module and stylesheet caches. */
+      timestamp: number
+      /** Browser update event. */
+      type: 'update'
+      /** JavaScript and CSS updates for the browser to apply. */
+      updates: HmrBrowserUpdate[]
+    }
+  | {
+      /** Absolute source file paths that could not be handled in place. */
+      files?: string[]
+      /** Browser reload event. */
+      type: 'reload'
+    }
+
+/**
+ * File watcher event reported to a browser HMR channel.
+ */
+export type BrowserHmrFileEvent = {
+  /** Filesystem operation observed by the parent watcher. */
+  event: 'add' | 'change' | 'unlink'
+  /** Absolute path of the source file that changed. */
+  filePath: string
+}
+
+/**
+ * Handles file events and returns browser HMR events to emit.
+ *
+ * @param events File additions, changes, and removals reported together by the parent watcher.
+ * @returns Browser events to publish in their returned order.
+ */
+export type BrowserHmrFileEventHandler = (
+  events: readonly BrowserHmrFileEvent[],
+) => Promise<readonly BrowserHmrEvent[]>
+
+/**
+ * Watched file delta for a browser HMR channel.
+ */
+export interface BrowserHmrWatchedFileDelta {
+  /** Absolute source file paths newly required by this channel. */
+  add: readonly string[]
+  /** Absolute source file paths no longer required by this channel. */
+  remove: readonly string[]
+}
+
+/**
+ * Child-process bridge between browser asset tooling and the parent `node-hmr` runtime.
+ *
+ * The channel contributes files to the parent's shared watcher and converts matching file changes
+ * into browser update or reload events. Close it when its owning asset server shuts down.
+ */
+export interface BrowserHmrChannel {
+  /** Absolute URL of the parent-owned EventSource endpoint for browser HMR clients. */
+  readonly url: string
+  /** Closes this channel, unregisters its handlers, and removes its files from the parent watcher. */
+  close(): void
+  /**
+   * Registers a handler that converts matching watcher events into events for browser clients.
+   *
+   * Multiple handlers may be registered; their returned browser events are concatenated. Calling
+   * the returned cleanup function stops invoking this handler without closing the channel.
+   *
+   * @param handler Callback that maps a batch of file changes to browser HMR events.
+   * @returns A cleanup function that unregisters only this handler.
+   */
+  onFileEvents(handler: BrowserHmrFileEventHandler): () => void
+  /**
+   * Adds and removes absolute file paths from the parent process's watcher for this channel.
+   *
+   * Paths remain watched until removed by a later delta or until the channel is closed. Repeated
+   * additions and removals are idempotent.
+   *
+   * @param delta Files to add and remove from the watcher.
+   */
+  updateWatchedFiles(delta: BrowserHmrWatchedFileDelta): void
+}
+
+export function sendHmrEventPayload(payload: HmrEventPayload): void {
+  if (!hasNodeHmrParentProcess()) return
+
+  process.send?.({
+    payload,
+    type: 'node-hmr:child:browser-event-emitted',
+  })
+}

package/src/lib/events.ts

@@ -0,0 +1,61 @@
+import process from 'node:process'
+
+import { hasNodeHmrParentProcess } from './process-state.ts'
+
+export type ServerHmrEvent =
+  | {
+      acceptedUrl?: string
+      filePath: string
+      timestamp: number
+      type: 'update'
+      url: string
+    }
+  | {
+      filePath?: string
+      reason?: string
+      timestamp: number
+      type: 'restart'
+      url?: string
+    }
+
+export interface ServerHmrEventSource {
+  subscribe(listener: (event: ServerHmrEvent) => void): () => void
+}
+
+type ServerHmrEventListener = (event: ServerHmrEvent) => void
+
+class ServerHmrEvents implements ServerHmrEventSource {
+  #listeners = new Set<ServerHmrEventListener>()
+
+  subscribe(listener: ServerHmrEventListener): () => void {
+    this.#listeners.add(listener)
+    return () => {
+      this.#listeners.delete(listener)
+    }
+  }
+
+  emit(event: ServerHmrEvent): void {
+    for (let listener of this.#listeners) {
+      listener(event)
+    }
+  }
+}
+
+export const serverHmrEvents = new ServerHmrEvents()
+
+export function emitServerHmrEvent(event: ServerHmrEvent): void {
+  serverHmrEvents.emit(event)
+}
+
+export function emitServerHmrUpdate(event: Extract<ServerHmrEvent, { type: 'update' }>): void {
+  emitServerHmrEvent(event)
+  if (!hasNodeHmrParentProcess()) return
+
+  process.send?.({
+    acceptedUrl: event.acceptedUrl,
+    filePath: event.filePath,
+    timestamp: event.timestamp,
+    type: 'node-hmr:child:hot-module-updated',
+    url: event.url,
+  })
+}

package/src/lib/hmr-analysis.ts

@@ -0,0 +1,178 @@
+import { parseSync, visitorKeys } from 'oxc-parser'
+import type { Node, Program } from 'oxc-parser'
+
+export interface NodeHmrAnalysis {
+  acceptedDeps: NodeHmrAcceptedDependency[]
+  selfAccepting: boolean
+  usesImportMetaHot: boolean
+}
+
+export interface ResolvedNodeHmrAnalysis {
+  acceptedDeps: string[]
+  selfAccepting: boolean
+  usesImportMetaHot: boolean
+}
+
+export interface NodeHmrAcceptedDependency {
+  end: number
+  specifier: string
+  start: number
+}
+
+const invalidAcceptMessage =
+  'import.meta.hot.accept() can only accept a callback, a string literal, or an array of string literals.'
+
+export function analyzeNodeHmrSource(importerUrl: string, source: string): NodeHmrAnalysis {
+  if (!source.includes('import.meta.hot')) {
+    return {
+      acceptedDeps: [],
+      selfAccepting: false,
+      usesImportMetaHot: false,
+    }
+  }
+
+  let acceptedDeps: NodeHmrAcceptedDependency[] = []
+  let selfAccepting = false
+  let usesImportMetaHot = false
+  let parseResult = parseSync('node-hmr-analysis.js', source, {
+    lang: 'js',
+    sourceType: 'module',
+  })
+
+  if (parseResult.errors.length > 0) {
+    return {
+      acceptedDeps: [],
+      selfAccepting: false,
+      usesImportMetaHot: false,
+    }
+  }
+
+  walkAst(parseResult.program, (node) => {
+    if (isImportMetaHotNode(node)) {
+      usesImportMetaHot = true
+    }
+
+    if (node.type !== 'CallExpression') return
+    if (!isImportMetaHotAcceptCallee(node.callee)) return
+
+    let [firstArgument] = node.arguments
+    if (firstArgument === undefined || isSelfAcceptArgument(firstArgument)) {
+      selfAccepting = true
+      return
+    }
+
+    let deps = getAcceptedDependencies(firstArgument)
+    if (deps === null) {
+      throw new TypeError(invalidAcceptMessage)
+    }
+
+    acceptedDeps.push(...deps)
+  })
+
+  return {
+    acceptedDeps,
+    selfAccepting,
+    usesImportMetaHot,
+  }
+}
+
+function isImportMetaHotAcceptCallee(node: Node): boolean {
+  let callee = unwrapChainExpression(node)
+  if (callee.type !== 'MemberExpression') return false
+  if (callee.computed || !isIdentifierNode(callee.property, 'accept')) return false
+
+  return isImportMetaHotNode(callee.object)
+}
+
+function isImportMetaHotNode(node: Node): boolean {
+  let hot = unwrapChainExpression(node)
+  if (hot.type !== 'MemberExpression') return false
+  if (hot.computed || !isIdentifierNode(hot.property, 'hot')) return false
+
+  let meta = unwrapChainExpression(hot.object)
+  return (
+    meta.type === 'MetaProperty' &&
+    isIdentifierNode(meta.meta, 'import') &&
+    isIdentifierNode(meta.property, 'meta')
+  )
+}
+
+function unwrapChainExpression(node: Node): Node {
+  return node.type === 'ChainExpression' ? node.expression : node
+}
+
+function isIdentifierNode(node: Node, name: string): boolean {
+  return node.type === 'Identifier' && node.name === name
+}
+
+function isSelfAcceptArgument(node: Node): boolean {
+  return (
+    node.type === 'FunctionExpression' ||
+    node.type === 'ArrowFunctionExpression' ||
+    isIdentifierNode(node, 'undefined')
+  )
+}
+
+function getAcceptedDependencies(node: Node): NodeHmrAcceptedDependency[] | null {
+  if (isStringLiteralNode(node)) {
+    return [toAcceptedDependency(node)]
+  }
+
+  if (node.type !== 'ArrayExpression') return null
+
+  let deps: NodeHmrAcceptedDependency[] = []
+  for (let element of node.elements) {
+    if (!isStringLiteralNode(element)) return null
+    deps.push(toAcceptedDependency(element))
+  }
+  return deps
+}
+
+function toAcceptedDependency(node: Node & { end: number; start: number; value: string }) {
+  return {
+    end: node.end - 1,
+    specifier: node.value,
+    start: node.start + 1,
+  }
+}
+
+function walkAst(node: Program | Node, visit: (node: Program | Node) => void): void {
+  visit(node)
+
+  let keys = visitorKeys[node.type]
+  if (!keys) return
+
+  let walkableNode = node as unknown as Record<string, unknown>
+  for (let key of keys) {
+    let value = walkableNode[key]
+    if (Array.isArray(value)) {
+      for (let child of value) {
+        if (isAstNode(child)) {
+          walkAst(child, visit)
+        }
+      }
+      continue
+    }
+
+    if (isAstNode(value)) {
+      walkAst(value, visit)
+    }
+  }
+}
+
+function isAstNode(value: unknown): value is Node {
+  return typeof value === 'object' && value !== null && 'type' in value
+}
+
+function isStringLiteralNode(node: Node | null | undefined): node is Node & {
+  end: number
+  start: number
+  value: string
+} {
+  return (
+    node?.type === 'Literal' &&
+    typeof node.end === 'number' &&
+    typeof node.start === 'number' &&
+    typeof node.value === 'string'
+  )
+}