@raynode/graphql-connector

Graphql Connector

This library is designed to easily connect a existing database system to the graphql ecosystem. It takes the types and models of the source system and maps them to GraphQL.

Usage

The connector needs to know 2 things to work:

• a ModelMapper to convert a Model from the source system into the GraphQL Connector Model-Type
• a TypeMapper to convert a Datatype of the source system into a GraphQLType

To see it in action you can look at the code for this example in the tests. This code will be kept up to date and be used as a test

@TODO: subscriptions are not in yet

First step, define a graphql-connector model mapper

import {
  createModelMapper,
} from 'graphql-connector'

// myModels is expected to be { user: DBUserModel, post: DBPostModel, comment: DBCommentModel }
type Models = typeof myModels

// myTypes is expected to be { DBIntType: any, DBStringType: any, ... }
type Types = typeof myTypes

// utility to check if some type is a list-type
const isListType = (type: myTypes.DBType): type is myTypes.DBListType => type instanceof myTypes.DBListType

// utility to resolve the final type of a type
const getFinalType = (type: myTypes.DBType) => (isListType(type) ? type.subtype : type)

// The modelMapper is responsible to convert a my-model into a graphql-connector model
// a graphql-connector model needs attributes, associations
// each association and attribute could be setup with an resolver here
const modelMapper = createModelMapper<myTypes.DBType, Models>((model, addAttribute, addAssociation) => {
  // to convert a my-model into a graphql-connector model, we need to tell the system all attributes and associations
  Object.keys(model.attributes).forEach(name => {
    const attribute = model.attributes[name]
    const type = getFinalType(attribute)
    const list = isListType(attribute)
    if (name !== 'id' && type instanceof myTypes.DBIDType)
      return addAssociation({
        list,
        model: type.source as any,
        name,
      })
    return addAttribute({
      list,
      name,
      type,
    })
  })
})

Next step is to create a type mapper to convert our my-types into GraphQLType

import { TypeMapper } from 'graphql-connector'
// this function tells the generator how to convert my-type into a GraphQLType
const typeMapper: TypeMapper<Types, Models> = ({ type }) => {
  if (type instanceof myTypes.DBIDType) return GraphQLID
  if (type instanceof myTypes.DBDateType) return DateType
  if (type instanceof myTypes.DBIntType) return GraphQLInt
  if (type instanceof myTypes.DBStringType) return GraphQLString
  throw new Error('invalid type: ' + typeof type)
}

The last step is to input the typeMapper and the modelMapper into the createBaseSchema function and use the result to generate a BaseSchema

// Generate a baseSchemaGenerator by providing the modelMapper and typeMapper
// here we could change other things, like the nameingStrategy
const baseSchemaGenerator = createBaseSchemaGenerator({
  modelMapper,
  typeMapper,
})

// apply all my-models to the generator
// the baseSchema will have all queryFields, mutationsFields and subscriptionFields
const baseSchema = baseSchemaGenerator(myModels)

Now we have generated all required queryFields, mutationFields and subscriptionFields. These now need to be converted to a GraphQLSchema, there is a utility function for it, but the step uses graphql code only.

// import { createSchema } from 'graphql-connector'
import {
  GraphQLObjectType,
  GraphQLSchema,
} from 'graphql'

export const createSchema = ({ queryFields, mutationFields }: BaseSchema) =>
  new GraphQLSchema({
    query: new GraphQLObjectType({
      name: 'Query',
      fields: queryFields,
    }),
    mutation: new GraphQLObjectType({
      name: 'Mutation',
      fields: mutationFields,
    }),
  })

const schema = createSchema(baseSchema)

This results in an SDL like:

type Comment implements Node {
  msg: String
  id: ID
  createdAt: Date
  lastUpdate: Date
  commentor: User
  Post: Post
}

type Comments implements List {
  nodes: [Comment!]!
  page: Page!
}

"""
A special custom Scalar type for Dates that converts to a ISO formatted string
"""
scalar Date

interface List {
  nodes: [Node!]!
  page: Page!
}

type Mutation {
  createUser: User
  updateUser: User
  deleteUsers: Users
  createPost: Post
  updatePost: Post
  deletePosts: Posts
  createComment: Comment
  updateComment: Comment
  deleteComments: Comments
}

interface Node {
  id: ID
}

type Page {
  limit: Int
  offset: Int
}

type Post implements Node {
  title: String
  text: String
  upvotes: Int
  id: ID
  createdAt: Date
  lastUpdate: Date
  author: User
  Comment: Comments
}

type Posts implements List {
  nodes: [Post!]!
  page: Page!
}

type Query {
  User: User
  Users: Users
  Post: Post
  Posts: Posts
  Comment: Comment
  Comments: Comments
}

type User implements Node {
  name: String
  email: String
  password: String
  id: ID
  createdAt: Date
  lastUpdate: Date
  Post: Posts
  Comment: Comments
}

type Users implements List {
  nodes: [User!]!
  page: Page!
}