Oxc Resolver

The oxc-resolver npm package provides high-performance module resolution for both Node.js and WASM environments. It implements ESM and CommonJS resolution algorithms and includes built-in support for tsconfig.json features like paths aliases, project references, and tsconfig.extends.

There are two primary ways to use the API:

1. Direct resolve function: A simple utility for resolving specifiers against a directory.
2. ResolverFactory: A more robust way to manage resolution state and configuration, allowing for cloning with different options (e.g., switching between ESM and CJS conditions).

import resolve, { ResolverFactory } from "./index.js";

// Using the direct resolve function
const result = resolve.sync(process.cwd(), "./index.js");

// Using ResolverFactory
const resolver = new ResolverFactory();
const result2 = resolver.sync(process.cwd(), "./index.js");

The resolver implements the Node.js algorithm for resolving package targets within exports and imports fields. When a target is encountered, the resolver follows these rules:

1. String Targets: If the target is a string, it is normalized. If the resulting path contains invalid segments (like .. or node_modules in certain contexts), it throws an InvalidPackageTarget error.
2. Object Targets: If the target is an object, the resolver iterates through its keys in insertion order. It checks for matches against the "default" key or any active conditions (e.g., import, require, node). The first matching condition returns the resolved path.
3. Array Targets: If the target is an array, the resolver iterates through the items. It returns the first successful resolution. If an item fails with an error other than NotFound, the resolution fails immediately. This allows for fallback mechanisms where a NotFound error in one array entry allows the resolver to try the next entry.
4. Null Targets: If the target is null, the resolution returns None (undefined).

Oxc Resolver implements Node.js [CommonJS] and [ECMAScript] module resolution algorithms.

Key Concepts

• Specifier: The string used to request a module. In require("id"), "id" is the specifier. In import { x } from "specifier", "specifier" is the specifier. This is also sometimes called a "request".
• Resolution: The process of mapping a specifier to a concrete file path on the file system.
• Resolution Result: A successful resolution returns a Resolution object containing:
  • path: The absolute path to the resolved file.
  • query: Any query parameters extracted from the specifier.
  • fragment: Any URL fragment extracted from the specifier.
  • package_json: The PackageJson associated with the resolved module (if applicable).
  • module_type: The detected module type (ESM or CJS).

Resolution Logic Flow

1. Parsing: The specifier is parsed into a Specifier object.
2. Alias/Fallback: The resolver checks for configured alias or fallback rules.
3. Core Modules: If the specifier matches a Node.js built-in (e.g., node:fs), it handles it as a core module.
4. Path Types:
   • Absolute: Starts with / or a drive prefix.
   • Relative: Starts with ./, ../, or ..
   • Hash: Starts with # (handles package#imports).
   • Bare: A standard package name (e.g., lodash), which triggers node_modules lookup.
5. File/Directory Loading: The resolver attempts to find the file by checking extensions (e.g., .js, .json) or by looking for a package.json with a main field if the specifier points to a directory.

Oxc Resolver implements the Node.js resolution algorithm for exports and imports fields in package.json.

Exports Resolution

When a specifier matches a key in the exports field, the resolver uses PACKAGE_EXPORTS_RESOLVE to find the target. It supports:

• Direct matches: Exact keys in the exports object.
• Subpath patterns: Keys containing * (e.g., ./utils/*) which are matched against the subpath. The resolver uses PATTERN_KEY_COMPARE to ensure the most specific pattern wins.
• Folder mapping: Supports mapping directories (e.g., ./dist/ to ./dist/*), though it notes this is deprecated in modern Node.js.

Imports Resolution

Specifiers starting with # are treated as package imports. The resolver looks up the imports field in the nearest package.json and performs matching similar to the exports logic.

Key Constraints

• Invalid Configuration: An error ResolveError::InvalidPackageConfig is thrown if an exports object contains both keys starting with . or # and keys that do not.
• Invalid Targets: For imports, targets must start with ./ unless they are absolute or relative to the package root in specific ways. Otherwise, ResolveError::InvalidPackageTarget is returned.

The TsConfig implementation includes logic to determine if a specific file is 'owned' or 'included' by a configuration, which is critical for auto-discovery of the correct config for a given file.

Inclusion Logic

A file is considered included if:

1. It is explicitly listed in the files array (highest priority).
2. It matches one of the patterns in the include array, provided it is not also matched by an exclude pattern.
3. If files is not present, it matches the default **/* pattern (scoped to the config directory and restricted to allowed TS/JS extensions).

Ownership (claims_ownership_of)

A TsConfig claims ownership of a path if:

• The file is included in the config via files or include/exclude patterns.
• The file is part of a resolved project reference.

Note on Solution-style configs: Configs that use references but have explicit empty files: [] and include: [] arrays are considered 'solution-style' and do not claim ownership of files themselves; they exist only to orchestrate sub-projects.

The tsconfig option in ResolveOptions allows you to control how TypeScript configuration files are discovered. It uses the TsconfigDiscovery enum.

• TsconfigDiscovery::Auto: Automatically discover the tsconfig.json.
• TsconfigDiscovery::Manual(TsconfigOptions): Provide specific configuration via TsconfigOptions.

TsconfigOptions allows you to specify:

• config_file: A PathBuf to the configuration file (can be relative to cwd).
• references: A TsconfigReferences enum to enable or disable support for TypeScript Project References (Auto or Disabled).

use oxc_resolver::{ResolveOptions, TsconfigDiscovery, TsconfigOptions, TsconfigReferences};
use std::path::PathBuf;

let options = ResolveOptions::default().tsconfig(Some(TsconfigDiscovery::Manual(
    TsconfigOptions {
        config_file: PathBuf::from("tsconfig.json"),
        references: TsconfigReferences::Auto,
    }
)));