fun_with_flags v0.6.0 FunWithFlags

FunWithFlags, the Elixir feature flag library.

This module provides the public interface to the library and its API is made of three simple methods to enable, disable and query feature flags.

In their simplest form, flags can be toggled on and off globally.

More advanced rules or “gates” are available, and they can be set and queried for any term that implements these protocols:

  • The FunWithFlags.Actor protocol can be implemented for types and structs that should have specific rules. For example, in web applications it’s common to use a %User{} struct or equivalent as an actor, or perhaps the current country of the request.

  • The FunWithFlags.Group protocol can be implemented for types and structs that should belong to groups for which one wants to enable and disable some flags. For example, one could implement the protocol for a %User{} struct to identify administrators.

See the Usage notes for a more detailed explanation.

Summary

Functions

Clears the data of a feature flag

Disables a feature flag

Enables a feature flag

Checks if a flag is enabled

Types

options()
options() :: Keyword.t

Functions

clear(flag_name, options \\ [])
clear(atom, options) :: :ok

Clears the data of a feature flag.

Clears the data for an entire feature flag or for a specific Actor or Group gate. Clearing a boolean gate is not supported because a missing boolean gate is equivalent to a disabled boolean gate.

Sometimes enabling or disabling a gate is not what you want, and you need to remove that gate’s rules instead. For example, if you don’t need anymore to explicitly enable or disable a flag for an actor, and the default state should be used instead, you’ll want to cleare the gate.

It’s also possible to clear the entire flag, by not passing any option.

Options

  • :for_actor - used to clear the flag for a specific term only. The value can be any term that implements the Actor protocol.
  • :for_group - used to clear the flag for a specific group only. The value should be an atom.

Examples

iex> alias FunWithFlags.TestUser, as: User
iex> harry = %User{id: 1, name: "Harry Potter", groups: [:wizards, :gryffindor]}
iex> hagrid = %User{id: 2, name: "Rubeus Hagrid", groups: [:wizards, :gamekeeper]}
iex> dudley = %User{id: 3, name: "Dudley Dursley", groups: [:muggles]}
iex> FunWithFlags.disable(:wands)
iex> FunWithFlags.enable(:wands, for_group: :wizards)
iex> FunWithFlags.disable(:wands, for_actor: hagrid)
iex>
iex> FunWithFlags.enabled?(:wands)
false
iex> FunWithFlags.enabled?(:wands, for: harry)
true
iex> FunWithFlags.enabled?(:wands, for: hagrid)
false
iex> FunWithFlags.enabled?(:wands, for: dudley)
false
iex>
iex> FunWithFlags.clear(:wands, for_actor: hagrid)
:ok
iex> FunWithFlags.enabled?(:wands, for: hagrid)
true
iex>
iex> FunWithFlags.clear(:wands)
:ok
iex> FunWithFlags.enabled?(:wands)
false
iex> FunWithFlags.enabled?(:wands, for: harry)
false
iex> FunWithFlags.enabled?(:wands, for: hagrid)
false
iex> FunWithFlags.enabled?(:wands, for: dudley)
false
disable(flag_name, options \\ [])
disable(atom, options) :: {:ok, false}

Disables a feature flag.

Options

  • :for_actor - used to disable the flag for a specific term only. The value can be any term that implements the Actor protocol.
  • :for_group - used to disable the flag for a specific group only. The value should be an atom.

Examples

Disable globally

iex> FunWithFlags.enable(:random_koala_gifs)
iex> FunWithFlags.enabled?(:random_koala_gifs)
true
iex> FunWithFlags.disable(:random_koala_gifs)
{:ok, false}
iex> FunWithFlags.enabled?(:random_koala_gifs)
false

Disable for an actor

iex> FunWithFlags.enable(:spider_sense)
{:ok, true}
iex> villain = %{name: "Venom"}
iex> FunWithFlags.disable(:spider_sense, for_actor: villain)
{:ok, false}
iex> FunWithFlags.enabled?(:spider_sense)
true
iex> FunWithFlags.enabled?(:spider_sense, for: villain)
false

Disable for a group

This example relies on the reference implementation used in the tests.

iex> alias FunWithFlags.TestUser, as: User
iex> harry = %User{name: "Harry Potter", groups: [:wizards, :gryffindor]}
iex> dudley = %User{name: "Dudley Dursley", groups: [:muggles]}
iex> FunWithFlags.enable(:hogwarts)
{:ok, true}
iex> FunWithFlags.disable(:hogwarts, for_group: :muggles)
{:ok, false}
iex> FunWithFlags.enabled?(:hogwarts)
true
iex> FunWithFlags.enabled?(:hogwarts, for: harry)
true
iex> FunWithFlags.enabled?(:hogwarts, for: dudley)
false
enable(flag_name, options \\ [])
enable(atom, options) :: {:ok, true}

Enables a feature flag.

Options

  • :for_actor - used to enable the flag for a specific term only. The value can be any term that implements the Actor protocol.
  • :for_group - used to enable the flag for a specific group only. The value should be an atom.

Examples

Enable globally

iex> FunWithFlags.enabled?(:super_shrink_ray)
false
iex> FunWithFlags.enable(:super_shrink_ray)
{:ok, true}
iex> FunWithFlags.enabled?(:super_shrink_ray)
true

Enable for an actor

iex> FunWithFlags.disable(:warp_drive)
{:ok, false}
iex> FunWithFlags.enable(:warp_drive, for_actor: "Scotty")
{:ok, true}
iex> FunWithFlags.enabled?(:warp_drive)
false
iex> FunWithFlags.enabled?(:warp_drive, for: "Scotty")
true

Enable for a group

This example relies on the reference implementation used in the tests.

iex> alias FunWithFlags.TestUser, as: User
iex> marty = %User{name: "Marty McFly", groups: [:students, :time_travelers]}
iex> doc = %User{name: "Emmet Brown", groups: [:scientists, :time_travelers]}
iex> buford = %User{name: "Buford Tannen", groups: [:gunmen, :bandits]}
iex> FunWithFlags.enable(:delorean, for_group: :time_travelers)
{:ok, true}
iex> FunWithFlags.enabled?(:delorean)
false
iex> FunWithFlags.enabled?(:delorean, for: buford)
false
iex> FunWithFlags.enabled?(:delorean, for: marty)
true
iex> FunWithFlags.enabled?(:delorean, for: doc)
true
enabled?(flag_name, options \\ [])
enabled?(atom, options) :: boolean

Checks if a flag is enabled.

It can be invoked with just the flag name, as an atom, to check the general staus of a flag (i.e. the boolean gate).

Options

  • :for - used to provide a term for which the flag could have a specific value. The passed term should implement the Actor or Group protocol, or both.

Examples

This example relies on the reference implementation used in the tests.

iex> alias FunWithFlags.TestUser, as: User
iex> harry = %User{id: 1, name: "Harry Potter", groups: [:wizards, :gryffindor]}
iex> FunWithFlags.disable(:elder_wand)
iex> FunWithFlags.enable(:elder_wand, for_actor: harry)
iex> FunWithFlags.enabled?(:elder_wand)
false
iex> FunWithFlags.enabled?(:elder_wand, for: harry)
true
iex> voldemort = %User{id: 7, name: "Tom Riddle", groups: [:wizards, :slytherin]}
iex> FunWithFlags.enabled?(:elder_wand, for: voldemort)
false
iex> filch = %User{id: 88, name: "Argus Filch", groups: [:staff]}
iex> FunWithFlags.enable(:magic_wands, for_group: :wizards)
iex> FunWithFlags.enabled?(:magic_wands, for: harry)
true
iex> FunWithFlags.enabled?(:magic_wands, for: voldemort)
true
iex> FunWithFlags.enabled?(:magic_wands, for: filch)
false