@spec cast_flow_slug(term()) :: {:ok, String.t()} | {:error, :invalid_flow_slug}

Normalizes an atom or string flow slug and rejects unsupported values.

This only normalizes the Elixir value. Callers that interpolate a slug into SQL must additionally validate it with PgFlow's database slug rules.

@spec cast_uuid(term()) :: {:ok, Ecto.UUID.t()} | {:error, :invalid_id}

Casts a UUID to its canonical string form and fails closed for invalid IDs.

@spec direction_to_string(:next | :prev | String.t()) :: String.t()

Converts a direction atom to string for database queries.

@spec execute_rpc(module(), String.t(), list(), keyword()) ::
  {:ok, nil | map() | [map()]}
  | {:error, :not_found | term()}
  | [map()]
  | integer()

Executes an RPC-style call to a PostgreSQL function.

Parameters

• repo - The Ecto repository
• function_name - Name of the PostgreSQL function
• params - List of parameters to pass
• opts - Options keyword list

Options

• :schema - (required) The PostgreSQL schema containing the function
• :mode - Result handling mode: :list, :single, :count, :void, :raw

Returns

Depends on mode:

• :list - Returns list of maps
• :single - Returns {:ok, map} or {:error, :not_found}
• :count - Returns integer count
• :void - Returns {:ok, nil}
• :raw - Returns {:ok, list of maps} or error

@spec format_uuid(nil | binary()) :: nil | String.t()

Formats a binary UUID to string representation.

@spec health_status_to_string(nil | atom() | String.t()) :: nil | String.t()

Converts a health status atom or string to string for database queries.

@spec optional_uuid(term()) :: {:ok, Ecto.UUID.t() | nil} | {:error, :invalid_id}

Casts an optional UUID while preserving nil.

@spec parse_uuid(nil | String.t() | binary()) :: nil | binary()

Parses a UUID string to binary format for database queries.

@spec positive_limit(
  keyword(),
  pos_integer()
) :: pos_integer()

Returns a positive :limit option or the supplied positive default.

@spec status_to_string(nil | atom() | String.t()) :: nil | String.t()

Converts a status atom or string to string for database queries.

@spec time_range_start(atom()) :: DateTime.t()

Converts a time range atom to a start DateTime.