Automatic GraphQL API generator for objection.js models.
This project is based on objection-graphql
- Add support for custom GraphQl query builder (documentation)
- Add support for custom jsonSchema attribute (documentation)
- Improve cache layer
objectionjs-graphql automatically generates a GraphQL schema
for objection.js models. The schema is created based on the jsonSchema
and relationMappings properties of the models, mainly its
use withGraphFetched to
build and fetch the relation relationMappings query.
It creates a rich set of filter arguments for the
relations and provides a simple way to add custom filters.
The following example creates a schema for three models Person, Movie, and Review and executes a GraphQL query:
const graphql = require('graphql').graphql;
const graphQlBuilder = require('objectionjs-graphql').builder;
// Objection.js models.
const Movie = require('./models/Movie');
const Person = require('./models/Person');
const Review = require('./models/Review');
// This is all you need to do to generate the schema.
const graphQlSchema = async() => {
const builder = await graphQlBuilder()
.allModels([Movie, Person, Review]);
return builder.build();
};
// Execute a GraphQL query.
graphql(
graphQlSchema,
`
{
movies(nameLike: "%erminato%", range: [0, 2], orderBy: releaseDate) {
name
releaseDate
actors(gender: Male, ageLte: 100, orderBy: firstName) {
id
firstName
age
}
reviews(starsIn: [3, 4, 5], orderByDesc: stars) {
title
text
stars
reviewer {
firstName
}
}
}
}
`,
).then((result) => {
console.log(result.data.movies);
});The example query used some of the many default filter arguments. For example the nameLike: "%erminato%"
the filter is mapped into a where clause where name like '%erminato%'. Similarly the ageLte: 100 is mapped into
a where age <= 100 clause. In addition to the property filters, there are some special arguments like orderBy and
range. Check out this table for a complete list of filter arguments available by default.
const { graphQlSchema } = require('./graphql') // your graphql schema
const graphQlSchemaResult = await graphQlSchema()
const { createHandler } = require('graphql-http/lib/use/express')
app.use('/graphql', (req, res, next) => {
res.set('Content-Security-Policy', 'default-src *; style-src \'self\' http://* \'unsafe-inline\'; script-src \'self\' http://* \'unsafe-inline\' \'unsafe-eval\'')
next()
}, createHandler({
schema: graphQlSchemaResult, context: (req, res, params) => ({ req, res, params })
}))express-graphql (deprecated)
const { graphQlSchema } = require('./graphql') // your graphql schema
const graphQlSchemaResult = await graphQlSchema()
const { graphqlHTTP } = require('express-graphql')
app.use('/graphql', (req, res, next) => {
res.set('Content-Security-Policy', 'default-src *; style-src \'self\' http://* \'unsafe-inline\'; script-src \'self\' http://* \'unsafe-inline\' \'unsafe-eval\'')
next()
}, graphqlHTTP({ schema: graphQlSchemaResult }))If you are already using objection.js the example in the usage section is all you need to get started. If you are unfamiliar with objection.js you should try our example project.
| argument | type | action |
|---|---|---|
prop: value |
property type | prop = value |
propEq: value |
property type | prop = value |
propGt: value |
property type | prop > value |
propGte: value |
property type | prop >= value |
propLt: value |
property type | prop < value |
propLte: value |
property type | prop <= value |
propLike: value |
string | prop LIKE value |
propIsNull: value |
boolean | prop IS NULL or prop IS NOT NULL |
propIn: value |
Array | prop IN value |
propNotIn: value |
Array | prop NOT IN value |
propLikeNoCase: value |
string | lower(prop) LIKE lower(value) |
| argument | action |
|---|---|
orderBy: prop |
Order the result by some property |
orderByDesc: prop |
Order the result by some property in descending order |
range: [start, end] |
Select a range. Doesn't work for relations! |
limit: prop |
Select a given number of records. |
offset: prop |
Skip a given number of records. |
Here's an example of how you could implement a NotEq filter for primitive values:
const graphql = require('graphql');
const graphQlSchema = graphQlBuilder()
.model(Movie)
.model(Person)
.model(Review)
.argFactory((fields, modelClass) => {
const args = {};
_.forOwn(fields, (field, propName) => {
// Skip all nonprimitive fields.
if (
field.type instanceof graphql.GraphQLObjectType ||
field.type instanceof graphql.GraphQLList
) {
return;
}
args[propName + 'NotEq'] = {
// For our filter the type of value needs to be
// the same as the type of field.
type: field.type,
query: (query, value) => {
// query is an objection.js QueryBuilder instance.
query.where(propName, '<>', value);
},
};
});
return args;
})
.build();This package will auto-generate the jsonSchema for you if you don't have one.
It will use the model's table schema to generate the structure of the jsonSchema.
Often you need to provide mutations in your GraphQL schema. At the same time, mutations can be quite opinionated with
side effects and complex business logic, so plain CUD implementation is not always a good idea.
Therefore, we provide a method extendWithMutations which allows you to extend the generated query schema with
mutations. You can provide a root GraphQLObjectType or a function as the first argument for this method.
Function in this case plays as a strategy that receives the current builder as a first argument and
returns GraphQLObjectType.
//...
const personType = new GraphQLObjectType({
name: 'PersonType',
description: 'Use this object to create a new person',
fields: () => ({
id: {
type: new GraphQLNonNull(GraphQLInt),
description: 'Id',
},
firstName: {
type: new GraphQLNonNull(GraphQLString),
description: 'First Name',
},
lastName: {
type: new GraphQLNonNull(GraphQLString),
description: 'Last Name',
},
}),
});
const createPersonInputType = new GraphQLInputObjectType({
name: 'CreatePersonType',
description: 'Person',
fields: () => ({
firstName: {
type: new GraphQLNonNull(GraphQLString),
description: 'First Name',
},
lastName: {
type: new GraphQLNonNull(GraphQLString),
description: 'Last Name',
},
}),
});
const mutationType = new GraphQLObjectType({
name: 'RootMutationType',
description: 'Domain API actions',
fields: () => ({
createPerson: {
description: 'Creates a new person',
type: personType,
args: {
input: { type: new GraphQLNonNull(createPersonInputType) },
},
resolve: (root, inputPerson) => {
const { firstName, lastName } = inputPerson.input;
return {
id: 1,
firstName,
lastName,
};
},
},
}),
});
//Here you can use a GraphQLObjectType or function as an argument for extendWithMutations
schema = mainModule
.builder()
.model(Person)
.extendWithMutations(mutationType)
.build();When you want to implement a real-time behavior in your app like push notifications, you basically have two options in GraphQl: subscriptions and live queries. The first approach focuses on events and granular control over updates, while the other is based on smart live queries, where most real-time magic is hidden from the client. We'd like to stick with the first approach since there are some decent implementations out there like graphql-subscriptions by Apollo.
The implementation is similar to the mutations extension point: you've got an extendWithSubscriptions method where you
can pass the root GraphQLObjectType or a function that can behave as a strategy that receives the current builder as
an argument.
//...
import { PubSub } from 'graphql-subscriptions';
const pubsub = new PubSub();
//...
const personType = new GraphQLObjectType({
name: 'PersonType',
description: 'Person',
fields: () => ({
id: {
type: new GraphQLNonNull(GraphQLInt),
description: 'First Name',
},
firstName: {
type: new GraphQLNonNull(GraphQLString),
description: 'First Name',
},
lastName: {
type: new GraphQLNonNull(GraphQLString),
description: 'Last Name',
},
}),
});
const subscriptionType = new GraphQLObjectType({
name: 'RootSubscriptionType',
description: 'Domain subscriptions',
fields: () => ({
personCreated: {
description: 'A new person created',
type: personType,
resolve: (payload: any) => payload,
subscribe: () => pubsub.asyncIterator('PERSON_CREATED'),
},
}),
});
//Here you can use a GraphQLObjectType or function as an argument for extendWithSubscriptions
schema = mainModule
.builder()
.model(Person)
.extendWithSubscriptions(subscriptionType)
.build();You can change the default filter suffixes and special filter names using the defaultArgNames method:
const graphQlSchema = graphQlBuilder()
.model(Movie)
.model(Person)
.model(Review)
.defaultArgNames({
eq: '_eq',
gt: '_gt',
gte: '_gte',
lt: '_lt',
lte: '_lte',
like: '_like',
isNull: '_is_null',
likeNoCase: '_like_no_case',
in: '_in',
notIn: '_not_in',
orderBy: 'order_by',
orderByDesc: 'order_by_desc',
range: 'range',
limit: 'limit',
offset: 'offset',
})
.build();Now you would have myProp_lt: value instead of the default myPropLt: value.
By default, the model names are pluralized by adding an s to the end of the caramelized table name.
You can set a custom plural and singular names for the root fields like so:
const graphQlSchema = graphQlBuilder()
.model(Movie)
.model(Person, {
listFieldName: 'people',
fieldName: 'person',
})
.model(Review);You can modify the root query by passing an object with onQuery method as the third argument for graphql method:
const graphQlSchema = graphQlBuilder()
.model(Movie)
.model(Person)
.model(Review)
.build();
expressApp.get('/graphql', (req, res, next) => {
graphql(graphQlSchema, req.query.graph, {
// builder is an objection.js query builder.
onQuery(builder) {
// You can for example store the logged in user to builder context
// so that it can be accessed from model hooks.
builder.mergeContext({
user: req.user,
});
// Or change the eager fetching algorithm.
builder.eagerAlgorithm(Model.JoinEagerAlgorithm);
},
})
.then((result) => {
res.send(result);
})
.catch((err) => {
next(err);
});
});Allows you to customize Objection query builder behavior. For instance, you can pass { skipUndefined: true } as an
options argument. So, each time the builder is called, it will be called with skipUndefined enabled.
This can be useful when you use graphql-tools schema stitching.
We add a cache layer to the GraphQl builder. This is useful when you have a lot of queries that are similar. You can enable the cache by passing a cache object to the builder.
Specifying Cache options when building the GraphQL schema is not necessary, but it can drastically improve performance
GraphQL Caching options are: host, port, redisKeyPrefix, timeout
host and port specify the host and port of your Redis connection
redisKeyPrefix is a prefix for all the cached Redis keys, the default value is 'gqlCache'
timeout specifies the age of each cached Redis key in seconds, and defaults to 1 hour, you might need to change this
value in case your system often faces data updates.
If you want to skip caching for testing purposes while still maintaining your cache layer, you can provide a skipCache
flag to disable caching for specific requests inside your request parameters or in the queryString, this must be
configured in your createHandler express middleware.
const graphql = require('graphql').graphql;
const graphQlBuilder = require('objectionjs-graphql').builder;
// Objection.js models.
const Movie = require('./models/Movie');
const Person = require('./models/Person');
const Review = require('./models/Review');
const graphQlSchema = async() => {
const builder = await graphQlBuilder({
// Builder options, currently only 'redis' is available
redis: {
host: 'localhost',
port: 6379,
redisKeyPrefix: 'gqlCache',
cacheTimeout: 10
}
}
).allModels([Movie, Person, Review]);
return builder.build();
};
// To skip the cache layer, assuming "skipCache" is sent in the query string
app.use('/graphql', (req, res, next) => {
res.set('Content-Security-Policy', 'default-src *; style-src \'self\' http://* \'unsafe-inline\'; script-src \'self\' http://* \'unsafe-inline\' \'unsafe-eval\'')
next()
}, createHandler({
schema: graphQlSchemaResult, context: (req, res, params) => {
return {
req,
res: {
...res,
skipCache: (req.raw.query['skipCache'] === 'true')
},
params
}
}
}))