1# resolve
2
3implements the [node `require.resolve()`
4algorithm](https://nodejs.org/api/modules.html#modules_all_together)
5such that you can `require.resolve()` on behalf of a file asynchronously and
6synchronously
7
8[![build status](https://secure.travis-ci.org/browserify/resolve.png)](http://travis-ci.org/browserify/resolve)
9
10# example
11
12asynchronously resolve:
13
14```js
15var resolve = require('resolve');
16resolve('tap', { basedir: __dirname }, function (err, res) {
17    if (err) console.error(err);
18    else console.log(res);
19});
20```
21
22```
23$ node example/async.js
24/home/substack/projects/node-resolve/node_modules/tap/lib/main.js
25```
26
27synchronously resolve:
28
29```js
30var resolve = require('resolve');
31var res = resolve.sync('tap', { basedir: __dirname });
32console.log(res);
33```
34
35```
36$ node example/sync.js
37/home/substack/projects/node-resolve/node_modules/tap/lib/main.js
38```
39
40# methods
41
42```js
43var resolve = require('resolve');
44```
45
46For both the synchronous and asynchronous methods, errors may have any of the following `err.code` values:
47
48- `MODULE_NOT_FOUND`: the given path string (`id`) could not be resolved to a module
49- `INVALID_BASEDIR`: the specified `opts.basedir` doesn't exist, or is not a directory
50- `INVALID_PACKAGE_MAIN`: a `package.json` was encountered with an invalid `main` property (eg. not a string)
51
52## resolve(id, opts={}, cb)
53
54Asynchronously resolve the module path string `id` into `cb(err, res [, pkg])`, where `pkg` (if defined) is the data from `package.json`.
55
56options are:
57
58* opts.basedir - directory to begin resolving from
59
60* opts.package - `package.json` data applicable to the module being loaded
61
62* opts.extensions - array of file extensions to search in order
63
64* opts.includeCoreModules - set to `false` to exclude node core modules (e.g. `fs`) from the search
65
66* opts.readFile - how to read files asynchronously
67
68* opts.isFile - function to asynchronously test whether a file exists
69
70* opts.isDirectory - function to asynchronously test whether a directory exists
71
72* opts.realpath - function to asynchronously resolve a potential symlink to its real path
73
74* `opts.packageFilter(pkg, pkgfile, dir)` - transform the parsed package.json contents before looking at the "main" field
75  * pkg - package data
76  * pkgfile - path to package.json
77  * dir - directory for package.json
78
79* `opts.pathFilter(pkg, path, relativePath)` - transform a path within a package
80  * pkg - package data
81  * path - the path being resolved
82  * relativePath - the path relative from the package.json location
83  * returns - a relative path that will be joined from the package.json location
84
85* opts.paths - require.paths array to use if nothing is found on the normal `node_modules` recursive walk (probably don't use this)
86
87  For advanced users, `paths` can also be a `opts.paths(request, start, opts)` function
88    * request - the import specifier being resolved
89    * start - lookup path
90    * getNodeModulesDirs - a thunk (no-argument function) that returns the paths using standard `node_modules` resolution
91    * opts - the resolution options
92
93* `opts.packageIterator(request, start, opts)` - return the list of candidate paths where the packages sources may be found (probably don't use this)
94    * request - the import specifier being resolved
95    * start - lookup path
96    * getPackageCandidates - a thunk (no-argument function) that returns the paths using standard `node_modules` resolution
97    * opts - the resolution options
98
99* opts.moduleDirectory - directory (or directories) in which to recursively look for modules. default: `"node_modules"`
100
101* opts.preserveSymlinks - if true, doesn't resolve `basedir` to real path before resolving.
102This is the way Node resolves dependencies when executed with the [--preserve-symlinks](https://nodejs.org/api/all.html#cli_preserve_symlinks) flag.
103**Note:** this property is currently `true` by default but it will be changed to
104`false` in the next major version because *Node's resolution algorithm does not preserve symlinks by default*.
105
106default `opts` values:
107
108```js
109{
110    paths: [],
111    basedir: __dirname,
112    extensions: ['.js'],
113    includeCoreModules: true,
114    readFile: fs.readFile,
115    isFile: function isFile(file, cb) {
116        fs.stat(file, function (err, stat) {
117            if (!err) {
118                return cb(null, stat.isFile() || stat.isFIFO());
119            }
120            if (err.code === 'ENOENT' || err.code === 'ENOTDIR') return cb(null, false);
121            return cb(err);
122        });
123    },
124    isDirectory: function isDirectory(dir, cb) {
125        fs.stat(dir, function (err, stat) {
126            if (!err) {
127                return cb(null, stat.isDirectory());
128            }
129            if (err.code === 'ENOENT' || err.code === 'ENOTDIR') return cb(null, false);
130            return cb(err);
131        });
132    },
133    realpath: function realpath(file, cb) {
134        var realpath = typeof fs.realpath.native === 'function' ? fs.realpath.native : fs.realpath;
135        realpath(file, function (realPathErr, realPath) {
136            if (realPathErr && realPathErr.code !== 'ENOENT') cb(realPathErr);
137            else cb(null, realPathErr ? file : realPath);
138        });
139    },
140    moduleDirectory: 'node_modules',
141    preserveSymlinks: true
142}
143```
144
145## resolve.sync(id, opts)
146
147Synchronously resolve the module path string `id`, returning the result and
148throwing an error when `id` can't be resolved.
149
150options are:
151
152* opts.basedir - directory to begin resolving from
153
154* opts.extensions - array of file extensions to search in order
155
156* opts.includeCoreModules - set to `false` to exclude node core modules (e.g. `fs`) from the search
157
158* opts.readFile - how to read files synchronously
159
160* opts.isFile - function to synchronously test whether a file exists
161
162* opts.isDirectory - function to synchronously test whether a directory exists
163
164* opts.realpathSync - function to synchronously resolve a potential symlink to its real path
165
166* `opts.packageFilter(pkg, dir)` - transform the parsed package.json contents before looking at the "main" field
167  * pkg - package data
168  * dir - directory for package.json (Note: the second argument will change to "pkgfile" in v2)
169
170* `opts.pathFilter(pkg, path, relativePath)` - transform a path within a package
171  * pkg - package data
172  * path - the path being resolved
173  * relativePath - the path relative from the package.json location
174  * returns - a relative path that will be joined from the package.json location
175
176* opts.paths - require.paths array to use if nothing is found on the normal `node_modules` recursive walk (probably don't use this)
177
178  For advanced users, `paths` can also be a `opts.paths(request, start, opts)` function
179    * request - the import specifier being resolved
180    * start - lookup path
181    * getNodeModulesDirs - a thunk (no-argument function) that returns the paths using standard `node_modules` resolution
182    * opts - the resolution options
183
184* `opts.packageIterator(request, start, opts)` - return the list of candidate paths where the packages sources may be found (probably don't use this)
185    * request - the import specifier being resolved
186    * start - lookup path
187    * getPackageCandidates - a thunk (no-argument function) that returns the paths using standard `node_modules` resolution
188    * opts - the resolution options
189
190* opts.moduleDirectory - directory (or directories) in which to recursively look for modules. default: `"node_modules"`
191
192* opts.preserveSymlinks - if true, doesn't resolve `basedir` to real path before resolving.
193This is the way Node resolves dependencies when executed with the [--preserve-symlinks](https://nodejs.org/api/all.html#cli_preserve_symlinks) flag.
194**Note:** this property is currently `true` by default but it will be changed to
195`false` in the next major version because *Node's resolution algorithm does not preserve symlinks by default*.
196
197default `opts` values:
198
199```js
200{
201    paths: [],
202    basedir: __dirname,
203    extensions: ['.js'],
204    includeCoreModules: true,
205    readFileSync: fs.readFileSync,
206    isFile: function isFile(file) {
207        try {
208            var stat = fs.statSync(file);
209        } catch (e) {
210            if (e && (e.code === 'ENOENT' || e.code === 'ENOTDIR')) return false;
211            throw e;
212        }
213        return stat.isFile() || stat.isFIFO();
214    },
215    isDirectory: function isDirectory(dir) {
216        try {
217            var stat = fs.statSync(dir);
218        } catch (e) {
219            if (e && (e.code === 'ENOENT' || e.code === 'ENOTDIR')) return false;
220            throw e;
221        }
222        return stat.isDirectory();
223    },
224    realpathSync: function realpathSync(file) {
225        try {
226            var realpath = typeof fs.realpathSync.native === 'function' ? fs.realpathSync.native : fs.realpathSync;
227            return realpath(file);
228        } catch (realPathErr) {
229            if (realPathErr.code !== 'ENOENT') {
230                throw realPathErr;
231            }
232        }
233        return file;
234    },
235    moduleDirectory: 'node_modules',
236    preserveSymlinks: true
237}
238```
239
240# install
241
242With [npm](https://npmjs.org) do:
243
244```sh
245npm install resolve
246```
247
248# license
249
250MIT
251