<commit_before>Muton
=========

[![NPM version][npm-image]][npm-url] [![Build Status](https://travis-ci.org/Mindera/muton.svg?branch=master)](https://travis-ci.org/Mindera/muton)

  This is the Muton project - a feature toggle tool with support for feature throttling and multivariance testing.
  
  You can engineer the genes of your application by meticulously choose what are the best features and create an organic result. With artificial manipulation, or even by random mutations, you will natural select the best version of your application.
  
    ___  ___      _              
    |  \/  |     | |             
    | .  . |_   _| |_ ___  _ __  
    | |\/| | | | | __/ _ \| '_ \ 
    | |  | | |_| | || (_) | | | |
    \_|  |_/\__,_|\__\___/|_| |_|
    
    O       o O       o O       o
    | O   o | | O   o | | O   o |
    | | O | | | | O | | | | O | |
    | o   O | | o   O | | o   O |
    o       O o       O o       O
    
  
  In real life, cells replicate DNA using an enzyme called polymerase. During the process, it checks for replication errors doing proof-reading on the fly. But sometimes a random mutation occur... that's life trying to evolve. This tool works in a similar way: random mutations may occur while processing the instructions to toggle features on and off. That's your application trying to evolve.

## Installation

### NPM

  npm install muton --save

### Bower

  bower install muton --save

## Usage

  Muton just decides what features to mutate, activate or deactivate and it doesn't store the features anywhere. You should integrate Muton with code that persists the features per user, like using cookies or other mechanism you prefer.

### Basic usage

  Currently, you can use Muton as a Node module or an AMD module. To include as an AMD module, please require the `muton-amd.min.js` file.
    
  You can use in the following way:
  
```javascript
var features = muton.getFeatureMutations(userProperties, featureInstructions);
```

Where `userProperties` is a dictionary containing user properties, something like this:

```javascript
var userProperties = {
  'location' : 'PT',
  'age' : '24'
}
```

And where `featureInstructions` is a dictionary of features containing specific instructions, which must follow a specific format. It can be something like this:
 
```javascript
var featureInstructions = {
  'superCoolFeature' : {
    'toggle' : true,
    'location' : {
      'PT' : {
        'toggle' : true
      },
      'FR' : {
        'toggle' : false
      }
    }
  }
}
```

A Muton valid response would be:

```javascript
var featureInstructions = {
  'superCoolFeature' : true,
  'anotherCoolFeature' : false
``` 

### Instructions format

  The instructions must contain one of the following elements: `toggle`, `throttle` and `bucket` and they can be placed behind every property inside the feature object, and even placed directly under the feature object. Muton will look for a path in the instructions and aggregate all of them that matches the user properties. When no matches are found, it will assume the general instructions.
  
#### Toggle

  The `toggle` instruction activates or deactivates toggles. The default value is false and can be overridden by the `throttle` and `bucket` instructions. The exception to this is when the `toggle` instruction is placed directly under the feature object and it's value is set to false. This allows to deactivate a feature completely.
  
#### Throttle

  The `throttle` instruction will activate or deactivate a toggle based on a percentage. In Muton terms, this is called a mutation. For example, you might want to have 50% of your users to have access to a feature and this instruction is perfect for that.
  
  For example, if you want to have 50% of your Portugal users to see a feature but 100% of the users of the remaining countries to see it (except for France), you could do something like:
  
```javascript
var featureInstructions = {
  'superCoolFeature' : {
    'toggle' : true,
    'location' : {
      'PT' : {
        'throttle' : '50%'
      },
      'FR' : {
        'toggle' : false
      }
    }
  }
}
```

#### Buckets (A/B testing, multivariant testing)

  The `bucket` instruction is perfect for A/B testing and it resources to mutations like the `throttle` instruction. This instruction can be written like the following:
  
```javascript
var featureInstructions = {
  'superCoolFeature' : {
    'toggle' : true,
    'location' : {
      'PT' : {
        'throttle' : '50%'
      },
      'FR' : {
        'buckets' : ['bigRedButton', 'mediumSizeButton', 'smallButton']
      }
    }
  }
}
```
 
 The above snippet would allow you to have your France users to access three different buckets for testing, let's say, three different buttons on a form and test which of them your users react best.
 
 A valid response for a french user could be:
 
```javascript
var featureInstructions = {
  'superCoolFeature' : true,
  'superCoolFeature.smallButton' : true
}
```

### Matchers

  Muton supports non-trivial user properties matching. For example, you might want to toggle a feature on when the user bought over 10000 books in your store. Or even to activate a feature for users whose referral site belongs to a specific domain.

#### Regular expressions

  To have user properties being matched by regexes, you must enclose the regex inside two '/'. The above example referral example with Google can be written like this:

```javascript
  var featureInstructions = {
    'superCoolFeature' : {
      'referral' : {
        '/.*\.google\..{2,4}/' : {
          'throttle' : 'true'
        }
      }
    }
  }
```

#### Numeric quantifiers

  Numeric user properties can be matched against an expression. The property value must start with one of the following operators: '>', '<', '>=', '<='.
  
  Picking the bookstore example, a user with over 10000 bought books would have a special feature toggle on:
  
```javascript
  var featureInstructions = {
    'superCoolFeature' : {
      'boughtBooks' : {
        '>=10000' : {
          'throttle' : 'true'
        }
      }
    }
  }
```

## Build
  
  grunt clean && grunt

## Tests
<commit_msg>Fixing documentation.<commit_after>Muton
=========

[![NPM version][npm-image]][npm-url] [![Build Status](https://travis-ci.org/Mindera/muton.svg?branch=master)](https://travis-ci.org/Mindera/muton)

  This is the Muton project - a feature toggle tool with support for feature throttling and multivariance testing.
  
  You can engineer the genes of your application by meticulously choose what are the best features and create an organic result. With artificial manipulation, or even by random mutations, you will natural select the best version of your application.
  
    ___  ___      _              
    |  \/  |     | |             
    | .  . |_   _| |_ ___  _ __  
    | |\/| | | | | __/ _ \| '_ \ 
    | |  | | |_| | || (_) | | | |
    \_|  |_/\__,_|\__\___/|_| |_|
    
    O       o O       o O       o
    | O   o | | O   o | | O   o |
    | | O | | | | O | | | | O | |
    | o   O | | o   O | | o   O |
    o       O o       O o       O
    
  
  In real life, cells replicate DNA using an enzyme called polymerase. During the process, it checks for replication errors doing proof-reading on the fly. But sometimes a random mutation occur... that's life trying to evolve. This tool works in a similar way: random mutations may occur while processing the instructions to toggle features on and off. That's your application trying to evolve.

## Installation

### NPM

  npm install muton --save

### Bower

  bower install muton --save

## Usage

  Muton just decides what features to mutate, activate or deactivate and it doesn't store the features anywhere. You should integrate Muton with code that persists the features per user, like using cookies or other mechanism you prefer.

### Basic usage

  Currently, you can use Muton as a Node module or an AMD module. To include as an AMD module, please require the `muton-amd.min.js` file.
    
  You can use in the following way:
  
```javascript
var features = muton.getFeatureMutations(userProperties, featureInstructions);
```

Where `userProperties` is a dictionary containing user properties, something like this:

```javascript
var userProperties = {
  'location' : 'PT',
  'age' : '24'
}
```

And where `featureInstructions` is a dictionary of features containing specific instructions, which must follow a specific format. It can be something like this:
 
```javascript
var featureInstructions = {
  'superCoolFeature' : {
    'toggle' : true,
    'location' : {
      'PT' : {
        'toggle' : true
      },
      'FR' : {
        'toggle' : false
      }
    }
  }
}
```

A Muton valid response would be:

```javascript
var featureInstructions = {
  'superCoolFeature' : true,
  'anotherCoolFeature' : false
``` 

### Instructions format

  The instructions must contain one of the following elements: `toggle`, `throttle` and `bucket` and they can be placed behind every property inside the feature object, and even placed directly under the feature object. Muton will look for a path in the instructions and aggregate all of them that matches the user properties. When no matches are found, it will assume the general instructions.
  
#### Toggle

  The `toggle` instruction activates or deactivates toggles. The default value is false and can be overridden by the `throttle` and `bucket` instructions. The exception to this is when the `toggle` instruction is placed directly under the feature object and it's value is set to false. This allows to deactivate a feature completely.
  
#### Throttle

  The `throttle` instruction will activate or deactivate a toggle based on a percentage. In Muton terms, this is called a mutation. For example, you might want to have 50% of your users to have access to a feature and this instruction is perfect for that.
  
  For example, if you want to have 50% of your Portugal users to see a feature but 100% of the users of the remaining countries to see it (except for France), you could do something like:
  
```javascript
var featureInstructions = {
  'superCoolFeature' : {
    'toggle' : true,
    'location' : {
      'PT' : {
        'throttle' : '50%'
      },
      'FR' : {
        'toggle' : false
      }
    }
  }
}
```

#### Buckets (A/B testing, multivariant testing)

  The `bucket` instruction is perfect for A/B testing and it resources to mutations like the `throttle` instruction. This instruction can be written like the following:
  
```javascript
var featureInstructions = {
  'superCoolFeature' : {
    'toggle' : true,
    'location' : {
      'PT' : {
        'throttle' : '50%'
      },
      'FR' : {
        'buckets' : ['bigRedButton', 'mediumSizeButton', 'smallButton']
      }
    }
  }
}
```
 
 The above snippet would allow you to have your France users to access three different buckets for testing, let's say, three different buttons on a form and test which of them your users react best.
 
 A valid response for a french user could be:
 
```javascript
var featureInstructions = {
  'superCoolFeature' : true,
  'superCoolFeature.smallButton' : true
}
```

### Matchers

  Muton supports non-trivial user properties matching. For example, you might want to toggle a feature on when the user bought over 10000 books in your store. Or even to activate a feature for users whose referral site belongs to a specific domain.

#### Regular expressions

  To have user properties being matched by regexes, you must enclose the regex inside two '/'. The above example referral example with Google can be written like this:

```javascript
  var featureInstructions = {
    'superCoolFeature' : {
      'referral' : {
        '/.*\.google\..{2,4}/' : {
          'toggle' : 'true'
        }
      }
    }
  }
```

#### Numeric quantifiers

  Numeric user properties can be matched against an expression. The property value must start with one of the following operators: '>', '<', '>=', '<='.
  
  Picking the bookstore example, a user with over 10000 bought books would have a special feature toggle on:
  
```javascript
  var featureInstructions = {
    'superCoolFeature' : {
      'boughtBooks' : {
        '>=10000' : {
          'toggle' : 'true'
        }
      }
    }
  }
```

## Build
  
  grunt clean && grunt

## Tests

{'fraction_non_alphanumeric': 0.0946865381500081, 'fraction_numerical': 0.004859873643285275, 'mean_word_length': 2.915953060577228, 'pattern_counts': {'":': 0, '<': 7, '<?xml version=': 0, '>': 9, 'https://': 4, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3762923', 'n_tokens_mistral': 3601, 'n_tokens_neox': 3382, 'n_words': 1493}