0
# Resolve
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: resolve
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install resolve`
10

11
## Core Imports
12

13
```javascript
14
const resolve = require('resolve');
15
```
16

17
Alternative imports:
18

19
```javascript
20
// Async-only
21
const resolve = require('resolve/async');
22

23
// Sync-only
24
const resolveSync = require('resolve/sync');
25
```
26

27
## Basic Usage
28

29
Asynchronous resolution:
30

31
```javascript
32
const resolve = require('resolve');
33

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

40
Synchronous resolution:
41

42
```javascript
43
const resolve = require('resolve');
44

45
try {
46
  const res = resolve.sync('lodash', { basedir: __dirname });
47
  console.log(res); // /path/to/node_modules/lodash/index.js
48
} catch (err) {
49
  console.error(err);
50
}
51
```
52

53
## Architecture
54

55
Resolve is built around several key components:
56

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

63
## Capabilities
64

65
### Asynchronous Resolution
66

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

69
```javascript { .api }
70
/**
71
 * Asynchronously resolve module path string
72
 * @param {string} id - Module path string to resolve
73
 * @param {object} [options] - Resolution options
74
 * @param {function} callback - Callback function (err, res, pkg) => void
75
 */
76
function resolve(id, options, callback);
77
function resolve(id, callback);
78
```
79

80
[Async Resolution](./async-resolution.md)
81

82
### Synchronous Resolution
83

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

86
```javascript { .api }
87
/**
88
 * Synchronously resolve module path string
89
 * @param {string} id - Module path string to resolve  
90
 * @param {object} [options] - Resolution options
91
 * @returns {string} Resolved module path
92
 * @throws {Error} Resolution or validation errors
93
 */
94
function resolveSync(id, options);
95
```
96

97
[Sync Resolution](./sync-resolution.md)
98

99
### Core Module Detection
100

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

103
```javascript { .api }
104
/**
105
 * Check if a module name is a Node.js core module
106
 * @param {string} moduleName - Module name to check
107
 * @returns {boolean} True if core module
108
 */
109
function isCore(moduleName);
110

111
/**
112
 * Object mapping core module names to boolean values
113
 * @type {object}
114
 */
115
const core;
116
```
117

118
[Core Modules](./core-modules.md)
119

120
### Command Line Interface
121

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

124
```bash { .api }
125
resolve <specifier> [--preserve-symlinks]
126
```
127

128
[CLI Usage](./cli.md)
129

130
## Common Types
131

132
```javascript { .api }
133
/**
134
 * Resolution options for both async and sync resolution
135
 */  
136
interface ResolveOptions {
137
  /** Directory to begin resolving from */
138
  basedir?: string;
139
  /** File extensions to search in order */
140
  extensions?: string[];
141
  /** Include Node.js core modules in search */
142
  includeCoreModules?: boolean;
143
  /** Custom require.paths array or function */
144
  paths?: string[] | PathsFunction;
145
  /** Don't resolve basedir to real path before resolving */
146
  preserveSymlinks?: boolean;
147
  /** Directory names to search for modules */
148
  moduleDirectory?: string | string[];
149
  /** package.json data applicable to module being loaded */
150
  package?: object;
151
  /** Alternative filename for error messages */
152
  filename?: string;
153
  /** Custom async file reading function */
154
  readFile?: ReadFileFunction;
155
  /** Custom sync file reading function */
156
  readFileSync?: ReadFileSyncFunction;
157
  /** Custom async file existence test function */
158
  isFile?: IsFileFunction;
159
  /** Custom async directory existence test function */
160
  isDirectory?: IsDirectoryFunction;
161
  /** Custom async symlink resolution function */
162
  realpath?: RealpathFunction;
163
  /** Custom sync symlink resolution function */
164
  realpathSync?: RealpathSyncFunction;
165
  /** Custom async package.json reading function */
166
  readPackage?: ReadPackageFunction;
167
  /** Custom sync package.json reading function */
168
  readPackageSync?: ReadPackageSyncFunction;
169
  /** Transform package.json contents before looking at main field */
170
  packageFilter?: PackageFilterFunction;
171
  /** Transform paths within packages */
172
  pathFilter?: PathFilterFunction;
173
  /** Custom package candidate path iterator */
174
  packageIterator?: PackageIteratorFunction;
175
}
176

177
/**
178
 * Error types that may be thrown or passed to callbacks
179
 */
180
interface ResolveError extends Error {
181
  /** Error code indicating the type of resolution failure */
182
  code: 'MODULE_NOT_FOUND' | 'INVALID_PACKAGE_MAIN';
183
}
184

185
/**
186
 * Function type for custom paths resolution
187
 */
188
interface PathsFunction {
189
  (request: string, start: string, getNodeModulesDirs: () => string[], opts: ResolveOptions): string[];
190
}
191

192
/**
193
 * Custom file system function types
194
 */
195
interface ReadFileFunction {
196
  (file: string, callback: (err: Error | null, data: Buffer | string) => void): void;
197
}
198

199
interface ReadFileSyncFunction {
200
  (file: string): Buffer | string;
201
}
202

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

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

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

215
interface RealpathSyncFunction {
216
  (path: string): string;
217
}
218

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

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

230
interface PackageFilterFunction {
231
  (pkg: object, pkgfile: string, dir?: string): object;
232
}
233

234
interface PathFilterFunction {
235
  (pkg: object, path: string, relativePath: string): string;
236
}
237

238
interface PackageIteratorFunction {
239
  (request: string, start: string, getPackageCandidates: () => string[], opts: ResolveOptions): string[];
240
}
241
```