nstdlib-nightly/lib/internal/modules/helpers.mjs

Node.js standard library converted to runtime-agnostic ES modules.

// Source: https://github.com/nodejs/node/blob/65eff1eb/lib/internal/modules/helpers.js

import * as __hoisted_internal_deps_amaro_dist_index__ from "nstdlib/stub/internal/deps/amaro/dist/index";
import { codes as __codes__ } from "nstdlib/lib/internal/errors";
import { BuiltinModule } from "nstdlib/lib/internal/bootstrap/realm";
import { validateString } from "nstdlib/lib/internal/validators";
import * as fs from "nstdlib/lib/fs";
import * as internalFS from "nstdlib/lib/internal/fs/utils";
import * as path from "nstdlib/lib/path";
import { pathToFileURL, fileURLToPath } from "nstdlib/lib/internal/url";
import * as assert from "nstdlib/lib/internal/assert";
import { Buffer } from "nstdlib/lib/buffer";
import { getOptionValue } from "nstdlib/lib/internal/options";
import { setOwnProperty } from "nstdlib/lib/internal/util";
import { inspect } from "nstdlib/lib/internal/util/inspect";
import { canParse as URLCanParse } from "nstdlib/stub/binding/url";
import * as __hoisted_internal_modules_cjs_loader__ from "nstdlib/lib/internal/modules/cjs/loader";

const { ERR_INVALID_ARG_TYPE } = __codes__;

// Import all of `fs` so that it can be monkey-patched.

/** @typedef {import('internal/modules/cjs/loader.js').Module} Module */

/**
 * Cache for storing resolved real paths of modules.
 * In order to minimize unnecessary lstat() calls, this cache is a list of known-real paths.
 * Set to an empty Map to reset.
 * @type {Map<string, string>}
 */
const realpathCache = new Map();
/**
 * Resolves the path of a given `require` specifier, following symlinks.
 * @param {string} requestPath The `require` specifier
 */
function toRealPath(requestPath) {
  return fs.realpathSync(requestPath, {
    [internalFS.realpathCacheKey]: realpathCache,
  });
}

/** @type {Set<string>} */
let cjsConditions;
/**
 * Define the conditions that apply to the CommonJS loader.
 */
function initializeCjsConditions() {
  const userConditions = getOptionValue("--conditions");
  const noAddons = getOptionValue("--no-addons");
  const addonConditions = noAddons ? [] : ["node-addons"];
  // TODO: Use this set when resolving pkg#exports conditions in loader.js.
  cjsConditions = new Set([
    "require",
    "node",
    ...addonConditions,
    ...userConditions,
  ]);
}

/**
 * Get the conditions that apply to the CommonJS loader.
 */
function getCjsConditions() {
  if (cjsConditions === undefined) {
    initializeCjsConditions();
  }
  return cjsConditions;
}

/**
 * Provide one of Node.js' public modules to user code.
 * @param {string} id - The identifier/specifier of the builtin module to load
 * @param {string} request - The module requiring or importing the builtin module
 */
function loadBuiltinModule(id, request) {
  if (!BuiltinModule.canBeRequiredByUsers(id)) {
    return;
  }
  /** @type {import('internal/bootstrap/realm.js').BuiltinModule} */
  const mod = BuiltinModule.map.get(id);
  {
    /* debug */
  }
  // compileForPublicLoader() throws if canBeRequiredByUsers is false:
  mod.compileForPublicLoader();
  return mod;
}

/** @type {Module} */
let $Module = null;
/**
 * Import the Module class on first use.
 */
function lazyModule() {
  $Module = $Module || __hoisted_internal_modules_cjs_loader__.Module;
  return $Module;
}

/**
 * Create the module-scoped `require` function to pass into CommonJS modules.
 * @param {Module} mod - The module to create the `require` function for.
 * @typedef {(specifier: string) => unknown} RequireFunction
 */
function makeRequireFunction(mod) {
  // lazy due to cycle
  const Module = lazyModule();
  if (mod instanceof Module !== true) {
    throw new ERR_INVALID_ARG_TYPE("mod", "Module", mod);
  }

  function require(path) {
    return mod.require(path);
  }

  /**
   * The `resolve` method that gets attached to module-scope `require`.
   * @param {string} request
   * @param {Parameters<Module['_resolveFilename']>[3]} options
   */
  function resolve(request, options) {
    validateString(request, "request");
    return Module._resolveFilename(request, mod, false, options);
  }

  require.resolve = resolve;

  /**
   * The `paths` method that gets attached to module-scope `require`.
   * @param {string} request
   */
  function paths(request) {
    validateString(request, "request");
    return Module._resolveLookupPaths(request, mod);
  }

  resolve.paths = paths;

  setOwnProperty(require, "main", process.mainModule);

  // Enable support to add extra extension types.
  require.extensions = Module._extensions;

  require.cache = Module._cache;

  return require;
}

/**
 * Remove byte order marker. This catches EF BB BF (the UTF-8 BOM)
 * because the buffer-to-string conversion in `fs.readFileSync()`
 * translates it to FEFF, the UTF-16 BOM.
 * @param {string} content
 */
function stripBOM(content) {
  if (String.prototype.charCodeAt.call(content) === 0xfeff) {
    content = String.prototype.slice.call(content, 1);
  }
  return content;
}

/**
 * Add built-in modules to a global or REPL scope object.
 * @param {Record<string, unknown>} object - The object such as `globalThis` to add the built-in modules to.
 * @param {string} dummyModuleName - The label representing the set of built-in modules to add.
 */
function addBuiltinLibsToObject(object, dummyModuleName) {
  // Make built-in modules available directly (loaded lazily).
  const { Module: Module } = __hoisted_internal_modules_cjs_loader__;
  const { builtinModules } = Module;

  // To require built-in modules in user-land and ignore modules whose
  // `canBeRequiredByUsers` is false. So we create a dummy module object and not
  // use `require()` directly.
  const dummyModule = new Module(dummyModuleName);

  Array.prototype.forEach.call(builtinModules, (name) => {
    // Neither add underscored modules, nor ones that contain slashes (e.g.,
    // 'fs/promises') or ones that are already defined.
    if (
      String.prototype.startsWith.call(name, "_") ||
      String.prototype.includes.call(name, "/") ||
      Object.prototype.hasOwnProperty.call(object, name)
    ) {
      return;
    }
    // Goals of this mechanism are:
    // - Lazy loading of built-in modules
    // - Having all built-in modules available as non-enumerable properties
    // - Allowing the user to re-assign these variables as if there were no
    //   pre-existing globals with the same name.

    const setReal = (val) => {
      // Deleting the property before re-assigning it disables the
      // getter/setter mechanism.
      delete object[name];
      object[name] = val;
    };

    Object.defineProperty(object, name, {
      __proto__: null,
      get: () => {
        const lib = dummyModule.require(name);

        try {
          // Override the current getter/setter and set up a new
          // non-enumerable property.
          Object.defineProperty(object, name, {
            __proto__: null,
            get: () => lib,
            set: setReal,
            configurable: true,
            enumerable: false,
          });
        } catch {
          // If the property is no longer configurable, ignore the error.
        }

        return lib;
      },
      set: setReal,
      configurable: true,
      enumerable: false,
    });
  });
}

/**
 * Normalize the referrer name as a URL.
 * If it's a string containing an absolute path or a URL it's normalized as
 * a URL string.
 * Otherwise it's returned as undefined.
 * @param {string | null | undefined} referrerName
 * @returns {string | undefined}
 */
function normalizeReferrerURL(referrerName) {
  if (referrerName === null || referrerName === undefined) {
    return undefined;
  }

  if (typeof referrerName === "string") {
    if (path.isAbsolute(referrerName)) {
      return pathToFileURL(referrerName).href;
    }

    if (
      String.prototype.startsWith.call(referrerName, "file://") ||
      URLCanParse(referrerName)
    ) {
      return referrerName;
    }

    return undefined;
  }

  assert.fail("Unreachable code reached by " + inspect(referrerName));
}

/**
 * @param {string|undefined} url URL to convert to filename
 */
function urlToFilename(url) {
  if (url && String.prototype.startsWith.call(url, "file://")) {
    return fileURLToPath(url);
  }
  return url;
}

// Whether we have started executing any user-provided CJS code.
// This is set right before we call the wrapped CJS code (not after,
// in case we are half-way in the execution when internals check this).
// Used for internal assertions.
let _hasStartedUserCJSExecution = false;
// Similar to _hasStartedUserCJSExecution but for ESM. This is set
// right before ESM evaluation in the default ESM loader. We do not
// update this during vm SourceTextModule execution because at that point
// some user code must already have been run to execute code via vm
// there is little value checking whether any user JS code is run anyway.
let _hasStartedUserESMExecution = false;

/**
 * Load a public built-in module. ID may or may not be prefixed by `node:` and
 * will be normalized.
 * @param {string} id ID of the built-in to be loaded.
 * @returns {object|undefined} exports of the built-in. Undefined if the built-in
 * does not exist.
 */
function getBuiltinModule(id) {
  validateString(id, "id");
  const normalizedId = BuiltinModule.normalizeRequirableId(id);
  return normalizedId ? require(normalizedId) : undefined;
}

/**
 * TypeScript parsing function, by default Amaro.transformSync.
 *  @type {Function}
 */
let typeScriptParser;
/**
 * The TypeScript parsing mode, either 'strip-only' or 'transform'.
 * @type {string}
 */
let typeScriptParsingMode;
/**
 * Whether source maps are enabled for TypeScript parsing.
 * @type {boolean}
 */
let sourceMapEnabled;

/**
 * Load the TypeScript parser.
 * @param {Function} parser - A function that takes a string of TypeScript code
 * and returns an object with a `code` property.
 * @returns {Function} The TypeScript parser function.
 */
function loadTypeScriptParser(parser) {
  if (typeScriptParser) {
    return typeScriptParser;
  }

  if (parser) {
    typeScriptParser = parser;
  } else {
    const amaro = __hoisted_internal_deps_amaro_dist_index__;
    // Default option for Amaro is to perform Type Stripping only.
    typeScriptParsingMode = getOptionValue("--experimental-transform-types")
      ? "transform"
      : "strip-only";
    sourceMapEnabled = getOptionValue("--enable-source-maps");
    // Curry the transformSync function with the default options.
    typeScriptParser = amaro.transformSync;
  }
  return typeScriptParser;
}

/**
 * @typedef {object} TransformOutput
 * @property {string} code The compiled code.
 * @property {string} [map] The source maps (optional).
 *
 * Performs type-stripping to TypeScript source code.
 * @param {string} source TypeScript code to parse.
 * @param {string} filename The filename of the source code.
 * @returns {TransformOutput} The stripped TypeScript code.
 */
function stripTypeScriptTypes(source, filename) {
  assert(typeof source === "string");
  const parse = loadTypeScriptParser();
  const options = {
    __proto__: null,
    mode: typeScriptParsingMode,
    sourceMap: sourceMapEnabled,
    filename,
    // Transform option is only applied in transform mode.
    transform: {
      verbatimModuleSyntax: true,
    },
  };
  const { code, map } = parse(source, options);
  if (map) {
    // TODO(@marco-ippolito) When Buffer.transcode supports utf8 to
    // base64 transformation, we should change this line.
    const base64SourceMap = Buffer.from(map).toString("base64");
    return `${code}\n\n//# sourceMappingURL=data:application/json;base64,${base64SourceMap}`;
  }
  return code;
}

function isUnderNodeModules(filename) {
  const resolvedPath = path.resolve(filename);
  const normalizedPath = path.normalize(resolvedPath);
  const splitPath = String.prototype.split.call(normalizedPath, path.sep);
  return Array.prototype.includes.call(splitPath, "node_modules");
}

export { addBuiltinLibsToObject };
export { getBuiltinModule };
export { getCjsConditions };
export { initializeCjsConditions };
export { isUnderNodeModules };
export { loadBuiltinModule };
export { makeRequireFunction };
export { normalizeReferrerURL };
export { stripTypeScriptTypes };
export { stripBOM };
export { toRealPath };
const _export_hasStartedUserCJSExecution_ = function () {
  return _hasStartedUserCJSExecution;
};
export { _export_hasStartedUserCJSExecution_ as hasStartedUserCJSExecution };
const _export_setHasStartedUserCJSExecution_ = function () {
  _hasStartedUserCJSExecution = true;
};
export { _export_setHasStartedUserCJSExecution_ as setHasStartedUserCJSExecution };
const _export_hasStartedUserESMExecution_ = function () {
  return _hasStartedUserESMExecution;
};
export { _export_hasStartedUserESMExecution_ as hasStartedUserESMExecution };
const _export_setHasStartedUserESMExecution_ = function () {
  _hasStartedUserESMExecution = true;
};
export { _export_setHasStartedUserESMExecution_ as setHasStartedUserESMExecution };
export { urlToFilename };