Mingo

MongoDB query language for in-memory objects

MongoDBSearch
kofrasa/mingomingo

README

mingo


MongoDB query language for in-memory objects

Install


$ npm install mingo

Features


- Supports dot notation for both _`.`_ and _`.`_ selectors.
- Query and Projection Operators.

For documentation on using operators see mongodb

Browse package docs for modules.

Usage


  1. ```js
  2. // Use as es6 module
  3. import mingo from "mingo";

  5. // or vanilla nodeJS
  6. const mingo = require("mingo");
  7. ```

The main module exports Aggregator, Query, aggregate(), find(), and remove(). Only Query and Projection operators are loaded by default when you require the main module. This is done using the side-effect modulemingo/init/basic and automatically includes pipeline operators; $project, $skip, $limit, and $sort.

Loading Operators


MongoDB query library is huge and you may not need all the operators. If using this library on the server-side where bundle size is not a concern, you can load all operators as shown below.

  1. ```js
  2. // Note that doing this effectively imports the entire library into your bundle and unused operators cannot be tree shaked
  3. import "mingo/init/system";
  4. ```

Or from the node CLI

  1. ```sh
  2. node -r 'mingo/init/system' myscript.js
  3. ```

To support tree-shaking for client side bundles, you can import and register specific operators that will be used in your application.

ES6


  1. ```js
  2. import { useOperators, OperatorType } from "mingo/core";
  3. import { $trunc } from "mingo/operators/expression";
  4. import { $bucket } from "mingo/operators/pipeline";

  6. useOperators(OperatorType.EXPRESSION, { $trunc });
  7. useOperators(OperatorType.PIPELINE, { $bucket });
  8. ```

CommonJS


  1. ```js
  2. const core = require("mingo/core");
  3. const $trunc = require("mingo/operators/expression").$trunc;
  4. const $bucket = require("mingo/operators/pipeline").$bucket;
  5. const useOperators = core.useOperators;
  6. const OperatorType = core.OperatorType;

  8. useOperators(OperatorType.EXPRESSION, { $trunc: $trunc });
  9. useOperators(OperatorType.PIPELINE, { $bucket: $bucket });
  10. ```

Using query to test objects


  1. ```js
  2. import { Query } from "mingo";

  4. // create a query with criteria
  5. // find all grades for homework with score >= 50
  6. let query = new Query({
  7.   type: "homework",
  8.   score: { $gte: 50 }
  9. });

  11. // test if an object matches query
  12. query.test(doc);
  13. ```

Searching and Filtering


  1. ```js
  2. import { Query } from "mingo";

  4. // input is either an Array or any iterable source (i.e Object{next:Function}) including ES6 generators.
  5. let criteria = { score: { $gt: 10 } };

  7. let query = new Query(criteria);

  9. // filter collection with find()
  10. let cursor = query.find(collection);

  12. // alternatively use shorthand
  13. // cursor = mingo.find(collection, criteria)

  15. // sort, skip and limit by chaining
  16. cursor.sort({ student_id: 1, score: -1 }).skip(100).limit(100);

  18. // count matches. exhausts cursor
  19. cursor.count();

  21. // classic cursor iterator (old school)
  22. while (cursor.hasNext()) {
  23.   console.log(cursor.next());
  24. }

  26. // ES6 iterators (new cool)
  27. for (let value of cursor) {
  28.   console.log(value);
  29. }

  31. // all() to retrieve matched objects. exhausts cursor
  32. cursor.all();
  33. ```

Using $jsonSchema operator


To use the $jsonSchema operator, you must register your own JsonSchemaValidator in the options.
No default implementation is provided out of the box so users can use a library with their preferred schema format.

The example below uses Ajv to implement schema validation.

  1. ```js
  2. import { RawObject } from "mingo/types"
  3. import { JsonSchemaValidator } from "mingo/core"
  4. import Ajv, { Schema } from "ajv"

  6. const jsonSchemaValidator: JsonSchemaValidator = (s: RawObject) => {
  7.   const ajv = new Ajv();
  8.   const v = ajv.compile(s as Schema);
  9.   return (o: RawObject) => (v(o) ? true : false);
  10. };

  12. const schema = {
  13.   type: "object",
  14.   required: ["item", "qty", "instock"],
  15.   properties: {
  16.     item: { type: "string" },
  17.     qty: { type: "integer" },
  18.     size: {
  19.       type: "object",
  20.       required: ["uom"],
  21.       properties: {
  22.         uom: { type: "string" },
  23.         h: { type: "number" },
  24.         w: { type: "number" },
  25.       },
  26.     },
  27.     instock: { type: "boolean" },
  28.   },
  29. };

  31. // queries documents using schema validation
  32. find(docs, { $jsonSchema: schema }, {}, { jsonSchemaValidator }).all();
  33. ```

Note: An error is thrown when the $jsonSchema operator is used without a the jsonSchemaValidator configured.

Aggregation Pipeline


  1. ```js
  2. import { Aggregator } from "mingo/aggregator";
  3. import { useOperators, OperatorType } from "mingo/core";
  4. import { $match, $group } from "mingo/operators/pipeline";
  5. import { $min } from "mingo/operators/accumulator";

  7. // ensure the required operators are preloaded prior to using them.
  8. useOperators(OperatorType.PIPELINE, { $match, $group });
  9. useOperators(OperatorType.ACCUMULATOR, { $min });

  11. let agg = new Aggregator([
  12.   { $match: { type: "homework" } },
  13.   { $group: { _id: "$student_id", score: { $min: "$score" } } },
  14.   { $sort: { _id: 1, score: 1 } }
  15. ]);

  17. // return an iterator for streaming results
  18. let stream = agg.stream(collection);

  20. // return all results. same as `stream.all()`
  21. let result = agg.run(collection);
  22. ```