resources/definitions/Relay.graphql

# https://github.com/facebook/relay/blob/349f161ff052de21fd0d4e247c93e375eceb6ecc/compiler/crates/relay-schema/src/relay-extensions.graphql

# noinspection GraphQLIllegalName

"""
`@argumentDefinitions` is a directive used to specify arguments taken by a fragment.

[Read More](https://relay.dev/docs/api-reference/graphql-and-directives/#argumentdefinitions)
"""
directive @argumentDefinitions on FRAGMENT_DEFINITION

"""
`@arguments` is a directive used to pass arguments to a fragment that was defined using `@argumentDefinitions`.

[Read More](https://relay.dev/docs/api-reference/graphql-and-directives/#arguments)
"""
directive @arguments on FRAGMENT_SPREAD

"""
A directive which declares that a field implements the connection spec.

[Read More](https://relay.dev/docs/guided-tour/list-data/pagination/)
"""
directive @connection(
    key: String!
    filters: [String]
    handler: String
    dynamicKey_UNSTABLE: String
    prefetchable_pagination: Boolean = false
) on FIELD

directive @stream_connection(
    key: String!
    filters: [String]
    handler: String
    label: String
    initial_count: Int!
    if: Boolean = true
    use_customized_batch: Boolean = false
    dynamicKey_UNSTABLE: String
    prefetchable_pagination: Boolean = false
) on FIELD

"""
A directive that allows you to turn off Relay's data masking.

Read more
[here](https://relay.dev/docs/api-reference/graphql-and-directives/#relayplural-boolean)
and
[here](https://relay.dev/docs/api-reference/graphql-and-directives/#relaymask-boolean).
"""
directive @relay(
    """
    Relay by default will only expose the data for fields explicitly requested by a component's fragment,
    which is known as data masking. However, `@relay(mask: false)` can be used to prevent data masking; when including a
    fragment and annotating it with `@relay(mask: false)`, its data will be available to the parent, recursively including
    the data from the fields of the referenced fragment.
    """
    mask: Boolean

    """
    When defining a fragment, you can use the `@relay(plural: true)` directive to indicate that the fragment is
    backed by a GraphQL list, meaning that it will inform Relay that this particular field is an array.
    """
    plural: Boolean
) on FRAGMENT_DEFINITION | FRAGMENT_SPREAD

directive @relay_test_operation(
    DO_NOT_USE_use_in_production: Boolean = false @static
    emitRawText: Boolean = false @static
) on QUERY | MUTATION | SUBSCRIPTION

"""
The hooks APIs that Relay exposes allow you to read data from the store only
during the render phase. In order to read data from outside of the render
phase (or from outside of React), Relay exposes the `@inline` directive. The
data from a fragment annotated with `@inline` can be read using `readInlineData`.

[Read More](https://relay.dev/docs/api-reference/graphql-and-directives/#inline)
"""
directive @inline on FRAGMENT_DEFINITION

directive @no_inline(raw_response_type: Boolean) on FRAGMENT_DEFINITION

"""
A directive added to queries and fragments which causes the Relay client to throw
if reading a field that has an error. Relay will also honor the `@semanticNonNull`
directive on fields read from that query or fragment. Emitted types for such
fields will be non-null. Requires the `experimental_emit_semantic_nullability_types`
typegen configuration to be enabled.

[Read More](https://relay.dev/docs/guides/throw-on-field-error-directive/)
"""
directive @throwOnFieldError on QUERY | FRAGMENT_DEFINITION

"""
A directive added to queries which tells Relay to generate types that cover
the `optimisticResponse` parameter to `commitMutation`.

[Read More](https://relay.dev/docs/glossary/#raw_response_type)
"""
directive @raw_response_type on QUERY | MUTATION | SUBSCRIPTION

"""
For use with [`useRefetchableFragment`](https://relay.dev/docs/api-reference/use-refetchable-fragment/).

The `@refetchable` directive can only be added to fragments that are
"refetchable", that is, on fragments that are declared on Viewer or Query
types, or on a type that implements `Node` (i.e. a type that has an id).

[Read More](https://relay.dev/docs/api-reference/use-refetchable-fragment/#arguments)
"""
directive @refetchable(
    queryName: String!
    directives: [String!]
    preferFetchable: Boolean
) on FRAGMENT_DEFINITION

"""
A directive that modifies queries and which causes Relay to generate
`$Parameters.js` files and preloadable concrete requests. Required if the
query is going to be used as part of an entry point.

[Read More](https://relay.dev/docs/glossary/#preloadable)
"""
directive @preloadable on QUERY

directive @__clientField(
    filters: [String!]
    handle: String!
    key: String
) repeatable on FIELD

"""
A directive that, when used in combination with `@module`, allows users to
download specific JS components alongside the rest of the GraphQL payload if
the field decorated with [`@match`](https://relay.dev/docs/glossary/#match)
has a certain type. See [3D](https://relay.dev/docs/glossary/#3d).

[Read More](https://relay.dev/docs/glossary/#match)
"""
directive @match(key: String @static) on FIELD

"""
A directive that, when used in combination with
[`@match`](https://relay.dev/docs/glossary/#match), allows users to specify
which JS components to download if the field decorated with @match has a
certain type. See [3D](https://relay.dev/docs/glossary/#3d).

[Read More](https://relay.dev/docs/glossary/#module)
"""
directive @module(name: String!) on FRAGMENT_SPREAD

enum RequiredFieldAction {
    NONE
    LOG
    THROW
}

"""
`@required` is a directive you can add to fields in your Relay queries to
declare how null values should be handled at runtime. You can think of it as
saying "if this field is ever null, its parent field is invalid and should be
null".

[Read More](https://relay.dev/docs/guides/required-directive/)
"""
directive @required(action: RequiredFieldAction! @static) on FIELD

"""
Directs the executor to defer this fragment when the `if` argument is true or undefined.

[Read More](https://relay.dev/docs/glossary/#defer)
"""
directive @defer(
    "Deferred when true or undefined."
    if: Boolean! = true,
    "Unique name"
    label: String
) on FRAGMENT_SPREAD | INLINE_FRAGMENT

"""
Directs the executor to stream plural fields when the `if` argument is true or undefined.

[Read More](https://relay.dev/docs/glossary/#stream)
"""
directive @stream(
    "Stream when true or undefined."
    if: Boolean! = true,
    "Number of items to return immediately"
    initialCount: Int = 0,
    "Unique name"
    label: String
) on FIELD

"""
For use within mutations. After the mutation request is complete, this field
will be removed from the store.

[Read More](https://relay.dev/docs/guided-tour/updating-data/graphql-mutations/#deleting-items-in-response-to-mutations)
"""
directive @deleteRecord on FIELD

"""
For use within mutations. After the mutation request is complete, this edge
will be removed from its parent connection.

[Read More](https://relay.dev/docs/guided-tour/list-data/updating-connections/#removing-edges)
"""
directive @deleteEdge(
    """
    An array of connection IDs. Connection IDs can be obtained either by using the `__id` field on connections
    or using the `ConnectionHandler.getConnectionID` API.
    """
    connections: [ID!]!
) on FIELD

"""
For use within mutations. After the mutation request is complete, this edge
will be appended to its parent connection.

[Read More](https://relay.dev/docs/guided-tour/list-data/updating-connections/#appendedge--prependedge)
"""
directive @appendEdge(connections: [ID!]!) on FIELD

"""
For use within mutations. After the mutation request is complete, this edge
will be prepended to its parent connection.

[Read More](https://relay.dev/docs/guided-tour/list-data/updating-connections/#appendedge--prependedge)
"""
directive @prependEdge(
    """
    An array of connection IDs. Connection IDs can be obtained either by using the `__id` field on connections
    or using the `ConnectionHandler.getConnectionID` API.
    """
    connections: [ID!]!
) on FIELD

"""
For use within mutations. After the mutation request is complete, this node
will be appended to its parent connection.

[Read More](https://relay.dev/docs/guided-tour/list-data/updating-connections/#appendnode--prependnode)
"""
directive @appendNode(
    """
    An array of connection IDs. Connection IDs can be obtained either by using the `__id` field on connections
    or using the `ConnectionHandler.getConnectionID` API.
    """
    connections: [ID!]!

    """
    The typename of an edge, corresponding to the edge type argument in `ConnectionHandler.createEdge`.
    """
    edgeTypeName: String!
) on FIELD

"""
For use within mutations. After the mutation request is complete, this node
will be prepended to its parent connection.

[Read More](https://relay.dev/docs/guided-tour/list-data/updating-connections/#appendnode--prependnode)
"""
directive @prependNode(
    """
    An array of connection IDs. Connection IDs can be obtained either by using the `__id` field on connections
    or using the `ConnectionHandler.getConnectionID` API.
    """
    connections: [ID!]!

    """
    The typename of an edge, corresponding to the edge type argument in `ConnectionHandler.createEdge`.
    """
    edgeTypeName: String!
) on FIELD

directive @relay_client_component on FRAGMENT_SPREAD

directive @relay_resolver(
    fragment_name: String!
    import_path: String!
    live: Boolean
) on FIELD_DEFINITION

"""
Reading this Client Edge field triggers a network roundtrip or "waterfall". The
consuming component will suspend until that request has been fulfilled.
"""
directive @waterfall on FIELD

"""
A special scalar type which can be used as the return type of a Relay Resolver.
When used, the resolver field will derive its TypeScript/Flow type from the
return value of the Resolver function.

[Learn More](https://relay.dev/docs/guides/relay-resolvers/return-types/#javascript-values)
"""
scalar RelayResolverValue

"""
Marks a given query or fragment as updatable.

[Read More](https://relay.dev/docs/guided-tour/updating-data/imperatively-modifying-linked-fields/)
"""
directive @updatable on QUERY | FRAGMENT_DEFINITION

"""
Marks a given fragment as assignable.

[Read More](https://relay.dev/docs/guided-tour/updating-data/imperatively-modifying-linked-fields/)
"""
directive @assignable on FRAGMENT_DEFINITION

"""
Exposes a fragment's data as a new field which can be null checked to ensure it
matches the parent selection.

[Read More](https://relay.dev/docs/guides/alias-directive/)
"""
directive @alias(as: String) on FRAGMENT_SPREAD | INLINE_FRAGMENT

"""
Indicates that a given directive argument is expected to be provided statically.
If a non-static value is provided, it will result in a validation error.

Used for arguments which are expected to be read by the Relay compiler.
"""
directive @static on ARGUMENT_DEFINITION

"""
If added to a query, resolvers in that query to run at exec-time, rather than read-time.
This means the resolvers are run when the query data is requested rather than when the
query is used (i.e. when the network request is made instead of at render time).
"""
directive @exec_time_resolvers(enabledProvider: String) on QUERY

"""
Indicates that a position is semantically non null: it is only null if there is a matching error in the `errors` array.
In all other cases, the position is non-null.

Tools doing code generation may use this information to generate the position as non-null if field errors are handled out of band:

```graphql
type User {
    # email is semantically non-null and can be generated as non-null by error-handling clients.
    email: String @semanticNonNull
}
```

The `levels` argument indicates what levels are semantically non null in case of lists:

```graphql
type User {
    # friends is semantically non null
    friends: [User] @semanticNonNull # same as @semanticNonNull(levels: [0])

    # every friends[k] is semantically non null
    friends: [User] @semanticNonNull(levels: [1])

    # friends as well as every friends[k] is semantically non null
    friends: [User] @semanticNonNull(levels: [0, 1])
}
```

`levels` are zero indexed.
Passing a negative level or a level greater than the list dimension is an error.

"""
directive @semanticNonNull(levels: [Int] = [0]) on FIELD_DEFINITION

"""
Indicates that a position is semantically non null: it is only null if there is a matching error in the `errors` array.
In all other cases, the position is non-null.

`@semanticNonNullField` is the same as `@semanticNonNull` but can be used on type system extensions for services
that do not own the schema like client services:

```graphql
# extend the schema to make User.email semantically non-null.
extend type User @semanticNonNullField(name: "email")
```

The `levels` argument indicates what levels are semantically non null in case of lists:

```graphql
# friends is semantically non null
extend type User @semanticNonNullField(name: "friends")  # same as @semanticNonNullField(name: "friends", levels: [0])

# every friends[k] is semantically non null
extend type User @semanticNonNullField(name: "friends", levels: [1])

# friends as well as every friends[k] is semantically non null
extend type User @semanticNonNullField(name: "friends", levels: [0, 1])
```

`levels` are zero indexed.
Passing a negative level or a level greater than the list dimension is an error.

See `@semanticNonNull`.
"""
directive @semanticNonNullField(name: String!, levels: [Int] = [0]) repeatable on OBJECT | INTERFACE

"""
`@catch` is a directive you can add to fields, fragment definitions, queries,
mutations, and aliased inline fragments to opt into explicitly handling field
errors.

[Read More](https://relay.dev/docs/guides/catch-directive/)
"""
directive @catch(
    to: CatchFieldTo! = RESULT @static
) on FIELD | FRAGMENT_DEFINITION | QUERY | MUTATION | INLINE_FRAGMENT

"""
`NULL` and `RESULT` are the `to` values you can use in the `@catch`
directive to tell relay how to treat field-level errors.
"""
enum CatchFieldTo {
    """
    Returns a result type containing either the value or error information.
    Enables explicit field-granular error handling.
    """
    NULL

    """
    Returns `null` on error. Simpler but cannot distinguish between semantic null and error null.
    """
    RESULT
}