@nexes/nql - npm Package Compare versions

Comparing version 0.2.1 to 0.2.2

lib/nql.js

@@ -6,40 +6,2 @@ const mingo = require('mingo');
 
-/**
- * Public API of NQL tools with consistent usage:
- *
- * nql('id:3').toJSON() => {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:
- *
- * 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'
- *  }).querySQL(knexQueryBuilderObject)
- *
- *  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
- */
 module.exports = (queryString, options = {}) => {
@@ -46,0 +8,0 @@ const api = {};

package.json

 {
   "name": "@nexes/nql",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "tbc",
-  "repository": "[e-mail]:NexesJS/NQL.git",
+  "repository": {
+    "type": "git",
+    "url": "git://github.com/NexesJS/NQL.git"
+  },
   "author": "Ghost Foundation",
@@ -7,0 +10,0 @@ "license": "MIT",

README.md

 # NQL
+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](https://github.com/NexesJS/NQL-Lang))
+ - enhancing a database query with additional filters based on provided expression (using [mongo-knex](https://github.com/NexesJS/mongo-knex))
+ - querying JSON objects with NQL expressions (using [mingo](https://github.com/kofrasa/mingo))
 
 ## Installation
-1. Make sure that `gstenv` is green. See [Dev Environment](https://github.com/TryGhost/Team/blob/master/Engineering/Dev%20Environment.md) for docs.
-2. `git clone` this repo & `cd` into it as usual
-3. Run `yarn` to install top-level dependencies.
+Using npm:
+```
+npm install @nexes/nql --save
+```
+or with yarn:
+```
+yarn add @nexes/nql
+```
 
-## Run
-- Use: `yarn dev`
-- View: [http://localhost:9999](http://localhost:9999)
+## Example
+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:
+```javascript
+{
+    $and: [
+        {
+            featured: true
+        },
+        {
+            slug: {
+                $in: ['photo', 'video']
+            }
+        }
+    ]
+}
+```
 
+If the same expression would be applied to Knex [QueryBuilder](https://knexjs.org/#Builder) object, the following SQL where statement would be generated:
+```sql
+where (`posts`.`featured` = true and `posts`.`slug` in ('photo', 'video'))
+```
+
+## Usage
+Some common usages:
+```javascript
+nql('id:3').toJSON();
+\\ => {id:3}
+```
+
+```javascript
+nql('id:3').queryJSON({test:true, id:3});
+\\ => true
+```
+
+```javascript
+nql('tags:test', {expansions: {tags: 'tags.slug'}}).toJSON();
+\\ => {'tags.slug': test}
+```
+```javascript
+nql('primary_tag:[photo]', {expansions: [
+      {key: 'primary_tag', replacement: 'tags.slug', expansion: 'order:0'}
+  ]})
+\\ => {$and: [{'tags.slug': {$in: ['photo']}}, {order: 0}]}
+```
+
+Advanced usage example:
+
+```javascript
+// 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'
+});
+
+query
+    .querySQL(knex('posts'))
+    .select();
+```
+
 ## Test
@@ -18,2 +102,2 @@ - `yarn lint` run just eslint
 
-Copyright (c) 2018 Ghost Foundation - Released under the [MIT license](LICENSE).
+Copyright (c) 2018-2019 Ghost Foundation - Released under the [MIT license](LICENSE).

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

New author

Supply chain risk

A new npm collaborator published a version of the package for the first time. New collaborators are usually benign additions to a project, but do indicate a change to the security surface area of a package.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

No repository

Supply chain risk

Package does not have a linked source code repository. Without this field, a package will have no reference to the location of the source code use to generate the package.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

45521

increased by3.89%

Number of package files

29

increased by3.57%

Number of lines in readme file

103

increased by442.11%

Number of low supply chain risk alerts

8

decreased by-11.11%

Worsened metrics

Lines of code

1040

decreased by-1.05%

Number of medium supply chain risk alerts

1

increased byInfinity%

No dependency changes