Skip to content

Commit f3b08dd

Browse files
docs: document resolve() public API and rename params to parent/specifier (#611)
1 parent ce6fb1d commit f3b08dd

5 files changed

Lines changed: 235 additions & 150 deletions

File tree

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+
Rename the positional `resolve`/`resolveSync`/`resolvePromise` parameters to `parent`/`specifier` (from `path`/`request`) for ESM-aligned naming and document them in the README. Purely cosmetic — arguments are positional, so there is no behavior or API change.

‎README.md‎

Lines changed: 91 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -60,27 +60,105 @@ myResolve("/some/path/to/folder", "ts-module", (err, result) => {
6060

6161
All of the following are exposed from `require("enhanced-resolve")`.
6262

63-
#### `resolve(context?, path, request, resolveContext?, callback)`
63+
#### `resolve(context?, parent, specifier, resolveContext?, callback)`
6464

65-
Async Node-style resolver using the built-in defaults (`conditionNames: ["node"]`, `extensions: [".js", ".json", ".node"]`). `context` is optional; when omitted, a built-in Node context is used.
65+
Async Node-style resolver using the built-in defaults (`conditionNames: ["node"]`, `extensions: [".js", ".json", ".node"]`). Both `context` and `resolveContext` are optional, so the function accepts four shapes:
66+
67+
```js
68+
resolve(context, parent, specifier, resolveContext, callback);
69+
resolve(context, parent, specifier, callback);
70+
resolve(parent, specifier, resolveContext, callback);
71+
resolve(parent, specifier, callback); // most common
72+
```
73+
74+
The `parent` / `specifier` naming mirrors the ECMAScript resolution terms (as in `import.meta.resolve(specifier, parent)`): `parent` is the location you resolve **from**, and `specifier` is the string being resolved.
75+
76+
##### Arguments — what each one is and when to pass it
77+
78+
| Argument | Required | What it is | When to pass it |
79+
| ---------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
80+
| `context` | no | Extra info about _who_ is requesting, e.g. `{ environments: ["node+es3+es5+process+native"] }`. Plugins can read arbitrary keys off it. When omitted, a built-in Node context is used. | Pass it only when a plugin you use reads from it. Most callers omit it. |
81+
| `parent` | yes | The absolute directory to resolve **from** — the location the `specifier` is relative to (the ECMAScript "parent", historically called the "lookup start path"). | Always. |
82+
| `specifier` | yes | The string to resolve — a relative specifier (`./utils`), a bare module (`lodash/merge`), an alias, etc. (the ECMAScript "specifier", historically called the "request"). | Always. |
83+
| `resolveContext` | no | A collector object the resolver writes into / reads from: `fileDependencies`, `contextDependencies`, `missingDependencies` (`Set`s it fills in), `log` (a function it calls for trace output). | Pass it when you need to know which files/dirs were touched (e.g. to set up a watcher) or want a log of the resolution steps. |
84+
| `callback` | yes | `(err, result, resolveRequest) => void`. `result` is the resolved absolute path (or `false` if the request resolves to an ignored module). `resolveRequest` is the full request object with `path`, `query`, `fragment`, `descriptionFilePath`, etc. | Always. |
85+
86+
##### Minimal form — just `parent`, `specifier`, `callback`
6687

6788
```js
6889
const resolve = require("enhanced-resolve");
6990

7091
resolve(__dirname, "./utils", (err, result) => {
71-
// result === "/abs/path/to/utils.js"
92+
if (err) throw err;
93+
result; // === "/abs/path/to/utils.js"
94+
});
95+
```
96+
97+
##### Inspecting the full result via the third callback argument
98+
99+
```js
100+
resolve(__dirname, "./utils?query#frag", (err, result, resolveRequest) => {
101+
result; // === "/abs/path/to/utils.js?query#frag" — path with query/fragment appended
102+
resolveRequest.path; // === "/abs/path/to/utils.js" (the bare path, no query/fragment)
103+
resolveRequest.query; // === "?query" (empty string if the request has none)
104+
resolveRequest.fragment; // === "#frag" (empty string if the request has none)
105+
resolveRequest.descriptionFilePath; // path to the nearest package.json, if any
72106
});
73107
```
74108

75-
#### `resolve.sync(context?, path, request, resolveContext?) => string | false`
109+
##### With `resolveContext` — collect dependencies and a log
110+
111+
Pass a `resolveContext` when you need the resolver to report back _what it looked at_. The `Set`s you provide are filled in during resolution, and `log` is called with each step:
112+
113+
```js
114+
const fileDependencies = new Set();
115+
const missingDependencies = new Set();
116+
const contextDependencies = new Set();
117+
const logs = [];
118+
119+
resolve(
120+
__dirname,
121+
"./utils",
122+
{
123+
fileDependencies, // files that were read/checked
124+
missingDependencies, // paths that were probed but didn't exist
125+
contextDependencies, // directories that were read
126+
log: (msg) => logs.push(msg), // trace of each resolution step
127+
},
128+
(err, result) => {
129+
result; // === "/abs/path/to/utils.js"
130+
fileDependencies; // Set { ".../utils.js", ".../package.json", ... }
131+
missingDependencies; // Set { ".../utils", ".../utils.json", ... } (candidates tried)
132+
// `fileDependencies` / `missingDependencies` are exactly what you'd feed
133+
// a file watcher so a rebuild re-runs when any of them changes.
134+
},
135+
);
136+
```
137+
138+
##### With a custom `context`
139+
140+
Pass a `context` when a plugin reads from it. The default resolver only uses `environments`, but custom plugins may key off anything you put here:
141+
142+
```js
143+
resolve(
144+
{ environments: ["node+es3+es5+process+native"] }, // context
145+
__dirname,
146+
"./utils",
147+
(err, result) => {
148+
result; // === "/abs/path/to/utils.js"
149+
},
150+
);
151+
```
152+
153+
#### `resolve.sync(context?, parent, specifier, resolveContext?) => string | false`
76154

77155
Synchronous variant. Throws on failure, returns `false` when the resolve yields no result.
78156

79157
```js
80158
const file = resolve.sync(__dirname, "./utils");
81159
```
82160

83-
#### `resolve.promise(context?, path, request, resolveContext?) => Promise<string | false>`
161+
#### `resolve.promise(context?, parent, specifier, resolveContext?) => Promise<string | false>`
84162

85163
Promise variant of `resolve`.
86164

@@ -120,7 +198,7 @@ const file = await resolveTsPromise(__dirname, "./component");
120198

121199
#### `ResolverFactory.createResolver(options) => Resolver`
122200

123-
Lower-level factory. Returns a `Resolver` whose `resolve`, `resolveSync`, and `resolvePromise` methods accept `(context, path, request, resolveContext, [callback])`. Use this when you need a reusable resolver instance or access to its `hooks` (see the [Plugins](#plugins) section). `fileSystem` is required here — the high-level `resolve.create` defaults it for you.
201+
Lower-level factory. Returns a `Resolver` whose `resolve`, `resolveSync`, and `resolvePromise` methods accept `(context, parent, specifier, resolveContext, [callback])`. Use this when you need a reusable resolver instance or access to its `hooks` (see the [Plugins](#plugins) section). `fileSystem` is required here — the high-level `resolve.create` defaults it for you.
124202

125203
```js
126204
const fs = require("fs");
@@ -203,15 +281,15 @@ const myResolver = ResolverFactory.createResolver({
203281

204282
// resolve a file with the new resolver
205283
const context = {};
206-
const lookupStartPath = "/Users/webpack/some/root/dir";
207-
const request = "./path/to-look-up.js";
284+
const parent = "/Users/webpack/some/root/dir"; // directory to resolve from
285+
const specifier = "./path/to-look-up.js"; // string to resolve
208286
const resolveContext = {};
209287

210288
// callback
211289
myResolver.resolve(
212290
context,
213-
lookupStartPath,
214-
request,
291+
parent,
292+
specifier,
215293
resolveContext,
216294
(err /* Error */, filepath /* string */) => {
217295
// Do something with the path
@@ -222,8 +300,8 @@ myResolver.resolve(
222300
try {
223301
const filepath = await myResolver.resolvePromise(
224302
context,
225-
lookupStartPath,
226-
request,
303+
parent,
304+
specifier,
227305
resolveContext,
228306
);
229307
// Do something with the path
@@ -232,7 +310,7 @@ try {
232310
}
233311

234312
// sync (requires a sync fileSystem, e.g. the default Node.js one)
235-
const filepath = myResolver.resolveSync(context, lookupStartPath, request);
313+
const filepath = myResolver.resolveSync(context, parent, specifier);
236314
```
237315

238316
#### Resolver Options

‎lib/Resolver.js‎

Lines changed: 43 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -693,27 +693,27 @@ class Resolver {
693693

694694
/**
695695
* @overload
696-
* @param {string | URL} path context path or a `file:` URL instance
697-
* @param {string | URL} request request string or a `file:` URL instance
696+
* @param {string | URL} parent context path or a `file:` URL instance
697+
* @param {string | URL} specifier request string or a `file:` URL instance
698698
* @param {ResolveContext=} resolveContext resolve context
699699
* @returns {string | false} result
700700
*/
701701
/**
702702
* @overload
703703
* @param {Context} context context information object
704-
* @param {string | URL} path context path or a `file:` URL instance
705-
* @param {string | URL} request request string or a `file:` URL instance
704+
* @param {string | URL} parent context path or a `file:` URL instance
705+
* @param {string | URL} specifier request string or a `file:` URL instance
706706
* @param {ResolveContext=} resolveContext resolve context
707707
* @returns {string | false} result
708708
*/
709709
/**
710710
* @param {Context | string | URL} context context information object, or the context path (string or `file:` URL instance) when no context is provided
711-
* @param {string | URL | ResolveContext=} path context path (string or `file:` URL instance) or resolve context when no context is provided
712-
* @param {string | URL | ResolveContext=} request request string (or `file:` URL instance) or resolve context when no context is provided
711+
* @param {string | URL | ResolveContext=} parent context path (string or `file:` URL instance) or resolve context when no context is provided
712+
* @param {string | URL | ResolveContext=} specifier request string (or `file:` URL instance) or resolve context when no context is provided
713713
* @param {ResolveContext=} resolveContext resolve context
714714
* @returns {string | false} result
715715
*/
716-
resolveSync(context, path, request, resolveContext) {
716+
resolveSync(context, parent, specifier, resolveContext) {
717717
/** @type {Error | null | undefined} */
718718
let err;
719719
/** @type {string | false | undefined} */
@@ -724,8 +724,8 @@ class Resolver {
724724
// caller supplied a resolveContext.
725725
this.resolve(
726726
/** @type {Context} */ (context),
727-
/** @type {string} */ (path),
728-
/** @type {string} */ (request),
727+
/** @type {string} */ (parent),
728+
/** @type {string} */ (specifier),
729729
/** @type {ResolveContext} */ (resolveContext) || {},
730730
(_err, r) => {
731731
err = _err;
@@ -745,79 +745,79 @@ class Resolver {
745745

746746
/**
747747
* @overload
748-
* @param {string | URL} path context path or a `file:` URL instance
749-
* @param {string | URL} request request string or a `file:` URL instance
748+
* @param {string | URL} parent context path or a `file:` URL instance
749+
* @param {string | URL} specifier request string or a `file:` URL instance
750750
* @param {ResolveContext=} resolveContext resolve context
751751
* @returns {Promise<string | false>} result
752752
*/
753753
/**
754754
* @overload
755755
* @param {Context} context context information object
756-
* @param {string | URL} path context path or a `file:` URL instance
757-
* @param {string | URL} request request string or a `file:` URL instance
756+
* @param {string | URL} parent context path or a `file:` URL instance
757+
* @param {string | URL} specifier request string or a `file:` URL instance
758758
* @param {ResolveContext=} resolveContext resolve context
759759
* @returns {Promise<string | false>} result
760760
*/
761761
/**
762762
* @param {Context | string | URL} context context information object, or the context path (string or `file:` URL instance) when no context is provided
763-
* @param {string | URL | ResolveContext=} path context path (string or `file:` URL instance) or resolve context when no context is provided
764-
* @param {string | URL | ResolveContext=} request request string (or `file:` URL instance) or resolve context when no context is provided
763+
* @param {string | URL | ResolveContext=} parent context path (string or `file:` URL instance) or resolve context when no context is provided
764+
* @param {string | URL | ResolveContext=} specifier request string (or `file:` URL instance) or resolve context when no context is provided
765765
* @param {ResolveContext=} resolveContext resolve context
766766
* @returns {Promise<string | false>} result
767767
*/
768-
resolvePromise(context, path, request, resolveContext) {
768+
resolvePromise(context, parent, specifier, resolveContext) {
769769
// `|| {}` ensures the 5-arg fast path inside `resolve()` is reached
770770
// even when the caller doesn't pass a resolveContext.
771771
return _withResolvers(
772772
this,
773773
/** @type {Context} */ (context),
774-
/** @type {string} */ (path),
775-
/** @type {string} */ (request),
774+
/** @type {string} */ (parent),
775+
/** @type {string} */ (specifier),
776776
/** @type {ResolveContext} */ (resolveContext) || {},
777777
);
778778
}
779779

780780
/**
781781
* @overload
782-
* @param {string | URL} path context path or a `file:` URL instance
783-
* @param {string | URL} request request string or a `file:` URL instance
782+
* @param {string | URL} parent context path or a `file:` URL instance
783+
* @param {string | URL} specifier request string or a `file:` URL instance
784784
* @param {ResolveCallback} callback callback function
785785
* @returns {void}
786786
*/
787787
/**
788788
* @overload
789-
* @param {string | URL} path context path or a `file:` URL instance
790-
* @param {string | URL} request request string or a `file:` URL instance
789+
* @param {string | URL} parent context path or a `file:` URL instance
790+
* @param {string | URL} specifier request string or a `file:` URL instance
791791
* @param {ResolveContext} resolveContext resolve context
792792
* @param {ResolveCallback} callback callback function
793793
* @returns {void}
794794
*/
795795
/**
796796
* @overload
797797
* @param {Context} context context information object
798-
* @param {string | URL} path context path or a `file:` URL instance
799-
* @param {string | URL} request request string or a `file:` URL instance
798+
* @param {string | URL} parent context path or a `file:` URL instance
799+
* @param {string | URL} specifier request string or a `file:` URL instance
800800
* @param {ResolveCallback} callback callback function
801801
* @returns {void}
802802
*/
803803
/**
804804
* @overload
805805
* @param {Context} context context information object
806-
* @param {string | URL} path context path or a `file:` URL instance
807-
* @param {string | URL} request request string or a `file:` URL instance
806+
* @param {string | URL} parent context path or a `file:` URL instance
807+
* @param {string | URL} specifier request string or a `file:` URL instance
808808
* @param {ResolveContext} resolveContext resolve context
809809
* @param {ResolveCallback} callback callback function
810810
* @returns {void}
811811
*/
812812
/**
813813
* @param {Context | string | URL} context context information object, or the context path (string or `file:` URL instance) when no context is provided
814-
* @param {string | URL | ResolveContext | ResolveCallback=} path context path (string or `file:` URL instance) or (when no context) resolve context or callback
815-
* @param {string | URL | ResolveContext | ResolveCallback=} request request string (or `file:` URL instance) or (when no context) resolve context or callback
814+
* @param {string | URL | ResolveContext | ResolveCallback=} parent context path (string or `file:` URL instance) or (when no context) resolve context or callback
815+
* @param {string | URL | ResolveContext | ResolveCallback=} specifier request string (or `file:` URL instance) or (when no context) resolve context or callback
816816
* @param {ResolveContext | ResolveCallback=} resolveContext resolve context or callback when no resolve context is provided
817817
* @param {ResolveCallback=} callback callback function
818818
* @returns {void}
819819
*/
820-
resolve(context, path, request, resolveContext, callback) {
820+
resolve(context, parent, specifier, resolveContext, callback) {
821821
// Fast path for the common 5-arg call (`resolver.resolve(ctx, from,
822822
// req, resolveCtx, cb)`) — every call from `resolveSync` /
823823
// `resolvePromise` plus the vast majority of direct API callers.
@@ -836,7 +836,7 @@ class Resolver {
836836
// proceed straight to per-arg validation below
837837
} else {
838838
// Slow path: shift positional args based on what was supplied.
839-
// Shift when context is omitted (first positional arg is the path,
839+
// Shift when context is omitted (first positional arg is the parent,
840840
// either a string or a `file:` URL instance).
841841
if (typeof context === "string" || context instanceof URL) {
842842
// Keep an already-supplied callback (resolveSync / resolvePromise
@@ -847,9 +847,11 @@ class Resolver {
847847
);
848848
}
849849
resolveContext =
850-
/** @type {ResolveContext | ResolveCallback | undefined} */ (request);
851-
request = /** @type {string} */ (path);
852-
path = context;
850+
/** @type {ResolveContext | ResolveCallback | undefined} */ (
851+
specifier
852+
);
853+
specifier = /** @type {string} */ (parent);
854+
parent = context;
853855
context = {};
854856
}
855857
// 4-arg form: the resolveContext slot holds the callback.
@@ -866,24 +868,24 @@ class Resolver {
866868
context = {};
867869
}
868870
}
869-
// Accept `file:` URL instances for path/request, converting to a
871+
// Accept `file:` URL instances for parent/specifier, converting to a
870872
// filesystem path (mirrors the URL support in resolve options). The
871873
// `instanceof` check sits on the error branch, so the common string
872874
// case keeps its single `typeof` check on this hot path.
873-
if (typeof path !== "string") {
874-
if (path instanceof URL) path = toPath(path);
875+
if (typeof parent !== "string") {
876+
if (parent instanceof URL) parent = toPath(parent);
875877
else return callback(new Error("path argument is not a string"));
876878
}
877-
if (typeof request !== "string") {
878-
if (request instanceof URL) request = toPath(request);
879+
if (typeof specifier !== "string") {
880+
if (specifier instanceof URL) specifier = toPath(specifier);
879881
else return callback(new Error("request argument is not a string"));
880882
}
881883

882884
/** @type {ResolveRequest} */
883885
const obj = {
884886
context,
885-
path,
886-
request,
887+
path: parent,
888+
request: specifier,
887889
};
888890

889891
/** @type {ResolveContextYield | undefined} */
@@ -912,7 +914,7 @@ class Resolver {
912914
};
913915
}
914916

915-
const message = `resolve '${request}' in '${path}'`;
917+
const message = `resolve '${specifier}' in '${parent}'`;
916918

917919
/**
918920
* @param {ResolveRequest} result result

0 commit comments

Comments
 (0)