11cb0ef41Sopenharmony_ci<!DOCTYPE html> 21cb0ef41Sopenharmony_ci<html lang="en"> 31cb0ef41Sopenharmony_ci<head> 41cb0ef41Sopenharmony_ci <meta charset="utf-8"> 51cb0ef41Sopenharmony_ci <meta name="viewport" content="width=device-width"> 61cb0ef41Sopenharmony_ci <meta name="nodejs.org:node-version" content="v18.20.1"> 71cb0ef41Sopenharmony_ci <title>Modules: node:module API | Node.js v18.20.1 Documentation</title> 81cb0ef41Sopenharmony_ci <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Lato:400,700,400italic&display=fallback"> 91cb0ef41Sopenharmony_ci <link rel="stylesheet" href="assets/style.css"> 101cb0ef41Sopenharmony_ci <link rel="stylesheet" href="assets/hljs.css"> 111cb0ef41Sopenharmony_ci <link rel="canonical" href="https://nodejs.org/api/module.html"> 121cb0ef41Sopenharmony_ci <script async defer src="assets/api.js" type="text/javascript"></script> 131cb0ef41Sopenharmony_ci <style>@media(max-width:430px){.with-26-chars>.js-flavor-selector{float:none;margin:0 0 1em auto;}}@media(max-width:574px){.with-44-chars>.js-flavor-selector{float:none;margin:0 0 1em auto;}}@media(max-width:590px){.with-46-chars>.js-flavor-selector{float:none;margin:0 0 1em auto;}}@media(max-width:646px){.with-53-chars>.js-flavor-selector{float:none;margin:0 0 1em auto;}}</style> 141cb0ef41Sopenharmony_ci</head> 151cb0ef41Sopenharmony_ci<body class="alt apidoc" id="api-section-module"> 161cb0ef41Sopenharmony_ci <div id="content" class="clearfix"> 171cb0ef41Sopenharmony_ci <div id="column2" class="interior"> 181cb0ef41Sopenharmony_ci <div id="intro" class="interior"> 191cb0ef41Sopenharmony_ci <a href="/" title="Go back to the home page"> 201cb0ef41Sopenharmony_ci Node.js 211cb0ef41Sopenharmony_ci </a> 221cb0ef41Sopenharmony_ci </div> 231cb0ef41Sopenharmony_ci <ul> 241cb0ef41Sopenharmony_ci<li><a href="documentation.html" class="nav-documentation">About this documentation</a></li> 251cb0ef41Sopenharmony_ci<li><a href="synopsis.html" class="nav-synopsis">Usage and example</a></li> 261cb0ef41Sopenharmony_ci</ul> 271cb0ef41Sopenharmony_ci<hr class="line"> 281cb0ef41Sopenharmony_ci<ul> 291cb0ef41Sopenharmony_ci<li><a href="assert.html" class="nav-assert">Assertion testing</a></li> 301cb0ef41Sopenharmony_ci<li><a href="async_context.html" class="nav-async_context">Asynchronous context tracking</a></li> 311cb0ef41Sopenharmony_ci<li><a href="async_hooks.html" class="nav-async_hooks">Async hooks</a></li> 321cb0ef41Sopenharmony_ci<li><a href="buffer.html" class="nav-buffer">Buffer</a></li> 331cb0ef41Sopenharmony_ci<li><a href="addons.html" class="nav-addons">C++ addons</a></li> 341cb0ef41Sopenharmony_ci<li><a href="n-api.html" class="nav-n-api">C/C++ addons with Node-API</a></li> 351cb0ef41Sopenharmony_ci<li><a href="embedding.html" class="nav-embedding">C++ embedder API</a></li> 361cb0ef41Sopenharmony_ci<li><a href="child_process.html" class="nav-child_process">Child processes</a></li> 371cb0ef41Sopenharmony_ci<li><a href="cluster.html" class="nav-cluster">Cluster</a></li> 381cb0ef41Sopenharmony_ci<li><a href="cli.html" class="nav-cli">Command-line options</a></li> 391cb0ef41Sopenharmony_ci<li><a href="console.html" class="nav-console">Console</a></li> 401cb0ef41Sopenharmony_ci<li><a href="corepack.html" class="nav-corepack">Corepack</a></li> 411cb0ef41Sopenharmony_ci<li><a href="crypto.html" class="nav-crypto">Crypto</a></li> 421cb0ef41Sopenharmony_ci<li><a href="debugger.html" class="nav-debugger">Debugger</a></li> 431cb0ef41Sopenharmony_ci<li><a href="deprecations.html" class="nav-deprecations">Deprecated APIs</a></li> 441cb0ef41Sopenharmony_ci<li><a href="diagnostics_channel.html" class="nav-diagnostics_channel">Diagnostics Channel</a></li> 451cb0ef41Sopenharmony_ci<li><a href="dns.html" class="nav-dns">DNS</a></li> 461cb0ef41Sopenharmony_ci<li><a href="domain.html" class="nav-domain">Domain</a></li> 471cb0ef41Sopenharmony_ci<li><a href="errors.html" class="nav-errors">Errors</a></li> 481cb0ef41Sopenharmony_ci<li><a href="events.html" class="nav-events">Events</a></li> 491cb0ef41Sopenharmony_ci<li><a href="fs.html" class="nav-fs">File system</a></li> 501cb0ef41Sopenharmony_ci<li><a href="globals.html" class="nav-globals">Globals</a></li> 511cb0ef41Sopenharmony_ci<li><a href="http.html" class="nav-http">HTTP</a></li> 521cb0ef41Sopenharmony_ci<li><a href="http2.html" class="nav-http2">HTTP/2</a></li> 531cb0ef41Sopenharmony_ci<li><a href="https.html" class="nav-https">HTTPS</a></li> 541cb0ef41Sopenharmony_ci<li><a href="inspector.html" class="nav-inspector">Inspector</a></li> 551cb0ef41Sopenharmony_ci<li><a href="intl.html" class="nav-intl">Internationalization</a></li> 561cb0ef41Sopenharmony_ci<li><a href="modules.html" class="nav-modules">Modules: CommonJS modules</a></li> 571cb0ef41Sopenharmony_ci<li><a href="esm.html" class="nav-esm">Modules: ECMAScript modules</a></li> 581cb0ef41Sopenharmony_ci<li><a href="module.html" class="nav-module active">Modules: <code>node:module</code> API</a></li> 591cb0ef41Sopenharmony_ci<li><a href="packages.html" class="nav-packages">Modules: Packages</a></li> 601cb0ef41Sopenharmony_ci<li><a href="net.html" class="nav-net">Net</a></li> 611cb0ef41Sopenharmony_ci<li><a href="os.html" class="nav-os">OS</a></li> 621cb0ef41Sopenharmony_ci<li><a href="path.html" class="nav-path">Path</a></li> 631cb0ef41Sopenharmony_ci<li><a href="perf_hooks.html" class="nav-perf_hooks">Performance hooks</a></li> 641cb0ef41Sopenharmony_ci<li><a href="permissions.html" class="nav-permissions">Permissions</a></li> 651cb0ef41Sopenharmony_ci<li><a href="process.html" class="nav-process">Process</a></li> 661cb0ef41Sopenharmony_ci<li><a href="punycode.html" class="nav-punycode">Punycode</a></li> 671cb0ef41Sopenharmony_ci<li><a href="querystring.html" class="nav-querystring">Query strings</a></li> 681cb0ef41Sopenharmony_ci<li><a href="readline.html" class="nav-readline">Readline</a></li> 691cb0ef41Sopenharmony_ci<li><a href="repl.html" class="nav-repl">REPL</a></li> 701cb0ef41Sopenharmony_ci<li><a href="report.html" class="nav-report">Report</a></li> 711cb0ef41Sopenharmony_ci<li><a href="single-executable-applications.html" class="nav-single-executable-applications">Single executable applications</a></li> 721cb0ef41Sopenharmony_ci<li><a href="stream.html" class="nav-stream">Stream</a></li> 731cb0ef41Sopenharmony_ci<li><a href="string_decoder.html" class="nav-string_decoder">String decoder</a></li> 741cb0ef41Sopenharmony_ci<li><a href="test.html" class="nav-test">Test runner</a></li> 751cb0ef41Sopenharmony_ci<li><a href="timers.html" class="nav-timers">Timers</a></li> 761cb0ef41Sopenharmony_ci<li><a href="tls.html" class="nav-tls">TLS/SSL</a></li> 771cb0ef41Sopenharmony_ci<li><a href="tracing.html" class="nav-tracing">Trace events</a></li> 781cb0ef41Sopenharmony_ci<li><a href="tty.html" class="nav-tty">TTY</a></li> 791cb0ef41Sopenharmony_ci<li><a href="dgram.html" class="nav-dgram">UDP/datagram</a></li> 801cb0ef41Sopenharmony_ci<li><a href="url.html" class="nav-url">URL</a></li> 811cb0ef41Sopenharmony_ci<li><a href="util.html" class="nav-util">Utilities</a></li> 821cb0ef41Sopenharmony_ci<li><a href="v8.html" class="nav-v8">V8</a></li> 831cb0ef41Sopenharmony_ci<li><a href="vm.html" class="nav-vm">VM</a></li> 841cb0ef41Sopenharmony_ci<li><a href="wasi.html" class="nav-wasi">WASI</a></li> 851cb0ef41Sopenharmony_ci<li><a href="webcrypto.html" class="nav-webcrypto">Web Crypto API</a></li> 861cb0ef41Sopenharmony_ci<li><a href="webstreams.html" class="nav-webstreams">Web Streams API</a></li> 871cb0ef41Sopenharmony_ci<li><a href="worker_threads.html" class="nav-worker_threads">Worker threads</a></li> 881cb0ef41Sopenharmony_ci<li><a href="zlib.html" class="nav-zlib">Zlib</a></li> 891cb0ef41Sopenharmony_ci</ul> 901cb0ef41Sopenharmony_ci<hr class="line"> 911cb0ef41Sopenharmony_ci<ul> 921cb0ef41Sopenharmony_ci<li><a href="https://github.com/nodejs/node" class="nav-https-github-com-nodejs-node">Code repository and issue tracker</a></li> 931cb0ef41Sopenharmony_ci</ul> 941cb0ef41Sopenharmony_ci </div> 951cb0ef41Sopenharmony_ci 961cb0ef41Sopenharmony_ci <div id="column1" data-id="module" class="interior"> 971cb0ef41Sopenharmony_ci <header class="header"> 981cb0ef41Sopenharmony_ci <div class="header-container"> 991cb0ef41Sopenharmony_ci <h1>Node.js v18.20.1 documentation</h1> 1001cb0ef41Sopenharmony_ci <button class="theme-toggle-btn" id="theme-toggle-btn" title="Toggle dark mode/light mode" aria-label="Toggle dark mode/light mode" hidden> 1011cb0ef41Sopenharmony_ci <svg xmlns="http://www.w3.org/2000/svg" class="icon dark-icon" height="24" width="24"> 1021cb0ef41Sopenharmony_ci <path fill="none" d="M0 0h24v24H0z" /> 1031cb0ef41Sopenharmony_ci <path d="M11.1 12.08c-2.33-4.51-.5-8.48.53-10.07C6.27 2.2 1.98 6.59 1.98 12c0 .14.02.28.02.42.62-.27 1.29-.42 2-.42 1.66 0 3.18.83 4.1 2.15A4.01 4.01 0 0111 18c0 1.52-.87 2.83-2.12 3.51.98.32 2.03.5 3.11.5 3.5 0 6.58-1.8 8.37-4.52-2.36.23-6.98-.97-9.26-5.41z"/> 1041cb0ef41Sopenharmony_ci <path d="M7 16h-.18C6.4 14.84 5.3 14 4 14c-1.66 0-3 1.34-3 3s1.34 3 3 3h3c1.1 0 2-.9 2-2s-.9-2-2-2z"/> 1051cb0ef41Sopenharmony_ci </svg> 1061cb0ef41Sopenharmony_ci <svg xmlns="http://www.w3.org/2000/svg" class="icon light-icon" height="24" width="24"> 1071cb0ef41Sopenharmony_ci <path d="M0 0h24v24H0z" fill="none" /> 1081cb0ef41Sopenharmony_ci <path d="M6.76 4.84l-1.8-1.79-1.41 1.41 1.79 1.79 1.42-1.41zM4 10.5H1v2h3v-2zm9-9.95h-2V3.5h2V.55zm7.45 3.91l-1.41-1.41-1.79 1.79 1.41 1.41 1.79-1.79zm-3.21 13.7l1.79 1.8 1.41-1.41-1.8-1.79-1.4 1.4zM20 10.5v2h3v-2h-3zm-8-5c-3.31 0-6 2.69-6 6s2.69 6 6 6 6-2.69 6-6-2.69-6-6-6zm-1 16.95h2V19.5h-2v2.95zm-7.45-3.91l1.41 1.41 1.79-1.8-1.41-1.41-1.79 1.8z"/> 1091cb0ef41Sopenharmony_ci </svg> 1101cb0ef41Sopenharmony_ci </button> 1111cb0ef41Sopenharmony_ci </div> 1121cb0ef41Sopenharmony_ci <div id="gtoc"> 1131cb0ef41Sopenharmony_ci <ul> 1141cb0ef41Sopenharmony_ci <li class="pinned-header">Node.js v18.20.1</li> 1151cb0ef41Sopenharmony_ci 1161cb0ef41Sopenharmony_ci <li class="picker-header"> 1171cb0ef41Sopenharmony_ci <a href="#"> 1181cb0ef41Sopenharmony_ci <span class="collapsed-arrow">►</span><span class="expanded-arrow">▼</span> 1191cb0ef41Sopenharmony_ci Table of contents 1201cb0ef41Sopenharmony_ci </a> 1211cb0ef41Sopenharmony_ci 1221cb0ef41Sopenharmony_ci <div class="picker"><div class="toc"><ul> 1231cb0ef41Sopenharmony_ci<li><a href="#modules-nodemodule-api">Modules: <code>node:module</code> API</a> 1241cb0ef41Sopenharmony_ci<ul> 1251cb0ef41Sopenharmony_ci<li><a href="#the-module-object">The <code>Module</code> object</a> 1261cb0ef41Sopenharmony_ci<ul> 1271cb0ef41Sopenharmony_ci<li><a href="#modulebuiltinmodules"><code>module.builtinModules</code></a></li> 1281cb0ef41Sopenharmony_ci<li><a href="#modulecreaterequirefilename"><code>module.createRequire(filename)</code></a></li> 1291cb0ef41Sopenharmony_ci<li><a href="#moduleisbuiltinmodulename"><code>module.isBuiltin(moduleName)</code></a></li> 1301cb0ef41Sopenharmony_ci<li><span class="stability_1"><a href="#moduleregisterspecifier-parenturl-options"><code>module.register(specifier[, parentURL][, options])</code></a></span></li> 1311cb0ef41Sopenharmony_ci<li><a href="#modulesyncbuiltinesmexports"><code>module.syncBuiltinESMExports()</code></a></li> 1321cb0ef41Sopenharmony_ci</ul> 1331cb0ef41Sopenharmony_ci</li> 1341cb0ef41Sopenharmony_ci<li><span class="stability_1"><a href="#customization-hooks">Customization Hooks</a></span> 1351cb0ef41Sopenharmony_ci<ul> 1361cb0ef41Sopenharmony_ci<li><a href="#enabling">Enabling</a></li> 1371cb0ef41Sopenharmony_ci<li><a href="#chaining">Chaining</a></li> 1381cb0ef41Sopenharmony_ci<li><a href="#communication-with-module-customization-hooks">Communication with module customization hooks</a></li> 1391cb0ef41Sopenharmony_ci<li><a href="#hooks">Hooks</a> 1401cb0ef41Sopenharmony_ci<ul> 1411cb0ef41Sopenharmony_ci<li><span class="stability_1"><a href="#initialize"><code>initialize()</code></a></span></li> 1421cb0ef41Sopenharmony_ci<li><span class="stability_1"><a href="#resolvespecifier-context-nextresolve"><code>resolve(specifier, context, nextResolve)</code></a></span></li> 1431cb0ef41Sopenharmony_ci<li><span class="stability_1"><a href="#loadurl-context-nextload"><code>load(url, context, nextLoad)</code></a></span></li> 1441cb0ef41Sopenharmony_ci<li><span class="stability_1"><a href="#globalpreload"><code>globalPreload()</code></a></span></li> 1451cb0ef41Sopenharmony_ci</ul> 1461cb0ef41Sopenharmony_ci</li> 1471cb0ef41Sopenharmony_ci<li><a href="#examples">Examples</a> 1481cb0ef41Sopenharmony_ci<ul> 1491cb0ef41Sopenharmony_ci<li><a href="#import-from-https">Import from HTTPS</a></li> 1501cb0ef41Sopenharmony_ci<li><a href="#transpilation">Transpilation</a></li> 1511cb0ef41Sopenharmony_ci<li><a href="#import-maps">Import maps</a></li> 1521cb0ef41Sopenharmony_ci</ul> 1531cb0ef41Sopenharmony_ci</li> 1541cb0ef41Sopenharmony_ci</ul> 1551cb0ef41Sopenharmony_ci</li> 1561cb0ef41Sopenharmony_ci<li><span class="stability_1"><a href="#source-map-v3-support">Source map v3 support</a></span> 1571cb0ef41Sopenharmony_ci<ul> 1581cb0ef41Sopenharmony_ci<li><a href="#modulefindsourcemappath"><code>module.findSourceMap(path)</code></a></li> 1591cb0ef41Sopenharmony_ci<li><a href="#class-modulesourcemap">Class: <code>module.SourceMap</code></a> 1601cb0ef41Sopenharmony_ci<ul> 1611cb0ef41Sopenharmony_ci<li><a href="#new-sourcemappayload"><code>new SourceMap(payload)</code></a></li> 1621cb0ef41Sopenharmony_ci<li><a href="#sourcemappayload"><code>sourceMap.payload</code></a></li> 1631cb0ef41Sopenharmony_ci<li><a href="#sourcemapfindentrylineoffset-columnoffset"><code>sourceMap.findEntry(lineOffset, columnOffset)</code></a></li> 1641cb0ef41Sopenharmony_ci<li><a href="#sourcemapfindoriginlinenumber-columnnumber"><code>sourceMap.findOrigin(lineNumber, columnNumber)</code></a></li> 1651cb0ef41Sopenharmony_ci</ul> 1661cb0ef41Sopenharmony_ci</li> 1671cb0ef41Sopenharmony_ci</ul> 1681cb0ef41Sopenharmony_ci</li> 1691cb0ef41Sopenharmony_ci</ul> 1701cb0ef41Sopenharmony_ci</li> 1711cb0ef41Sopenharmony_ci</ul></div></div> 1721cb0ef41Sopenharmony_ci </li> 1731cb0ef41Sopenharmony_ci 1741cb0ef41Sopenharmony_ci 1751cb0ef41Sopenharmony_ci <li class="picker-header"> 1761cb0ef41Sopenharmony_ci <a href="#"> 1771cb0ef41Sopenharmony_ci <span class="collapsed-arrow">►</span><span class="expanded-arrow">▼</span> 1781cb0ef41Sopenharmony_ci Index 1791cb0ef41Sopenharmony_ci </a> 1801cb0ef41Sopenharmony_ci 1811cb0ef41Sopenharmony_ci <div class="picker"><ul> 1821cb0ef41Sopenharmony_ci<li><a href="documentation.html" class="nav-documentation">About this documentation</a></li> 1831cb0ef41Sopenharmony_ci<li><a href="synopsis.html" class="nav-synopsis">Usage and example</a></li> 1841cb0ef41Sopenharmony_ci 1851cb0ef41Sopenharmony_ci <li> 1861cb0ef41Sopenharmony_ci <a href="index.html">Index</a> 1871cb0ef41Sopenharmony_ci </li> 1881cb0ef41Sopenharmony_ci </ul> 1891cb0ef41Sopenharmony_ci 1901cb0ef41Sopenharmony_ci<hr class="line"> 1911cb0ef41Sopenharmony_ci<ul> 1921cb0ef41Sopenharmony_ci<li><a href="assert.html" class="nav-assert">Assertion testing</a></li> 1931cb0ef41Sopenharmony_ci<li><a href="async_context.html" class="nav-async_context">Asynchronous context tracking</a></li> 1941cb0ef41Sopenharmony_ci<li><a href="async_hooks.html" class="nav-async_hooks">Async hooks</a></li> 1951cb0ef41Sopenharmony_ci<li><a href="buffer.html" class="nav-buffer">Buffer</a></li> 1961cb0ef41Sopenharmony_ci<li><a href="addons.html" class="nav-addons">C++ addons</a></li> 1971cb0ef41Sopenharmony_ci<li><a href="n-api.html" class="nav-n-api">C/C++ addons with Node-API</a></li> 1981cb0ef41Sopenharmony_ci<li><a href="embedding.html" class="nav-embedding">C++ embedder API</a></li> 1991cb0ef41Sopenharmony_ci<li><a href="child_process.html" class="nav-child_process">Child processes</a></li> 2001cb0ef41Sopenharmony_ci<li><a href="cluster.html" class="nav-cluster">Cluster</a></li> 2011cb0ef41Sopenharmony_ci<li><a href="cli.html" class="nav-cli">Command-line options</a></li> 2021cb0ef41Sopenharmony_ci<li><a href="console.html" class="nav-console">Console</a></li> 2031cb0ef41Sopenharmony_ci<li><a href="corepack.html" class="nav-corepack">Corepack</a></li> 2041cb0ef41Sopenharmony_ci<li><a href="crypto.html" class="nav-crypto">Crypto</a></li> 2051cb0ef41Sopenharmony_ci<li><a href="debugger.html" class="nav-debugger">Debugger</a></li> 2061cb0ef41Sopenharmony_ci<li><a href="deprecations.html" class="nav-deprecations">Deprecated APIs</a></li> 2071cb0ef41Sopenharmony_ci<li><a href="diagnostics_channel.html" class="nav-diagnostics_channel">Diagnostics Channel</a></li> 2081cb0ef41Sopenharmony_ci<li><a href="dns.html" class="nav-dns">DNS</a></li> 2091cb0ef41Sopenharmony_ci<li><a href="domain.html" class="nav-domain">Domain</a></li> 2101cb0ef41Sopenharmony_ci<li><a href="errors.html" class="nav-errors">Errors</a></li> 2111cb0ef41Sopenharmony_ci<li><a href="events.html" class="nav-events">Events</a></li> 2121cb0ef41Sopenharmony_ci<li><a href="fs.html" class="nav-fs">File system</a></li> 2131cb0ef41Sopenharmony_ci<li><a href="globals.html" class="nav-globals">Globals</a></li> 2141cb0ef41Sopenharmony_ci<li><a href="http.html" class="nav-http">HTTP</a></li> 2151cb0ef41Sopenharmony_ci<li><a href="http2.html" class="nav-http2">HTTP/2</a></li> 2161cb0ef41Sopenharmony_ci<li><a href="https.html" class="nav-https">HTTPS</a></li> 2171cb0ef41Sopenharmony_ci<li><a href="inspector.html" class="nav-inspector">Inspector</a></li> 2181cb0ef41Sopenharmony_ci<li><a href="intl.html" class="nav-intl">Internationalization</a></li> 2191cb0ef41Sopenharmony_ci<li><a href="modules.html" class="nav-modules">Modules: CommonJS modules</a></li> 2201cb0ef41Sopenharmony_ci<li><a href="esm.html" class="nav-esm">Modules: ECMAScript modules</a></li> 2211cb0ef41Sopenharmony_ci<li><a href="module.html" class="nav-module active">Modules: <code>node:module</code> API</a></li> 2221cb0ef41Sopenharmony_ci<li><a href="packages.html" class="nav-packages">Modules: Packages</a></li> 2231cb0ef41Sopenharmony_ci<li><a href="net.html" class="nav-net">Net</a></li> 2241cb0ef41Sopenharmony_ci<li><a href="os.html" class="nav-os">OS</a></li> 2251cb0ef41Sopenharmony_ci<li><a href="path.html" class="nav-path">Path</a></li> 2261cb0ef41Sopenharmony_ci<li><a href="perf_hooks.html" class="nav-perf_hooks">Performance hooks</a></li> 2271cb0ef41Sopenharmony_ci<li><a href="permissions.html" class="nav-permissions">Permissions</a></li> 2281cb0ef41Sopenharmony_ci<li><a href="process.html" class="nav-process">Process</a></li> 2291cb0ef41Sopenharmony_ci<li><a href="punycode.html" class="nav-punycode">Punycode</a></li> 2301cb0ef41Sopenharmony_ci<li><a href="querystring.html" class="nav-querystring">Query strings</a></li> 2311cb0ef41Sopenharmony_ci<li><a href="readline.html" class="nav-readline">Readline</a></li> 2321cb0ef41Sopenharmony_ci<li><a href="repl.html" class="nav-repl">REPL</a></li> 2331cb0ef41Sopenharmony_ci<li><a href="report.html" class="nav-report">Report</a></li> 2341cb0ef41Sopenharmony_ci<li><a href="single-executable-applications.html" class="nav-single-executable-applications">Single executable applications</a></li> 2351cb0ef41Sopenharmony_ci<li><a href="stream.html" class="nav-stream">Stream</a></li> 2361cb0ef41Sopenharmony_ci<li><a href="string_decoder.html" class="nav-string_decoder">String decoder</a></li> 2371cb0ef41Sopenharmony_ci<li><a href="test.html" class="nav-test">Test runner</a></li> 2381cb0ef41Sopenharmony_ci<li><a href="timers.html" class="nav-timers">Timers</a></li> 2391cb0ef41Sopenharmony_ci<li><a href="tls.html" class="nav-tls">TLS/SSL</a></li> 2401cb0ef41Sopenharmony_ci<li><a href="tracing.html" class="nav-tracing">Trace events</a></li> 2411cb0ef41Sopenharmony_ci<li><a href="tty.html" class="nav-tty">TTY</a></li> 2421cb0ef41Sopenharmony_ci<li><a href="dgram.html" class="nav-dgram">UDP/datagram</a></li> 2431cb0ef41Sopenharmony_ci<li><a href="url.html" class="nav-url">URL</a></li> 2441cb0ef41Sopenharmony_ci<li><a href="util.html" class="nav-util">Utilities</a></li> 2451cb0ef41Sopenharmony_ci<li><a href="v8.html" class="nav-v8">V8</a></li> 2461cb0ef41Sopenharmony_ci<li><a href="vm.html" class="nav-vm">VM</a></li> 2471cb0ef41Sopenharmony_ci<li><a href="wasi.html" class="nav-wasi">WASI</a></li> 2481cb0ef41Sopenharmony_ci<li><a href="webcrypto.html" class="nav-webcrypto">Web Crypto API</a></li> 2491cb0ef41Sopenharmony_ci<li><a href="webstreams.html" class="nav-webstreams">Web Streams API</a></li> 2501cb0ef41Sopenharmony_ci<li><a href="worker_threads.html" class="nav-worker_threads">Worker threads</a></li> 2511cb0ef41Sopenharmony_ci<li><a href="zlib.html" class="nav-zlib">Zlib</a></li> 2521cb0ef41Sopenharmony_ci</ul> 2531cb0ef41Sopenharmony_ci<hr class="line"> 2541cb0ef41Sopenharmony_ci<ul> 2551cb0ef41Sopenharmony_ci<li><a href="https://github.com/nodejs/node" class="nav-https-github-com-nodejs-node">Code repository and issue tracker</a></li> 2561cb0ef41Sopenharmony_ci</ul></div> 2571cb0ef41Sopenharmony_ci </li> 2581cb0ef41Sopenharmony_ci 2591cb0ef41Sopenharmony_ci 2601cb0ef41Sopenharmony_ci <li class="picker-header"> 2611cb0ef41Sopenharmony_ci <a href="#"> 2621cb0ef41Sopenharmony_ci <span class="collapsed-arrow">►</span><span class="expanded-arrow">▼</span> 2631cb0ef41Sopenharmony_ci Other versions 2641cb0ef41Sopenharmony_ci </a> 2651cb0ef41Sopenharmony_ci <div class="picker"><ol id="alt-docs"><li><a href="https://nodejs.org/docs/latest-v21.x/api/module.html">21.x</a></li> 2661cb0ef41Sopenharmony_ci<li><a href="https://nodejs.org/docs/latest-v20.x/api/module.html">20.x <b>LTS</b></a></li> 2671cb0ef41Sopenharmony_ci<li><a href="https://nodejs.org/docs/latest-v19.x/api/module.html">19.x</a></li> 2681cb0ef41Sopenharmony_ci<li><a href="https://nodejs.org/docs/latest-v18.x/api/module.html">18.x <b>LTS</b></a></li> 2691cb0ef41Sopenharmony_ci<li><a href="https://nodejs.org/docs/latest-v17.x/api/module.html">17.x</a></li> 2701cb0ef41Sopenharmony_ci<li><a href="https://nodejs.org/docs/latest-v16.x/api/module.html">16.x</a></li> 2711cb0ef41Sopenharmony_ci<li><a href="https://nodejs.org/docs/latest-v15.x/api/module.html">15.x</a></li> 2721cb0ef41Sopenharmony_ci<li><a href="https://nodejs.org/docs/latest-v14.x/api/module.html">14.x</a></li> 2731cb0ef41Sopenharmony_ci<li><a href="https://nodejs.org/docs/latest-v13.x/api/module.html">13.x</a></li> 2741cb0ef41Sopenharmony_ci<li><a href="https://nodejs.org/docs/latest-v12.x/api/module.html">12.x</a></li></ol></div> 2751cb0ef41Sopenharmony_ci </li> 2761cb0ef41Sopenharmony_ci 2771cb0ef41Sopenharmony_ci <li class="picker-header"> 2781cb0ef41Sopenharmony_ci <a href="#"> 2791cb0ef41Sopenharmony_ci <span class="collapsed-arrow">►</span><span class="expanded-arrow">▼</span> 2801cb0ef41Sopenharmony_ci Options 2811cb0ef41Sopenharmony_ci </a> 2821cb0ef41Sopenharmony_ci 2831cb0ef41Sopenharmony_ci <div class="picker"> 2841cb0ef41Sopenharmony_ci <ul> 2851cb0ef41Sopenharmony_ci <li> 2861cb0ef41Sopenharmony_ci <a href="all.html">View on single page</a> 2871cb0ef41Sopenharmony_ci </li> 2881cb0ef41Sopenharmony_ci <li> 2891cb0ef41Sopenharmony_ci <a href="module.json">View as JSON</a> 2901cb0ef41Sopenharmony_ci </li> 2911cb0ef41Sopenharmony_ci <li class="edit_on_github"><a href="https://github.com/nodejs/node/edit/main/doc/api/module.md">Edit on GitHub</a></li> 2921cb0ef41Sopenharmony_ci </ul> 2931cb0ef41Sopenharmony_ci </div> 2941cb0ef41Sopenharmony_ci </li> 2951cb0ef41Sopenharmony_ci </ul> 2961cb0ef41Sopenharmony_ci </div> 2971cb0ef41Sopenharmony_ci <hr> 2981cb0ef41Sopenharmony_ci </header> 2991cb0ef41Sopenharmony_ci 3001cb0ef41Sopenharmony_ci <details id="toc" open><summary>Table of contents</summary><ul> 3011cb0ef41Sopenharmony_ci<li><a href="#modules-nodemodule-api">Modules: <code>node:module</code> API</a> 3021cb0ef41Sopenharmony_ci<ul> 3031cb0ef41Sopenharmony_ci<li><a href="#the-module-object">The <code>Module</code> object</a> 3041cb0ef41Sopenharmony_ci<ul> 3051cb0ef41Sopenharmony_ci<li><a href="#modulebuiltinmodules"><code>module.builtinModules</code></a></li> 3061cb0ef41Sopenharmony_ci<li><a href="#modulecreaterequirefilename"><code>module.createRequire(filename)</code></a></li> 3071cb0ef41Sopenharmony_ci<li><a href="#moduleisbuiltinmodulename"><code>module.isBuiltin(moduleName)</code></a></li> 3081cb0ef41Sopenharmony_ci<li><span class="stability_1"><a href="#moduleregisterspecifier-parenturl-options"><code>module.register(specifier[, parentURL][, options])</code></a></span></li> 3091cb0ef41Sopenharmony_ci<li><a href="#modulesyncbuiltinesmexports"><code>module.syncBuiltinESMExports()</code></a></li> 3101cb0ef41Sopenharmony_ci</ul> 3111cb0ef41Sopenharmony_ci</li> 3121cb0ef41Sopenharmony_ci<li><span class="stability_1"><a href="#customization-hooks">Customization Hooks</a></span> 3131cb0ef41Sopenharmony_ci<ul> 3141cb0ef41Sopenharmony_ci<li><a href="#enabling">Enabling</a></li> 3151cb0ef41Sopenharmony_ci<li><a href="#chaining">Chaining</a></li> 3161cb0ef41Sopenharmony_ci<li><a href="#communication-with-module-customization-hooks">Communication with module customization hooks</a></li> 3171cb0ef41Sopenharmony_ci<li><a href="#hooks">Hooks</a> 3181cb0ef41Sopenharmony_ci<ul> 3191cb0ef41Sopenharmony_ci<li><span class="stability_1"><a href="#initialize"><code>initialize()</code></a></span></li> 3201cb0ef41Sopenharmony_ci<li><span class="stability_1"><a href="#resolvespecifier-context-nextresolve"><code>resolve(specifier, context, nextResolve)</code></a></span></li> 3211cb0ef41Sopenharmony_ci<li><span class="stability_1"><a href="#loadurl-context-nextload"><code>load(url, context, nextLoad)</code></a></span></li> 3221cb0ef41Sopenharmony_ci<li><span class="stability_1"><a href="#globalpreload"><code>globalPreload()</code></a></span></li> 3231cb0ef41Sopenharmony_ci</ul> 3241cb0ef41Sopenharmony_ci</li> 3251cb0ef41Sopenharmony_ci<li><a href="#examples">Examples</a> 3261cb0ef41Sopenharmony_ci<ul> 3271cb0ef41Sopenharmony_ci<li><a href="#import-from-https">Import from HTTPS</a></li> 3281cb0ef41Sopenharmony_ci<li><a href="#transpilation">Transpilation</a></li> 3291cb0ef41Sopenharmony_ci<li><a href="#import-maps">Import maps</a></li> 3301cb0ef41Sopenharmony_ci</ul> 3311cb0ef41Sopenharmony_ci</li> 3321cb0ef41Sopenharmony_ci</ul> 3331cb0ef41Sopenharmony_ci</li> 3341cb0ef41Sopenharmony_ci<li><span class="stability_1"><a href="#source-map-v3-support">Source map v3 support</a></span> 3351cb0ef41Sopenharmony_ci<ul> 3361cb0ef41Sopenharmony_ci<li><a href="#modulefindsourcemappath"><code>module.findSourceMap(path)</code></a></li> 3371cb0ef41Sopenharmony_ci<li><a href="#class-modulesourcemap">Class: <code>module.SourceMap</code></a> 3381cb0ef41Sopenharmony_ci<ul> 3391cb0ef41Sopenharmony_ci<li><a href="#new-sourcemappayload"><code>new SourceMap(payload)</code></a></li> 3401cb0ef41Sopenharmony_ci<li><a href="#sourcemappayload"><code>sourceMap.payload</code></a></li> 3411cb0ef41Sopenharmony_ci<li><a href="#sourcemapfindentrylineoffset-columnoffset"><code>sourceMap.findEntry(lineOffset, columnOffset)</code></a></li> 3421cb0ef41Sopenharmony_ci<li><a href="#sourcemapfindoriginlinenumber-columnnumber"><code>sourceMap.findOrigin(lineNumber, columnNumber)</code></a></li> 3431cb0ef41Sopenharmony_ci</ul> 3441cb0ef41Sopenharmony_ci</li> 3451cb0ef41Sopenharmony_ci</ul> 3461cb0ef41Sopenharmony_ci</li> 3471cb0ef41Sopenharmony_ci</ul> 3481cb0ef41Sopenharmony_ci</li> 3491cb0ef41Sopenharmony_ci</ul></details> 3501cb0ef41Sopenharmony_ci 3511cb0ef41Sopenharmony_ci <div id="apicontent"> 3521cb0ef41Sopenharmony_ci <h2>Modules: <code>node:module</code> API<span><a class="mark" href="#modules-nodemodule-api" id="modules-nodemodule-api">#</a></span><a aria-hidden="true" class="legacy" id="module_modules_node_module_api"></a></h2> 3531cb0ef41Sopenharmony_ci 3541cb0ef41Sopenharmony_ci<div class="api_metadata"> 3551cb0ef41Sopenharmony_ci<span>Added in: v0.3.7</span> 3561cb0ef41Sopenharmony_ci</div> 3571cb0ef41Sopenharmony_ci<section><h3>The <code>Module</code> object<span><a class="mark" href="#the-module-object" id="the-module-object">#</a></span><a aria-hidden="true" class="legacy" id="module_the_module_object"></a></h3> 3581cb0ef41Sopenharmony_ci<ul> 3591cb0ef41Sopenharmony_ci<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a></li> 3601cb0ef41Sopenharmony_ci</ul> 3611cb0ef41Sopenharmony_ci<p>Provides general utility methods when interacting with instances of 3621cb0ef41Sopenharmony_ci<code>Module</code>, the <a href="modules.html#the-module-object"><code>module</code></a> variable often seen in <a href="modules.html">CommonJS</a> modules. Accessed 3631cb0ef41Sopenharmony_civia <code>import 'node:module'</code> or <code>require('node:module')</code>.</p> 3641cb0ef41Sopenharmony_ci<h4><code>module.builtinModules</code><span><a class="mark" href="#modulebuiltinmodules" id="modulebuiltinmodules">#</a></span><a aria-hidden="true" class="legacy" id="module_module_builtinmodules"></a></h4> 3651cb0ef41Sopenharmony_ci<div class="api_metadata"> 3661cb0ef41Sopenharmony_ci<span>Added in: v9.3.0, v8.10.0, v6.13.0</span> 3671cb0ef41Sopenharmony_ci</div> 3681cb0ef41Sopenharmony_ci<ul> 3691cb0ef41Sopenharmony_ci<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string[]></a></li> 3701cb0ef41Sopenharmony_ci</ul> 3711cb0ef41Sopenharmony_ci<p>A list of the names of all modules provided by Node.js. Can be used to verify 3721cb0ef41Sopenharmony_ciif a module is maintained by a third party or not.</p> 3731cb0ef41Sopenharmony_ci<p><code>module</code> in this context isn't the same object that's provided 3741cb0ef41Sopenharmony_ciby the <a href="modules.html#the-module-wrapper">module wrapper</a>. To access it, require the <code>Module</code> module:</p> 3751cb0ef41Sopenharmony_ci 3761cb0ef41Sopenharmony_ci<pre class="with-26-chars"><input class="js-flavor-selector" type="checkbox" checked aria-label="Show modern ES modules syntax"><code class="language-js mjs"><span class="hljs-comment">// module.mjs</span> 3771cb0ef41Sopenharmony_ci<span class="hljs-comment">// In an ECMAScript module</span> 3781cb0ef41Sopenharmony_ci<span class="hljs-keyword">import</span> { builtinModules <span class="hljs-keyword">as</span> builtin } <span class="hljs-keyword">from</span> <span class="hljs-string">'node:module'</span>;</code><code class="language-js cjs"><span class="hljs-comment">// module.cjs</span> 3791cb0ef41Sopenharmony_ci<span class="hljs-comment">// In a CommonJS module</span> 3801cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> builtin = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:module'</span>).<span class="hljs-property">builtinModules</span>;</code><button class="copy-button">copy</button></pre> 3811cb0ef41Sopenharmony_ci<h4><code>module.createRequire(filename)</code><span><a class="mark" href="#modulecreaterequirefilename" id="modulecreaterequirefilename">#</a></span><a aria-hidden="true" class="legacy" id="module_module_createrequire_filename"></a></h4> 3821cb0ef41Sopenharmony_ci<div class="api_metadata"> 3831cb0ef41Sopenharmony_ci<span>Added in: v12.2.0</span> 3841cb0ef41Sopenharmony_ci</div> 3851cb0ef41Sopenharmony_ci<ul> 3861cb0ef41Sopenharmony_ci<li><code>filename</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="url.html#the-whatwg-url-api" class="type"><URL></a> Filename to be used to construct the require 3871cb0ef41Sopenharmony_cifunction. Must be a file URL object, file URL string, or absolute path 3881cb0ef41Sopenharmony_cistring.</li> 3891cb0ef41Sopenharmony_ci<li>Returns: <a href="modules.html#requireid" class="type"><require></a> Require function</li> 3901cb0ef41Sopenharmony_ci</ul> 3911cb0ef41Sopenharmony_ci<pre><code class="language-js mjs"><span class="hljs-keyword">import</span> { createRequire } <span class="hljs-keyword">from</span> <span class="hljs-string">'node:module'</span>; 3921cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> <span class="hljs-built_in">require</span> = <span class="hljs-title function_">createRequire</span>(<span class="hljs-keyword">import</span>.<span class="hljs-property">meta</span>.<span class="hljs-property">url</span>); 3931cb0ef41Sopenharmony_ci 3941cb0ef41Sopenharmony_ci<span class="hljs-comment">// sibling-module.js is a CommonJS module.</span> 3951cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> siblingModule = <span class="hljs-built_in">require</span>(<span class="hljs-string">'./sibling-module'</span>);</code> <button class="copy-button">copy</button></pre> 3961cb0ef41Sopenharmony_ci<h4><code>module.isBuiltin(moduleName)</code><span><a class="mark" href="#moduleisbuiltinmodulename" id="moduleisbuiltinmodulename">#</a></span><a aria-hidden="true" class="legacy" id="module_module_isbuiltin_modulename"></a></h4> 3971cb0ef41Sopenharmony_ci<div class="api_metadata"> 3981cb0ef41Sopenharmony_ci<span>Added in: v18.6.0</span> 3991cb0ef41Sopenharmony_ci</div> 4001cb0ef41Sopenharmony_ci<ul> 4011cb0ef41Sopenharmony_ci<li><code>moduleName</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> name of the module</li> 4021cb0ef41Sopenharmony_ci<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> returns true if the module is builtin else returns false</li> 4031cb0ef41Sopenharmony_ci</ul> 4041cb0ef41Sopenharmony_ci<pre><code class="language-js mjs"><span class="hljs-keyword">import</span> { isBuiltin } <span class="hljs-keyword">from</span> <span class="hljs-string">'node:module'</span>; 4051cb0ef41Sopenharmony_ci<span class="hljs-title function_">isBuiltin</span>(<span class="hljs-string">'node:fs'</span>); <span class="hljs-comment">// true</span> 4061cb0ef41Sopenharmony_ci<span class="hljs-title function_">isBuiltin</span>(<span class="hljs-string">'fs'</span>); <span class="hljs-comment">// true</span> 4071cb0ef41Sopenharmony_ci<span class="hljs-title function_">isBuiltin</span>(<span class="hljs-string">'wss'</span>); <span class="hljs-comment">// false</span></code> <button class="copy-button">copy</button></pre> 4081cb0ef41Sopenharmony_ci<h4><code>module.register(specifier[, parentURL][, options])</code><span><a class="mark" href="#moduleregisterspecifier-parenturl-options" id="moduleregisterspecifier-parenturl-options">#</a></span><a aria-hidden="true" class="legacy" id="module_module_register_specifier_parenturl_options"></a></h4> 4091cb0ef41Sopenharmony_ci<div class="api_metadata"> 4101cb0ef41Sopenharmony_ci<details class="changelog"><summary>History</summary> 4111cb0ef41Sopenharmony_ci<table> 4121cb0ef41Sopenharmony_ci<tbody><tr><th>Version</th><th>Changes</th></tr> 4131cb0ef41Sopenharmony_ci<tr><td>v18.19.0</td> 4141cb0ef41Sopenharmony_ci<td><p>Add support for WHATWG URL instances.</p></td></tr> 4151cb0ef41Sopenharmony_ci<tr><td>v18.19.0</td> 4161cb0ef41Sopenharmony_ci<td><p><span>Added in: v18.19.0</span></p></td></tr> 4171cb0ef41Sopenharmony_ci</tbody></table> 4181cb0ef41Sopenharmony_ci</details> 4191cb0ef41Sopenharmony_ci</div> 4201cb0ef41Sopenharmony_ci<p></p><div class="api_stability api_stability_1"><a href="documentation.html#stability-index">Stability: 1</a>.1 - Active development</div><p></p> 4211cb0ef41Sopenharmony_ci<ul> 4221cb0ef41Sopenharmony_ci<li><code>specifier</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="url.html#the-whatwg-url-api" class="type"><URL></a> Customization hooks to be registered; this should be 4231cb0ef41Sopenharmony_cithe same string that would be passed to <code>import()</code>, except that if it is 4241cb0ef41Sopenharmony_cirelative, it is resolved relative to <code>parentURL</code>.</li> 4251cb0ef41Sopenharmony_ci<li><code>parentURL</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="url.html#the-whatwg-url-api" class="type"><URL></a> If you want to resolve <code>specifier</code> relative to a base 4261cb0ef41Sopenharmony_ciURL, such as <code>import.meta.url</code>, you can pass that URL here. <strong>Default:</strong> 4271cb0ef41Sopenharmony_ci<code>'data:'</code></li> 4281cb0ef41Sopenharmony_ci<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> 4291cb0ef41Sopenharmony_ci<ul> 4301cb0ef41Sopenharmony_ci<li><code>data</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Data_types" class="type"><any></a> Any arbitrary, cloneable JavaScript value to pass into the 4311cb0ef41Sopenharmony_ci<a href="#initialize"><code>initialize</code></a> hook.</li> 4321cb0ef41Sopenharmony_ci<li><code>transferList</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object[]></a> <a href="worker_threads.html#portpostmessagevalue-transferlist">transferrable objects</a> to be passed into the 4331cb0ef41Sopenharmony_ci<code>initialize</code> hook.</li> 4341cb0ef41Sopenharmony_ci</ul> 4351cb0ef41Sopenharmony_ci</li> 4361cb0ef41Sopenharmony_ci</ul> 4371cb0ef41Sopenharmony_ci<p>Register a module that exports <a href="#customization-hooks">hooks</a> that customize Node.js module 4381cb0ef41Sopenharmony_ciresolution and loading behavior. See <a href="#customization-hooks">Customization hooks</a>.</p> 4391cb0ef41Sopenharmony_ci<h4><code>module.syncBuiltinESMExports()</code><span><a class="mark" href="#modulesyncbuiltinesmexports" id="modulesyncbuiltinesmexports">#</a></span><a aria-hidden="true" class="legacy" id="module_module_syncbuiltinesmexports"></a></h4> 4401cb0ef41Sopenharmony_ci<div class="api_metadata"> 4411cb0ef41Sopenharmony_ci<span>Added in: v12.12.0</span> 4421cb0ef41Sopenharmony_ci</div> 4431cb0ef41Sopenharmony_ci<p>The <code>module.syncBuiltinESMExports()</code> method updates all the live bindings for 4441cb0ef41Sopenharmony_cibuiltin <a href="esm.html">ES Modules</a> to match the properties of the <a href="modules.html">CommonJS</a> exports. It 4451cb0ef41Sopenharmony_cidoes not add or remove exported names from the <a href="esm.html">ES Modules</a>.</p> 4461cb0ef41Sopenharmony_ci<pre><code class="language-js"><span class="hljs-keyword">const</span> fs = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:fs'</span>); 4471cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> assert = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:assert'</span>); 4481cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> { syncBuiltinESMExports } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:module'</span>); 4491cb0ef41Sopenharmony_ci 4501cb0ef41Sopenharmony_cifs.<span class="hljs-property">readFile</span> = newAPI; 4511cb0ef41Sopenharmony_ci 4521cb0ef41Sopenharmony_ci<span class="hljs-keyword">delete</span> fs.<span class="hljs-property">readFileSync</span>; 4531cb0ef41Sopenharmony_ci 4541cb0ef41Sopenharmony_ci<span class="hljs-keyword">function</span> <span class="hljs-title function_">newAPI</span>(<span class="hljs-params"></span>) { 4551cb0ef41Sopenharmony_ci <span class="hljs-comment">// ...</span> 4561cb0ef41Sopenharmony_ci} 4571cb0ef41Sopenharmony_ci 4581cb0ef41Sopenharmony_cifs.<span class="hljs-property">newAPI</span> = newAPI; 4591cb0ef41Sopenharmony_ci 4601cb0ef41Sopenharmony_ci<span class="hljs-title function_">syncBuiltinESMExports</span>(); 4611cb0ef41Sopenharmony_ci 4621cb0ef41Sopenharmony_ci<span class="hljs-keyword">import</span>(<span class="hljs-string">'node:fs'</span>).<span class="hljs-title function_">then</span>(<span class="hljs-function">(<span class="hljs-params">esmFS</span>) =></span> { 4631cb0ef41Sopenharmony_ci <span class="hljs-comment">// It syncs the existing readFile property with the new value</span> 4641cb0ef41Sopenharmony_ci assert.<span class="hljs-title function_">strictEqual</span>(esmFS.<span class="hljs-property">readFile</span>, newAPI); 4651cb0ef41Sopenharmony_ci <span class="hljs-comment">// readFileSync has been deleted from the required fs</span> 4661cb0ef41Sopenharmony_ci assert.<span class="hljs-title function_">strictEqual</span>(<span class="hljs-string">'readFileSync'</span> <span class="hljs-keyword">in</span> fs, <span class="hljs-literal">false</span>); 4671cb0ef41Sopenharmony_ci <span class="hljs-comment">// syncBuiltinESMExports() does not remove readFileSync from esmFS</span> 4681cb0ef41Sopenharmony_ci assert.<span class="hljs-title function_">strictEqual</span>(<span class="hljs-string">'readFileSync'</span> <span class="hljs-keyword">in</span> esmFS, <span class="hljs-literal">true</span>); 4691cb0ef41Sopenharmony_ci <span class="hljs-comment">// syncBuiltinESMExports() does not add names</span> 4701cb0ef41Sopenharmony_ci assert.<span class="hljs-title function_">strictEqual</span>(esmFS.<span class="hljs-property">newAPI</span>, <span class="hljs-literal">undefined</span>); 4711cb0ef41Sopenharmony_ci});</code> <button class="copy-button">copy</button></pre> 4721cb0ef41Sopenharmony_ci<p><i id="module_customization_hooks"></i></p> 4731cb0ef41Sopenharmony_ci</section><section><h3>Customization Hooks<span><a class="mark" href="#customization-hooks" id="customization-hooks">#</a></span><a aria-hidden="true" class="legacy" id="module_customization_hooks"></a></h3> 4741cb0ef41Sopenharmony_ci<div class="api_metadata"> 4751cb0ef41Sopenharmony_ci<details class="changelog"><summary>History</summary> 4761cb0ef41Sopenharmony_ci<table> 4771cb0ef41Sopenharmony_ci<tbody><tr><th>Version</th><th>Changes</th></tr> 4781cb0ef41Sopenharmony_ci<tr><td>v18.19.0</td> 4791cb0ef41Sopenharmony_ci<td><p>Added <code>initialize</code> hook to replace <code>globalPreload</code>.</p></td></tr> 4801cb0ef41Sopenharmony_ci<tr><td>v18.6.0, v16.17.0</td> 4811cb0ef41Sopenharmony_ci<td><p>Add support for chaining loaders.</p></td></tr> 4821cb0ef41Sopenharmony_ci<tr><td>v16.12.0</td> 4831cb0ef41Sopenharmony_ci<td><p>Removed <code>getFormat</code>, <code>getSource</code>, <code>transformSource</code>, and <code>globalPreload</code>; added <code>load</code> hook and <code>getGlobalPreload</code> hook.</p></td></tr> 4841cb0ef41Sopenharmony_ci<tr><td>v8.8.0</td> 4851cb0ef41Sopenharmony_ci<td><p><span>Added in: v8.8.0</span></p></td></tr> 4861cb0ef41Sopenharmony_ci</tbody></table> 4871cb0ef41Sopenharmony_ci</details> 4881cb0ef41Sopenharmony_ci</div> 4891cb0ef41Sopenharmony_ci<p></p><div class="api_stability api_stability_1"><a href="documentation.html#stability-index">Stability: 1</a>.1 - Active development</div><p></p> 4901cb0ef41Sopenharmony_ci 4911cb0ef41Sopenharmony_ci<p><i id="enabling_module_customization_hooks"></i></p> 4921cb0ef41Sopenharmony_ci<h4>Enabling<span><a class="mark" href="#enabling" id="enabling">#</a></span><a aria-hidden="true" class="legacy" id="module_enabling"></a></h4> 4931cb0ef41Sopenharmony_ci<p>Module resolution and loading can be customized by registering a file which 4941cb0ef41Sopenharmony_ciexports a set of hooks. This can be done using the <a href="#moduleregisterspecifier-parenturl-options"><code>register</code></a> method 4951cb0ef41Sopenharmony_cifrom <code>node:module</code>, which you can run before your application code by 4961cb0ef41Sopenharmony_ciusing the <code>--import</code> flag:</p> 4971cb0ef41Sopenharmony_ci<pre><code class="language-bash">node --import ./register-hooks.js ./my-app.js</code> <button class="copy-button">copy</button></pre> 4981cb0ef41Sopenharmony_ci 4991cb0ef41Sopenharmony_ci<pre class="with-44-chars"><input class="js-flavor-selector" type="checkbox" checked aria-label="Show modern ES modules syntax"><code class="language-js mjs"><span class="hljs-comment">// register-hooks.js</span> 5001cb0ef41Sopenharmony_ci<span class="hljs-keyword">import</span> { register } <span class="hljs-keyword">from</span> <span class="hljs-string">'node:module'</span>; 5011cb0ef41Sopenharmony_ci 5021cb0ef41Sopenharmony_ci<span class="hljs-title function_">register</span>(<span class="hljs-string">'./hooks.mjs'</span>, <span class="hljs-keyword">import</span>.<span class="hljs-property">meta</span>.<span class="hljs-property">url</span>);</code><code class="language-js cjs"><span class="hljs-comment">// register-hooks.js</span> 5031cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> { register } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:module'</span>); 5041cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> { pathToFileURL } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:url'</span>); 5051cb0ef41Sopenharmony_ci 5061cb0ef41Sopenharmony_ci<span class="hljs-title function_">register</span>(<span class="hljs-string">'./hooks.mjs'</span>, <span class="hljs-title function_">pathToFileURL</span>(__filename));</code><button class="copy-button">copy</button></pre> 5071cb0ef41Sopenharmony_ci<p>The file passed to <code>--import</code> can also be an export from a dependency:</p> 5081cb0ef41Sopenharmony_ci<pre><code class="language-bash">node --import some-package/register ./my-app.js</code> <button class="copy-button">copy</button></pre> 5091cb0ef41Sopenharmony_ci<p>Where <code>some-package</code> has an <a href="packages.html#exports"><code>"exports"</code></a> field defining the <code>/register</code> 5101cb0ef41Sopenharmony_ciexport to map to a file that calls <code>register()</code>, like the following <code>register-hooks.js</code> 5111cb0ef41Sopenharmony_ciexample.</p> 5121cb0ef41Sopenharmony_ci<p>Using <code>--import</code> ensures that the hooks are registered before any application 5131cb0ef41Sopenharmony_cifiles are imported, including the entry point of the application. Alternatively, 5141cb0ef41Sopenharmony_ci<code>register</code> can be called from the entry point, but dynamic <code>import()</code> must be 5151cb0ef41Sopenharmony_ciused for any code that should be run after the hooks are registered:</p> 5161cb0ef41Sopenharmony_ci 5171cb0ef41Sopenharmony_ci<pre class="with-46-chars"><input class="js-flavor-selector" type="checkbox" checked aria-label="Show modern ES modules syntax"><code class="language-js mjs"><span class="hljs-keyword">import</span> { register } <span class="hljs-keyword">from</span> <span class="hljs-string">'node:module'</span>; 5181cb0ef41Sopenharmony_ci 5191cb0ef41Sopenharmony_ci<span class="hljs-title function_">register</span>(<span class="hljs-string">'http-to-https'</span>, <span class="hljs-keyword">import</span>.<span class="hljs-property">meta</span>.<span class="hljs-property">url</span>); 5201cb0ef41Sopenharmony_ci 5211cb0ef41Sopenharmony_ci<span class="hljs-comment">// Because this is a dynamic `import()`, the `http-to-https` hooks will run</span> 5221cb0ef41Sopenharmony_ci<span class="hljs-comment">// to handle `./my-app.js` and any other files it imports or requires.</span> 5231cb0ef41Sopenharmony_ci<span class="hljs-keyword">await</span> <span class="hljs-keyword">import</span>(<span class="hljs-string">'./my-app.js'</span>);</code><code class="language-js cjs"><span class="hljs-keyword">const</span> { register } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:module'</span>); 5241cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> { pathToFileURL } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:url'</span>); 5251cb0ef41Sopenharmony_ci 5261cb0ef41Sopenharmony_ci<span class="hljs-title function_">register</span>(<span class="hljs-string">'http-to-https'</span>, <span class="hljs-title function_">pathToFileURL</span>(__filename)); 5271cb0ef41Sopenharmony_ci 5281cb0ef41Sopenharmony_ci<span class="hljs-comment">// Because this is a dynamic `import()`, the `http-to-https` hooks will run</span> 5291cb0ef41Sopenharmony_ci<span class="hljs-comment">// to handle `./my-app.js` and any other files it imports or requires.</span> 5301cb0ef41Sopenharmony_ci<span class="hljs-keyword">import</span>(<span class="hljs-string">'./my-app.js'</span>);</code><button class="copy-button">copy</button></pre> 5311cb0ef41Sopenharmony_ci<p>In this example, we are registering the <code>http-to-https</code> hooks, but they will 5321cb0ef41Sopenharmony_cionly be available for subsequently imported modules—in this case, <code>my-app.js</code> 5331cb0ef41Sopenharmony_ciand anything it references via <code>import</code> (and optionally <code>require</code>). If the 5341cb0ef41Sopenharmony_ci<code>import('./my-app.js')</code> had instead been a static <code>import './my-app.js'</code>, the 5351cb0ef41Sopenharmony_ciapp would have <em>already</em> been loaded <strong>before</strong> the <code>http-to-https</code> hooks were 5361cb0ef41Sopenharmony_ciregistered. This due to the ES modules specification, where static imports are 5371cb0ef41Sopenharmony_cievaluated from the leaves of the tree first, then back to the trunk. There can 5381cb0ef41Sopenharmony_cibe static imports <em>within</em> <code>my-app.js</code>, which will not be evaluated until 5391cb0ef41Sopenharmony_ci<code>my-app.js</code> is dynamically imported.</p> 5401cb0ef41Sopenharmony_ci<p><code>my-app.js</code> can also be CommonJS. Customization hooks will run for any 5411cb0ef41Sopenharmony_cimodules that it references via <code>import</code> (and optionally <code>require</code>).</p> 5421cb0ef41Sopenharmony_ci<p>Finally, if all you want to do is register hooks before your app runs and you 5431cb0ef41Sopenharmony_cidon't want to create a separate file for that purpose, you can pass a <code>data:</code> 5441cb0ef41Sopenharmony_ciURL to <code>--import</code>:</p> 5451cb0ef41Sopenharmony_ci<pre><code class="language-bash">node --import <span class="hljs-string">'data:text/javascript,import { register } from "node:module"; import { pathToFileURL } from "node:url"; register("http-to-https", pathToFileURL("./"));'</span> ./my-app.js</code> <button class="copy-button">copy</button></pre> 5461cb0ef41Sopenharmony_ci<h4>Chaining<span><a class="mark" href="#chaining" id="chaining">#</a></span><a aria-hidden="true" class="legacy" id="module_chaining"></a></h4> 5471cb0ef41Sopenharmony_ci<p>It's possible to call <code>register</code> more than once:</p> 5481cb0ef41Sopenharmony_ci 5491cb0ef41Sopenharmony_ci<pre class="with-44-chars"><input class="js-flavor-selector" type="checkbox" checked aria-label="Show modern ES modules syntax"><code class="language-js mjs"><span class="hljs-comment">// entrypoint.mjs</span> 5501cb0ef41Sopenharmony_ci<span class="hljs-keyword">import</span> { register } <span class="hljs-keyword">from</span> <span class="hljs-string">'node:module'</span>; 5511cb0ef41Sopenharmony_ci 5521cb0ef41Sopenharmony_ci<span class="hljs-title function_">register</span>(<span class="hljs-string">'./first.mjs'</span>, <span class="hljs-keyword">import</span>.<span class="hljs-property">meta</span>.<span class="hljs-property">url</span>); 5531cb0ef41Sopenharmony_ci<span class="hljs-title function_">register</span>(<span class="hljs-string">'./second.mjs'</span>, <span class="hljs-keyword">import</span>.<span class="hljs-property">meta</span>.<span class="hljs-property">url</span>); 5541cb0ef41Sopenharmony_ci<span class="hljs-keyword">await</span> <span class="hljs-keyword">import</span>(<span class="hljs-string">'./my-app.mjs'</span>);</code><code class="language-js cjs"><span class="hljs-comment">// entrypoint.cjs</span> 5551cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> { register } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:module'</span>); 5561cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> { pathToFileURL } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:url'</span>); 5571cb0ef41Sopenharmony_ci 5581cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> parentURL = <span class="hljs-title function_">pathToFileURL</span>(__filename); 5591cb0ef41Sopenharmony_ci<span class="hljs-title function_">register</span>(<span class="hljs-string">'./first.mjs'</span>, parentURL); 5601cb0ef41Sopenharmony_ci<span class="hljs-title function_">register</span>(<span class="hljs-string">'./second.mjs'</span>, parentURL); 5611cb0ef41Sopenharmony_ci<span class="hljs-keyword">import</span>(<span class="hljs-string">'./my-app.mjs'</span>);</code><button class="copy-button">copy</button></pre> 5621cb0ef41Sopenharmony_ci<p>In this example, the registered hooks will form chains. If both <code>first.mjs</code> and 5631cb0ef41Sopenharmony_ci<code>second.mjs</code> define a <code>resolve</code> hook, both will be called, in the order they 5641cb0ef41Sopenharmony_ciwere registered. The same applies to all the other hooks.</p> 5651cb0ef41Sopenharmony_ci<p>The registered hooks also affect <code>register</code> itself. In this example, 5661cb0ef41Sopenharmony_ci<code>second.mjs</code> will be resolved and loaded per the hooks registered by 5671cb0ef41Sopenharmony_ci<code>first.mjs</code>. This allows for things like writing hooks in non-JavaScript 5681cb0ef41Sopenharmony_cilanguages, so long as an earlier registered loader is one that transpiles into 5691cb0ef41Sopenharmony_ciJavaScript.</p> 5701cb0ef41Sopenharmony_ci<p>The <code>register</code> method cannot be called from within the module that defines the 5711cb0ef41Sopenharmony_cihooks.</p> 5721cb0ef41Sopenharmony_ci<h4>Communication with module customization hooks<span><a class="mark" href="#communication-with-module-customization-hooks" id="communication-with-module-customization-hooks">#</a></span><a aria-hidden="true" class="legacy" id="module_communication_with_module_customization_hooks"></a></h4> 5731cb0ef41Sopenharmony_ci<p>Module customization hooks run on a dedicated thread, separate from the main 5741cb0ef41Sopenharmony_cithread that runs application code. This means mutating global variables won't 5751cb0ef41Sopenharmony_ciaffect the other thread(s), and message channels must be used to communicate 5761cb0ef41Sopenharmony_cibetween the threads.</p> 5771cb0ef41Sopenharmony_ci<p>The <code>register</code> method can be used to pass data to an <a href="#initialize"><code>initialize</code></a> hook. The 5781cb0ef41Sopenharmony_cidata passed to the hook may include transferrable objects like ports.</p> 5791cb0ef41Sopenharmony_ci 5801cb0ef41Sopenharmony_ci<pre class="with-53-chars"><input class="js-flavor-selector" type="checkbox" checked aria-label="Show modern ES modules syntax"><code class="language-js mjs"><span class="hljs-keyword">import</span> { register } <span class="hljs-keyword">from</span> <span class="hljs-string">'node:module'</span>; 5811cb0ef41Sopenharmony_ci<span class="hljs-keyword">import</span> { <span class="hljs-title class_">MessageChannel</span> } <span class="hljs-keyword">from</span> <span class="hljs-string">'node:worker_threads'</span>; 5821cb0ef41Sopenharmony_ci 5831cb0ef41Sopenharmony_ci<span class="hljs-comment">// This example demonstrates how a message channel can be used to</span> 5841cb0ef41Sopenharmony_ci<span class="hljs-comment">// communicate with the hooks, by sending `port2` to the hooks.</span> 5851cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> { port1, port2 } = <span class="hljs-keyword">new</span> <span class="hljs-title class_">MessageChannel</span>(); 5861cb0ef41Sopenharmony_ci 5871cb0ef41Sopenharmony_ciport1.<span class="hljs-title function_">on</span>(<span class="hljs-string">'message'</span>, <span class="hljs-function">(<span class="hljs-params">msg</span>) =></span> { 5881cb0ef41Sopenharmony_ci <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(msg); 5891cb0ef41Sopenharmony_ci}); 5901cb0ef41Sopenharmony_ci 5911cb0ef41Sopenharmony_ci<span class="hljs-title function_">register</span>(<span class="hljs-string">'./my-hooks.mjs'</span>, { 5921cb0ef41Sopenharmony_ci <span class="hljs-attr">parentURL</span>: <span class="hljs-keyword">import</span>.<span class="hljs-property">meta</span>.<span class="hljs-property">url</span>, 5931cb0ef41Sopenharmony_ci <span class="hljs-attr">data</span>: { <span class="hljs-attr">number</span>: <span class="hljs-number">1</span>, <span class="hljs-attr">port</span>: port2 }, 5941cb0ef41Sopenharmony_ci <span class="hljs-attr">transferList</span>: [port2], 5951cb0ef41Sopenharmony_ci});</code><code class="language-js cjs"><span class="hljs-keyword">const</span> { register } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:module'</span>); 5961cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> { pathToFileURL } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:url'</span>); 5971cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> { <span class="hljs-title class_">MessageChannel</span> } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:worker_threads'</span>); 5981cb0ef41Sopenharmony_ci 5991cb0ef41Sopenharmony_ci<span class="hljs-comment">// This example showcases how a message channel can be used to</span> 6001cb0ef41Sopenharmony_ci<span class="hljs-comment">// communicate with the hooks, by sending `port2` to the hooks.</span> 6011cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> { port1, port2 } = <span class="hljs-keyword">new</span> <span class="hljs-title class_">MessageChannel</span>(); 6021cb0ef41Sopenharmony_ci 6031cb0ef41Sopenharmony_ciport1.<span class="hljs-title function_">on</span>(<span class="hljs-string">'message'</span>, <span class="hljs-function">(<span class="hljs-params">msg</span>) =></span> { 6041cb0ef41Sopenharmony_ci <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(msg); 6051cb0ef41Sopenharmony_ci}); 6061cb0ef41Sopenharmony_ci 6071cb0ef41Sopenharmony_ci<span class="hljs-title function_">register</span>(<span class="hljs-string">'./my-hooks.mjs'</span>, { 6081cb0ef41Sopenharmony_ci <span class="hljs-attr">parentURL</span>: <span class="hljs-title function_">pathToFileURL</span>(__filename), 6091cb0ef41Sopenharmony_ci <span class="hljs-attr">data</span>: { <span class="hljs-attr">number</span>: <span class="hljs-number">1</span>, <span class="hljs-attr">port</span>: port2 }, 6101cb0ef41Sopenharmony_ci <span class="hljs-attr">transferList</span>: [port2], 6111cb0ef41Sopenharmony_ci});</code><button class="copy-button">copy</button></pre> 6121cb0ef41Sopenharmony_ci<h4>Hooks<span><a class="mark" href="#hooks" id="hooks">#</a></span><a aria-hidden="true" class="legacy" id="module_hooks"></a></h4> 6131cb0ef41Sopenharmony_ci<p>The <a href="#moduleregisterspecifier-parenturl-options"><code>register</code></a> method can be used to register a module that exports a set of 6141cb0ef41Sopenharmony_cihooks. The hooks are functions that are called by Node.js to customize the 6151cb0ef41Sopenharmony_cimodule resolution and loading process. The exported functions must have specific 6161cb0ef41Sopenharmony_cinames and signatures, and they must be exported as named exports.</p> 6171cb0ef41Sopenharmony_ci<pre><code class="language-js mjs"><span class="hljs-keyword">export</span> <span class="hljs-keyword">async</span> <span class="hljs-keyword">function</span> <span class="hljs-title function_">initialize</span>(<span class="hljs-params">{ number, port }</span>) { 6181cb0ef41Sopenharmony_ci <span class="hljs-comment">// Receives data from `register`.</span> 6191cb0ef41Sopenharmony_ci} 6201cb0ef41Sopenharmony_ci 6211cb0ef41Sopenharmony_ci<span class="hljs-keyword">export</span> <span class="hljs-keyword">async</span> <span class="hljs-keyword">function</span> <span class="hljs-title function_">resolve</span>(<span class="hljs-params">specifier, context, nextResolve</span>) { 6221cb0ef41Sopenharmony_ci <span class="hljs-comment">// Take an `import` or `require` specifier and resolve it to a URL.</span> 6231cb0ef41Sopenharmony_ci} 6241cb0ef41Sopenharmony_ci 6251cb0ef41Sopenharmony_ci<span class="hljs-keyword">export</span> <span class="hljs-keyword">async</span> <span class="hljs-keyword">function</span> <span class="hljs-title function_">load</span>(<span class="hljs-params">url, context, nextLoad</span>) { 6261cb0ef41Sopenharmony_ci <span class="hljs-comment">// Take a resolved URL and return the source code to be evaluated.</span> 6271cb0ef41Sopenharmony_ci}</code> <button class="copy-button">copy</button></pre> 6281cb0ef41Sopenharmony_ci<p>Hooks are part of a chain, even if that chain consists of only one custom 6291cb0ef41Sopenharmony_ci(user-provided) hook and the default hook, which is always present. Hook 6301cb0ef41Sopenharmony_cifunctions nest: each one must always return a plain object, and chaining happens 6311cb0ef41Sopenharmony_cias a result of each function calling <code>next<hookName>()</code>, which is a reference to 6321cb0ef41Sopenharmony_cithe subsequent loader's hook.</p> 6331cb0ef41Sopenharmony_ci<p>A hook that returns a value lacking a required property triggers an exception. A 6341cb0ef41Sopenharmony_cihook that returns without calling <code>next<hookName>()</code> <em>and</em> without returning 6351cb0ef41Sopenharmony_ci<code>shortCircuit: true</code> also triggers an exception. These errors are to help 6361cb0ef41Sopenharmony_ciprevent unintentional breaks in the chain. Return <code>shortCircuit: true</code> from a 6371cb0ef41Sopenharmony_cihook to signal that the chain is intentionally ending at your hook.</p> 6381cb0ef41Sopenharmony_ci<p>Hooks are run in a separate thread, isolated from the main thread where 6391cb0ef41Sopenharmony_ciapplication code runs. That means it is a different <a href="https://tc39.es/ecma262/#realm">realm</a>. The hooks thread 6401cb0ef41Sopenharmony_cimay be terminated by the main thread at any time, so do not depend on 6411cb0ef41Sopenharmony_ciasynchronous operations (like <code>console.log</code>) to complete.</p> 6421cb0ef41Sopenharmony_ci<h5><code>initialize()</code><span><a class="mark" href="#initialize" id="initialize">#</a></span><a aria-hidden="true" class="legacy" id="module_initialize"></a></h5> 6431cb0ef41Sopenharmony_ci<div class="api_metadata"> 6441cb0ef41Sopenharmony_ci<span>Added in: v18.19.0</span> 6451cb0ef41Sopenharmony_ci</div> 6461cb0ef41Sopenharmony_ci<p></p><div class="api_stability api_stability_1"><a href="documentation.html#stability-index">Stability: 1</a>.1 - Active development</div><p></p> 6471cb0ef41Sopenharmony_ci<ul> 6481cb0ef41Sopenharmony_ci<li><code>data</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Data_types" class="type"><any></a> The data from <code>register(loader, import.meta.url, { data })</code>.</li> 6491cb0ef41Sopenharmony_ci</ul> 6501cb0ef41Sopenharmony_ci<p>The <code>initialize</code> hook provides a way to define a custom function that runs in 6511cb0ef41Sopenharmony_cithe hooks thread when the hooks module is initialized. Initialization happens 6521cb0ef41Sopenharmony_ciwhen the hooks module is registered via <a href="#moduleregisterspecifier-parenturl-options"><code>register</code></a>.</p> 6531cb0ef41Sopenharmony_ci<p>This hook can receive data from a <a href="#moduleregisterspecifier-parenturl-options"><code>register</code></a> invocation, including 6541cb0ef41Sopenharmony_ciports and other transferrable objects. The return value of <code>initialize</code> can be a 6551cb0ef41Sopenharmony_ci<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a>, in which case it will be awaited before the main application thread 6561cb0ef41Sopenharmony_ciexecution resumes.</p> 6571cb0ef41Sopenharmony_ci<p>Module customization code:</p> 6581cb0ef41Sopenharmony_ci<pre><code class="language-js mjs"><span class="hljs-comment">// path-to-my-hooks.js</span> 6591cb0ef41Sopenharmony_ci 6601cb0ef41Sopenharmony_ci<span class="hljs-keyword">export</span> <span class="hljs-keyword">async</span> <span class="hljs-keyword">function</span> <span class="hljs-title function_">initialize</span>(<span class="hljs-params">{ number, port }</span>) { 6611cb0ef41Sopenharmony_ci port.<span class="hljs-title function_">postMessage</span>(<span class="hljs-string">`increment: <span class="hljs-subst">${number + <span class="hljs-number">1</span>}</span>`</span>); 6621cb0ef41Sopenharmony_ci}</code> <button class="copy-button">copy</button></pre> 6631cb0ef41Sopenharmony_ci<p>Caller code:</p> 6641cb0ef41Sopenharmony_ci 6651cb0ef41Sopenharmony_ci<pre class="with-44-chars"><input class="js-flavor-selector" type="checkbox" checked aria-label="Show modern ES modules syntax"><code class="language-js mjs"><span class="hljs-keyword">import</span> assert <span class="hljs-keyword">from</span> <span class="hljs-string">'node:assert'</span>; 6661cb0ef41Sopenharmony_ci<span class="hljs-keyword">import</span> { register } <span class="hljs-keyword">from</span> <span class="hljs-string">'node:module'</span>; 6671cb0ef41Sopenharmony_ci<span class="hljs-keyword">import</span> { <span class="hljs-title class_">MessageChannel</span> } <span class="hljs-keyword">from</span> <span class="hljs-string">'node:worker_threads'</span>; 6681cb0ef41Sopenharmony_ci 6691cb0ef41Sopenharmony_ci<span class="hljs-comment">// This example showcases how a message channel can be used to communicate</span> 6701cb0ef41Sopenharmony_ci<span class="hljs-comment">// between the main (application) thread and the hooks running on the hooks</span> 6711cb0ef41Sopenharmony_ci<span class="hljs-comment">// thread, by sending `port2` to the `initialize` hook.</span> 6721cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> { port1, port2 } = <span class="hljs-keyword">new</span> <span class="hljs-title class_">MessageChannel</span>(); 6731cb0ef41Sopenharmony_ci 6741cb0ef41Sopenharmony_ciport1.<span class="hljs-title function_">on</span>(<span class="hljs-string">'message'</span>, <span class="hljs-function">(<span class="hljs-params">msg</span>) =></span> { 6751cb0ef41Sopenharmony_ci assert.<span class="hljs-title function_">strictEqual</span>(msg, <span class="hljs-string">'increment: 2'</span>); 6761cb0ef41Sopenharmony_ci}); 6771cb0ef41Sopenharmony_ci 6781cb0ef41Sopenharmony_ci<span class="hljs-title function_">register</span>(<span class="hljs-string">'./path-to-my-hooks.js'</span>, { 6791cb0ef41Sopenharmony_ci <span class="hljs-attr">parentURL</span>: <span class="hljs-keyword">import</span>.<span class="hljs-property">meta</span>.<span class="hljs-property">url</span>, 6801cb0ef41Sopenharmony_ci <span class="hljs-attr">data</span>: { <span class="hljs-attr">number</span>: <span class="hljs-number">1</span>, <span class="hljs-attr">port</span>: port2 }, 6811cb0ef41Sopenharmony_ci <span class="hljs-attr">transferList</span>: [port2], 6821cb0ef41Sopenharmony_ci});</code><code class="language-js cjs"><span class="hljs-keyword">const</span> assert = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:assert'</span>); 6831cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> { register } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:module'</span>); 6841cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> { pathToFileURL } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:url'</span>); 6851cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> { <span class="hljs-title class_">MessageChannel</span> } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:worker_threads'</span>); 6861cb0ef41Sopenharmony_ci 6871cb0ef41Sopenharmony_ci<span class="hljs-comment">// This example showcases how a message channel can be used to communicate</span> 6881cb0ef41Sopenharmony_ci<span class="hljs-comment">// between the main (application) thread and the hooks running on the hooks</span> 6891cb0ef41Sopenharmony_ci<span class="hljs-comment">// thread, by sending `port2` to the `initialize` hook.</span> 6901cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> { port1, port2 } = <span class="hljs-keyword">new</span> <span class="hljs-title class_">MessageChannel</span>(); 6911cb0ef41Sopenharmony_ci 6921cb0ef41Sopenharmony_ciport1.<span class="hljs-title function_">on</span>(<span class="hljs-string">'message'</span>, <span class="hljs-function">(<span class="hljs-params">msg</span>) =></span> { 6931cb0ef41Sopenharmony_ci assert.<span class="hljs-title function_">strictEqual</span>(msg, <span class="hljs-string">'increment: 2'</span>); 6941cb0ef41Sopenharmony_ci}); 6951cb0ef41Sopenharmony_ci 6961cb0ef41Sopenharmony_ci<span class="hljs-title function_">register</span>(<span class="hljs-string">'./path-to-my-hooks.js'</span>, { 6971cb0ef41Sopenharmony_ci <span class="hljs-attr">parentURL</span>: <span class="hljs-title function_">pathToFileURL</span>(__filename), 6981cb0ef41Sopenharmony_ci <span class="hljs-attr">data</span>: { <span class="hljs-attr">number</span>: <span class="hljs-number">1</span>, <span class="hljs-attr">port</span>: port2 }, 6991cb0ef41Sopenharmony_ci <span class="hljs-attr">transferList</span>: [port2], 7001cb0ef41Sopenharmony_ci});</code><button class="copy-button">copy</button></pre> 7011cb0ef41Sopenharmony_ci<h5><code>resolve(specifier, context, nextResolve)</code><span><a class="mark" href="#resolvespecifier-context-nextresolve" id="resolvespecifier-context-nextresolve">#</a></span><a aria-hidden="true" class="legacy" id="module_resolve_specifier_context_nextresolve"></a></h5> 7021cb0ef41Sopenharmony_ci<div class="api_metadata"> 7031cb0ef41Sopenharmony_ci<details class="changelog"><summary>History</summary> 7041cb0ef41Sopenharmony_ci<table> 7051cb0ef41Sopenharmony_ci<tbody><tr><th>Version</th><th>Changes</th></tr> 7061cb0ef41Sopenharmony_ci<tr><td>v18.19.0</td> 7071cb0ef41Sopenharmony_ci<td><p>The property <code>context.importAssertions</code> is replaced with <code>context.importAttributes</code>. Using the old name is still supported and will emit an experimental warning.</p></td></tr> 7081cb0ef41Sopenharmony_ci<tr><td>v18.6.0, v16.17.0</td> 7091cb0ef41Sopenharmony_ci<td><p>Add support for chaining resolve hooks. Each hook must either call <code>nextResolve()</code> or include a <code>shortCircuit</code> property set to <code>true</code> in its return.</p></td></tr> 7101cb0ef41Sopenharmony_ci<tr><td>v17.1.0, v16.14.0</td> 7111cb0ef41Sopenharmony_ci<td><p>Add support for import assertions.</p></td></tr> 7121cb0ef41Sopenharmony_ci</tbody></table> 7131cb0ef41Sopenharmony_ci</details> 7141cb0ef41Sopenharmony_ci</div> 7151cb0ef41Sopenharmony_ci<p></p><div class="api_stability api_stability_1"><a href="documentation.html#stability-index">Stability: 1</a>.2 - Release candidate</div><p></p> 7161cb0ef41Sopenharmony_ci<ul> 7171cb0ef41Sopenharmony_ci<li><code>specifier</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li> 7181cb0ef41Sopenharmony_ci<li><code>context</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> 7191cb0ef41Sopenharmony_ci<ul> 7201cb0ef41Sopenharmony_ci<li><code>conditions</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string[]></a> Export conditions of the relevant <code>package.json</code></li> 7211cb0ef41Sopenharmony_ci<li><code>importAttributes</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> An object whose key-value pairs represent the 7221cb0ef41Sopenharmony_ciattributes for the module to import</li> 7231cb0ef41Sopenharmony_ci<li><code>parentURL</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Undefined_type" class="type"><undefined></a> The module importing this one, or undefined 7241cb0ef41Sopenharmony_ciif this is the Node.js entry point</li> 7251cb0ef41Sopenharmony_ci</ul> 7261cb0ef41Sopenharmony_ci</li> 7271cb0ef41Sopenharmony_ci<li><code>nextResolve</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> The subsequent <code>resolve</code> hook in the chain, or the 7281cb0ef41Sopenharmony_ciNode.js default <code>resolve</code> hook after the last user-supplied <code>resolve</code> hook 7291cb0ef41Sopenharmony_ci<ul> 7301cb0ef41Sopenharmony_ci<li><code>specifier</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li> 7311cb0ef41Sopenharmony_ci<li><code>context</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a></li> 7321cb0ef41Sopenharmony_ci</ul> 7331cb0ef41Sopenharmony_ci</li> 7341cb0ef41Sopenharmony_ci<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a> 7351cb0ef41Sopenharmony_ci<ul> 7361cb0ef41Sopenharmony_ci<li><code>format</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Null_type" class="type"><null></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Undefined_type" class="type"><undefined></a> A hint to the load hook (it might be 7371cb0ef41Sopenharmony_ciignored) 7381cb0ef41Sopenharmony_ci<code>'builtin' | 'commonjs' | 'json' | 'module' | 'wasm'</code></li> 7391cb0ef41Sopenharmony_ci<li><code>importAttributes</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Undefined_type" class="type"><undefined></a> The import attributes to use when 7401cb0ef41Sopenharmony_cicaching the module (optional; if excluded the input will be used)</li> 7411cb0ef41Sopenharmony_ci<li><code>shortCircuit</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Undefined_type" class="type"><undefined></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> A signal that this hook intends to 7421cb0ef41Sopenharmony_citerminate the chain of <code>resolve</code> hooks. <strong>Default:</strong> <code>false</code></li> 7431cb0ef41Sopenharmony_ci<li><code>url</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> The absolute URL to which this input resolves</li> 7441cb0ef41Sopenharmony_ci</ul> 7451cb0ef41Sopenharmony_ci</li> 7461cb0ef41Sopenharmony_ci</ul> 7471cb0ef41Sopenharmony_ci<blockquote> 7481cb0ef41Sopenharmony_ci<p><strong>Warning</strong> Despite support for returning promises and async functions, calls 7491cb0ef41Sopenharmony_cito <code>resolve</code> may block the main thread which can impact performance.</p> 7501cb0ef41Sopenharmony_ci</blockquote> 7511cb0ef41Sopenharmony_ci<p>The <code>resolve</code> hook chain is responsible for telling Node.js where to find and 7521cb0ef41Sopenharmony_cihow to cache a given <code>import</code> statement or expression, or <code>require</code> call. It can 7531cb0ef41Sopenharmony_cioptionally return a format (such as <code>'module'</code>) as a hint to the <code>load</code> hook. If 7541cb0ef41Sopenharmony_cia format is specified, the <code>load</code> hook is ultimately responsible for providing 7551cb0ef41Sopenharmony_cithe final <code>format</code> value (and it is free to ignore the hint provided by 7561cb0ef41Sopenharmony_ci<code>resolve</code>); if <code>resolve</code> provides a <code>format</code>, a custom <code>load</code> hook is required 7571cb0ef41Sopenharmony_cieven if only to pass the value to the Node.js default <code>load</code> hook.</p> 7581cb0ef41Sopenharmony_ci<p>Import type attributes are part of the cache key for saving loaded modules into 7591cb0ef41Sopenharmony_cithe internal module cache. The <code>resolve</code> hook is responsible for returning an 7601cb0ef41Sopenharmony_ci<code>importAttributes</code> object if the module should be cached with different 7611cb0ef41Sopenharmony_ciattributes than were present in the source code.</p> 7621cb0ef41Sopenharmony_ci<p>The <code>conditions</code> property in <code>context</code> is an array of conditions for 7631cb0ef41Sopenharmony_ci<a href="packages.html#conditional-exports">package exports conditions</a> that apply to this resolution 7641cb0ef41Sopenharmony_cirequest. They can be used for looking up conditional mappings elsewhere or to 7651cb0ef41Sopenharmony_cimodify the list when calling the default resolution logic.</p> 7661cb0ef41Sopenharmony_ci<p>The current <a href="packages.html#conditional-exports">package exports conditions</a> are always in 7671cb0ef41Sopenharmony_cithe <code>context.conditions</code> array passed into the hook. To guarantee <em>default 7681cb0ef41Sopenharmony_ciNode.js module specifier resolution behavior</em> when calling <code>defaultResolve</code>, the 7691cb0ef41Sopenharmony_ci<code>context.conditions</code> array passed to it <em>must</em> include <em>all</em> elements of the 7701cb0ef41Sopenharmony_ci<code>context.conditions</code> array originally passed into the <code>resolve</code> hook.</p> 7711cb0ef41Sopenharmony_ci<pre><code class="language-js mjs"><span class="hljs-keyword">export</span> <span class="hljs-keyword">async</span> <span class="hljs-keyword">function</span> <span class="hljs-title function_">resolve</span>(<span class="hljs-params">specifier, context, nextResolve</span>) { 7721cb0ef41Sopenharmony_ci <span class="hljs-keyword">const</span> { parentURL = <span class="hljs-literal">null</span> } = context; 7731cb0ef41Sopenharmony_ci 7741cb0ef41Sopenharmony_ci <span class="hljs-keyword">if</span> (<span class="hljs-title class_">Math</span>.<span class="hljs-title function_">random</span>() > <span class="hljs-number">0.5</span>) { <span class="hljs-comment">// Some condition.</span> 7751cb0ef41Sopenharmony_ci <span class="hljs-comment">// For some or all specifiers, do some custom logic for resolving.</span> 7761cb0ef41Sopenharmony_ci <span class="hljs-comment">// Always return an object of the form {url: <string>}.</span> 7771cb0ef41Sopenharmony_ci <span class="hljs-keyword">return</span> { 7781cb0ef41Sopenharmony_ci <span class="hljs-attr">shortCircuit</span>: <span class="hljs-literal">true</span>, 7791cb0ef41Sopenharmony_ci <span class="hljs-attr">url</span>: parentURL ? 7801cb0ef41Sopenharmony_ci <span class="hljs-keyword">new</span> <span class="hljs-title function_">URL</span>(specifier, parentURL).<span class="hljs-property">href</span> : 7811cb0ef41Sopenharmony_ci <span class="hljs-keyword">new</span> <span class="hljs-title function_">URL</span>(specifier).<span class="hljs-property">href</span>, 7821cb0ef41Sopenharmony_ci }; 7831cb0ef41Sopenharmony_ci } 7841cb0ef41Sopenharmony_ci 7851cb0ef41Sopenharmony_ci <span class="hljs-keyword">if</span> (<span class="hljs-title class_">Math</span>.<span class="hljs-title function_">random</span>() < <span class="hljs-number">0.5</span>) { <span class="hljs-comment">// Another condition.</span> 7861cb0ef41Sopenharmony_ci <span class="hljs-comment">// When calling `defaultResolve`, the arguments can be modified. In this</span> 7871cb0ef41Sopenharmony_ci <span class="hljs-comment">// case it's adding another value for matching conditional exports.</span> 7881cb0ef41Sopenharmony_ci <span class="hljs-keyword">return</span> <span class="hljs-title function_">nextResolve</span>(specifier, { 7891cb0ef41Sopenharmony_ci ...context, 7901cb0ef41Sopenharmony_ci <span class="hljs-attr">conditions</span>: [...context.<span class="hljs-property">conditions</span>, <span class="hljs-string">'another-condition'</span>], 7911cb0ef41Sopenharmony_ci }); 7921cb0ef41Sopenharmony_ci } 7931cb0ef41Sopenharmony_ci 7941cb0ef41Sopenharmony_ci <span class="hljs-comment">// Defer to the next hook in the chain, which would be the</span> 7951cb0ef41Sopenharmony_ci <span class="hljs-comment">// Node.js default resolve if this is the last user-specified loader.</span> 7961cb0ef41Sopenharmony_ci <span class="hljs-keyword">return</span> <span class="hljs-title function_">nextResolve</span>(specifier); 7971cb0ef41Sopenharmony_ci}</code> <button class="copy-button">copy</button></pre> 7981cb0ef41Sopenharmony_ci<h5><code>load(url, context, nextLoad)</code><span><a class="mark" href="#loadurl-context-nextload" id="loadurl-context-nextload">#</a></span><a aria-hidden="true" class="legacy" id="module_load_url_context_nextload"></a></h5> 7991cb0ef41Sopenharmony_ci<div class="api_metadata"> 8001cb0ef41Sopenharmony_ci<details class="changelog"><summary>History</summary> 8011cb0ef41Sopenharmony_ci<table> 8021cb0ef41Sopenharmony_ci<tbody><tr><th>Version</th><th>Changes</th></tr> 8031cb0ef41Sopenharmony_ci<tr><td>v18.6.0, v16.17.0</td> 8041cb0ef41Sopenharmony_ci<td><p>Add support for chaining load hooks. Each hook must either call <code>nextLoad()</code> or include a <code>shortCircuit</code> property set to <code>true</code> in its return.</p></td></tr> 8051cb0ef41Sopenharmony_ci</tbody></table> 8061cb0ef41Sopenharmony_ci</details> 8071cb0ef41Sopenharmony_ci</div> 8081cb0ef41Sopenharmony_ci<p></p><div class="api_stability api_stability_1"><a href="documentation.html#stability-index">Stability: 1</a>.2 - Release candidate</div><p></p> 8091cb0ef41Sopenharmony_ci<ul> 8101cb0ef41Sopenharmony_ci<li><code>url</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> The URL returned by the <code>resolve</code> chain</li> 8111cb0ef41Sopenharmony_ci<li><code>context</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> 8121cb0ef41Sopenharmony_ci<ul> 8131cb0ef41Sopenharmony_ci<li><code>conditions</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string[]></a> Export conditions of the relevant <code>package.json</code></li> 8141cb0ef41Sopenharmony_ci<li><code>format</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Null_type" class="type"><null></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Undefined_type" class="type"><undefined></a> The format optionally supplied by the 8151cb0ef41Sopenharmony_ci<code>resolve</code> hook chain</li> 8161cb0ef41Sopenharmony_ci<li><code>importAttributes</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a></li> 8171cb0ef41Sopenharmony_ci</ul> 8181cb0ef41Sopenharmony_ci</li> 8191cb0ef41Sopenharmony_ci<li><code>nextLoad</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> The subsequent <code>load</code> hook in the chain, or the 8201cb0ef41Sopenharmony_ciNode.js default <code>load</code> hook after the last user-supplied <code>load</code> hook 8211cb0ef41Sopenharmony_ci<ul> 8221cb0ef41Sopenharmony_ci<li><code>specifier</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li> 8231cb0ef41Sopenharmony_ci<li><code>context</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a></li> 8241cb0ef41Sopenharmony_ci</ul> 8251cb0ef41Sopenharmony_ci</li> 8261cb0ef41Sopenharmony_ci<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> 8271cb0ef41Sopenharmony_ci<ul> 8281cb0ef41Sopenharmony_ci<li><code>format</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li> 8291cb0ef41Sopenharmony_ci<li><code>shortCircuit</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Undefined_type" class="type"><undefined></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> A signal that this hook intends to 8301cb0ef41Sopenharmony_citerminate the chain of <code>resolve</code> hooks. <strong>Default:</strong> <code>false</code></li> 8311cb0ef41Sopenharmony_ci<li><code>source</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer" class="type"><ArrayBuffer></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray" class="type"><TypedArray></a> The source for Node.js to evaluate</li> 8321cb0ef41Sopenharmony_ci</ul> 8331cb0ef41Sopenharmony_ci</li> 8341cb0ef41Sopenharmony_ci</ul> 8351cb0ef41Sopenharmony_ci<p>The <code>load</code> hook provides a way to define a custom method of determining how a 8361cb0ef41Sopenharmony_ciURL should be interpreted, retrieved, and parsed. It is also in charge of 8371cb0ef41Sopenharmony_civalidating the import assertion.</p> 8381cb0ef41Sopenharmony_ci<p>The final value of <code>format</code> must be one of the following:</p> 8391cb0ef41Sopenharmony_ci 8401cb0ef41Sopenharmony_ci 8411cb0ef41Sopenharmony_ci 8421cb0ef41Sopenharmony_ci 8431cb0ef41Sopenharmony_ci 8441cb0ef41Sopenharmony_ci 8451cb0ef41Sopenharmony_ci 8461cb0ef41Sopenharmony_ci 8471cb0ef41Sopenharmony_ci 8481cb0ef41Sopenharmony_ci 8491cb0ef41Sopenharmony_ci 8501cb0ef41Sopenharmony_ci 8511cb0ef41Sopenharmony_ci 8521cb0ef41Sopenharmony_ci 8531cb0ef41Sopenharmony_ci 8541cb0ef41Sopenharmony_ci 8551cb0ef41Sopenharmony_ci 8561cb0ef41Sopenharmony_ci 8571cb0ef41Sopenharmony_ci 8581cb0ef41Sopenharmony_ci 8591cb0ef41Sopenharmony_ci 8601cb0ef41Sopenharmony_ci 8611cb0ef41Sopenharmony_ci 8621cb0ef41Sopenharmony_ci 8631cb0ef41Sopenharmony_ci 8641cb0ef41Sopenharmony_ci 8651cb0ef41Sopenharmony_ci 8661cb0ef41Sopenharmony_ci 8671cb0ef41Sopenharmony_ci 8681cb0ef41Sopenharmony_ci 8691cb0ef41Sopenharmony_ci 8701cb0ef41Sopenharmony_ci 8711cb0ef41Sopenharmony_ci 8721cb0ef41Sopenharmony_ci 8731cb0ef41Sopenharmony_ci 8741cb0ef41Sopenharmony_ci<table><thead><tr><th><code>format</code></th><th>Description</th><th>Acceptable types for <code>source</code> returned by <code>load</code></th></tr></thead><tbody><tr><td><code>'builtin'</code></td><td>Load a Node.js builtin module</td><td>Not applicable</td></tr><tr><td><code>'commonjs'</code></td><td>Load a Node.js CommonJS module</td><td>Not applicable</td></tr><tr><td><code>'json'</code></td><td>Load a JSON file</td><td>{ <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String"><code>string</code></a>, <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer"><code>ArrayBuffer</code></a>, <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray"><code>TypedArray</code></a> }</td></tr><tr><td><code>'module'</code></td><td>Load an ES module</td><td>{ <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String"><code>string</code></a>, <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer"><code>ArrayBuffer</code></a>, <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray"><code>TypedArray</code></a> }</td></tr><tr><td><code>'wasm'</code></td><td>Load a WebAssembly module</td><td>{ <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer"><code>ArrayBuffer</code></a>, <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray"><code>TypedArray</code></a> }</td></tr></tbody></table> 8751cb0ef41Sopenharmony_ci<p>The value of <code>source</code> is ignored for type <code>'builtin'</code> because currently it is 8761cb0ef41Sopenharmony_cinot possible to replace the value of a Node.js builtin (core) module. The value 8771cb0ef41Sopenharmony_ciof <code>source</code> is ignored for type <code>'commonjs'</code> because the CommonJS module loader 8781cb0ef41Sopenharmony_cidoes not provide a mechanism for the ES module loader to override the 8791cb0ef41Sopenharmony_ci<a href="esm.html#commonjs-namespaces">CommonJS module return value</a>. This limitation 8801cb0ef41Sopenharmony_cimight be overcome in the future.</p> 8811cb0ef41Sopenharmony_ci<blockquote> 8821cb0ef41Sopenharmony_ci<p><strong>Warning</strong>: The ESM <code>load</code> hook and namespaced exports from CommonJS modules 8831cb0ef41Sopenharmony_ciare incompatible. Attempting to use them together will result in an empty 8841cb0ef41Sopenharmony_ciobject from the import. This may be addressed in the future.</p> 8851cb0ef41Sopenharmony_ci</blockquote> 8861cb0ef41Sopenharmony_ci<blockquote> 8871cb0ef41Sopenharmony_ci<p>These types all correspond to classes defined in ECMAScript.</p> 8881cb0ef41Sopenharmony_ci</blockquote> 8891cb0ef41Sopenharmony_ci<ul> 8901cb0ef41Sopenharmony_ci<li>The specific <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer"><code>ArrayBuffer</code></a> object is a <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/SharedArrayBuffer"><code>SharedArrayBuffer</code></a>.</li> 8911cb0ef41Sopenharmony_ci<li>The specific <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray"><code>TypedArray</code></a> object is a <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array"><code>Uint8Array</code></a>.</li> 8921cb0ef41Sopenharmony_ci</ul> 8931cb0ef41Sopenharmony_ci<p>If the source value of a text-based format (i.e., <code>'json'</code>, <code>'module'</code>) 8941cb0ef41Sopenharmony_ciis not a string, it is converted to a string using <a href="util.html#class-utiltextdecoder"><code>util.TextDecoder</code></a>.</p> 8951cb0ef41Sopenharmony_ci<p>The <code>load</code> hook provides a way to define a custom method for retrieving the 8961cb0ef41Sopenharmony_cisource code of a resolved URL. This would allow a loader to potentially avoid 8971cb0ef41Sopenharmony_cireading files from disk. It could also be used to map an unrecognized format to 8981cb0ef41Sopenharmony_cia supported one, for example <code>yaml</code> to <code>module</code>.</p> 8991cb0ef41Sopenharmony_ci<pre><code class="language-js mjs"><span class="hljs-keyword">export</span> <span class="hljs-keyword">async</span> <span class="hljs-keyword">function</span> <span class="hljs-title function_">load</span>(<span class="hljs-params">url, context, nextLoad</span>) { 9001cb0ef41Sopenharmony_ci <span class="hljs-keyword">const</span> { format } = context; 9011cb0ef41Sopenharmony_ci 9021cb0ef41Sopenharmony_ci <span class="hljs-keyword">if</span> (<span class="hljs-title class_">Math</span>.<span class="hljs-title function_">random</span>() > <span class="hljs-number">0.5</span>) { <span class="hljs-comment">// Some condition</span> 9031cb0ef41Sopenharmony_ci <span class="hljs-comment">/* 9041cb0ef41Sopenharmony_ci For some or all URLs, do some custom logic for retrieving the source. 9051cb0ef41Sopenharmony_ci Always return an object of the form { 9061cb0ef41Sopenharmony_ci format: <string>, 9071cb0ef41Sopenharmony_ci source: <string|buffer>, 9081cb0ef41Sopenharmony_ci }. 9091cb0ef41Sopenharmony_ci */</span> 9101cb0ef41Sopenharmony_ci <span class="hljs-keyword">return</span> { 9111cb0ef41Sopenharmony_ci format, 9121cb0ef41Sopenharmony_ci <span class="hljs-attr">shortCircuit</span>: <span class="hljs-literal">true</span>, 9131cb0ef41Sopenharmony_ci <span class="hljs-attr">source</span>: <span class="hljs-string">'...'</span>, 9141cb0ef41Sopenharmony_ci }; 9151cb0ef41Sopenharmony_ci } 9161cb0ef41Sopenharmony_ci 9171cb0ef41Sopenharmony_ci <span class="hljs-comment">// Defer to the next hook in the chain.</span> 9181cb0ef41Sopenharmony_ci <span class="hljs-keyword">return</span> <span class="hljs-title function_">nextLoad</span>(url); 9191cb0ef41Sopenharmony_ci}</code> <button class="copy-button">copy</button></pre> 9201cb0ef41Sopenharmony_ci<p>In a more advanced scenario, this can also be used to transform an unsupported 9211cb0ef41Sopenharmony_cisource to a supported one (see <a href="#examples">Examples</a> below).</p> 9221cb0ef41Sopenharmony_ci<h5><code>globalPreload()</code><span><a class="mark" href="#globalpreload" id="globalpreload">#</a></span><a aria-hidden="true" class="legacy" id="module_globalpreload"></a></h5> 9231cb0ef41Sopenharmony_ci<div class="api_metadata"> 9241cb0ef41Sopenharmony_ci<details class="changelog"><summary>History</summary> 9251cb0ef41Sopenharmony_ci<table> 9261cb0ef41Sopenharmony_ci<tbody><tr><th>Version</th><th>Changes</th></tr> 9271cb0ef41Sopenharmony_ci<tr><td>v18.6.0, v16.17.0</td> 9281cb0ef41Sopenharmony_ci<td><p>Add support for chaining globalPreload hooks.</p></td></tr> 9291cb0ef41Sopenharmony_ci</tbody></table> 9301cb0ef41Sopenharmony_ci</details> 9311cb0ef41Sopenharmony_ci</div> 9321cb0ef41Sopenharmony_ci<p></p><div class="api_stability api_stability_1"><a href="documentation.html#stability-index">Stability: 1</a>.0 - Early development</div><p></p> 9331cb0ef41Sopenharmony_ci<blockquote> 9341cb0ef41Sopenharmony_ci<p><strong>Warning:</strong> This hook will be removed in a future version. Use 9351cb0ef41Sopenharmony_ci<a href="#initialize"><code>initialize</code></a> instead. When a hooks module has an <code>initialize</code> export, 9361cb0ef41Sopenharmony_ci<code>globalPreload</code> will be ignored.</p> 9371cb0ef41Sopenharmony_ci</blockquote> 9381cb0ef41Sopenharmony_ci<ul> 9391cb0ef41Sopenharmony_ci<li><code>context</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> Information to assist the preload code 9401cb0ef41Sopenharmony_ci<ul> 9411cb0ef41Sopenharmony_ci<li><code>port</code> <a href="worker_threads.html#class-messageport" class="type"><MessagePort></a></li> 9421cb0ef41Sopenharmony_ci</ul> 9431cb0ef41Sopenharmony_ci</li> 9441cb0ef41Sopenharmony_ci<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> Code to run before application startup</li> 9451cb0ef41Sopenharmony_ci</ul> 9461cb0ef41Sopenharmony_ci<p>Sometimes it might be necessary to run some code inside of the same global 9471cb0ef41Sopenharmony_ciscope that the application runs in. This hook allows the return of a string 9481cb0ef41Sopenharmony_cithat is run as a sloppy-mode script on startup.</p> 9491cb0ef41Sopenharmony_ci<p>Similar to how CommonJS wrappers work, the code runs in an implicit function 9501cb0ef41Sopenharmony_ciscope. The only argument is a <code>require</code>-like function that can be used to load 9511cb0ef41Sopenharmony_cibuiltins like "fs": <code>getBuiltin(request: string)</code>.</p> 9521cb0ef41Sopenharmony_ci<p>If the code needs more advanced <code>require</code> features, it has to construct 9531cb0ef41Sopenharmony_ciits own <code>require</code> using <code>module.createRequire()</code>.</p> 9541cb0ef41Sopenharmony_ci<pre><code class="language-js mjs"><span class="hljs-keyword">export</span> <span class="hljs-keyword">function</span> <span class="hljs-title function_">globalPreload</span>(<span class="hljs-params">context</span>) { 9551cb0ef41Sopenharmony_ci <span class="hljs-keyword">return</span> <span class="hljs-string">`\ 9561cb0ef41Sopenharmony_ciglobalThis.someInjectedProperty = 42; 9571cb0ef41Sopenharmony_ciconsole.log('I just set some globals!'); 9581cb0ef41Sopenharmony_ci 9591cb0ef41Sopenharmony_ciconst { createRequire } = getBuiltin('module'); 9601cb0ef41Sopenharmony_ciconst { cwd } = getBuiltin('process'); 9611cb0ef41Sopenharmony_ci 9621cb0ef41Sopenharmony_ciconst require = createRequire(cwd() + '/<preload>'); 9631cb0ef41Sopenharmony_ci// [...] 9641cb0ef41Sopenharmony_ci`</span>; 9651cb0ef41Sopenharmony_ci}</code> <button class="copy-button">copy</button></pre> 9661cb0ef41Sopenharmony_ci<p>Another argument is provided to the preload code: <code>port</code>. This is available as a 9671cb0ef41Sopenharmony_ciparameter to the hook and inside of the source text returned by the hook. This 9681cb0ef41Sopenharmony_cifunctionality has been moved to the <code>initialize</code> hook.</p> 9691cb0ef41Sopenharmony_ci<p>Care must be taken in order to properly call <a href="worker_threads.html#portref"><code>port.ref()</code></a> and 9701cb0ef41Sopenharmony_ci<a href="worker_threads.html#portunref"><code>port.unref()</code></a> to prevent a process from being in a state where it won't 9711cb0ef41Sopenharmony_ciclose normally.</p> 9721cb0ef41Sopenharmony_ci<pre><code class="language-js mjs"><span class="hljs-comment">/** 9731cb0ef41Sopenharmony_ci * This example has the application context send a message to the hook 9741cb0ef41Sopenharmony_ci * and sends the message back to the application context 9751cb0ef41Sopenharmony_ci */</span> 9761cb0ef41Sopenharmony_ci<span class="hljs-keyword">export</span> <span class="hljs-keyword">function</span> <span class="hljs-title function_">globalPreload</span>(<span class="hljs-params">{ port }</span>) { 9771cb0ef41Sopenharmony_ci port.<span class="hljs-title function_">on</span>(<span class="hljs-string">'message'</span>, <span class="hljs-function">(<span class="hljs-params">msg</span>) =></span> { 9781cb0ef41Sopenharmony_ci port.<span class="hljs-title function_">postMessage</span>(msg); 9791cb0ef41Sopenharmony_ci }); 9801cb0ef41Sopenharmony_ci <span class="hljs-keyword">return</span> <span class="hljs-string">`\ 9811cb0ef41Sopenharmony_ci port.postMessage('console.log("I went to the hook and back");'); 9821cb0ef41Sopenharmony_ci port.on('message', (msg) => { 9831cb0ef41Sopenharmony_ci eval(msg); 9841cb0ef41Sopenharmony_ci }); 9851cb0ef41Sopenharmony_ci `</span>; 9861cb0ef41Sopenharmony_ci}</code> <button class="copy-button">copy</button></pre> 9871cb0ef41Sopenharmony_ci<h4>Examples<span><a class="mark" href="#examples" id="examples">#</a></span><a aria-hidden="true" class="legacy" id="module_examples"></a></h4> 9881cb0ef41Sopenharmony_ci<p>The various module customization hooks can be used together to accomplish 9891cb0ef41Sopenharmony_ciwide-ranging customizations of the Node.js code loading and evaluation 9901cb0ef41Sopenharmony_cibehaviors.</p> 9911cb0ef41Sopenharmony_ci<h5>Import from HTTPS<span><a class="mark" href="#import-from-https" id="import-from-https">#</a></span><a aria-hidden="true" class="legacy" id="module_import_from_https"></a></h5> 9921cb0ef41Sopenharmony_ci<p>In current Node.js, specifiers starting with <code>https://</code> are experimental (see 9931cb0ef41Sopenharmony_ci<a href="esm.html#https-and-http-imports">HTTPS and HTTP imports</a>).</p> 9941cb0ef41Sopenharmony_ci<p>The hook below registers hooks to enable rudimentary support for such 9951cb0ef41Sopenharmony_cispecifiers. While this may seem like a significant improvement to Node.js core 9961cb0ef41Sopenharmony_cifunctionality, there are substantial downsides to actually using these hooks: 9971cb0ef41Sopenharmony_ciperformance is much slower than loading files from disk, there is no caching, 9981cb0ef41Sopenharmony_ciand there is no security.</p> 9991cb0ef41Sopenharmony_ci<pre><code class="language-js mjs"><span class="hljs-comment">// https-hooks.mjs</span> 10001cb0ef41Sopenharmony_ci<span class="hljs-keyword">import</span> { get } <span class="hljs-keyword">from</span> <span class="hljs-string">'node:https'</span>; 10011cb0ef41Sopenharmony_ci 10021cb0ef41Sopenharmony_ci<span class="hljs-keyword">export</span> <span class="hljs-keyword">function</span> <span class="hljs-title function_">load</span>(<span class="hljs-params">url, context, nextLoad</span>) { 10031cb0ef41Sopenharmony_ci <span class="hljs-comment">// For JavaScript to be loaded over the network, we need to fetch and</span> 10041cb0ef41Sopenharmony_ci <span class="hljs-comment">// return it.</span> 10051cb0ef41Sopenharmony_ci <span class="hljs-keyword">if</span> (url.<span class="hljs-title function_">startsWith</span>(<span class="hljs-string">'https://'</span>)) { 10061cb0ef41Sopenharmony_ci <span class="hljs-keyword">return</span> <span class="hljs-keyword">new</span> <span class="hljs-title class_">Promise</span>(<span class="hljs-function">(<span class="hljs-params">resolve, reject</span>) =></span> { 10071cb0ef41Sopenharmony_ci <span class="hljs-title function_">get</span>(url, <span class="hljs-function">(<span class="hljs-params">res</span>) =></span> { 10081cb0ef41Sopenharmony_ci <span class="hljs-keyword">let</span> data = <span class="hljs-string">''</span>; 10091cb0ef41Sopenharmony_ci res.<span class="hljs-title function_">setEncoding</span>(<span class="hljs-string">'utf8'</span>); 10101cb0ef41Sopenharmony_ci res.<span class="hljs-title function_">on</span>(<span class="hljs-string">'data'</span>, <span class="hljs-function">(<span class="hljs-params">chunk</span>) =></span> data += chunk); 10111cb0ef41Sopenharmony_ci res.<span class="hljs-title function_">on</span>(<span class="hljs-string">'end'</span>, <span class="hljs-function">() =></span> <span class="hljs-title function_">resolve</span>({ 10121cb0ef41Sopenharmony_ci <span class="hljs-comment">// This example assumes all network-provided JavaScript is ES module</span> 10131cb0ef41Sopenharmony_ci <span class="hljs-comment">// code.</span> 10141cb0ef41Sopenharmony_ci <span class="hljs-attr">format</span>: <span class="hljs-string">'module'</span>, 10151cb0ef41Sopenharmony_ci <span class="hljs-attr">shortCircuit</span>: <span class="hljs-literal">true</span>, 10161cb0ef41Sopenharmony_ci <span class="hljs-attr">source</span>: data, 10171cb0ef41Sopenharmony_ci })); 10181cb0ef41Sopenharmony_ci }).<span class="hljs-title function_">on</span>(<span class="hljs-string">'error'</span>, <span class="hljs-function">(<span class="hljs-params">err</span>) =></span> <span class="hljs-title function_">reject</span>(err)); 10191cb0ef41Sopenharmony_ci }); 10201cb0ef41Sopenharmony_ci } 10211cb0ef41Sopenharmony_ci 10221cb0ef41Sopenharmony_ci <span class="hljs-comment">// Let Node.js handle all other URLs.</span> 10231cb0ef41Sopenharmony_ci <span class="hljs-keyword">return</span> <span class="hljs-title function_">nextLoad</span>(url); 10241cb0ef41Sopenharmony_ci}</code> <button class="copy-button">copy</button></pre> 10251cb0ef41Sopenharmony_ci<pre><code class="language-js mjs"><span class="hljs-comment">// main.mjs</span> 10261cb0ef41Sopenharmony_ci<span class="hljs-keyword">import</span> { <span class="hljs-variable constant_">VERSION</span> } <span class="hljs-keyword">from</span> <span class="hljs-string">'https://coffeescript.org/browser-compiler-modern/coffeescript.js'</span>; 10271cb0ef41Sopenharmony_ci 10281cb0ef41Sopenharmony_ci<span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-variable constant_">VERSION</span>);</code> <button class="copy-button">copy</button></pre> 10291cb0ef41Sopenharmony_ci<p>With the preceding hooks module, running 10301cb0ef41Sopenharmony_ci<code>node --import 'data:text/javascript,import { register } from "node:module"; import { pathToFileURL } from "node:url"; register(pathToFileURL("./https-hooks.mjs"));' ./main.mjs</code> 10311cb0ef41Sopenharmony_ciprints the current version of CoffeeScript per the module at the URL in 10321cb0ef41Sopenharmony_ci<code>main.mjs</code>.</p> 10331cb0ef41Sopenharmony_ci<h5>Transpilation<span><a class="mark" href="#transpilation" id="transpilation">#</a></span><a aria-hidden="true" class="legacy" id="module_transpilation"></a></h5> 10341cb0ef41Sopenharmony_ci<p>Sources that are in formats Node.js doesn't understand can be converted into 10351cb0ef41Sopenharmony_ciJavaScript using the <a href="#loadurl-context-nextload"><code>load</code> hook</a>.</p> 10361cb0ef41Sopenharmony_ci<p>This is less performant than transpiling source files before running Node.js; 10371cb0ef41Sopenharmony_citranspiler hooks should only be used for development and testing purposes.</p> 10381cb0ef41Sopenharmony_ci<pre><code class="language-js mjs"><span class="hljs-comment">// coffeescript-hooks.mjs</span> 10391cb0ef41Sopenharmony_ci<span class="hljs-keyword">import</span> { readFile } <span class="hljs-keyword">from</span> <span class="hljs-string">'node:fs/promises'</span>; 10401cb0ef41Sopenharmony_ci<span class="hljs-keyword">import</span> { dirname, extname, resolve <span class="hljs-keyword">as</span> resolvePath } <span class="hljs-keyword">from</span> <span class="hljs-string">'node:path'</span>; 10411cb0ef41Sopenharmony_ci<span class="hljs-keyword">import</span> { cwd } <span class="hljs-keyword">from</span> <span class="hljs-string">'node:process'</span>; 10421cb0ef41Sopenharmony_ci<span class="hljs-keyword">import</span> { fileURLToPath, pathToFileURL } <span class="hljs-keyword">from</span> <span class="hljs-string">'node:url'</span>; 10431cb0ef41Sopenharmony_ci<span class="hljs-keyword">import</span> coffeescript <span class="hljs-keyword">from</span> <span class="hljs-string">'coffeescript'</span>; 10441cb0ef41Sopenharmony_ci 10451cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> extensionsRegex = <span class="hljs-regexp">/\.(coffee|litcoffee|coffee\.md)$/</span>; 10461cb0ef41Sopenharmony_ci 10471cb0ef41Sopenharmony_ci<span class="hljs-keyword">export</span> <span class="hljs-keyword">async</span> <span class="hljs-keyword">function</span> <span class="hljs-title function_">load</span>(<span class="hljs-params">url, context, nextLoad</span>) { 10481cb0ef41Sopenharmony_ci <span class="hljs-keyword">if</span> (extensionsRegex.<span class="hljs-title function_">test</span>(url)) { 10491cb0ef41Sopenharmony_ci <span class="hljs-comment">// CoffeeScript files can be either CommonJS or ES modules, so we want any</span> 10501cb0ef41Sopenharmony_ci <span class="hljs-comment">// CoffeeScript file to be treated by Node.js the same as a .js file at the</span> 10511cb0ef41Sopenharmony_ci <span class="hljs-comment">// same location. To determine how Node.js would interpret an arbitrary .js</span> 10521cb0ef41Sopenharmony_ci <span class="hljs-comment">// file, search up the file system for the nearest parent package.json file</span> 10531cb0ef41Sopenharmony_ci <span class="hljs-comment">// and read its "type" field.</span> 10541cb0ef41Sopenharmony_ci <span class="hljs-keyword">const</span> format = <span class="hljs-keyword">await</span> <span class="hljs-title function_">getPackageType</span>(url); 10551cb0ef41Sopenharmony_ci 10561cb0ef41Sopenharmony_ci <span class="hljs-keyword">const</span> { <span class="hljs-attr">source</span>: rawSource } = <span class="hljs-keyword">await</span> <span class="hljs-title function_">nextLoad</span>(url, { ...context, format }); 10571cb0ef41Sopenharmony_ci <span class="hljs-comment">// This hook converts CoffeeScript source code into JavaScript source code</span> 10581cb0ef41Sopenharmony_ci <span class="hljs-comment">// for all imported CoffeeScript files.</span> 10591cb0ef41Sopenharmony_ci <span class="hljs-keyword">const</span> transformedSource = coffeescript.<span class="hljs-title function_">compile</span>(rawSource.<span class="hljs-title function_">toString</span>(), url); 10601cb0ef41Sopenharmony_ci 10611cb0ef41Sopenharmony_ci <span class="hljs-keyword">return</span> { 10621cb0ef41Sopenharmony_ci format, 10631cb0ef41Sopenharmony_ci <span class="hljs-attr">shortCircuit</span>: <span class="hljs-literal">true</span>, 10641cb0ef41Sopenharmony_ci <span class="hljs-attr">source</span>: transformedSource, 10651cb0ef41Sopenharmony_ci }; 10661cb0ef41Sopenharmony_ci } 10671cb0ef41Sopenharmony_ci 10681cb0ef41Sopenharmony_ci <span class="hljs-comment">// Let Node.js handle all other URLs.</span> 10691cb0ef41Sopenharmony_ci <span class="hljs-keyword">return</span> <span class="hljs-title function_">nextLoad</span>(url); 10701cb0ef41Sopenharmony_ci} 10711cb0ef41Sopenharmony_ci 10721cb0ef41Sopenharmony_ci<span class="hljs-keyword">async</span> <span class="hljs-keyword">function</span> <span class="hljs-title function_">getPackageType</span>(<span class="hljs-params">url</span>) { 10731cb0ef41Sopenharmony_ci <span class="hljs-comment">// `url` is only a file path during the first iteration when passed the</span> 10741cb0ef41Sopenharmony_ci <span class="hljs-comment">// resolved url from the load() hook</span> 10751cb0ef41Sopenharmony_ci <span class="hljs-comment">// an actual file path from load() will contain a file extension as it's</span> 10761cb0ef41Sopenharmony_ci <span class="hljs-comment">// required by the spec</span> 10771cb0ef41Sopenharmony_ci <span class="hljs-comment">// this simple truthy check for whether `url` contains a file extension will</span> 10781cb0ef41Sopenharmony_ci <span class="hljs-comment">// work for most projects but does not cover some edge-cases (such as</span> 10791cb0ef41Sopenharmony_ci <span class="hljs-comment">// extensionless files or a url ending in a trailing space)</span> 10801cb0ef41Sopenharmony_ci <span class="hljs-keyword">const</span> isFilePath = !!<span class="hljs-title function_">extname</span>(url); 10811cb0ef41Sopenharmony_ci <span class="hljs-comment">// If it is a file path, get the directory it's in</span> 10821cb0ef41Sopenharmony_ci <span class="hljs-keyword">const</span> dir = isFilePath ? 10831cb0ef41Sopenharmony_ci <span class="hljs-title function_">dirname</span>(<span class="hljs-title function_">fileURLToPath</span>(url)) : 10841cb0ef41Sopenharmony_ci url; 10851cb0ef41Sopenharmony_ci <span class="hljs-comment">// Compose a file path to a package.json in the same directory,</span> 10861cb0ef41Sopenharmony_ci <span class="hljs-comment">// which may or may not exist</span> 10871cb0ef41Sopenharmony_ci <span class="hljs-keyword">const</span> packagePath = <span class="hljs-title function_">resolvePath</span>(dir, <span class="hljs-string">'package.json'</span>); 10881cb0ef41Sopenharmony_ci <span class="hljs-comment">// Try to read the possibly nonexistent package.json</span> 10891cb0ef41Sopenharmony_ci <span class="hljs-keyword">const</span> type = <span class="hljs-keyword">await</span> <span class="hljs-title function_">readFile</span>(packagePath, { <span class="hljs-attr">encoding</span>: <span class="hljs-string">'utf8'</span> }) 10901cb0ef41Sopenharmony_ci .<span class="hljs-title function_">then</span>(<span class="hljs-function">(<span class="hljs-params">filestring</span>) =></span> <span class="hljs-title class_">JSON</span>.<span class="hljs-title function_">parse</span>(filestring).<span class="hljs-property">type</span>) 10911cb0ef41Sopenharmony_ci .<span class="hljs-title function_">catch</span>(<span class="hljs-function">(<span class="hljs-params">err</span>) =></span> { 10921cb0ef41Sopenharmony_ci <span class="hljs-keyword">if</span> (err?.<span class="hljs-property">code</span> !== <span class="hljs-string">'ENOENT'</span>) <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">error</span>(err); 10931cb0ef41Sopenharmony_ci }); 10941cb0ef41Sopenharmony_ci <span class="hljs-comment">// Ff package.json existed and contained a `type` field with a value, voila</span> 10951cb0ef41Sopenharmony_ci <span class="hljs-keyword">if</span> (type) <span class="hljs-keyword">return</span> type; 10961cb0ef41Sopenharmony_ci <span class="hljs-comment">// Otherwise, (if not at the root) continue checking the next directory up</span> 10971cb0ef41Sopenharmony_ci <span class="hljs-comment">// If at the root, stop and return false</span> 10981cb0ef41Sopenharmony_ci <span class="hljs-keyword">return</span> dir.<span class="hljs-property">length</span> > <span class="hljs-number">1</span> && <span class="hljs-title function_">getPackageType</span>(<span class="hljs-title function_">resolvePath</span>(dir, <span class="hljs-string">'..'</span>)); 10991cb0ef41Sopenharmony_ci}</code> <button class="copy-button">copy</button></pre> 11001cb0ef41Sopenharmony_ci<pre><code class="language-coffee"><span class="hljs-comment"># main.coffee</span> 11011cb0ef41Sopenharmony_ci<span class="hljs-keyword">import</span> { scream } <span class="hljs-keyword">from</span> <span class="hljs-string">'./scream.coffee'</span> 11021cb0ef41Sopenharmony_ciconsole.log scream <span class="hljs-string">'hello, world'</span> 11031cb0ef41Sopenharmony_ci 11041cb0ef41Sopenharmony_ci<span class="hljs-keyword">import</span> { version } <span class="hljs-keyword">from</span> <span class="hljs-string">'node:process'</span> 11051cb0ef41Sopenharmony_ciconsole.log <span class="hljs-string">"Brought to you by Node.js version <span class="hljs-subst">#{version}</span>"</span></code> <button class="copy-button">copy</button></pre> 11061cb0ef41Sopenharmony_ci<pre><code class="language-coffee"><span class="hljs-comment"># scream.coffee</span> 11071cb0ef41Sopenharmony_ci<span class="hljs-keyword">export</span> scream = <span class="hljs-function"><span class="hljs-params">(str)</span> -></span> str.toUpperCase()</code> <button class="copy-button">copy</button></pre> 11081cb0ef41Sopenharmony_ci<p>With the preceding hooks module, running 11091cb0ef41Sopenharmony_ci<code>node --import 'data:text/javascript,import { register } from "node:module"; import { pathToFileURL } from "node:url"; register(pathToFileURL("./coffeescript-hooks.mjs"));' ./main.coffee</code> 11101cb0ef41Sopenharmony_cicauses <code>main.coffee</code> to be turned into JavaScript after its source code is 11111cb0ef41Sopenharmony_ciloaded from disk but before Node.js executes it; and so on for any <code>.coffee</code>, 11121cb0ef41Sopenharmony_ci<code>.litcoffee</code> or <code>.coffee.md</code> files referenced via <code>import</code> statements of any 11131cb0ef41Sopenharmony_ciloaded file.</p> 11141cb0ef41Sopenharmony_ci<h5>Import maps<span><a class="mark" href="#import-maps" id="import-maps">#</a></span><a aria-hidden="true" class="legacy" id="module_import_maps"></a></h5> 11151cb0ef41Sopenharmony_ci<p>The previous two examples defined <code>load</code> hooks. This is an example of a 11161cb0ef41Sopenharmony_ci<code>resolve</code> hook. This hooks module reads an <code>import-map.json</code> file that defines 11171cb0ef41Sopenharmony_ciwhich specifiers to override to other URLs (this is a very simplistic 11181cb0ef41Sopenharmony_ciimplementation of a small subset of the "import maps" specification).</p> 11191cb0ef41Sopenharmony_ci<pre><code class="language-js mjs"><span class="hljs-comment">// import-map-hooks.js</span> 11201cb0ef41Sopenharmony_ci<span class="hljs-keyword">import</span> fs <span class="hljs-keyword">from</span> <span class="hljs-string">'node:fs/promises'</span>; 11211cb0ef41Sopenharmony_ci 11221cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> { imports } = <span class="hljs-title class_">JSON</span>.<span class="hljs-title function_">parse</span>(<span class="hljs-keyword">await</span> fs.<span class="hljs-title function_">readFile</span>(<span class="hljs-string">'import-map.json'</span>)); 11231cb0ef41Sopenharmony_ci 11241cb0ef41Sopenharmony_ci<span class="hljs-keyword">export</span> <span class="hljs-keyword">async</span> <span class="hljs-keyword">function</span> <span class="hljs-title function_">resolve</span>(<span class="hljs-params">specifier, context, nextResolve</span>) { 11251cb0ef41Sopenharmony_ci <span class="hljs-keyword">if</span> (<span class="hljs-title class_">Object</span>.<span class="hljs-title function_">hasOwn</span>(imports, specifier)) { 11261cb0ef41Sopenharmony_ci <span class="hljs-keyword">return</span> <span class="hljs-title function_">nextResolve</span>(imports[specifier], context); 11271cb0ef41Sopenharmony_ci } 11281cb0ef41Sopenharmony_ci 11291cb0ef41Sopenharmony_ci <span class="hljs-keyword">return</span> <span class="hljs-title function_">nextResolve</span>(specifier, context); 11301cb0ef41Sopenharmony_ci}</code> <button class="copy-button">copy</button></pre> 11311cb0ef41Sopenharmony_ci<p>With these files:</p> 11321cb0ef41Sopenharmony_ci<pre><code class="language-js mjs"><span class="hljs-comment">// main.js</span> 11331cb0ef41Sopenharmony_ci<span class="hljs-keyword">import</span> <span class="hljs-string">'a-module'</span>;</code> <button class="copy-button">copy</button></pre> 11341cb0ef41Sopenharmony_ci<pre><code class="language-json"><span class="hljs-comment">// import-map.json</span> 11351cb0ef41Sopenharmony_ci<span class="hljs-punctuation">{</span> 11361cb0ef41Sopenharmony_ci <span class="hljs-attr">"imports"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> 11371cb0ef41Sopenharmony_ci <span class="hljs-attr">"a-module"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"./some-module.js"</span> 11381cb0ef41Sopenharmony_ci <span class="hljs-punctuation">}</span> 11391cb0ef41Sopenharmony_ci<span class="hljs-punctuation">}</span></code> <button class="copy-button">copy</button></pre> 11401cb0ef41Sopenharmony_ci<pre><code class="language-js mjs"><span class="hljs-comment">// some-module.js</span> 11411cb0ef41Sopenharmony_ci<span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'some module!'</span>);</code> <button class="copy-button">copy</button></pre> 11421cb0ef41Sopenharmony_ci<p>Running <code>node --import 'data:text/javascript,import { register } from "node:module"; import { pathToFileURL } from "node:url"; register(pathToFileURL("./import-map-hooks.js"));' main.js</code> 11431cb0ef41Sopenharmony_cishould print <code>some module!</code>.</p> 11441cb0ef41Sopenharmony_ci</section><section><h3>Source map v3 support<span><a class="mark" href="#source-map-v3-support" id="source-map-v3-support">#</a></span><a aria-hidden="true" class="legacy" id="module_source_map_v3_support"></a></h3> 11451cb0ef41Sopenharmony_ci<div class="api_metadata"> 11461cb0ef41Sopenharmony_ci<span>Added in: v13.7.0, v12.17.0</span> 11471cb0ef41Sopenharmony_ci</div> 11481cb0ef41Sopenharmony_ci<p></p><div class="api_stability api_stability_1"><a href="documentation.html#stability-index">Stability: 1</a> - Experimental</div><p></p> 11491cb0ef41Sopenharmony_ci<p>Helpers for interacting with the source map cache. This cache is 11501cb0ef41Sopenharmony_cipopulated when source map parsing is enabled and 11511cb0ef41Sopenharmony_ci<a href="https://sourcemaps.info/spec.html#h.lmz475t4mvbx">source map include directives</a> are found in a modules' footer.</p> 11521cb0ef41Sopenharmony_ci<p>To enable source map parsing, Node.js must be run with the flag 11531cb0ef41Sopenharmony_ci<a href="cli.html#--enable-source-maps"><code>--enable-source-maps</code></a>, or with code coverage enabled by setting 11541cb0ef41Sopenharmony_ci<a href="cli.html#node_v8_coveragedir"><code>NODE_V8_COVERAGE=dir</code></a>.</p> 11551cb0ef41Sopenharmony_ci 11561cb0ef41Sopenharmony_ci<pre class="with-26-chars"><input class="js-flavor-selector" type="checkbox" checked aria-label="Show modern ES modules syntax"><code class="language-js mjs"><span class="hljs-comment">// module.mjs</span> 11571cb0ef41Sopenharmony_ci<span class="hljs-comment">// In an ECMAScript module</span> 11581cb0ef41Sopenharmony_ci<span class="hljs-keyword">import</span> { findSourceMap, <span class="hljs-title class_">SourceMap</span> } <span class="hljs-keyword">from</span> <span class="hljs-string">'node:module'</span>;</code><code class="language-js cjs"><span class="hljs-comment">// module.cjs</span> 11591cb0ef41Sopenharmony_ci<span class="hljs-comment">// In a CommonJS module</span> 11601cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> { findSourceMap, <span class="hljs-title class_">SourceMap</span> } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:module'</span>);</code><button class="copy-button">copy</button></pre> 11611cb0ef41Sopenharmony_ci<!-- Anchors to make sure old links find a target --> 11621cb0ef41Sopenharmony_ci<p><a id="module_module_findsourcemap_path_error"></a></p> 11631cb0ef41Sopenharmony_ci<h4><code>module.findSourceMap(path)</code><span><a class="mark" href="#modulefindsourcemappath" id="modulefindsourcemappath">#</a></span><a aria-hidden="true" class="legacy" id="module_module_findsourcemap_path"></a></h4> 11641cb0ef41Sopenharmony_ci<div class="api_metadata"> 11651cb0ef41Sopenharmony_ci<span>Added in: v13.7.0, v12.17.0</span> 11661cb0ef41Sopenharmony_ci</div> 11671cb0ef41Sopenharmony_ci<ul> 11681cb0ef41Sopenharmony_ci<li><code>path</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li> 11691cb0ef41Sopenharmony_ci<li>Returns: <a href="module.html#class-modulesourcemap" class="type"><module.SourceMap></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Undefined_type" class="type"><undefined></a> Returns <code>module.SourceMap</code> if a source 11701cb0ef41Sopenharmony_cimap is found, <code>undefined</code> otherwise.</li> 11711cb0ef41Sopenharmony_ci</ul> 11721cb0ef41Sopenharmony_ci<p><code>path</code> is the resolved path for the file for which a corresponding source map 11731cb0ef41Sopenharmony_cishould be fetched.</p> 11741cb0ef41Sopenharmony_ci<h4>Class: <code>module.SourceMap</code><span><a class="mark" href="#class-modulesourcemap" id="class-modulesourcemap">#</a></span><a aria-hidden="true" class="legacy" id="module_class_module_sourcemap"></a></h4> 11751cb0ef41Sopenharmony_ci<div class="api_metadata"> 11761cb0ef41Sopenharmony_ci<span>Added in: v13.7.0, v12.17.0</span> 11771cb0ef41Sopenharmony_ci</div> 11781cb0ef41Sopenharmony_ci<h5><code>new SourceMap(payload)</code><span><a class="mark" href="#new-sourcemappayload" id="new-sourcemappayload">#</a></span><a aria-hidden="true" class="legacy" id="module_new_sourcemap_payload"></a></h5> 11791cb0ef41Sopenharmony_ci<ul> 11801cb0ef41Sopenharmony_ci<li><code>payload</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a></li> 11811cb0ef41Sopenharmony_ci</ul> 11821cb0ef41Sopenharmony_ci<p>Creates a new <code>sourceMap</code> instance.</p> 11831cb0ef41Sopenharmony_ci<p><code>payload</code> is an object with keys matching the <a href="https://sourcemaps.info/spec.html#h.mofvlxcwqzej">Source map v3 format</a>:</p> 11841cb0ef41Sopenharmony_ci<ul> 11851cb0ef41Sopenharmony_ci<li><code>file</code>: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li> 11861cb0ef41Sopenharmony_ci<li><code>version</code>: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a></li> 11871cb0ef41Sopenharmony_ci<li><code>sources</code>: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string[]></a></li> 11881cb0ef41Sopenharmony_ci<li><code>sourcesContent</code>: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string[]></a></li> 11891cb0ef41Sopenharmony_ci<li><code>names</code>: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string[]></a></li> 11901cb0ef41Sopenharmony_ci<li><code>mappings</code>: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li> 11911cb0ef41Sopenharmony_ci<li><code>sourceRoot</code>: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li> 11921cb0ef41Sopenharmony_ci</ul> 11931cb0ef41Sopenharmony_ci<h5><code>sourceMap.payload</code><span><a class="mark" href="#sourcemappayload" id="sourcemappayload">#</a></span><a aria-hidden="true" class="legacy" id="module_sourcemap_payload"></a></h5> 11941cb0ef41Sopenharmony_ci<ul> 11951cb0ef41Sopenharmony_ci<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a></li> 11961cb0ef41Sopenharmony_ci</ul> 11971cb0ef41Sopenharmony_ci<p>Getter for the payload used to construct the <a href="#class-modulesourcemap"><code>SourceMap</code></a> instance.</p> 11981cb0ef41Sopenharmony_ci<h5><code>sourceMap.findEntry(lineOffset, columnOffset)</code><span><a class="mark" href="#sourcemapfindentrylineoffset-columnoffset" id="sourcemapfindentrylineoffset-columnoffset">#</a></span><a aria-hidden="true" class="legacy" id="module_sourcemap_findentry_lineoffset_columnoffset"></a></h5> 11991cb0ef41Sopenharmony_ci<ul> 12001cb0ef41Sopenharmony_ci<li><code>lineOffset</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> The zero-indexed line number offset in 12011cb0ef41Sopenharmony_cithe generated source</li> 12021cb0ef41Sopenharmony_ci<li><code>columnOffset</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> The zero-indexed column number offset 12031cb0ef41Sopenharmony_ciin the generated source</li> 12041cb0ef41Sopenharmony_ci<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a></li> 12051cb0ef41Sopenharmony_ci</ul> 12061cb0ef41Sopenharmony_ci<p>Given a line offset and column offset in the generated source 12071cb0ef41Sopenharmony_cifile, returns an object representing the SourceMap range in the 12081cb0ef41Sopenharmony_cioriginal file if found, or an empty object if not.</p> 12091cb0ef41Sopenharmony_ci<p>The object returned contains the following keys:</p> 12101cb0ef41Sopenharmony_ci<ul> 12111cb0ef41Sopenharmony_ci<li>generatedLine: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> The line offset of the start of the 12121cb0ef41Sopenharmony_cirange in the generated source</li> 12131cb0ef41Sopenharmony_ci<li>generatedColumn: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> The column offset of start of the 12141cb0ef41Sopenharmony_cirange in the generated source</li> 12151cb0ef41Sopenharmony_ci<li>originalSource: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> The file name of the original source, 12161cb0ef41Sopenharmony_cias reported in the SourceMap</li> 12171cb0ef41Sopenharmony_ci<li>originalLine: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> The line offset of the start of the 12181cb0ef41Sopenharmony_cirange in the original source</li> 12191cb0ef41Sopenharmony_ci<li>originalColumn: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> The column offset of start of the 12201cb0ef41Sopenharmony_cirange in the original source</li> 12211cb0ef41Sopenharmony_ci<li>name: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li> 12221cb0ef41Sopenharmony_ci</ul> 12231cb0ef41Sopenharmony_ci<p>The returned value represents the raw range as it appears in the 12241cb0ef41Sopenharmony_ciSourceMap, based on zero-indexed offsets, <em>not</em> 1-indexed line and 12251cb0ef41Sopenharmony_cicolumn numbers as they appear in Error messages and CallSite 12261cb0ef41Sopenharmony_ciobjects.</p> 12271cb0ef41Sopenharmony_ci<p>To get the corresponding 1-indexed line and column numbers from a 12281cb0ef41Sopenharmony_cilineNumber and columnNumber as they are reported by Error stacks 12291cb0ef41Sopenharmony_ciand CallSite objects, use <code>sourceMap.findOrigin(lineNumber, columnNumber)</code></p> 12301cb0ef41Sopenharmony_ci<h5><code>sourceMap.findOrigin(lineNumber, columnNumber)</code><span><a class="mark" href="#sourcemapfindoriginlinenumber-columnnumber" id="sourcemapfindoriginlinenumber-columnnumber">#</a></span><a aria-hidden="true" class="legacy" id="module_sourcemap_findorigin_linenumber_columnnumber"></a></h5> 12311cb0ef41Sopenharmony_ci<ul> 12321cb0ef41Sopenharmony_ci<li><code>lineNumber</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> The 1-indexed line number of the call 12331cb0ef41Sopenharmony_cisite in the generated source</li> 12341cb0ef41Sopenharmony_ci<li><code>columnOffset</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> The 1-indexed column number 12351cb0ef41Sopenharmony_ciof the call site in the generated source</li> 12361cb0ef41Sopenharmony_ci<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a></li> 12371cb0ef41Sopenharmony_ci</ul> 12381cb0ef41Sopenharmony_ci<p>Given a 1-indexed lineNumber and columnNumber from a call site in 12391cb0ef41Sopenharmony_cithe generated source, find the corresponding call site location 12401cb0ef41Sopenharmony_ciin the original source.</p> 12411cb0ef41Sopenharmony_ci<p>If the lineNumber and columnNumber provided are not found in any 12421cb0ef41Sopenharmony_cisource map, then an empty object is returned. Otherwise, the 12431cb0ef41Sopenharmony_cireturned object contains the following keys:</p> 12441cb0ef41Sopenharmony_ci<ul> 12451cb0ef41Sopenharmony_ci<li>name: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Undefined_type" class="type"><undefined></a> The name of the range in the 12461cb0ef41Sopenharmony_cisource map, if one was provided</li> 12471cb0ef41Sopenharmony_ci<li>fileName: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> The file name of the original source, as 12481cb0ef41Sopenharmony_cireported in the SourceMap</li> 12491cb0ef41Sopenharmony_ci<li>lineNumber: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> The 1-indexed lineNumber of the 12501cb0ef41Sopenharmony_cicorresponding call site in the original source</li> 12511cb0ef41Sopenharmony_ci<li>columnNumber: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> The 1-indexed columnNumber of the 12521cb0ef41Sopenharmony_cicorresponding call site in the original source</li> 12531cb0ef41Sopenharmony_ci</ul></section> 12541cb0ef41Sopenharmony_ci <!-- API END --> 12551cb0ef41Sopenharmony_ci </div> 12561cb0ef41Sopenharmony_ci </div> 12571cb0ef41Sopenharmony_ci </div> 12581cb0ef41Sopenharmony_ci</body> 12591cb0ef41Sopenharmony_ci</html> 1260