or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

async-resolution.mdcli.mdcore-modules.mdindex.mdsync-resolution.md
tile.json

tessl/npm-resolve

Resolve like require.resolve() on behalf of files asynchronously and synchronously

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/resolve@1.22.x

To install, run

npx @tessl/cli install tessl/npm-resolve@1.22.0

index.mddocs/

Resolve

Resolve implements the Node.js require.resolve() algorithm, enabling resolution of module paths both asynchronously and synchronously on behalf of files. It provides comprehensive module resolution capabilities with support for custom basedir, file extensions, package.json filtering, path transformation, and symlink handling.

Package Information

  • Package Name: resolve
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install resolve

Core Imports

const resolve = require('resolve');

Alternative imports:

// Async-only
const resolve = require('resolve/async');

// Sync-only
const resolveSync = require('resolve/sync');

Basic Usage

Asynchronous resolution:

const resolve = require('resolve');

resolve('lodash', { basedir: __dirname }, (err, res) => {
  if (err) console.error(err);
  else console.log(res); // /path/to/node_modules/lodash/index.js
});

Synchronous resolution:

const resolve = require('resolve');

try {
  const res = resolve.sync('lodash', { basedir: __dirname });
  console.log(res); // /path/to/node_modules/lodash/index.js
} catch (err) {
  console.error(err);
}

Architecture

Resolve is built around several key components:

  • Async Resolution Engine: Main resolution function implementing Node.js algorithm asynchronously
  • Sync Resolution Engine: Synchronous version of the resolution algorithm
  • Options System: Comprehensive configuration for custom file system operations and path transformations
  • Core Module Detection: Built-in awareness of Node.js core modules
  • CLI Interface: Command-line tool for module resolution

Capabilities

Asynchronous Resolution

Core asynchronous module resolution functionality that mirrors Node.js require.resolve() behavior with extensive customization options.

/**
 * Asynchronously resolve module path string
 * @param {string} id - Module path string to resolve
 * @param {object} [options] - Resolution options
 * @param {function} callback - Callback function (err, res, pkg) => void
 */
function resolve(id, options, callback);
function resolve(id, callback);

Async Resolution

Synchronous Resolution

Synchronous module resolution that throws errors instead of using callbacks, suitable for build-time and initialization scenarios.

/**
 * Synchronously resolve module path string
 * @param {string} id - Module path string to resolve  
 * @param {object} [options] - Resolution options
 * @returns {string} Resolved module path
 * @throws {Error} Resolution or validation errors
 */
function resolveSync(id, options);

Sync Resolution

Core Module Detection

Utilities for detecting and working with Node.js core modules during resolution.

/**
 * Check if a module name is a Node.js core module
 * @param {string} moduleName - Module name to check
 * @returns {boolean} True if core module
 */
function isCore(moduleName);

/**
 * Object mapping core module names to boolean values
 * @type {object}
 */
const core;

Core Modules

Command Line Interface

Command-line tool for resolving module paths from the terminal.

resolve <specifier> [--preserve-symlinks]

CLI Usage

Common Types

/**
 * Resolution options for both async and sync resolution
 */  
interface ResolveOptions {
  /** Directory to begin resolving from */
  basedir?: string;
  /** File extensions to search in order */
  extensions?: string[];
  /** Include Node.js core modules in search */
  includeCoreModules?: boolean;
  /** Custom require.paths array or function */
  paths?: string[] | PathsFunction;
  /** Don't resolve basedir to real path before resolving */
  preserveSymlinks?: boolean;
  /** Directory names to search for modules */
  moduleDirectory?: string | string[];
  /** package.json data applicable to module being loaded */
  package?: object;
  /** Alternative filename for error messages */
  filename?: string;
  /** Custom async file reading function */
  readFile?: ReadFileFunction;
  /** Custom sync file reading function */
  readFileSync?: ReadFileSyncFunction;
  /** Custom async file existence test function */
  isFile?: IsFileFunction;
  /** Custom async directory existence test function */
  isDirectory?: IsDirectoryFunction;
  /** Custom async symlink resolution function */
  realpath?: RealpathFunction;
  /** Custom sync symlink resolution function */
  realpathSync?: RealpathSyncFunction;
  /** Custom async package.json reading function */
  readPackage?: ReadPackageFunction;
  /** Custom sync package.json reading function */
  readPackageSync?: ReadPackageSyncFunction;
  /** Transform package.json contents before looking at main field */
  packageFilter?: PackageFilterFunction;
  /** Transform paths within packages */
  pathFilter?: PathFilterFunction;
  /** Custom package candidate path iterator */
  packageIterator?: PackageIteratorFunction;
}

/**
 * Error types that may be thrown or passed to callbacks
 */
interface ResolveError extends Error {
  /** Error code indicating the type of resolution failure */
  code: 'MODULE_NOT_FOUND' | 'INVALID_PACKAGE_MAIN';
}

/**
 * Function type for custom paths resolution
 */
interface PathsFunction {
  (request: string, start: string, getNodeModulesDirs: () => string[], opts: ResolveOptions): string[];
}

/**
 * Custom file system function types
 */
interface ReadFileFunction {
  (file: string, callback: (err: Error | null, data: Buffer | string) => void): void;
}

interface ReadFileSyncFunction {
  (file: string): Buffer | string;
}

interface IsFileFunction {
  (file: string, callback: (err: Error | null, isFile: boolean) => void): void;
}

interface IsDirectoryFunction {
  (dir: string, callback: (err: Error | null, isDirectory: boolean) => void): void;
}

interface RealpathFunction {
  (path: string, callback: (err: Error | null, resolvedPath: string) => void): void;
}

interface RealpathSyncFunction {
  (path: string): string;
}

/**
 * Package processing function types
 */
interface ReadPackageFunction {
  (readFile: ReadFileFunction, pkgfile: string, callback: (err: Error | null, pkg?: object) => void): void;
}

interface ReadPackageSyncFunction {
  (readFileSync: ReadFileSyncFunction, pkgfile: string): object | undefined;
}

interface PackageFilterFunction {
  (pkg: object, pkgfile: string, dir?: string): object;
}

interface PathFilterFunction {
  (pkg: object, path: string, relativePath: string): string;
}

interface PackageIteratorFunction {
  (request: string, start: string, getPackageCandidates: () => string[], opts: ResolveOptions): string[];
}