directive @supplies
The @supplies
directive specifies that a Query
or Mutation
field (the supplying field) with an object type
supplies another Query
or Mutation
field (the supplied field) with an abstract type.
When the supplied field is selected, all of its supplying fields are resolved. The value of the supplied field is derived from the collection of values from the supplying fields.
Usage
@supplies(query:"fieldname")
can only annotate fields in typeQuery
that return an object type or list of object type (regardless of any nullability wrapping).@supplies(mutation:"fieldname")
can only annotate fields in typeMutation
that return an object type or list of object type (regardless of any nullability wrapping).Note: One of
query
ormutation
must be set.
Supplier field requirements
The object type of the supplying field must:
implement the interface type of the supplied field, or
be a member of the union type of the supplied field
Multiple fields can supply a single field, and the supplying fields can have different object types that are assignable to the abstract type.
Resolution of supplied field values
The value of the supplied field depends on the number and types of the supplying fields.
All supplying fields are logically executed to create a collection of non-null values. For each supplying field:
if its type is
T
orT!
and its value is non-null, the value is added to the collection.if its type is
[T]
,[T!]
, or[T!]!
and its list value is non-null, all of the list's non-null elements are extracted and added to the collection.
The value of the supplied field will be:
for fields of type
A
orA!
:null
if the collection is emptyone of the values in the collection.
for fields of type
[A]
,[A!]
, or[A!]!
:null
if all supplying fields arenull
empty list if the collection is empty
all of the values in the collection
Conditional execution
Supplying fields can be conditionally executed using the if
argument.
The return value of the script is converted to a boolean value
using the ECMAScript ToBoolean
conversion.
If the converted return value is true
then
the supplying field is invoked to provide a value for the supplied field.
If false
, the supplying field is not invoked and evaluates tonull
.
Note: if
condition applies only when executing the supplied field.
Errors from supplying fields are hidden unless no other supplying field returns a non-null value, in which case an error is returned.
Arguments
if: StepZen_Script
Optional condition to be executed before the annotated field is invoked
when supplying the field specified in query
or mutation
.
The script has access to the arguments of the annotated field
and any JWT claims using $jwt
.
The return value of the script is converted to a boolean value
using the ECMAScript ToBoolean
conversion.
If the converted return value is true
then
the supplying field will be invoked to provide a value for the supplied field.
Otherwise the supplying field is not invoked and evaluates tonull
.
mutation: String
query: String
Locations
Type System: FIELD_DEFINITION
Examples
Conditional using ECMASCRIPT
For language ECMASCRIPT
the script has the supplying field's arguments
available as global variables. In this example, the supplying field
is only called if the trackingId
argument starts with PX-
.
extend type Query {
pkgExpress(tackingId:ID!):PKGExpress
@supplies(query:"delivery" if: {src:"trackingId.startsWith('PX-')"})
@rest(endpoint:"https://pkgexpress.com/track")
}
Conditional using JSONATA
For language JSONATA
, the script is executed with a single object as
its input containing the field's arguments as values. In this example, the supplying field
is called only if the trackingId
argument starts with TYD-
.
extend type Query {
tyd(trackingId: ID!): ToYourDoor
@supplies(query:"delivery" if: {src: "$contains(trackingId, /^TYD-/)", language: JSONATA})
@rest(endpoint:"https://to-your-door.com/track")
}
Conditional accessing JWT custom claims
If the original request used a JWT for authorization then JWT custom claims are available as keys
in the object $jwt
. This allows conditional execution based upon JWT claims.
extend type Query {
promotion: Promotion
goldPromotion: GoldPromotion
@supplies(
query: "promotion",
if: {src: "$jwt && $jwt.rewards === 'gold'" language: ECMASCRIPT}
)
silverPromotion: SilverPromotion
@supplies(
query: "promotion"
if: {src: "`$jwt`.rewards = 'silver'" language: JSONATA}
)
}
Note If no JWT was used then $jwt
is set to null
.