Graphene-JS¶

Definition¶

You can create an Enum using classes:

import { EnumType } from "graphene-js";

@EnumType()
class Episode {
    static NEWHOPE = 4
    static EMPIRE = 5
    static JEDI = 6
}

Graphene will automatically search for the static variables in the Enum and expose them as the enum values.

Value descriptions¶

It’s possible to add a description to an enum value, for that the enum value needs to have the ``description``decorator on it.

@EnumType()
class Episode {
    @description("New hope episode")
    static NEWHOPE = 4

    @description("Empire episode")
    static EMPIRE = 5

    @description("JEDI episode")
    static JEDI = 6
}

Base scalars¶

String

Represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Int

Represents non-fractional signed whole numeric values. Int can represent values between -(2^53 - 1) and 2^53 - 1 since represented in JSON as double-precision floating point numbers specified by IEEE 754.

Float

Represents signed double-precision fractional values as specified by IEEE 754.

Boolean

Represents true or false.

ID

Represents a unique identifier, often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as “4”) or integer (such as 4) input value will be accepted as an ID.

Graphene also provides custom scalars for Dates, Times, and JSON:

graphene.Date

Represents a Date value as specified by iso8601.

graphene.DateTime

Represents a DateTime value as specified by iso8601.

graphene.Time

Represents a Time value as specified by iso8601.

Custom scalars¶

You can create custom scalars for your schema. The following is an example for creating a DateTime scalar:

  import { GraphQLScalarType } from "graphql";

  const Date = new GraphQLScalarType({
      name: 'Date',
      description: 'Date custom scalar type',
      parseValue(value) {
          return new Date(value); // value from the client
      },
      serialize(value) {
          return value.getTime(); // value sent to the client
      },
      parseLiteral(ast) {
          if (ast.kind === Kind.INT) {
              return parseInt(ast.value, 10); // ast value is always in string format
          }
          return null;
      },
});

List¶

import { ObjectType, List } from "graphene-js";

@ObjectType()
class Character {
    @Field(List(String)) appearsIn;
}

Lists work in a similar way: We can use a type modifier to mark a type as a List, which indicates that this field will return a list of that type. It works the same for arguments, where the validation step will expect a list for that value.

For ease of development, we can directly use js lists with one element [].

Like:

import { ObjectType, Field } from "graphene-js";

@ObjectType()
class Character {
    @Field([String]) appearsIn;
}

NonNull¶

import { ObjectType, Field, NonNull } from "graphene-js";

@ObjectType()
class Character {
    @Field(NonNull(String)) name;
}

Here, we’re using a String type and marking it as Non-Null by wrapping it using the NonNull class. This means that our server always expects to return a non-null value for this field, and if it ends up getting a null value that will actually trigger a GraphQL execution error, letting the client know that something has gone wrong.

Quick example¶

This example model defines a Character interface with a name. Human and Droid are two implementations of that interface.

import { InterfaceType, ObjectType, Field } from "graphene-js";

@InterfaceType()
class Character {
    @Field(String) name;
}

// Human is a Character implementation
@ObjectType({
    interfaces: [Character]
})
class Human {
    @Field(String) bornIn;
}

// Droid is a Character implementation
@ObjectType({
    interfaces: [Character]
})
class Human {
    @Field(String) function;
}

name is a field on the Character interface that will also exist on both the Human and Droid ObjectTypes (as those implement the Character interface). Each ObjectType may define additional fields.

The above types have the following representation in a schema:

interface Character {
  name: String
}

type Droid implements Character {
  name: String
  function: String
}

type Human implements Character {
  name: String
  bornIn: String
}

Quick example¶

This example model defines several ObjectTypes with their own fields. SearchResult is the implementation of Union of this object types.

import { ObjectType, UnionType, Field } from "graphene-js";

class Human {
    @Field(String) name;
    @Field(String) bornIn;
}

class Droid {
    @Field(String) name;
    @Field(String) primaryFunction;
}

class Starship {
    @Field(String) name;
    @Field(Number) length;
}

const SearchResult = new UnionType({
    name: 'SearchResult',
    types: [Human, Droid, Starship]
})

Wherever we return a SearchResult type in our schema, we might get a Human, a Droid, or a Starship. Note that members of a union type need to be concrete object types; you can’t create a union type out of interfaces or other unions.

The above types have the following representation in a schema:

type Droid {
  name: String
  primaryFunction: String
}

type Human {
  name: String
  bornIn: String
}

type Ship {
  name: String
  length: Int
}

union SearchResult = Human | Droid | Starship

Quick example¶

This example model defines a Person, with a first and a last name:

import { ObjectType, Field } from "graphene-js";

@ObjectType()
class Person {
    @Field(String) firstName;
    @Field(String) lastName;
    @Field(String)
    fullName() {
        return `${this.firstName} ${this.lastName}`;
    }
}

firstName and lastName are fields of the ObjectType. Each field is specified as a class attribute, and each attribute maps to a Field.

The above Person ObjectType has the following schema representation:

type Person {
  firstName: String
  lastName: String
  fullName: String
}

Resolvers¶

A resolver is a method that resolves certain fields within a ObjectType. If not specififed otherwise, the resolver of a field is the resolve_{field_name} method on the ObjectType.

By default resolvers take the arguments args, context and info.

import { ObjectType, Field } from "graphene-js";

@ObjectType()
class Query {
    @Field(String, {args: {word: String}})
    reverse({word}) {
        return (word || "").split("").reverse().join("")
    }
}

Instances as data containers¶

Graphene ObjectTypes can act as containers too. So with the previous example you could do:

peter = new Person({firstName: "", lastName: ""})

peter.firstName # prints "Peter"
peter.lastName # prints "Griffin"

Types¶

There are some cases where the schema cannot access all of the types that we plan to have. For example, when a field returns an Interface, the schema doesn’t know about any of the implementations.

In this case, we need to use the types argument when creating the Schema.

const schema = new Schema({
    query: MyRootQuery,
    types=[SomeExtraType, ],
})

Querying¶

To query a schema, call the execute method on it.

await schema.execute('{ hello }')