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 type Query that return an object type or list of object type (regardless of any nullability wrapping).

  • @supplies(mutation:"fieldname") can only annotate fields in type Mutation that return an object type or list of object type (regardless of any nullability wrapping).

    Note: One of query or mutation 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 or T!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 or A!:

    • null if the collection is empty

    • one of the values in the collection.

  • for fields of type [A], [A!], or [A!]!:

    • null if all supplying fields are null

    • 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.