absinthe.ex (3944B)
1 defmodule Absinthe do 2 @moduledoc """ 3 Documentation for the Absinthe package, a toolkit for building GraphQL 4 APIs with Elixir. 5 6 For usage information, see [the documentation](http://hexdocs.pm/absinthe), which 7 includes guides, API information for important modules, and links to useful resources. 8 """ 9 10 defmodule SerializationError do 11 @moduledoc """ 12 An error during serialization. 13 """ 14 defexception message: "serialization failed" 15 end 16 17 defmodule ExecutionError do 18 @moduledoc """ 19 An error during execution. 20 """ 21 defexception message: "execution failed" 22 end 23 24 defmodule AnalysisError do 25 @moduledoc """ 26 An error during analysis. 27 """ 28 defexception message: "analysis failed" 29 end 30 31 @type result_selection_t :: %{ 32 String.t() => 33 nil 34 | integer 35 | float 36 | boolean 37 | binary 38 | atom 39 | result_selection_t 40 | [result_selection_t] 41 } 42 43 @type result_error_t :: 44 %{message: String.t()} 45 | %{message: String.t(), locations: [%{line: pos_integer, column: integer}]} 46 47 @type result_t :: 48 %{data: nil | result_selection_t} 49 | %{data: nil | result_selection_t, errors: [result_error_t]} 50 | %{errors: [result_error_t]} 51 52 @doc """ 53 Evaluates a query document against a schema, with options. 54 55 ## Options 56 57 * `:adapter` - The name of the adapter to use. See the `Absinthe.Adapter` 58 behaviour and the `Absinthe.Adapter.Passthrough` and 59 `Absinthe.Adapter.LanguageConventions` modules that implement it. 60 (`Absinthe.Adapter.LanguageConventions` is the default value for this option.) 61 * `:operation_name` - If more than one operation is present in the provided 62 query document, this must be provided to select which operation to execute. 63 * `:variables` - A map of provided variable values to be used when filling in 64 arguments in the provided query document. 65 * `:context` -> A map of the execution context. 66 * `:root_value` -> A root value to use as the source for toplevel fields. 67 * `:analyze_complexity` -> Whether to analyze the complexity before 68 executing an operation. 69 * `:max_complexity` -> An integer (or `:infinity`) for the maximum allowed 70 complexity for the operation being executed. 71 72 ## Examples 73 74 ``` 75 \""" 76 query GetItemById($id: ID) { 77 item(id: $id) { 78 name 79 } 80 } 81 \""" 82 |> Absinthe.run(App.Schema, variables: %{"id" => params[:item_id]}) 83 ``` 84 85 See the `Absinthe` module documentation for more examples. 86 87 """ 88 @type run_opts :: [ 89 context: %{}, 90 adapter: Absinthe.Adapter.t(), 91 root_value: term, 92 operation_name: String.t(), 93 analyze_complexity: boolean, 94 variables: %{optional(String.t()) => any()}, 95 max_complexity: non_neg_integer | :infinity 96 ] 97 98 @type run_result :: {:ok, result_t} | {:error, String.t()} 99 100 @spec run( 101 binary | Absinthe.Language.Source.t() | Absinthe.Language.Document.t(), 102 Absinthe.Schema.t(), 103 run_opts 104 ) :: run_result 105 def run(document, schema, options \\ []) do 106 pipeline = 107 schema 108 |> Absinthe.Pipeline.for_document(options) 109 110 case Absinthe.Pipeline.run(document, pipeline) do 111 {:ok, %{result: result}, _phases} -> 112 {:ok, result} 113 114 {:error, msg, _phases} -> 115 {:error, msg} 116 end 117 end 118 119 @doc """ 120 Evaluates a query document against a schema, without options. 121 122 ## Options 123 124 See `run/3` for the available options. 125 """ 126 @spec run!( 127 binary | Absinthe.Language.Source.t() | Absinthe.Language.Document.t(), 128 Absinthe.Schema.t(), 129 Keyword.t() 130 ) :: result_t | no_return 131 def run!(input, schema, options \\ []) do 132 case run(input, schema, options) do 133 {:ok, result} -> result 134 {:error, err} -> raise ExecutionError, message: err 135 end 136 end 137 end