gleamql/directive

GraphQL directive support for fields, fragments, and operations.

This module provides support for GraphQL directives, which are annotations that can be applied to fields, fragments, and other GraphQL elements to modify their behavior at execution time.

Basic Usage

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")))

Built-in Directives

GraphQL defines several standard directives:

@skip(if: Boolean!) - Skip field if condition is true
@include(if: Boolean!) - Include field if condition is true
@deprecated(reason: String) - Mark field as deprecated
@specifiedBy(url: String!) - Provide scalar specification URL

Custom Directives

You can also create custom directives using the new() and with_arg() functions:

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

Types

Directive

opaque </>

A GraphQL directive that can be applied to fields, fragments, and other elements.

Directives are prefixed with @ in GraphQL and can have arguments. Example: @skip(if: $shouldSkip)

pub opaque type Directive

DirectiveArgument

</>

Arguments that can be passed to directive parameters.

This type is defined here to avoid circular dependencies with the field module.

pub type DirectiveArgument {
  Variable(name: String)
  InlineString(value: String)
  InlineInt(value: Int)
  InlineFloat(value: Float)
  InlineBool(value: Bool)
  InlineNull
  InlineObject(fields: List(#(String, DirectiveArgument)))
  InlineList(items: List(DirectiveArgument))
}

Constructors

```
Variable(name: String)
```
A reference to a variable: $variableName
```
InlineString(value: String)
```
An inline string literal: “value”
```
InlineInt(value: Int)
```
An inline integer literal: 42
```
InlineFloat(value: Float)
```
An inline float literal: 3.14
```
InlineBool(value: Bool)
```
An inline boolean literal: true or false
```
InlineNull
```
An inline null value

InlineObject(fields: List(#(String, DirectiveArgument)))

An inline object: { key: value, … }

InlineList(items: List(DirectiveArgument))

An inline list: [item1, item2, …]

Values

arguments

</>

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

Get the arguments of a directive.

deprecated

</>

pub fn deprecated(reason: option.Option(String)) -> Directive

Create a @deprecated directive to mark a field as deprecated.

The @deprecated directive is typically used in schema definitions, but can also be useful for documentation purposes in queries.

Example

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

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

include

</>

pub fn include(variable_name: String) -> Directive

Create an @include directive that conditionally includes a field.

The @include directive is one of the standard GraphQL directives. When the condition evaluates to true, the field is included in the response.

Example

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

You must define the corresponding variable in your operation:

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

include_if

</>

pub fn include_if(condition: Bool) -> Directive

Create an @include directive with an inline boolean value.

This variant uses an inline boolean instead of a variable reference.

Example

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

name

</>

pub fn name(dir: Directive) -> String

Get the name of a directive.

new

</>

pub fn new(name: String) -> Directive

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

Example

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

skip

</>

pub fn skip(variable_name: String) -> Directive

Create a @skip directive that conditionally excludes a field.

The @skip directive is one of the standard GraphQL directives. When the condition evaluates to true, the field is excluded from the response.

Example

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

You must define the corresponding variable in your operation:

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

skip_if

</>

pub fn skip_if(condition: Bool) -> Directive

Create a @skip directive with an inline boolean value.

This variant uses an inline boolean instead of a variable reference.

Example

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

specified_by

</>

pub fn specified_by(url: String) -> Directive

Create a @specifiedBy directive to reference a scalar specification.

The @specifiedBy directive provides a URL to the specification of a custom scalar.

Example

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

to_string

</>

pub fn to_string(dir: Directive) -> String

Convert a directive to its GraphQL string representation.

This is used internally to generate the GraphQL query string.

Example

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

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

with_arg

</>

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

Add an argument to a directive.

Arguments can be inline values or variable references.

Example

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