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.

Compatibility

The project is written in TypeScript, and targets ES2023.

This is a pure ESM package.

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({
  $set: {
    my: 'Pleasure',
  },
})

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

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,
    },
  },
])

// logs [{ _id: new ObjectId("507f191e810c19729de860ea"), value: 42 }]
console.log(aggregate(documents))

Supported features

Query Operators

Array

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

Bitwise

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

Comparison

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

Data Type

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

Geospatial

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

Logical

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

Miscellaneous

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

Update Operators

Array

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

Modifiers

• [x] $each
• [x] $position
• [x] $slice
• [x] $sort Single sort key/value.

Bitwise

• [ ] $bit

Fields

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

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
• [ ] $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

Expressions Associated with Accumulators

• [x] $avg
• [ ] $max
• [ ] $median
• [ ] $min
• [ ] $percentile
• [ ] $setUnion
• [ ] $stdDevPop
• [ ] $stdDevSamp
• [x] $sum

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
• [x] $regexMatch
• [ ] $replaceOne
• [ ] $replaceAll
• [ ] $rtrim
• [ ] $split
• [ ] $strLenBytes
• [ ] $strLenCP
• [ ] $strcasecmp
• [ ] $substr
• [ ] $substrBytes
• [ ] $substrCP
• [x] $toLower
• [x] $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
• [x] $toDate
• [ ] $toDecimal
• [x] $toDouble
• [x] $toInt
• [x] $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.