### Quick Start GraphQL Query

Source: https://hexdocs.pm/gleamql/index.html

An example of building and sending a GraphQL query using gleamql.

```gleam
import gleamql
import gleamql/field
import gleamql/operation
import gleam/json
import gleam/hackney

pub type Country {
  Country(name: String, code: String)
}

pub fn main() {
  // Build the operation
  let country_op =
    operation.query("CountryQuery")
    |> operation.variable("code", "ID!")
    |> operation.field(
      field.object("country", fn() {
        use name <- field.field(field.string("name"))
        use code <- field.field(field.string("code"))
        field.build(Country(name:, code:))
      })
      |> field.arg("code", "code"),
    )

  // Send the request
  let assert Ok(Some(Country(name: "United Kingdom", code: "GB"))) =
    gleamql.new(country_op)
    |> gleamql.host("countries.trevorblades.com")
    |> gleamql.path("/graphql")
    |> gleamql.json_content_type()
    |> gleamql.send(hackney.send, [#("code", json.string("GB"))])
}
```

```graphql
query CountryQuery($code: ID!) {
  country(code: $code) {
    name
    code
  }
}
```

--------------------------------

### Run Example Projects

Source: https://hexdocs.pm/gleamql/index.html

Navigate to an example directory and run it using the Gleam CLI.

```bash
cd examples/01-basics/01-simple-query
gleam run
```

--------------------------------

### to_definition example

Source: https://hexdocs.pm/gleamql/gleamql/fragment.html

Example of calling fragment.to_definition and the returned string.

```gleam
fragment.to_definition(user_fields)
// Returns: "fragment UserFields on User { id name email }"
```

--------------------------------

### with_directives example

Source: https://hexdocs.pm/gleamql/gleamql/fragment.html

Example of adding multiple directives to a fragment spread.

```gleam
import gleamql/directive

fragment.with_directives(user_fields, [
  directive.include("showUser"),
  directive.skip("hideUser"),
])
```

--------------------------------

### on function example with generated output

Source: https://hexdocs.pm/gleamql/gleamql/fragment.html

Example of defining a fragment with fragment.on and the resulting GraphQL fragment definition.

```gleam
pub type User {
  User(id: String, name: String, email: String)
}

let user_fields = 
  fragment.on("User", "UserFields", fn() {
    use id <- field.field(field.id("id"))
    use name <- field.field(field.string("name"))
    use email <- field.field(field.string("email"))
    field.build(User(id:, name:, email:))
  })
```

```graphql
fragment UserFields on User {
  id
  name
  email
}
```

--------------------------------

### float() example

Source: https://hexdocs.pm/gleamql/gleamql/field.html

Example usage of `float()` to create a Float field.

```gleam
let price_field = field.float("price")
// Generates: price
// Decodes: Float
```

--------------------------------

### id() example

Source: https://hexdocs.pm/gleamql/gleamql/field.html

Example usage of `id()` to create an ID field.

```gleam
let id_field = field.id("id")
// Generates: id
// Decodes: String
```

--------------------------------

### with_directives example: Add multiple directives

Source: https://hexdocs.pm/gleamql/gleamql/field.html

Example of adding multiple directives at once using `with_directives`.

```gleam
import gleamql/directive

field.string("profile")
|> field.with_directives([
  directive.include("showProfile"),
  directive.deprecated(Some("Use profileV2")),
])
```

--------------------------------

### spread function example with generated output

Source: https://hexdocs.pm/gleamql/gleamql/fragment.html

Example of using fragment.spread in an object builder and the resulting GraphQL selection.

```gleam
field.object("user", fn() {
  use user_data <- field.field(fragment.spread(user_fields))
  field.build(user_data)
})
```

```graphql
user {
  ...UserFields
}
```

--------------------------------

### field() example

Source: https://hexdocs.pm/gleamql/gleamql/field.html

Example usage of `field()` to build an object with multiple fields.

```gleam
field.object("person", fn() {
  use name <- field.field(field.string("name"))
  use age <- field.field(field.int("age"))
  field.build(Person(name:, age:))
})
```

--------------------------------

### field.build function and example

Source: https://hexdocs.pm/gleamql/gleamql/field.html

Completes the object with a constructor. The example shows usage within field.object and the comment about completing with a constructor.

```gleam
pub fn build(value: a) -> ObjectBuilder(a)
```

```gleam
field.object("country", fn() {
  use name <- field.field(field.string("name"))
  field.build(Country(name:))  // <- Complete with constructor
})
```

--------------------------------

### Install gleamql

Source: https://hexdocs.pm/gleamql/index.html

Use the Gleam CLI to add the package to your project.

```bash
gleam add gleamql
```

--------------------------------

### new usage example

Source: https://hexdocs.pm/gleamql/gleamql/directive.html

Shows how to create a custom directive with no arguments.

```Gleam
let custom = directive.new("myDirective")
// Generates: @myDirective

```

--------------------------------

### field_as() example

Source: https://hexdocs.pm/gleamql/gleamql/field.html

Example usage of `field_as()` to add aliased fields with arguments.

```gleam
field.object("user", fn() {
  use small_pic <- field.field_as("smallPic", 
    field.string("profilePic") 
    |> field.arg_int("size", 64))
  use large_pic <- field.field_as("largePic",
    field.string("profilePic")
    |> field.arg_int("size", 1024))
  field.build(#(small_pic, large_pic))
})
// Generates: user { smallPic: profilePic(size: 64) largePic: profilePic(size: 1024) }
```

--------------------------------

### inline() example - grouping fields with directives

Source: https://hexdocs.pm/gleamql/gleamql/field.html

Example of grouping fields with directives using `inline()`.

```gleam
field.object("user", fn() {
  use name <- field.field(field.string("name"))
  use private_data <- field.field(
    field.inline(fn() {
      use email <- field.field(field.string("email"))
      use phone <- field.field(field.string("phone"))
      field.build(#(email, phone))
    })
    |> field.with_directive(directive.include("showPrivate"))
  )
  field.build(User(name:, private: private_data))
})
// Generates: user { name ... @include(if: $showPrivate) { email phone } }
```

--------------------------------

### inline_on() example - querying a union type

Source: https://hexdocs.pm/gleamql/gleamql/field.html

Example of querying a union type using `inline_on()`.

```gleam
// GraphQL schema:
// union SearchResult = User | Post | Comment

field.object("search", fn() {
  use user_result <- field.field(
    field.inline_on("User", fn() {
      use name <- field.field(field.string("name"))
      use email <- field.field(field.string("email"))
      field.build(UserResult(name:, email:))
    })
  )
  use post_result <- field.field(
    field.inline_on("Post", fn() {
      use title <- field.field(field.string("title"))
      field.build(PostResult(title:))
    })
  )
  field.build(SearchResults(user: user_result, post: post_result))
})
// Generates: search { ... on User { name email } ... on Post { title } }
```

--------------------------------

### with_directive example

Source: https://hexdocs.pm/gleamql/gleamql/fragment.html

Example of adding a directive to a fragment spread and using it in a field, with the generated GraphQL.

```gleam
import gleamql/directive

let user_fields = fragment.on("User", "UserFields", fn() {
  use id <- field.field(field.id("id"))
  use name <- field.field(field.string("name"))
  field.build(User(id:, name:))
})

// Add directive to the fragment spread
let conditional_user = fragment.with_directive(
  user_fields,
  directive.include("includeUser")
)

// Use in a field
field.object("data", fn() {
  use user <- field.field(fragment.spread(conditional_user))
  field.build(user)
})
// Generates: data { ...UserFields @include(if: $includeUser) }
```

--------------------------------

### to_string usage example

Source: https://hexdocs.pm/gleamql/gleamql/directive.html

Shows how to convert directives to their string representation.

```Gleam
directive.to_string(directive.skip("var"))
// Returns: "@skip(if: $var)"

directive.to_string(directive.include_if(true))
// Returns: "@include(if: true)"

```

--------------------------------

### with_arg usage example

Source: https://hexdocs.pm/gleamql/gleamql/directive.html

Shows how to add inline and variable arguments to a custom directive.

```Gleam
directive.new("customDirective")
|> directive.with_arg("limit", directive.InlineInt(10))
|> directive.with_arg("filter", directive.Variable("filterVar"))
// Generates: @customDirective(limit: 10, filter: $filterVar)

```

--------------------------------

### Building GraphQL Fields

Source: https://hexdocs.pm/gleamql/index.html

Examples of defining scalars, optional fields, lists, and nested objects.

```gleam
// Scalars
field.string("name")
field.int("age")
field.bool("active")

// Optional fields and lists
field.optional(field.string("nickname"))
field.list(field.string("tags"))

// Nested objects
field.object("user", fn() {
  use name <- field.field(field.string("name"))
  use age <- field.field(field.int("age"))
  field.build(User(name:, age:))
})
```

--------------------------------

### Defining Mutations

Source: https://hexdocs.pm/gleamql/index.html

Example of building a mutation operation.

```gleam
operation.mutation("CreatePost")
|> operation.variable("input", "CreatePostInput!")
|> operation.field(
  field.object("createPost", fn() {
    use id <- field.field(field.id("id"))
    field.build(Post(id:))
  })
  |> field.arg("input", "input")
)
```

--------------------------------

### field.arg_list function and example

Source: https://hexdocs.pm/gleamql/gleamql/field.html

Adds an inline list argument to a field. The example shows usage and the generated GraphQL.

```gleam
pub fn arg_list(
  fld: Field(a),
  arg_name: String,
  items: List(Argument),
) -> Field(a)
```

```gleam
field.object("users", users_builder)
|> field.arg_list("ids", [InlineString("1"), InlineString("2")])
// Generates: users(ids: ["1", "2"]) { ... }
```

--------------------------------

### include usage example

Source: https://hexdocs.pm/gleamql/gleamql/directive.html

Shows how to add an @include directive to a field and define the corresponding variable in the operation.

```Gleam
field.string("email")
|> field.with_directive(directive.include("shouldIncludeEmail"))
// Generates: email @include(if: $shouldIncludeEmail)

```

```Gleam
operation.query("GetUser")
|> operation.variable("shouldIncludeEmail", "Boolean!")
|> operation.field(user_field())

```

--------------------------------

### field.bool function and example

Source: https://hexdocs.pm/gleamql/gleamql/field.html

Creates a Bool field. The example shows usage and the generated GraphQL and decoded type.

```gleam
pub fn bool(name: String) -> Field(Bool)
```

```gleam
let active_field = field.bool("isActive")
// Generates: isActive
// Decodes: Bool
```

--------------------------------

### with_args example: Add arguments to a field

Source: https://hexdocs.pm/gleamql/gleamql/field.html

Example usage of `with_args` to add arguments to a field. The comment shows the generated GraphQL query.

```gleam
field.object("posts", posts_builder)
|> field.with_args([
  #("first", Variable("limit")),
  #("after", InlineString("cursor123")),
])
// Generates: posts(first: $limit, after: "cursor123") { ... }
```

--------------------------------

### Example: field.list usage

Source: https://hexdocs.pm/gleamql/gleamql/field.html

Creates a list field for 'tags'. The generated selection is 'tags' and the decoder returns a List(String).

```gleam
let tags_field = field.list(field.string("tags"))
// Generates: tags
// Decodes: List(String)
```

--------------------------------

### Example: field.optional usage

Source: https://hexdocs.pm/gleamql/gleamql/field.html

Creates an optional field for 'nickname'. The generated selection is 'nickname' and the decoder returns Option(String).

```gleam
let nickname_field = field.optional(field.string("nickname"))
// Generates: nickname
// Decodes: Option(String)
```

--------------------------------

### field.arg_string function and example

Source: https://hexdocs.pm/gleamql/gleamql/field.html

Adds an inline string argument to a field. The example shows usage and the generated GraphQL.

```gleam
pub fn arg_string(
  fld: Field(a),
  arg_name: String,
  value: String,
) -> Field(a)
```

```gleam
field.object("country", country_builder)
|> field.arg_string("code", "GB")
// Generates: country(code: "GB") { ... }
```

--------------------------------

### deprecated usage example

Source: https://hexdocs.pm/gleamql/gleamql/directive.html

Shows how to create a @deprecated directive with and without a reason.

```Gleam
directive.deprecated(Some("Use newField instead"))
// Generates: @deprecated(reason: "Use newField instead")

directive.deprecated(None)
// Generates: @deprecated

```

--------------------------------

### Example: field.string usage

Source: https://hexdocs.pm/gleamql/gleamql/field.html

Creates a String field named 'name'. The generated selection is 'name' and the decoder returns a String.

```gleam
let name_field = field.string("name")
// Generates: name
// Decodes: String
```

--------------------------------

### field.arg function and example

Source: https://hexdocs.pm/gleamql/gleamql/field.html

Adds a single variable argument to a field. The example shows usage with field.object and the generated GraphQL.

```gleam
pub fn arg(
  fld: Field(a),
  arg_name: String,
  var_name: String,
) -> Field(a)
```

```gleam
field.object("country", country_builder)
|> field.arg("code", "code")
// Generates: country(code: $code) { ... }
```

--------------------------------

### Basic usage of directives with fields

Source: https://hexdocs.pm/gleamql/gleamql/directive.html

Shows how to apply built-in directives (@skip, @include, @deprecated) to fields using the gleamql/directive and gleamql/field modules. The example demonstrates conditional inclusion/exclusion and deprecation with a reason.

```gleam
import gleamql/directive
import gleamql/field

// Use @skip directive to conditionally exclude a field
let name_field = 
  field.string("name")
  |> field.with_directive(directive.skip("skipName"))

// Use @include directive to conditionally include a field
let email_field =
  field.string("email")
  |> field.with_directive(directive.include("includeEmail"))

// Multiple directives on one field
let profile_field =
  field.string("profile")
  |> field.with_directive(directive.include("showProfile"))
  |> field.with_directive(directive.deprecated(Some("Use profileV2 instead")))

```

--------------------------------

### include_if usage example

Source: https://hexdocs.pm/gleamql/gleamql/directive.html

Shows how to add an @include directive with an inline boolean condition.

```Gleam
field.string("email")
|> field.with_directive(directive.include_if(True))
// Generates: email @include(if: true)

```

--------------------------------

### with_directive example: Add a skip directive

Source: https://hexdocs.pm/gleamql/gleamql/field.html

Example of adding a single directive using `with_directive`. The comment shows the generated GraphQL query.

```gleam
import gleamql/directive

field.string("name")
|> field.with_directive(directive.skip("shouldSkipName"))
// Generates: name @skip(if: $shouldSkipName)
```

--------------------------------

### skip usage example

Source: https://hexdocs.pm/gleamql/gleamql/directive.html

Shows how to add a @skip directive to a field and define the corresponding variable in the operation.

```Gleam
field.string("name")
|> field.with_directive(directive.skip("shouldSkipName"))
// Generates: name @skip(if: $shouldSkipName)

```

```Gleam
operation.query("GetUser")
|> operation.variable("shouldSkipName", "Boolean!")
|> operation.field(user_field())

```

--------------------------------

### with_args: Add multiple arguments to a field

Source: https://hexdocs.pm/gleamql/gleamql/field.html

Adds multiple arguments to a field. The example shows passing a variable and an inline string, generating `posts(first: $limit, after: "cursor123") { ... }`.

```gleam
pub fn with_args(
  fld: Field(a),
  args: List(#(String, Argument)),
) -> Field(a)
```

--------------------------------

### Example: phantom_root usage

Source: https://hexdocs.pm/gleamql/gleamql/field.html

Creates a phantom root field for multiple root selections. The generated GraphQL outputs the child fields directly at the operation level without a wrapper.

```gleam
// Internal usage (via operation.root):
let phantom = field.phantom_root(fn() {
  use user <- field.field(user_field())
  use posts <- field.field(posts_field())
  field.build(#(user, posts))
})
```

--------------------------------

### field.arg_int function and example

Source: https://hexdocs.pm/gleamql/gleamql/field.html

Adds an inline int argument to a field. The example shows usage and the generated GraphQL.

```gleam
pub fn arg_int(
  fld: Field(a),
  arg_name: String,
  value: Int,
) -> Field(a)
```

```gleam
field.object("posts", posts_builder)
|> field.arg_int("first", 10)
// Generates: posts(first: 10) { ... }
```

--------------------------------

### specified_by usage example

Source: https://hexdocs.pm/gleamql/gleamql/directive.html

Shows how to create a @specifiedBy directive with a URL.

```Gleam
directive.specified_by("https://tools.ietf.org/html/rfc3339")
// Generates: @specifiedBy(url: "https://tools.ietf.org/html/rfc3339")

```

--------------------------------

### field.arg_object function and example

Source: https://hexdocs.pm/gleamql/gleamql/field.html

Adds an inline object argument to a field, commonly used for mutation input objects. The example shows usage and the generated GraphQL.

```gleam
pub fn arg_object(
  fld: Field(a),
  arg_name: String,
  fields: List(#(String, Argument)),
) -> Field(a)
```

```gleam
field.object("createPost", create_post_builder)
|> field.arg_object("input", [
  #("title", InlineString("My Post")),
  #("body", InlineString("Content here")),
])
// Generates: createPost(input: { title: "My Post", body: "Content here" }) { ... }
```

--------------------------------

### skip_if usage example

Source: https://hexdocs.pm/gleamql/gleamql/directive.html

Shows how to add a @skip directive with an inline boolean condition.

```Gleam
field.string("name")
|> field.with_directive(directive.skip_if(True))
// Generates: name @skip(if: true)

```

--------------------------------

### Example: is_phantom_root usage

Source: https://hexdocs.pm/gleamql/gleamql/field.html

Checks if a field is a phantom root. A phantom root returns True, while a regular object field returns False.

```gleam
let phantom = field.phantom_root(builder)
field.is_phantom_root(phantom)  // -> True

let regular = field.object("user", builder)
field.is_phantom_root(regular)  // -> False
```

--------------------------------

### fragment.decoder

Source: https://hexdocs.pm/gleamql/gleamql/fragment.html

Gets the decoder for the fragment.

```APIDOC
## fragment.decoder

### Description
Gets the decoder for the fragment.

### Function Signature
gleam
pub fn decoder(fragment: Fragment(a)) -> decode.Decoder(a)


### Parameters
- **fragment** (Fragment(a)) - Required - The fragment to get the decoder for.

### Returns
- **decode.Decoder(a)** - The decoder for the fragment.
```

--------------------------------

### field.arg_float function and example

Source: https://hexdocs.pm/gleamql/gleamql/field.html

Adds an inline float argument to a field. The example shows usage and the generated GraphQL.

```gleam
pub fn arg_float(
  fld: Field(a),
  arg_name: String,
  value: Float,
) -> Field(a)
```

```gleam
field.object("products", products_builder)
|> field.arg_float("minPrice", 9.99)
// Generates: products(minPrice: 9.99) { ... }
```

--------------------------------

### field.arg_bool function and example

Source: https://hexdocs.pm/gleamql/gleamql/field.html

Adds an inline bool argument to a field. The example shows usage and the generated GraphQL.

```gleam
pub fn arg_bool(
  fld: Field(a),
  arg_name: String,
  value: Bool,
) -> Field(a)
```

```gleam
field.object("posts", posts_builder)
|> field.arg_bool("published", True)
// Generates: posts(published: true) { ... }
```

--------------------------------

### fragment.name

Source: https://hexdocs.pm/gleamql/gleamql/fragment.html

Gets the fragment name.

```APIDOC
## fragment.name

### Description
Gets the fragment name.

### Function Signature
gleam
pub fn name(fragment: Fragment(a)) -> String


### Parameters
- **fragment** (Fragment(a)) - Required - The fragment to get the name from.

### Returns
- **String** - The fragment name.
```

--------------------------------

### operation.decoder

Source: https://hexdocs.pm/gleamql/gleamql/operation.html

Gets the decoder from an operation.

```APIDOC
## operation.decoder

### Description
Gets the decoder from an operation. This decoder will automatically unwrap the "data" field from the GraphQL response.

### Function Signature
`pub fn decoder(operation: Operation(a)) -> decode.Decoder(a)`

### Parameters
- `operation` (Operation(a)) - Required - The operation.

### Returns
- `decode.Decoder(a)` - The decoder for the operation's data.

### Example
```gleam
let op = operation.query("GetCountry") |> operation.field(country_field())
let decoder = operation.decoder(op)
```
```

--------------------------------

### Example: field.int usage

Source: https://hexdocs.pm/gleamql/gleamql/field.html

Creates an Int field named 'age'. The generated GraphQL selection is 'age' and the decoder returns an Int.

```gleam
let age_field = field.int("age")
// Generates: age
// Decodes: Int
```

--------------------------------

### Example: field.object with Country type

Source: https://hexdocs.pm/gleamql/gleamql/field.html

Builds an object field for a Country type with nested name and code fields. The generated selection is 'country { name code }' and decodes to a Country.

```gleam
pub type Country {
  Country(name: String, code: String)
}

fn country_field() {
  field.object("country", fn() {
    use name <- field.field(field.string("name"))
    use code <- field.field(field.string("code"))
    field.build(Country(name:, code:))
  })
}
// Generates: country { name code }
// Decodes: Country
```

--------------------------------

### with_directive chaining example: Multiple directives

Source: https://hexdocs.pm/gleamql/gleamql/field.html

Shows chaining multiple directives on a field. The comment shows the generated GraphQL query with both directives.

```gleam
field.string("email")
|> field.with_directive(directive.include("showEmail"))
|> field.with_directive(directive.deprecated(Some("Use emailAddress instead")))
// Generates: email @include(if: $showEmail) @deprecated(reason: "Use emailAddress instead")
```

--------------------------------

### Basic Usage: Define and use a fragment

Source: https://hexdocs.pm/gleamql/gleamql/fragment.html

Shows how to define a reusable fragment with fragment.on and use it in a query with operation.fragment and fragment.spread.

```gleam
import gleamql/fragment
import gleamql/field

// Define a reusable fragment
let user_fields = 
  fragment.on("User", "UserFields", fn() {
    use id <- field.field(field.id("id"))
    use name <- field.field(field.string("name"))
    use email <- field.field(field.string("email"))
    field.build(User(id:, name:, email:))
  })

// Use in a query
operation.query("GetUsers")
|> operation.fragment(user_fields)
|> operation.field(
  field.object("users", fn() {
    field.field(fragment.spread(user_fields))
  })
)
```

--------------------------------

### Querying an interface type with field.object and inline_on

Source: https://hexdocs.pm/gleamql/gleamql/field.html

Builds an object field with an inline fragment on an interface type. The example shows querying a 'node' field with a common 'id' and inline fields for 'User'.

```gleam
field.object("node", fn() {
  use common_id <- field.field(field.id("id"))
  use user_fields <- field.field(
    field.inline_on("User", fn() {
      use name <- field.field(field.string("name"))
      field.build(name)
    })
  )
  field.build(#(common_id, user_fields))
})
// Generates: node { id ... on User { name } }
```

--------------------------------

### fragment.to_definition

Source: https://hexdocs.pm/gleamql/gleamql/fragment.html

Gets the fragment definition as a GraphQL string. This generates the fragment definition that will be included in the operation's query string.

```APIDOC
## fragment.to_definition

### Description
Gets the fragment definition as a GraphQL string. This generates the fragment definition that will be included in the operation's query string.

### Function Signature
gleam
pub fn to_definition(fragment: Fragment(a)) -> String


### Parameters
- **fragment** (Fragment(a)) - Required - The fragment to get the definition for.

### Returns
- **String** - The fragment definition as a GraphQL string.

### Example
gleam
fragment.to_definition(user_fields)
// Returns: "fragment UserFields on User { id name email }"

```

--------------------------------

### Example: nested object field

Source: https://hexdocs.pm/gleamql/gleamql/field.html

Builds a nested object field using a previously defined country_field. The generated selection is 'data { country { name code } }'.

```gleam
pub type Data {
  Data(country: Country)
}

fn data_field() {
  field.object("data", fn() {
    use country <- field.field(country_field())
    field.build(Data(country:))
  })
}
// Generates: data { country { name code } }
```

--------------------------------

### Build basic field selections

Source: https://hexdocs.pm/gleamql/gleamql/field.html

Shows how to build simple scalar, list, and optional field selections using the field module.

```gleam
import gleamql/field

// Simple scalar field
let name_field = field.string("name")

// List of strings
let tags_field = field.list(field.string("tags"))

// Optional field
let nickname_field = field.optional(field.string("nickname"))
```

--------------------------------

### Creating custom directives with new() and with_arg()

Source: https://hexdocs.pm/gleamql/gleamql/directive.html

Demonstrates how to create a custom directive using directive.new() and add arguments with directive.with_arg(), using InlineString and InlineInt for argument values.

```gleam
directive.new("customDirective")
|> directive.with_arg("arg1", directive.InlineString("value"))
|> directive.with_arg("arg2", directive.InlineInt(42))

```

--------------------------------

### gleamql.new

Source: https://hexdocs.pm/gleamql/gleamql.html

Constructs a GleamQL Request with an operation.

```APIDOC
## gleamql.new

### Description
Constructs a GleamQL Request with an operation.

### Function Signature
```
pub fn new(op: operation.Operation(t)) -> Request(t)
```

### Parameters
- **op** (operation.Operation(t)) - The GraphQL operation to include in the request.

### Returns
- **Request(t)** - A new request.

### Example
```
gleamql.new(country_operation)
|> gleamql.host("api.example.com")
|> gleamql.path("/graphql")
|> gleamql.json_content_type()
|> gleamql.send(hackney.send, [#("code", json.string("GB"))])
```
```

--------------------------------

### field.inline

Source: https://hexdocs.pm/gleamql/gleamql/field.html

Creates an inline fragment builder.

```APIDOC
## field.inline

### Description
Creates an inline fragment builder that can be used to group fields.

### Usage
```gleam
field.inline(builder)
```

### Parameters
- **builder** (FieldBuilder) - The field builder to wrap in an inline fragment.

### Returns
An inline fragment field builder.
```

--------------------------------

### Build Operation

Source: https://hexdocs.pm/gleamql/gleamql/operation.html

Alias for building the operation.

```gleam
pub fn build(operation: Operation(a)) -> Operation(a)
```

--------------------------------

### fragment.type_condition

Source: https://hexdocs.pm/gleamql/gleamql/fragment.html

Gets the fragment's type condition.

```APIDOC
## fragment.type_condition

### Description
Gets the fragment's type condition.

### Function Signature
gleam
pub fn type_condition(fragment: Fragment(a)) -> String


### Parameters
- **fragment** (Fragment(a)) - Required - The fragment to get the type condition from.

### Returns
- **String** - The fragment's type condition.
```

--------------------------------

### field.name(field: Field(a)) -> String

Source: https://hexdocs.pm/gleamql/gleamql/field.html

Gets the field name.

```APIDOC
## field.name

### Description
Gets the field name.

### Function Signature
pub fn name(field: Field(a)) -> String

### Parameters
- **field** (Field(a)) - Required - The field to get the name from.

### Example
// No example provided in source.
```

--------------------------------

### new Function

Source: https://hexdocs.pm/gleamql/gleamql.html

Constructs a GleamQL Request with an operation.

```gleam
pub fn new(op: operation.Operation(t)) -> Request(t)
```

```gleam
gleamql.new(country_operation)
|> gleamql.host("api.example.com")
|> gleamql.path("/graphql")
|> gleamql.json_content_type()
|> gleamql.send(hackney.send, [#("code", json.string("GB"))])
```

--------------------------------

### name function signature

Source: https://hexdocs.pm/gleamql/gleamql/field.html

Function signature for getting the field name.

```gleam
pub fn name(field: Field(a)) -> String
```

--------------------------------

### host Function

Source: https://hexdocs.pm/gleamql/gleamql.html

Sets the host of the request.

```gleam
pub fn host(req: Request(t), host: String) -> Request(t)
```

```gleam
gleamql.host(req, "api.example.com")
```

--------------------------------

### gleamql.path

Source: https://hexdocs.pm/gleamql/gleamql.html

Sets the path of the request.

```APIDOC
## gleamql.path

### Description
Sets the path of the request.

### Function Signature
```
pub fn path(req: Request(t), path: String) -> Request(t)
```

### Parameters
- **req** (Request(t)) - The request to modify.
- **path** (String) - The path to set.

### Returns
- **Request(t)** - The modified request.

### Example
```
gleamql.path(req, "/graphql")
```
```

--------------------------------

### field.object_builder_decoder(builder: ObjectBuilder(a)) -> decode.Decoder(a)

Source: https://hexdocs.pm/gleamql/gleamql/field.html

Gets the decoder from an ObjectBuilder. This is for internal use.

```APIDOC
## field.object_builder_decoder

### Description
Gets the decoder from an ObjectBuilder. This is for internal use.

### Function Signature
pub fn object_builder_decoder(
  builder: ObjectBuilder(a),
) -> decode.Decoder(a)

### Parameters
- **builder** (ObjectBuilder(a)) - Required - The ObjectBuilder to extract the decoder from.

### Example
// No example provided in source.
```

--------------------------------

### gleamql.host

Source: https://hexdocs.pm/gleamql/gleamql.html

Sets the host of the request.

```APIDOC
## gleamql.host

### Description
Sets the host of the request.

### Function Signature
```
pub fn host(req: Request(t), host: String) -> Request(t)
```

### Parameters
- **req** (Request(t)) - The request to modify.
- **host** (String) - The host to set.

### Returns
- **Request(t)** - The modified request.

### Example
```
gleamql.host(req, "api.example.com")
```
```

--------------------------------

### object_builder_decoder function signature

Source: https://hexdocs.pm/gleamql/gleamql/field.html

Function signature for getting the decoder from an ObjectBuilder. Internal use.

```gleam
pub fn object_builder_decoder(
  builder: ObjectBuilder(a),
) -> decode.Decoder(a)
```

--------------------------------

### Get Decoder

Source: https://hexdocs.pm/gleamql/gleamql/operation.html

Retrieve the decoder from an operation, which automatically unwraps the 'data' field from the response.

```gleam
pub fn decoder(operation: Operation(a)) -> decode.Decoder(a)
```

--------------------------------

### Using Inline Fragments

Source: https://hexdocs.pm/gleamql/index.html

Querying union and interface types using inline fragments.

```gleam
// Query a union type
field.object("search", fn() {
  use user <- field.field(field.inline_on("User", fn() {
    use name <- field.field(field.string("name"))
    field.build(name)
  }))
  use post <- field.field(field.inline_on("Post", fn() {
    use title <- field.field(field.string("title"))
    field.build(title)
  }))
  field.build(SearchResult(user:, post:))
})
```

--------------------------------

### gleamql.header

Source: https://hexdocs.pm/gleamql/gleamql.html

Sets a header on the request, replacing any existing header with the same key.

```APIDOC
## gleamql.header

### Description
Sets a header on the request. If already present, it is replaced.

### Function Signature
```
pub fn header(req: Request(t), key: String, value: String) -> Request(t)
```

### Parameters
- **req** (Request(t)) - The request to modify.
- **key** (String) - The header name.
- **value** (String) - The header value.

### Returns
- **Request(t)** - The modified request.

### Example
```
gleamql.header(req, "Authorization", "Bearer token123")
```
```

--------------------------------

### with_args

Source: https://hexdocs.pm/gleamql/gleamql/field.html

Adds multiple arguments to a field. This function takes a field and a list of argument key-value pairs and returns a new field with the arguments applied.

```APIDOC
## with_args

### Description
Add multiple arguments to a field.

### Function Signature
pub fn with_args(
  fld: Field(a),
  args: List(#(String, Argument)),
) -> Field(a)

### Parameters
- **fld** (Field(a)) - Required - The field to which arguments will be added.
- **args** (List(#(String, Argument))) - Required - A list of tuples containing argument names and Argument values.

### Returns
- **Field(a)** - A new field with the specified arguments added.

### Example
```
field.object("posts", posts_builder)
|> field.with_args([
  #("first", Variable("limit")),
  #("after", InlineString("cursor123")),
])
// Generates: posts(first: $limit, after: "cursor123") { ... }
```
```

--------------------------------

### Using Fragments

Source: https://hexdocs.pm/gleamql/index.html

Reuse field selections across multiple queries using fragments.

```gleam
import gleamql/fragment

let user_fields = 
  fragment.on("User", "UserFields", fn() {
    use id <- field.field(field.id("id"))
    use name <- field.field(field.string("name"))
    field.build(User(id:, name:))
  })

operation.query("GetUsers")
|> operation.field(
  field.list(field.object("users", fn() {
    use user <- field.field(fragment.spread(user_fields))
    field.build(user)
  }))
)
```

--------------------------------

### field.string(name: String) -> Field(String)

Source: https://hexdocs.pm/gleamql/gleamql/field.html

Creates a String field.

```APIDOC
## field.string

### Description
Creates a String field.

### Function Signature
pub fn string(name: String) -> Field(String)

### Parameters
- **name** (String) - Required - The name of the field.

### Example
let name_field = field.string("name")
// Generates: name
// Decodes: String
```

--------------------------------

### build

Source: https://hexdocs.pm/gleamql/gleamql/field.html

Completes the object with a constructor. This is the final step in building an object field. It takes the constructed value and wraps it in a field.

```APIDOC
## build

### Description
Completes the object with a constructor. This is the final step in building an object field. It takes the constructed value and wraps it in a field.

### Function Signature
```gleam
pub fn build(value: a) -> ObjectBuilder(a)
```

### Parameters
- **value** (a) - The constructed value to wrap.

### Example
```gleam
field.object("country", fn() {
  use name <- field.field(field.string("name"))
  field.build(Country(name:))  // <- Complete with constructor
})
```
```

--------------------------------

### directive.new

Source: https://hexdocs.pm/gleamql/gleamql/directive.html

Creates a new directive with the given name and no arguments.

```APIDOC
## directive.new

### Description
Creates a new directive with the given name and no arguments.

### Function Signature
pub fn new(name: String) -> Directive

### Parameters
- **name** (String) - Required - The name of the directive.

### Returns
- **Directive** - The new directive.

### Example
```
let custom = directive.new("myDirective")
// Generates: @myDirective
```
```

--------------------------------

### path Function

Source: https://hexdocs.pm/gleamql/gleamql.html

Sets the path of the request.

```gleam
pub fn path(req: Request(t), path: String) -> Request(t)
```

```gleam
gleamql.path(req, "/graphql")
```

--------------------------------

### Create a query operation

Source: https://hexdocs.pm/gleamql/gleamql/operation.html

Use the query function to initialize a named query operation.

```gleam
operation.query("GetCountry")
|> operation.variable("code", "ID!")
|> operation.field(country_field())
|> operation.build()
```

--------------------------------

### field.object_builder_to_selection(builder: ObjectBuilder(a)) -> String

Source: https://hexdocs.pm/gleamql/gleamql/field.html

Extracts the selection string from an ObjectBuilder. This is used by the fragment module to get the field selection string from an ObjectBuilder.

```APIDOC
## field.object_builder_to_selection

### Description
Extracts the selection string from an ObjectBuilder. This is used by the fragment module to get the field selection string from an ObjectBuilder.

### Function Signature
pub fn object_builder_to_selection(
  builder: ObjectBuilder(a),
) -> String

### Parameters
- **builder** (ObjectBuilder(a)) - Required - The ObjectBuilder to extract the selection string from.

### Example
// No example provided in source.
```

--------------------------------

### Argument constructors

Source: https://hexdocs.pm/gleamql/gleamql/field.html

Lists the constructors for the Argument type, each representing a different kind of GraphQL argument value.

```gleam
Variable(name: String)
```

```gleam
InlineString(value: String)
```

```gleam
InlineInt(value: Int)
```

```gleam
InlineFloat(value: Float)
```

```gleam
InlineBool(value: Bool)
```

```gleam
InlineNull
```

```gleam
InlineObject(fields: List(#(String, Argument)))
```

```gleam
InlineList(items: List(Argument))
```

--------------------------------

### SelectionSet InlineFragment constructor

Source: https://hexdocs.pm/gleamql/gleamql/field.html

Constructor for an inline fragment: … on TypeName { fields } or … { fields }.

```gleam
InlineFragment(
  type_condition: option.Option(String),
  fields: String,
)
```

--------------------------------

### header Function

Source: https://hexdocs.pm/gleamql/gleamql.html

Sets a header on the request.

```gleam
pub fn header(
  req: Request(t),
  key: String,
  value: String,
) -> Request(t)
```

```gleam
gleamql.header(req, "Authorization", "Bearer token123")
```

--------------------------------

### to_selection: Build GraphQL selection string

Source: https://hexdocs.pm/gleamql/gleamql/field.html

Builds the GraphQL selection string for a field. This is an internal function used to generate the actual GraphQL query text.

```gleam
pub fn to_selection(field: Field(a)) -> String
```

--------------------------------

### Combining list with optional

Source: https://hexdocs.pm/gleamql/gleamql/field.html

Shows combining list and optional. The first creates a list of optional strings, the second an optional list of strings.

```gleam
// List of optional strings
let items_field = field.list(field.optional(field.string("items")))
// Decodes: List(Option(String))

// Optional list of strings
let maybe_tags_field = field.optional(field.list(field.string("tags")))
// Decodes: Option(List(String))
```

--------------------------------

### gleamql.send

Source: https://hexdocs.pm/gleamql/gleamql.html

Sends the built request to a GraphQL server with variable values. Requires an HTTP client adapter.

```APIDOC
## gleamql.send

### Description
Sends the built request to a GraphQL server with variable values. A HTTP client is needed to send the request, see https://github.com/gleam-lang/http#client-adapters.

### Function Signature
```
pub fn send(
  req: Request(t),
  http_send: fn(request.Request(String)) -> Result(response.Response(String), e),
  variables: List(#(String, json.Json)),
) -> Result(option.Option(t), Error(e))
```

### Parameters
- **req** (Request(t)) - The request to send.
- **http_send** (fn(request.Request(String)) -> Result(response.Response(String), e)) - The HTTP client send function.
- **variables** (List(#(String, json.Json))) - A list of name/JSON pairs for the GraphQL variables.

### Returns
- **Result(option.Option(t), Error(e))** - `Ok(Some(data))` if the query succeeded and returned data, `Ok(None)` if the query succeeded but returned null, or an `Error` if the request failed at any level.

### Example
```
import gleam/hackney
import gleam/json

gleamql.send(request, hackney.send, [
  #("code", json.string("GB")),
  #("lang", json.string("en")),
])
```
```

--------------------------------

### root

Source: https://hexdocs.pm/gleamql/gleamql/operation.html

Sets multiple root fields for the operation using a builder pattern.

```APIDOC
## root(builder: OperationBuilder(b), root_builder: fn() -> field.ObjectBuilder(a)) -> Operation(a)

### Description
Set multiple root fields for the operation using a builder pattern. This allows you to query multiple root fields in a single operation while maintaining full type safety.
```

--------------------------------

### Applying Directives

Source: https://hexdocs.pm/gleamql/index.html

Conditionally include fields using GraphQL directives.

```gleam
import gleamql/directive

field.string("email")
|> field.with_directive(directive.include("showEmail"))
// Generates: email @include(if: $showEmail)
```

--------------------------------

### SelectionSet FragmentSpread constructor

Source: https://hexdocs.pm/gleamql/gleamql/field.html

Constructor for a fragment spread: …FragmentName.

```gleam
FragmentSpread(name: String)
```

--------------------------------

### operation.root

Source: https://hexdocs.pm/gleamql/gleamql/operation.html

Sets multiple root fields for the operation.

```APIDOC
## operation.root

### Description
Sets multiple root fields for the operation, allowing querying multiple fields at the root level while maintaining type safety.

### Function Signature
`pub fn root(builder: OperationBuilder(a), build_fields: fn() -> a) -> OperationBuilder(a)`

### Parameters
- `builder` (OperationBuilder(a)) - Required - The operation builder.
- `build_fields` (fn() -> a) - Required - A function that builds the root fields.

### Returns
- `OperationBuilder(a)` - The updated operation builder.

### Example
```gleam
operation.query("GetDashboard")
|> operation.variable("userId", "ID!")
|> operation.root(fn() {
  use user <- field.field(user_field())
  use posts <- field.field(posts_field())
  use stats <- field.field(stats_field())
  field.build(#(user, posts, stats))
})
```
```

--------------------------------

### bool

Source: https://hexdocs.pm/gleamql/gleamql/field.html

Creates a Bool field.

```APIDOC
## bool

### Description
Creates a Bool field.

### Function Signature
```gleam
pub fn bool(name: String) -> Field(Bool)
```

### Parameters
- **name** (String) - The name of the field.

### Example
```gleam
let active_field = field.bool("isActive")
// Generates: isActive
// Decodes: Bool
```
```

--------------------------------

### operation.build

Source: https://hexdocs.pm/gleamql/gleamql/operation.html

Alias for `field` that builds the operation.

```APIDOC
## operation.build

### Description
Alias for `field` that builds the operation.

### Function Signature
`pub fn build(operation: Operation(a)) -> Operation(a)`

### Parameters
- `operation` (Operation(a)) - Required - The operation to build.

### Returns
- `Operation(a)` - The built operation.

### Example
```gleam
operation.query("GetCountry")
|> operation.variable("code", "ID!")
|> operation.field(country_field())
|> operation.build()
```
```

--------------------------------

### SelectionSet PhantomRoot constructor

Source: https://hexdocs.pm/gleamql/gleamql/field.html

Constructor for a phantom root for multiple root-level fields. This selection type exists only in the builder - it renders its children directly without wrapping them in a named field.

```gleam
PhantomRoot(fields: String)
```

--------------------------------

### directive.to_string

Source: https://hexdocs.pm/gleamql/gleamql/directive.html

Converts a directive to its GraphQL string representation.

```APIDOC
## directive.to_string

### Description
Converts a directive to its GraphQL string representation.

### Function Signature
pub fn to_string(dir: Directive) -> String

### Parameters
- **dir** (Directive) - Required - The directive to convert.

### Returns
- **String** - The GraphQL string representation.

### Example
```
directive.to_string(directive.skip("var"))
// Returns: "@skip(if: $var)"

directive.to_string(directive.include_if(true))
// Returns: "@include(if: true)"
```
```

--------------------------------

### with_arg function signature

Source: https://hexdocs.pm/gleamql/gleamql/directive.html

Adds an argument to a directive.

```Gleam
pub fn with_arg(
  dir: Directive,
  arg_name: String,
  arg_value: DirectiveArgument,
) -> Directive

```

--------------------------------

### to_string function signature

Source: https://hexdocs.pm/gleamql/gleamql/directive.html

Converts a directive to its GraphQL string representation.

```Gleam
pub fn to_string(dir: Directive) -> String

```

--------------------------------

### from_fragment_spread_with_definition function signature

Source: https://hexdocs.pm/gleamql/gleamql/field.html

Creates a field from a fragment spread with the fragment definition (internal use by fragment module).

```gleam
pub fn from_fragment_spread_with_definition(
  fragment_name: String,
  fragment_decoder: decode.Decoder(a),
  fragment_definition: String,
) -> Field(a)
```

--------------------------------

### operation.field

Source: https://hexdocs.pm/gleamql/gleamql/operation.html

Sets the root field for the operation and builds the final Operation.

```APIDOC
## operation.field

### Description
Sets the root field for the operation and builds the final Operation. This completes the operation builder and generates the GraphQL query string. Fragments used in the field tree are automatically collected and included in the operation.

### Function Signature
`pub fn field(builder: OperationBuilder(a), root_field: field.Field(a)) -> Operation(a)`

### Parameters
- `builder` (OperationBuilder(a)) - Required - The operation builder.
- `root_field` (field.Field(a)) - Required - The root field to include in the operation.

### Returns
- `Operation(a)` - The completed operation.

### Example
```gleam
operation.query("GetCountry")
|> operation.variable("code", "ID!")
|> operation.field(country_field())
|> operation.build()
```
```

--------------------------------

### Create a mutation operation

Source: https://hexdocs.pm/gleamql/gleamql/operation.html

Use the mutation function to initialize a named mutation operation.

```gleam
operation.mutation("CreatePost")
|> operation.variable("input", "CreatePostInput!")
|> operation.field(create_post_field())
|> operation.build()
```

--------------------------------

### new function signature

Source: https://hexdocs.pm/gleamql/gleamql/directive.html

Creates a new directive with the given name and no arguments.

```Gleam
pub fn new(name: String) -> Directive

```

--------------------------------

### arguments function signature

Source: https://hexdocs.pm/gleamql/gleamql/directive.html

Returns a list of argument name and DirectiveArgument pairs for a given directive.

```Gleam
pub fn arguments(
  dir: Directive,
) -> List(#(String, DirectiveArgument))

```

--------------------------------

### SelectionSet Object constructor

Source: https://hexdocs.pm/gleamql/gleamql/field.html

Constructor for an object field with nested field selections.

```gleam
Object(fields: String)
```

--------------------------------

### arg_string

Source: https://hexdocs.pm/gleamql/gleamql/field.html

Adds an inline string argument to a field.

```APIDOC
## arg_string

### Description
Adds an inline string argument to a field.

### Function Signature
```gleam
pub fn arg_string(
  fld: Field(a),
  arg_name: String,
  value: String,
) -> Field(a)
```

### Parameters
- **fld** (Field(a)) - The field to add the argument to.
- **arg_name** (String) - The name of the argument.
- **value** (String) - The string value to use as the argument.

### Example
```gleam
field.object("country", country_builder)
|> field.arg_string("code", "GB")
// Generates: country(code: "GB") { ... }
```
```

--------------------------------

### field.inline_on

Source: https://hexdocs.pm/gleamql/gleamql/field.html

Creates an inline fragment for a specific type.

```APIDOC
## field.inline_on

### Description
Creates an inline fragment that conditionally selects fields based on a type.

### Usage
```gleam
field.inline_on("User", fn() {
  use name <- field.field(field.string("name"))
  field.build(name)
})
```

### Parameters
- **type** (String) - The type name to match.
- **builder** (fn() -> FieldBuilder) - A function that builds the fields for the fragment.

### Returns
An inline fragment field builder.
```

--------------------------------

### to_string

Source: https://hexdocs.pm/gleamql/gleamql/operation.html

Converts an operation to its GraphQL query string representation.

```APIDOC
## to_string(operation: Operation(a)) -> String

### Description
Get the GraphQL query string from an operation.
```

--------------------------------

### Use inline fragments for unions and directives

Source: https://hexdocs.pm/gleamql/gleamql/field.html

Shows how to use inline fragments to conditionally select fields on a union type and to group fields with directives.

```gleam
// Querying a union type
field.object("search", fn() {
  use user <- field.field(field.inline_on("User", fn() {
    use name <- field.field(field.string("name"))
    field.build(name)
  }))
  field.build(user)
})
// Generates: search { ... on User { name } }
```

```gleam
// Grouping fields with directives
field.inline(builder)
|> field.with_directive(directive.include("var"))
```

--------------------------------

### field.list

Source: https://hexdocs.pm/gleamql/gleamql/field.html

Creates a field builder for a list of fields.

```APIDOC
## field.list

### Description
Creates a field builder for a list of fields.

### Usage
```gleam
let tags_field = field.list(field.string("tags"))
```

### Parameters
- **inner** (FieldBuilder) - The field builder for the list items.

### Returns
A field builder for a list field.
```