http-modules 0.0.1

package/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## 0.0.1 - 2026-07-15
+
+Initial release.
+
+- Added Bun support for `https://` imports through a preloadable `Bun.plugin`.
+- Added Node.js support through asynchronous module customization hooks and a `node --import` registration entrypoint.
+- Added shared remote module fetching, HTTP error handling, runtime format detection, and relative import rewriting for nested remote modules.
+- Added package entrypoints for the side-effect-free root API, Bun preload, Node hooks, and Node registration.

package/README.md

@@ -0,0 +1,120 @@
+# http-modules
+
+`http-modules` lets JavaScript runtimes import modules directly from `https://` URLs.
+
+The package currently supports:
+
+- Bun, through a preloadable `Bun.plugin`.
+- Node.js, through module customization hooks.
+- Remote JavaScript and TypeScript modules.
+- Relative imports inside fetched remote modules.
+
+## Why this exists
+
+Browsers and Deno can import URL-based modules as first-class module specifiers. Bun and Node.js normally expect package, file, or built-in specifiers. This package fills that gap for runtime code that wants to write normal static imports against HTTPS module URLs:
+
+```ts
+import { nanoid } from "https://cdn.jsdelivr.net/npm/nanoid@5.0.7/index.browser.js";
+```
+
+## Install
+
+```sh
+bun add http-modules
+```
+
+## Bun
+
+Preload the Bun plugin before any static HTTPS imports are resolved:
+
+```toml
+# bunfig.toml
+preload = ["http-modules/bun"]
+```
+
+Then import HTTPS modules directly:
+
+```ts
+import { nanoid } from "https://cdn.jsdelivr.net/npm/nanoid@5.0.7/index.browser.js";
+
+console.log(nanoid());
+```
+
+For local development in this repo, `bunfig.toml` preloads `./src/bun.ts` so the source plugin is exercised directly.
+
+## Node.js
+
+Preload the Node registration entrypoint:
+
+```sh
+node --import http-modules/node/register ./app.mjs
+```
+
+Then import HTTPS modules directly:
+
+```js
+import { basename } from "https://deno.land/std@0.224.0/path/mod.ts";
+
+console.log(basename("/tmp/example.ts"));
+```
+
+Node.js support uses asynchronous module customization hooks. Remote TypeScript modules require Node.js `>=22.6`, because Node must understand the `module-typescript` loader format.
+
+If you need to register hooks yourself, use:
+
+```js
+import { register } from "node:module";
+
+register("http-modules/node/hooks", import.meta.url);
+```
+
+## Package entrypoints
+
+| Export | Purpose |
+| --- | --- |
+| `http-modules` | Shared helper exports. No runtime side effects. |
+| `http-modules/bun` | Registers the Bun HTTPS import plugin. Use as a Bun preload. |
+| `http-modules/node/register` | Registers Node customization hooks. Use with `node --import`. |
+| `http-modules/node/hooks` | Raw Node hook module for manual registration. |
+
+## Behavior
+
+- Only `https://` module specifiers are handled.
+- HTTP errors fail module loading with the response status.
+- Remote JavaScript and TypeScript sources have relative import specifiers rewritten to absolute HTTPS URLs before evaluation. This keeps nested remote imports working across both runtimes.
+- JSON modules are loaded as JSON where the runtime supports that loader format.
+- No cache is implemented yet. Every process fetches remote modules through the runtime loader path.
+
+## Development
+
+This repo uses Bun for package management and build tasks, with mise pinning Bun and Node versions.
+
+```sh
+mise install
+bun install
+bun run build
+bun run test
+bun run typecheck
+```
+
+Equivalent mise tasks:
+
+```sh
+mise run build
+mise run test
+mise run typecheck
+```
+
+`bun run test` builds `dist/` and then runs the cross-runtime test suite. The tests start a local HTTPS server with fixture modules, then verify both Bun and Node can import the same remote module graph without depending on third-party networks.
+
+## Repository layout
+
+```txt
+src/shared.ts         Shared fetch, format detection, and import-rewrite logic.
+src/bun.ts            Bun plugin entrypoint.
+src/node/hooks.ts     Node async resolve/load hooks.
+src/node/register.ts  Node --import registration entrypoint.
+src/index.ts          Side-effect-free public helper exports.
+```
+
+Build output is written to `dist/` and included in the published package.

package/dist/bun.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/bun.js

@@ -0,0 +1,116 @@
+// src/bun.ts
+import { plugin } from "bun";
+
+// src/shared.ts
+var RELATIVE_IMPORT_SPECIFIER = /(\b(?:from|import)\s*(?:\(\s*)?)(["'])(\.{1,2}\/[^"']+)\2/g;
+function isHttpsSpecifier(specifier) {
+  return specifier.startsWith("https://");
+}
+function isRelativeSpecifier(specifier) {
+  return specifier.startsWith("./") || specifier.startsWith("../");
+}
+function toFetchUrl(namespacePath) {
+  if (namespacePath.startsWith("//")) {
+    return `https:${namespacePath}`;
+  }
+  if (namespacePath.startsWith("https://")) {
+    return namespacePath;
+  }
+  throw new Error(`Expected an HTTPS URL, received ${namespacePath}`);
+}
+function toNamespacePath(url) {
+  if (url.startsWith("https://")) {
+    return url.slice("https:".length);
+  }
+  if (url.startsWith("//")) {
+    return url;
+  }
+  throw new Error(`Expected an HTTPS URL, received ${url}`);
+}
+function resolveHttpsSpecifier(specifier, parentUrl) {
+  if (isHttpsSpecifier(specifier)) {
+    return specifier;
+  }
+  if (parentUrl?.startsWith("https://") && isRelativeSpecifier(specifier)) {
+    return new URL(specifier, parentUrl).href;
+  }
+  return;
+}
+function rewriteRelativeImportSpecifiers(source, importerUrl) {
+  return source.replace(RELATIVE_IMPORT_SPECIFIER, (_specifier, prefix, quote, path) => `${prefix}${quote}${new URL(path, importerUrl).href}${quote}`);
+}
+function bunLoaderFor(url, contentType) {
+  const pathname = new URL(url).pathname;
+  if (contentType?.includes("application/json") || pathname.endsWith(".json")) {
+    return "json";
+  }
+  if (pathname.endsWith(".ts") || pathname.endsWith(".mts") || contentType?.includes("typescript")) {
+    return "ts";
+  }
+  if (pathname.endsWith(".tsx")) {
+    return "tsx";
+  }
+  if (pathname.endsWith(".jsx")) {
+    return "jsx";
+  }
+  return "js";
+}
+function nodeFormatFor(url, contentType) {
+  const pathname = new URL(url).pathname;
+  if (contentType?.includes("application/json") || pathname.endsWith(".json")) {
+    return "json";
+  }
+  if (pathname.endsWith(".ts") || pathname.endsWith(".mts") || contentType?.includes("typescript")) {
+    return "module-typescript";
+  }
+  return "module";
+}
+function rewritesImports(loader) {
+  return loader === "js" || loader === "jsx" || loader === "ts" || loader === "tsx";
+}
+async function fetchRemoteModule(url) {
+  const response = await fetch(url);
+  if (!response.ok) {
+    throw new Error(`Failed to load ${url}: ${response.status} ${response.statusText}`);
+  }
+  const contentType = response.headers.get("content-type");
+  const bunLoader = bunLoaderFor(url, contentType);
+  const source = await response.text();
+  return {
+    bunLoader,
+    nodeFormat: nodeFormatFor(url, contentType),
+    source: rewritesImports(bunLoader) ? rewriteRelativeImportSpecifiers(source, url) : source
+  };
+}
+
+// src/bun.ts
+var HTTPS_NAMESPACE = "https";
+plugin({
+  name: "https-imports",
+  setup(build) {
+    build.onResolve({ filter: /^https:\/\// }, (args) => ({
+      path: toNamespacePath(args.path),
+      namespace: HTTPS_NAMESPACE
+    }));
+    build.onResolve({ filter: /.*/, namespace: HTTPS_NAMESPACE }, (args) => {
+      if (args.path.startsWith("https://") || args.path.startsWith("//")) {
+        return {
+          path: toNamespacePath(args.path),
+          namespace: HTTPS_NAMESPACE
+        };
+      }
+      const importer = toFetchUrl(args.importer);
+      return {
+        path: toNamespacePath(new URL(args.path, importer).href),
+        namespace: HTTPS_NAMESPACE
+      };
+    });
+    build.onLoad({ filter: /.*/, namespace: HTTPS_NAMESPACE }, async (args) => {
+      const remoteModule = await fetchRemoteModule(toFetchUrl(args.path));
+      return {
+        contents: remoteModule.source,
+        loader: remoteModule.bunLoader
+      };
+    });
+  }
+});

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export type { BunRemoteLoader, NodeRemoteFormat, RemoteModule } from "./shared";
+export { fetchRemoteModule, resolveHttpsSpecifier } from "./shared";

package/dist/index.js

@@ -0,0 +1,85 @@
+// src/shared.ts
+var RELATIVE_IMPORT_SPECIFIER = /(\b(?:from|import)\s*(?:\(\s*)?)(["'])(\.{1,2}\/[^"']+)\2/g;
+function isHttpsSpecifier(specifier) {
+  return specifier.startsWith("https://");
+}
+function isRelativeSpecifier(specifier) {
+  return specifier.startsWith("./") || specifier.startsWith("../");
+}
+function toFetchUrl(namespacePath) {
+  if (namespacePath.startsWith("//")) {
+    return `https:${namespacePath}`;
+  }
+  if (namespacePath.startsWith("https://")) {
+    return namespacePath;
+  }
+  throw new Error(`Expected an HTTPS URL, received ${namespacePath}`);
+}
+function toNamespacePath(url) {
+  if (url.startsWith("https://")) {
+    return url.slice("https:".length);
+  }
+  if (url.startsWith("//")) {
+    return url;
+  }
+  throw new Error(`Expected an HTTPS URL, received ${url}`);
+}
+function resolveHttpsSpecifier(specifier, parentUrl) {
+  if (isHttpsSpecifier(specifier)) {
+    return specifier;
+  }
+  if (parentUrl?.startsWith("https://") && isRelativeSpecifier(specifier)) {
+    return new URL(specifier, parentUrl).href;
+  }
+  return;
+}
+function rewriteRelativeImportSpecifiers(source, importerUrl) {
+  return source.replace(RELATIVE_IMPORT_SPECIFIER, (_specifier, prefix, quote, path) => `${prefix}${quote}${new URL(path, importerUrl).href}${quote}`);
+}
+function bunLoaderFor(url, contentType) {
+  const pathname = new URL(url).pathname;
+  if (contentType?.includes("application/json") || pathname.endsWith(".json")) {
+    return "json";
+  }
+  if (pathname.endsWith(".ts") || pathname.endsWith(".mts") || contentType?.includes("typescript")) {
+    return "ts";
+  }
+  if (pathname.endsWith(".tsx")) {
+    return "tsx";
+  }
+  if (pathname.endsWith(".jsx")) {
+    return "jsx";
+  }
+  return "js";
+}
+function nodeFormatFor(url, contentType) {
+  const pathname = new URL(url).pathname;
+  if (contentType?.includes("application/json") || pathname.endsWith(".json")) {
+    return "json";
+  }
+  if (pathname.endsWith(".ts") || pathname.endsWith(".mts") || contentType?.includes("typescript")) {
+    return "module-typescript";
+  }
+  return "module";
+}
+function rewritesImports(loader) {
+  return loader === "js" || loader === "jsx" || loader === "ts" || loader === "tsx";
+}
+async function fetchRemoteModule(url) {
+  const response = await fetch(url);
+  if (!response.ok) {
+    throw new Error(`Failed to load ${url}: ${response.status} ${response.statusText}`);
+  }
+  const contentType = response.headers.get("content-type");
+  const bunLoader = bunLoaderFor(url, contentType);
+  const source = await response.text();
+  return {
+    bunLoader,
+    nodeFormat: nodeFormatFor(url, contentType),
+    source: rewritesImports(bunLoader) ? rewriteRelativeImportSpecifiers(source, url) : source
+  };
+}
+export {
+  resolveHttpsSpecifier,
+  fetchRemoteModule
+};

package/dist/node/hooks.d.ts

@@ -0,0 +1,21 @@
+interface ResolveContext {
+    parentURL?: string;
+}
+interface ResolveResult {
+    format?: string;
+    shortCircuit?: boolean;
+    url: string;
+}
+interface LoadContext {
+    format?: string;
+}
+interface LoadResult {
+    format: string;
+    shortCircuit?: boolean;
+    source: string;
+}
+type NextResolve = (specifier: string, context: ResolveContext) => Promise<ResolveResult>;
+type NextLoad = (url: string, context: LoadContext) => Promise<LoadResult>;
+export declare function resolve(specifier: string, context: ResolveContext, nextResolve: NextResolve): Promise<ResolveResult>;
+export declare function load(url: string, context: LoadContext, nextLoad: NextLoad): Promise<LoadResult>;
+export {};

package/dist/node/hooks.js

@@ -0,0 +1,109 @@
+// src/shared.ts
+var RELATIVE_IMPORT_SPECIFIER = /(\b(?:from|import)\s*(?:\(\s*)?)(["'])(\.{1,2}\/[^"']+)\2/g;
+function isHttpsSpecifier(specifier) {
+  return specifier.startsWith("https://");
+}
+function isRelativeSpecifier(specifier) {
+  return specifier.startsWith("./") || specifier.startsWith("../");
+}
+function toFetchUrl(namespacePath) {
+  if (namespacePath.startsWith("//")) {
+    return `https:${namespacePath}`;
+  }
+  if (namespacePath.startsWith("https://")) {
+    return namespacePath;
+  }
+  throw new Error(`Expected an HTTPS URL, received ${namespacePath}`);
+}
+function toNamespacePath(url) {
+  if (url.startsWith("https://")) {
+    return url.slice("https:".length);
+  }
+  if (url.startsWith("//")) {
+    return url;
+  }
+  throw new Error(`Expected an HTTPS URL, received ${url}`);
+}
+function resolveHttpsSpecifier(specifier, parentUrl) {
+  if (isHttpsSpecifier(specifier)) {
+    return specifier;
+  }
+  if (parentUrl?.startsWith("https://") && isRelativeSpecifier(specifier)) {
+    return new URL(specifier, parentUrl).href;
+  }
+  return;
+}
+function rewriteRelativeImportSpecifiers(source, importerUrl) {
+  return source.replace(RELATIVE_IMPORT_SPECIFIER, (_specifier, prefix, quote, path) => `${prefix}${quote}${new URL(path, importerUrl).href}${quote}`);
+}
+function bunLoaderFor(url, contentType) {
+  const pathname = new URL(url).pathname;
+  if (contentType?.includes("application/json") || pathname.endsWith(".json")) {
+    return "json";
+  }
+  if (pathname.endsWith(".ts") || pathname.endsWith(".mts") || contentType?.includes("typescript")) {
+    return "ts";
+  }
+  if (pathname.endsWith(".tsx")) {
+    return "tsx";
+  }
+  if (pathname.endsWith(".jsx")) {
+    return "jsx";
+  }
+  return "js";
+}
+function nodeFormatFor(url, contentType) {
+  const pathname = new URL(url).pathname;
+  if (contentType?.includes("application/json") || pathname.endsWith(".json")) {
+    return "json";
+  }
+  if (pathname.endsWith(".ts") || pathname.endsWith(".mts") || contentType?.includes("typescript")) {
+    return "module-typescript";
+  }
+  return "module";
+}
+function rewritesImports(loader) {
+  return loader === "js" || loader === "jsx" || loader === "ts" || loader === "tsx";
+}
+async function fetchRemoteModule(url) {
+  const response = await fetch(url);
+  if (!response.ok) {
+    throw new Error(`Failed to load ${url}: ${response.status} ${response.statusText}`);
+  }
+  const contentType = response.headers.get("content-type");
+  const bunLoader = bunLoaderFor(url, contentType);
+  const source = await response.text();
+  return {
+    bunLoader,
+    nodeFormat: nodeFormatFor(url, contentType),
+    source: rewritesImports(bunLoader) ? rewriteRelativeImportSpecifiers(source, url) : source
+  };
+}
+
+// src/node/hooks.ts
+async function resolve(specifier, context, nextResolve) {
+  const url = resolveHttpsSpecifier(specifier, context.parentURL);
+  if (url) {
+    return {
+      format: nodeFormatFor(url, null),
+      shortCircuit: true,
+      url
+    };
+  }
+  return nextResolve(specifier, context);
+}
+async function load(url, context, nextLoad) {
+  if (!url.startsWith("https://")) {
+    return nextLoad(url, context);
+  }
+  const remoteModule = await fetchRemoteModule(url);
+  return {
+    format: remoteModule.nodeFormat,
+    shortCircuit: true,
+    source: remoteModule.source
+  };
+}
+export {
+  resolve,
+  load
+};

package/dist/node/register.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/node/register.js

@@ -0,0 +1,3 @@
+// src/node/register.ts
+import { register } from "node:module";
+register("./hooks.js", import.meta.url);

package/dist/shared.d.ts

@@ -0,0 +1,17 @@
+export type BunRemoteLoader = "js" | "jsx" | "ts" | "tsx" | "json";
+export type NodeRemoteFormat = "module" | "module-typescript" | "json";
+export interface RemoteModule {
+    bunLoader: BunRemoteLoader;
+    nodeFormat: NodeRemoteFormat;
+    source: string;
+}
+export declare function isHttpsSpecifier(specifier: string): boolean;
+export declare function isRelativeSpecifier(specifier: string): boolean;
+export declare function toFetchUrl(namespacePath: string): string;
+export declare function toNamespacePath(url: string): string;
+export declare function resolveHttpsSpecifier(specifier: string, parentUrl?: string): string | undefined;
+export declare function rewriteRelativeImportSpecifiers(source: string, importerUrl: string): string;
+export declare function bunLoaderFor(url: string, contentType: string | null): BunRemoteLoader;
+export declare function nodeFormatFor(url: string, contentType: string | null): NodeRemoteFormat;
+export declare function rewritesImports(loader: BunRemoteLoader): boolean;
+export declare function fetchRemoteModule(url: string): Promise<RemoteModule>;

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "http-modules",
+  "version": "0.0.1",
+  "description": "Import HTTPS modules in Bun and Node.js.",
+  "type": "module",
+  "sideEffects": [
+    "./dist/bun.js",
+    "./dist/node/register.js"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./bun": {
+      "types": "./dist/bun.d.ts",
+      "import": "./dist/bun.js"
+    },
+    "./node/hooks": {
+      "types": "./dist/node/hooks.d.ts",
+      "import": "./dist/node/hooks.js"
+    },
+    "./node/register": {
+      "types": "./dist/node/register.d.ts",
+      "import": "./dist/node/register.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "rm -rf ./dist && bun build ./src/index.ts ./src/bun.ts ./src/node/hooks.ts ./src/node/register.ts --outdir ./dist --target node --format esm --packages external && bun x tsc --project tsconfig.build.json",
+    "test": "bun run build && bun test",
+    "typecheck": "bun x tsc --noEmit"
+  },
+  "engines": {
+    "bun": ">=1.3.1",
+    "node": ">=22.6"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@types/node": "latest",
+    "typescript": "^5"
+  }
+}