sql2gql v2.1.2

sql2gql

Opininated Sequelize to GraphQL bridge, extending out graphql-sequelize with dynamically exposing relationships and functions via queries and mutations. We rely heavily on the Sequelize API for definition of the model classes.

Requirements

• NodeJs >= 4
• Sequelize v3/v4
• graphql
• graphql-sequelize

Features

• Dynamic mapping of sequelize models and relationships to graphql for query and mutation.
• Exposing classMethods as mutation/query options.
• Permissions to restrict access to parts of the graphql schema on generation.
• Generation of subscriptions from sequelize hooks

API

Model

The model object is the bread and butter of the setup, it basically serves two purposes, creating the data model in sequelize and the graphql model.

Model.Override

Model.Expose

Model.Expose.Definition

This object is a HashObject which the key must match the function name targeted.

Model.Relationship

connect

This creates sequelize models and injects appropriate metadata for the createSchema function

import {connect} from "sql2gql";

createSchema

Generates a graphql schema from the metadata stored in the sequelize instance.

import {createSchema} from "sql2gql";

createSchema.options

Generates a graphql schema from the metadata stored in the sequelize instance.

Returns Object(GraphQLSchema)

createSchema.options.subscriptions

createSchema.options.permissions

hooks to constrain visibility of fields and functions will only hide elements by default if hook is defined,

GraphqlSchema

graphql-sequlize helpers

Query

query {
  models {
    modelName(defaultListArgs): GraphQLList<Model> {
      field
      relationship(args) {
        field
      }
    }
  }
  classMethods {
    modelName {
      functionName(params) {
        {definedModel}
      }
    }
  }
}

Mutation

mutation {
  models {
    modelName {
      create(input: modelDefinition) {
        field
      }
      update(where: SequelizeJSONType, input: modelDefinition) {
        field
      }
      classMethod(params) {
        field
      }
    }
  }
}

Subscription

Reference

subscription X {
  afterCreateTask {
    id,
    name
  }
  afterUpdateTask {
    id,
    name
  }
}

Example

Github Repo

import Sequelize from "sequelize";
import {connect, createSchema} from "sql2gql";
import expect from "expect";
import {
  graphql,
  GraphQLString,
  GraphQLNonNull,
  GraphQLInputObjectType,
  GraphQLObjectType,
  GraphQLInt,
} from "graphql";

const TaskModel = {
  name: "Task",
  define: {
    name: {
      type: Sequelize.STRING,
      allowNull: false,
      validate: {
        isAlphanumeric: {
          msg: "Your task name can only use letters and numbers",
        },
        len: {
          args: [1, 50],
          msg: "Your task name must be between 1 and 50 characters",
        },
      },
    },
    options: {
      type: Sequelize.STRING,
      allowNull: true,
    },
  },
  before(findOptions, args, context, info) {
    return findOptions;
  },
  after(result, args, context, info) {
    return result;
  },
  override: {
    options: {
      type: {
        name: "TaskOptions",
        fields: {
          hidden: {type: GraphQLString},
        },
      },
      output(result, args, context, info) {
        return JSON.parse(result.get("options"));
      },
      input(field, args, context, info) {
        return JSON.stringify(field);
      },
    },
  },
  relationships: [{
    type: "hasMany",
    model: "TaskItem",
    name: "items",
  }],
  expose: {
    classMethods: {
      mutations: {
        reverseName: {
          type: "Task",
          args: {
            input: {
              type: new GraphQLNonNull(new GraphQLInputObjectType({
                name: "TaskReverseNameInput",
                fields: {
                  amount: {type: new GraphQLNonNull(GraphQLInt)},
                },
              })),
            },
          },
        },
      },
      query: {
        getHiddenData: {
          type: new GraphQLObjectType({
            name: "TaskHiddenData",
            fields: () => ({
              hidden: {type: GraphQLString},
            }),
          }),
          args: {},
        },
        getHiddenData2: {
          type: new GraphQLObjectType({
            name: "TaskHiddenData2",
            fields: () => ({
              hidden: {type: GraphQLString},
            }),
          }),
          args: {},
        },
      },
    },
  },
  options: {
    tableName: "tasks",
    classMethods: {
      reverseName({input: {amount}}, context) {
        return {
          id: 1,
          name: `reverseName${amount}`,
        };
      },
      getHiddenData(args, context) {
        return {
          hidden: "Hi",
        };
      },
      getHiddenData2(args, context) {
        return {
          hidden: "Hi2",
        };
      },
    },
    hooks: {
      beforeFind(options) {
        return undefined;
      },
      beforeCreate(instance, options) {
        return undefined;
      },
      beforeUpdate(instance, options) {
        return undefined;
      },
      beforeDestroy(instance, options) {
        return undefined;
      },
    },
    indexes: [
      // {unique: true, fields: ["name"]},
    ],
    //instanceMethods: {}, //TODO: figure out a way to expose this on graphql
  },
};


const schemas = [TaskModel];

(async() => {
  let instance = new Sequelize("database", "username", "password", {
    dialect: "sqlite",
    logging: false
  });
  connect(schemas, instance, {}); // this populates the sequelize instance with the appropriate models and referential information for schema generation
  await instance.sync();

  const schema = await createSchema(instance); //creates graphql schema
  const mutation = `mutation {
    models {
      Task {
        create(input: {name: "item1", options: {hidden: "nowhere"}}) {
          id, 
          name
          options {
            hidden
          }
        }
      }
    }
  }`; // create item in database
  const mutationResult = await graphql(schema, mutation);
  expect(mutationResult.data.models.Task.create.options.hidden).toEqual("nowhere");
  const queryResult = await graphql(schema, "query { models { Task { id, name, options {hidden} } } }"); // retrieves information from database
  return expect(queryResult.data.models.Task[0].options.hidden).toEqual("nowhere");
})();

Permission Helper

The is a simple role base helper for hooking into the permission events for deny and allowing sections during schema generation based on roles provided.

/* 
  options = {
    defaultDeny: true
    defaults: {

    }
  }
  defaultPerm = {
    "fields": {
      "Task": {
        "options": "deny",
      },
    },
    "classMethods": {
      "User": {
        "login": "allow",
        "logout": "allow",
      },
    },
  };

  rules = {
    "admin": {
      "field": {
        "User": "allow",
      } 
      "model": "allow",
      "classMethods": {
        "User": {
          "login": "deny",
        },
      },
    },
    "user": {
      "mutation": "deny",
    },
  };

*/

const ruleSet = {
  "someone": "deny",
  "anyone": {
    "query": "allow",
    "model": {
      "Task": "allow",
    },
    "field": {
      "Task": {
        "name": "allow",
      },
    },
  },
};

const anyoneSchema = await createSchema(instance, {
  permission: permissionHelper("anyone", ruleSet)
});

const someoneSchema = await createSchema(instance, {
  permission: permissionHelper("someone", ruleSet)
});

ChangeLog

1.1.0

• delete mutations now return object that it has deleted instead of boolean - Breaking change from 1.0.0
• subscriptions are now supported, defaults will hook into afterCreate, afterUpdate, afterDestroy on the sequelize models
• added extend to options in createScheme for supporting unknown/future root variables
• set all functions to export to allow for anyone wanting to use the api directly

1.2.0

• changed before and after hooks on the model definition to include mutations, the arguments have been reduced to a single object - Breaking change from 1.1.0

1.2.1

• fixed before, after hooks arguments for mutations

1.2.2

• adding rootValue and context to the findOptions statement provided to sequelize. accessible from the hook beforeFind.
• updated base model before after hooks.

1.2.4

• updated override to allow scalar and enum types to be set as the field type directly

1.2.5

• added Instance Methods to the query field definition if exposed.

1.2.6

• exposed generated types via $sql2gql.types on the schema returned from connect

1.2.7

• Added field permission option

2.0.0

• Added subscription permission option
• added a simple role based permission helper
• fixed field permissions return value to be correct
• removed some let over debugging mechanics from 1.2.7
• updated package dependencies
• switch to the official graphql subscriptions mechanic in the test cases
• updated all the tests to match the jest version of expect
• implemented a basic role based permission helper.
• added checks for over aggressive permission handling
• added the default fields to the permission check
• dropping node support for anything lesser then current LTS aka compile target is currently v6.11.3

2.0.1

• total overcomplicated implementation for field filtering in permissions - now fixed.
• added a new permissions test

2.0.2

• added list types for all available models for instanceMethods, classMethods and schema.$sql2gql.types. format is "List<${modelName}>"

2.1.0

• BUGFIX #21 - Unable to use list types in for instanceMethods
• Breaking Change switch formatting from List to Object[] to be more consistent with javascript syntax

2.1.1

• Added model to parameters of override.input on updates

2.1.2

• Something went wrong with npm publish