Skip to content

Commit ac7d7c5

Browse files
feat: make the resolver runtime-agnostic (browser/deno/bun) (#606)
1 parent f3b08dd commit ac7d7c5

35 files changed

Lines changed: 2254 additions & 213 deletions

‎.changeset/platform-agnostic.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
"enhanced-resolve": patch
3+
---
4+
5+
Make the resolver runtime-agnostic so it works in browsers, Deno and Bun as well as Node. File contents are decoded without assuming a Node `Buffer`, and browser shims are provided for the `path`, `url` and `graceful-fs` builtins (Node, Deno and Bun keep using the native ones) so the package bundles for the browser — supply your own `fileSystem` there.

‎.cspell.json‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -50,7 +50,8 @@
5050
"readlink",
5151
"extensionless",
5252
"ENOENT",
53-
"hardlinks"
53+
"hardlinks",
54+
"denoland"
5455
],
5556
"ignorePaths": [
5657
"package.json",
Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
name: Cross-runtime
2+
3+
on:
4+
push:
5+
branches: [main]
6+
pull_request:
7+
branches: [main]
8+
9+
permissions:
10+
contents: read
11+
12+
# Runs the real test suite on non-Node runtimes. Bun uses its built-in
13+
# jest-compatible runner; Deno runs the actual jest via its Node compatibility.
14+
# The browser job bundles the core resolver for the browser and runs it both in
15+
# a web-globals sandbox and in real headless Chromium (the Node-based jest suite
16+
# cannot run in a browser).
17+
jobs:
18+
bun:
19+
runs-on: ubuntu-latest
20+
steps:
21+
- uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
22+
23+
- name: Use Bun
24+
uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0
25+
with:
26+
bun-version: latest
27+
28+
- name: Install dependencies
29+
run: bun install
30+
env:
31+
HUSKY: "0"
32+
33+
- name: Run tests
34+
run: bun test test/
35+
36+
deno:
37+
runs-on: ubuntu-latest
38+
steps:
39+
- uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
40+
41+
- name: Use Node.js
42+
uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
43+
with:
44+
node-version: lts/*
45+
cache: npm
46+
47+
- name: Install dependencies
48+
run: npm ci
49+
env:
50+
HUSKY: "0"
51+
52+
- name: Use Deno
53+
uses: denoland/setup-deno@667a34cdef165d8d2b2e98dde39547c9daac7282 # v2.0.4
54+
with:
55+
deno-version: v2.x
56+
57+
- name: Run tests (jest via Deno node compatibility)
58+
run: deno run -A --node-modules-dir=auto node_modules/jest/bin/jest.js
59+
60+
browser:
61+
runs-on: ubuntu-latest
62+
steps:
63+
- uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
64+
65+
- name: Use Node.js
66+
uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
67+
with:
68+
node-version: lts/*
69+
cache: npm
70+
71+
- name: Install dependencies
72+
run: npm ci
73+
env:
74+
HUSKY: "0"
75+
76+
# webpack bundles the core resolver for the browser as an ES module
77+
# (experiments.outputModule), resolving the browser field and failing on
78+
# any Node builtin that is not shimmed. First run it in a web-globals-only
79+
# sandbox (fast, deterministic), then in real headless Chromium.
80+
- name: Verify browser bundle in a web-globals sandbox
81+
run: npm run test:browser
82+
83+
- name: Install Playwright Chromium
84+
run: |
85+
npm install --no-save playwright
86+
npx playwright install --with-deps chromium
87+
88+
- name: Run resolver in headless Chromium
89+
run: node test/smoke/browser-playwright.cjs

‎eslint.config.mjs‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,4 +22,14 @@ export default defineConfig([
2222
"n/no-process-exit": "off",
2323
},
2424
},
25+
{
26+
// Cross-runtime smoke scripts run standalone on node/bun/deno and in a
27+
// browser sandbox; relax the library-grade JSDoc typing rules for them.
28+
files: ["test/smoke/**/*"],
29+
rules: {
30+
"jsdoc/no-restricted-syntax": "off",
31+
"jsdoc/reject-any-type": "off",
32+
"unicorn/prefer-native-coercion-functions": "off",
33+
},
34+
},
2535
]);

‎jest.config.js‎

Lines changed: 1 addition & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,6 @@
11
"use strict";
22

33
module.exports = {
4-
prettierPath: require.resolve("prettier-2"),
54
moduleFileExtensions: ["js", "mjs", "cjs", "ts"],
6-
snapshotFormat: {
7-
escapeString: true,
8-
printBasicPrototype: true,
9-
},
5+
setupFiles: ["<rootDir>/test/polyfill-text-encoding.js"],
106
};

‎lib/DescriptionFileUtils.js‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@
66
"use strict";
77

88
const forEachBail = require("./forEachBail");
9+
const { decodeText } = require("./util/fs");
910

1011
/** @typedef {import("./Resolver")} Resolver */
1112
/** @typedef {import("./Resolver").JsonObject} JsonObject */
@@ -160,7 +161,7 @@ function loadDescriptionFile(
160161

161162
if (content) {
162163
try {
163-
json = JSON.parse(content.toString());
164+
json = JSON.parse(decodeText(content));
164165
} catch (/** @type {unknown} */ err_) {
165166
return onJson(/** @type {Error} */ (err_));
166167
}

‎lib/index.js‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -165,8 +165,8 @@ const resolvePromise =
165165
*/
166166
function create(options) {
167167
const resolver = getResolverFactory().createResolver({
168-
fileSystem: getNodeFileSystem(),
169168
...options,
169+
fileSystem: options.fileSystem || getNodeFileSystem(),
170170
});
171171
/**
172172
* @param {object | string | URL} context Custom context
@@ -203,8 +203,8 @@ function create(options) {
203203
function createSync(options) {
204204
const resolver = getResolverFactory().createResolver({
205205
useSyncFileSystemCalls: true,
206-
fileSystem: getNodeFileSystem(),
207206
...options,
207+
fileSystem: options.fileSystem || getNodeFileSystem(),
208208
});
209209
/**
210210
* @param {object | string | URL} context custom context
@@ -235,8 +235,8 @@ function createSync(options) {
235235
*/
236236
function createPromise(options) {
237237
const resolver = getResolverFactory().createResolver({
238-
fileSystem: getNodeFileSystem(),
239238
...options,
239+
fileSystem: options.fileSystem || getNodeFileSystem(),
240240
});
241241
/**
242242
* @param {object | string | URL} context Custom context

‎lib/util/fileURLToPath.js‎

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
/*
2+
MIT License http://www.opensource.org/licenses/mit-license.php
3+
*/
4+
5+
"use strict";
6+
7+
// A runtime-agnostic port of Node's `url.fileURLToPath`, built on the global
8+
// `URL` (available in Node, browsers, Deno and Bun) so the resolver does not
9+
// depend on the Node `url` builtin. The platform branch can be forced via the
10+
// `windows` option; otherwise it follows the host platform like Node does.
11+
12+
const CHAR_LOWERCASE_A = 97;
13+
const CHAR_LOWERCASE_Z = 122;
14+
15+
const isWindows =
16+
typeof process !== "undefined" && process.platform === "win32";
17+
18+
const forwardSlashRegEx = /\//g;
19+
20+
/**
21+
* @param {URL} url file: URL instance
22+
* @returns {string} Windows filesystem path
23+
*/
24+
function getPathFromURLWin32(url) {
25+
const { hostname } = url;
26+
let { pathname } = url;
27+
for (let n = 0; n < pathname.length; n++) {
28+
if (pathname[n] === "%") {
29+
const third = (pathname.codePointAt(n + 2) || 0) | 0x20;
30+
if (
31+
(pathname[n + 1] === "2" && third === 102) || // 2f 2F (/)
32+
(pathname[n + 1] === "5" && third === 99) // 5c 5C (\)
33+
) {
34+
throw new TypeError(
35+
"File URL path must not include encoded \\ or / characters",
36+
);
37+
}
38+
}
39+
}
40+
pathname = pathname.replace(forwardSlashRegEx, "\\");
41+
pathname = decodeURIComponent(pathname);
42+
if (hostname !== "") {
43+
// UNC path: `\\host\share\…`. Node runs the host through
44+
// `domainToUnicode`; we keep the (already punycode) hostname as-is,
45+
// which is identical for ASCII hosts and only differs for rare IDN UNC.
46+
return `\\\\${hostname}${pathname}`;
47+
}
48+
const letter = (pathname.codePointAt(1) || 0) | 0x20;
49+
const sep = pathname.charAt(2);
50+
if (letter < CHAR_LOWERCASE_A || letter > CHAR_LOWERCASE_Z || sep !== ":") {
51+
throw new TypeError("File URL path must be absolute");
52+
}
53+
return pathname.slice(1);
54+
}
55+
56+
/**
57+
* @param {URL} url file: URL instance
58+
* @returns {string} POSIX filesystem path
59+
*/
60+
function getPathFromURLPosix(url) {
61+
if (url.hostname !== "") {
62+
throw new TypeError('File URL host must be "localhost" or empty');
63+
}
64+
const { pathname } = url;
65+
for (let n = 0; n < pathname.length; n++) {
66+
if (pathname[n] === "%") {
67+
const third = (pathname.codePointAt(n + 2) || 0) | 0x20;
68+
if (pathname[n + 1] === "2" && third === 102) {
69+
throw new TypeError(
70+
"File URL path must not include encoded / characters",
71+
);
72+
}
73+
}
74+
}
75+
return decodeURIComponent(pathname);
76+
}
77+
78+
/**
79+
* @param {string | URL} path a `file:` URL string or `URL` instance
80+
* @param {{ windows?: boolean }=} options force the platform branch
81+
* @returns {string} the filesystem path
82+
*/
83+
function fileURLToPath(path, options) {
84+
const url = typeof path === "string" ? new URL(path) : path;
85+
if (url.protocol !== "file:") {
86+
throw new TypeError("The URL must be of scheme file");
87+
}
88+
const windows =
89+
options && options.windows !== undefined ? options.windows : isWindows;
90+
return windows ? getPathFromURLWin32(url) : getPathFromURLPosix(url);
91+
}
92+
93+
module.exports = fileURLToPath;

‎lib/util/fs.js‎

Lines changed: 36 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@
55

66
"use strict";
77

8+
const memoize = require("./memoize");
89
const stripJsonComments = require("./strip-json-comments");
910

1011
/** @typedef {import("../Resolver").FileSystem} FileSystem */
@@ -15,9 +16,33 @@ const stripJsonComments = require("./strip-json-comments");
1516
* @property {boolean=} stripComments Whether to strip JSONC comments
1617
*/
1718

18-
/** @type {WeakMap<Buffer, JsonObject>} */
19+
/** @type {WeakMap<Buffer | Uint8Array, JsonObject>} */
1920
const _stripCommentsCache = new WeakMap();
2021

22+
// Only constructed for non-Buffer input: on Node the `Buffer.isBuffer` branch
23+
// in `decodeText` handles decoding, so the global `TextDecoder` (Node 11+,
24+
// always present in browsers/Deno/Bun) is only reached off the Buffer path.
25+
// `ignoreBOM: true` keeps a leading BOM in the output, matching
26+
// `Buffer.toString("utf8")` so both decode paths behave identically.
27+
// eslint-disable-next-line n/no-unsupported-features/node-builtins
28+
const getDecoder = memoize(() => new TextDecoder("utf-8", { ignoreBOM: true }));
29+
30+
/**
31+
* Decode a file's raw contents to text without assuming a Node runtime. A
32+
* `Buffer` (Node) uses its fast native `toString`; any other binary input
33+
* (`Uint8Array` from a browser/Deno/Bun file system) goes through
34+
* `TextDecoder`, and strings are returned as-is.
35+
* @param {string | Buffer | Uint8Array} data raw file contents
36+
* @returns {string} decoded text
37+
*/
38+
const decodeText = (data) => {
39+
if (typeof data === "string") return data;
40+
if (typeof Buffer !== "undefined" && Buffer.isBuffer(data)) {
41+
return data.toString("utf8");
42+
}
43+
return getDecoder().decode(data);
44+
};
45+
2146
/**
2247
* Read and parse JSON file (supports JSONC with comments).
2348
* Callback-based so a synchronous `fileSystem` stays synchronous all the
@@ -43,16 +68,21 @@ function readJson(fileSystem, jsonFilePath, options, callback) {
4368

4469
fileSystem.readFile(jsonFilePath, (err, data) => {
4570
if (err) return callback(err);
46-
const buf = /** @type {Buffer} */ (data);
71+
const buf = /** @type {Buffer | Uint8Array | string} */ (data);
72+
73+
// The strip-comments cache is keyed by the file-contents object; a file
74+
// system may hand back a plain string, which cannot be a WeakMap key, so
75+
// only cache when the contents are an object.
76+
const cacheable = stripComments && typeof buf === "object";
4777

48-
if (stripComments) {
78+
if (cacheable) {
4979
const cached = _stripCommentsCache.get(buf);
5080
if (cached !== undefined) return callback(null, cached);
5181
}
5282

5383
let result;
5484
try {
55-
const jsonText = buf.toString();
85+
const jsonText = decodeText(buf);
5686
const jsonWithoutComments = stripComments
5787
? stripJsonComments(jsonText, {
5888
trailingCommas: true,
@@ -64,12 +94,13 @@ function readJson(fileSystem, jsonFilePath, options, callback) {
6494
return callback(/** @type {Error} */ (parseErr));
6595
}
6696

67-
if (stripComments) {
97+
if (cacheable) {
6898
_stripCommentsCache.set(buf, result);
6999
}
70100

71101
callback(null, result);
72102
});
73103
}
74104

105+
module.exports.decodeText = decodeText;
75106
module.exports.readJson = readJson;

‎lib/util/graceful-fs-browser.js‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
/*
2+
MIT License http://www.opensource.org/licenses/mit-license.php
3+
*/
4+
5+
"use strict";
6+
7+
// Browser stub for the default `graceful-fs` file system. A browser has no
8+
// ambient file system, so the convenience entry's default resolver has nothing
9+
// to read — pass your own `fileSystem` to `create()` /
10+
// `ResolverFactory.createResolver()` instead. Each method throws a clear error
11+
// if the default is actually used, while keeping the package able to bundle for
12+
// the browser (no Node `fs` dependency is pulled in).
13+
14+
const message =
15+
"enhanced-resolve: no default file system is available in the browser. " +
16+
"Pass a `fileSystem` to `create()` or `ResolverFactory.createResolver()`.";
17+
18+
/**
19+
* @returns {never} always throws
20+
*/
21+
const unavailable = () => {
22+
throw new Error(message);
23+
};
24+
25+
// The same set of methods `CachedInputFileSystem` reads from the file system
26+
// (graceful-fs has no `readJson`/`readJsonSync`, so those stay undefined).
27+
module.exports = {
28+
lstat: unavailable,
29+
lstatSync: unavailable,
30+
readFile: unavailable,
31+
readFileSync: unavailable,
32+
readdir: unavailable,
33+
readdirSync: unavailable,
34+
readlink: unavailable,
35+
readlinkSync: unavailable,
36+
realpath: unavailable,
37+
realpathSync: unavailable,
38+
stat: unavailable,
39+
statSync: unavailable,
40+
};

0 commit comments

Comments
 (0)