NextQL
NextQL is JSON query language for APIs and a robust and extensible runtime for resolve those queries. Equivalent with Facebook's GraphQL, but much more simple.
- Ask what you need, get exactly that.
- Get many resources by a single request.
- No limitation how to define type systems.
- No limitation how to resolve requests.
TOC
- NextQL
Change Logs
0.0.6 (08-14-2017)
- Support conditional queries.
- Support getAttr hook
0.0.5 (08-10-2017)
- Fix bugs
- Replace lodash.set by simpler implementation; now nextql have no-dependencies and some increase in raw performance.
0.0.3 (08-08-2017)
- Support explicit type defines for methods and computed fields.
- Remove Object typed behavior.
- Introduce new type define: Scalar
- New beforeExecute hook
- Better error messages.
- Back compatible with 0.0.2 except Object typed behavior.
Install
Install NextQL from npm
npm install --save nextql
Plugins
- nextql-validate : Validate nextql methods with fastest-validator.
- nextql-feathers : Extend NextQL with awesome Feathersjs service. NextQL could do real-time/multiple backend/authentication.
- nextql-limit : Simple solution to protect against excessive or abusive calls (DoS)
- nextql-neo4j : Use nextql to provide OGM interface for neo4j database.
Introduction to NextQL
NextQL is simply a data query engine inspired by Facebook GraphQL but much more simple. NextQL consists a type system based on pure JS objects and a JSON query language.
Type System
For example a User model:
fields: firstName: 1 /* let NextQL decide field type */ lastName: 1 address: "Address" // explicit field type phone: /* explicit inline type */ work: 1 home: 1 fullName: "*" // explicit scalar type for computed field [fullName] computed: // virtual field computed from source value. { return sourcefirstName + sourcelastName; } methods: // exposed method for this model. { return contextdb; } returns: // Define resolve function to return type for method [get] { return "User" }
Every model configuration may have 4 keys:
- fields : define model's field name and how to resolve its type.
- computed : define model's virtual field and the function to compute value from source object. NextQL will automatically resolve the value type, unless explicit defined in fields
- methods: define exposed APIs for the model.
- returns: By default NextQL will try to resolve type for method's result. The options allow explicit defined type for return value.
fields and computed equivalent with GraphQL's fields; methods and returns equivalent with GraphQL's queries and mutations.
Different with GraphQL, NextQL not enforced strong-typed for field and method values rather use "ducking type system". You have many options for define how to resolve value type:
- 1 : let NextQL decide value type. How NextQL decide field/method type?
- "other model name" : explicit assign value type.
- "*" : explicit assign value as scalar value.
- [Object] : explicit define value as inline nested type
- [Function] : Given a function, NextQL should call to resolve value type.
getAttr hook
By default, nextql resolve directly field from source:
fieldValue = sourcefieldName
Override getAttr hook, you could implement your own field resolver. For example, Neo4j Entry object actually store value inside "properties" field; so you either model Entry use nested fields or use getAttr hook
without getAttr
fields: // without getAttr hook you must define Entry with nested properties field properties: name: 1
with getAttr
fields: // with getAttr hook, you could define Entry as normal name: 1 getAttr: source fieldName return sourcefieldName;
Complex type define
Combine all those options, you can define very complex model. For example:
;
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 = valueconstructor && valueconstructorname;
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 ...
Query
NextQL query is a JSON object define what API methods called and what data to return. NextQL will start to resolve query follow order: model -> method -> fields -> ... recursive fields -> final result.
For example the query
"user": // model "me": // method "fullName": 1 //field or computed field
Could produce the JSON result:
Equivalent call me method of class user then pick fullName field from result. It look like combine REST API call with GraphQL query.
/user/me => { fullName }
Conditional Query
NextQL conditional query is close with GraphQL fragment but more powerful. Conditional query is a computed function start with "?".
"user": "me": "fullName": 1 "?manager": "subordinates": "fullName": 1
The results could be
"user": "me": "fullName": "Giap Nguyen Huu" "subordinates": // This fields only resolve if the computed "?manager" passed. "fullName": "Tuyen Phuong"
The conditonal function is a resolver start with "?". It should return a model name or "true" if the conditionals passed.
If a model name, the query inside conditional field will resolved with return model. The behavior is same with GraphQL fragment.
If true, the query inside conditonal field will resolved as current model or self conditonal query.
nextql; nextql; const result = await nextql;
The result should be
a: test: a: "a" b: "b" a: "a" b: "b"
Self Conditional Query
Self conditional is when the resolver return true. It seems make no sense because the parent query already resolve as current model. But it could useful in some usecases. Assume you have a User model. If a user is admin, it need additional fields. So you either define a User model with additional fields or 3 models: User interface, Admin model and User model. But if you feels use 1 model not clear the relationship and 3 models is overkill and self conditonal could be used.
nextql; const result = await nextql;
The result should be
User: fillAll: name : "Thanh" // not admin name : "Liem" // not admin name: "Giap" adminWebsites: null adminStuffs: 123 //admin
Next time you decide that Admin is enough complex for another model, just remove admin fields and update ?admin resolver. Client side use the same query without aware your changes.
{ return sourceisAdmin ? "Admin" : undefined; }
Arguments
NextQL allow pass arguments to methods and computed fields and conditional fields via reserved $params field.
Could produce the JSON result:
You could use params in conditional query.
computed: { // I going to cast source in any model return paramsname; }
Then query:
Person: get: personStuffs: 1 "?cast": "$params": "name": "Drone" // Please treat me as a 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.
Could produce the JSON result:
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.
The JSON result should be
NextQL ❤️ Plugins
NextQL very simple and flexible. Everything could extensible/customize. NextQL follow Vue plugin pattern.
MyPlugin { nextql; nextql;} nextql;
- 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.
Sample 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 = ; /** Simply convert mongoose schema to nextql fields */ { const _fields = {}; Object; return _fields;} { if optionsmongoose const model = mongoose; optionsfields = ; optionsmethods = Object; } { return sourceconstructor && sourceconstructormodelName;} moduleexports = { nextql; nextql; };
Mongoose plugin in action
const mongoose = ;mongoosePromise = globalPromise; mongoose; const nextql = ;const nextqlMongoose = ;nextql; nextql; { const users = await nextql; return userstest}
Combine beforeCreate hook and afterResolveType hook, you able to create any kind of NextQL schema and behaviors.
Samples
APIs
execute
Execute query.
nextql;
model
Register new model
nextql
Lookup model throw execption if not found
nextql
use
Register plugin
nextql;
beforeCreate
Register a hook called when new model added. Allow you manipulate model options.
nextql;
afterResolveType
Register a hook called when NextQL try resolve type from source.
nextql;
Equivalent with GraphQL
Compare two version of getDie example, NextQL very close with GraphQL. Very easy to convert GraphQL code into NextQL. NextQL's StarWar reuse most of GraphQL sample code except model's definition.
Testing
PASS test/resolvers.test.js
PASS samples/starwar/starwar.test.js
PASS test/nextql.test.js
PASS test/getDie.test.js
Test Suites: 4 passed, 4 total
Tests: 55 passed, 55 total
Snapshots: 0 total
Time: 0.539s, estimated 1s
Ran all test suites.
------------------|----------|----------|----------|----------|----------------|
File | % Stmts | % Branch | % Funcs | % Lines |Uncovered Lines |
------------------|----------|----------|----------|----------|----------------|
All files | 95.26 | 92.63 | 90.91 | 96.15 | |
samples/starwar | 90.24 | 75 | 85.71 | 89.47 | |
starWarsData.js | 92.31 | 75 | 85.71 | 91.3 | 104,121 |
starwar.js | 86.67 | 100 | 100 | 86.67 | 30,60 |
src | 96.64 | 94.25 | 91.89 | 97.92 | |
index.js | 91.43 | 82.35 | 83.33 | 93.75 | 39,81 |
model.js | 93.75 | 92.86 | 85.71 | 96.77 | 18 |
resolvers.js | 100 | 98.15 | 100 | 100 | 53 |
util.js | 100 | 100 | 100 | 100 | |
------------------|----------|----------|----------|----------|----------------|
Benchmarks
node benchmark/index.js
nextql#getDie x 42,284 ops/sec ±0.44% (84 runs sampled)
graphql#getDie x 9,713 ops/sec ±4.18% (78 runs sampled)
Fastest is nextql#getDie
Without type checked and parse query string, NextQL significantly faster than GraphQL.
Licensing
"The code in this project is licensed under MIT license."