diff options
Diffstat (limited to 'node_modules/cosmiconfig/README.md')
| -rw-r--r-- | node_modules/cosmiconfig/README.md | 494 |
1 files changed, 494 insertions, 0 deletions
diff --git a/node_modules/cosmiconfig/README.md b/node_modules/cosmiconfig/README.md new file mode 100644 index 00000000..4c133525 --- /dev/null +++ b/node_modules/cosmiconfig/README.md @@ -0,0 +1,494 @@ +# cosmiconfig + +[](https://travis-ci.org/davidtheclark/cosmiconfig) [](https://ci.appveyor.com/project/davidtheclark/cosmiconfig/branch/master) +[](https://codecov.io/gh/davidtheclark/cosmiconfig) + +Cosmiconfig searches for and loads configuration for your program. + +It features smart defaults based on conventional expectations in the JavaScript ecosystem. +But it's also flexible enough to search wherever you'd like to search, and load whatever you'd like to load. + +By default, Cosmiconfig will start where you tell it to start and search up the directory tree for the following: + +- a `package.json` property +- a JSON or YAML, extensionless "rc file" +- an "rc file" with the extensions `.json`, `.yaml`, `.yml`, or `.js`. +- a `.config.js` CommonJS module + +For example, if your module's name is "soursocks", cosmiconfig will search up the directory tree for configuration in the following places: + +- a `soursocks` property in `package.json` +- a `.soursocksrc` file in JSON or YAML format +- a `.soursocksrc.json` file +- a `.soursocksrc.yaml`, `.soursocksrc.yml`, or `.soursocksrc.js` file +- a `soursocks.config.js` file exporting a JS object + +Cosmiconfig continues to search up the directory tree, checking each of these places in each directory, until it finds some acceptable configuration (or hits the home directory). + +👀 **Looking for the v4 docs?** +v5 involves significant revisions to Cosmiconfig's API, allowing for much greater flexibility and clarifying some things. +If you have trouble switching from v4 to v5, please file an issue. +If you are still using v4, those v4 docs are available [in the `4.0.0` tag](https://github.com/davidtheclark/cosmiconfig/tree/4.0.0). + +## Table of contents + +- [Installation](#installation) +- [Usage](#usage) +- [Result](#result) +- [cosmiconfig()](#cosmiconfig-1) + - [moduleName](#modulename) +- [explorer.search()](#explorersearch) + - [searchFrom](#searchfrom) +- [explorer.searchSync()](#explorersearchsync) +- [explorer.load()](#explorerload) +- [explorer.loadSync()](#explorerloadsync) +- [explorer.clearLoadCache()](#explorerclearloadcache) +- [explorer.clearSearchCache()](#explorerclearsearchcache) +- [explorer.clearCaches()](#explorerclearcaches) +- [cosmiconfigOptions](#cosmiconfigoptions) + - [searchPlaces](#searchplaces) + - [loaders](#loaders) + - [packageProp](#packageprop) + - [stopDir](#stopdir) + - [cache](#cache) + - [transform](#transform) + - [ignoreEmptySearchPlaces](#ignoreemptysearchplaces) +- [Caching](#caching) +- [Differences from rc](#differences-from-rc) +- [Contributing & Development](#contributing--development) + +## Installation + +``` +npm install cosmiconfig +``` + +Tested in Node 4+. + +## Usage + +Create a Cosmiconfig explorer, then either `search` for or directly `load` a configuration file. + +```js +const cosmiconfig = require('cosmiconfig'); +// ... +const explorer = cosmiconfig(moduleName); + +// Search for a configuration by walking up directories. +// See documentation for search, below. +explorer.search() + .then((result) => { + // result.config is the parsed configuration object. + // result.filepath is the path to the config file that was found. + // result.isEmpty is true if there was nothing to parse in the config file. + }) + .catch((error) => { + // Do something constructive. + }); + +// Load a configuration directly when you know where it should be. +// The result object is the same as for search. +// See documentation for load, below. +explorer.load(pathToConfig).then(..); + +// You can also search and load synchronously. +const searchedFor = explorer.searchSync(); +const loaded = explorer.loadSync(pathToConfig); +``` + +## Result + +The result object you get from `search` or `load` has the following properties: + +- **config:** The parsed configuration object. `undefined` if the file is empty. +- **filepath:** The path to the configuration file that was found. +- **isEmpty:** `true` if the configuration file is empty. This property will not be present if the configuration file is not empty. + +## cosmiconfig() + +```js +const explorer = cosmiconfig(moduleName[, cosmiconfigOptions]) +``` + +Creates a cosmiconfig instance ("explorer") configured according to the arguments, and initializes its caches. + +### moduleName + +Type: `string`. **Required.** + +Your module name. This is used to create the default [`searchPlaces`] and [`packageProp`]. + +**[`cosmiconfigOptions`] are documented below.** +You may not need them, and should first read about the functions you'll use. + +## explorer.search() + +```js +explorer.search([searchFrom]).then(result => {..}) +``` + +Searches for a configuration file. Returns a Promise that resolves with a [result] or with `null`, if no configuration file is found. + +You can do the same thing synchronously with [`searchSync()`]. + +Let's say your module name is `goldengrahams` so you initialized with `const explorer = cosmiconfig('goldengrahams');`. +Here's how your default [`search()`] will work: + +- Starting from `process.cwd()` (or some other directory defined by the `searchFrom` argument to [`search()`]), look for configuration objects in the following places: + 1. A `goldengrahams` property in a `package.json` file. + 2. A `.goldengrahamsrc` file with JSON or YAML syntax. + 3. A `.goldengrahamsrc.json` file. + 4. A `.goldengrahamsrc.yaml`, `.goldengrahamsrc.yml`, or `.goldengrahamsrc.js` file. + 5. A `goldengrahams.config.js` JS file exporting the object. +- If none of those searches reveal a configuration object, move up one directory level and try again. + So the search continues in `./`, `../`, `../../`, `../../../`, etc., checking the same places in each directory. +- Continue searching until arriving at your home directory (or some other directory defined by the cosmiconfig option [`stopDir`]). +- If at any point a parseable configuration is found, the [`search()`] Promise resolves with its [result] \(or, with [`searchSync()`], the [result] is returned). +- If no configuration object is found, the [`search()`] Promise resolves with `null` (or, with [`searchSync()`], `null` is returned). +- If a configuration object is found *but is malformed* (causing a parsing error), the [`search()`] Promise rejects with that error (so you should `.catch()` it). (Or, with [`searchSync()`], the error is thrown.) + +**If you know exactly where your configuration file should be, you can use [`load()`], instead.** + +**The search process is highly customizable.** +Use the cosmiconfig options [`searchPlaces`] and [`loaders`] to precisely define where you want to look for configurations and how you want to load them. + +### searchFrom + +Type: `string`. +Default: `process.cwd()`. + +A filename. +[`search()`] will start its search here. + +If the value is a directory, that's where the search starts. +If it's a file, the search starts in that file's directory. + +## explorer.searchSync() + +```js +const result = explorer.searchSync([searchFrom]); +``` + +Synchronous version of [`search()`]. + +Returns a [result] or `null`. + +## explorer.load() + +```js +explorer.load(loadPath).then(result => {..}) +``` + +Loads a configuration file. Returns a Promise that resolves with a [result] or rejects with an error (if the file does not exist or cannot be loaded). + +Use `load` if you already know where the configuration file is and you just need to load it. + +```js +explorer.load('load/this/file.json'); // Tries to load load/this/file.json. +``` + +If you load a `package.json` file, the result will be derived from whatever property is specified as your [`packageProp`]. + +## explorer.loadSync() + +```js +const result = explorer.loadSync(loadPath); +``` + +Synchronous version of [`load()`]. + +Returns a [result]. + +## explorer.clearLoadCache() + +Clears the cache used in [`load()`]. + +## explorer.clearSearchCache() + +Clears the cache used in [`search()`]. + +## explorer.clearCaches() + +Performs both [`clearLoadCache()`] and [`clearSearchCache()`]. + +## cosmiconfigOptions + +### searchPlaces + +Type: `Array<string>`. +Default: See below. + +An array of places that [`search()`] will check in each directory as it moves up the directory tree. +Each place is relative to the directory being searched, and the places are checked in the specified order. + +**Default `searchPlaces`:** + +```js +[ + 'package.json', + `.${moduleName}rc`, + `.${moduleName}rc.json`, + `.${moduleName}rc.yaml`, + `.${moduleName}rc.yml`, + `.${moduleName}rc.js`, + `${moduleName}.config.js`, +] +``` + +Create your own array to search more, fewer, or altogether different places. + +Every item in `searchPlaces` needs to have a loader in [`loaders`] that corresponds to its extension. +(Common extensions are covered by default loaders.) +Read more about [`loaders`] below. + +`package.json` is a special value: When it is included in `searchPlaces`, Cosmiconfig will always parse it as JSON and load a property within it, not the whole file. +That property is defined with the [`packageProp`] option, and defaults to your module name. + +Examples, with a module named `porgy`: + +```js +// Disallow extensions on rc files: +[ + 'package.json', + '.porgyrc', + 'porgy.config.js' +] + +// ESLint searches for configuration in these places: +[ + '.eslintrc.js', + '.eslintrc.yaml', + '.eslintrc.yml', + '.eslintrc.json', + '.eslintrc', + 'package.json' +] + +// Babel looks in fewer places: +[ + 'package.json', + '.babelrc' +] + +// Maybe you want to look for a wide variety of JS flavors: +[ + 'porgy.config.js', + 'porgy.config.mjs', + 'porgy.config.ts', + 'porgy.config.coffee' +] +// ^^ You will need to designate custom loaders to tell +// Cosmiconfig how to handle these special JS flavors. + +// Look within a .config/ subdirectory of every searched directory: +[ + 'package.json', + '.porgyrc', + '.config/.porgyrc', + '.porgyrc.json', + '.config/.porgyrc.json' +] +``` + +### loaders + +Type: `Object`. +Default: See below. + +An object that maps extensions to the loader functions responsible for loading and parsing files with those extensions. + +Cosmiconfig exposes its default loaders for `.js`, `.json`, and `.yaml` as `cosmiconfig.loadJs`, `cosmiconfig.loadJson`, and `cosmiconfig.loadYaml`, respectively. + +**Default `loaders`:** + +```js +{ + '.json': cosmiconfig.loadJson, + '.yaml': cosmiconfig.loadYaml, + '.yml': cosmiconfig.loadYaml, + '.js': cosmiconfig.loadJs, + noExt: cosmiconfig.loadYaml +} +``` + +(YAML is a superset of JSON; which means YAML parsers can parse JSON; which is how extensionless files can be either YAML *or* JSON with only one parser.) + +**If you provide a `loaders` object, your object will be *merged* with the defaults.** +So you can override one or two without having to override them all. + +**Keys in `loaders`** are extensions (starting with a period), or `noExt` to specify the loader for files *without* extensions, like `.soursocksrc`. + +**Values in `loaders`** are either a loader function (described below) or an object with `sync` and/or `async` properties, whose values are loader functions. + +**The most common use case for custom loaders value is to load extensionless `rc` files as strict JSON**, instead of JSON *or* YAML (the default). +To accomplish that, provide the following `loaders` value: + +```js +{ + noExt: cosmiconfig.loadJson +} +``` + +If you want to load files that are not handled by the loader functions Cosmiconfig exposes, you can write a custom loader function. + +**Use cases for custom loader function:** + +- Allow configuration syntaxes that aren't handled by Cosmiconfig's defaults, like JSON5, INI, or XML. +- Allow ES2015 modules from `.mjs` configuration files. +- Parse JS files with Babel before deriving the configuration. + +**Custom loader functions** have the following signature: + +```js +// Sync +(filepath: string, content: string) => Object | null + +// Async +(filepath: string, content: string) => Object | null | Promise<Object | null> +``` + +Cosmiconfig reads the file when it checks whether the file exists, so it will provide you with both the file's path and its content. +Do whatever you need to, and return either a configuration object or `null` (or, for async-only loaders, a Promise that resolves with one of those). +`null` indicates that no real configuration was found and the search should continue. + +It's easiest if you make your custom loader function synchronous. +Then it can be used regardless of whether you end up calling [`search()`] or [`searchSync()`], [`load()`] or [`loadSync()`]. +If you want or need to provide an async-only loader, you can do so by making the value of `loaders` an object with an `async` property whose value is the async loader. +You can also add a `sync` property to designate a sync loader, if you want to use both async and sync search and load functions. + +A few things to note: + +- If you use a custom loader, be aware of whether it's sync or async and how that aligned with your usage of sync or async search and load functions. +- **Special JS syntax can also be handled by using a `require` hook**, because `cosmiconfig.loadJs` just uses `require`. + Whether you use custom loaders or a `require` hook is up to you. + +Examples: + +```js +// Allow JSON5 syntax: +{ + '.json': json5Loader +} + +// Allow XML, and treat sync and async separately: +{ + '.xml': { async: asyncXmlLoader, sync: syncXmlLoader } +} + +// Allow a special configuration syntax of your own creation: +{ + '.special': specialLoader +} + +// Allow many flavors of JS, using custom loaders: +{ + '.mjs': esmLoader, + '.ts': typeScriptLoader, + '.coffee': coffeeScriptLoader +} + +// Allow many flavors of JS but rely on require hooks: +{ + '.mjs': cosmiconfig.loadJs, + '.ts': cosmiconfig.loadJs, + '.coffee': cosmiconfig.loadJs +} +``` + +### packageProp + +Type: `string`. +Default: `` `${moduleName}` ``. + +Name of the property in `package.json` to look for. + +### stopDir + +Type: `string`. +Default: Absolute path to your home directory. + +Directory where the search will stop. + +### cache + +Type: `boolean`. +Default: `true`. + +If `false`, no caches will be used. +Read more about ["Caching"](#caching) below. + +### transform + +Type: `(Result) => Promise<Result> | Result`. + +A function that transforms the parsed configuration. Receives the [result]. + +If using [`search()`] or [`load()`] \(which are async), the transform function can return the transformed result or return a Promise that resolves with the transformed result. +If using [`searchSync()`] or [`loadSync()`], the function must be synchronous and return the transformed result. + +The reason you might use this option — instead of simply applying your transform function some other way — is that *the transformed result will be cached*. If your transformation involves additional filesystem I/O or other potentially slow processing, you can use this option to avoid repeating those steps every time a given configuration is searched or loaded. + +### ignoreEmptySearchPlaces + +Type: `boolean`. +Default: `true`. + +By default, if [`search()`] encounters an empty file (containing nothing but whitespace) in one of the [`searchPlaces`], it will ignore the empty file and move on. +If you'd like to load empty configuration files, instead, set this option to `false`. + +Why might you want to load empty configuration files? +If you want to throw an error, or if an empty configuration file means something to your program. + +## Caching + +As of v2, cosmiconfig uses caching to reduce the need for repetitious reading of the filesystem or expensive transforms. Every new cosmiconfig instance (created with `cosmiconfig()`) has its own caches. + +To avoid or work around caching, you can do the following: + +- Set the `cosmiconfig` option [`cache`] to `false`. +- Use the cache-clearing methods [`clearLoadCache()`], [`clearSearchCache()`], and [`clearCaches()`]. +- Create separate instances of cosmiconfig (separate "explorers"). + +## Differences from [rc](https://github.com/dominictarr/rc) + +[rc](https://github.com/dominictarr/rc) serves its focused purpose well. cosmiconfig differs in a few key ways — making it more useful for some projects, less useful for others: + +- Looks for configuration in some different places: in a `package.json` property, an rc file, a `.config.js` file, and rc files with extensions. +- Built-in support for JSON, YAML, and CommonJS formats. +- Stops at the first configuration found, instead of finding all that can be found up the directory tree and merging them automatically. +- Options. +- Asynchronous by default (though can be run synchronously). + +## Contributing & Development + +Please note that this project is released with a [Contributor Code of Conduct](CODE_OF_CONDUCT.md). By participating in this project you agree to abide by its terms. + +And please do participate! + +[result]: #result + +[`load()`]: #explorerload + +[`loadsync()`]: #explorerloadsync + +[`search()`]: #explorersearch + +[`searchsync()`]: #explorersearchsync + +[`clearloadcache()`]: #explorerclearloadcache + +[`clearsearchcache()`]: #explorerclearsearchcache + +[`clearcaches()`]: #explorerclearcaches + +[`packageprop`]: #packageprop + +[`cache`]: #cache + +[`stopdir`]: #stopdir + +[`searchplaces`]: #searchplaces + +[`loaders`]: #loaders + +[`cosmiconfigoptions`]: #cosmiconfigoptions |