@cazoo/toggles

• Installation
• Updating
• Basic usage

- features

- [market-specific features](#market-specific-features)

- treatments

• More usages
• Release

- Commit messages

- [Type](#type)
- [Context](#context)
- [Examples](#examples)

Simple wrapper on top of environment variables to standardise feature toggling.
This is a universal package for both the browser and node.
At this point this package is more about estabilishing a convention rather being super useful. In the future this can be extended with pluggable Providers, like cookies or any service that stores key-value pairs.

Installation

npm install @cazoo/toggles --save

Basic usage

features

Given:

process.env = {
    FEATURE_LASER: 'on',
    FEATURE_DEATH_STAR: 'off'
}

Then:

import toggles from '@cazoo/toggles';

const { featureIsEnabled } = toggles.create();

...

if (featureIsEnabled('LASER')) {
    // use laser
} else {
    // don't use laser
}

market-specific features

When a feature toggle value is a stringified object, this object's keys are treated as markets and its values - as toggle values for each market.
It is possible to declare also a default value that will be used for markets where the toggle is not explicitly set.
Given:

process.env = {
    FEATURE_LASER: '{"gb":"off","default":"on"}',
    FEATURE_DEATH_STAR: 'on'
}

Then:

featureIsEnabled('LASER', 'gb')
// false

featureIsEnabled('LASER', 'fr')
// true - because the default value is set to 'on'

featureIsEnabled('LASER')
// true - the default value is used also when queried without a market 

featureIsEnabled('DEATH_STAR', 'gb')
// true - 'on' is equivalent to '{"default":"on"}'

treatments

Given:

process.env = {
    EXPERIMENT_LASER: JSON.stringify( {treatment: "on"} );
    EXPERIMENT_DEATH_STAR: JSON.stringify( {treatment: "off", config: JSON.stringify({luke: "I'm your father"}) );
}

Then:

import toggles from '@cazoo/toggles';

const { getTreatment, getAllExperiments } = toggles.create();

...

if (getTreatment('LASER').treatment === "on") {
    // use laser
} else {
    // don't use laser
}

//declare your config interface
interface config {
    luke : string
}

if(toggle.getTreatment("DEATH_STAR").config as config) {
    // if config is defined
}

const abSetup = getAllExperiments();
// array of experiments e.g.
// [
//     {
//         testName: "LASER",
//         treatment: "on"
//     },
//     {
//         testName: "DEATH_STAR",
//         treatment: "off",
//         config: {luke: "I'm your father"}
//     }
// ]

More usages

Please, refer to the integration.test.ts and integration.browser.test.ts for all the usages. They are intended to be a living documentation for the user.

Release

Releases are created by semantic-release, which checks all the commit messages since the last release to determine what the new version number should be.

Commit messages

To trigger a release, your commits need to follow the Angular Commit Message Conventions, meaning they need to be written in this pattern:

type(context): message

Type

Commits using the types feat, fix or perf will appear in the changelogs. However, any commit with BREAKING CHANGE in the body will also appear in the changelog, regardless of the type.
| Type | Release type | Description | | - | - | - | | feat | Minor (0.X.0) | A new feature | | fix | Patch (0.0.X) | A bug fix | | perf | Patch (0.0.X) | A code change that improves performance | | refactor | - | A code change that neither fixes a bug nor adds a feature | | test | - | Adding missing tests or correcting existing tests | | docs | - | Documentation only changes | | ci | - | Changes to our CI configuration files and scripts (example: CircleCI, BrowserStack, SauceLabs) | | build | - | Changes that affect the build system or external dependencies (example scopes: gulp, broccoli, npm) |

Context

For the context, we add the Jira ticket number. It's optional but good to have since the release logs are generated from the commits.

Examples

| Commit message | Release type | | - | - | | perf(DR-4567): remove graphiteWidth option from Pencil

BREAKING CHANGE: The graphiteWidth option has been removed.
The default graphite width of 10mm is always used for performance reasons. | Major (X.0.0) | | feat(DR-4567): add 'graphiteWidth' option to Pencil | Minor (0.X.0) | | fix(DR-4567): stop graphite breaking when too much pressure applied to Pencil | Patch (0.0.X) |
💡 To add a body to your commit message, you can use git commit -m "TITLE" -m "BODY"