@nubjs/loader 0.0.0 → 0.8.2

package/loader-register.cjs

@@ -0,0 +1,33 @@
+"use strict";
+// `node --require <pkg>` — the CommonJS delivery of the full loader (ESM hooks +
+// CommonJS require() augmentation). On Node 22.15+ this is strictly the better
+// consumption shape: a `--require` CJS preload keeps Node's synchronous CJS entry
+// path (the mere presence of `--import` forces eager async ESM-loader init that
+// routes even a CJS entry through the async module-job — see preload.cjs, R1),
+// which is exactly why the nub CLI injects its own fast-tier preload this way.
+//
+// require(esm) loads the shared ES-module arming logic synchronously (TLA-free by
+// construction). Where require(esm) is unavailable — `--no-experimental-require-
+// module`, or a compat-tier Node below 22.12/20.19 — fall back to registering the
+// loader-worker hooks directly (preload-common is CommonJS, so that registration
+// needs no require(esm)): `import`-side TS still transpiles through the worker,
+// and only require()'d TS is inactive, matching the CLI preload's own degradation
+// under that flag.
+try {
+  require("./loader-entry.mjs").arm({ esm: true, cjs: true });
+} catch (err) {
+  if (!err || err.code !== "ERR_REQUIRE_ESM") throw err;
+  if (process.versions.electron) return;
+  // The loader worker's transform-core needs the addon path in the inherited env
+  // — loader-entry.mjs (which normally sets it) could not load here.
+  require("./loader-platform.cjs").ensureAddonEnv(require);
+  const { pathToFileURL } = require("node:url");
+  const common = require("./preload-common.cjs");
+  common.registerLoaderWorker(
+    "./preload-async-hooks.mjs",
+    pathToFileURL(__filename).href,
+    // Same payload the ESM entry sends: the worker clears its own realm's
+    // clobber map (see initialize in preload-async-hooks.mjs).
+    { data: { standaloneLoader: true } },
+  );
+}

package/loader-register.mjs

@@ -0,0 +1,5 @@
+// `node --import <pkg>` — arms BOTH module systems (ESM hooks + CommonJS
+// require() augmentation), tsx's default-entry shape.
+import { arm } from "./loader-entry.mjs";
+
+arm({ esm: true, cjs: true });

package/package.json

@@ -1,7 +1,61 @@
 {
   "name": "@nubjs/loader",
-  "version": "0.0.0",
-  "description": "Placeholder — the Nub loader ships here with the next Nub release.",
+  "version": "0.8.2",
+  "description": "Standalone TypeScript loader for Node.js from the Nub project — TypeScript, JSX, tsconfig paths, and data-format imports through a native transform, registered the way tsx and ts-node are",
   "license": "MIT",
-  "repository": "https://github.com/nubjs/nub"
+  "repository": "https://github.com/nubjs/nub",
+  "homepage": "https://nubjs.com",
+  "bugs": {
+    "url": "https://github.com/nubjs/nub/issues"
+  },
+  "keywords": [
+    "typescript",
+    "loader",
+    "esm",
+    "nodejs",
+    "tsx",
+    "ts-node",
+    "transpiler",
+    "jsx"
+  ],
+  "engines": {
+    "node": ">=18.19.0"
+  },
+  "exports": {
+    ".": {
+      "import": "./loader-register.mjs",
+      "require": "./loader-register.cjs"
+    },
+    "./esm": "./loader-esm.mjs",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "loader-register.mjs",
+    "loader-register.cjs",
+    "loader-esm.mjs",
+    "loader-entry.mjs",
+    "loader-addon-env.mjs",
+    "loader-platform.cjs",
+    "transform-core.mjs",
+    "preload-common.cjs",
+    "preload-async-hooks.mjs",
+    "pnp-util.cjs",
+    "floor-builtin.mjs",
+    "cache-evict.mjs",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@oxc-project/runtime": "0.140.0"
+  },
+  "optionalDependencies": {
+    "@nubjs/loader-darwin-arm64": "0.8.2",
+    "@nubjs/loader-darwin-x64": "0.8.2",
+    "@nubjs/loader-linux-x64": "0.8.2",
+    "@nubjs/loader-linux-x64-musl": "0.8.2",
+    "@nubjs/loader-linux-arm64": "0.8.2",
+    "@nubjs/loader-linux-arm64-musl": "0.8.2",
+    "@nubjs/loader-win32-x64": "0.8.2",
+    "@nubjs/loader-win32-arm64": "0.8.2"
+  }
 }

package/pnp-util.cjs

@@ -0,0 +1,62 @@
+// Shared Yarn PnP ESM-resolution helper, used by BOTH realms that resolve ESM
+// imports: the main-thread preload (preload-common.cjs, fast tier) and the
+// compat-tier loader worker (preload-async-hooks.mjs). CJS resolution does NOT live
+// here — it just strips the `conditions` option and delegates to PnP's own patched
+// `_resolveFilename` (see installCjsRequireHooks). ESM is different: PnP does not
+// patch the ESM loader, so `import` of a PnP dep must be resolved explicitly, AND it
+// must pass the *import* conditions — otherwise a dual package (separate `import` /
+// `require` exports) resolves to its CJS build and `import { x }` fails. So we go
+// through `pnpapi.resolveRequest` (the only PnP resolver that accepts conditions).
+const { readFileSync } = require("node:fs");
+const { dirname, join, sep } = require("node:path");
+const { fileURLToPath, pathToFileURL } = require("node:url");
+
+// A directory issuer for resolveRequest: cwd with a trailing separator so PnP treats
+// it as a directory. `path.sep` (not a literal "/") keeps it correct on Windows.
+const cwdIssuer = () => process.cwd() + sep;
+
+// Module format of a resolved file. `.mjs`/`.cjs` are unambiguous; a `.js` file
+// inherits its nearest package's `type`, read by walking up to package.json via the
+// zip-patched `fs` (`.pnp.cjs` patches `fs`, so reads inside `.zip` work in both
+// realms). No pnpapi needed. Defaults to "commonjs" if detection fails.
+function formatOf(resolvedPath) {
+  if (resolvedPath.endsWith(".mjs")) return "module";
+  if (resolvedPath.endsWith(".cjs")) return "commonjs";
+  let dir = dirname(resolvedPath);
+  for (let i = 0; i < 16; i++) {
+    try {
+      const pj = JSON.parse(readFileSync(join(dir, "package.json"), "utf8"));
+      return pj.type === "module" ? "module" : "commonjs";
+    } catch {}
+    const up = dirname(dir);
+    if (up === dir) break;
+    dir = up;
+  }
+  return "commonjs";
+}
+
+// Resolve a `specifier` through PnP for a hook `context`, applying the correct
+// exports conditions so a dual package resolves to the right build. Returns a Node
+// resolve-hook result `{ url, format, shortCircuit }`, or `null` if PnP can't resolve
+// it (the caller then delegates). Throwing is also a fall-through signal.
+//
+// Conditions: trust `context.conditions` when Node populates it (Node 24+/26 for both
+// import and require; Node 22.15 for import). But Node 22.15 hands the resolve hook
+// an EMPTY `conditions` for a `require()` — so when it's empty, infer the side from
+// `importAttributes` (`undefined` ⇒ a require, an object ⇒ an import) and apply the
+// matching default. Without this a 22.15 `require()` of a dual package would wrongly
+// get the `import` build.
+function pnpResolveEsm(api, specifier, context) {
+  const parentURL = context && context.parentURL;
+  const issuer = parentURL ? fileURLToPath(parentURL) : cwdIssuer();
+  let conds = context && context.conditions;
+  if (!conds || !conds.length) {
+    const isImport = !!context && context.importAttributes !== undefined;
+    conds = isImport ? ["node", "import"] : ["node", "require"];
+  }
+  const resolved = api.resolveRequest(specifier, issuer, { conditions: new Set(conds) });
+  if (!resolved) return null;
+  return { url: pathToFileURL(resolved).href, format: formatOf(resolved), shortCircuit: true };
+}
+
+module.exports = { pnpResolveEsm, cwdIssuer };

package/preload-async-hooks.mjs

@@ -0,0 +1,133 @@
+// Nub compat-tier hooks module — Node 18.19 through 22.14.
+//
+// On Node 22.15+, runtime/preload.mjs registers its hooks synchronously via
+// `module.registerHooks({ resolve, load })`. That API didn't exist before 22.15,
+// so on 18.19..22.14 the main-thread bootstrap calls
+// `module.register('./preload-async-hooks.mjs', parentURL)` instead, which loads
+// THIS file into a dedicated loader worker thread and uses its async
+// `resolve` / `load` exports. (CommonJS `require()` is augmented separately, on
+// the main thread, by preload.mjs's installCjsRequireHooks — `module.register`
+// hooks the ESM loader only.)
+//
+// There is NO logic of its own here: resolution + transpilation come verbatim
+// from runtime/transform-core.mjs, the single source of truth shared with the
+// fast path. The two tiers can no longer drift — the only difference is the
+// async function signatures Node's loader-worker protocol requires (it awaits
+// the returned values, so returning the core's synchronous results is fine). The
+// worker injects no watch hooks (watch IPC is main-thread only), so the core's
+// dependency reporters stay no-ops here, exactly as before the extraction.
+
+// Floor bootstrap (Node < 22.3/20.16/18.20.4): threads node:module's createRequire
+// into transform-core via a MODULE-SCOPE SETTER — never globalThis (brand boundary) —
+// because transform-core has no process.getBuiltinModule on the floor. floor-builtin
+// calls transform-core's setter during its own evaluation, so importing it FIRST
+// (ESM evaluates imports in source order) means the value is threaded before any hook
+// in this loader worker fires. No-op where getBuiltinModule exists. This worker runs
+// OFF any user loader chain, so floor-builtin's static node:module import never leaks
+// — see floor-builtin.mjs. (worker-polyfill is NOT loaded here: this is the dedicated
+// loader worker, not a user realm, so it installs no browser globals.)
+import "./floor-builtin.mjs";
+import {
+  TRANSPILE_EXTS, PLAIN_JS_EXTS, CLOBBER_MAP, dataExtsFor,
+  extname, isFileUrl, resolveSpec, loadTranspile, maybeTranspilePlainJs, loadData, loadTextImport, isDependency,
+} from "./transform-core.mjs";
+import { createRequire, isBuiltin } from "node:module";
+import { existsSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { pnpResolveEsm } from "./pnp-util.cjs";
+
+// Yarn PnP handle for this loader worker. The worker runs in its own thread where
+// `.pnp.cjs` was never --require'd, so neither the `pnpapi` builtin nor
+// `module.findPnpApi` is installed here (the main-thread preload uses findPnpApi; it
+// can't reach across to this realm). So bootstrap PnP for this thread directly: walk
+// up from cwd to the `.pnp.cjs` Rust located and require it by absolute path — that
+// returns the pnpapi object. nub then resolves PnP specifiers via
+// `pnpapi.resolveRequest` (its public, conditions-free resolver), mirroring the main
+// thread, so there is no need to register Yarn's `.pnp.loader.mjs` (which deadlocks
+// against the fast tier's `module.registerHooks`). `null` when not a PnP run.
+const __pnp = (() => {
+  if (!process.versions.pnp) return null;
+  const req = createRequire(import.meta.url);
+  try {
+    let dir = process.cwd();
+    for (;;) {
+      const candidate = join(dir, ".pnp.cjs");
+      if (existsSync(candidate)) return req(candidate);
+      const parent = dirname(dir);
+      if (parent === dir) return null;
+      dir = parent;
+    }
+  } catch { return null; }
+})();
+
+// Node calls this once per worker when the main thread invokes
+// `module.register(url, parentURL, { data })`, and register() blocks until it
+// resolves — so anything done here lands before the first resolve/load fires.
+// The STANDALONE LOADER (loader-entry.mjs / loader-register.cjs) sends
+// `{ standaloneLoader: true }`: this worker imports its OWN transform-core
+// instance (a separate module registry from the main thread), so the entry's
+// main-thread CLOBBER_MAP.clear() cannot reach the map THIS realm's resolveSpec
+// reads — without the clear here, `import "@js-temporal/polyfill"` on the
+// compat tier resolved to a synthetic re-export of a global the loader never
+// installs, silently binding `undefined` (verified on Node 20.19). The nub CLI
+// registers this worker with no data, keeping its clobbers intact.
+export async function initialize(data) {
+  if (data && data.standaloneLoader) CLOBBER_MAP.clear();
+}
+
+// ── Resolve hook ────────────────────────────────────────────────────
+export async function resolve(specifier, context, nextResolve) {
+  const r = resolveSpec(specifier, context.parentURL);
+  if (r) return r;
+  // Yarn PnP: resolve deps through PnP's own resolver — identical to the fast tier,
+  // via the shared helper (resolveRequest with the import conditions + format
+  // detection), so dual packages resolve to their `import` build.
+  if (__pnp && !isBuiltin(specifier) && !specifier.startsWith("node:")) {
+    try {
+      const res = pnpResolveEsm(__pnp, specifier, context);
+      if (res) return res;
+    } catch { /* fall through to Node's resolver */ }
+  }
+  return nextResolve(specifier, context);
+}
+
+// ── Load hook ───────────────────────────────────────────────────────
+export async function load(url, context, nextLoad) {
+  // Import Text (attribute-keyed): honor `with { type: "text" }` on ANY extension,
+  // checked BEFORE extension dispatch so `import s from "./c.yaml" with {type:"text"}`
+  // returns the raw text, not parsed YAML. shortCircuits, so Node never runs its own
+  // unknown-'text'-attribute validation. (Node 18.20+ parses the `with` syntax; the
+  // 18.19.x floor cannot parse it at all — see the import-text thread.) Unlike the
+  // fast-tier hook (preload-common.cjs) this ALWAYS polyfills, with no native
+  // fall-through gate: native import-text is Node 26.5+, but the compat tier tops out
+  // at Node 22.14, so a native-capable Node never reaches this loader worker.
+  // `isFileUrl` because this branch precedes extension dispatch and so is not covered
+  // by `extname`'s scheme gate; the polyfill reads the bytes off disk. Mirrors the
+  // fast-tier hook.
+  if (context?.importAttributes?.type === "text" && isFileUrl(url)) return loadTextImport(url);
+  const ext = extname(url);
+  // node_modules deps are NEVER transpiled (the byte-parity boundary). This guard is
+  // make-or-break now that TRANSPILE_EXTS includes `.js`/`.mjs`/`.cjs`: without it,
+  // the compat tier would route every dependency `.js` through oxc. (loadTranspile's
+  // own skip-gate handles the project-source no-op case; this keeps deps off the
+  // pipeline entirely.) Mirrors the fast-tier sync hook's `!isDependency` gate.
+  if (TRANSPILE_EXTS.has(ext) && !isDependency(url)) {
+    // Module-format + decorator detection inside loadTranspile is a synchronous
+    // native call (nub's addon), available on every supported Node — no parser
+    // warm-up needed (the old `await ensureParser()` for the ESM-only oxc-parser
+    // is gone with the package).
+    return loadTranspile(url, ext);
+  }
+  // Project-source plain JS: transpile ONLY when it carries transformable syntax. A
+  // no-op plain-JS file returns null and falls through to `nextLoad` — Node's own
+  // loader handles it byte-identically, preserving every native CJS/ESM behavior.
+  // node_modules excluded (the byte-parity boundary).
+  if (PLAIN_JS_EXTS.has(ext) && !isDependency(url)) {
+    const r = maybeTranspilePlainJs(url, ext);
+    if (r) return r;
+  }
+  // Data-format imports. dataExtsFor pins node_modules to nub's BUILT-IN loaders, so
+  // the project's `loader` config can't redefine how a dependency's imports load.
+  if (ext in dataExtsFor(url)) return loadData(url, ext);
+  return nextLoad(url, context);
+}