Choreo.Lab.Compose (Choreo v0.12.0)

Pipe-friendly composition helpers for assembling Choreo models in Livebook.

This module is ordinary Elixir, not a macro DSL. It is a thin convenience layer over the stable composition primitives in Choreo: clusters, embedding, normal graph connections, and semantic trace links.

Choreo remains the primitive composition API. Choreo.Lab.Compose is the ergonomic exploration API for building larger composed models from smaller Choreo diagrams.

Prefer alias-qualified usage for better editor autocomplete:

alias Choreo.Lab.Compose

Choreo.new()
|> Compose.cluster("system", label: "System")
|> Compose.embed(infra, into: "system", as: :infra)
|> Compose.embed(auth_fsm, into: "system", as: :auth)
|> Compose.trace(:infra_auth, :auth_unauthenticated, :executes)

connect/4 creates a normal visible relationship. trace/4 creates a semantic cross-model relationship that Choreo.Analysis.Tracing and Choreo.View.focus_trace/4 can follow.

Summary

Types

cluster_id()

node_id()

system()

Functions

cluster(system, name, opts \\ [])

Adds a visual cluster/grouping boundary to a composed system.

connect(system, from, to, label_or_opts \\ [])

Connects two nodes with a normal visible relationship.

embed(system, child, opts)

Embeds a child diagram into a cluster of the parent system.

taxonomy()

Returns the composition helper vocabulary for Livebook discovery.

trace(system, from, to, type_or_opts \\ [])

Adds a semantic trace relationship between two nodes.

verbs()

Compatibility alias for taxonomy/0.

Types

cluster_id()

@type cluster_id() :: String.t() | atom()

node_id()

@type node_id() :: Yog.node_id()

system()

@type system() :: Choreo.t()

Functions

cluster(system, name, opts \\ [])

@spec cluster(system(), cluster_id(), keyword()) :: system()

Adds a visual cluster/grouping boundary to a composed system.

iex> system = Choreo.new() |> Choreo.Lab.Compose.cluster(:auth, label: "Auth")
iex> Map.has_key?(system.clusters, "cluster_auth")
true

connect(system, from, to, label_or_opts \\ [])

@spec connect(system(), node_id(), node_id(), String.t() | keyword()) :: system()

Connects two nodes with a normal visible relationship.

The third argument may be a label string, a keyword list, or omitted.

iex> system =
...>   Choreo.new()
...>   |> Choreo.add_service(:api)
...>   |> Choreo.add_database(:db)
...>   |> Choreo.Lab.Compose.connect(:api, :db, "reads")
iex> [{:api, :db, _weight, meta}] = Choreo.edges_with_meta(system)
iex> meta.label
"reads"

embed(system, child, opts)

@spec embed(system(), struct(), keyword()) :: system()

Embeds a child diagram into a cluster of the parent system.

Required options:

:into — target cluster name/id

Prefix options:

:as — friendly alias converted to a prefix with a trailing underscore
:prefix — explicit prefix passed through to Choreo.embed/4

:prefix wins over :as when both are supplied.

iex> child = Choreo.new() |> Choreo.add_service(:api)
iex> system =
...>   Choreo.new()
...>   |> Choreo.Lab.Compose.cluster(:system)
...>   |> Choreo.Lab.Compose.embed(child, into: :system, as: :child)
iex> Map.has_key?(Choreo.nodes(system), :child_api)
true

taxonomy()

@spec taxonomy() :: %{structure: [atom()], links: [atom()], options: [atom()]}

Returns the composition helper vocabulary for Livebook discovery.

iex> taxonomy = Choreo.Lab.Compose.taxonomy()
iex> :embed in taxonomy.structure
true
iex> :trace in taxonomy.links
true
iex> :as in taxonomy.options
true

trace(system, from, to, type_or_opts \\ [])

@spec trace(system(), node_id(), node_id(), atom() | keyword()) :: system()

Adds a semantic trace relationship between two nodes.

The fourth argument may be a trace type atom, a keyword list, or omitted.

iex> system =
...>   Choreo.new()
...>   |> Choreo.add_service(:api)
...>   |> Choreo.add_service(:auth)
...>   |> Choreo.Lab.Compose.trace(:api, :auth, :executes)
iex> [{:api, :auth, _weight, meta}] = Choreo.edges_with_meta(system)
iex> {meta.edge_type, meta.type, meta.label}
{:trace, :executes, "executes"}

verbs()

@spec verbs() :: %{structure: [atom()], links: [atom()], options: [atom()]}

Compatibility alias for taxonomy/0.