Hochuli

Hochuli - "The strongest toggle library in the world."

Hochuli is a module for managing features in your applications. It helps facilitate Trunk Based Development by defining the concepts of release and business toggles. It's a good idea to familiarize yourself with these concepts here. Named after the famed Ed Hochuli.

Installation

npm install hochuli

Usage

Features are defined in two categories, release or business.

• new Hochuli(options)
• rules()
• release()
• business()
• feature()
• sync()
• getState()

import Hochuli from 'hochuli'

// Create a Toggles instance
const Toggles = new Hochuli({
  applicationID: 'my-test-app'
})

// Some user id's that we'll use later
const QAUserUUIDs = [
  '5c6dd8cf-c55b-427d-99d2-9d859273c00c',
  'ca050d9c-dce8-4b34-8612-19f510701685',
  '9b447de2-7d4c-463d-857a-44b19dcd8c13'
]


// Define rules that can be assigned to features
Toggles.rules(function() {
  // A Group rule representing the QA team
  this.rule('qa-team', 'user_uuid').group(QAUserUUIDs)
})

// Define in-app features managed by developers
Toggles.release(function() {
  // This feature is given the 'on' Bool-type rule
  this.feature('friend-referrals', 'allow user to refer friends').on();
  // This feature evaluates to `true` given
  this.feature('one-step-link-a-bank', 'allow users to link a bank in one step', 'user_uuid').on('qa-team');
});

// Define external features managed by the buisness
Toggles.business(function() {
  // By default this feature is given the 'off' Bool-type rule
  this.feature('show-confetti', 'display a nice confetti animation').off();
});

new Hochuli(options)

An instance of the Hochuli class is needed to start managing your togls.

options

• applicationID - A unique identifier representing your application
• defaultFeatureTargetType - The default Target Type associated with a feature if not provided
• togglesDigestURL - URL to an external Togle manifest (see example)
• rulesDigestURL - URl to an external Rules manifest (see example)
• cachePrefix - Prefix for cache keys
• caching - Cache toggle and rule digests (defaults to false)

Hochuli.rules(block)

rules() provides a DSL for defining rules that can later be assigned to features. This function takes another function which exposes a rule() on it's this context. Notice that we can the call bool or group on this.rule to define what type of rule it is.

• rule(id, targetType)

Example:

hochuli.rules(function() {
  this.rule('admin-group', 'user_uuid').group(adminUUIDs)
})

Hochuli.release(block)

release() is used to define features as release togls. It exposes a this.feature function on the function that you pass it. Note that a targetType is optional but you really should specify one.

• this.feature(id, description, targetType)

Example:

hochuli.release(function() {
  this.feature('my-sweet-feat', 'Do something awesome').on()
})

Hochuli.business(block)

business() is used to define features as business togls. It again exposes a this.feature function that works exactly like above.

Hochuli.feature(id)

feature() returns a Togl instance that exposes a single isOn method. isOn takes optional context data that gets fed into the feature's rule's run method. This is the interface used for controlling features in your code.

• isOn(context)

Example:

hochuli.feature('my-sweet-feat').isOn() // => false
hochuli.feature('super-secret-feature').isOn(anAdminUUID) // => true

Hochuli.sync()

sync() is used to refresh the in-memory store's business toggle and rules definitions. It returns a Promise. Sync will also result in rule and toggle manifests being persisted in localStorage (if available) along with their ETags. Subsequent sync calls will make special GET requests that include the cached manifest ETags.

Hochuli.getState()

getState() returns the entire serialized representation of your app's features and rules. Note that it doesn't return Toggles as these are simply runtime representations of a feature and corresponding rule.

Development

Developing

• 1. git clone [email protected]:timkendall/hochuli.git && cd hochuli
• 2. yarn install
• 3. npm run test:watch

Building

npm run build

Publishing

npm publish

License

MIT © Tim Kendall