stalniy

@ucast/mongo

All notable changes to this project will be documented in this file.

## [2.3.1](https://github.com/stalniy/ucast/compare/@ucast/mongo@2.3.0...@ucast/mongo@2.3.1) (2020-08-24)

* **types:** exports `RegExpFieldContext`, so ts allows to use typeof on object of instructions ([9a4580d](https://github.com/stalniy/ucast/commit/9a4580d054a6988fc41732de96d108ddb55b269f))

# [2.3.0](https://github.com/stalniy/ucast/compare/@ucast/mongo@2.2.0...@ucast/mongo@2.3.0) (2020-08-20)

* **esm:** adds ESM support via dual loading in package.json for latest Node.js version ([c730f95](https://github.com/stalniy/ucast/commit/c730f9598a4c62589c612403c0ac59ba4aa1600e)), closes [#10](https://github.com/stalniy/ucast/issues/10)

# [2.2.0](https://github.com/stalniy/ucast/compare/@ucast/mongo@2.1.2...@ucast/mongo@2.2.0) (2020-08-18)

* **parser:** adds possibility to set `parse` function ([8a1e388](https://github.com/stalniy/ucast/commit/8a1e388fe1c5722ae322b783101f066d763dfde5)), closes [#9](https://github.com/stalniy/ucast/issues/9)

## [2.1.2](https://github.com/stalniy/ucast/compare/@ucast/mongo@2.1.1...@ucast/mongo@2.1.2) (2020-08-13)

* **parser:** updates @ucast/core and uses `buildAnd` instead of `and` ([154c7a6](https://github.com/stalniy/ucast/commit/154c7a6ff86c3a193592f642416030d0d78ea8ea))

## [2.1.1](https://github.com/stalniy/ucast/compare/@ucast/mongo@2.1.0...@ucast/mongo@2.1.1) (2020-08-13)

* **parser:** replaces `Object.keys().forEach` with `Object.keys() + for(..)` ([003661d](https://github.com/stalniy/ucast/commit/003661da2170243a6bd95233df397eb7c9c4d70a))

# [2.1.0](https://github.com/stalniy/ucast/compare/@ucast/mongo@2.0.0...@ucast/mongo@2.1.0) (2020-08-10)

* **types:** ensure `MongoQuery<any>` returns proper types and can be used with primitive values ([d138ee5](https://github.com/stalniy/ucast/commit/d138ee565bc54d623a283243dc12fc9c930dd2af))

* **types:** exports CustomOperators type and adds `BuildMongoQuery` type ([5ebff17](https://github.com/stalniy/ucast/commit/5ebff1709a448d8683650b26ffff5b7e472c6ac3))

# [2.0.0](https://github.com/stalniy/ucast/compare/@ucast/mongo@1.1.0...@ucast/mongo@2.0.0) (2020-08-08)

* **docs:** removes `$` sign from README examples ([0dc924a](https://github.com/stalniy/ucast/commit/0dc924af72abfefa41ebeac107f1bc070ad796c7))

* **parser:** removes `$` from operator name in resulting AST ([e589a9c](https://github.com/stalniy/ucast/commit/e589a9ce577bc191f48e481fc8aebe5b1164783b))

* **parser:** `MongoQueryParser.parse` returns AST with operator names that doesn't have `$` prefix. This was done to make it easier import/re-export parser instructions and operator interpreters from single package

# [1.1.0](https://github.com/stalniy/ucast/compare/@ucast/mongo@1.0.2...@ucast/mongo@1.1.0) (2020-08-08)

* **mongo:** adds built-in `$all` instruction for MongoQueryParser ([6d3f224](https://github.com/stalniy/ucast/commit/6d3f224bcba1ef6b875f992752f08d01116bbf9b))

* **build:** adds es6cjs format which works few times faster then umd in node env ([4adba3b](https://github.com/stalniy/ucast/commit/4adba3bbf85afe95abfbcee0e36b5edc9d09396f))

## [1.0.2](https://github.com/stalniy/ucast/compare/@ucast/mongo@1.0.1...@ucast/mongo@1.0.2) (2020-07-23)

* **license:** changes mistakenly set MIT license to the correct one - Apache 2.0 ([197363c](https://github.com/stalniy/ucast/commit/197363c321392c742d31b7e1e024d88c0499ce73))

## [1.0.1](https://github.com/stalniy/ucast/compare/@ucast/mongo@1.0.0...@ucast/mongo@1.0.1) (2020-07-10)

* **package:** fixes deps ranges ([c2de9c1](https://github.com/stalniy/ucast/commit/c2de9c1b2d6ad85050f4eeb2635c6cb377200013)), closes [#1](https://github.com/stalniy/ucast/issues/1)

* **mongo:** adds basic implementation for mongo parser and js interpreter ([a8f7271](https://github.com/stalniy/ucast/commit/a8f7271fc893491755e5c7fb522ed42be992e7b1))

* **mongo:** stabilize mongo package ([7d77768](https://github.com/stalniy/ucast/commit/7d7776874be3050026b53ee3b61c3361a89d1b21))

* **mongo:** updates mongo parser to support ValueParsingInstruction ([b918c34](https://github.com/stalniy/ucast/commit/b918c34224a5b60f3f1aa16197587f279b0e3e3a))

* **package:** reverts root package.json to fix CI ([277deb5](https://github.com/stalniy/ucast/commit/277deb561bc2a74a2c98170608805ded57802d7d))

import { CompoundInstruction, FieldInstruction, DocumentInstruction, Comparable, FieldParsingContext } from '@ucast/core';

export declare const $and: CompoundInstruction<MongoQuery<any>[]>;

export declare const $or: CompoundInstruction<(import("./types").MongoQueryOperators<any> | ({

} & import("./types").MongoQueryTopLevelOperators<any>))[], {}>;

export declare const $nor: CompoundInstruction<MongoQuery<any>[]>;

export declare const $not: FieldInstruction<MongoQuery<any> | RegExp>;

export declare const $elemMatch: FieldInstruction<MongoQuery<any>>;

export declare const $size: FieldInstruction<number>;

export declare const $in: FieldInstruction<unknown[]>;

export declare const $nin: FieldInstruction<unknown[], FieldParsingContext>;

export declare const $all: FieldInstruction<unknown[], FieldParsingContext>;

export declare const $mod: FieldInstruction<[number, number]>;

export declare const $exists: FieldInstruction<boolean>;

export declare const $gte: FieldInstruction<Comparable>;

export declare const $gt: FieldInstruction<string | number | Date, FieldParsingContext>;

export declare const $lt: FieldInstruction<string | number | Date, FieldParsingContext>;

export declare const $lte: FieldInstruction<string | number | Date, FieldParsingContext>;

export declare const $eq: FieldInstruction;

export declare const $ne: FieldInstruction<unknown, FieldParsingContext>;

interface RegExpFieldContext extends FieldParsingContext {

export interface RegExpFieldContext extends FieldParsingContext {

export declare const $regex: FieldInstruction<string | RegExp, RegExpFieldContext>;

export declare const $options: FieldInstruction;

export declare const $where: DocumentInstruction<() => boolean>;

  "description": "git@github.com:stalniy/ucast.git",

    "prebuild": "rm -rf dist/* && npm run build.types",

    "build": "rollup -c ../../rollup.config.js -n ucast.mongo -g @ucast/core:ucast.core",

    "lint": "eslint --ext .js,.ts src/ spec/",

    "test": "mocha -r ts-node/register spec/*",

    "coverage": "nyc -n src npm run test && nyc report --reporter=lcov",

    "prerelease": "npm run lint && npm test && NODE_ENV=production npm run build",

    "release": "semantic-release -e ../../semantic-release.js"

    "url": "git+https://github.com/stalniy/ucast.git"

  "author": "Sergii Stotskyi <sergiy.stotskiy@freaksidea.com>",

    "url": "https://github.com/stalniy/ucast/issues"

  "homepage": "https://github.com/stalniy/ucast#readme",

    "@babel/plugin-proposal-class-properties": "^7.10.4",

    "@babel/plugin-proposal-object-rest-spread": "^7.10.4",

    "@babel/plugin-transform-typescript": "^7.10.1",

    "@rollup/plugin-commonjs": "^14.0.0",

    "@rollup/plugin-node-resolve": "^8.0.1",

    "@semantic-release/changelog": "^5.0.1",

    "@semantic-release/github": "^7.0.7",

    "@typescript-eslint/eslint-plugin": "^3.6.0",

    "eslint-config-airbnb-base": "^14.2.0",

    "eslint-config-airbnb-typescript": "^8.0.2",

[![@ucast/mongo NPM version](https://badge.fury.io/js/%40ucast%2Fmongo.svg)](https://badge.fury.io/js/%40ucast%2Fmongo)

[![](https://img.shields.io/npm/dm/%40ucast%2Fmongo.svg)](https://www.npmjs.com/package/%40ucast%2Fmongo)

[![UCAST join the chat](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/stalniy-ucast/community)

This package is a part of [ucast] ecosystem. It provides a parser that can parse [MongoDB query](https://docs.mongodb.com/manual/reference/operator/query/) into conditions AST.

[ucast]: https://github.com/stalniy/ucast

To parse MongoDB query into conditions AST, you need to create a `MongoQueryParser` instance:

import { MongoQueryParser, allParsingInstructions } from '@ucast/mongo';

const parser = new MongoQueryParser(allParsingInstructions);

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`:

  It represents an instruction for an operator which operates in a field context only. For example, operators `$eq`, `$lt`, `$not`, `$regex`

  It represents an instruction for an operator which operates in a document context and contains nested queries. For example, operators `$and`, `$or`, `$nor`

  It represents an instruction for an operator which operates in a document context only. For example, `$where`

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.

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`.

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:

     FieldCondition { operator: "eq", field: "a", value: 1 },

     FieldCondition { operator: "eq", field: "b", value: 2 },

     FieldCondition { operator: "eq", field: "c", value: 3 },

This optimization logic helps to speed up interpreter's execution time, instead of going deeply over tree-like structure we have a plain structure of all conditions under a single compound condition.

**Pay attention**: parser removes `$` prefix from operator names, so the resulting AST operators doesn't have in its `operator` property!

In order for an operator to be parsed, it needs to define a parsing instruction. Let's implement a custom instruction which checks that object corresponds to a particular [json schema](https://json-schema.org/).

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`.

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.

import { DocumentInstruction, DocumentCondition } from '@ucast/core';

export const $jsonSchema: DocumentInstruction = {

    if (!value || typeof value !== 'object') {

      throw new Error(`"${instruction.name}" expects to receive an object`)

    return new DocumentCondition(instruction.name, ajv.compile(schema));

[contributing]: https://github.com/stalniy/uscast/blob/master/CONTRIBUTING.md

[contributing]: https://github.com/stalniy/ucast/blob/master/CONTRIBUTING.md

		{
		"name": "@ucast/mongo",
		"version": "2.3.0",
		"version": "2.3.1",
		"description": "git@github.com:stalniy/ucast.git",
		@@ -5,0 +5,0 @@ "main": "dist/es6c/index.js",

Improved metrics

Worsened metrics

		@@ -5,2 +5,9 @@ # Change Log

		## [2.3.1](https://github.com/stalniy/ucast/compare/@ucast/mongo@2.3.0...@ucast/mongo@2.3.1) (2020-08-24)


		### Bug Fixes

		* types: exports `RegExpFieldContext`, so ts allows to use typeof on object of instructions ([9a4580d](https://github.com/stalniy/ucast/commit/9a4580d054a6988fc41732de96d108ddb55b269f))

		# [2.3.0](https://github.com/stalniy/ucast/compare/@ucast/mongo@2.2.0...@ucast/mongo@2.3.0) (2020-08-20)
		@@ -7,0 +14,0 @@

		@@ -22,3 +22,3 @@ import { CompoundInstruction, FieldInstruction, DocumentInstruction, Comparable, FieldParsingContext } from '@ucast/core';
		export declare const $ne: FieldInstruction<unknown, FieldParsingContext>;
		interface RegExpFieldContext extends FieldParsingContext {
		export interface RegExpFieldContext extends FieldParsingContext {
		query: {
		@@ -31,2 +31,1 @@ $options?: string;
		export declare const $where: DocumentInstruction<() => boolean>;
		export {};

		@@ -138,2 +138,2 @@ # UCAST Mongo

		[contributing]: https://github.com/stalniy/uscast/blob/master/CONTRIBUTING.md
		[contributing]: https://github.com/stalniy/ucast/blob/master/CONTRIBUTING.md