graphql-compose-json
This is a plugin for graphql-compose, which generates GraphQLTypes from REST response or any JSON. It takes fields from object, determines their types and construct GraphQLObjectType with same shape.
Demo
We have a Live demo (source code repo) which shows how to build an API upon SWAPI using graphql-compose-json
.
Installation
npm install graphql graphql-compose graphql-compose-json --save
Modules graphql
, graphql-compose
, are located in peerDependencies
, so they should be installed explicitly in your app. They have global objects and should not have ability to be installed as submodule.
Example
You have a sample response object restApiResponse
which you can pass to graphql-compose-json
along with desired type name as your first argument and it will automatically generate a composed GraphQL type PersonTC
.
// person.js
import { composeWithJson, composeInputWithJson } from 'graphql-compose-json';
const restApiResponse = {
name: 'Anakin Skywalker',
birth_year: '41.9BBY',
gender: 'male',
mass: 77,
homeworld: 'https://swapi.co/api/planets/1/',
films: [
'https://swapi.co/api/films/5/',
'https://swapi.co/api/films/4/',
'https://swapi.co/api/films/6/',
],
species: ['https://swapi.co/api/species/1/'],
starships: [
'https://swapi.co/api/starships/59/',
'https://swapi.co/api/starships/65/',
'https://swapi.co/api/starships/39/',
],
};
export const PersonTC = composeWithJson('Person', restApiResponse);
export const PersonGraphQLType = PersonTC.getType(); // GraphQLObjectType
export const PersonITC = composeInputWithJson('PersonInput', restApiResponse);
export const PersonGraphQLInput = PersonITC.getType(); // GraphQLInputObjectType
Customization
You can write custom field configs directly to a field of your API response object via function (see mass
and starships_count
field):
import { composeWithJson } from 'graphql-compose-json';
const restApiResponse = {
name: 'Anakin Skywalker',
birth_year: '41.9BBY',
starships: [
'https://swapi.co/api/starships/59/',
'https://swapi.co/api/starships/65/',
'https://swapi.co/api/starships/39/',
],
mass: () => 'Int!', // by default JSON numbers coerced to Float, here we set up Int
starships_count: () => ({ // more granular field config with resolve function
type: 'Int',
resolve: source => source.starships.length,
}),
};
export const CustomPersonTC = composeWithJson('CustomPerson', restApiResponse);
export const CustomPersonGraphQLType = CustomPersonTC.getType();
Will be produced following GraphQL Type from upper shape:
const CustomPersonGraphQLType = new GraphQLObjectType({
name: 'CustomPerson',
fields: () => {
name: {
type: GraphQLString,
},
birth_year: {
type: GraphQLString,
},
starships: {
type: new GraphQLList(GraphQLString),
},
mass: {
type: GraphQLInt,
},
starships_count: {
type: GraphQLInt,
resolve: source => source.starships.length,
},
},
});
Schema building
Now when you have your type built, you may specify the schema and data fetching method:
// schema.js
import { GraphQLSchema, GraphQLObjectType, GraphQLNonNull, GraphQLInt } from 'graphql';
import fetch from 'node-fetch';
import { PersonTC } from './person';
const schema = new GraphQLSchema({
query: new GraphQLObjectType({
name: 'Query',
fields: {
person: {
type: PersonTC.getType(), // get GraphQL type from PersonTC
args: {
id: {
type: new GraphQLNonNull(GraphQLInt),
}
},
resolve: (_, args) =>
fetch(`https://swapi.co/api/people/${args.id}/`).then(r => r.json()),
},
},
}),
});
Or do the same via graphql-compose
:
import { SchemaComposer } from 'graphql-compose';
const schemaComposer = new SchemaComposer();
const PersonTC = composeWithJson('CustomPerson', restApiResponse, { schemaComposer });
schemaComposer.Query.addFields({
person: {
type: PersonTC,
args: {
id: `Int!`, // equals to `new GraphQLNonNull(GraphQLInt)`
},
resolve: (_, args) =>
fetch(`https://swapi.co/api/people/${args.id}/`).then(r => r.json()),
},
}
const schema = schemaComposer.buildSchema(); // returns GraphQLSchema
Building schema asynchronously
To build the schema at the runtime, you should rewrite the Schema.js
and insert there an async function which will return a promise:
export const buildAsyncSchema = async (): Promise<GraphQLSchema> => {
const url = `https://swapi.co/api/people/1`;
const data = await fetch(url);
const jsonData = await data.json();
const PeopleTC = composeWithJson('People', jsonData);
schemaComposer.Query.addFields({
person: {
type: PeopleTC,
args: {
id: 'Int!',
},
resolve: (_, args) => {
return fetch(`https://swapi.co/api/people/${args.id}/`).then(r => r.json());
},
},
});
const schema = schemaComposer.buildSchema();
return schema;
};
So, you can just import this function and tell to the express-graphql
that we are passing a promise:
import express from 'express';
import graphqlHTTP from 'express-graphql';
import { buildAsyncSchema } from './Schema';
const PORT = 4000;
const app = express();
const promiseSchema = buildAsyncSchema();
app.use(
'/graphql',
graphqlHTTP(async req => ({
schema: await promiseSchema,
graphiql: true,
context: req,
}))
);
graphql-compose
Further customization with Moreover, graphql-compose
allows you to pass pre-defined resolvers of other types to the response object and customize them:
const restApiResponse = {
name: 'Anakin Skywalker',
starships: () =>
StarshipTC.getResolver('findByUrlList') // get some standard resolver
.wrapResolve(next => rp => { // wrap with additional logic
const starshipsUrls = rp.source.starships;
rp.args.urls = starshipsUrls; // populate `urls` arg from source
return next(rp); // call standard resolver
})
.removeArg('urls'), // remove `urls` args from resolver and schema
};
}
const PersonTC = composeWithJson('Person', restApiResponse);
In case you need to separate custom field definition from your response object there are graphql-compose
methods made for this purpose.
If you want to specify new fields of your type, simply use the addFields
method of graphql-compose
:
PersonTC.addFields({
vehicles_count: {
type: 'Int!', // equals to `new GraphQLNonNull(GraphQLInt)`
resolve: (source) => source.vehicles.length,
},
});
When you want to create a relation with another type simply use addRelation
method of graphql-compose
:
PersonTC.addRelation('filmObjects', {
resolver: () => FilmTC.getResolver('findByUrlList'),
prepareArgs: {
urls: source => source.films,
},
});
graphql-compose
provides a vast variety of methods for fields
and resolvers
(aka field configs in vanilla GraphQL
) management of GraphQL
types. To learn more visit graphql-compose repo.