avanes/dollar-config

Static config with dynamic settings

Dollar config

Dollar config lets you keep dynamic settings in a declarative way and query them with runtime params.

• Dollar config
  • Installation
  • Setup
  • Usage
  • Features
    • Static setting
    • $default
    • $param
    • $template
    • $guard
    • $switch
    • $function
    • Nested settings/params/functions
    • Nested $-keywords
  • Binding
  • Express middleware
  • Validation
  • Building

Installation

npm install dollar-config

Setup

const DollarConfig = require('dollar-config');

const config = new DollarConfig(require('config.json'));

Usage

config.get('path.to.setting', runtimeParams);

Examples

Static setting

No magic here.

{
  "foo": 1
}

config.get('foo');
> 1

$default

Provides a fallback for an absent setting.

{
  "foo": 1,
  "$default": 0
}

config.get('bar');
> 0

$param

Looks up a param and returns its value.

{
  "foo": {
    "$param": "bar"
  }
}

config.get('foo', { bar: 1 });
> 1

Use an array to provide a default value:

{
  "foo": {
    "$param": [ "bar", 0 ]
  }
}

config.get('foo', { baz: 1 });
> 0

$template

Replaces ${paramName} with param value.

{
  "greeting": {
    "$template": "Hello, ${name}!"
  }
}

config.get('greeting', { name: 'John' });
> Hello, John!

$guard

Picks the first truthy param and returns correspondent setting.

Falls back to an optional $default if none of the params is truthy.

N.B. $default, if present, must be the last item for lookup performance.

{
  "foo": {
    "$guard": [
      [ "bar", "no luck" ],
      [ "baz", "close, but no cigar" ],
      [ "qux", "you are the champion" ],
      [ "$default", "oops" ]
    ]
  }
}

config.get('foo', { bar: false, baz: '', qux: 1 });
> you are the champion

config.get('foo', {})
> oops

$switch

Matches param value to a list of cases and picks correspondent setting.

Falls back to an optional $default if no match is found.

N.B. $default, if present, must be the last item for lookup performance.

{
  "meal": {
    "$switch": [
      "dayOfTime",
      [
        [ "morning", "breakfast" ],
        [ "midday", "lunch" ],
        [ "evening", "dinner" ],
        [ "$default", "fridge" ]
      ]
    ]
  }
}

config.get('meal', { dayOfTime: 'midday' });
> lunch

config.get('meal', { dayOfTime: 'night' });
> fridge

$function

Calls the referenced function and returns it's value.

Functions are provided as an option to config constructor.

Each function recevies params as a single argument.

{
  "expectedSalary": {
    "$function": "double"
  }
}

const config = new DollarConfig(require('config.json'), {
    functions: {
        double: (params) => params.currentSalary * 2
    }
});

config.get('expectedSalary', { currentSalary: 500 });
> 1000

Nested settings/params/functions

Deep properties are accessible with dot-notation:

{
  "foo": {
    "bar": {
      "$param": "baz.qux"
    }
  }
}

config.get('foo.bar', { baz: { qux: 1 } });
> 1

Nested $-keywords

You can mix and match $-keywords to get the desired effect:

{
  "foo": {
    "$switch": [
      "bar",
      [
        [
          "baz",
          {
            "$guard": [
              [ "qux", { "$param": "xyz" } ]
            ]
          }
        ]
      ]
    ]
  }
}

config.get('foo', { bar: 'baz', qux: true, xyz: 1 });
> 1

Binding

The .bind() method clones your config, converting all dynamic keys to getters, so that you can use them as a normal object:

const config = new DollarConfig({
    foo: 1,
    bar: { $param: 'baz' }
});

config.bind({ baz: 2 });
> { foo: 1, bar: 2 }

Because all dynamic keys are evaluated lazily, you can even make self-references:

const config = new DollarConfig({
    foo: { $param: 'baz' },
    bar: { $param: 'config.foo' }
});

const params = { baz: 1 };
params.config = config.bind(params);

params.config
> { foo: 1, bar: 1 }

After the first invocation getters replace themselves with evaluated values (a.k.a memoization):

let i = 1;
const config = new DollarConfig(
    { foo: { $function: 'bar' } },
    { functions: { bar: () => i++ } }
);
const boundConfig = config.bind({});

boundConfig.foo
> 1

boundConfig.foo
> 1

Express middleware

Dollar config express middleware binds provided config to the express req and puts the result into req.config:

{
  "foo": {
    "$param": "query.bar"
  }
}

const dollarConfigMiddleware = require('dollar-config/middleware');

app.use(dollarConfigMiddleware(require('config.json'));

// /?bar=1
app.use((req, res, next) => {
    req.config.foo === 1 // true
});

The middleware accepts dollar config instances as well:

const dollarConfigMiddleware = require('dollar-config/middleware');

const config = new DollarConfig(require('config.json'));

app.use(dollarConfigMiddleware(config));

Validation

You can use special ajv plugin to validate dollar-configs against JSON schemas.

const ajv = require('dollar-config/ajv')(new Ajv());
const validate = ajv.compile(require('schema.json'));

Or, with ajv-cli:

ajv validate -d config.json -s schema.json -c dollar-config/ajv

The plugin introduces a custom dynamic keyword which accepts any valid JSON schema inside it:

{
  "type": "object",
  "properties": {
    "foo": {
      "dynamic": {
        "type": "number"
      }
    }
  }
}

validate({ foo: 1 });
> true

validate({ foo: { $param: 'bar' } });
> true

The plugin checks that leaf values of $-keywords match original schema:

validate({ foo: { $param: [ 'bar', 1 ] } });
> true

validate({ foo: { $param: [ 'bar', '1' ] } });
> false (expected number, got string)

validate({ foo: { $guard: [ [ 'bar': '1' ] ] } });
> false (expected number, got string)

Using $template implies that the original schema is string:

validate({ foo: { $template: '${bar}/${baz}' } });
> false (expected original schema to be string, got number)

Building

Sometimes you want to have separate configs for different environments. Dollar config lets you keep all the settings in one source config and generate per-environment configs. dollar-config/build can be used to inline predefined params. Other dynamic params are returned as-is.

{
  "backendUrl": {
    "$switch": [
      "environment",
      [
        [ "prestable", "https://prestable-backend/" ],
        [ "$default", "https://production-backend/" ]
      ]
    ]
  },
  "backendQuery": {
    "foo": { "$param": "bar" }
  }
}

const buildConfig = require('dollar-config/build');

const config = require('config.json');

buildConfig(config, { environment: 'prestable' });
>
{
  backendUrl: "https://prestable-backend/",
  backendQuery: {
    "foo": { "$param": "bar" }
  }
}

buildConfig(config, { environment: 'production' });
>
{
  backendUrl: "https://production-backend/",
  backendQuery: {
    "foo": { "$param": "bar" }
  }
}