defmodule GraphQL.Node do
@moduledoc """
Functions to create all different types of nodes of a GraphQL operation.
Usually, this module should not be used directly, since it is easier to use
the function from `GraphQL.QueryBuilder`.
"""
@enforce_keys [:node_type]
defstruct node_type: nil,
name: nil,
alias: nil,
type: nil,
arguments: nil,
nodes: nil,
directives: nil
@typedoc """
The GraphQL query element that this node represents.
The four node types are:
- field: a single field of a GraphQL schema, may have arguments and other nodes
- fragment_ref: a reference to a fragment, used inside fields to import fragment fields
- fragment: a fragment definition, with name, type and fields
- inline_fragment: much like a fragment, but being inline, it does not need a name
"""
@type node_type :: :field | :fragment_ref | :fragment | :inline_fragment
@typedoc """
A GraphQL identifier that is not a GraphQL keyword (like mutation, query and fragment)
Used to identify fields, aliases and fragments.
"""
@type name :: String.t() | atom()
@typedoc """
A two-element tuple where the first position is the name of the field and the
second element is the alias of the field.
"""
@type name_and_alias :: {name(), name()}
@typedoc """
A struct representing a GraphQL operation node.
A %Node{} struct can be represent a field, a fragment, an inline fragment or a
fragment reference, identified by the `:node_type` field.
The `name` represents how this node is identified within the GraphQL operation.
The `alias` is only used when the `:node_type` is `:field`, and as the name
suggests, represents the alias of the field's name.
The `arguments` is a map with all the arguments used by a node, and it's only
valid when thew `:node_type` is `:field`.
The `type` is only used when `:node_type` is `:fragment` or `:inline_fragment`,
and represents the GraphQL type of the fragment.
The `nodes` is a list of child nodes, that can used to query for complex
objects.
The `directives` field is an enum with all the graphQL directives to be
applied on a node node.
"""
@type t :: %__MODULE__{
node_type: node_type(),
name: name(),
alias: name(),
type: String.t(),
arguments: map() | Keyword.t(),
nodes: [t()],
directives: map() | Keyword.t()
}
@doc """
Creates a simple field, with no arguments or sub nodes.
The `name` parameter can be an atom or string, or a two-element tuple with
atoms or strings, where the first element is the actual name of the field and
the second element is the alias of the field.
## GraphQL example
A query with a simple field inside another field:
```
query {
user {
id <---- Simple field
}
}
```
A query with a simple field with an alias:
```
query {
user {
theId: id <---- Simple field with alias
}
}
```
## Examples
iex> field(:my_field)
%GraphQL.Node{node_type: :field, name: :my_field}
iex> field({:my_field, "field_alias"})
%GraphQL.Node{node_type: :field, name: :my_field, alias: "field_alias"}
"""
@spec field(name() | name_and_alias()) :: t()
def field(name_spec)
def field({name, an_alias}) do
%__MODULE__{
node_type: :field,
name: name,
alias: an_alias
}
end
def field(name) do
%__MODULE__{
node_type: :field,
name: name
}
end
@doc """
Creates a field with arguments and sub nodes.
The `name` parameter can be an atom or string, or a two-element tuple with
atoms or strings, where the first element is the actual name of the field and
the second element is the alias of the field.
The `arguments` parameter is a map.
The `nodes` argument is a list of `%GraphQL.Node{}` structs.
## GraphQL Example
A query with a field that has arguments, an alias and subfields
```
query {
someObject: object(slug: "the-object") { <----- Field with an alias and arguments
field <----- Sub field
anotherField <----- Sub field
}
}
```
## Examples
iex> field(:my_field, %{id: "id"}, [ field(:subfield) ] )
%GraphQL.Node{node_type: :field, name: :my_field, arguments: %{id: "id"}, nodes: [%GraphQL.Node{node_type: :field, name: :subfield}]}
iex> field({:my_field, "field_alias"}, %{id: "id"}, [ field(:subfield) ] )
%GraphQL.Node{node_type: :field, name: :my_field, alias: "field_alias", arguments: %{id: "id"}, nodes: [%GraphQL.Node{node_type: :field, name: :subfield}]}
"""
@spec field(name() | name_and_alias(), map(), [t()], [any()]) :: t()
def field(name_spec, arguments, nodes, directives \\ nil)
def field({name, an_alias}, arguments, nodes, directives) do
%__MODULE__{
node_type: :field,
name: name,
alias: an_alias,
arguments: arguments,
nodes: nodes,
directives: directives
}
end
def field(name, arguments, nodes, directives) do
%__MODULE__{
node_type: :field,
name: name,
arguments: arguments,
nodes: nodes,
directives: directives
}
end
@doc """
Creates a reference to a fragment.
A fragment reference is used inside a field to import the fields of a fragment.
## GraphQL Example
```
query {
object {
...fieldsFromFragment <----- Fragment Reference
}
}
```
## Examples
iex> fragment("myFields")
%GraphQL.Node{node_type: :fragment_ref, name: "myFields"}
"""
@spec fragment(name()) :: t()
def fragment(name) do
%__MODULE__{
node_type: :fragment_ref,
name: name
}
end
@doc """
Creates a fragment.
A fragment is used to share fields between other fields
## GraphQL Example
```
query {
object {
...fieldsFromFragment
}
}
fragment fieldsFromFragment on Type { <------ Fragment
field1
field2
}
```
## Examples
iex> fragment("myFields", "SomeType", [field(:field)])
%GraphQL.Node{node_type: :fragment, name: "myFields", type: "SomeType", nodes: [%GraphQL.Node{node_type: :field, name: :field}]}
"""
@spec fragment(name(), name(), [t()]) :: t()
def fragment(name, type, fields) do
%__MODULE__{
node_type: :fragment,
name: name,
type: type,
nodes: fields
}
end
@doc """
Creates an inline fragment.
An inline fragment is used to conditionally add fields on another field depending
on its type
## GraphQL Example
```
query {
object {
... on Type { <------ Inline Fragment
field1
field2
}
}
}
```
## Examples
iex> inline_fragment("SomeType", [field(:field)])
%GraphQL.Node{node_type: :inline_fragment, type: "SomeType", nodes: [%GraphQL.Node{node_type: :field, name: :field}]}
"""
@spec inline_fragment(name(), [t()]) :: t()
def inline_fragment(type, fields) do
%__MODULE__{
node_type: :inline_fragment,
type: type,
nodes: fields
}
end
end
