Behaviour for applicative operations across monad DSLs.

Ap (apply) is the applicative functor operation that produces a wrapped function to be applied to wrapped values. This allows for function application within a computational context.

Contract

@callback ap(value :: any(), opts :: keyword(), env :: keyword()) ::
  {:ok, (any() -> any())}
  | {:error, any()}
  | Either.t((any() -> any()), any())
  | Maybe.t((any() -> any()))

Arguments

• value - The value to use for producing the function
• opts - Keyword list of options (module-specific configuration)
• env - Environment/context from DSL (for Reader-like dependency injection)

Return Values

Monad types (preferred):

• Either.right(fn) - Success with a function
• Either.left(error) - Failure with error
• Maybe.just(fn) - Success with a function
• Maybe.nothing() - Failure (no function)

Tagged tuples (supported):

• {:ok, fn} - Operation succeeded with a function
• {:error, reason} - Operation failed with error

The DSL will normalize all these return values into the appropriate monad type.

Cross-Monad Normalization

When an ap module returns a monad type different from the current DSL context, the result is automatically normalized:

Maybe → Either:

• Just(fn) → Right(fn)
• Nothing → Left(:nothing) (uses :nothing atom as error)

Either → Maybe:

• Right(fn) → Just(fn)
• Left(_error) → Nothing (error information is discarded)

Semantic Rules

1. Arguments strictly ordered: value, opts, env
2. May use env for Reader-like dependency injection (only way to access env - functions cannot)
3. Produces a function - returns a wrapped function, not a wrapped value
4. Can fail - use this for operations that might not produce a function

Examples

Basic Applicative

defmodule Multiplier do
  @behaviour Funx.Monad.Behaviour.Ap
  import Funx.Monad.Either

  @impl true
  def ap(factor, _opts, _env) when is_number(factor) do
    right(fn x -> x * factor end)
  end

  def ap(_value, _opts, _env), do: left("Expected number for factor")
end

# Usage in Either DSL
use Funx.Monad.Either

either 5 do
  ap Multiplier
end
# First evaluates Multiplier.ap(5, []) -> Right(fn x -> x * 5 end)
# Then applies: fn x -> x * 5 end to 5 -> 25
#=> %Right{right: 25}

With Options

defmodule ConditionalOperator do
  @behaviour Funx.Monad.Behaviour.Ap
  import Funx.Monad.Either

  @impl true
  def ap(value, opts, _env) do
    op = Keyword.get(opts, :operation, :add)

    case op do
      :add -> right(fn x -> x + value end)
      :multiply -> right(fn x -> x * value end)
      :subtract -> right(fn x -> x - value end)
      _ -> left("Unknown operation: #{op}")
    end
  end
end

# Usage
either 10 do
  ap {ConditionalOperator, operation: :multiply}
end
#=> %Right{right: 100}

Failure Cases

defmodule ValidatedOperator do
  @behaviour Funx.Monad.Behaviour.Ap
  import Funx.Monad.Either

  @impl true
  def ap(value, _opts, _env) when is_number(value) and value > 0 do
    right(fn x -> x + value end)
  end

  def ap(value, _opts, _env) when is_number(value) do
    left("Factor must be positive, got: #{value}")
  end

  def ap(_value, _opts, _env), do: left("Expected number")
end

# Success
either 5 do
  ap ValidatedOperator
end
#=> %Right{right: 10}

# Failure
either -3 do
  ap ValidatedOperator
end
#=> %Left{left: "Factor must be positive, got: -3"}