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/node-resolve.png)](http://travis-ci.org/browserify/node-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
46## resolve(id, opts={}, cb)
47
48Asynchronously resolve the module path string `id` into `cb(err, res [, pkg])`, where `pkg` (if defined) is the data from `package.json`.
49
50options are:
51
52* opts.basedir - directory to begin resolving from
53
54* opts.package - `package.json` data applicable to the module being loaded
55
56* opts.extensions - array of file extensions to search in order
57
58* opts.readFile - how to read files asynchronously
59
60* opts.isFile - function to asynchronously test whether a file exists
61
62* opts.isDirectory - function to asynchronously test whether a directory exists
63
64* `opts.packageFilter(pkg, pkgfile)` - transform the parsed package.json contents before looking at the "main" field
65  * pkg - package data
66  * pkgfile - path to package.json
67
68* `opts.pathFilter(pkg, path, relativePath)` - transform a path within a package
69  * pkg - package data
70  * path - the path being resolved
71  * relativePath - the path relative from the package.json location
72  * returns - a relative path that will be joined from the package.json location
73
74* opts.paths - require.paths array to use if nothing is found on the normal `node_modules` recursive walk (probably don't use this)
75
76  For advanced users, `paths` can also be a `opts.paths(request, start, opts)` function
77    * request - the import specifier being resolved
78    * start - lookup path
79    * getNodeModulesDirs - a thunk (no-argument function) that returns the paths using standard `node_modules` resolution
80    * opts - the resolution options
81
82* opts.moduleDirectory - directory (or directories) in which to recursively look for modules. default: `"node_modules"`
83
84* opts.preserveSymlinks - if true, doesn't resolve `basedir` to real path before resolving.
85This is the way Node resolves dependencies when executed with the [--preserve-symlinks](https://nodejs.org/api/all.html#cli_preserve_symlinks) flag.
86**Note:** this property is currently `true` by default but it will be changed to
87`false` in the next major version because *Node's resolution algorithm does not preserve symlinks by default*.
88
89default `opts` values:
90
91```js
92{
93    paths: [],
94    basedir: __dirname,
95    extensions: ['.js'],
96    readFile: fs.readFile,
97    isFile: function isFile(file, cb) {
98        fs.stat(file, function (err, stat) {
99            if (!err) {
100                return cb(null, stat.isFile() || stat.isFIFO());
101            }
102            if (err.code === 'ENOENT' || err.code === 'ENOTDIR') return cb(null, false);
103            return cb(err);
104        });
105    },
106    isDirectory: function isDirectory(dir, cb) {
107        fs.stat(dir, function (err, stat) {
108            if (!err) {
109                return cb(null, stat.isDirectory());
110            }
111            if (err.code === 'ENOENT' || err.code === 'ENOTDIR') return cb(null, false);
112            return cb(err);
113        });
114    },
115    moduleDirectory: 'node_modules',
116    preserveSymlinks: true
117}
118```
119
120## resolve.sync(id, opts)
121
122Synchronously resolve the module path string `id`, returning the result and
123throwing an error when `id` can't be resolved.
124
125options are:
126
127* opts.basedir - directory to begin resolving from
128
129* opts.extensions - array of file extensions to search in order
130
131* opts.readFile - how to read files synchronously
132
133* opts.isFile - function to synchronously test whether a file exists
134
135* opts.isDirectory - function to synchronously test whether a directory exists
136
137* `opts.packageFilter(pkg, dir)` - transform the parsed package.json contents before looking at the "main" field
138  * pkg - package data
139  * dir - directory for package.json (Note: the second argument will change to "pkgfile" in v2)
140
141* `opts.pathFilter(pkg, path, relativePath)` - transform a path within a package
142  * pkg - package data
143  * path - the path being resolved
144  * relativePath - the path relative from the package.json location
145  * returns - a relative path that will be joined from the package.json location
146
147* opts.paths - require.paths array to use if nothing is found on the normal `node_modules` recursive walk (probably don't use this)
148
149* opts.moduleDirectory - directory (or directories) in which to recursively look for modules. default: `"node_modules"`
150
151* opts.preserveSymlinks - if true, doesn't resolve `basedir` to real path before resolving.
152This is the way Node resolves dependencies when executed with the [--preserve-symlinks](https://nodejs.org/api/all.html#cli_preserve_symlinks) flag.
153**Note:** this property is currently `true` by default but it will be changed to
154`false` in the next major version because *Node's resolution algorithm does not preserve symlinks by default*.
155
156default `opts` values:
157
158```js
159{
160    paths: [],
161    basedir: __dirname,
162    extensions: ['.js'],
163    readFileSync: fs.readFileSync,
164    isFile: function isFile(file) {
165        try {
166            var stat = fs.statSync(file);
167        } catch (e) {
168            if (e && (e.code === 'ENOENT' || e.code === 'ENOTDIR')) return false;
169            throw e;
170        }
171        return stat.isFile() || stat.isFIFO();
172    },
173    isDirectory: function isDirectory(dir) {
174        try {
175            var stat = fs.statSync(dir);
176        } catch (e) {
177            if (e && (e.code === 'ENOENT' || e.code === 'ENOTDIR')) return false;
178            throw e;
179        }
180        return stat.isDirectory();
181    },
182    moduleDirectory: 'node_modules',
183    preserveSymlinks: true
184}
185```
186
187## resolve.isCore(pkg)
188
189Return whether a package is in core.
190
191# install
192
193With [npm](https://npmjs.org) do:
194
195```sh
196npm install resolve
197```
198
199# license
200
201MIT
202