nav tabs on admin dashboard

This commit is contained in:
2019-03-07 00:20:34 -06:00
parent f73d6ae228
commit e4f473f376
11661 changed files with 216240 additions and 1544253 deletions
+430 -161
View File
@@ -1,23 +1,61 @@
# cosmiconfig
[![Build Status](https://img.shields.io/travis/davidtheclark/cosmiconfig/master.svg?label=unix%20build)](https://travis-ci.org/davidtheclark/cosmiconfig) [![Build status](https://img.shields.io/appveyor/ci/davidtheclark/cosmiconfig/master.svg?label=windows%20build)](https://ci.appveyor.com/project/davidtheclark/cosmiconfig/branch/master)
[![codecov](https://codecov.io/gh/davidtheclark/cosmiconfig/branch/master/graph/badge.svg)](https://codecov.io/gh/davidtheclark/cosmiconfig)
Find and load a configuration object from
- a `package.json` property (anywhere up the directory tree)
- a JSON or YAML "rc file" (anywhere up the directory tree)
- a `.config.js` CommonJS module (anywhere up the directory tree)
Cosmiconfig searches for and loads configuration for your program.
For example, if your module's name is "soursocks," cosmiconfig will search out configuration in the following places:
- a `soursocks` property in `package.json` (anywhere up the directory tree)
- a `.soursocksrc` file in JSON or YAML format (anywhere up the directory tree)
- a `soursocks.config.js` file exporting a JS object (anywhere up the directory tree)
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.
cosmiconfig continues to search in these places all the way up the directory tree until it finds acceptable configuration (or hits the home directory).
By default, Cosmiconfig will start where you tell it to start and search up the directory tree for the following:
Additionally, all of these search locations are configurable: you can customize filenames or turn off any location.
- 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
You can also look for rc files with extensions, e.g. `.soursocksrc.json` or `.soursocksrc.yaml`.
You may like extensions on your rc files because you'll get syntax highlighting and linting in text editors.
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
@@ -29,202 +67,405 @@ Tested in Node 4+.
## Usage
Create a Cosmiconfig explorer, then either `search` for or directly `load` a configuration file.
```js
var cosmiconfig = require('cosmiconfig');
const cosmiconfig = require('cosmiconfig');
// ...
const explorer = cosmiconfig(moduleName);
var explorer = cosmiconfig(yourModuleName[, options]);
explorer.load()
// 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.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((parsingError) => {
// do something constructive
.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);
```
The function `cosmiconfig()` searches for a configuration object and returns a Promise,
which resolves with an object containing the information you're looking for.
## Result
You can also pass option `sync: true` to load the config synchronously, returning the config itself.
The result object you get from `search` or `load` has the following properties:
So let's say `var yourModuleName = 'goldengrahams'` — here's how cosmiconfig will work:
- **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.
- Starting from `process.cwd()` (or some other directory defined by the `searchPath` argument to `load()`), it looks for configuration objects in three places, in this order:
1. A `goldengrahams` property in a `package.json` file (or some other property defined by `options.packageProp`);
2. A `.goldengrahamsrc` file with JSON or YAML syntax (or some other filename defined by `options.rc`);
3. A `goldengrahams.config.js` JS file exporting the object (or some other filename defined by `options.js`).
- If none of those searches reveal a configuration object, it moves up one directory level and tries again. So the search continues in `./`, `../`, `../../`, `../../../`, etc., checking those three locations in each directory.
- It continues searching until it arrives at your home directory (or some other directory defined by `options.stopDir`).
- If at any point a parseable configuration is found, the `cosmiconfig()` Promise resolves with its result object.
- If no configuration object is found, the `cosmiconfig()` Promise resolves with `null`.
- If a configuration object is found *but is malformed* (causing a parsing error), the `cosmiconfig()` Promise rejects and shares that error (so you should `.catch()` it).
## cosmiconfig()
All this searching can be short-circuited by passing `options.configPath` to specify a file.
cosmiconfig will read that file and try parsing it as JSON, YAML, or JS.
```js
const explorer = cosmiconfig(moduleName[, cosmiconfigOptions])
```
## Caching
Creates a cosmiconfig instance ("explorer") configured according to the arguments, and initializes its caches.
As of v2, cosmiconfig uses a few caches to reduce the need for repetitious reading of the filesystem. Every new cosmiconfig instance (created with `cosmiconfig()`) has its own caches.
### moduleName
To avoid or work around caching, you can
- create separate instances of cosmiconfig, or
- set `cache: false` in your options.
- use the cache clearing methods documented below.
Type: `string`. **Required.**
## API
Your module name. This is used to create the default [`searchPlaces`] and [`packageProp`].
### `var explorer = cosmiconfig(moduleName[, options])`
**[`cosmiconfigOptions`] are documented below.**
You may not need them, and should first read about the functions you'll use.
Creates a cosmiconfig instance (i.e. explorer) configured according to the arguments, and initializes its caches.
## explorer.search()
#### moduleName
```js
explorer.search([searchFrom]).then(result => {..})
```
Type: `string`
Searches for a configuration file. Returns a Promise that resolves with a [result] or with `null`, if no configuration file is found.
You module name. This is used to create the default filenames that cosmiconfig will look for.
You can do the same thing synchronously with [`searchSync()`].
#### Options
Let's say your module name is `goldengrahams` so you initialized with `const explorer = cosmiconfig('goldengrahams');`.
Here's how your default [`search()`] will work:
##### packageProp
- 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.)
Type: `string` or `false`
Default: `'[moduleName]'`
**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
Type: `Object`.
Possible options are documented below.
### 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 or use one from NPM if it exists.
**Third-party loaders:**
- [@endemolshinegroup/cosmiconfig-typescript-loader](https://github.com/EndemolShineGroup/cosmiconfig-typescript-loader)
**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.
If `false`, cosmiconfig will not look in `package.json` files.
Use periods to describe a path to nested properties. For example, the value `'configs.myPackage'` will get you the `"myPackage"` value in a `package.json` like this:
##### rc
```json
{
"configs": {
"myPackage": {..}
}
}
```
Type: `string` or `false`
Default: `'.[moduleName]rc'`
### stopDir
Name of the "rc file" to look for, which can be formatted as JSON or YAML.
If `false`, cosmiconfig will not look for an rc file.
If `rcExtensions: true`, the rc file can also have extensions that specify the syntax, e.g. `.[moduleName]rc.json`.
You may like extensions on your rc files because you'll get syntax highlighting and linting in text editors.
Also, with `rcExtensions: true`, you can use JS modules as rc files, e.g. `.[moduleName]rc.js`.
##### js
Type: `string` or `false`
Default: `'[moduleName].config.js'`
Name of a JS file to look for, which must export the configuration object.
If `false`, cosmiconfig will not look for a JS file.
##### rcStrictJson
Type: `boolean`
Default: `false`
If `true`, cosmiconfig will expect rc files to be strict JSON. No YAML permitted, and no sloppy JSON.
By default, rc files are parsed with [js-yaml](https://github.com/nodeca/js-yaml), which is
more permissive with punctuation than standard strict JSON.
##### rcExtensions
Type: `boolean`
Default: `false`
If `true`, cosmiconfig will look for rc files with extensions, in addition to rc files without.
This adds a few steps to the search process.
Instead of *just* looking for `.goldengrahamsrc` (no extension), it will also look for the following, in this order:
- `.goldengrahamsrc.json`
- `.goldengrahamsrc.yaml`
- `.goldengrahamsrc.yml`
- `.goldengrahamsrc.js`
##### stopDir
Type: `string`
Default: Absolute path to your home directory
Type: `string`.
Default: Absolute path to your home directory.
Directory where the search will stop.
##### cache
### cache
Type: `boolean`
Default: `true`
Type: `boolean`.
Default: `true`.
If `false`, no caches will be used.
Read more about ["Caching"](#caching) below.
##### sync
### transform
Type: `boolean`
Default: `false`
Type: `(Result) => Promise<Result> | Result`.
If `true`, config will be loaded synchronously.
A function that transforms the parsed configuration. Receives the [result].
##### transform
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.
Type: `Function`
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.
A function that transforms the parsed configuration. Receives the result object with `config` and `filepath` properties.
### ignoreEmptySearchPlaces
If the option `sync` is `false` (default), the function must return a Promise that resolves with the transformed result.
If the option `sync` is `true`, though, `transform` should be a synchronous function which returns the transformed result.
Type: `boolean`.
Default: `true`.
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 loaded.
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`.
##### configPath
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.
Type: `string`
## Caching
If provided, cosmiconfig will load and parse a config from this path, and will not perform its usual search.
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.
##### format
To avoid or work around caching, you can do the following:
Type: `'json' | 'yaml' | 'js'`
The expected file format for the config loaded from `configPath`.
If not specified, cosmiconfig will try to infer the format using the extension name (if it has one).
In the event that the file does not have an extension or the extension is unrecognized, cosmiconfig will try to parse it as a JSON, YAML, or JS file.
### Instance methods (on `explorer`)
#### `load([searchPath, configPath])`
Find and load a configuration file. Returns a Promise that resolves with `null`, if nothing is found, or an object with two properties:
- `config`: The loaded and parsed configuration.
- `filepath`: The filepath where this configuration was found.
You should provide *either* `searchPath` *or* `configPath`. Use `configPath` if you know the path of the configuration file you want to load. Note that `configPath` takes priority over `searchPath` if both parameters are specified.
```js
explorer.load()
explorer.load('start/search/here');
explorer.load('start/search/at/this/file.css');
explorer.load(null, 'load/this/file.json');
```
If you provide `searchPath`, cosmiconfig will start its search at `searchPath` and continue to search up the directory tree, as documented above.
By default, `searchPath` is set to `process.cwd()`.
If you provide `configPath` (i.e. you already know where the configuration is that you want to load), cosmiconfig will try to read and parse that file. Note that the [`format` option](#format) is applicable for this as well.
#### `clearFileCache()`
Clears the cache used when you provide a `configPath` argument to `load`.
#### `clearDirectoryCache()`
Clears the cache used when you provide a `searchPath` argument to `load`.
#### `clearCaches()`
Performs both `clearFileCache()` and `clearDirectoryCache()`.
- 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)
@@ -238,6 +479,34 @@ Performs both `clearFileCache()` and `clearDirectoryCache()`.
## Contributing & Development
Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.
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