Flippant

https://hexdocs.pm/flippant/
Admin
Flippant is a feature toggling library for Elixir applications that enables runtime control of...
Tokens:13,183
Snippets:150
Trust Score:9
Update:6 months ago
Show doc for...
Tokens:
Raw
### Start Link

Source: https://hexdocs.pm/flippant/index.html

Starts a Flippant process linked to the current process.

```APIDOC
## POST /start_link

### Description
Starts a Flippant process linked to the current process.

### Method
POST

### Endpoint
/start_link

### Parameters
#### Request Body
- **opts** (list) - Optional - Options for starting the process, e.g., `[{:name, module()}]`.

### Response
#### Success Response (200)
- **Supervisor.on_start()** (term()) - The result of starting the supervisor process.

### Request Example
```json
{
  "opts": [
    {
      "name": "Elixir.Flippant"
    }
  ]
}
```

### Response Example
```json
:ok
```
```

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

### Setup Adapter

Source: https://hexdocs.pm/flippant/index.html

Prepares the adapter for usage. For adapters that don't require setup, this is a no-op. For others, like Postgres, it creates the necessary schema/table.

```APIDOC
## POST /setup

### Description
Prepares the adapter for usage.

### Method
POST

### Endpoint
/setup

### Parameters
#### Query Parameters
- **name** (atom) - Optional - The name of the feature set to set up.

### Request Body
None

### Response
#### Success Response (200)
- **:ok** (:ok) - Indicates the adapter setup was successful.

### Request Example
```json
{
  "name": "features"
}
```

### Response Example
```json
:ok
```
```

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

### Start the Memory adapter

Source: https://hexdocs.pm/flippant/Flippant.Adapter.Memory.html

Defines the specification for starting the Memory adapter process.

```elixir
start_link(Keyword.t()) :: GenServer.on_start()
```

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

### Setup the adapter

Source: https://hexdocs.pm/flippant/Flippant.html

Prepares the adapter for usage, such as creating necessary database tables.

```elixir
Flippant.setup()
:ok
```

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

### Setup Adapter

Source: https://hexdocs.pm/flippant/index.html

Prepares the adapter for usage. This is a no-op for adapters that don't require setup, but for others like Postgres, it creates the necessary table.

```elixir
setup(name :: atom()) :: :ok
```

```elixir
Flippant.setup()
:ok
```

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

### Start Flippant Process

Source: https://hexdocs.pm/flippant/index.html

Starts a Flippant process linked to the current process. Accepts options, typically including the module name.

```elixir
start_link([{:name, module()}]) :: Supervisor.on_start()
```

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

### Defining Groups on Application Start

Source: https://hexdocs.pm/flippant/Flippant.html

Demonstrates how to define feature groups by registering them during application startup using `Flippant.register/2`.

```APIDOC
## Defining Groups on Application Start

Group definitions are stored in a process, which requires the Flippant application to be started. That means they can't be defined within a configuration file and should instead be linked from `Application.start/2`. You can make `Flippant.register/2` calls directly from the application module, or put them into a separate module and start it as a temporary worker. Here we're starting a temporary worker with the rest of an application:

```elixir
defmodule MyApp do
  use Application

  def start(_type, _args) do
    import Supervisor.Spec, warn: false

    children = [
      worker(MyApp.Flippant, [], restart: :temporary)
    ]

    opts = [strategy: :one_for_one, name: MyApp.Supervisor]

    Supervisor.start_link(children, opts)
  end
end
```

Note that the worker is defined with `restart: :temporary`. Now, define the `MyApp.Flippant` module:

```elixir
defmodule MyApp.Flippant do
  def start_link do
    Flippant.register("everybody", &everybody?/2)
    Flippant.register("nobody", &nobody?/2)
    Flippant.register("staff", &staff?/2)

    :ignore
  end

  def everybody?(_, _), do: true
  def nobody?(_, _), do: false
  def staff?(%User{staff?: staff?}, _), do: staff?
end
```
```

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

### Define Groups on Application Start

Source: https://hexdocs.pm/flippant/index.html

Register feature groups by calling `Flippant.register/2` within a temporary worker started from `Application.start/2`. Ensure the worker is defined with `restart: :temporary`.

```elixir
defmodule MyApp do
  use Application

  def start(_type, _args) do
    import Supervisor.Spec, warn: false

    children = [
      worker(MyApp.Flippant, [], restart: :temporary)
    ]

    opts = [strategy: :one_for_one, name: MyApp.Supervisor]

    Supervisor.start_link(children, opts)
  end
end
```

```elixir
defmodule MyApp.Flippant do
  def start_link do
    Flippant.register("everybody", &everybody?/2)
    Flippant.register("nobody", &nobody?/2)
    Flippant.register("staff", &staff?/2)

    :ignore
  end

  def everybody?(_, _), do: true
  def nobody?(_, _), do: false
  def staff?(%User{staff?: staff?}, _), do: staff?
end
```

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

### Ecto Migration for Flippant Features Table

Source: https://hexdocs.pm/flippant/Flippant.Adapter.Postgres.html

An example Ecto migration statement to create the `flippant_features` table.

```APIDOC
## Ecto Migration Example

If you're managing a database using Ecto, you can create a migration to add the `flippant_features` table with the following statement:

```sql
CREATE TABLE IF NOT EXISTS flippant_features (
  name varchar(140) NOT NULL CHECK (name <> ''),
  rules jsonb NOT NULL DEFAULT '{}'::jsonb,
  CONSTRAINT unique_name UNIQUE(name)
)
```
```

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

### Validate group and actor membership

Source: https://hexdocs.pm/flippant/Flippant.Rules.html

Specification and implementation example for the enabled? callback.

```elixir
enabled?(group :: binary(), enabled_for :: list(), actor :: Rules.actor()) ::
  boolean()
```

```elixir
  def enabled?("staff", enabled_for, %{staff: true} = actor) do
    Enum.any?(enabled_for, &actor.id == &1.id)
  end
```

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

### Retrieve Feature Breakdown

Source: https://hexdocs.pm/flippant/Flippant.html

Get a map of all enabled features and their associated groups, or check status for a specific actor.

```elixir
Flippant.breakdown()
#=> %{"search" => %{"awesome" => [], "heinous" => []},
      "delete" => %{"radical" => []},
      "invite" => %{"heinous" => []}}
```

```elixir
actor = %User{ id: 1, awesome?: true, radical?: false}
Flippant.breakdown(actor)
#=> %{"delete" => true, "search" => false}
```

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

### Get feature breakdown for a user

Source: https://hexdocs.pm/flippant/index.html

Evaluate all enabled features for a specific user and return the results as a map. This is useful for optimizing feature evaluation in single-page applications.

```elixir
Flippant.breakdown(%User{id: 1, staff?: true})
#=> %{"search" => true, "delete" => true, "invite" => false}
```

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

### Get Feature Breakdown

Source: https://hexdocs.pm/flippant/index.html

Retrieves the breakdown of enabled features across groups. Useful for understanding the current state of feature flags.

```elixir
Flippant.breakdown()
#=> %{"search" => %{"awesome" => [], "heinous" => []},
      "delete" => %{"radical" => []},
      "invite" => %{"heinous" => []}}
```

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

### Get Actor Feature Breakdown

Source: https://hexdocs.pm/flippant/index.html

Retrieves the feature breakdown for a specific actor. This helps determine which features are enabled for a given user or entity.

```elixir
actor = %User{ id: 1, awesome?: true, radical?: false}
Flippant.breakdown(actor)
#=> %{"delete" => true, "search" => false}
```

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

### setup/1

Source: https://hexdocs.pm/flippant/Flippant.html

Prepare the adapter for usage.

```APIDOC
## setup(name)

### Description
Prepare the adapter for usage. Creates necessary tables for adapters like Postgres.

### Parameters
#### Path Parameters
- **name** (atom) - Optional - The module name, defaults to __MODULE__.

### Response
#### Success Response (200)
- **result** (:ok) - Returns :ok on success.
```

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

### Backups and Portability

Source: https://hexdocs.pm/flippant/Flippant.html

Explains how to use `dump/1` and `load/1` for backing up and transferring feature configurations between different database adapters or servers.

```APIDOC
## Backups and Portability

The `dump/1` and `load/1` functions are handy for storing feature backups on disk. The backup may be used to transfer features between database servers, or even between adapters. For example, if you've decided to move away from using Redis and would like to switch to Postgres instead, you could transfer the data with a few commands:

```bash
# Dump from the Redis instance
Flippant.dump("flippant.dump")

# Restart the application
Application.stop(:flippant)
Application.put_env(:flippant, :adapter, Flippant.Adapter.Postgres)
Application.ensure_started(:flippant)

# Load to the postgres instance
Flippant.load("flippant.dump")
```
```

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

### Flippant Adapters Overview

Source: https://hexdocs.pm/flippant/api-reference.html

Information about the different storage adapters available for Flippant.

```APIDOC
## Flippant Adapters

Flippant supports various storage backends for feature rule management.

### Flippant.Adapter.Memory

This module provides ETS backed rule storage.

### Flippant.Adapter.Postgres

This adapter provides Postgres 9.5+ backed rule storage.

### Flippant.Adapter.Redis

This module provides Redis backed rule storage.
```

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

### Flippant.dump/1 and load/1

Source: https://hexdocs.pm/flippant/index.html

Functions for backing up and restoring feature configurations to disk.

```APIDOC
## Function: dump/1

### Description
Dump the full feature breakdown to a file for backup or portability.

### Parameters
- **path** (string) - Required - The file path to save the dump.

## Function: load/1

### Description
Restore all features from a dump file.

### Parameters
- **path** (string) - Required - The file path to load the dump from.
```

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

### Backup and Restore Features

Source: https://hexdocs.pm/flippant/index.html

Use `Flippant.dump/1` to store feature configurations to a file and `Flippant.load/1` to restore them. This is useful for transferring features between database servers or adapters, such as switching from Redis to Postgres.

```shell
# Dump from the Redis instance
Flippant.dump("flippant.dump")

# Restart the application
Application.stop(:flippant)
Application.put_env(:flippant, :adapter, Flippant.Adapter.Postgres)
Application.ensure_started(:flippant)

# Load to the postgres instance
Flippant.load("flippant.dump")
```

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

### List All Features

Source: https://hexdocs.pm/flippant/index.html

Lists all known features registered in the system. This provides an overview of all available features.

```elixir
Flippant.features()
#=> ["search", "delete"]

Flippant.features(:all)
#=> ["search", "delete"]
```

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

### load/2

Source: https://hexdocs.pm/flippant/Flippant.html

Restore all features from a JSON dump file.

```APIDOC
## load(name, path)

### Description
Restore all features from a dump file. The file is decoded as JSON. Loading is atomic but does not clear existing features.

### Parameters
#### Path Parameters
- **name** (atom) - Optional - The module name, defaults to __MODULE__.
- **path** (binary) - Required - The file path to the dump file.

### Response
#### Success Response (200)
- **result** (:ok) - Returns :ok on success.

#### Error Response
- **error** ({:error, File.posix() | binary()}) - Returns error tuple on failure.
```

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

### Memory Adapter Functions

Source: https://hexdocs.pm/flippant/Flippant.Adapter.Memory.html

This section details the functions available in the Flippant.Adapter.Memory module.

```APIDOC
## Functions

### `change_values(arg, rules, fun)`

#### Description
This function is part of the Flippant.Adapter.Memory module.

### Method
N/A (Function within a module)

### Endpoint
N/A

### Parameters
- **arg** (any) - Description not provided.
- **rules** (any) - Description not provided.
- **fun** (any) - Description not provided.

### Request Example
N/A

### Response
N/A

---

## `child_spec(init_arg)`

### Description
Returns a specification to start this module under a supervisor. See `Supervisor`.

### Method
N/A (Function within a module)

### Endpoint
N/A

### Parameters
- **init_arg** (any) - Description not provided.

### Request Example
N/A

### Response
N/A

---

## `init(opts)`

### Description
Callback implementation for `GenServer.init/1`.

### Method
N/A (Function within a module)

### Endpoint
N/A

### Parameters
- **opts** (any) - Description not provided.

### Request Example
N/A

### Response
N/A

---

## `start_link(opts \\ [])`

### Description
Starts the Memory adapter.

### Method
N/A (Function within a module)

### Endpoint
N/A

### Parameters
- **opts** (Keyword.t()) - Optional keyword list for starting the adapter.

### Specs
```elixir
start_link(Keyword.t()) :: GenServer.on_start()
```

### Request Example
N/A

### Response
N/A
```

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

### Flippant.Adapter.Postgres Functions

Source: https://hexdocs.pm/flippant/Flippant.Adapter.Postgres.html

Overview of the functions available in the Flippant Postgres adapter.

```APIDOC
## Functions

### `child_spec(init_arg)`

Returns a specification to start this module under a supervisor. See `Supervisor`.

### `init(opts)`

Callback implementation for `GenServer.init/1`.

### `start_link(opts \\ [])`

Starts the Postgres adapter.

#### Options

* `:postgres_opts` - Options that can be passed to Postgrex, the underlying library used to connect to Postgres. At a minimum the `database` must be set, otherwise it will attempt to connect to the `flippant_test` database.
* `table` - The table where rules will be stored. Defaults to `flippant_features`.
```

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

### Configure Flippant to use Memory adapter for testing

Source: https://hexdocs.pm/flippant/index.html

Configure the Flippant application to use the `Flippant.Adapters.Memory` for testing purposes. This adapter is cleared on application restart.

```elixir
config :flippant, adapter: Flippant.Adapters.Memory
```

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

### Create Flippant Features Table (SQL)

Source: https://hexdocs.pm/flippant/Flippant.Adapter.Postgres.html

Use this SQL statement to create the `flippant_features` table if you are managing your database with Ecto. Ensure your Postgres version is 9.5 or greater for `jsonb` support.

```sql
CREATE TABLE IF NOT EXISTS flippant_features (
  name varchar(140) NOT NULL CHECK (name <> ''),
  rules jsonb NOT NULL DEFAULT '{}'::jsonb,
  CONSTRAINT unique_name UNIQUE(name)
)
```

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

### Enable features for breakdown analysis

Source: https://hexdocs.pm/flippant/index.html

Enable 'search' for staff, 'delete' for everybody, and 'invite' for nobody to set up a scenario for the `breakdown/1` function.

```elixir
Flippant.enable("search", "staff")
Flippant.enable("delete", "everybody")
Flippant.enable("invite", "nobody")
```

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

### Flippant.Adapter.Redis Functions

Source: https://hexdocs.pm/flippant/Flippant.Adapter.Redis.html

This section details the functions available in the Flippant Redis Adapter module.

```APIDOC
## Flippant.Adapter.Redis API

### Description
This module provides Redis backed rule storage for Flippant.

### Functions

#### `child_spec(init_arg)`

##### Description
Returns a specification to start this module under a supervisor.

##### Method
N/A (Function definition)

##### Endpoint
N/A

#### `init(opts)`

##### Description
Callback implementation for `GenServer.init/1`.

##### Method
N/A (Function definition)

##### Endpoint
N/A

#### `start_link(opts \\ [])`

##### Description
Starts the Redis adapter.

##### Method
N/A (Function definition)

##### Endpoint
N/A

### Options for `start_link`

#### `:redis_opts`
- **Type**: list
- **Description**: Options that can be passed to Redix, the underlying library used to connect to Redis. Defaults to `[]`.

#### `:set_key`
- **Type**: string
- **Description**: The Redis key where rules will be stored. Defaults to `"flippant-features"`.
```

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

### Dump Feature Breakdown

Source: https://hexdocs.pm/flippant/Flippant.html

Export the current feature configuration to a file.

```elixir
dump(name :: atom(), binary()) :: :ok | {:error, File.posix()}
```

```elixir
Flippant.dump((Date.utc_today() |> Date.to_string()) <> ".dump")
#=> :ok
```

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

### Flippant Dump API

Source: https://hexdocs.pm/flippant/Flippant.html

Dump the full feature breakdown to a file, which can be used for portability between adapters.

```APIDOC
## POST /api/flippant/dump

### Description
Dumps the full feature breakdown to a file. This is useful for creating portable backups of feature configurations.

### Method
POST

### Endpoint
/api/flippant/dump

### Parameters
#### Request Body
- **path** (binary) - Required - The file path where the dump should be saved.

### Request Example
```json
{
  "path": "/path/to/dump.json"
}
```

### Response
#### Success Response (200)
- **:ok** - Indicates that the dump was successful.
- **{:error, File.posix()}** - Indicates an error occurred during the dump process.

### Response Example
```json
:ok
```
```

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

### Adapter Specification

Source: https://hexdocs.pm/flippant/Flippant.html

Retrieve the PID of the configured adapter process.

```elixir
adapter(name :: atom()) :: pid() | nil
```

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

### Enable 'search' for 'everybody' and disable for 'nobody'

Source: https://hexdocs.pm/flippant/index.html

Demonstrates how multiple rules and groups interact. The 'search' feature is enabled for 'everybody' and also enabled for 'nobody', resulting in it being enabled for any user due to the 'everybody' rule taking precedence.

```elixir
Flippant.enable("search", "everybody")
Flippant.enable("search", "nobody")

Flippant.enabled?("search", %User{}) #=> true
```

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

### Enable Features

Source: https://hexdocs.pm/flippant/Flippant.html

Grant feature access to a group, optionally with specific values.

```elixir
enable(binary(), binary(), [any()]) :: :ok
```

```elixir
Flippant.enable("search", "radical")
#=> :ok
```

```elixir
Flippant.enable("search", "awesome", [1, 2, 3])
#=> :ok
```

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

### Register an 'adopters' group for percentage rollout

Source: https://hexdocs.pm/flippant/index.html

Register a group that enables a feature for a percentage of actors based on their ID. It expects a list of integers between 1 and 10, and enables the feature if the actor's ID modulo 10 is in the provided list.

```elixir
Flippant.register("adopters", fn
  _actor, [] -> false
  %User{id: id}, samples -> rem(id, 10) in samples
end)
```

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

### Check if 'search' feature is enabled for different users

Source: https://hexdocs.pm/flippant/index.html

Check the enabled status of the 'search' feature for a staff user, an early adopter, and a later adopter. Demonstrates how rules are evaluated against different actor types.

```elixir
staff_user = %User{id: 1, staff?: true}
early_user = %User{id: 2, staff?: false}
later_user = %User{id: 3, staff?: false}

Flippant.enabled?("search", staff_user) #=> true, staff
Flippant.enabled?("search", early_user) #=> false, not an adopter
Flippant.enabled?("search", later_user) #=> true, is an adopter
```

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

### Flippant.Adapter.Postgres Table Structure

Source: https://hexdocs.pm/flippant/Flippant.Adapter.Postgres.html

The Postgres adapter relies on a table with specific columns for storing feature rules.

```APIDOC
## Table Structure Requirements

The adapter relies on a table with the following structure:

* `name` - A `text` or `varchar` column with a unique constraint. The adapter makes heavy use of `UPSERT` functionality, which relies on unique names.
* `rules` - A `jsonb` column where rules will be stored. The use of jsonb and jsonb specific operators means the Postgres version must be 9.5 or greater.
```

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

### Flippant Rules Module Overview

Source: https://hexdocs.pm/flippant/Flippant.Rules.html

Overview of the Flippant Rules module, its purpose, and key components.

```APIDOC
## Flippant.Rules Behaviour (Flippant v2.0.0)

The Rules module glues rules, actors, and groups together.

### Types
- `actor()`
- `rules()`

### Functions
- `enabled_for_actor?(name, rules, actor)`: Checks if any rules are enabled for a specific actor.

### Callbacks
- `enabled?(group, enabled_for, actor)`: Validates if an actor belongs to a group and is in an enabled list.
```

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

### Flippant Enable API

Source: https://hexdocs.pm/flippant/Flippant.html

Enable a feature for a particular group, optionally with specific values.

```APIDOC
## POST /api/flippant/enable

### Description
Enables a feature for a particular group. Features can be enabled with a set of values, which are useful for limiting a feature to a subset of actors.

### Method
POST

### Endpoint
/api/flippant/enable

### Parameters
#### Request Body
- **feature** (binary) - Required - The name of the feature to enable.
- **group** (binary) - Required - The name of the group to enable the feature for.
- **values** (list) - Optional - A list of specific values to associate with the enabled feature.

### Request Example
```json
{
  "feature": "search",
  "group": "radical"
}
```

### Response
#### Success Response (200)
- **:ok** - Indicates that the feature has been successfully enabled for the specified group and values.

### Response Example
```json
:ok
```
```

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

### Enable 'search' feature for a percentage of adopters

Source: https://hexdocs.pm/flippant/index.html

Enable the 'search' feature for a specific percentage of actors in the 'adopters' group, defined by the provided list of sample values.

```elixir
# 30% of "adopters" can use the "search" feature as well
Flippant.enable("search", "adopters", [0, 1, 2])
```

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

### Flippant Functions

Source: https://hexdocs.pm/flippant/Flippant.html

Provides a reference for core Flippant functions, including adapter retrieval, feature management, and state inspection.

```APIDOC
## Functions

### adapter(name \\ __MODULE__)

Retrieve the `pid` of the configured adapter process.

#### Specs
```elixir
adapter(name :: atom()) :: pid() | nil
```

This will return `nil` if the adapter hasn't been started.

### add(name \\ __MODULE__, feature)

Add a new feature without any rules.

#### Specs
```elixir
add(name :: atom(), feature :: binary()) :: :ok
```

Adding a feature does not enable it for any groups, that can be done using `enable/2` or `enable/3`.

#### Examples
```elixir
Flippant.add("search")
#=> :ok
```

### breakdown(actor \\ :all)

Generate a mapping of all features and associated rules.

#### Specs
```elixir
breakdown(actor :: map() | struct() | :all) :: map()
```

Breakdown without any arguments defaults to `:all`, and will list all registered features along with their group and value metadata. It is the only way to retrieve a snapshot of all the features in the system. The operation is optimized for round-trip efficiency.
Alternatively, breakdown takes a single `actor` argument, typically a `%User{}` struct or some other entity. It generates a map outlining which features are enabled for the actor.

### breakdown(name, actor)

### child_spec(init_arg)

Returns a specification to start this module under a supervisor.

### clear(name \\ __MODULE__)

Purge registered features.

### disable(feature, group, values \\ [])

Disable a feature for a particular group.

### disable(name, feature, group, values)

### dump(name \\ __MODULE__, path)

Dump the full feature breakdown to a file.

### enable(feature, group, values \\ [])

Enable a feature for a particular group.

### enable(name, feature, group, values)

### enabled?(name \\ __MODULE__, feature, actor)

Check if a particular feature is enabled for an actor.

### exists?(feature, group \\ :any)

Check whether a given feature has been registered.

### exists?(name, feature, group)

### features(group \\ :all)

List all known features or only features enabled for a particular group.

### features(name, group)

### load(name \\ __MODULE__, path)

Restore all features from a dump file.

### remove(name \\ __MODULE__, feature)

Fully remove a feature for all groups.

### rename(name \\ __MODULE__, old_name, new_name)

Rename an existing feature.

### setup(name \\ __MODULE__)

Prepare the adapter for usage.

### start_link(opts \\ [])

Start a Flippant process linked to the current process.
```

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

### Load Features

Source: https://hexdocs.pm/flippant/index.html

Restores all features from a dump file. The file is decoded as JSON. Loading happens atomically but does not clear existing features. Use `clear/1` first for a clean restore.

```APIDOC
## POST /features/load

### Description
Restores all features from a dump file.

### Method
POST

### Endpoint
/features/load

### Parameters
#### Query Parameters
- **name** (atom) - Required - The name of the feature set.
- **path** (binary) - Required - The path to the dump file.

### Request Body
None

### Response
#### Success Response (200)
- **:ok** (:ok) - Indicates the features were loaded successfully.

#### Error Response (400)
- **{:error, File.posix() | binary()}** ({:error, term()}) - Indicates an error during loading, with the error reason.

### Request Example
```json
{
  "name": "features",
  "path": "backup.dump"
}
```

### Response Example
```json
:ok
```
```

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

### Load Features from Dump File

Source: https://hexdocs.pm/flippant/index.html

Restores all features from a JSON-encoded dump file. Loading is atomic but does not clear existing features; run `clear/1` first for a clean restore.

```elixir
load(name :: atom(), binary()) :: :ok | {:error, File.posix() | binary()}
```

```elixir
Flippant.clear(:features)
#=> :ok
Flippant.load("backup.dump")
#=> :ok
```

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

### Flippant Enable API

Source: https://hexdocs.pm/flippant/index.html

Enable a feature for a specific group, optionally for a set of values within that group.

```APIDOC
## POST /api/flippant/enable

### Description
Enables a feature for a particular group. Features can be enabled with specific values, which are useful for limiting feature access to a subset of actors.

### Method
POST

### Endpoint
/api/flippant/enable

### Parameters
#### Request Body
- **feature** (binary) - Required - The name of the feature to enable.
- **group** (binary) - Required - The name of the group for which to enable the feature.
- **values** (list) - Optional - A list of specific values for which to enable the feature.

### Request Example
```json
{
  "feature": "search",
  "group": "radical"
}
```

### Response
#### Success Response (200)
- **:ok** - Indicates that the feature has been successfully enabled for the group.

### Response Example
```json
:ok
```
```

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

### Flippant Dump API

Source: https://hexdocs.pm/flippant/index.html

Dump the full feature breakdown to a JSON file.

```APIDOC
## POST /api/flippant/dump

### Description
Dumps the full feature breakdown to a JSON file at the specified path. This dump is portable and can be used to load data into other adapters.

### Method
POST

### Endpoint
/api/flippant/dump

### Parameters
#### Request Body
- **path** (binary) - Required - The file path where the JSON dump should be saved.

### Response
#### Success Response (200)
- **:ok** - Indicates that the feature breakdown was successfully dumped to the file.
#### Error Response (500)
- **{:error, File.posix()}** - Indicates an error occurred while writing to the file.

### Response Example
```json
:ok
```
```

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

### List Features

Source: https://hexdocs.pm/flippant/Flippant.html

Retrieve a list of all known features or those enabled for a specific group.

```elixir
features(:all | binary()) :: [binary()]
```

```elixir
Flippant.features()
#=> ["search", "delete"]

Flippant.features(:all)
#=> ["search", "delete"]
```

```elixir
Flippant.features("awesome")
#=> ["search"]
```

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

### Managing Feature Rules

Source: https://hexdocs.pm/flippant/Flippant.html

Enable or disable features for specific groups at runtime.

```elixir
# Any staff can use the "search" feature
Flippant.enable("search", "staff")

# 30% of "adopters" can use the "search" feature as well
Flippant.enable("search", "adopters", [0, 1, 2])
```

```elixir
# Turn search off for adopters
Flippant.disable("search", "adopters")

# On second thought, enable it again for 10% of users
Flippant.enable("search", "adopters", [3])
```

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

### HexDocs Keyboard Shortcuts

Source: https://hexdocs.pm/flippant/Flippant.Rules.Default.html

Keyboard shortcuts for navigating the HexDocs interface.

```APIDOC
## Keyboard Shortcuts

### Description
These shortcuts help you navigate the HexDocs interface efficiently.

### Shortcuts
- `c`: Toggle sidebar
- `n`: Toggle night mode
- `/` or `s`: Focus search bar
- `g`: Go to a HexDocs package
- `?`: Bring up this help dialog
```

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

### Define Feature Specs

Source: https://hexdocs.pm/flippant/index.html

Defines the signature for features, accepting a name and either :all or a binary.

```elixir
features(name :: atom(), :all | binary()) :: [binary()]
```

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

### Flippant.add/2

Source: https://hexdocs.pm/flippant/index.html

Adds a new feature to the system without enabling it for any groups.

```APIDOC
## Function: add/2

### Description
Add a new feature without any rules. Adding a feature does not enable it for any groups; that can be done using enable/2 or enable/3.

### Parameters
- **name** (atom) - Optional - The name of the Flippant process (defaults to __MODULE__).
- **feature** (binary) - Required - The name of the feature to add.

### Response
- **:ok** (atom) - Returned upon successful addition of the feature.

### Example
Flippant.add("search")
#=> :ok
```

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

### Re-enable 'search' feature for a smaller percentage of adopters

Source: https://hexdocs.pm/flippant/index.html

Re-enable the 'search' feature for a smaller percentage of actors in the 'adopters' group, specified by the new list of sample values.

```elixir
# On second thought, enable it again for 10% of users
Flippant.enable("search", "adopters", [3])
```

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

### Flippant Rules Management

Source: https://hexdocs.pm/flippant/api-reference.html

Details on how Flippant manages feature rules, actors, and groups.

```APIDOC
## Flippant.Rules

The Rules module glues rules, actors, and groups together.

### Flippant.Rules.Default

The default rules defines `nobody` and `everybody`.
```

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

### Registering Groups

Source: https://hexdocs.pm/flippant/Flippant.html

Define groups by registering a name and an evaluation function that checks actor properties.

```elixir
Flippant.register("nobody", fn(_actor, _values) -> false end)
```

```elixir
Flippant.register("everybody", fn(_actor, _values) -> true end)
```

```elixir
Flippant.register("staff", fn
  %User{staff?: staff?}, _values -> staff?
end)
```

```elixir
Flippant.register("adopters", fn
  _actor, [] -> false
  %User{id: id}, samples -> rem(id, 10) in samples
end)
```

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

### Flippant.Rules.Default

Source: https://hexdocs.pm/flippant/Flippant.Rules.Default.html

The default rules define 'nobody' and 'everybody' for feature flagging.

```APIDOC
## Flippant.Rules.Default

### Description
The default rules define `nobody` and `everybody`.

### Rules
- `nobody`: No users are included by default.
- `everybody`: All users are included by default.
```

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

### Dump Feature Breakdown to File

Source: https://hexdocs.pm/flippant/index.html

Dumps the full feature breakdown to a JSON file. This is useful for creating portable backups or migrating feature configurations between adapters.

```elixir
Flippant.dump((Date.utc_today() |> Date.to_string()) <> ".dump")
#=> :ok
```

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

### Restore features from a dump file

Source: https://hexdocs.pm/flippant/Flippant.html

Restores features from a JSON dump file. Run clear/1 before loading to ensure a clean state.

```elixir
Flippant.clear(:features) #=> :ok
Flippant.load("backup.dump") #=> :ok
```

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

### Flippant Rules Callbacks

Source: https://hexdocs.pm/flippant/Flippant.Rules.html

Describes the callback functions used in the Flippant Rules module.

```APIDOC
## Callbacks

### enabled?(group, enabled_for, actor)

View Source
#### Specs
```elixir
enabled?(group :: binary(), enabled_for :: list(), actor :: Rules.actor()) :: boolean()
```

#### Description
Validate that an actor is both a member of `group` and in the `enabled_for` list. For example, if we had a `staff` group, and a rule containing `%{"staff" => ids}`, we could have a function like this:

```elixir
  def enabled?("staff", enabled_for, %{staff: true} = actor) do
    Enum.any?(enabled_for, &actor.id == &1.id)
  end
```

This both validates the actor is staff, and that the actor is in the enabled list. Allowing rules definition in this way makes the logic for rule checking very visible in application code.
```

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

### Flippant Exists? API

Source: https://hexdocs.pm/flippant/index.html

Check whether a given feature has been registered.

```APIDOC
## GET /api/flippant/exists

### Description
Checks if a feature has been registered within the Flippant system. Optionally, it can check if the feature has any rules defined for a specific group.

### Method
GET

### Endpoint
/api/flippant/exists

### Parameters
#### Query Parameters
- **feature** (binary) - Required - The name of the feature to check.
- **group** (binary | :any) - Optional - The name of the group to check for rules. Defaults to `:any`.

### Response
#### Success Response (200)
- **boolean** - `true` if the feature exists (and optionally has rules for the group), `false` otherwise.

### Response Example
```json
true
```
```

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

### Enable 'search' feature for staff

Source: https://hexdocs.pm/flippant/index.html

Enable the 'search' feature for all actors belonging to the 'staff' group.

```elixir
# Any staff can use the "search" feature
Flippant.enable("search", "staff")
```

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

### Add Feature

Source: https://hexdocs.pm/flippant/Flippant.html

Register a new feature without enabling it for any groups.

```elixir
add(name :: atom(), feature :: binary()) :: :ok
```

```elixir
Flippant.add("search")
#=> :ok
```

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

### Flippant Rules Functions

Source: https://hexdocs.pm/flippant/Flippant.Rules.html

Details the functions available in the Flippant Rules module.

```APIDOC
## Functions

### enabled_for_actor?(name, rules, actor)

View Source
#### Specs
```elixir
enabled_for_actor?(name :: atom(), rules(), actor()) :: boolean()
```

#### Description
Check whether any rules are enabled for a particular actor. The function accepts a list of names/value pairs and an actor.
```

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

### Flippant Features API

Source: https://hexdocs.pm/flippant/index.html

List all known features or only features enabled for a particular group.

```APIDOC
## GET /api/flippant/features

### Description
Retrieves a list of all registered features, or filters the list to show only features enabled for a specific group.

### Method
GET

### Endpoint
/api/flippant/features

### Parameters
#### Query Parameters
- **group** (binary | :all) - Optional - The name of the group to filter features by. Defaults to `:all`.

### Response
#### Success Response (200)
- **list** - A list of feature names (binary strings).

### Response Example
```json
["search", "delete"]
```
```

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

### Register an 'everybody' group

Source: https://hexdocs.pm/flippant/index.html

Register a group that all actors can belong to, useful for enabling features universally.

```elixir
Flippant.register("everybody", fn(_actor, _values) -> true end)
```

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

### List Features Enabled for a Group

Source: https://hexdocs.pm/flippant/index.html

Lists features that are enabled for a specific group. This helps in understanding which features are active for a particular segment of users or system components.

```elixir
Flippant.features("awesome")
#=> ["search"]
```

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

### Evaluating Feature Breakdown

Source: https://hexdocs.pm/flippant/Flippant.html

Retrieve a map of all feature statuses for an actor to avoid multiple database round trips.

```elixir
Flippant.enable("search", "staff")
Flippant.enable("delete", "everybody")
Flippant.enable("invite", "nobody")

Flippant.breakdown(%User{id: 1, staff?: true})
#=> %{"search" => true, "delete" => true, "invite" => false}
```

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

### Check actor eligibility

Source: https://hexdocs.pm/flippant/Flippant.Rules.html

Specification for the enabled_for_actor? function.

```elixir
enabled_for_actor?(name :: atom(), rules(), actor()) :: boolean()
```

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

### Verify Feature Existence

Source: https://hexdocs.pm/flippant/Flippant.html

Check if a feature is registered, optionally filtering by group.

```elixir
exists?(binary(), binary() | :any) :: boolean()
```

```elixir
Flippant.exists?("search")
#=> false

Flippant.add("search")
Flippant.exists?("search")
#=> true
```

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

### Clear features from Memory adapter

Source: https://hexdocs.pm/flippant/index.html

Manually clear all features stored in the `Flippant.Adapters.Memory`. This is useful for resetting the state between test runs.

```elixir
Flippant.clear(:features)
```

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

### Flippant Clear API

Source: https://hexdocs.pm/flippant/index.html

Purge all registered features, useful for resetting the state, especially in testing environments.

```APIDOC
## POST /api/flippant/clear

### Description
Purges all registered features. This is particularly useful in testing scenarios to reset the feature flag state.

### Method
POST

### Endpoint
/api/flippant/clear

### Response
#### Success Response (200)
- **:ok** - Indicates that the features have been successfully cleared.

### Response Example
```json
:ok
```
```

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

### Register a 'staff' group

Source: https://hexdocs.pm/flippant/index.html

Register a group to identify actors who are staff members. This function checks the `staff?` attribute of a `%User{}` struct.

```elixir
Flippant.register("staff", fn
  %User{staff?: staff?}, _values -> staff?
end)
```

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

### Flippant Enabled? API

Source: https://hexdocs.pm/flippant/index.html

Check if a particular feature is enabled for a given actor.

```APIDOC
## GET /api/flippant/enabled

### Description
Checks if a specific feature is enabled for a given actor. The feature is considered enabled if the actor belongs to any group that has access to it.

### Method
GET

### Endpoint
/api/flippant/enabled

### Parameters
#### Query Parameters
- **feature** (binary) - Required - The name of the feature to check.
- **actor** (map | struct) - Required - The actor object to check against.

### Response
#### Success Response (200)
- **boolean** - `true` if the feature is enabled for the actor, `false` otherwise.

### Response Example
```json
false
```
```

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

### Checking Feature Status

Source: https://hexdocs.pm/flippant/Flippant.html

Verify if a feature is enabled for a specific actor based on registered rules.

```elixir
staff_user = %User{id: 1, staff?: true}
early_user = %User{id: 2, staff?: false}
later_user = %User{id: 3, staff?: false}

Flippant.enabled?("search", staff_user) #=> true, staff
Flippant.enabled?("search", early_user) #=> false, not an adopter
Flippant.enabled?("search", later_user) #=> true, is an adopter
```

```elixir
Flippant.enable("search", "everybody")
Flippant.enable("search", "nobody")

Flippant.enabled?("search", %User{}) #=> true
```

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

### Flippant.breakdown/1

Source: https://hexdocs.pm/flippant/index.html

Retrieves a mapping of features and their associated rules or enabled status for a specific actor.

```APIDOC
## Function: breakdown/1

### Description
Generate a mapping of all features and associated rules. If no actor is provided, it lists all registered features with metadata. If an actor is provided, it returns a map of features enabled for that specific actor.

### Parameters
- **actor** (map | struct | :all) - Optional - The actor to check features against, or :all to list all features.

### Response
- **map** - A map containing feature breakdown data.

### Example
Flippant.breakdown(:all)
#=> %{"search" => %{...}}
```

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

### Check Feature Status

Source: https://hexdocs.pm/flippant/Flippant.html

Determine if a feature is enabled for a specific actor.

```elixir
enabled?(name :: atom(), binary(), map() | struct()) :: boolean()
```

```elixir
Flippant.enabled?("search", actor)
#=> false
```

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

### Add a New Feature

Source: https://hexdocs.pm/flippant/index.html

Add a new feature without any associated rules using `Flippant.add/1`. This function does not enable the feature for any groups; use `enable/2` or `enable/3` for that purpose.

```elixir
Flippant.add("search")
#=> :ok
```

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

### Flippant Breakdown API

Source: https://hexdocs.pm/flippant/index.html

Retrieve the breakdown of enabled features for all groups or a specific actor.

```APIDOC
## GET /api/flippant/breakdown

### Description
Retrieves the feature breakdown for all groups or a specific actor.

### Method
GET

### Endpoint
/api/flippant/breakdown

### Parameters
#### Query Parameters
- **actor** (map | struct | :all) - Optional - The actor for whom to retrieve the breakdown. If not provided, the breakdown for all groups is returned.

### Response
#### Success Response (200)
- **map** - A map representing the feature breakdown.

### Response Example
```json
{
  "search": {
    "awesome": [],
    "heinous": []
  },
  "delete": {
    "radical": []
  },
  "invite": {
    "heinous": []
  }
}
```
```

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

### Register a 'nobody' group

Source: https://hexdocs.pm/flippant/index.html

Register a group that no actor can belong to, useful for disabling features.

```elixir
Flippant.register("nobody", fn(_actor, _values) -> false end)
```

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

### rename/3

Source: https://hexdocs.pm/flippant/Flippant.html

Rename an existing feature.

```APIDOC
## rename(name, old_name, new_name)

### Description
Rename an existing feature. If the new name exists, it will be overwritten.

### Parameters
#### Path Parameters
- **name** (atom) - Optional - The module name, defaults to __MODULE__.
- **old_name** (binary) - Required - The current name of the feature.
- **new_name** (binary) - Required - The new name for the feature.

### Response
#### Success Response (200)
- **result** (:ok) - Returns :ok on success.
```

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

### Generate Feature Breakdown

Source: https://hexdocs.pm/flippant/Flippant.html

Retrieve a mapping of features and rules, optionally filtered by a specific actor.

```elixir
breakdown(actor :: map() | struct() | :all) :: map()
```

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

### Flippant Rules Types

Source: https://hexdocs.pm/flippant/Flippant.Rules.html

Defines the types used within the Flippant Rules module.

```APIDOC
## Types

### actor()

View Source
#### Specs
```elixir
actor() :: term()
```

### rules()

View Source
#### Specs
```elixir
rules() :: Enumerable.t()
```
```

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

### remove/2

Source: https://hexdocs.pm/flippant/Flippant.html

Fully remove a feature for all groups.

```APIDOC
## remove(name, feature)

### Description
Fully remove a feature for all groups.

### Parameters
#### Path Parameters
- **name** (atom) - Optional - The module name, defaults to __MODULE__.
- **feature** (binary) - Required - The name of the feature to remove.

### Response
#### Success Response (200)
- **result** (:ok) - Returns :ok on success.
```

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

### Check if Feature Exists

Source: https://hexdocs.pm/flippant/index.html

Checks if a feature has been registered. Optionally, it can check if the feature has any rules defined for a specific group.

```elixir
Flippant.exists?("search")
#=> false

Flippant.add("search")
Flippant.exists?("search")
#=> true
```

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

### Disable 'search' feature for adopters

Source: https://hexdocs.pm/flippant/index.html

Disable the 'search' feature for actors belonging to the 'adopters' group.

```elixir
# Turn search off for adopters
Flippant.disable("search", "adopters")
```

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

### Flippant Breakdown API

Source: https://hexdocs.pm/flippant/Flippant.html

Retrieve the breakdown of features for all groups or a specific actor.

```APIDOC
## GET /api/flippant/breakdown

### Description
Retrieves the feature breakdown for all groups or a specific actor.

### Method
GET

### Endpoint
/api/flippant/breakdown

### Parameters
#### Query Parameters
- **actor** (map | struct | :all) - Optional - The actor for whom to get the breakdown. Defaults to :all.

### Response
#### Success Response (200)
- **map** - A map representing the feature breakdown.

### Response Example
```json
{
  "search": {
    "awesome": [],
    "heinous": []
  },
  "delete": {
    "radical": []
  },
  "invite": {
    "heinous": []
  }
}
```
```
Tokens:
Raw