tessl/npm-enhanced-resolve

Highly configurable async require.resolve function with extensive customization options for module resolution

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Core Resolution

Name: tessl/npm-enhanced-resolve
Author: tessl

Primary async and sync resolution functions providing the main interface for module resolution with flexible calling patterns.

Capabilities

Main Async Resolve Function

The primary asynchronous resolution function with multiple overloads for different usage patterns.

/**
 * Resolves a module request to an absolute path
 * @param context - Context object (optional when path is string)
 * @param path - Base path for resolution
 * @param request - Module request to resolve
 * @param resolveContext - Resolution context (optional)
 * @param callback - Result callback function
 */
function resolve(
  context: object,
  path: string,
  request: string,
  resolveContext: ResolveContext,
  callback: ResolveCallback
): void;

function resolve(
  context: object,
  path: string,
  request: string,
  callback: ResolveCallback
): void;

function resolve(
  path: string,
  request: string,
  resolveContext: ResolveContext,
  callback: ResolveCallback
): void;

function resolve(
  path: string,
  request: string,
  callback: ResolveCallback
): void;

Usage Examples:

const resolve = require("enhanced-resolve");

// Simple resolution with callback
resolve(__dirname, "./utils", (err, result) => {
  if (err) {
    console.error("Resolution failed:", err.message);
  } else {
    console.log("Resolved to:", result);
  }
});

// Resolution with context and resolve context
const context = { environments: ["node"] };
const resolveContext = {
  fileDependencies: new Set(),
  contextDependencies: new Set(),
};

resolve(context, __dirname, "lodash", resolveContext, (err, result, req) => {
  if (result) {
    console.log("Resolved:", result);
    console.log("Dependencies:", [...resolveContext.fileDependencies]);
  }
});

// Resolution with custom context
resolve({ custom: "context" }, "/app/src", "./components/Button", (err, result) => {
  console.log(result); // "/app/src/components/Button.js"
});

Sync Resolve Function

Synchronous version that returns the resolved path immediately or false if resolution fails.

/**
 * Synchronously resolves a module request to an absolute path
 * @param context - Context object (optional when path is string)
 * @param path - Base path for resolution
 * @param request - Module request to resolve
 * @returns Resolved absolute path or false if not found
 */
function resolveSync(context: object, path: string, request: string): string | false;
function resolveSync(path: string, request: string): string | false;

Usage Examples:

const resolve = require("enhanced-resolve");

// Simple sync resolution
const result = resolve.sync(__dirname, "./utils");
if (result) {
  console.log("Found:", result);
} else {
  console.log("Module not found");
}

// Sync resolution with context
const context = { environments: ["node", "browser"] };
const browserModule = resolve.sync(context, __dirname, "./src/browser-utils");

// Error handling for sync resolution
try {
  const resolved = resolve.sync("/app", "non-existent-module");
  if (!resolved) {
    console.log("Module could not be resolved");
  }
} catch (error) {
  console.error("Resolution error:", error.message);
}

Default Context

When no context is provided, enhanced-resolve uses a default Node.js context.

// Default context used when none provided
const defaultContext = {
  environments: ["node+es3+es5+process+native"]
};

Types

type ResolveCallback = (
  err: null | Error,
  res?: string | false,
  req?: ResolveRequest
) => void;

interface ResolveContext {
  /** Directories that were found on file system */
  contextDependencies?: WriteOnlySet<string>;
  /** Files that were found on file system */
  fileDependencies?: WriteOnlySet<string>;
  /** Dependencies that were not found on file system */
  missingDependencies?: WriteOnlySet<string>;
  /** Set of hooks' calls for debugging */
  stack?: Set<string>;
  /** Log function for debugging */
  log?: (str: string) => void;
  /** Yield additional results if provided */
  yield?: (request: ResolveRequest) => void;
}

interface ResolveRequest {
  /** Path being resolved */
  path: string | false;
  /** Custom context object */
  context?: object;
  /** Description file path (package.json) */
  descriptionFilePath?: string;
  /** Description file root directory */
  descriptionFileRoot?: string;
  /** Parsed description file data */
  descriptionFileData?: JsonObject;
  /** Relative path component */
  relativePath?: string;
  /** Whether to ignore symlinks */
  ignoreSymlinks?: boolean;
  /** Whether request is fully specified */
  fullySpecified?: boolean;
}

Install with Tessl CLI