Normally Palatable Mango

    dollar-config

    0.1.18 • Public • Published

    Dollar config

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

    Build Status npm version Coverage Status

    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" }
      }
    }

    Keywords

    none

    Install

    npm i dollar-config

    DownloadsWeekly Downloads

    9

    Version

    0.1.18

    License

    MIT

    Unpacked Size

    23 kB

    Total Files

    8

    Last publish

    Collaborators

    • razetdinov