@ucast/mongo - npm Package Compare versions

Comparing version 2.3.1 to 2.3.2

CHANGELOG.md

@@ -5,2 +5,9 @@ # Change Log
 
+## [2.3.2](https://github.com/stalniy/ucast/compare/@ucast/mongo@2.3.1...@ucast/mongo@2.3.2) (2020-10-17)
+
+
+### Bug Fixes
+
+* **README:** updates outdated docs ([550a08e](https://github.com/stalniy/ucast/commit/550a08ec1b0d0cd71b9ef432757cbc80aad88965))
+
 ## [2.3.1](https://github.com/stalniy/ucast/compare/@ucast/mongo@2.3.0...@ucast/mongo@2.3.1) (2020-08-24)
@@ -7,0 +14,0 @@

package.json

 {
   "name": "@ucast/mongo",
-  "version": "2.3.1",
+  "version": "2.3.2",
   "description": "[e-mail]:stalniy/ucast.git",
@@ -5,0 +5,0 @@ "main": "dist/es6c/index.js",

README.md

@@ -35,19 +35,33 @@ # UCAST Mongo
 
-To create a parser you need to pass in it parsing instruction. Parsing instruction is an object that defines how a particular operator should be parsed. There are 3 types of `ParsingInstruction`, one for each `Condition`:
+To create a parser you need to pass in it parsing instruction. Parsing instruction is an object that defines how a particular operator should be parsed. There are 3 types of `ParsingInstruction`, one for each AST node type:
 
-* `FieldInstruction`\
-  It represents an instruction for an operator which operates in a field context only. For example, operators `$eq`, `$lt`, `$not`, `$regex`
-* `CompoundInstruction`\
-  It represents an instruction for an operator which operates in a document context and contains nested queries. For example, operators `$and`, `$or`, `$nor`
-* `ValueInstruction`\
-  It represents an instruction for an operator which operates in a document context only. For example, `$where`
+* `field` represents an instruction for an operator which operates in a field context only. For example, operators `$eq`, `$lt`, `$not`, `$regex`
+* `compound` represents an instruction for an operator that aggregates nested queries. For example, operators `$and`, `$or`, `$nor`
+* `document` represents an instruction for an operator which operates in a document context only. For example, `$where` or `$jsonSchema`
 
-### Optimization logic
+It's important to understand that it's not required that parsing instruction with type `field` should be parsed into `FieldCondition`. It can be parsed into `CompoundCondition` as it's done for `$not` operator.
 
-It's important to understand that it's not required for `FieldInstruction` to be parsed into `FieldCondition`. I can be parsed into `CompoundCondition` as it's done for `$not` operator.
+### Parsing instruction
 
-Also some operators like `$and` and `$or` optimize their parsing logic, so if one of that operators contain only one condition it will be resolved to `FieldCondition`.
+A parsing instruction is an object of 3 fields:
 
-As said before `$and` and `$or` operators optimize their representation in case they have a single condition but this is not all. They also recursively collapse conditions from nested operators with the same name. Let's see an example to understand what this means:
+```ts
+const parsingInstruction = {
+  type: 'field' | 'document' | 'compound',
+  validate?(instruction, value) { // optional
+    // throw exception if something is wrong
+  },
+  parse?(instruction, schema, context) { // optional
+    /*
+     * custom logic to parse operator,
+     * returns FieldCondition | DocumentCondition | CompoundCondition
+     */
+  }
+}
+```
 
+### Optimization logic
+
+Some operators like `$and` and `$or` optimize their parsing logic, so if one of that operators contain a single condition it will be resolved to that condition without additional wrapping. They also recursively collapse conditions from nested operators with the same name. Let's see an example to understand what this means:
+
 ```js
@@ -76,3 +90,3 @@ const ast = parser.parse({
 
-**Pay attention**: parser removes `$` prefix from operator names, so the resulting AST operators doesn't have in its `operator` property!
+**Pay attention**: parser removes `$` prefix from operator names
 
@@ -83,5 +97,5 @@ ### Custom Operator
 
-First of all, we need to understand on which level this operator operates (field or document). In this case, `$jsonSchema` clearly operates on document level. It doesn't contain nested MongoDB queries, so it should be defined using `DocumentInstruction`.
+First of all, we need to understand on which level this operator operates (field or document). In this case, `$jsonSchema` clearly operates on document level. It doesn't contain nested MongoDB queries, so it's not a `compound` instruction. So, we are left only with `document` one.
 
-To test that document corresponds to provided json schema, we will use [ajv](https://ajv.js.org/) but it's possible to use any JSON schema validator you want.
+To test that document corresponds to provided json schema, we use [ajv](https://ajv.js.org/) but it's also possible to use a library of your preference.
 
@@ -107,3 +121,3 @@ ```js
 
-In order to use this operator, we need to pass it into `MongoQueryParser` constructor:
+In order to use this operator, we need to pass this instruction into `MongoQueryParser` constructor:
 
@@ -114,3 +128,6 @@ ```js
 
-const parser = new MongoQueryParser({ ...allParsingInstructions, $jsonSchema });
+const parser = new MongoQueryParser({
+  ...allParsingInstructions,
+  $jsonSchema
+});
 const ast = parser.parse({
@@ -133,4 +150,10 @@ $jsonSchema: {
 
-The only thing which is left is to implement a corresponding interpreter.
+The only thing which is left is to implement a corresponding JavaScript interpreter:
 
+```js
+function jsonSchema(condition, object) { // interpreter
+  return condition.value(object);
+}
+```
+
 ## Want to help?
@@ -137,0 +160,0 @@

No alert changes

Improved metrics

Total package byte prevSize

108710

increased by0.58%

Number of lines in readme file

162

increased by16.55%

No dependency changes