Skip to content

SeveralBrands/objectionjs-graphql

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

65 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

objectionjs-graphql

npm install

npm version downloads

Automatic GraphQL API generator for objection.js models.

Credit

This project is based on objection-graphql

To Do

  • Add support for custom GraphQl query builder (documentation)
  • Add support for custom jsonSchema attribute (documentation)
  • Improve cache layer

Usage

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.

Setup with HTTP (Express.js) package

    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 }))

Getting started

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.

Filters

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)

Special arguments

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.

Adding your own custom arguments

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();

Auto Generated JsonSchema

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.

Extending your schema with mutations

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();

Extending your schema with subscriptions

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();

Misc

defaultArgNames

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);

onQuery

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);
    });
});

setBuilderOptions

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.

Caching

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
    }
  }
}))