# @amazebot/config

> Centralised app configuration loaded from ENV, CLI and/or JSON.

Latest version **0.1.1** (published 2018-12-11) · MIT license · 0 weekly downloads

## Install

```sh
npm install @amazebot/config
pnpm add @amazebot/config
yarn add @amazebot/config
bun add @amazebot/config
```

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.1.1 |
| Published | 2018-12-11 |
| First published | 2018-12-06 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Node | > 8.0.0 |
| Dependencies | 3 |
| Unpacked size | 15.1 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 1 |
| Author | Tim Kinnane |
| Maintainers | timkinnane |
| Keywords | util, typescript, config, settings, yargs |

## Links

- npm: https://www.npmjs.com/package/@amazebot/config
- Repository: git@github.com:Amazebot/util
- Homepage: https://github.com/Amazebot/util/tree/master/packages/config
- npm.io page: https://npm.io/package/@amazebot/config

## Dependencies (3)

- [yargs](https://npm.io/package/yargs.md) ^12.0.5
- [dotenv](https://npm.io/package/dotenv.md) ^6.1.0
- [@types/yargs](https://npm.io/package/@types/yargs.md) ^12.0.1

## Alternatives

- [jsforce](https://npm.io/package/jsforce.md) — 851.2K weekly downloads
- [react-native-qrcode-svg](https://npm.io/package/react-native-qrcode-svg.md) — 693.5K weekly downloads
- [@salesforce/plugin-data](https://npm.io/package/@salesforce/plugin-data.md) — 394.9K weekly downloads
- [@backstage/plugin-search-common](https://npm.io/package/@backstage/plugin-search-common.md) — 308.5K weekly downloads
- [@chain-registry/types](https://npm.io/package/@chain-registry/types.md) — 38.4K weekly downloads

## Recent versions

- 0.1.1 (latest) — 2018-12-11
- 0.1.0 — 2018-12-06

## README

[dotenv]: https://github.com/motdotla/dotenv
[yargs]: https://yargs.js.org/

# ⚙️ Config
Centralised app/module configuration loaded from ENV, CLI and/or JSON.
---

This utility wraps [Yargs][yargs] and [dotenv][dotenv] capabilities with some
simple interfaces for easily managing configuration from various sources.

Can load a single configuration, or use the same options for a series of
instances, loading from different sources using custom prefixes.

Possible config sources include:
  - Command line args
  - Local `.env` file
  - Environment variables
  - Package JSON `'config': {}`
  - `config.json` file

A note on syntax/format. Options are defined and stored with **hyphenated**
names, that match to their command line argument. However, the corresponding key
in JSON would be **camelCase** and the env variable would be **all caps** with
underscore separators.

Please be aware of the semantics:
- **Option**: Defines a possible value type and default.
- **Value**: The current value assigned for an option.
- **Settings**: An object containing all current values.
- **Config**: Loads, gets, sets and extends options.
- **Series**: Collection of configs with the same options.

## Config

### `new Config(options: IOptions, sourcePrefix?: string)`

Config instances accept an initial range of options, which can be extended, for
sharing the config between modules that each add their own options. The options
argument follows the [Yargs][yargs] syntax.

The optional prefix argument on the constructor is applied to the sources for
loading all options.

```ts
import { Config } from '@amazebot/config'
const config = new Config({
  'amazing-enabled': {
    type: 'boolean',
    description: 'Makes everything amazing',
    default: true
  }
}, 'my')
```

In this example, the prefix 'my' would modify the source for the option as
- env variable: `MY_AMAZING_ENABLED`
- package json: `myConfig`
- config file: `my-config.json`

### `.load(keyPrefix?: string)`

Load values for the defined options from all recognised sources:

```ts
import { Config } from '@amazebot/config'
const config = new Config({ 'amazing': { type: 'boolean', default: 'true' } })
config.load()
console.log(config.settings.amazing) // --> true
```

Passing a prefix to the load method modifies the key for all options, allowing
multiple instances to have unique settings, from a common source. e.g. `.env`

```sh
FOO_AMAZING='false'
BAR_AMAZING='true'
```

```ts
import { Config } from '@amazebot/config'
const options = { 'amazing': { type: 'boolean', default: 'true' } }
const foo = new Config(options)
const bar = new Config(options)
foo.load('foo')
foo.load('bar')
console.log(foo.settings.amazing) // --> false
console.log(bar.settings.amazing) // --> true
```

### `.extend(options: IOptions)`

Add more options, possibly after initial options loaded (requiring load again).
Calling load after extend will merge new options with the initial set.

```ts
// index.ts
export * from './app.ts'
export * from './module.ts'
```

```ts
// app.ts
import { Config } from '@amazebot/config'
export const app = {
  config: new Config({ 'amazing': { type: 'boolean', default: 'true' } }),
  start: () => {
    config.load()
    console.log(config.settings)
  }
}
```

```ts
// module.ts
import { app } from '.'
app.config.extend({ 'more-amazing': { type: 'boolean', default: 'false' } })
app.start() // --> { 'amazing': true, 'more-amazing': false }
```

### `.get(key: string)`

Gets the loaded value from settings.

```ts
import { Config } from '@amazebot/config'
const config = new Config({ 'amazing': { type: 'boolean', default: 'true' } })
config.load()
config.get('amazing') // --> true
```

### `.set(key: string, value: any)`

Set the value. Set values override loaded ones.

```sh
AMAZING='true'
```

```ts
import { Config } from '@amazebot/config'
const config = new Config({ 'amazing': { type: 'boolean' } })
config.load()
config.get('amazing') // --> true
config.set('amazing', false)
config.get('amazing') // --> false
```

```ts
import { Config } from '@amazebot/config'
const config = new Config({ 'amazing': { type: 'boolean' } })
config.set('amazing', false)
config.load()
config.get('amazing') // --> false
```

### `.reset()`

Clear any loaded or set values.

```ts
import { Config } from '@amazebot/config'
const config = new Config({ 'amazing': { type: 'boolean', default: 'true' } })
config.load()
config.set('amazing', false)
config.reset()
config.get('amazing') // --> true
```

## ConfigMap

Config Maps allow defining a set of config instances with common options and
defaults, with different values assigned by loading a unique prefixed source.

### `new ConfigMap(options: IOptions, sourcePrefix?: string)`

The constructor uses the same arguments as normal configs. The map contains a
collection of config instance `items`, always with at least one `default` item.

```ts
import { ConfigMap } from '@amazebot/config'
const map = new ConfigMap({ 'amazing': { type: 'boolean', default: 'true' } })
console.log(map.items.default.settings['amazing'].default) // --> true
```

### `.item(key: string)`

Get a config item by it's key, creating if it didn't exist.

```ts
import { ConfigMap } from '@amazebot/config'
const map = new ConfigMap({ 'amazing': { type: 'boolean', default: 'true' } })
map.item('alt')
console.log(map.items.alt.settings['amazing'].default) // --> true
```

### `.load()`

Loads every item's config, using it's key as a prefix for value sources.

```sh
AMAZING='true'
ALT_AMAZING='false'
```

```ts
import { ConfigMap } from '@amazebot/config'
const map = new ConfigMap({ 'amazing': { type: 'boolean' } })
map.item('alt')
map.load()
map.item('default').get('amazing') // --> true
map.item('alt').get('amazing') // --> false
```

### `.extend(options: IOptions)`

Extends every config item's options and for any newly created items.

```ts
import { ConfigMap } from '@amazebot/config'
const map = new ConfigMap({ 'amazing': { type: 'boolean' } })
map.extend({ 'more-amazing': { type: 'boolean', default: true } })
map.item('alt')
map.load()
map.item('alt').get('more-amazing') // --> true
```

---
_Source: https://npm.io/package/@amazebot/config · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._