From 043d9c3e5186e8dd52061c6527b7efd6a3497461 Mon Sep 17 00:00:00 2001 From: Jonas Kello Date: Tue, 21 Sep 2021 23:52:53 +0200 Subject: [PATCH 01/13] Add doc --- doc/design-resolve-reuse.md | 97 +++++++++++++++++++++++++++++++++++++ 1 file changed, 97 insertions(+) create mode 100644 doc/design-resolve-reuse.md diff --git a/doc/design-resolve-reuse.md b/doc/design-resolve-reuse.md new file mode 100644 index 0000000..4cd02b7 --- /dev/null +++ b/doc/design-resolve-reuse.md @@ -0,0 +1,97 @@ +# Re-use of node's esm resolve algorithm + +Some loaders want to run basically the same algorithm that node is doing by default (`defaultResolve`) but with a few tweaks. For example these loaders would benefit from re-use of `defaultResolve`: + +- Yarn PnP loader that read files from compressed archives instead of the file system +- Typescript loader that translate the path to .ts/.tsx files + +In many cases it comes down to just altering how filsystem access is handled. For Yarn PnP it would just want to change where files are read, but the resolution algorithm would be the same as the default. + +Typescript files import from the future output so the imported file may not exist but need to be mapped back to the source file which potentially is in another directory (eg. if using project references and yarn workspaces). + +In other cases where larger alterations of the algorithm is desired it still might be useful to call into parts of the default algorithm(?). + +# Analysis of current file system access in defaultResolve + +The default resolve algorithm is implemented in [resolve.js](https://github.com/nodejs/node/blob/master/lib/internal/modules/esm/resolve.js). + +It uses filesystem by direct imports of `realpathSync` and `statSync` and also indirectly by import of `packageJsonReader`. + +`realpathSync` is only called from the top-level function `defaultResolve`. + +The following tree shows where `statSync` and `packageJsonReader.read` are called. It's not going all the way to the top of `defaultResolve` function but stopping at functions `packageResolve`, `finalizeResolution` and `moduleResolve`. + +- statSync + + - tryStatSync + - finalizeResolution + - packageResolve + - fileExists + - legacyMainResolve + - packageResolve + - resolveExtensionsWithTryExactName + - resolveDirectoryEntry + - finalizeResolution + - finalizeResolution + - resolveExtensions + - resolveExtensionsWithTryExactName + - resolveDirectoryEntry + - finalizeResolution + - finalizeResolution + - resolveDirectoryEntry + - finalizeResolution + - resolveDirectoryEntry + - finalizeResolution + +- packageJsonReader.read + + - getPackageConfig + + - getPackageScopeConfig + - packageImportsResolve + - moduleResolve + - defaultResolve + - getPackageType (not called within resolve.js) + - packageResolve + - packageResolve + + - resolveDirectoryEntry + - finalizeResolution + +The analysis shows that filesystem access occurs mainly as an effect of calls to `packageResolve`, `finalizeResolution`, and `moduleResolve`. + +`moduleResolve` is only called by the top-level `defaultResolve` function. +`finalizeResolution` is only called from `moduleResolve`. + +`packageResolve` is called in multiple places, it is also called recursively: + +- packageResolve + + - resolvePackageTargetString + + - resolvePackageTarget + - resolvePackageTarget (recursive) + - packageExportsResolve + - packageResolve (recursive) + - packageImportsResolve + - moduleResolve + - defaultResolve + + - moduleResolve + - defaultResolve + +# Stragegies for re-use of defaultResolve + +## Filesystem hooks + +Using this strategy, the loader would provide hooks for filesystem calls, specifically hooks corresponding to `realpathSync`, `statSync` and `packageJsonReader.read`. + +## Utility functions + +This strategy would export utility functions so a custom loader could pick which parts of the default algorithm's logic it wants to call. If utility functions are exported, they probably should not do any filesystem access or throw exceptions (but instead return a value indicating success/fail). + +Specifically we could refactor `resolve.js` so that `packageExportsResolve` and `packageImportsResolve` are exported and take a custom `packageResolve` function instead of calling the internal one. The loader could then call `packageExportsResolve` and `packageImportsResolve` as utility functions while providing its own `packageResolve` so it can control filesystem access. + +If the loader should provide its own `packageResolve` it could be useful to break out some parts of the default implementation. Eg. the part that finds package.json by ascending the file system and the part that checks for self resolve within the current package. The self-resolve part does not do any filesystem access so it could perhaps be moved so it does not have to be part of the `packageResolve` that the loader provides. + +Using this strategy the utility functions exported would be free of filesystem side-effects and the loader would do any such effects needed itself. So this would be akin to a [functional-core-imperative-shell](https://www.destroyallsoftware.com/screencasts/catalog/functional-core-imperative-shell) stratgegy. Altough the utility functions would be "pure" only in the sense that they do no filesystem side-effects or throw exceptions. Altough the utility functions cannot be made 100% pure, they probably could be made idempotent. From 07293fc7d2f6f768b2bdfdd3d9e70622852b37ba Mon Sep 17 00:00:00 2001 From: Jonas Kello Date: Sat, 23 Oct 2021 19:34:55 +0200 Subject: [PATCH 02/13] Update doc/design-resolve-reuse.md Co-authored-by: Jacob Smith <3012099+JakobJingleheimer@users.noreply.github.com> --- doc/design-resolve-reuse.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/design-resolve-reuse.md b/doc/design-resolve-reuse.md index 4cd02b7..d44b0c9 100644 --- a/doc/design-resolve-reuse.md +++ b/doc/design-resolve-reuse.md @@ -94,4 +94,4 @@ Specifically we could refactor `resolve.js` so that `packageExportsResolve` and If the loader should provide its own `packageResolve` it could be useful to break out some parts of the default implementation. Eg. the part that finds package.json by ascending the file system and the part that checks for self resolve within the current package. The self-resolve part does not do any filesystem access so it could perhaps be moved so it does not have to be part of the `packageResolve` that the loader provides. -Using this strategy the utility functions exported would be free of filesystem side-effects and the loader would do any such effects needed itself. So this would be akin to a [functional-core-imperative-shell](https://www.destroyallsoftware.com/screencasts/catalog/functional-core-imperative-shell) stratgegy. Altough the utility functions would be "pure" only in the sense that they do no filesystem side-effects or throw exceptions. Altough the utility functions cannot be made 100% pure, they probably could be made idempotent. +Using this strategy the utility functions exported would be free of filesystem side-effects and the loader would do any such effects needed itself. So this would be akin to a [functional-core-imperative-shell](https://www.destroyallsoftware.com/screencasts/catalog/functional-core-imperative-shell) stratgegy. Altough the utility functions would be "pure" only in the sense that they do no filesystem side-effects or throw exceptions. Although the utility functions cannot be made 100% pure, they probably could be made idempotent. From dd62c6b2c942c0358810cf0474736b645568427d Mon Sep 17 00:00:00 2001 From: Jonas Kello Date: Sun, 24 Oct 2021 11:08:19 +0200 Subject: [PATCH 03/13] Add example API --- doc/design-resolve-reuse.md | 99 +++++++++++++++++++++++++++++++++++++ 1 file changed, 99 insertions(+) diff --git a/doc/design-resolve-reuse.md b/doc/design-resolve-reuse.md index d44b0c9..2313e58 100644 --- a/doc/design-resolve-reuse.md +++ b/doc/design-resolve-reuse.md @@ -95,3 +95,102 @@ Specifically we could refactor `resolve.js` so that `packageExportsResolve` and If the loader should provide its own `packageResolve` it could be useful to break out some parts of the default implementation. Eg. the part that finds package.json by ascending the file system and the part that checks for self resolve within the current package. The self-resolve part does not do any filesystem access so it could perhaps be moved so it does not have to be part of the `packageResolve` that the loader provides. Using this strategy the utility functions exported would be free of filesystem side-effects and the loader would do any such effects needed itself. So this would be akin to a [functional-core-imperative-shell](https://www.destroyallsoftware.com/screencasts/catalog/functional-core-imperative-shell) stratgegy. Altough the utility functions would be "pure" only in the sense that they do no filesystem side-effects or throw exceptions. Although the utility functions cannot be made 100% pure, they probably could be made idempotent. + +### Utility functions API + +Here is an example of how the utility API could look like. It is written in typescript notation to make the types of parameters clear. The design of this API is mainly an effect of refactoring the existing functions and may have looked different if designed from scratch. + +The main functions are `packageExportsResolve` and `packageImportsResolve`. Both these function make use of a function of type `PackageResolve` that is provided by the calling application. The `PackageResolve` function is also the main function to start the resolve, and then it calls into the utility functions which may call back into the `PackageResolve` function. This is becuase of the recursive nature of the resolve, eg. an export/import can be a package name that has to be resolved. + +```ts +/** + * This needs to be implemented by the caller + */ +type PackageResolve = ( + specifier: string, + base: string | URL | undefined, + conditions: ReadonlySet, + isDirectory: IsDirectory, + readFile: ReadFile +) => ReadonlyArray; + +export type IsDirectory = (path: string) => boolean; +export type ReadFile = (filename: string) => string | undefined; + +/** + * Relevant parts of package.json + */ +type PackageConfig = { + readonly pjsonPath: string; + readonly exists: boolean; + readonly main: string | undefined; + readonly name: string | undefined; + readonly type: string; + readonly exports: unknown | undefined; + readonly imports: unknown | undefined; +}; + +export function packageExportsResolve( + packageResolve: PackageResolve, + packageJSONUrl: URL, + packageSubpath: string, + packageConfig: PackageConfig, + base: string | URL | undefined, + conditions: ReadonlySet +): { readonly resolved: URL; readonly exact: boolean }; + +export function packageImportsResolve( + packageResolve: PackageResolve, + name: string, + base: string | undefined, + conditions: ReadonlySet, + readFile: ReadFile +): { readonly resolved: URL; readonly exact: boolean }; + +export function getPackageConfig( + readFile: ReadFile, + path: string, + specifier: string, + base: string | URL | undefined +): PackageConfig; + +export function getConditionsSet( + conditions: ReadonlyArray +): ReadonlySet; + +export function shouldBeTreatedAsRelativeOrAbsolutePath( + specifier: string +): boolean { + return ru.shouldBeTreatedAsRelativeOrAbsolutePath(specifier); +} + +export function parsePackageName( + specifier: string, + base: string | URL | undefined +): { + readonly packageName: string; + readonly packageSubpath: string; + readonly isScoped: boolean; +}; + +export function legacyMainResolve( + packageJSONUrl: string | URL, + packageConfig: PackageConfig +): ReadonlyArray; + +export function resolveSelf( + packageResolve: PackageResolve, + base: string | URL | undefined, + packageName: string, + packageSubpath: string, + conditions: ReadonlySet, + readFile: ReadFile +): URL; + +export function findPackageJson( + packageName: string, + base: string | URL | undefined, + isScoped: boolean, + isDirectory: IsDirectory +): readonly [packageJSONUrl: URL, packageJSONPath: string] | undefined; +``` From 3cee3ea3f220a431283be6746157c83067827cb4 Mon Sep 17 00:00:00 2001 From: Jonas Kello Date: Sun, 24 Oct 2021 12:29:54 +0200 Subject: [PATCH 04/13] Remove impl code left in by mistake --- doc/design-resolve-reuse.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/doc/design-resolve-reuse.md b/doc/design-resolve-reuse.md index 2313e58..823c6c0 100644 --- a/doc/design-resolve-reuse.md +++ b/doc/design-resolve-reuse.md @@ -160,9 +160,7 @@ export function getConditionsSet( export function shouldBeTreatedAsRelativeOrAbsolutePath( specifier: string -): boolean { - return ru.shouldBeTreatedAsRelativeOrAbsolutePath(specifier); -} +): boolean; export function parsePackageName( specifier: string, From 7c0d408c155bb9f7351f5d7d9619f28728fb2b70 Mon Sep 17 00:00:00 2001 From: Jonas Kello Date: Sun, 24 Oct 2021 12:36:00 +0200 Subject: [PATCH 05/13] Add example impl --- doc/design-resolve-reuse.md | 75 +++++++++++++++++++++++++++++++++++++ 1 file changed, 75 insertions(+) diff --git a/doc/design-resolve-reuse.md b/doc/design-resolve-reuse.md index 823c6c0..7f930f4 100644 --- a/doc/design-resolve-reuse.md +++ b/doc/design-resolve-reuse.md @@ -192,3 +192,78 @@ export function findPackageJson( isDirectory: IsDirectory ): readonly [packageJSONUrl: URL, packageJSONPath: string] | undefined; ``` + +The implementation of a `PackageResolve` function in appliation code could look like this. Note that the resolve can be ambigous in that an array of multiple possible URLs is returned. This is becuase the `legacyMainResolve` is ambigous and is avoiding file system access by returning all possibilites rather than looking in the file system for what exists. The application is left to sort out which possibility is the right one with it's own logic. + +```ts +import * as rua from "utility-functions-from-above"; + +/** + * This function resolves bare specifiers that refers to packages (not node:, data: bare specifiers) + */ +function packageResolve( + specifier: string, + base: string | URL | undefined, + conditions: ReadonlySet, + isDirectory: IsDirectory, + readFile: ReadFile +): ReadonlyArray { + // Parse the specifier as a package name (package or @org/package) and separate out the sub-path + const { packageName, packageSubpath, isScoped } = rua.parsePackageName( + specifier, + base + ); + + // ResolveSelf + // Check if the specifier resolves to the same package we are resolving from + const selfResolved = rua.resolveSelf( + packageResolve, + base, + packageName, + packageSubpath, + conditions, + readFile + ); + if (selfResolved) { + return [selfResolved]; + } + + // Find package.json by ascending the file system + const packageJsonMatch = rua.findPackageJson( + packageName, + base, + isScoped, + isDirectory + ); + + // If package.json was found, resolve from it's exports or main field + if (packageJsonMatch) { + const [packageJSONUrl, packageJSONPath] = packageJsonMatch; + const packageConfig = rua.getPackageConfig( + readFile, + packageJSONPath, + specifier, + base + ); + if (packageConfig.exports !== undefined && packageConfig.exports !== null) { + const per = rua.packageExportsResolve( + packageResolve, + packageJSONUrl, + packageSubpath, + packageConfig, + base, + conditions + ).resolved; + return [per]; + } + debug("packageSubpath", packageSubpath); + if (packageSubpath === ".") { + // return legacyMainResolve(packageJSONUrl, packageConfig, base); + return rua.legacyMainResolve2(packageJSONUrl, packageConfig); + } + return [new URL(packageSubpath, packageJSONUrl)]; + } + + return []; +} +``` From a262d0a1355c67047e23aad3d292fd61b69567d8 Mon Sep 17 00:00:00 2001 From: Jonas Kello Date: Sun, 24 Oct 2021 12:36:14 +0200 Subject: [PATCH 06/13] Correct call --- doc/design-resolve-reuse.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/doc/design-resolve-reuse.md b/doc/design-resolve-reuse.md index 7f930f4..e03dcc8 100644 --- a/doc/design-resolve-reuse.md +++ b/doc/design-resolve-reuse.md @@ -258,8 +258,7 @@ function packageResolve( } debug("packageSubpath", packageSubpath); if (packageSubpath === ".") { - // return legacyMainResolve(packageJSONUrl, packageConfig, base); - return rua.legacyMainResolve2(packageJSONUrl, packageConfig); + return rua.legacyMainResolve(packageJSONUrl, packageConfig); } return [new URL(packageSubpath, packageJSONUrl)]; } From 9c1b37f98239dc5bb91ac27df39c225a59f5484c Mon Sep 17 00:00:00 2001 From: Jonas Kello Date: Sun, 24 Oct 2021 12:47:40 +0200 Subject: [PATCH 07/13] Add more example code --- doc/design-resolve-reuse.md | 45 ++++++++++++++++++++++++++++++++++++- 1 file changed, 44 insertions(+), 1 deletion(-) diff --git a/doc/design-resolve-reuse.md b/doc/design-resolve-reuse.md index e03dcc8..a340af4 100644 --- a/doc/design-resolve-reuse.md +++ b/doc/design-resolve-reuse.md @@ -193,11 +193,54 @@ export function findPackageJson( ): readonly [packageJSONUrl: URL, packageJSONPath: string] | undefined; ``` -The implementation of a `PackageResolve` function in appliation code could look like this. Note that the resolve can be ambigous in that an array of multiple possible URLs is returned. This is becuase the `legacyMainResolve` is ambigous and is avoiding file system access by returning all possibilites rather than looking in the file system for what exists. The application is left to sort out which possibility is the right one with it's own logic. +### Example of using utility functions to resolve + +Note that the resolve from the `packageResolve` function can be ambigous in that an array of multiple possible URLs is returned. This is becuase the `legacyMainResolve` is ambigous and is avoiding file system access by returning all possibilites rather than looking in the file system for what exists. The application is left to sort out which possibility is the right one with it's own logic. ```ts import * as rua from "utility-functions-from-above"; +function startResolve( + specifier: string, + base: string | undefined, + conditions: ReadonlySet, + isDirectory: IsDirectory, + readFile: ReadFile +): ResolveReturn | undefined { + // Resolve path specifiers + if (rua.shouldBeTreatedAsRelativeOrAbsolutePath(specifier)) { + // Application specific logic to resolve path specifiers + return appliationLogicToResolvePathSpecifiers(); + } + + // Resolve bare specifiers + let possibleUrls: ReadonlyArray = []; + if (specifier.startsWith("#")) { + // Use utility function to resolve + const { resolved } = rua.packageImportsResolve( + packageResolve, + specifier, + base, + conditions, + readFile + )!; + possibleUrls = [resolved]; + } else { + // Use application specific packageResolve() specified below + possibleUrls = packageResolve( + specifier, + base, + conditions, + isDirectory, + readFile + ); + } + + // At this point the bare specifier is resolved to one or more possible files + // Use application specific logic to determine which one to use (or return undefined if none exists) + return applicationLogicToSortOutWhichUrlToUse(); +} + /** * This function resolves bare specifiers that refers to packages (not node:, data: bare specifiers) */ From 9a552ab3be620f7bd8228dabe861f2379acd3404 Mon Sep 17 00:00:00 2001 From: Jonas Kello Date: Sun, 24 Oct 2021 12:49:56 +0200 Subject: [PATCH 08/13] Add cxall to getConditionsSet --- doc/design-resolve-reuse.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/doc/design-resolve-reuse.md b/doc/design-resolve-reuse.md index a340af4..6f0626c 100644 --- a/doc/design-resolve-reuse.md +++ b/doc/design-resolve-reuse.md @@ -203,10 +203,13 @@ import * as rua from "utility-functions-from-above"; function startResolve( specifier: string, base: string | undefined, - conditions: ReadonlySet, + conditionsArray: ReadonlyArray, isDirectory: IsDirectory, readFile: ReadFile ): ResolveReturn | undefined { + // Convert conditions to set + const conditions = rua.getConditionsSet(conditionsArray); + // Resolve path specifiers if (rua.shouldBeTreatedAsRelativeOrAbsolutePath(specifier)) { // Application specific logic to resolve path specifiers From 167fd578635ba9649cb56e470615e28faf1d4232 Mon Sep 17 00:00:00 2001 From: Jonas Kello Date: Sun, 24 Oct 2021 12:58:19 +0200 Subject: [PATCH 09/13] Remove debug statement --- doc/design-resolve-reuse.md | 1 - 1 file changed, 1 deletion(-) diff --git a/doc/design-resolve-reuse.md b/doc/design-resolve-reuse.md index 6f0626c..c76b17e 100644 --- a/doc/design-resolve-reuse.md +++ b/doc/design-resolve-reuse.md @@ -302,7 +302,6 @@ function packageResolve( ).resolved; return [per]; } - debug("packageSubpath", packageSubpath); if (packageSubpath === ".") { return rua.legacyMainResolve(packageJSONUrl, packageConfig); } From 3b695d610a39f9d13b568499104dcf4744c813a1 Mon Sep 17 00:00:00 2001 From: Jonas Kello Date: Tue, 26 Oct 2021 20:20:59 +0200 Subject: [PATCH 10/13] Add some refactoring suggestions --- doc/design-resolve-reuse.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/doc/design-resolve-reuse.md b/doc/design-resolve-reuse.md index c76b17e..ab134b5 100644 --- a/doc/design-resolve-reuse.md +++ b/doc/design-resolve-reuse.md @@ -311,3 +311,13 @@ function packageResolve( return []; } ``` + +### Suggestions for refactoring of the API functions + +The API functions above are derived from the current code in [resolve.js](https://github.com/nodejs/node/blob/master/lib/internal/modules/esm/resolve.js). Here are some suggestions for refactoring to a cleaner API with some tradeoffs. + +- `shouldBeTreatedAsRelativeOrAbsolutePath` could be made more generic by determining all types of specifiers. Something like a function that takes a specifier and returns the type, eg. this (incomplete) example: `classifySpecifier(specifier) => relative | absolute | built_in | internal`. The tradeoff here would probably be performance. + +- `packageImportsResolve` currently takes a `readFile` callback. It only uses this to do an unconditional call to`getPackageScopeConfig` at the very start. It might be better to do this call on the outside and pass the contents of the file into `packageImportsResolve` instead. This seems more straightforward than passing in a callback. + +- `resolveSelf` currently takes a `readFile` callback. It only uses this to do an unconditional call to`getPackageScopeConfig` at the very start. It might be better to do this call on the outside and pass the contents of the file into `resolveSelf` instead. This seems more straightforward than passing in a callback. From ca9fe007a8ab0f710632a45272fda69d980405ed Mon Sep 17 00:00:00 2001 From: Jonas Kello Date: Tue, 26 Oct 2021 20:24:30 +0200 Subject: [PATCH 11/13] Remove mention of file system hooks --- doc/design-resolve-reuse.md | 16 +++++----------- 1 file changed, 5 insertions(+), 11 deletions(-) diff --git a/doc/design-resolve-reuse.md b/doc/design-resolve-reuse.md index ab134b5..8397865 100644 --- a/doc/design-resolve-reuse.md +++ b/doc/design-resolve-reuse.md @@ -11,7 +11,7 @@ Typescript files import from the future output so the imported file may not exis In other cases where larger alterations of the algorithm is desired it still might be useful to call into parts of the default algorithm(?). -# Analysis of current file system access in defaultResolve +## Analysis of current file system access in defaultResolve The default resolve algorithm is implemented in [resolve.js](https://github.com/nodejs/node/blob/master/lib/internal/modules/esm/resolve.js). @@ -80,13 +80,7 @@ The analysis shows that filesystem access occurs mainly as an effect of calls to - moduleResolve - defaultResolve -# Stragegies for re-use of defaultResolve - -## Filesystem hooks - -Using this strategy, the loader would provide hooks for filesystem calls, specifically hooks corresponding to `realpathSync`, `statSync` and `packageJsonReader.read`. - -## Utility functions +## Re-use of defaultResolve as utility functions This strategy would export utility functions so a custom loader could pick which parts of the default algorithm's logic it wants to call. If utility functions are exported, they probably should not do any filesystem access or throw exceptions (but instead return a value indicating success/fail). @@ -96,7 +90,7 @@ If the loader should provide its own `packageResolve` it could be useful to brea Using this strategy the utility functions exported would be free of filesystem side-effects and the loader would do any such effects needed itself. So this would be akin to a [functional-core-imperative-shell](https://www.destroyallsoftware.com/screencasts/catalog/functional-core-imperative-shell) stratgegy. Altough the utility functions would be "pure" only in the sense that they do no filesystem side-effects or throw exceptions. Although the utility functions cannot be made 100% pure, they probably could be made idempotent. -### Utility functions API +## Utility functions API Here is an example of how the utility API could look like. It is written in typescript notation to make the types of parameters clear. The design of this API is mainly an effect of refactoring the existing functions and may have looked different if designed from scratch. @@ -193,7 +187,7 @@ export function findPackageJson( ): readonly [packageJSONUrl: URL, packageJSONPath: string] | undefined; ``` -### Example of using utility functions to resolve +## Example of using utility functions to resolve Note that the resolve from the `packageResolve` function can be ambigous in that an array of multiple possible URLs is returned. This is becuase the `legacyMainResolve` is ambigous and is avoiding file system access by returning all possibilites rather than looking in the file system for what exists. The application is left to sort out which possibility is the right one with it's own logic. @@ -312,7 +306,7 @@ function packageResolve( } ``` -### Suggestions for refactoring of the API functions +## Suggestions for refactoring of the API functions The API functions above are derived from the current code in [resolve.js](https://github.com/nodejs/node/blob/master/lib/internal/modules/esm/resolve.js). Here are some suggestions for refactoring to a cleaner API with some tradeoffs. From a802896d0f1028036918403e298091143753079b Mon Sep 17 00:00:00 2001 From: Jonas Kello Date: Tue, 26 Oct 2021 20:57:09 +0200 Subject: [PATCH 12/13] Resolver hook exampole --- doc/design-resolve-reuse.md | 45 ++++++++++++++++++++++++++++--------- 1 file changed, 34 insertions(+), 11 deletions(-) diff --git a/doc/design-resolve-reuse.md b/doc/design-resolve-reuse.md index 8397865..add0271 100644 --- a/doc/design-resolve-reuse.md +++ b/doc/design-resolve-reuse.md @@ -191,23 +191,40 @@ export function findPackageJson( Note that the resolve from the `packageResolve` function can be ambigous in that an array of multiple possible URLs is returned. This is becuase the `legacyMainResolve` is ambigous and is avoiding file system access by returning all possibilites rather than looking in the file system for what exists. The application is left to sort out which possibility is the right one with it's own logic. +Below is an example of a naive typescript resolve hook. For imports ending in `.js` it changes them to `.ts`. + ```ts import * as rua from "utility-functions-from-above"; -function startResolve( - specifier: string, - base: string | undefined, - conditionsArray: ReadonlyArray, - isDirectory: IsDirectory, - readFile: ReadFile -): ResolveReturn | undefined { +export function resolve( + specifier, + context, + defaultResolve +): { url: string; format: string } { + // Let node handle `data:` and `node:` prefix etc. + const excludeRegex = /^\w+:/; + if (excludeRegex.test(specifier)) { + return undefined; + } + + // Use regular filesystem + const readFile = (path: string) => fs.readFileSync(path, "utf8"); + const isDirectory = (path: string) => + fs.statSync(path, { throwIfNoEntry: false })?.isDirectory() ?? false; + // Convert conditions to set const conditions = rua.getConditionsSet(conditionsArray); // Resolve path specifiers if (rua.shouldBeTreatedAsRelativeOrAbsolutePath(specifier)) { - // Application specific logic to resolve path specifiers - return appliationLogicToResolvePathSpecifiers(); + // If parentURL was not specified, then we use cwd + const { parentURL: parentURLIn, conditions } = context; + const parentURL = parentURLIn ?? filesystem.cwd(); + // Just change .js to .ts + return { + url: makeTypescriptUrlFromJs(specifier, parentURL), + format: "module", + }; } // Resolve bare specifiers @@ -233,9 +250,15 @@ function startResolve( ); } - // At this point the bare specifier is resolved to one or more possible files + // At this point the bare specifier is resolved to one or more possible files, // Use application specific logic to determine which one to use (or return undefined if none exists) - return applicationLogicToSortOutWhichUrlToUse(); + for (const pu of possibleUrls) { + if (fs.existsSync(pu)) { + return { url: makeTypescriptUrlFromJs(pu), format: "module" }; + } + } + + return undefined; } /** From 1f1fe71cc4ba824b6f2597284f75788019504685 Mon Sep 17 00:00:00 2001 From: Jonas Kello Date: Tue, 26 Oct 2021 21:22:14 +0200 Subject: [PATCH 13/13] Fallback to defaultResolve in example --- doc/design-resolve-reuse.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/design-resolve-reuse.md b/doc/design-resolve-reuse.md index add0271..04f7f8f 100644 --- a/doc/design-resolve-reuse.md +++ b/doc/design-resolve-reuse.md @@ -204,7 +204,7 @@ export function resolve( // Let node handle `data:` and `node:` prefix etc. const excludeRegex = /^\w+:/; if (excludeRegex.test(specifier)) { - return undefined; + return defaultResolve(specifier, context); } // Use regular filesystem @@ -258,7 +258,7 @@ export function resolve( } } - return undefined; + return defaultResolve(specifier, context); } /**