Glues Bits and Pieces Of GraphQL Schemas & Resolvers Together
Make your code more readable and understandable by breaking down your monolithic GraphQL schema and resolver into smaller domain models. SchemaGlue.js will help glueing them back together.
SchemaGlue.js is designed specifically for building GraphQL schema using the awesome Apollo's graphql-tools.js.
Without SchemaGlue - Stuck With a Monolithic Schema
- src/
|__ schema.js
- index.js
- package.json
With SchemaGlue - Structure Your Schema At Will
- src/
|__ graphql/
|__ product/
| |__ schema.js
| |__ resolver.js
|
|__ variant/
|__ schema.js
|__ resolver.js
- index.js
- package.json
npm install schemaglue --save
const { glue } = require('schemaglue')
// This will look for any js files under the 'src/graphql' folder that
// comply to a certain convention described below. Those files describe
// bits and pieces of the GraphQL schema and resolver that schemaglue will
// reassemble into a single 'schema' string and 'resolver' object.
const options = {
ignore: '**/somefileyoudonotwant.js'
}
const { schema, resolver } = glue('src/graphql', options)
NOTE: The following example assumes this project is hosted on Google Cloud Functions (Google serverless solution), but it is easily applicable to any other projects that uses Apollo's graphql-tools.js. If you want to know more about hosting GraphQL APIs on Google Cloud Functions or Firebase (AWS Lambda coming soon), check out those 2 projects:
- webfunc: An assistant to easily create & deploy Google Cloud Functions project.
- graphql-serverless: A GraphQL plugin for webfunc that also exposes a GraphiQL front-end.
Project Structure Example
- src/
|__ schema.js
- index.js
- package.json
Where the schema.js file would contain the entire GraphQl schema and resolver definition:
// src/schema.js
const { makeExecutableSchema } = require('graphql-tools')
const _ = require('lodash')
const httpError = require('http-errors')
const schema = `
type Product {
id: ID!
name: String!
shortDescription: String
}
type Variant {
id: ID!
name: String!
shortDescription: String
}
type Query {
# ### GET products
#
# _Arguments_
# - **id**: Product's id (optional)
products(id: Int): [Product]
# ### GET variants
#
# _Arguments_
# - **id**: Variant's id (optional)
variants(id: Int): [Variant]
}
`
const productMocks = [{ id: 1, name: 'Product A', shortDescription: 'First product.' }, { id: 2, name: 'Product B', shortDescription: 'Second product.' }]
const productResolver = {
Query: {
products(root, { id }, context) {
const results = id ? _(productMocks).filter(p => p.id == id) : productMocks
if (results)
return results
else
throw httpError(404, `Product with id ${id} does not exist.`)
}
}
}
const variantMocks = [{ id: 1, name: 'Variant A', shortDescription: 'First variant.' }, { id: 2, name: 'Variant B', shortDescription: 'Second variant.' }]
const variantResolver = {
Query: {
variants(root, { id }, context) {
const results = id ? _(variantMocks).filter(p => p.id == id) : variantMocks
if (results)
return results
else
throw httpError(404, `Variant with id ${id} does not exist.`)
}
}
}
const executableSchema = makeExecutableSchema({
typeDefs: schema,
resolvers: _.merge(productResolver, variantResolver)
})
module.exports = {
executableSchema
}
// index.js
const { HttpHandler } = require('graphql-serverless')
const { serveHttp, app } = require('webfunc')
const { executableSchema } = require('./src/schema')
const graphqlOptions = {
schema: executableSchema,
graphiql: true,
endpointURL: "/graphiql"
}
app.use(new HttpHandler(graphqlOptions))
exports.main = serveHttp(app.resolve({ path: '/', handlerId: 'graphql' }))
Project Structure Example
- src/
|__ graphql/
|__ product/
| |__ schema.js
| |__ resolver.js
|
|__ variant/
|__ schema.js
|__ resolver.js
- index.js
- package.json
This is just one example of how to structure the schema and resolver. schemaglue looks for all js files under a specific path. That specific path can be set up in 3 different ways:
- Programmatically:
const { schema, resolver } = glue('src/graphql')
- Using a appconfig.json file. Set up the path as follow:
{ "graphql": { "schema": "src/graphql" } }
- Default value is 'schema'. That means that if no value is set in 1 or 2, then this default folder is used.
Js files following the following conventions will be extracted by schemaglue to rebuild the GraphQL schema and resolver from the example above:
// src/graphql/product/schema.js
exports.schema = `
type Product {
id: ID!
name: String!
shortDescription: String
}
`
// Notice that we have omitted to wrap the above with 'type Query { }'
exports.query = `
# ### GET products
#
# _Arguments_
# - **id**: Product's id (optional)
products(id: Int): [Product]
`
// We could also add the same for mutation and subscription:
// exports.mutation = `...`
//
// exports.subscription = `...`
// src/graphql/product/resolver.js
const httpError = require('http-errors')
const productMocks = [{ id: 1, name: 'Product A', shortDescription: 'First product.' }, { id: 2, name: 'Product B', shortDescription: 'Second product.' }]
exports.resolver = {
Query: {
products(root, { id }, context) {
const results = id ? productMocks.filter(p => p.id == id) : productMocks
if (results)
return results
else
throw httpError(404, `Product with id ${id} does not exist.`)
}
}
// Add Mutation or Subscription here as well:
// Mutation: { ... }
// Subscription: { ... }
}
// src/graphql/variant/schema.js
exports.schema = `
type Variant {
id: ID!
name: String!
shortDescription: String
}
`
// Notice that we have omitted to wrap the above with 'type Query { }'
exports.query = `
# ### GET variants
#
# _Arguments_
# - **id**: Variant's id (optional)
variants(id: Int): [Variant]
`
// We could also add the same for mutation and subscription:
// exports.mutation = `...`
//
// exports.subscription = `...`
// src/graphql/variant/resolver.js
const httpError = require('http-errors')
const variantMocks = [{ id: 1, name: 'Variant A', shortDescription: 'First variant.' }, { id: 2, name: 'Variant B', shortDescription: 'Second variant.' }]
exports.resolver = {
Query: {
variants(root, { id }, context) {
const results = id ? variantMocks.filter(p => p.id == id) : variantMocks
if (results)
return results
else
throw httpError(404, `Variant with id ${id} does not exist.`)
}
}
// Add Mutation or Subscription here as well:
// Mutation: { ... }
// Subscription: { ... }
}
// index.js
const { HttpHandler } = require('graphql-serverless')
const { serveHttp, app } = require('webfunc')
const { makeExecutableSchema } = require('graphql-tools')
const { glue } = require('schemaglue')
const { schema, resolver } = glue('src/graphql')
const executableSchema = makeExecutableSchema({
typeDefs: schema,
resolvers: resolver
})
const graphqlOptions = {
schema: executableSchema,
graphiql: true,
endpointURL: "/graphiql"
}
app.use(new HttpHandler(graphqlOptions))
exports.main = serveHttp(app.resolve({ path: '/', handlerId: 'graphql' }))
Notice that the path where the graphql schemas are located has been explicitely defined ('src/graphql'). This variable is optional and could have been defined in an appconfig.json file instead. Simply add that file at the root of the project. Example:
{ "graphql": { "schema": "src/graphql" } }
If this property is not setup, or if no appconfig.json has been defined, then schemaglue assumes that all the schema and resolver definitions are located under a ./schema/ folder. If neither the appconfig.json file nor the schema folder are defined, then an exception will be throwned by the glue method.
In some cases, you might want to ignore some specific files under the schema folder (by default, SchemaGlue will take into account all .js files). SchemaGlue adds support to ignore files or folders using globbing:
const { schema, resolver } = glue('./src/graphql', { ignore: '**/somefile.js' })
This will take into account all .js files under the folder ./src/graphql, excluding all somefile.js files. The ignore property supports both a single string or an array of strings.
// Ignore more than 1 specific .js file
const { schema:schema1 } = glue('./src/graphql', { ignore: ['**/somefile.js', '**/someotherfile.js'] })
// Ignore all files under the ./src/graphql/variant folder
const { schema:schema1 } = glue('./src/graphql', { ignore: 'variant/**' })
Using the appconfig.json file:
{
"graphql": {
"schema": "src/graphql",
"ignore": ["**/somefile.js", "**/someotherfile.js"]
}
}
Unions & Interfaces
If you're not familiar with this concept, check out this great article GraphQL Tour: Interfaces and Unions.
In our case, we're interested is knowing how to structure our code with unions or interfaces. If your schema is small, I would recommend to manage your unions and intefaces definitions inside a single schema.js file per model:
- src/
|__ graphql/
|__ product/
| |__ schema.js
| |__ resolver.js
|
|__ variant/
|__ schema.js
|__ resolver.js
- index.js
- package.json
Let's take the schema.js and resolver.js under src/graphql/product/ as an example:
schema.js
exports.schema = `
union Product = Bicycle | Racket
type Bicycle {
id: ID!
brand: String!
wheels: Int!
}
type Racket {
id: ID!
brand: String!
sportType: SportType!
}
enum SportType {
TENNIS
SQUASH
}
`
// Notice that we have omitted to wrap the above with 'type Query { }'
exports.query = `
# ### GET products
#
# _Arguments_
# - **id**: Product's id (optional)
products(id: Int): [Product]
`
resolver.js
const httpError = require('http-errors')
const productMocks = [{
id: 1,
brand: 'Giant',
wheels: 2
},{
id: 2,
brand: 'Prince',
sportType: 'TENNIS'
}]
exports.resolver = {
Query: {
products(root, { id }, context) {
const results = id ? productMocks.filter(p => p.id == id) : productMocks
if (results.length > 0)
return results
else
throw httpError(404, `Product with id ${id} does not exist.`)
}
},
Product: {
__resolveType(obj, context, info) {
return obj.wheels ? 'Bicycle' :
obj.sportType ? 'Racket' : null
}
}
}
Notice you need to define a resolveType method for the Product type under the exports.resolver
When your schema becomes to big or too complex to manage in a single file, then nothing prevents you to break it down in as many pieces as you want. That's the all point of using schemaglue. Let's imagine that for whatever reasons, we want to isolate in its own file all the logic and definition of the unions for the Product model. We could refactor the code above as follow:
- src/
|__ graphql/
|__ product/
| |__ schema.js
| |__ resolver.js
| |__ union.js
|
|__ variant/
|__ schema.js
|__ resolver.js
- index.js
- package.json
where the union.js file is as follow:
exports.schema = `
union Product = Bicycle | Racket
`
exports.resolver = {
Product: {
__resolveType(obj, context, info) {
return obj.wheels ? 'Bicycle' :
obj.sportType ? 'Racket' : null
}
}
}
We are Neap, an Australian Technology consultancy powering the startup ecosystem in Sydney. We simply love building Tech and also meeting new people, so don't hesitate to connect with us at https://neap.co.
Our other open-sourced projects:
- webfunc: Write code for serverless similar to Express once, deploy everywhere.
- now-flow: Automate your Zeit Now Deployments.
- graphql-serverless: GraphQL (incl. a GraphiQL interface) middleware for webfunc.
- schemaglue: Naturally breaks down your monolithic graphql schema into bits and pieces and then glue them back together.
- graphql-s2s: Add GraphQL Schema support for type inheritance, generic typing, metadata decoration. Transpile the enriched GraphQL string schema into the standard string schema understood by graphql.js and the Apollo server client.
- react-native-game-engine: A lightweight game engine for react native.
- react-native-game-engine-handbook: A React Native app showcasing some examples using react-native-game-engine.
- aws-cloudwatch-logger: Promise based logger for AWS CloudWatch LogStream.
Copyright (c) 2018, Neap Pty Ltd. All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
- Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
- Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
- Neither the name of Neap Pty Ltd nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL NEAP PTY LTD BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.