960.6.02 months ago3 years agoMinified + gzip package size for @nexes/nql in KB



The aim is putting together various nql related projects into single, easy to use api. It allows:

  • parsing of NQL expression into Mongo JSON (using nql-lang)
  • enhancing a database query with additional filters based on provided expression (using mongo-knex)
  • querying JSON objects with NQL expressions (using mingo)


Using npm:

npm install @nexes/nql --save

or with yarn:

yarn add @nexes/nql


A simple NQL expression could have following form: featured:true+slug:['photo', 'video'] When parsing it to Mongo JSON with nql(expression).parse() the output would be:

    $and: [
            featured: true
            slug: {
                $in: ['photo', 'video']

If the same expression would be applied to Knex QueryBuilder object, the following SQL where statement would be generated:

where (`posts`.`featured` = true and `posts`.`slug` in ('photo', 'video'))


Some common usages:

\\ => {id:3}
nql('id:3').queryJSON({test:true, id:3});
\\ => true
nql('tags:test', {expansions: {tags: 'tags.slug'}}).toJSON();
\\ => {'tags.slug': test}
nql('primary_tag:[photo]', {expansions: [
      {key: 'primary_tag', replacement: 'tags.slug', expansion: 'order:0'}
\\ => {$and: [{'tags.slug': {$in: ['photo']}}, {order: 0}]}

Advanced usage example:

// Builds SQL where statement on top of knex Query Builder including:
//  - combining custom filter 'primary_tag:test' with overrides filter and defaults
//  - expanding shortcut property 'primary_tag' into 'tags.slug' and adding 'posts_tags.sort_order:0' filter
//  - builds a where statement with related `tags` table through manyToMany relation
const query = nql('primary_tag:test', {
    relations: {
        tags: {
            tableName: 'tags',
            type: 'manyToMany',
            joinTable: 'posts_tags',
            joinFrom: 'post_id',
            joinTo: 'tag_id'
    expansions: [
            key: 'primary_tag',
            replacement: 'tags.slug',
            expansion: 'posts_tags.sort_order:0'
    overrides: 'status:published',
    defaults: 'featured:true'



  • yarn lint run just eslint
  • yarn test run lint && tests

Copyright & License

Copyright (c) 2013-2021 Ghost Foundation - Released under the MIT license.

If you find any bugs or have a feature request, please open an issue on github!

The npm package download data comes from npm's download counts api and package details come from npms.io.