Asynchronous Resolution

/**
 * 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);

const resolve = require('resolve');

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

// Resolution with package info
resolve('express', { basedir: __dirname }, (err, res, pkg) => {
  if (err) throw err;
  console.log(res); // /path/to/node_modules/express/index.js  
  console.log(pkg); // { name: 'express', version: '4.18.2', ... }
});

// Relative path resolution
resolve('./utils/helper', { basedir: '/project/src' }, (err, res) => {
  if (err) throw err;
  console.log(res); // /project/src/utils/helper.js
});

interface AsyncResolveOptions {
  /** Directory to begin resolving from (default: dirname of calling file) */
  basedir?: string;
  /** File extensions to search in order (default: ['.js']) */
  extensions?: string[];
  /** Include Node.js core modules in search (default: true) */
  includeCoreModules?: boolean;
  /** Don't resolve basedir to real path before resolving (default: true) */
  preserveSymlinks?: boolean;
  /** Directory names to search for modules (default: 'node_modules') */
  moduleDirectory?: string | string[];
}

interface FileSystemOptions {
  /** Custom async file reading function */
  readFile?: (file: string, callback: (err: Error | null, data: Buffer | string) => void) => void;
  /** Custom async file existence test function */
  isFile?: (file: string, callback: (err: Error | null, exists: boolean) => void) => void;
  /** Custom async directory existence test function */
  isDirectory?: (dir: string, callback: (err: Error | null, exists: boolean) => void) => void;
  /** Custom async symlink resolution function */
  realpath?: (path: string, callback: (err: Error | null, realPath: string) => void) => void;
}

const fs = require('fs');

resolve('custom-module', {
  basedir: __dirname,
  readFile: (file, cb) => {
    console.log('Reading:', file);
    fs.readFile(file, cb);
  },
  isFile: (file, cb) => {
    fs.stat(file, (err, stat) => {
      if (err) return cb(null, false);
      cb(null, stat.isFile());
    });
  }
}, (err, res) => {
  // Custom file system operations will be used during resolution
});

interface PackageOptions {
  /** package.json data applicable to module being loaded */
  package?: object;
  /** Custom async package.json reading function */
  readPackage?: ReadPackageFunction;
  /** Transform package.json contents before looking at main field */
  packageFilter?: (pkg: object, pkgfile: string, dir: string) => object;
  /** Transform paths within packages */
  pathFilter?: (pkg: object, path: string, relativePath: string) => string;
  /** Custom package candidate path iterator */
  packageIterator?: PackageIteratorFunction;
}

/**
 * Custom package.json reading function
 */
interface ReadPackageFunction {
  (readFile: Function, pkgfile: string, callback: (err: Error | null, pkg?: object) => void): void;
}

/**
 * Custom package candidate path iterator
 */
interface PackageIteratorFunction {
  (request: string, start: string, getPackageCandidates: () => string[], opts: AsyncResolveOptions): string[];
}

resolve('my-package', {
  basedir: __dirname,
  packageFilter: (pkg, pkgfile, dir) => {
    // Transform package.json before resolution
    if (pkg.name === 'my-package') {
      pkg.main = 'dist/index.js'; // Override main field
    }
    return pkg;
  },
  pathFilter: (pkg, path, relativePath) => {
    // Transform resolved paths
    if (pkg.name === 'my-package' && path.endsWith('.js')) {
      return path.replace('.js', '.min.js');
    }
    return path;
  }
}, (err, res) => {
  // Resolution will use transformed package data
});

interface PathOptions {
  /** Custom require.paths array or function for path resolution */
  paths?: string[] | PathsFunction;
}

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

resolve('custom-lib', {
  basedir: __dirname,
  paths: (request, start, getNodeModulesDirs, opts) => {
    const standardPaths = getNodeModulesDirs();
    // Add custom search paths
    return ['/custom/modules', ...standardPaths];
  }
}, (err, res) => {
  // Will search in custom paths in addition to standard locations
});

interface ResolveError extends Error {
  /** Error code indicating the type of resolution failure */
  code: 'MODULE_NOT_FOUND' | 'INVALID_PACKAGE_MAIN';
  /** Original error message */
  message: string;
}

resolve('nonexistent-module', { basedir: __dirname }, (err, res) => {
  if (err && err.code === 'MODULE_NOT_FOUND') {
    console.error('Module not found:', err.message);
    // "Cannot find module 'nonexistent-module' from '/current/directory'"
  }
});

// This can occur if a package.json has main: 123 instead of main: "index.js"
resolve('broken-package', { basedir: __dirname }, (err, res) => {
  if (err && err.code === 'INVALID_PACKAGE_MAIN') {
    console.error('Invalid package main:', err.message);
    // 'package "broken-package" `main` must be a string'
  }
});