What is NextQL

NextQL is a JSON query language for APIs and an extensible runtime for fulfilling those queries. It equivalent with Facebook’s GraphQL but much simpler. There are a lot of topics about GraphQL and GraphQL vs REST. I’m not going say it again. In short, FB’s GraphQL or Netflix’s Falcor or my NextQL or REST serve a same purpose. It is a tool for client query and manipulate data efficiently.

Why NextQL?

I absolutely love GraphQL, but struggling to apply into my projects. Strongly-typed schema, strongly-typed input and text based query are not my tastes. In my own opinion, they are bring little benefits and more obstructions for GraphQL. One day, I wake up and ask why not do something less pain and more enjoyable for myself. I image something:

• Simpler but still have same power.
• Able to resolve any data or any data source with minimum of work.
• Easy to extend both schema definition and functionals.

My dream of data query engine

That magic engine should consume anything from single object, single database to many data sources or many micro-services. Then it serves the complex data for clients via a simple and unified query language.

For that reason, I started NextQL. It just a very young project, but excited and enjoyable.

What NextQL differ with GraphQL?

1. NextQL focus data shape not data type. Without fear of type invariants, it is easier to map complex data or data source into NextQL models.
2. NextQL drop Input type to favor third-parties validation frameworks such as joi, ajv or fastest-validator. Developers could use the same input validation schemas for both client side and server side. See nextql-validate for more detail.
3. NextQL combine queries and mutations into relevant models same with REST. I believe it is better than GraphQL’s put everything inside Root Query and Root Mutation. First less pain in naming methods and naming is a hardest thing. Second it is scalable for hundreds API methods.
4. NextQL use Javascript plain object as model configurations. It is very flexible and customizable. Most of NextQL plugins take advantages to extend base configuration model into their own syntax.
5. NextQL use JSON as query language. It’s simpler and easier than string based language. You able to modify, merge or twist NextQL’s JSON query whatever you want. For example, nextql-feathers plugin transform Feathers request into NextQL query with couple lines of codes.
6. Finally, NextQL love plugins, everything should be extensible and customizable.

Models

NextQL models

The models are simple javascript object. It defines how to resolve your data source. NextQL focus data shape (how your data look like) not data type ( String, Number or Array). Take a look as User model:

{
     fields: {
        firstName: 1,        // let NextQL decide the type.
        lastName: 1,         
        address: "Address",  // explicit as Address model
        phone: {             // nested model
           work: 1,
           home: 1
        }     
     },
     computed: {
        // calculate fields by default let NextQL decide return type
        fullName(source, params, context){
	    return source.firstName + source.lastName;
	},
        // conditional resolver more detail later.
        "?manager": function(source, params){
             return source.isManager ? "Manager" : underfined;
        }
     },
     methods: {
	 // exposed method for this model. Same as GraphQL Root           
         // queries and mutations
         get(params, context){
	      return context.db.get(params.id);
	}
     },
     returns: {
        get: "User" // explicit get's result as User model
     }
}

There are 4 important keys.

1. Fields: Define which field expose for query and how to resolve it’s type.
2. Computed: Virtual fields which either calculated from source, or relationship objects. If the field start with “?” , it is conditional resolvers which more detail later. By default, NextQL resolve computed result’s type automatically.
3. Methods: Exposed APIs for the model equivalent with REST APIs or GraphQL’s Root Queries or Mutations. By default, NextQL resolve API result’s type automatically.
4. Returns: The keys use to explicit assign type for above methods.

Different with GraphQL, NextQL not enforced strongly-typed rather use “ducking type system”. You have many options for define how to resolve value type:

• 1 meaning let NextQL decide value type.
• “string” meaning explicit assign value type as a model.
• “*” meaning treat the value as scalar.
• [Object] meaning the value is a inline model.
• [Function] meaning call the function to resolve the type.

How NextQL decide field/method type?

NextQL use a global resolveType function to resolve model name from object which by default use value constructor name for model name.

const defaultResolveType = value => value.constructor && value.constructor.name;

You can config your own resolveType or better use afterResolveTypeHooks. You free to choose whatever to resolve type from object. It could be mongoose model name, __type field …

Why provide so many way to define field type or model?

1. NextQL want able to resolve any kind of data. You could have a great DDD system or a lot of ad hoc plain JS objects or many micro service or message queue or mixed; NextQL should provide tools or rules to map all of them into unified models.
2. NextQL want the mapping process is painless. It support nested model, conditional resolvers to help you minimum model definitions. Less models meaning less boilerplate, less code, less naming and naming is hardest thing (again).

Queries

NextQL’s query is simple JSON object. It defines what API methods called and what data to return. NextQL will start to resolve query follow order: model -> method -> fields -> … recursive fields -> final result..

{
    "hero": {               # model
         "get": {           # method
                "name": 1   # fields
         }    
    }
}

NextQL’s queries look likes combine GraphQL and REST. The query could translate as:

GET /hero { name }

Conditional Queries

Field names start with “?” consider as conditional queries. It is close with GraphQL fragments but more powerful. Differ GraphQL fragments, conditional queries not use to solve duplicated fields. Those queries are resolved by conditional resolvers. If the conditionals passed, the resolvers return a model name or true.

If a model name returns, the query inside conditional fields will resolved with the model. The behavior is same with GraphQL fragment.

If true returns, the query inside conditional fields will resolved as a current model.

{
    "users": {
          "get": {
                "name": 1,
                "?manager": {            # is user is a manager?
                     "subordinates": {   
                           "name": 1 
                     }
                }
           }
    }
}

The result could be

{
    "users":{
        "get": {
            "name": "Giap Nguyen Huu",
	    "subordinates": [
		{ "name": "Tuyen Phuong"}
	    ]
        }
    }
}

Arguments

NextQL allow pass arguments to methods and computed fields and conditional fields via reserved $params field.

{   
    "human": {
        "get": {
            "$params": { "id": "1000" },
            "fullName": 1,
            "height": {
                "$params": { "unit": "m"}
            }
        }
    }
}

Could produce the JSON result:

{
    "human":{
        "get": {
            "fullName": "Nguyen Huu Giap",
            "height" : 1.69
        }
    }
}

You could use params in conditional query.

{
	computed: {
                // I going to cast source in any model
                "?cast": function(source, params){ 
                     return params.name;
		}
	}
}

Then query:

{
	Person: {
		get: {
			personStuffs: 1,
			"?cast": {
                                // Please treat me as a drone
				"$params": { "name": "Drone" }, 

				droneStuffs: 1
			}
		}
	}
}

Alias

Because result field match with query field. If you need call multiple methods, fields you need alias. NextQL alias is a suffix separator which resolver ignore.

{
    "human":{
        "get/1000": {
            "$params": { "id": "1000" },
            "name": 1
        },
        "get/1001": {
            "$params": { "id": "1001" },
            "name": 1
        }
    }
}

Could produce the JSON result:

{
    "human":{
        "get/1000": {
            "name": "Nguyen Huu Giap"
        },
        "get/1001": {
            "name": "Dinh Thi Kim Nguyen"
        }
    }
}

By default “/” is alias separator, anything after it doesn’t counted. You could config any suffix separator.

Traverse related object

You can ask more data from relate objects.

{
	"person": {
		"get/giapnh": {
			"$params": { "id": "giapnh" },
			"name": 1,
			"children": {
				"name": 1
			}
		},
		"get/nguyen": {
			"$params": { "id": "nguyen" },
			"name": 1,
			"children": {
				"name": 1
			}
		}
	}
}

The JSON result should be

{
	"person": {
		"get/giapnh": {
			"name": "Nguyen Huu Giap",
			"children": [{
				"name": "Nguyen Huu Vinh"
			}]
		},
		"get/nguyen": {
			"name": "Dinh Thi Kim Nguyen",
			"children": [{
				"name": "Nguyen Huu Vinh"
			}]
		}
	}
}

NextQL ❤️ Plugins

NextQL very simple and flexible. Everything could extensible/customize. NextQL follow Vue plugin pattern.

MyPlugin.install = function (nextql, options) {
  nextql.beforeCreate(schema => schema);
  nextql.afterResolveType(source => source.__type);
}
nextql.use(MyPlugin);

• nextql.beforeCreate : the hook call before NextQL build Model object from schema. It is powerful hook to customize schema.
• nextql.afterResolveType : the hook call after NextQL resolve type from source object. It give you a chance to map source to NextQL model type.

For example Mongoose plugin — it catch any schema have mongoose option:

• Create mongoose model from schema fields.
• Inject CRUD methods into schema methods.

Finally it help resolve mongoose document into NextQL model.

const mongoose = require("mongoose");
/** Simply convert mongoose schema to nextql fields */
function normalizeFields(fields) {
	const _fields = {};
	Object.keys(fields).forEach(k => {
		if (fields[k].constructor == Object && !fields[k].type) {
			_fields[k] = normalizeFields(fields[k]);
		} else {
			_fields[k] = 1;
		}
	});
	return _fields;
}
function hookBeforeCreate(options) {
	if (options.mongoose) {
		const model = mongoose.model(options.name, options.fields);
		options.fields = normalizeFields(options.fields);
		options.methods = Object.assign(
			{
				get({ id }) {
					return model.findById(id);
				},
				find() {
					return model.find();
				},
				create({ data }) {
					var ins = new model(data);
					return ins.save();
				},
				update({ id, data }) {
					return model.findById(id).then(ins => {
						Object.keys(data).forEach(path =>
							ins.set(path, data[path])
						);
						return ins.save();
					});
				},
				remove({ id }) {
					return model.findByIdAndRemove(id);
				}
			},
			options.methods
		);
	}
}
function hookAfterResolveType(source) {
	return source.constructor && source.constructor.modelName;
}
module.exports = {
	install(nextql) {
		nextql.beforeCreate(hookBeforeCreate);
		nextql.afterResolveType(hookAfterResolveType);
	}
};

Mongoose plugin in action

const mongoose = require("mongoose");
mongoose.Promise = global.Promise;
mongoose.connect('mongodb://localhost/nextql', { useMongoClient: true }).catch(error => {
	console.log(error);
	process.exit(1);
});
const nextql = require('../nextql');
const nextqlMongoose = require('./index');
nextql.use(nextqlMongoose);
nextql.model('test', {
	mongoose: true,
	fields: {
		_id: String,
		name: String
	}
});
async function run() {
	const users = await nextql.execute({
		test: {
			find: {
				name: 1
			}
		}
	});
	return users.test
}

Combine beforeCreate hook and afterResolveType hook, you able to create any kind of NextQL schema and behaviors.

Summary

That’s some about NextQL. More detail specs, API and plugin systems please check the project github