@remix-run/node-hmr 0.0.0 → 0.1.0

package/dist/register.js

@@ -0,0 +1,317 @@
+import { registerHooks } from 'node:module';
+import { isAbsolute, relative } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { SourceMapConsumer, SourceMapGenerator } from 'source-map-js/source-map.js';
+import { analyzeNodeHmrSource, } from './lib/hmr-analysis.js';
+import { markNodeHmrParentProcess } from './lib/process-state.js';
+import { installNodeHmrRuntime } from './lib/runtime.js';
+markNodeHmrParentProcess();
+const runtime = installNodeHmrRuntime({
+    browserEventUrl: getBrowserEventUrl(),
+});
+const rootPath = getRegisterUrlParam('rootPath');
+let invalidatedUrlTimestamps = new Map();
+let updateQueue = Promise.resolve();
+registerHooks({
+    resolve(specifier, context, nextResolve) {
+        let result = nextResolve(specifier, context);
+        reportModuleImport(context.parentURL, result.url);
+        return result;
+    },
+    load(url, context, nextLoad) {
+        let result = nextLoad(url, context);
+        let source = result.source;
+        if (!shouldTransformModule(url, result.format, source))
+            return result;
+        let canonicalUrl = getCanonicalUrl(url);
+        let transformedSource = transformSource(canonicalUrl, source);
+        transformedSource = rewriteInvalidatedImports(canonicalUrl, transformedSource);
+        let hmrAnalysis = analyzeNodeHmrSource(canonicalUrl, transformedSource);
+        if (!hmrAnalysis.usesImportMetaHot) {
+            reportModuleUpdate(canonicalUrl, {
+                acceptedDeps: [],
+                selfAccepting: false,
+                usesImportMetaHot: false,
+            });
+            return {
+                ...result,
+                source: transformedSource,
+            };
+        }
+        reportModuleUpdate(canonicalUrl, {
+            acceptedDeps: [],
+            selfAccepting: hmrAnalysis.selfAccepting,
+            usesImportMetaHot: true,
+        });
+        return {
+            ...result,
+            source: injectHotContext(canonicalUrl, transformedSource, hmrAnalysis),
+        };
+    },
+});
+function getRegisterUrlParam(name) {
+    let value = new URL(import.meta.url).searchParams.get(name);
+    return value ?? undefined;
+}
+function getBrowserEventUrl() {
+    let eventUrl = getRegisterUrlParam('browserEventUrl');
+    if (eventUrl === undefined)
+        return undefined;
+    return isHttpUrl(eventUrl) ? eventUrl : undefined;
+}
+function isHttpUrl(value) {
+    try {
+        let url = new URL(value);
+        return url.protocol === 'http:' || url.protocol === 'https:';
+    }
+    catch {
+        return false;
+    }
+}
+process.on('message', (message) => {
+    if (isBrowserHmrFileEventsMessage(message)) {
+        runtime.handleBrowserHmrFileEvents(message.requestId, message.events);
+        return;
+    }
+    if (!isHmrUpdateMessage(message))
+        return;
+    updateQueue = updateQueue.then(() => handleHotUpdateMessage(message));
+    void updateQueue;
+});
+process.once('SIGINT', () => disposeOnSignal('SIGINT'));
+process.once('SIGTERM', () => disposeOnSignal('SIGTERM'));
+function shouldTransformModule(url, format, source) {
+    if (!url.startsWith('file:'))
+        return false;
+    if (format !== 'module')
+        return false;
+    if (typeof source !== 'string')
+        return false;
+    return true;
+}
+function injectHotContext(url, source, hmr) {
+    let resolveDependencyExpression = `(specifier) => { let url = new URL(import.meta.resolve(specifier)); url.search = ''; url.hash = ''; return url.href }`;
+    let sourceWithMap = extractInlineSourceMap(source);
+    let prelude = [
+        `const __remixNodeHmrResolveDependency = ${resolveDependencyExpression};`,
+        `globalThis.__remixNodeHmr.reportAcceptedDependencies(${JSON.stringify(url)}, ${getAcceptedDependencyExpression(hmr)});`,
+        `import.meta.hot = globalThis.__remixNodeHmr.createHotContext(${JSON.stringify(url)}, __remixNodeHmrResolveDependency);`,
+    ].join('\n');
+    let injectedSource = `${prelude}\n${sourceWithMap.code}`;
+    let injectionSourceMap = createLineOffsetSourceMap(url, sourceWithMap.code, getLineCount(prelude));
+    let sourceMap = sourceWithMap.sourceMap === null
+        ? injectionSourceMap
+        : composeSourceMaps(injectionSourceMap, sourceWithMap.sourceMap);
+    return appendInlineSourceMap(injectedSource, sourceMap);
+}
+function getAcceptedDependencyExpression(hmr) {
+    return `[${hmr.acceptedDeps
+        .map((acceptedDep) => `__remixNodeHmrResolveDependency(${JSON.stringify(acceptedDep.specifier)})`)
+        .join(', ')}]`;
+}
+function transformSource(url, source) {
+    let filePath = fileURLToPath(url);
+    if (url.includes('/node_modules/') ||
+        (rootPath !== undefined && !isInsideRoot(filePath, rootPath))) {
+        return source;
+    }
+    return source;
+}
+function rewriteInvalidatedImports(url, source) {
+    if (invalidatedUrlTimestamps.size === 0)
+        return source;
+    let replacements = [];
+    let staticSpecifierPattern = /\b(?:import\s+(?:[^'"()]*?\s+from\s*)?|export\s+[^'"()]*?\s+from\s*)(["'])([^"']+)\1/g;
+    for (let match of source.matchAll(staticSpecifierPattern)) {
+        let quote = match[1];
+        let specifier = match[2];
+        if (quote === undefined || specifier === undefined || match.index === undefined)
+            continue;
+        let resolvedUrl = new URL(specifier, url).href;
+        let timestamp = invalidatedUrlTimestamps.get(getCanonicalUrl(resolvedUrl));
+        if (timestamp === undefined)
+            continue;
+        let specifierStart = match.index + match[0].length - specifier.length - quote.length;
+        replacements.push({
+            end: specifierStart + specifier.length,
+            specifier: addTimestampQuery(specifier, timestamp),
+            start: specifierStart,
+        });
+    }
+    if (replacements.length === 0)
+        return source;
+    let rewrittenSource = '';
+    let position = 0;
+    for (let replacement of replacements) {
+        rewrittenSource += source.slice(position, replacement.start);
+        rewrittenSource += replacement.specifier;
+        position = replacement.end;
+    }
+    rewrittenSource += source.slice(position);
+    return rewrittenSource;
+}
+function reportModuleUpdate(url, hmr) {
+    process.send?.({
+        type: 'node-hmr:child:module-analyzed',
+        url,
+        filePath: fileURLToPath(url),
+        hmr,
+    });
+}
+function reportModuleImport(parentUrl, url) {
+    if (parentUrl === undefined)
+        return;
+    let canonicalParentUrl = getCanonicalUrl(parentUrl);
+    let canonicalUrl = getCanonicalUrl(url);
+    if (!canonicalParentUrl.startsWith('file:') || !canonicalUrl.startsWith('file:'))
+        return;
+    process.send?.({
+        type: 'node-hmr:child:module-imported',
+        importerFilePath: fileURLToPath(canonicalParentUrl),
+        importerUrl: canonicalParentUrl,
+        depFilePath: fileURLToPath(canonicalUrl),
+        depUrl: canonicalUrl,
+    });
+}
+function getCanonicalUrl(url) {
+    let parsedUrl = new URL(url);
+    parsedUrl.search = '';
+    parsedUrl.hash = '';
+    return parsedUrl.href;
+}
+function addTimestampQuery(specifier, timestamp) {
+    return `${specifier}${specifier.includes('?') ? '&' : '?'}t=${timestamp}`;
+}
+function isInsideRoot(filePath, root) {
+    let relativePath = relative(root, filePath);
+    return relativePath === '' || (!relativePath.startsWith('..') && !isAbsolute(relativePath));
+}
+function getLineCount(source) {
+    return source.split('\n').length;
+}
+function extractInlineSourceMap(source) {
+    let sourceMapPattern = /(?:\/\/# sourceMappingURL=data:application\/json;base64,([A-Za-z0-9+/=]+)|\/\*# sourceMappingURL=data:application\/json;base64,([A-Za-z0-9+/=]+) \*\/)\s*$/g;
+    let sourceMap = null;
+    let code = source.replace(sourceMapPattern, (_match, lineComment, blockComment) => {
+        sourceMap = Buffer.from(lineComment ?? blockComment, 'base64').toString('utf-8');
+        return '';
+    });
+    return { code: code.trimEnd(), sourceMap };
+}
+function appendInlineSourceMap(source, sourceMap) {
+    let encoded = Buffer.from(sourceMap).toString('base64');
+    return `${source}\n//# sourceMappingURL=data:application/json;base64,${encoded}`;
+}
+function createLineOffsetSourceMap(url, source, lineOffset) {
+    let generator = new SourceMapGenerator({ file: url });
+    let lines = source.split('\n');
+    for (let index = 0; index < lines.length; index++) {
+        generator.addMapping({
+            generated: {
+                column: 0,
+                line: index + lineOffset + 1,
+            },
+            original: {
+                column: 0,
+                line: index + 1,
+            },
+            source: url,
+        });
+    }
+    generator.setSourceContent(url, source);
+    return JSON.stringify(generator.toJSON());
+}
+function composeSourceMaps(rewriteSourceMap, transformSourceMap) {
+    let rewriteConsumer = new SourceMapConsumer(JSON.parse(rewriteSourceMap));
+    let transformConsumer = new SourceMapConsumer(JSON.parse(transformSourceMap));
+    let generator = new SourceMapGenerator();
+    rewriteConsumer.eachMapping((mapping) => {
+        if (mapping.originalLine == null ||
+            mapping.originalColumn == null ||
+            mapping.generatedLine == null ||
+            mapping.generatedColumn == null) {
+            return;
+        }
+        let original = transformConsumer.originalPositionFor({
+            line: mapping.originalLine,
+            column: mapping.originalColumn,
+        });
+        if (original.line == null || original.column == null || original.source == null)
+            return;
+        generator.addMapping({
+            generated: {
+                line: mapping.generatedLine,
+                column: mapping.generatedColumn,
+            },
+            original: {
+                line: original.line,
+                column: original.column,
+            },
+            source: original.source,
+            name: original.name ?? mapping.name ?? undefined,
+        });
+    });
+    for (let source of transformConsumer.sources) {
+        let sourceContent = transformConsumer.sourceContentFor(source, true);
+        if (sourceContent !== null) {
+            generator.setSourceContent(source, sourceContent);
+        }
+    }
+    return JSON.stringify(generator.toJSON());
+}
+async function handleHotUpdateMessage(message) {
+    invalidatedUrlTimestamps = new Map(Object.entries(message.invalidatedUrls ?? {}));
+    try {
+        await runtime.update(message.url, message.timestamp, message.acceptedUrl);
+    }
+    catch (error) {
+        process.send?.({
+            type: 'node-hmr:child:restart-requested',
+            message: error instanceof Error ? error.message : String(error),
+        });
+    }
+}
+function isHmrUpdateMessage(message) {
+    return (typeof message === 'object' &&
+        message !== null &&
+        'type' in message &&
+        message.type === 'node-hmr:parent:hot-module-changed' &&
+        'url' in message &&
+        typeof message.url === 'string' &&
+        'timestamp' in message &&
+        typeof message.timestamp === 'number' &&
+        (!('acceptedUrl' in message) || typeof message.acceptedUrl === 'string') &&
+        (!('invalidatedUrls' in message) || isInvalidatedUrls(message.invalidatedUrls)));
+}
+function isBrowserHmrFileEventsMessage(message) {
+    return (typeof message === 'object' &&
+        message !== null &&
+        'type' in message &&
+        message.type === 'node-hmr:parent:browser-hmr-file-events' &&
+        'requestId' in message &&
+        typeof message.requestId === 'number' &&
+        'events' in message &&
+        Array.isArray(message.events) &&
+        message.events.every((event) => typeof event === 'object' &&
+            event !== null &&
+            'filePath' in event &&
+            typeof event.filePath === 'string' &&
+            'event' in event &&
+            (event.event === 'add' || event.event === 'change' || event.event === 'unlink')));
+}
+function isInvalidatedUrls(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    for (let timestamp of Object.values(value)) {
+        if (typeof timestamp !== 'number')
+            return false;
+    }
+    return true;
+}
+function disposeOnSignal(signal) {
+    runtime.disposeAll().finally(() => {
+        if (process.listenerCount(signal) === 0) {
+            process.exit(signal === 'SIGINT' ? 130 : 143);
+        }
+    });
+}

package/dist/runtime.d.ts

@@ -0,0 +1,26 @@
+import type { NodeHmrRuntimeApi } from './lib/runtime-api.ts';
+export type { BrowserHmrChannel } from './lib/browser-events.ts';
+/**
+ * Connects browser asset tooling in this child process to the browser HMR event stream and file
+ * watcher owned by its `node-hmr` parent process.
+ *
+ * Pass this function as the `hmr` factory for `createAssetServer()`. Each call creates an
+ * independent channel that must be closed when its owner shuts down. The returned promise rejects
+ * when browser HMR is disabled for the runner.
+ *
+ * The `remix/node-hmr/runtime` module itself can only be imported by a process supervised by
+ * `node-hmr`. Use a dynamic import guarded by `process.env.REMIX_NODE_HMR` when the same entry module
+ * also runs without HMR supervision.
+ *
+ * @returns A child-scoped channel for watching browser source files and publishing HMR events.
+ */
+export declare const createBrowserHmrChannel: NodeHmrRuntimeApi['createBrowserHmrChannel'];
+/**
+ * Notifies the `node-hmr` parent that this child process is ready to serve requests.
+ *
+ * Call this after the app server starts listening. After a restart, `node-hmr` waits for this
+ * signal before publishing the browser `server:update` event, preventing clients from refreshing
+ * against a server that is not ready yet.
+ */
+export declare const emitServerReady: NodeHmrRuntimeApi['emitServerReady'];
+//# sourceMappingURL=runtime.d.ts.map

package/dist/runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAA;AAG7D,YAAY,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAA;AAEhE;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,uBAAuB,EAAE,iBAAiB,CAAC,yBAAyB,CAG9E,CAAA;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,EAAE,iBAAiB,CAAC,iBAAiB,CAEhE,CAAA"}

package/dist/runtime.js

@@ -0,0 +1,32 @@
+import { nodeHmrRuntimeUnavailableError } from './lib/runtime-api.js';
+/**
+ * Connects browser asset tooling in this child process to the browser HMR event stream and file
+ * watcher owned by its `node-hmr` parent process.
+ *
+ * Pass this function as the `hmr` factory for `createAssetServer()`. Each call creates an
+ * independent channel that must be closed when its owner shuts down. The returned promise rejects
+ * when browser HMR is disabled for the runner.
+ *
+ * The `remix/node-hmr/runtime` module itself can only be imported by a process supervised by
+ * `node-hmr`. Use a dynamic import guarded by `process.env.REMIX_NODE_HMR` when the same entry module
+ * also runs without HMR supervision.
+ *
+ * @returns A child-scoped channel for watching browser source files and publishing HMR events.
+ */
+export const createBrowserHmrChannel = async function createBrowserHmrChannel() {
+    throwNodeHmrRuntimeUnavailable();
+};
+/**
+ * Notifies the `node-hmr` parent that this child process is ready to serve requests.
+ *
+ * Call this after the app server starts listening. After a restart, `node-hmr` waits for this
+ * signal before publishing the browser `server:update` event, preventing clients from refreshing
+ * against a server that is not ready yet.
+ */
+export const emitServerReady = function emitServerReady() {
+    throwNodeHmrRuntimeUnavailable();
+};
+throwNodeHmrRuntimeUnavailable();
+function throwNodeHmrRuntimeUnavailable() {
+    throw new Error(nodeHmrRuntimeUnavailableError);
+}

package/dist/runtime.node-hmr.d.ts

@@ -0,0 +1,27 @@
+import type { NodeHmrRuntimeApi } from './lib/runtime-api.ts';
+export type { BrowserHmrChannel } from './lib/browser-events.ts';
+/**
+ * Connects browser asset tooling in this child process to the browser HMR event stream and file
+ * watcher owned by its `node-hmr` parent process.
+ *
+ * Pass this function as the `hmr` factory for `createAssetServer()`. Each call creates an
+ * independent channel that must be closed when its owner shuts down. The returned promise rejects
+ * when browser HMR is disabled for the runner.
+ *
+ * The `remix/node-hmr/runtime` module itself can only be imported by a process supervised by
+ * `node-hmr`. Use a dynamic import guarded by `process.env.REMIX_NODE_HMR` when the same entry module
+ * also runs without HMR supervision.
+ *
+ * @returns A child-scoped channel for watching browser source files and publishing HMR events.
+ */
+export declare const createBrowserHmrChannel: NodeHmrRuntimeApi['createBrowserHmrChannel'];
+/**
+ * Notifies the `node-hmr` parent that this child process is ready to serve requests.
+ *
+ * Call this after the app server starts listening. After a restart, `node-hmr` waits for this
+ * signal before publishing the browser `server:update` event, preventing clients from refreshing
+ * against a server that is not ready yet.
+ */
+declare const emitRuntimeServerReady: NodeHmrRuntimeApi['emitServerReady'];
+export { emitRuntimeServerReady as emitServerReady };
+//# sourceMappingURL=runtime.node-hmr.d.ts.map

package/dist/runtime.node-hmr.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.node-hmr.d.ts","sourceRoot":"","sources":["../src/runtime.node-hmr.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAA;AAG7D,YAAY,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAA;AAQhE;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,uBAAuB,EAAE,iBAAiB,CAAC,yBAAyB,CAG9E,CAAA;AAEH;;;;;;GAMG;AACH,QAAA,MAAM,sBAAsB,EAAE,iBAAiB,CAAC,iBAAiB,CAAmB,CAAA;AACpF,OAAO,EAAE,sBAAsB,IAAI,eAAe,EAAE,CAAA"}

package/dist/runtime.node-hmr.js

@@ -0,0 +1,33 @@
+import { emitServerReady, getNodeHmrRuntime } from './lib/runtime.js';
+import { nodeHmrRuntimeUnavailableError } from './lib/runtime-api.js';
+const maybeNodeHmrRuntime = getNodeHmrRuntime();
+if (maybeNodeHmrRuntime === undefined) {
+    throw new Error(nodeHmrRuntimeUnavailableError);
+}
+const nodeHmrRuntime = maybeNodeHmrRuntime;
+/**
+ * Connects browser asset tooling in this child process to the browser HMR event stream and file
+ * watcher owned by its `node-hmr` parent process.
+ *
+ * Pass this function as the `hmr` factory for `createAssetServer()`. Each call creates an
+ * independent channel that must be closed when its owner shuts down. The returned promise rejects
+ * when browser HMR is disabled for the runner.
+ *
+ * The `remix/node-hmr/runtime` module itself can only be imported by a process supervised by
+ * `node-hmr`. Use a dynamic import guarded by `process.env.REMIX_NODE_HMR` when the same entry module
+ * also runs without HMR supervision.
+ *
+ * @returns A child-scoped channel for watching browser source files and publishing HMR events.
+ */
+export const createBrowserHmrChannel = async function createBrowserHmrChannel() {
+    return await nodeHmrRuntime.createBrowserHmrChannel();
+};
+/**
+ * Notifies the `node-hmr` parent that this child process is ready to serve requests.
+ *
+ * Call this after the app server starts listening. After a restart, `node-hmr` waits for this
+ * signal before publishing the browser `server:update` event, preventing clients from refreshing
+ * against a server that is not ready yet.
+ */
+const emitRuntimeServerReady = emitServerReady;
+export { emitRuntimeServerReady as emitServerReady };

package/dist/types.d.ts

@@ -0,0 +1,36 @@
+interface ImportMetaHot {
+  /** Mutable state preserved for this module across accepted updates and passed to dispose handlers. */
+  readonly data: Record<string, unknown>
+  /** Accepts updates to this module, optionally receiving its newly evaluated namespace. */
+  accept(callback?: (module: HotModule) => HotCallbackResult): void
+  /** Accepts updates from one dependency, optionally receiving its newly evaluated namespace. */
+  accept(dep: string, callback?: (module: HotModule) => HotCallbackResult): void
+  /**
+   * Accepts updates from multiple dependencies. The callback array preserves `deps` order and
+   * contains the updated namespace only at the position of the dependency that changed.
+   */
+  accept(
+    deps: readonly string[],
+    callback?: (modules: Array<HotModule | undefined>) => HotCallbackResult,
+  ): void
+  /** Registers cleanup that runs before this module is re-evaluated or the runtime is disposed. */
+  dispose(callback: (data: Record<string, unknown>) => HotCallbackResult): void
+  /** Declines the current update and asks the runner to restart the child process. */
+  invalidate(message?: string): void
+  /** Registers a custom-event listener for API compatibility. Server modules receive no events. */
+  on(event: string, callback: (data: unknown) => void | Promise<void>): void
+}
+
+type HotModule = Readonly<Record<string, unknown>> & {
+  readonly [Symbol.toStringTag]: 'Module'
+}
+
+type HotCallbackResult = void | Promise<void>
+
+declare global {
+  interface ImportMeta {
+    readonly hot?: ImportMetaHot
+  }
+}
+
+export {}

package/package.json

@@ -1,14 +1,64 @@
 {
   "name": "@remix-run/node-hmr",
-  "version": "0.0.0",
-  "description": "Placeholder package for Remix CI/OIDC setup",
+  "version": "0.1.0",
+  "description": "Run Node.js applications with Hot Module Reloading",
+  "author": "Michael Jackson <mjijackson@gmail.com>",
   "license": "MIT",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/remix-run/remix.git",
     "directory": "packages/node-hmr"
   },
-  "publishConfig": {
-    "access": "public"
+  "homepage": "https://github.com/remix-run/remix/tree/main/packages/node-hmr#readme",
+  "files": [
+    "LICENSE",
+    "README.md",
+    "dist",
+    "src",
+    "!src/**/*.test.ts"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./runtime": {
+      "node-hmr": {
+        "types": "./dist/runtime.node-hmr.d.ts",
+        "default": "./dist/runtime.node-hmr.js"
+      },
+      "types": "./dist/runtime.d.ts",
+      "default": "./dist/runtime.js"
+    },
+    "./types": {
+      "types": "./dist/types.d.ts"
+    },
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "chokidar": "^5.0.0",
+    "oxc-parser": "^0.121.0",
+    "source-map-js": "^1.2.1",
+    "@remix-run/terminal": "^0.1.1"
+  },
+  "devDependencies": {
+    "@types/node": "^24.6.0",
+    "typescript": "^7.0.2",
+    "@remix-run/assert": "^0.3.0",
+    "@remix-run/node-tsx": "^0.1.1",
+    "@remix-run/test": "^0.6.0"
+  },
+  "keywords": [
+    "remix",
+    "node",
+    "hmr",
+    "watch"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && node ../../scripts/copy-package-type-only-exports.ts .",
+    "clean": "git clean -fdX",
+    "test": "remix test",
+    "typecheck": "tsc --noEmit"
   }
-}
+}