From cfdeb3416da19ac64c22414b858f26c599c5b873 Mon Sep 17 00:00:00 2001 From: Boshen Date: Sun, 23 Jul 2023 18:48:51 +0800 Subject: [PATCH] chore(resolver): improve documentation (#591) --- crates/oxc_resolver/README.md | 14 +++++++------- crates/oxc_resolver/src/cache.rs | 4 ++-- crates/oxc_resolver/src/lib.rs | 19 +++++++++++-------- crates/oxc_resolver/src/options.rs | 24 +++++++++++++++++------- crates/oxc_resolver/src/path.rs | 2 +- 5 files changed, 38 insertions(+), 25 deletions(-) diff --git a/crates/oxc_resolver/README.md b/crates/oxc_resolver/README.md index 45a24ac96..80900f891 100644 --- a/crates/oxc_resolver/README.md +++ b/crates/oxc_resolver/README.md @@ -3,7 +3,6 @@ ## TODO - [ ] use `thiserror` for better error messages -- [ ] copy API documentation from webpack https://webpack.js.org/configuration/resolve/#resolve #### Resolver Options @@ -38,9 +37,10 @@ ## Test Tests ported from [enhanced-resolve](https://github.com/webpack/enhanced-resolve). +Crossed out test files are irrelevant. -- [ ] CachedInputFileSystem.test.js -- [ ] SyncAsyncFileSystemDecorator.test.js +- [x] ~CachedInputFileSystem.test.js~ +- [x] ~SyncAsyncFileSystemDecorator.test.js~ - [x] alias.test.js (need to fix a todo) - [x] browserField.test.js (reading the browser field is currently static - not read from the `browserField` option) - [ ] dependencies.test.js @@ -48,7 +48,7 @@ Tests ported from [enhanced-resolve](https://github.com/webpack/enhanced-resolve - [x] extension-alias.test.js - [x] extensions.test.js - [x] fallback.test.js (need to fix a todo) -- ~[ ] forEachBail.test.js~ +- [x] ~forEachBail.test.js~ - [ ] fullSpecified.test.js - [ ] getPaths.test.js - [x] identifier.test.js (see unit test in `crates/oxc_resolver/src/request.rs`) @@ -58,12 +58,12 @@ Tests ported from [enhanced-resolve](https://github.com/webpack/enhanced-resolve - [ ] path.test.js - [ ] plugins.test.js - [ ] pnp.test.js -- [ ] pr-53.test.js +- [x] ~pr-53.test.js~ - [x] resolve.test.js (need to add resolveToContext) - [ ] restrictions.test.js - [x] roots.test.js (need to add resolveToContext) - [x] scoped-packages.test.js - [x] simple.test.js - [x] symlink.test.js -- [ ] unsafe-cache.test.js -- [ ] yield.test.js +- [x] ~unsafe-cache.test.js~ +- [x] ~yield.test.js~ diff --git a/crates/oxc_resolver/src/cache.rs b/crates/oxc_resolver/src/cache.rs index 72ba43887..88cc96731 100644 --- a/crates/oxc_resolver/src/cache.rs +++ b/crates/oxc_resolver/src/cache.rs @@ -48,7 +48,7 @@ impl Cache { /// /// # Errors /// - /// * [ResolveError::JSONError] + /// * [ResolveError::JSON] pub fn get_package_json(&self, path: &Path) -> Result>, ResolveError> { self.cache_value(path).package_json(&self.fs).transpose() } @@ -57,7 +57,7 @@ impl Cache { /// /// # Errors /// - /// * [ResolveError::JSONError] + /// * [ResolveError::JSON] pub fn find_package_json(&self, path: &Path) -> Result>, ResolveError> { let mut cache_value = Some(self.cache_value(path)); while let Some(cv) = cache_value { diff --git a/crates/oxc_resolver/src/lib.rs b/crates/oxc_resolver/src/lib.rs index 834e9fd51..76d461da0 100644 --- a/crates/oxc_resolver/src/lib.rs +++ b/crates/oxc_resolver/src/lib.rs @@ -1,5 +1,7 @@ //! # Oxc Resolver //! +//! Node.js Module Resolution. +//! //! ## References: //! //! * Tests ported from [enhanced-resolve](https://github.com/webpack/enhanced-resolve) @@ -21,25 +23,26 @@ use std::{ path::{Path, PathBuf}, }; -pub use crate::{ - cache::Cache, - error::{JSONError, ResolveError}, - file_system::{FileMetadata, FileSystem, FileSystemOs}, - options::{Alias, AliasValue, ResolveOptions}, - resolution::Resolution, -}; use crate::{ + cache::Cache, + file_system::FileSystemOs, package_json::PackageJson, path::PathUtil, request::{Request, RequestPath}, }; +pub use crate::{ + error::{JSONError, ResolveError}, + file_system::{FileMetadata, FileSystem}, + options::{Alias, AliasValue, ResolveOptions}, + resolution::Resolution, +}; -pub type ResolveResult = Result; type ResolveState = Result, ResolveError>; /// Resolver with the current operating system as the file system pub type Resolver = ResolverGeneric; +/// Generic implementation of the resolver, backed by a cached file system. pub struct ResolverGeneric { options: ResolveOptions, cache: Cache, diff --git a/crates/oxc_resolver/src/options.rs b/crates/oxc_resolver/src/options.rs index 0391c5ab7..c19578674 100644 --- a/crates/oxc_resolver/src/options.rs +++ b/crates/oxc_resolver/src/options.rs @@ -11,9 +11,15 @@ pub enum AliasValue { Ignore, } +/// Module Resolution Options +/// +/// Options are directly ported from [enhanced-resolve](https://github.com/webpack/enhanced-resolve#resolver-options). +/// +/// See [webpack resolve](https://webpack.js.org/configuration/resolve/) for information and examples #[derive(Debug, Clone)] pub struct ResolveOptions { - /// A list of module alias configurations or an object which maps key to value + /// Create aliases to import or require certain modules more easily. + /// A trailing $ can also be added to the given object's keys to signify an exact match. pub alias: Alias, /// A list of alias fields in description files. @@ -22,12 +28,14 @@ pub struct ResolveOptions { /// Default `[]` pub alias_fields: Vec, - /// A list of description files to read (there was once a `bower.json`). + /// The JSON files to use for descriptions. (There was once a `bower.json`.) /// /// Default `["package.json"]` pub description_files: Vec, - /// Enforce that a extension from extensions must be used. + /// If true, it will not allow extension-less files. + /// So by default `require('./foo')` works if `./foo` has a `.js` extension, + /// but with this enabled only `require('./foo.js')` will work. /// /// Default to `true` when [ResolveOptions::extensions] contains an empty string. /// Use `Some(false)` to disable the behavior. @@ -41,17 +49,19 @@ pub struct ResolveOptions { /// Default `{}` pub extension_alias: Vec<(String, Vec)>, - /// A list of extensions which should be tried for. + /// Attempt to resolve these extensions in order. + /// If multiple files share the same name but have different extensions, + /// will resolve the one with the extension listed first in the array and skip the rest. /// /// Default `[".js", ".json", ".node"]` pub extensions: Vec, - /// Same as [ResolveOptions::alias], Redirect module requests when normal resolving fails. . + /// Redirect module requests when normal resolving fails. /// /// Default `[]` pub fallback: Alias, - /// A list of main files in directories. + /// The filename to be used while resolving directories. /// /// Default `["index"]` pub main_files: Vec, @@ -61,7 +71,7 @@ pub struct ResolveOptions { /// Default `["node_modules"]` pub modules: Vec, - /// prefer to resolve module requests as relative requests instead of using modules from node_modules directories. + /// Prefer to resolve module requests as relative requests instead of using modules from node_modules directories. /// /// Default `false` pub prefer_relative: bool, diff --git a/crates/oxc_resolver/src/path.rs b/crates/oxc_resolver/src/path.rs index 29f9be047..45f76ab1e 100644 --- a/crates/oxc_resolver/src/path.rs +++ b/crates/oxc_resolver/src/path.rs @@ -2,7 +2,7 @@ //! //! Code adapted from the following libraries //! * [path-absolutize](https://docs.rs/path-absolutize) -//! * [normalize_path](