# confab

> fabulous configuration!

Latest version **0.1.5** (published 2021-03-31) · MIT license · 0 weekly downloads

## Install

```sh
npm install confab
pnpm add confab
yarn add confab
bun add confab
```

## 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.5 |
| Published | 2021-03-31 |
| First published | 2015-01-15 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 1 |
| Unpacked size | 12.8 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 4 |
| Author | RJ Zaworski |
| Maintainers | rjz |
| Keywords | config, configuration, environment, json |

## Links

- npm: https://www.npmjs.com/package/confab
- Repository: https://github.com/rjz/confab
- Homepage: https://github.com/rjz/confab#readme
- Issues: https://github.com/rjz/confab/issues
- npm.io page: https://npm.io/package/confab

## Dependencies (1)

- [object-assign](https://npm.io/package/object-assign.md) ~4.0.1

## Alternatives

- [@mapbox/jsonlint-lines-primitives](https://npm.io/package/@mapbox/jsonlint-lines-primitives.md) — 5.3M weekly downloads
- [reftools](https://npm.io/package/reftools.md) — 3.5M weekly downloads
- [@hey-api/openapi-ts](https://npm.io/package/@hey-api/openapi-ts.md) — 3.5M weekly downloads
- [@mapbox/geojson-rewind](https://npm.io/package/@mapbox/geojson-rewind.md) — 2.4M weekly downloads
- [turbo-stream](https://npm.io/package/turbo-stream.md) — 1.7M weekly downloads

## Recent versions

- 0.1.5 (latest) — 2021-03-31
- 0.1.4 — 2020-09-12
- 0.1.3 — 2020-09-12
- 0.1.2 — 2020-09-12
- 0.1.1 — 2020-09-12
- 0.1.0 — 2016-01-23
- 0.0.9 — 2015-12-01
- 0.0.8 — 2015-09-19
- 0.0.7 — 2015-09-07
- 0.0.6 — 2015-07-08
- 0.0.5 — 2015-06-13
- 0.0.4 — 2015-02-15
- 0.0.3 — 2015-01-15

## README

Confab
===============================================================================

Build configuration objects from chains of recycleable transformations:

[![Build Status](https://travis-ci.org/rjz/confab.png)](https://travis-ci.org/rjz/confab)
[![Coverage Status](https://coveralls.io/repos/rjz/confab/badge.png?branch=master)](https://coveralls.io/r/rjz/confab?branch=master)

```js
// file: myapp.js
'use strict';
var confab = require('confab');

var config = confab([
  confab.loadEnvironment({
    PORT: 'port'
  }),

  confab.defaults({
    role: 'api',
    port: 4500
  }),
]);

console.log(config);
```

With the environment and defaults applied, we see a nicely built configuration:

```sh
$ PORT=3200 node myapp.js
{ role: 'api', port: '3200' }
```

Installation
-------------------------------------------------------------------------------

```sh
$ npm install confab
```


Convention and Configuration
-------------------------------------------------------------------------------

Confab is configuration-first by nature, as the details of configuration may
vary widely from one project to the next. Nevertheless, the built-in
transformations reflect certain opinions.

Namely, configuration should be:

  * **separate**. Keeping configuration isolated from application logic eases
    deployment across multiple environments. Confab encourages developers to
    author complete configurations independent of the application.

  * **predictable**. Like any other exception, errors in configuration should be
    immediately fatal. All confab transformations will fail immediately if
    unexpected conditions are encountered, while the [`required`][confab-required]
    transformation can assert the presence of certain configuration keys.
    Similarly, the [`defaults`][confab-defaults] transformation--while
    unquestionably useful--should be approached with care.

  * **immutable**. The running application should not be concerned with
    configuration changes: if a change must be applied it should be applied to a
    new process. The [`freeze`][confab-freeze] transformation guarantees that a
    config will not change after initialization.

  * **simple**. File-based configs (JSON, YAML, etc.) make
    it easy to nest data inside multiple levels of keys. This is convenient for
    grouping like data, but it is not immediately clear how these data would map
    to (e.g.) environment variables or command-line arguments.
    Sub-configurations can enhance separation between unrelated concerns, but
    they should be used with care.

##### And one non-opinion

  * Command-line parsing, and what impact (if any) arguments should have on the
    configuration is left as a project-specific decision. No transformations
    are provided for command-line support--but you can write your own!

Transformations
-------------------------------------------------------------------------------

Confab ships with transformations for:

  * Loading JSON configurations
  * Mapping environment variables to a configuration object
  * Providing default values
  * Marking required values
  * Locking down the configuration

Complete [reference](http://rjz.github.io/confab/#transforms).

### Additional transformations

Known third-party transformations include:

Name                                 | Description
------------------------------------ | ----------------------------------------
[`loadYaml`][confab-addons]          | load YAML configuration files
[`loadEnvConfigFile`][confab-addons] | load config files from likely locations
[`features`][confab-features]        | declare and toggle config features

### Custom transformations

Every transformation accepts the config object and returns it after any
modifications have been applied. A silly example from the test suite will
multiply any numeric config values by two:

```js
function transformTimesTwo (config) {
  Object.keys(config).forEach(function (k) {
    if (typeof config[k] === 'number') config[k] *= 2;
  });
  return config;
}
```

This filter can then be used like any other:

```js
var config = confab([

  confab.loadJSON([
    './config.json'
  ]),

  transformTimesTwo
]);
```

Test
-------------------------------------------------------------------------------

Lint and run test suite:

```sh
$ npm test
```

Generate code coverage report:

```sh
$ npm run cover
```


License
-------------------------------------------------------------------------------

MIT

[confab-defaults]: http://rjz.github.io/confab/#transforms-defaults
[confab-required]: http://rjz.github.io/confab/#transforms-required
[confab-freeze]: http://rjz.github.io/confab/#transforms-freeze
[confab-addons]: https://github.com/kenjones-cisco/confab-addons
[confab-features]: https://github.com/rjz/confab-features

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