Mongql

A package to convert your mongoose schema to graphql schema

TOC

• Mongql
  • TOC
  • Features
  • Motivation
  • Usage
    • Basic Usage (Without initial typedef and resolvers)
    • Intermediate Usage (With initial typedef and resolvers)
    • Intermediate Usage (Output SDL and AST)
    • Intermediate Usage (Fine grain Mutation configuration)
    • Intermediate Usage (Fine grain Query configuration)
    • Intermediate Usage (Extra Powerful Fine grain Query configuration)
    • Advanced Usage (generating Schema and Models)
    • Advanced Usage (Using local folders)
  • Configs
    • Global Configs
    • Schema configs
    • Field configs
  • Concept
  • API
  • FAQ
  • TODO

Features

1. Create graphql schema (typedef and resolvers) from mongoose schema
2. Stitch already created typedef and resolvers
3. Easily configurable (any of the typedef and resolvers can be turned off)
4. View the generated SDL
5. Auto addition of graphql validators with mongoose

Motivation

1. Creating a graphql SDL is not a difficult task by any means, but things get really cumbersome after a while, especially since a lot of the typedefs and resolvers are being repeated.
2. Automating the schema generation helps to avoid errors regarding forgetting to define something in the schema thats been added to the resolver or vice versa.
3. Creating resolvers for subtypes in a PITA, especially if all of them just refers to the same named key in parent

Usage

Basic Usage (Without initial typedef and resolvers)

// User.schema.js
const mongoose = require('mongoose');
 
const UserSchema = mongoose.Schema({
    name: {
        type: String,
        mongql: {
            writable: false // field level config
        }
    }
});
 
UserSchema.mongql = {
    resource: 'user'
}; // schema level config
 
module.exports = UserSchema;

// index.js
const {
    makeExecutableSchema 
} = require('@graphql-tools/schema');
const {
    ApolloServer 
} = require('apollo-server-express');
const Mongql = require('MonGql');
 
const UserSchema = require('./User.schema.js');
 
(async function() {
    const mongql = new Mongql({
        Schemas: [UserSchema],
    });
 
    // Calling the generate method generates the typedefs and resolvers
    const {
        TransformedResolvers,
        TransformedTypedefs, // Contains both arr and obj representation 
    } = await mongql.generate();
 
    const GRAPHQL_SERVER = new ApolloServer({
        schema: makeExecutableSchema({
            typeDefs: TransformedTypedefs.arr,
            resolvers: TransformedResolvers.arr,
        }),
        context: () => ({
            user: req.user
        })
    });
})();

Intermediate Usage (With initial typedef and resolvers)

// user.typedef.js
module.exports = gql `
  type BasicUserType{
    name:String!
  }
`;

// user.resolver.js
module.exports = {
    Mutation: {
        updateUserSettings: ...
    }
}

const UserAST = require('./user.typedef.js');
const UserResolver = require('./user.resolver.js');
 
const PreTransformedTypeDefsASTs = {
    user: UserAST // This has to match with the resource name added in the mongoose schema
}
 
const PreTransformedResolvers = {
    user: UserResolver
}
 
const mongql = new Mongql({
    Schemas: [UserSchema, SettingsSchema],
    Typedefs: {
        init: PreTransformedTypeDefsASTs
    },
    Resolvers: {
        init: PreTransformedResolvers
    }
});

Intermediate Usage (Output SDL and AST)

  const mongql = new Mongql({
      Schemas: [],
      output: {
          SDL: path.resolve(__dirname, "./SDL"),
          AST: path.resolve(__dirname, "./AST")
      }
  });
 
  await mongql.generate()

Intermediate Usage (Fine grain Mutation configuration)

const mongql = new Mongql({
    Schemas: [UserSchema, SettingsSchema],
    generate: {
        mutation: false, // will not generate any mutation typedef and resolver,
        mutation: {
            create: false, // Will not generate any create mutation typedef and resolver,
            update: {
                multi: false // Will not generate any update multi mutation typedef and resolver
            },
            single: false // Will not generate any single mutation typedef and resolver
        }
    }
});

Intermediate Usage (Fine grain Query configuration)

const mongql = new Mongql({
    Schemas: [UserSchema, SettingsSchema],
    generate: {
        query: false,
        query: {
            all: false
        },
        query: {
            paginated: {
                self: false
            }
        },
        query: {
            filtered: {
                others: {
                    whole: false
                }
            }
        }
    }
});

Intermediate Usage (Extra Powerful Fine grain Query configuration)

const mongql = new Mongql({
    Schemas: [UserSchema, SettingsSchema],
    generate: {
        query: {
            self: false, // remove all self related typedefs and resolvers,
            self: {
                whole: false // remove all selfwhole related typedefs and resolvers,
            },
            count: false, // remove all count related typedefs and resolvers,
        }
    }
});

Advanced Usage (generating Schema and Models)

const Mongql = require('mongql');
const {
    ApolloServer 
} = require('apollo-server');
 
(async function() {
    const mongql = new Mongql({
        Schemas: [
            /* Your schema array here */
        ],
 
    });
    const server = new ApolloServer({
        schema: await mongql.generateSchema(), // there is a known issue with this use makeExecutableSchema
        context: mongql.generateModels()
    });
    await server.listen();
})();

Advanced Usage (Using local folders)

const Mongql = require('mongql');
const {
    ApolloServer 
} = require('apollo-server');
 
(async function() {
    const mongql = new Mongql({
        Schemas: path.resolve(__dirname, './schemas'),
        output: {
            dir: __dirname + '\\SDL'
        },
        Typedefs: path.resolve(__dirname, './typedefs'),
        Resolvers: path.resolve(__dirname, './resolvers')
    });
    const server = new ApolloServer({
        schema: await mongql.generateSchema(), // there is a known issue with this use makeExecutableSchema
        context: mongql.generateModels()
    });
    await server.listen();
})();

Mongql contains 3 level of configs

1. Constructor/global level config: passed to the ctor during Mongql instantiation
2. Schema level config: Attached to the schema via mongql key
3. Field level config: Attached to the field via mongql key

Precedence of same config option is global < Schema < field. That is for the same option the one with the highest precedence will be used.

Configs

& refers to the whole key declared just right above.

Global Configs

Name	Description	Type	Default Value	Usage	Available in
output	output related configuration	boolean \| Object	false	{output: false} {output: { dir: process.cwd()}}	Schema
&.(dir|SDL)	SDL Output directory	string	undefined	{output: { dir: process.cwd()}}	Schema
&. AST	AST Output directory	string	undefined	{output: { AST: process.cwd()}}	Schema
generate	Controls generation of type, query and mutations typedefs and resolvers	Object | boolean	true	generate: true	Schema
&.query	Controls generation of query typedefs and resolvers	Object | boolean	Object	generate :{query: true}	Schema
&.(range)	Controls generation of query range typedefs and resolvers	Object | boolean	Object	generate :{query:{ all: false}} Take a look at concepts to see all ranges	Schema
&.(auth)	Controls generation of query range auth typedefs and resolvers	Object | boolean	Object	generate :{query:{ all: {self: false}}} Take a look at concepts to see all auth	Schema
&.(part)	Controls generation of query range auth part typedefs and resolvers	Object | boolean	Object	generate :{query:{ all: {self: {whole: false}}}} Take a look at concepts to see all part	Schema
&.mutation	Controls generation of mutations typedefs and resolvers	Object | boolean	true	generate :{mutation: true}	Schema
&.(action)	Controls generation of mutations typedefs and resolvers action	Object | boolean	true	generate :{mutation: {create: {multi:true}, update: {single: false}}} Take a look at concepts to see all mutation action	Schema
&.(target)	Controls generation of mutations typedefs and resolvers target	Object | boolean	true	generate :{mutation: {create: {multi:true}, update: {single: false}}} Take a look at concepts to see all mutation targets	Schema
Schemas	Array of schemas generate by mongoose or path to schema folder	Schema[] | String	[]	Schemas: [UserSchema, ...]
Typedefs	Typedefs related configuration or path to typedefs folder	Object | String	{init: undefined}	Typedefs: {init: {User: InitialUserTypedef}}
&.init	Initial typedefs to be attached to resultant typedef	Object	undefined	init: {User: InitialUserTypedef}
Resolvers	Resolvers related configuration or path to resolvers folders	Object | String	{init: undefined}	Resolvers: {init: {User: InitialUserResolvers}}
&.init	Initial resolvers to be attached to resultant resolver	Object	undefined	init: {User: InitialUserResolver}
appendRTypeToEmbedTypesKey	Controls whether or not to append the resource type to sub/embed/extra types	boolean	true	appendRTypeToEmbedTypesKey: true	Schema

Schema configs

Name	Description	Type	Default Value	Usage	Available in
resource	name of the resource	string	Required	resource: User
global_excludePartitions	Controls which auth partition will be excluded in the generated schemas	Object	{base: [], extra: ['Others', 'Mixed']}	global_excludePartitions: {base: [ 'Others', 'Mixed' ]}
&.(base|extra)	Controls which auth partition will be excluded in the types of generated schemas	[] \| boolean	{base: [], extra: ['Others', 'Mixed']}	global_excludePartitions: {base: [ 'Others', 'Mixed' ], extra: ['Self']}
generateInterface	Controls whether or not to generate interface from base resource	boolean	true	generateInterface: true
skip	Skip mongql all together	boolean	false	skip: true

Field configs

Name	Description	Type	Default Value	Usage	Available in
writable	Controls whether or not this field is present in generated input	boolean	true	writable: true
scalar	Custom graphql scalar to be used (atm all graphql-scalars scalars are included)	string	parsed type from mongoose	scalar: 'NonNegativeInt'

Concept

During the generation of schema, a few concepts are followed

1. Each Resource query object type contains four parts

   1. Range(Input):

      1. All: Gets all the resource
      2. Paginated : Used to get resource through pagination inpu
      3. Filtered : Used to get resource through filter input
      4. ID: Used to get a resource by id

   2. Auth:

      1. Self: Used to indicate logged in users resource
      2. Others: Used to indicate other users resource (when current user is authenticated)
      3. Mixed: Used to incicate others users resource (when user is unauthenticated)

   3. Resource: Name of the resource (capitalized & pluralized form)

   4. Part(Output):

      1. Whole: Get the whole data along with sub/extra types
      2. NameAndId: get the name and id of the resource
      3. Count: get the count of resource

2. Each resource mutation object type contains 2 parts

   1. Action: One of create|update|delete
   2. Target: resource for targeting single resource, resources for targeting multiple resources

3. Each resource types contains the following parts

   1. Based on the permitted auths types will be generated with the following syntax auth resource type and type, eg SelfUserType
   2. All the embedded mongoose schema will be converted into its own type
   3. mongoose Enums fields will be converted into enums
   4. Based on the generateInterface option interface will be generated
   5. Inputs will be created based on the generated type

Generated Query Examples: getSelfSettingsWhole, getOthersSettingsNameAndId

Generated Mutation Examples: createSetting, updateSettings

NOTE: Count part is not generate in paginated and id range as for paginated query the user already knows the count and id returns just one

API

These methods are available in the created Mongql instance

Name	Description	Params	Returned
generate()	Generate the Typedefs and resolvers from the schemas		{TransformedTypedefs, TransformedResolvers}
getResources()	Gets all the resources collected from all schemas		(Schema.mongql.resource)[]
generateModels()	Generates models from the schema provided		Object:{[Schema.mongql.resource]: MongooseModel}
generateSchema()	Generates a schema by calling makeExecutableSchema internally	options passed to makeExecutableSchema expect for typedefs and resolvers	GraphQLSchema
static outputSDL()	Outputs the SDL from the given typedef	path: String // SDL output dir typedefs: GraphqlAST | String // String or AST to convert resource: String // name of file or resource

FAQ

1. Why do I need to use resource key?

Answer.

1. Resource key is used to merge the initial query, mutation and types in the correct place

2. Its used as the Model name, in the generated resolvers

3. Its used to derive relation between resources, (not yet supported), for eg in the mutation resolver, dependant resources can be created and deleted

TODO

1. Add more well rounded tests
2. Migrate the whole project to TS
3. Using babel to transpile to transform modern featues
4. Standard liniting configuration
5. Provide ES modules to make the library tree-shakable
6. More enriched API
7. Better documentation

PRS are more than welcome and highly appreciated!!!!