@packmate/adapt v2.1.6

@packmate/adapt

Flexible configuration and environment variable management for Node.js applications.

For a quickstart, see the usage example.

Installation

npm install @packmate/adapt

The Configuration Function

Usage

const configureAdapt = require('@packmate/adapt')

Syntax

configureAdapt(options)

Arguments

Returns

Exceptions

Throws a standard Error if:

• The configuration object is not present.
• The environment object is not present.
• The environment object does not contain the mode key.

The Options Object

The Configuration Object

The configuration object contains the configuration data for your application. It can contain special keys and values.

Example Structure

{
  api: {
    keys: {
      _default: 'bcd-234',
      staging: 'abc-123'
      production: '[production_key]'
    }
  },

  general: {
    arbitrary_list: [ 1, 2, 3 ],
    number: 5,
    release_date: '2020-01-01'
  }
}

Normal Keys

Normal keys can be accessed by name with the selecting function:

adapt('general.arbitrary_list') // => [ 1, 2, 3 ]
adapt('general.number') // => 5
adapt('general.release_date') // => '2020-01-01'

Special Keys

Plural Keys

Plural keys, such as api.keys above, will be accessed when the singular form of the selector (api.key) can't be found.

The value returned will be based on the mode defined in the environment object. If the mode matches a key within the plural key (such as api.keys.production), that mode-specific value will be returned.

// With environment = { mode: 'staging' }:
adapt('api.key') // => 'abc-123'

The _default Key

The _default key may be defined as a child of a plural key (api.keys._default). This key will be accessed if no key matching the mode can be found within the plural key.

// With environment = { mode: 'development' }:
adapt('api.key') // => 'bcd-234'

Special Values

Environment Values

Environment values are surrounded in brackets ([value_from_environment]). This tells the selecting function to search the environment object for a matching value.

This is useful for private values that you don't want committed to source control.

// With environment = { mode: 'production', production_key: 'xyz-345' }
adapt('api.token') // => 'xyz-345'

The Environment Object

The environment object contains the application's environment data and mode.

The simplest form of this could be to use process.env:

const adapt = require('@packmate/adapt')({
  configuration: {},
  environment: process.env
})

You can also mix together sources. This is useful when you want to keep an environment file (or files) on your local machine, while relying on private values in remote environments.

let local = {}
try { local = require('./environment.json') } catch {}

const adapt = require('@packmate/adapt')({
  configuration: {},

  environment: {
    ...local,
    ...process.env
  }
})

Example Structure

{
  mode: 'staging',

  production_key: 'xyz-654',
  private_api_key: 'vfx-125'
}

Special Keys

The Mode Key

The environment object must contain a mode key which contains the running mode of the application (i.e. development or production).

This tells the selecting function which part of the configuration object to use when a plural key is accessed.

For an example, see the usage example.

The Selecting Function

The selecting function is generated by the configuration function and can be used throughout your application to access configuration data.

Syntax

adapt(selector)

Arguments

Example

adapt('api.key')

Exceptions

Throws a standard Error if:

• No selector is present.
• A matching key cannot be found in the configuration object.
• The value of a selected environment value is undefined.

Usage Example

environment.json

{
  "api_key_development": "development_value"
}

adapt.json

{
  "api": {
    "keys": {
      "_default": "[api_key_development]",
      "production": "[api_key_production]"
    }
  }
}

adapt.js

let local = {}
try { local = require('./environment.json') } catch {}

const adapt = require('@packmate/adapt')({
  configuration: require('./adapt.json'),

  environment: {
    ...local,
    ...process.env
  }
})

app.js

const adapt = require('./adapt')

// With process.env = { mode: 'development' }:
adapt('api.key') // => 'development_value'

// With process.env = { mode: 'production', api_key_production: 'production_value' }:
adapt('api.key') // => 'production_value'