mql-match

This project is a MQL (MongoDB Query Language) compiler. Filter, Update, and Aggregation queries are supported. See the support table table for more info.

Why

This project can be useful to mock some basic functionality of MongoDB's driver or simply using its query syntax for object matching.

Example

import { ObjectId } from 'bson' // or 'mongodb'
import {
  compileAggregationExpression,
  compileAggregationPipeline,
  compileFilterQuery,
  compileUpdateQuery
} from 'mql-match'

const documents = [
  {
    _id: new ObjectId("507f1f77bcf86cd799439011"),
    value: 130
  },
  {
    _id: new ObjectId("507f191e810c19729de860ea"),
    value: 42
  }
]

const match = compileFilterQuery({
  _id: new ObjectId("507f1f77bcf86cd799439011")
})

// logs { _id: new ObjectId("507f1f77bcf86cd799439011"), value: 130 }
console.log(documents.find(match))

const update = compileUpdateQuery({
  $setOnInsert: {
    hello: 'World'
  },
  $set: {
    my: 'Pleasure'
  }
})

const oldObject = { _id: "my_doc" }
update(oldObject)
// logs { _id: 'my_doc', my: 'Pleasure' }
console.log(oldObject)

const newObject = {}
// the `true` say that this document was inserted
update(newObject, true)
// logs { _id: new ObjectId("xxxxxxxxxxxxxxxxxxxxxxxx"), hello: 'World', my: 'Pleasure' }
console.log(newObject)

const map = compileAggregationExpression({
  _id: 0,
  item: 1,
  discount: {
    $cond: {
      if: { $gte: ['$qty', 250] },
      then: 30,
      else: 20
    }
  }
})

// logs { item: 'xyz1', discount: 30 }
console.log(map({ _id: 3, item: 'xyz1', qty: 250 }))

// Returns a function that accepts an iterable (both sync or async) and returns an async iterable
const aggregate = compileAggregationPipeline([
  {
    $match: {
      value: 42
    }
  }
])

async function pipelineExample () {
  // logs { _id: new ObjectId("507f191e810c19729de860ea"), value: 42 }
  for await (const document of aggregate(documents)) {
    console.log(document)
  }
}

pipelineExample().catch(err => console.error(err))

Supported features

Query Operators

Comparison

• [x] $eq
• [x] $gt
• [x] $gte
• [x] $in
• [x] $lt
• [x] $lte
• [x] $ne
• [x] $nin

Logical

• [x] $and
• [x] $not
• [x] $nor
• [x] $or

Element

• [x] $exists
• [x] $type

Evaluation

• [x] $expr
• [ ] $jsonSchema
• [x] $mod
• [x] $regex
• [ ] $text
• [ ] $where

Geospatial

• [ ] $geoIntersects
• [ ] $geoWithin
• [ ] $near
• [ ] $nearSphere

Array

• [x] $all
• [x] $elemMatch
• [x] $size

Bitwise

• [ ] $bitsAllClear
• [ ] $bitsAllSet
• [ ] $bitsAnyClear
• [ ] $bitsAnySet

Projection

• [ ] $
• [ ] $elemMatch
• [ ] $meta
• [ ] $slice

Miscellaneous

• [x] $comment Stub.
• [ ] $rand

Update Operators

Fields

• [x] $currentDate
• [x] $inc
• [x] $min
• [x] $max
• [x] $mul
• [x] $rename
• [x] $set
• [x] $setOnInsert
• [x] $unset

Array

• [ ] $
• [ ] $[]
• [ ] $[<identifier>]
• [x] $addToSet
• [x] $pop
• [x] $pull
• [x] $push
• [x] $pullAll

Modifiers

• [x] $each
• [x] $position
• [x] $slice
• [x] $sort Limited to a single field.

Bitwise

• [ ] $bit

Aggregation Pipeline Stages

• [x] $addFields
• [ ] $bucket
• [ ] $bucketAuto
• [ ] $changeStream
• [ ] $collStats
• [x] $count
• [ ] $currentOp
• [ ] $densify
• [ ] $documents
• [ ] $facet
• [ ] $fill
• [ ] $geoNear
• [ ] $graphLookup
• [ ] $group
• [ ] $indexStats
• [x] $limit
• [ ] $listLocalSessions
• [ ] $listSessions
• [ ] $lookup
• [x] $match
• [ ] $merge
• [ ] $out
• [ ] $planCacheStats
• [x] $project
• [ ] $redact
• [ ] $replaceRoot
• [ ] $replaceWith
• [ ] $sample
• [ ] $search
• [ ] $searchMeta
• [x] $set
• [ ] $setWindowFields
• [x] $skip
• [x] $sort
• [ ] $sortByCount
• [ ] $unionWith
• [x] $unset
• [x] $unwind

Aggregation Variables

• [x] $$NOW
• [x] $$CLUSTER_TIME
• [x] $$ROOT
• [ ] $$CURRENT
• [ ] $$REMOVE
• [ ] $$DESCEND
• [ ] $$PRUNE

Aggregation Pipeline Operators

Operators not listed here are currently not supported. Feel free to open an GitHub Issue if you need something in particular.

Arithmetic Expression Operators

• [x] $abs
• [x] $add
• [x] $ceil
• [x] $divide
• [x] $exp
• [x] $floor
• [x] $ln
• [x] $log
• [x] $log10
• [x] $mod
• [x] $multiply
• [x] $pow
• [x] $round
• [x] $sqrt
• [x] $subtract
• [x] $trunc

Array Expression Operators

• [ ] $arrayElemAt
• [ ] $arrayToObject
• [x] $concatArrays
• [ ] $filter
• [ ] $first
• [ ] $firstN
• [x] $in
• [ ] $indexOfArray
• [x] $isArray
• [ ] $last
• [ ] $lastN
• [ ] $map
• [ ] $maxN
• [ ] $minN
• [ ] $objectToArray
• [ ] $range
• [ ] $reduce
• [ ] $reverseArray
• [x] $size
• [ ] $slice
• [ ] $sortArray
• [ ] $zip

Boolean Expression Operators

• [x] $and
• [x] $not
• [x] $or

Comparison Expression Operators

• [x] $cmp
• [x] $eq
• [x] $gt
• [x] $gte
• [x] $lt
• [x] $lte
• [x] $ne

Conditional Expression Operators

• [x] $cond
• [x] $ifNull
• [x] $switch

Custom Aggregation Expression Operators

• [ ] $accumulator
• [ ] $function

Data Size Operators

• [ ] $binarySize
• [ ] $bsonSize

Date Expression Operators

• [ ] $dateAdd
• [ ] $dateDiff
• [ ] $dateFromParts
• [ ] $dateFromString
• [ ] $dateSubtract
• [ ] $dateToParts
• [ ] $dateToString
• [ ] $dateTrunc
• [ ] $dayOfMonth
• [ ] $dayOfWeek
• [ ] $dayOfYear
• [ ] $hour
• [ ] $isoDayOfWeek
• [ ] $isoWeek
• [ ] $isoWeekYear
• [ ] $millisecond
• [ ] $minute
• [ ] $month
• [ ] $second
• [ ] $toDate
• [ ] $week
• [ ] $year

Literal Expression Operator

• [x] $literal No validation.

Miscellaneous Operators

• [ ] $getField
• [ ] $rand
• [ ] $sampleRate

Object Expression Operators

• [ ] $mergeObjects
• [ ] $objectToArray
• [ ] $setField

Set Expression Operators

• [ ] $allElementsTrue
• [ ] $anyElementTrue
• [ ] $setDifference
• [ ] $setEquals
• [ ] $setIntersection
• [ ] $setIsSubset
• [ ] $setUnion

String Expression Operators

• [ ] $concat
• [ ] $dateFromString
• [ ] $dateToString
• [ ] $indexOfBytes
• [ ] $indexOfCP
• [ ] $ltrim
• [ ] $regexFind
• [ ] $regexFindAll
• [ ] $regexMatch
• [ ] $replaceOne
• [ ] $replaceAll
• [ ] $rtrim
• [ ] $split
• [ ] $strLenBytes
• [ ] $strLenCP
• [ ] $strcasecmp
• [ ] $substr
• [ ] $substrBytes
• [ ] $substrCP
• [ ] $toLower
• [ ] $toString
• [ ] $trim
• [ ] $toUpper

Text Expression Operator

• [ ] $meta

Timestamp Expression Operators

• [ ] $tsIncrement
• [ ] $tsSecond

Trigonometry Expression Operators

• [ ] $sin
• [ ] $cos
• [ ] $tan
• [ ] $asin
• [ ] $acos
• [ ] $atan
• [ ] $atan2
• [ ] $asinh
• [ ] $acosh
• [ ] $atanh
• [ ] $sinh
• [ ] $cosh
• [ ] $tanh
• [ ] $degreesToRadians
• [ ] $radiansToDegrees

Type Expression Operators

• [x] $convert
• [x] $isNumber
• [x] $toBool
• [ ] $toDate
• [ ] $toDecimal
• [x] $toDouble
• [ ] $toInt
• [ ] $toLong
• [x] $toObjectId
• [x] $toString
• [x] $type Adds "unknown" type.

Support

If this library helps you in your organization, you can show some love by giving the repo a star or support by making a nominal monetary contribution.