confidence

Confidence is a configuration document format, an API, and a foundation for A/B testing. The configuration format is designed to work with any existing JSON-based configuration, serving values based on object path ('/a/b/c' translates to a.b.c). In addition, confidence defines special $-prefixed keys used to filter values for a given criteria.

• Example
• Document Format
  • Basic Structure
  • Filters
  • Ranges
• API

Example

{
    "key1": "abc",
    "key2": {
        "$filter": "env",
        "production": {
            "deeper": "value"
        },
        "$default": {
            "$filter": "platform",
            "android": 0,
            "ios": 1,
            "$default": 2
        }
    },
    "key3": {
        "sub1": 123,
        "sub2": {
            "$filter": "xfactor",
            "yes": 6
        }
    },
    "ab": {
        "$filter": "random.a",
        "$range": [
            { "limit": 10, "value": 4 },
            { "limit": 20, "value": 5 }
        ],
        "$default": 6
    }
}

Without any criteria applied, the above configuration document will result in the following:

{
    "key1": "abc",
    "key2": 2,
    "key3": {
        "sub1": 123
    },
    "ab": 6
}

With the following criteria applied:

{
    "env": "production",
    "platform": "ios",
    "xfactor": "yes",
    "random": {
        "1": 15
    }
}

The result is:

{
    "key1": "abc",
    "key2": {
        "deeper": "value"
    },
    "key3": {
        "sub1": 123,
        "sub2": 6
    },
    "ab": 5
}

Document Format

Confidence builds on top of a Javascript object as its document.

Basic structure

The configuration document starts with a simple object. key names can only contain alphanumeric characters and '_' with the '$' prefix reserved for special directives. Values can contain any non-object value (e.g. strings, numbers, booleans) as well as arrays. Values cannot be null or undefined.

{
    "key1": "abc",
    "key2": 2
}

Keys can have children:

{
    "key1": "abc",
    "key2": 2,
    "key3": {
        "sub1": 123
    }
}

Filters

A key can have multiple values based on a filter. The filter is a key provided in a criteria object as the time of retrieval. Filter names can only contain alphanumeric characters and '_'.

{
    "key1": "abc",
    "key2": {
        "$filter": "env",
        "production": 1
    }
}

When asking for '/key2', if no criteria set is provided or the criteria set does not include a value for the 'env' filter, no value is available. Only when a criteria set with a key 'env' and value 'production' is provided, the value returned is 1.

Filtes can point to a nested value using '.' seperated tokens for accessing child values within the criteria object.

{
    "key1": "abc",
    "key2": {
        "$filter": "system.env",
        "production": 1
    }
}

Filter can have a default value which will be used is the provided criteria set does not include a value of the filter or if the value does not match.

{
    "key1": "abc",
    "key2": {
        "$filter": "system.env",
        "production": 1,
        "$default": 2
    }
}

Ranges

Ranges provide a way to filter a value based on numerical buckets. The criteria value must be an integer and it matched against the highest bucket limit it can fit.

{
    "key1": "abc",
    "key2": {
        "$filter": "system.env",
        "production": 1,
        "$default": 2
    },
    "key3": {
        "$filter": "random.a",
        "$range": [
            { "limit": 10, "value": 4 },
            { "limit": 20, "value": 5 }
        ],
        "$default": 6
    }
}

If the criteria includes a value for random.a, that value is matched against the sorted range entries. The criterion value will match the entry with highest limit it is still less than or equal the limit of. For example, a criterion value of 5 will return a key value for '/key3' of 4. A criterion value of 15 will return a key value for '/key3' of 5, and a criterion value of 50 will return a key value for '/key3' of 6.

API

Confidence.Store

The configuration parser used to load the configuration document and apply criteria to get values based on keys.

new Store([document])

Creates an empty configuration storage container where:

• document - an optional object containing a confidence configuration object generated from a parsed JSON document. If the document is invalid, will throw an error. Defaults to {}.

var Confidence = require('confidence');

var store = new Store();

store.load(document)

Validates the provided configuration, clears any existing configuration, then loads the configuration where:

• document - an object containing a confidence configuration object generated from a parsed JSON document. If the document is invlaid, will throw an error.

var document = {
    a: 1,
    b: 2,
    c: {
        $filter: 'size',
        big: 100,
        small: 1,
        $default: 50
    }
};

store.load(document);

store.get(key, [criteria,] [depth])

Retrieves a value from the configuration document after applying the provided criteria where:

• key - the requested key path. All keys must begin with '/'. '/' returns the the entire document.
• criteria - optional object used as criteria for applying filters in the configuration document. Defaults to {}.
• depth - optional number used to determine how deep the resulting tree is. Defaults to full depth.

Returns the value found after applying the criteria. If the key is invalid or not found, returns null.

var value = store.get('/c', { size: 'big' });