Fun with Flags

https://hexdocs.pm/fun_with_flags/1.13.0/
Admin
Fun with Flags is an Elixir feature flag library that enables developers to toggle features globally...
Tokens:3,879
Snippets:35
Trust Score:9
Update:6 months ago
Show doc for...
Tokens:
Raw
### Example: Clearing and Enabling Flags

Source: https://hexdocs.pm/fun_with_flags/FunWithFlags.html

Demonstrates disabling, enabling with specific gates, clearing for an actor, and clearing globally. Shows the effect on `enabled?` checks.

```elixir
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
```

--------------------------------

### Get All Flags

Source: https://hexdocs.pm/fun_with_flags/FunWithFlags.html

Returns a list of all configured flags as data structures. Provided for debugging and GUI purposes, not for runtime flag checks.

```elixir
 @spec all_flags() :: {:ok, [FunWithFlags.Flag.t()]} | {:error, any()}
```

--------------------------------

### Get All Flag Names

Source: https://hexdocs.pm/fun_with_flags/FunWithFlags.html

Returns a list of all configured flag names as atoms. Useful for debugging or display, not for runtime checks.

```elixir
 @spec all_flag_names() :: {:ok, [atom()]} | {:error, any()}
```

--------------------------------

### enable(flag_name, options)

Source: https://hexdocs.pm/fun_with_flags/FunWithFlags.html

Enables a feature flag globally or for specific actors, groups, or percentages.

```APIDOC
## enable(flag_name, options)

### Description
Enables a feature flag. Can be applied globally or restricted using options.

### Parameters
- **flag_name** (atom) - Required - The name of the feature flag.
- **options** (keyword list) - Optional - Configuration options:
  - **:for_actor** (term) - Enables for a specific actor implementing the Actor protocol.
  - **:for_group** (binary/atom) - Enables for a specific group.
  - **:for_percentage_of** (tuple) - Enables for a percentage of time or actors, e.g., {:time, 0.5} or {:actors, 0.5}.

### Response
- **Success** ({:ok, true}) - Flag enabled successfully.
- **Error** ({:error, any()}) - Failed to enable the flag.
```

--------------------------------

### Verify flag status for actors and groups

Source: https://hexdocs.pm/fun_with_flags/FunWithFlags.html

Shows how to check flag status for specific actors and groups using the enabled? function.

```elixir
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
```

--------------------------------

### Enable Flag Globally

Source: https://hexdocs.pm/fun_with_flags/FunWithFlags.html

Use this to enable a feature flag globally. Check the initial state before enabling if necessary.

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

--------------------------------

### Define Options Type

Source: https://hexdocs.pm/fun_with_flags/FunWithFlags.html

Defines the type for options, which is a keyword list.

```elixir
 @type options() :: Keyword.t()
```

--------------------------------

### get_flag(name)

Source: https://hexdocs.pm/fun_with_flags/FunWithFlags.html

Retrieves the configuration struct for a specific feature flag.

```APIDOC
## get_flag(name)

### Description
Returns a `FunWithFlags.Flag` struct for the given name, or `nil` if no flag is found. This is primarily used for debugging purposes.

### Parameters
- **name** (atom) - Required - The name of the flag to retrieve.

### Response
- **FunWithFlags.Flag.t | nil | {:error, any()}** - The flag struct, nil if not found, or an error tuple.
```

--------------------------------

### Enable flag for a percentage of actors

Source: https://hexdocs.pm/fun_with_flags/FunWithFlags.html

Demonstrates enabling a flag for a specific percentage of actors and verifying the status for individual users.

```elixir
iex> FunWithFlags.disable(:new_ui)
iex> FunWithFlags.enable(:new_ui, for_percentage_of: {:actors, 0.5})
iex> FunWithFlags.enabled?(:new_ui)
false
iex> alias FunWithFlags.TestUser, as: User
iex> marty = %User{id: 42, name: "Marty McFly"}
iex> buford = %User{id: 2, name: "Buford Tannen"}
iex> FunWithFlags.enabled?(:new_ui, for: marty)
true
iex> FunWithFlags.enabled?(:new_ui, for: buford)
false
```

--------------------------------

### Check flag status with enabled?/2

Source: https://hexdocs.pm/fun_with_flags/FunWithFlags.html

Defines the specification for the enabled? function.

```elixir
@spec enabled?(atom(), options()) :: boolean()
```

--------------------------------

### Retrieve flag structure with get_flag/1

Source: https://hexdocs.pm/fun_with_flags/FunWithFlags.html

Defines the specification for retrieving a flag structure by name.

```elixir
@spec get_flag(atom()) :: FunWithFlags.Flag.t() | nil | {:error, any()}
```

--------------------------------

### Enable Flag for a Percentage of Time

Source: https://hexdocs.pm/fun_with_flags/FunWithFlags.html

Enable a feature flag for a specified percentage of time. The value is a float between 0.0 and 1.0.

```elixir
iex> FunWithFlags.disable(:random_glitch)
iex> FunWithFlags.enable(:random_glitch, for_percentage_of: {:time, 0.999999999})
iex> FunWithFlags.enabled?(:random_glitch)
true
iex> FunWithFlags.enable(:random_glitch, for_percentage_of: {:time, 0.000000001})
iex> FunWithFlags.enabled?(:random_glitch)
false
```

--------------------------------

### enabled?(flag_name, options)

Source: https://hexdocs.pm/fun_with_flags/FunWithFlags.html

Checks if a feature flag is enabled, optionally scoped to a specific actor or group.

```APIDOC
## enabled?(flag_name, options)

### Description
Checks if a flag is enabled. It can be invoked with just the flag name to check the general status, or with options to check status for a specific actor or group.

### Parameters
- **flag_name** (atom) - Required - The name of the flag to check.
- **options** (keyword list) - Optional - Configuration options including `:for` to provide an actor or group term.

### Response
- **boolean** - Returns true if the flag is enabled for the given context, false otherwise.
```

--------------------------------

### FunWithFlags Core API

Source: https://hexdocs.pm/fun_with_flags/FunWithFlags.html

Core functions for managing and querying feature flags within the FunWithFlags library.

```APIDOC
## all_flag_names()

### Description
Returns a list of all flag names currently configured as atoms.

### Method
Function Call

### Response
- **Result** (list) - {:ok, [atom()]} or {:error, any()}

## all_flags()

### Description
Returns a list of all the flags currently configured as data structures.

### Method
Function Call

### Response
- **Result** (list) - {:ok, [FunWithFlags.Flag.t()]} or {:error, any()}

## clear(flag_name, options)

### Description
Clears the data of a feature flag, either entirely or for a specific Actor, Group, or gate.

### Method
Function Call

### Parameters
#### Path Parameters
- **flag_name** (atom) - Required - The name of the flag to clear.

#### Options
- **for_actor** (term) - Optional - Clear for a specific actor.
- **for_group** (binary/atom) - Optional - Clear for a specific group.
- **boolean** (boolean) - Optional - Clear the boolean gate.
- **for_percentage** (boolean) - Optional - Clear any percentage gate.

### Response
- **Result** (:ok | {:error, any()})

## disable(flag_name, options)

### Description
Disables a feature flag.

### Method
Function Call

### Parameters
#### Path Parameters
- **flag_name** (atom) - Required - The name of the flag to disable.

### Response
- **Result** ({:ok, boolean()} | {:error, any()})
```

--------------------------------

### Enable Flag for an Actor

Source: https://hexdocs.pm/fun_with_flags/FunWithFlags.html

Enable a feature flag for a specific actor. The actor must implement the `Actor` protocol. This does not affect the global flag status.

```elixir
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 Flag for a Group

Source: https://hexdocs.pm/fun_with_flags/FunWithFlags.html

Enable a feature flag for a specific group. The group identifier can be a binary or an atom. This is useful for targeted feature rollouts.

```elixir
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
```

--------------------------------

### disable(flag_name, options)

Source: https://hexdocs.pm/fun_with_flags/FunWithFlags.html

Disables a feature flag globally or for specific actors, groups, or percentages.

```APIDOC
## disable(flag_name, options)

### Description
Disables a feature flag. Can be applied globally or restricted using options.

### Parameters
- **flag_name** (atom) - Required - The name of the feature flag.
- **options** (keyword list) - Optional - Configuration options:
  - **:for_actor** (term) - Disables for a specific actor implementing the Actor protocol.
  - **:for_group** (binary/atom) - Disables for a specific group.
  - **:for_percentage_of** (tuple) - Disables for a percentage of time or actors, e.g., {:time, 0.5} or {:actors, 0.5}.

### Response
- **Success** ({:ok, false}) - Flag disabled successfully.
```

--------------------------------

### Disable Flag Globally

Source: https://hexdocs.pm/fun_with_flags/FunWithFlags.html

Use this to disable a feature flag for all users and contexts. Ensure the flag is enabled before disabling if it was previously enabled.

```elixir
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 Flag for a Percentage of Time

Source: https://hexdocs.pm/fun_with_flags/FunWithFlags.html

Disable a feature flag for a specified percentage of time. The value is a float between 0.0 and 1.0. Use `FunWithFlags.clear/1` to reset the flag before testing percentages.

```elixir
iex> FunWithFlags.clear(:random_glitch)
:ok
iex> FunWithFlags.disable(:random_glitch, for_percentage_of: {:time, 0.999999999})
{:ok, false}
iex> FunWithFlags.enabled?(:random_glitch)
false
iex> FunWithFlags.disable(:random_glitch, for_percentage_of: {:time, 0.000000001})
{:ok, false}
iex> FunWithFlags.enabled?(:random_glitch)
true
```

--------------------------------

### Disable Feature Flag

Source: https://hexdocs.pm/fun_with_flags/FunWithFlags.html

Disables a feature flag. Returns {:ok, boolean()} or {:error, any()}.

```elixir
 @spec disable(atom(), options()) :: {:ok, boolean()} | {:error, any()}
```

--------------------------------

### Clear Feature Flag Data

Source: https://hexdocs.pm/fun_with_flags/FunWithFlags.html

Clears feature flag data, either globally, for a specific Actor, Group, or gate type. Boolean gates cannot be cleared directly.

```elixir
 @spec clear(atom(), options()) :: :ok | {:error, any()}
```

--------------------------------

### Disable Flag for a Percentage of Actors

Source: https://hexdocs.pm/fun_with_flags/FunWithFlags.html

Disable a feature flag for a specified percentage of actors. The value is a float between 0.0 and 1.0.

```elixir
iex> FunWithFlags.disable(:new_ui, for_percentage_of: {:actors, 0.3})
{:ok, false}
```

--------------------------------

### Disable Flag for an Actor

Source: https://hexdocs.pm/fun_with_flags/FunWithFlags.html

Disable a feature flag for a specific actor. The actor must implement the `Actor` protocol. This does not affect the global flag status.

```elixir
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 Flag for a Group

Source: https://hexdocs.pm/fun_with_flags/FunWithFlags.html

Disable a feature flag for a specific group. The group identifier can be a binary or an atom. This is useful for segmenting feature rollouts.

```elixir
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
```
Tokens:
Raw