codekingpro/portable-devtools

1# `@npmcli/config`
2
3Configuration management for the npm cli.
4
5This module is the spiritual descendant of [`npmconf`](http://npm.im/npmconf), and the code that once lived in npm's
6`lib/config/` folder.
7
8It does the management of configuration files that npm uses, but importantly, does _not_ define all the configuration defaults or types, as those parts make more sense to live within the npm CLI itself.
9
10The only exceptions:
11
12- The `prefix` config value has some special semantics, setting the local prefix if specified on the CLI options and not in global mode, or the global prefix otherwise.
13- The `project` config file is loaded based on the local prefix (which can only be set by the CLI config options, and otherwise defaults to a walk up the folder tree to the first parent containing a `node_modules` folder, `package.json` file, or `package-lock.json` file.)
14- The `userconfig` value, as set by the environment and CLI (defaulting to
15  `~/.npmrc`, is used to load user configs.
16- The `globalconfig` value, as set by the environment, CLI, and
17  `userconfig` file (defaulting to `$PREFIX/etc/npmrc`) is used to load global configs.
18- A `builtin` config, read from a `npmrc` file in the root of the npm project itself, overrides all defaults.
19
20The resulting hierarchy of configs:
21
22- CLI switches.
23  eg `--some-key=some-value` on the command line.
24  These are parsed by [`nopt`](http://npm.im/nopt), which is not a great choice, but it's the one that npm has used forever, and changing it will be difficult.
25- Environment variables.
26  eg `npm_config_some_key=some_value` in the environment.
27  There is no way at this time to modify this prefix.
28- INI-formatted project configs.
29  eg `some-key = some-value` in the
30  `localPrefix` folder (ie, the `cwd`, or its nearest parent that contains either a `node_modules` folder or `package.json` file.)
31- INI-formatted userconfig file.
32  eg `some-key = some-value` in `~/.npmrc`.
33  The `userconfig` config value can be overridden by the `cli`, `env`, or
34  `project` configs to change this value.
35- INI-formatted globalconfig file.
36  eg `some-key = some-value` in the `globalPrefix` folder, which is inferred by looking at the location of the node executable, or the `prefix` setting in the `cli`, `env`, `project`, or `userconfig`.
37  The `globalconfig` value at any of those levels can override this.
38- INI-formatted builtin config file.
39  eg `some-key = some-value` in `/usr/local/lib/node_modules/npm/npmrc`.
40  This is not configurable, and is determined by looking in the `npmPath` folder.
41- Default values (passed in by npm when it loads this module).
42
43## USAGE
44
45```js
46const Config = require('@npmcli/config')
47const { shorthands, definitions, flatten } = require('@npmcli/config/lib/definitions')
48
49const conf = new Config({
50  // path to the npm module being run
51  npmPath: resolve(__dirname, '..'),
52  definitions,
53  shorthands,
54  flatten,
55  // optional, defaults to process.argv
56  // argv: [] <- if you are using this package in your own cli
57  //             and don't want to have colliding argv
58  argv: process.argv,
59  // optional, defaults to process.env
60  env: process.env,
61  // optional, defaults to process.execPath
62  execPath: process.execPath,
63  // optional, defaults to process.platform
64  platform: process.platform,
65  // optional, defaults to process.cwd()
66  cwd: process.cwd(),
67})
68
69// emits log events on the process object
70// see `proc-log` for more info
71process.on('log', (level, ...args) => {
72  console.log(level, ...args)
73})
74
75// returns a promise that fails if config loading fails, and
76// resolves when the config object is ready for action
77conf.load().then(() => {
78  conf.validate()
79  console.log('loaded ok! some-key = ' + conf.get('some-key'))
80}).catch(er => {
81  console.error('error loading configs!', er)
82})
83```
84
85## API
86
87The `Config` class is the sole export.
88
89```js
90const Config = require('@npmcli/config')
91```
92
93### static `Config.typeDefs`
94
95The type definitions passed to `nopt` for CLI option parsing and known configuration validation.
96
97### constructor `new Config(options)`
98
99Options:
100
101- `types` Types of all known config values.
102Note that some are effectively given semantic value in the config loading process itself.
103- `shorthands` An object mapping a shorthand value to an array of CLI arguments that replace it.
104- `defaults` Default values for each of the known configuration keys.
105  These should be defined for all configs given a type, and must be valid.
106- `npmPath` The path to the `npm` module, for loading the `builtin` config file.
107- `cwd` Optional, defaults to `process.cwd()`, used for inferring the
108  `localPrefix` and loading the `project` config.
109- `platform` Optional, defaults to `process.platform`.
110Used when inferring the `globalPrefix` from the `execPath`, since this is done differently on Windows.
111- `execPath` Optional, defaults to `process.execPath`.
112Used to infer the
113  `globalPrefix`.
114- `env` Optional, defaults to `process.env`.
115Source of the environment variables for configuration.
116- `argv` Optional, defaults to `process.argv`.
117Source of the CLI options used for configuration.
118
119Returns a `config` object, which is not yet loaded.
120
121Fields:
122
123- `config.globalPrefix` The prefix for `global` operations.
124Set by the
125  `prefix` config value, or defaults based on the location of the
126  `execPath` option.
127- `config.localPrefix` The prefix for `local` operations.
128Set by the
129  `prefix` config value on the CLI only, or defaults to either the `cwd` or its nearest ancestor containing a `node_modules` folder or `package.json` file.
130- `config.sources` A read-only `Map` of the file (or a comment, if no file found, or relevant) to the config level loaded from that source.
131- `config.data` A `Map` of config level to `ConfigData` objects.
132These objects should not be modified directly under any circumstances.
133  - `source` The source where this data was loaded from.
134  - `raw` The raw data used to generate this config data, as it was parsed initially from the environment, config file, or CLI options.
135  - `data` The data object reflecting the inheritance of configs up to this point in the chain.
136  - `loadError` Any errors encountered that prevented the loading of this config data.
137- `config.list` A list sorted in priority of all the config data objects in the prototype chain.
138`config.list[0]` is the `cli` level,
139  `config.list[1]` is the `env` level, and so on.
140- `cwd` The `cwd` param
141- `env` The `env` param
142- `argv` The `argv` param
143- `execPath` The `execPath` param
144- `platform` The `platform` param
145- `defaults` The `defaults` param
146- `shorthands` The `shorthands` param
147- `types` The `types` param
148- `npmPath` The `npmPath` param
149- `globalPrefix` The effective `globalPrefix`
150- `localPrefix` The effective `localPrefix`
151- `prefix` If `config.get('global')` is true, then `globalPrefix`, otherwise `localPrefix`
152- `home` The user's home directory, found by looking at `env.HOME` or calling `os.homedir()`.
153- `loaded` A boolean indicating whether or not configs are loaded
154- `valid` A getter that returns `true` if all the config objects are valid.
155  Any data objects that have been modified with `config.set(...)` will be re-evaluated when `config.valid` is read.
156
157### `config.load()`
158
159Load configuration from the various sources of information.
160
161Returns a `Promise` that resolves when configuration is loaded, and fails if a fatal error is encountered.
162
163### `config.find(key)`
164
165Find the effective place in the configuration levels a given key is set.
166Returns one of: `cli`, `env`, `project`, `user`, `global`, `builtin`, or
167`default`.
168
169Returns `null` if the key is not set.
170
171### `config.get(key, where = 'cli')`
172
173Load the given key from the config stack.
174
175### `config.set(key, value, where = 'cli')`
176
177Set the key to the specified value, at the specified level in the config stack.
178
179### `config.delete(key, where = 'cli')`
180
181Delete the configuration key from the specified level in the config stack.
182
183### `config.validate(where)`
184
185Verify that all known configuration options are set to valid values, and log a warning if they are invalid.
186
187Invalid auth options will cause this method to throw an error with a `code` property of `ERR_INVALID_AUTH`, and a `problems` property listing the specific concerns with the current configuration.
188
189If `where` is not set, then all config objects are validated.
190
191Returns `true` if all configs are valid.
192
193Note that it's usually enough (and more efficient) to just check
194`config.valid`, since each data object is marked for re-evaluation on every
195`config.set()` operation.
196
197### `config.repair(problems)`
198
199Accept an optional array of problems (as thrown by `config.validate()`) and perform the necessary steps to resolve them.
200If no problems are provided, this method will call `config.validate()` internally to retrieve them.
201
202Note that you must `await config.save('user')` in order to persist the changes.
203
204### `config.isDefault(key)`
205
206Returns `true` if the value is coming directly from the default definitions, if the current value for the key config is coming from any other source, returns `false`.
207
208This method can be used for avoiding or tweaking default values, e.g:
209
210>  Given a global default definition of foo='foo' it's possible to read that value such as:
211>
212>  ```js
213>     const save = config.get('foo')
214>  ```
215>
216>  Now in a different place of your app it's possible to avoid using the `foo` default value, by checking to see if the current config value is currently one that was defined by the default definitions:
217>
218>  ```js
219>     const save = config.isDefault('foo') ? 'bar' : config.get('foo')
220>  ```
221
222### `config.save(where)`
223
224Save the config file specified by the `where` param.
225Must be one of
226`project`, `user`, `global`, `builtin`.
227