supergraph-orm

GraphQL ORM for GraphQL query delegation

Overview

supergraph-orm is an ORM layer on top of any existing executable GraphQL schema. This can be a local executable schema, or a remote one. It makes query delegation (a common pattern in GraphQL gateways) easier.

Install

yarn add supergraph-orm
# or
npm install --save supergraph-orm

Example

Consider the following executable schema definition:

const users = []

const typeDefs = `
  type Query {
    allUsers: [User]
    hello(name: String): HelloPayload
  }
  
  type Mutation {
    createUser: User
  }
  
  type User {
    id: Int
    name: String
  }
  
  type HelloPayload {
    message: String
  }`

const resolvers = {
  Query: {
    hello: (_, { name }) => ({ message: `Hello ${name || 'world'}!` })
    allUsers: () => users
  },
  Mutation: {
    createUser: (_ { name }) => {
      const newUser = { id: users.length, name }
      users.push(newUser)
      return newUser
    }
  }
}

If you create an executable schema based on this definition, you'll be able to send the following queries:

// Create executable schema
const executableSchema = makeExecutableSchema({
  typeDefs,
  resolvers
})

const orm = new Orm({executableSchema})

// Execute the `hello` query, returning all fields
orm.query.hello()

// Execute the `hello` query with a parameter
orm.query.hello({ name: 'John' })

// Execute the 'createUser' mutation
orm.mutation.createUser({ name: 'Joe' })

// Execute the 'allUsers' query, returning only the user names
orm.query.allUsers(null, { name })

API

constructor(options: OrmOptions): Orm

The Orm type has the following fields:

| Key | Required | Type | Default | Note | | --- | --- | --- | --- | --- | | executableSchema | Yes | GraphQLSchema | - | Instance of an executable GraphQL schema | | fragmentReplacements | No | FragmentReplacements | null | A list of GraphQL fragment definitions, specifying fields that are required for the resolver to function correctly |

query and mutation

query and mutation are public properties on your Orm instance. They both are of type Query and expose a number of auto-generated delegate resolver functions that are named after the fields on the Query and Mutation types in your GraphQL schema.

Each of these delegate resolvers in essence provides a convenience API for executing queries/mutations against your schema, so you don't have to spell out the full query/mutation from scratch. This is all handled by the delegate resolver function under the hood.

Delegate resolver have the following interface:

(args: any, info: GraphQLResolveInfo | string): Promise<T>

The input arguments are used as follows:

• args: An object carrying potential arguments for the query/mutation
• info: An object representing the selection set of the query/mutation, either expressed directly as a string or in the form of GraphQLResolveInfo (you can find more info about the GraphQLResolveInfo type here)

The generic type T corresponds to the type of the respective field.

request

The request method allows executing any GraphQL query/mutation against your schema. The functionality is identical to the auto-generated delegate resolves, but the API is more verbose as you need to spell out the full query/mutation.

Here is an example of how it can be used:

const query = `
  query ($userId: ID!){
    user(id: $userId) {
      id
      name
    }
  }
`

const variables = { userId: '123' }

orm.request(query, variables)
  .then(result => console.log(result))
// sample result:
// { "id": "abc", "name": "Sarah" }

Usage

• graphcool-binding uses supergraph-orm and adds functionality to it specific to Graphcool endpoints.