sequelize-graphql

Opinionated zero dependency library to sync Sequelize and GraphQL.

[!WARNING] The library is in WIP until v2 is released. Issues and PRs are welcomed.

Key features

• Define your model in one place and have the Sequelize model as well as the GraphQL type auto-generated.
• GraphQL oriented (e.g A model must have a primary key named id wich is by default a UUID mapped to a GraphQLID).
• Association handling (e.g An hasMany association will be exposed as a pagination).
• Pagination utility which is orderable, filterable, and type safe.
• N+1 query handling. Caching and batching is automatically handled.
• Enums handling.
• Sequelize utilities.
• GraphQL utilities.

Getting Started

Install sequelize-graphql from npm

With npm:

1npm install --save @sequelize-graphql/core sequelize graphql dataloader

or using yarn:

1yarn add @sequelize-graphql/core sequelize graphql dataloader

See Peer dependencies breakdown for more information.

Setup the context and you are good to go:

1import { makeContext } from '@sequelize-graphql/core';
2
3// Apollo Server example
4const { url } = await startStandaloneServer(server, {
5  context: async ({ req, res }) => ({
6    ...makeContext(), // An object containing everyting sequelize-graphql needs to work properly.
7    authToken: req.headers.authorization, // Stuff you want to place in the context like an auth token.
8  }),
9});

Usage

One can easily define a model like so:

1import type { ForeignKey } from 'sequelize';
2import type { IdType, InferModelAttributesWithDefaults } from '@sequelize-graphql/core';
3
4import { GraphQLNonNull, GraphQLString } from 'graphql';
5import { Model, STRING, ID, ENUM } from '@sequelize-graphql/core';
6import sequelize from '@db/index';
7import { Author, Rating } from '@models/index';
8
9export enum Genre {
10  Action = 'Action',
11  Fantasy = 'Fantasy',
12  Horror = 'Horror',
13}
14
15export const GenreEnum = ENUM({ name: 'Genre', values: Genre });
16
17export interface BookModel extends InferModelAttributesWithDefaults<BookModel> {
18  title: string;
19  genre: Genre;
20
21  authorId: ForeignKey<IdType>; // Auto-added by the belongsTo association
22}
23
24const Book: Model<BookModel> = new Model({
25  name: 'Book',
26  columns: {
27    title: { type: STRING, allowNull: false, exposed: true },
28    genre: { type: GenreEnum, defaultValue: Genre.Action, exposed: true },
29  },
30  fields: {
31    fullTitle: {
32      type: new GraphQLNonNull(GraphQLString),
33      async resolve(book, args, ctx) {
34        const { authorId, title } = book;
35        const author = await Author.ensureExistence(authorId, { ctx });
36        return `${title} by ${author.name}`;
37      },
38    },
39  },
40  associations: () => ({
41    author: {
42      model: Author,
43      type: 'belongsTo',
44      exposed: true,
45    },
46
47    ratings: {
48      model: Rating,
49      type: 'hasMany',
50      exposed: true,
51    },
52  }),
53  timestamps: true,
54  sequelize,
55});

Here is the GraphQL type that will be generated:

1type Book {
2  id: ID!
3  createdAt: Date!
4  updatedAt: Date!
5  title: String!
6  genre: Genre
7  author: Author
8  ratings(offset: Int, limit: Int, order: [RatingOrderBy!], filters: RatingFilters): RatingOffsetConnection!
9  fullTitle: String!
10}

The lib comes with a set of utilities to generate queries and mutations for your models.
Query:

1export default new GraphQLObjectType({
2  name: 'Query',
3  fields: {
4    ...exposeModel(Book, {
5      findById: 'book',
6      findByIds: false,
7      pagination: 'books',
8    }),
9  }
10});

1type Query {
2  book(id: ID!): Book!
3  books(offset: Int, limit: Int, order: [BookOrderBy!], filters: BookFilters): BookOffsetConnection!
4}

Mutation:

1import { GraphQLID, GraphQLNonNull, GraphQLString } from 'graphql';
2import { genModelMutations } from '@sequelize-graphql/core';
3import { Book, Author, GenreEnum } from '@models/index';
4
5export default genModelMutations(Book, {
6  create: {
7    args: {
8      authorId: { type: new GraphQLNonNull(GraphQLID) },
9      title: { type: new GraphQLNonNull(GraphQLString) },
10      genre: { type: new GraphQLNonNull(GenreEnum.gqlType) },
11    },
12    async resolve(_, args, ctx) {
13      const { authorId, title, genre } = args;
14      await Author.ensureExistence(authorId, { ctx });
15      return Book.model.create({ authorId, title, genre });
16    },
17  },
18
19  update: {
20    args: {
21      title: { type: GraphQLString },
22      genre: { type: GenreEnum.gqlType },
23    },
24    async resolve(book, args, ctx) {
25      const { title, genre } = args;
26      return book.update({ title, genre });
27    },
28  },
29
30  delete: true,
31});

1type BookMutation {
2  create(input: BookCreateInput!): Book!
3  update(id: ID!, input: BookUpdateInput!): Book!
4  delete(id: ID!): Boolean!
5}

Example

A simple project running sequelize-graphql:
https://github.com/BaptisteMartinet/sequelize-graphql-example