Valence — Getting Started

Copy Markdown View Source

Guia curto para o Valence 1.0: tipos em Elixir normal, arquivos .val e LSP.

Requisitos

  • Elixir 1.20+ (OTP 27+).
  • Mix.
  • Opcional: Zed para o LSP.

Instalação

No mix.exs do projeto:

defp deps do
  [
    {:valence, "~> 1.0", runtime: false}
  ]
end

def project do
  [
    compilers: [:valence, :phoenix_live_view] ++ Mix.compilers(),
    deps: deps()
  ]
end

Sem Phoenix, use compilers: [:valence] ++ Mix.compilers().

mix deps.get
mix compile

Primeiro .val

lib/minha_app/scoring.val:

defmodule MinhaApp.Scoring do
  @spec classificar(non_neg_integer()) :: :low | :mid | :high
  def classificar(score) when score < 50, do: :low
  def classificar(score) when score < 100, do: :mid
  def classificar(_score), do: :high
end

O modo estrito exige @spec em def público, confere o corpo contra o retorno e trata case não-exaustivo como erro. @impl isenta callbacks.

mix compile
mix valence.check "lib/**/*.ex" "lib/**/*.val"
mix valence.type lib/minha_app/scoring.val:2:5

LSP no Zed

Adicione a dep acima e instale a extensão:

  1. Cmd+Shift+P → zed: install dev extension → zed-valence/.
  2. Abra um .val. A extensão inicia mix valence.lsp no projeto.
  3. Para formatar ao salvar:
"languages": {
  "Val": {
    "formatter": "language_server",
    "format_on_save": "on"
  }
}

Fora de um projeto Mix, instale o escript (mix escript.install hex valence) e use valence lsp.

LiveView

defmodule MinhaAppWeb.ProducersLive do
  use MinhaAppWeb, :live_view

  @impl true
  def mount(_params, _session, socket) do
    {:ok, assign(socket, :producers, MinhaApp.Producers.list())}
  end

  @impl true
  def render(assigns) do
    ~H"""
    <ul id="producers">
      <li :for={producer <- @producers}>{producer.name}</li>
    </ul>
    """
  end
end

Com reloadable_compilers no endpoint de dev, alterações em .val recarregam sem reiniciar o servidor:

# config/dev.exs
config :minha_app, MinhaAppWeb.Endpoint,
  reloadable_compilers: [:phoenix_live_view, :gettext, :elixir, :valence, :app]

Recursos úteis

  • Hover/completion/diagnóstico no LSP, inclusive de Ecto/Phoenix.
  • Assigns @nome tipados no HEEx.
  • PubSub: handle_info({:evento, payload}, ...) tipado pelo broadcast.
  • Cmd+S formata; Cmd+. oferece # valence:ignore e @impl true.
  • Snippets de callbacks (mount, render, handle_event, …).

Problemas comuns

sintomacausacorreção
task valence.* não encontradadep não compiladamix deps.get/mix compile
LSP não inicia no Zedprojeto sem dep valenceadicione a dep e reinicie o LSP
hover de função própria em dynamic()sem @spec e corpo dinâmicodeclare @spec
mix format ignora .valfora dos inputsadicione lib/**/*.val ao .formatter.exs

Mais detalhes: README.md e docs/VAL_AND_ZED.md.