graphcraft

    1.0.0-beta.21 • Public • Published

    GraphCraft

    npm version dependencies devdependencies Build Status

    Rapildy build and extend GraphQL API based on Sequelize models. This library helps you focus on business logic while taking care of GraphQL schema automatically. https://almost-full-stack.github.io/graphcraft/

    If you are updating from a previous version to 1.0 read notes at the end to fix breaking changes it will cause.

    Installation

    npm install graphcraft

    Prerequisites

    This package assumes you have graphql and sequelize already installed (both packages are declared as peerDependencies).

    This library uses two set of configurations, Library Options and Model Options.

    Library Options

    These options are defined globally and are applied throughout schema and all models.

    /**
     * naming convention for mutations/queries and types.
     * {name} = Model Name or type name
     * {type} = Get | Create | Update | Delete
     * {bulk} = Bulk for bulk operations only
     * */
       
    naming: {
      pascalCase: true, // applied everywhere
      queries: '{name}', // applied to auto generated queries
      mutations: '{name}{type}{bulk}', // applied to auto generated mutations
      input: '{name}', // applied to all input types
      rootQueries: 'RootQueries',
      rootMutations: 'RootMutations',
      // {type} and {bulk} will be replaced with one of the following
      type: {
        create: 'Create',
        update: 'Update',
        delete: 'Delete',
        get: '',
        bulk: 'Bulk'
      }
    }
    // default limit to be applied on find queries.
    limits: {
      default: 50,
      max: 100 // maximum allowed limit. use 0 for unlimited
    },
    // nested objects can be passed and will be mutated automatically. Only hasMany and belongsTo relation supported.
    nestedMutations: true, // doesn't work with add bulk mutation
    /**
     * update modes when sending nested association objects
     * UPDATE_ONLY > update only incoming records
     * UPDATE_ADD > update existing records and add new ones i.e [{id: 1, name: 'test'}, {name: 'test2'}] record[0] will be updated and record[1] will be added
     * UPDATE_ADD_DELETE > not recommended: update existing records, add new ones and delete non-existent records i.e [{id: 1, name: 'test'}, {name: 'test2'}] record[0] will be updated, record[1] will be added, anything else will be deleted
     * MIXED > i.e [{id: 1, name: 'test'}, {id:2}, {name: 'test2'}], record[0] will be updated, record[1] will be deleted and record[2] will be added
     * IGNORE > ignore nested update
     */
     
    nestedUpdateMode: 'MIXED',
    // applied globaly on both auto-generated and custom queries/mutations.
    // only specified queries/ and mutations would be exposed via api
    exposeOnly: {
      queries: [], // ['Product'] this will only generate Product query
      mutations: [] // ['ProductUpdate'] this will only generate ProductUpdate mutation
    },
    // these models will be excluded from graphql schema
    exclude: [], // ['Product'] this will exclude all queries/mutations for Product model.
    // include these arguments to all queries/mutations
    includeArguments: {}, // {'scopeId': 'int'} this will add scopeId in arguments for all queries and mutations
    // enabled/disable dataloader for nested queries
    dataloader: false, // use dataloader for queries. Uses dataloader-sequelize
    // mutations are run inside transactions. Transactions are accessible in extend hook.
    transactionedMutations: true,
    // generic or those types/queries/mutations which are not model specific
    // custom graphql types
    types: {},
    // custom queries
    queries: {},
    // custom mutations
    mutations: {},
    // data, source, args, context, info are passed as function arguments
    // executes after all queries/mutations
    logger() {
      return Promise.resolve();
    },
    // your custom authorizer
    // executes before all queries/mutations
    authorizer() {
      return Promise.resolve();
    },
    // these error messages are used when certain exceptions are thrown
    // must be used with errorHandler function exposed via library
    errorHandler: {
      'ETIMEDOUT': { statusCode: 503 }
    }
    const options = {
      exclude: ["payments"],
      authorizer: function authorizer(source, args, context, info) {
        const { fieldName } = info; // resource name
     
        return Promise.resolve();
      }
    };
     
    const { generateSchema } = require("graphcraft")(options);

    Model Options

    Following options are model specific options, must be accessible via model.graphql property.

    // manipulate your model attributes
    attributes: {
    // list attributes which are to be ignored in Model Input
      exclude: [], // ['id', 'createdAt'], these fields will be excluded from GraphQL Schema
    // attributes in key:type format which are to be included in Model Input
      include: {}, // {'customKey': 'string'} this extra field will be added in GraphQL schema
    },
    // scope usage is highy recommended.
    // common scope to be applied on all find/update/destroy operations
    scopes: null, 
    // 'scopes': ['scope', 'args.scopeId'] this will pass value of args.scopeId to model scope
    // values can be either picked from args or context
    // rename default queries/mutations to specified custom name
    alias: {},
    // {'fetch': 'productGet', 'create': 'productAdd', 'update': ..., 'destroy': ....}
    bulk: { // OR bulk: ['create', 'destroy', ....]
      enabled: [], // enable bulk options ['create', 'destroy', 'update']
      // Use bulkColumn when using bulk option for 'create' and using returning true to increase efficiency.
      bulkColumn: false, // bulk identifier column, when bulk creating this column will be auto filled with a uuid and later used to fetch added records 'columnName' or ['columnName', true] when using a foreign key as bulk column
      returning: true // This will return all created/updated items, doesn't use sequelize returning option.
    }
    types: {}, // user defined custom types
    mutations: {}, // user defined custom mutations
    queries: {}, // user defined custom queries
    // exclude one or more default mutations ['create', 'destroy', 'update']
    excludeMutations: [],
    excludeQueries: [], // exclude one or more default queries ['fetch']
    // HOOKS
    // each hook must return a promise.
    // extend/after hook default queries/mutations behavior {fetch, create, destroy, update}
    // (data, source, args, context, info) are passed to extend
    extend: {},
    // before hook for default queries/mutations behavior {fetch, create, destroy, update}
    // (source, args, context, info) arguments are passed to before
    before: {},
    // overwrite default queries/mutations behavior {fetch, create, destroy, update}
    // overwrite hooks are passed (source, args, context, info) arguments
    overwrite: {},
    joins: false // make a query using join (left/right/inner) instead of batch dataloader, join will appear in all subtype args. Right join won't work for sqlite
    Product.graphql = {
        attributes: {
            exclude: ['description'],
            include: { modelPortfolioId: 'int', obj: 'myObj' },
        }
    };

    Usage

    const {generateModelTypes, generateSchema} = require('graphcraft')(options);
    const models = require('./models')
    const schema = await generateSchema(models) // Generates the schema, return promise.

    Example with Express

    const { GraphQLSchema } = require('graphql');
    const express = require('express');
    const graphqlHTTP = require('express-graphql');
     
    var options = {
      exclude: ["Users"]
    }
     
    const {generateSchema} = require('graphcraft')(options);
     
    const models = require('./models');
     
    const app = express();
     
    app.use('/graphql', async (req, res) => {
      
      const schema = await generateSchema(models, req);
     
      return graphqlHTTP({
          schema: new GraphQLSchema(schema),
          graphiql: true
        })(req, res);
     
    });
     
    app.listen(8080, function() {
      console.log('RUNNING ON 8080. Graphiql http://localhost:8080/graphql')
    })

    Credits

    This library is inspired and was initiated from https://github.com/rpellerin/graphql-sequelize-schema-generator.

    Install

    npm i graphcraft

    DownloadsWeekly Downloads

    6

    Version

    1.0.0-beta.21

    License

    MIT

    Unpacked Size

    183 kB

    Total Files

    31

    Last publish

    Collaborators

    • alirizwan