mongodb-pipelinejs

MongoDB PipelineJS

Abbreviated syntax for authoring MongoDB aggregation pipelines (and more).

PipelineJS attempts to provide a concise typed interface for writing MongoDB aggregations in nodejs projects.

Other features that may be commonly found useful are also available.

Browse the API Documentation for implementation details.

Syntax Comparison

Without PipelineJS:

{ $map: {
    input: { $filter: {
      input: '$myArray',
      as: 'item',
      cond: $and('$$item.a', $or('$$item.b', '$$item.c')),
    },
    as: 'stockedItem',
    in: { $multiply: ['$$stockedItem.quantity', '$$stockedItem.qtyDiscount'] },
} }

What do you do with all those braces—without PipelineJS? Your linter might enforce one opening brace per-line if your preference doesn't. Either way, the above example is a klunky mess.

With PipelineJS: (Static Notation)

$map(
  $filter('$myArray', 'item', $gte('$$item.quantity', 1)),
  'stockedItem',
  $multiply('$$stockedItem.quantity', '$$stockedItem.price'),
)

With PipelineJS: (Object Notation)

$map($filter('$myArray').as('item').cond($gte('$$item.quanity', 1)))
  .as('stockedItem')
  .in($multiply('$$stockedItem.quantity', '$$stockedItem.price'))

With PipelineJS: (Mixed Notation)

// Using object notation with $map for clean meaningful lines
// Using static notation with $filter since it fits on a single line cleanly
$map($filter('$myArray', 'item', $and('$$item.a', $or('$$item.b', '$$item.c')))).
  .as('stockedItem')
  .in($multiply('$$stockedItem.quantity', '$$stockedItem.price'))

With PipelineJS: (Upcoming release)

// Use default variable name
$map($filter('$myArray', '$$this.inStock')).in($multiply('$$this.quantity', '$$this.price'))

PipelineJS is what you already expect! PipelineJS nearly mimics the MongoDB aggregation syntax. There is nominal learning required to start writing cleaner aggregations today!

MongoDB has numerous pipeline stages and operators. PipelineJS aims to support them all. As demonstrated above, PipelineJS provides the means to compose aggregations in an abbreviated fashion.

Built-in Extras

PipelineJS includes some extras that provide additional functionality beyond MongoDB's supported operators.

• Safe-Operators
  Avoid runtime type errors using Safe Operators. details
• Utility Operators
  Some extra operator-like helpers that can be useful. details
• Standard Rounding
  Provides alternative numerical rounding commonly expected. details

Installation

Add mongodb-pipelinejs to your MongoDB project:

With Yarn: yarn add mongodb-pipelinejs

With NPM: npm install mongodb-pipelinejs

It is recommended to lock npm to the patch version (using "~") since breaking changes may be introduced in minor versions prior to a stable 1.0 release.

Usage

Typescript support is included but needs refinement.

The example below depicts an example aggregation using PipelineJS. What's not shown here is the default syntax that is replaced.

// Using the dollar-sign ($) closely resembles MongoDB's operator naming
// convention and provides quick access to all operators.
const $ = require('mongodb-pipelinejs');

mongoDB.collection('transactions').aggregate([
  $.match({
    userId: MY_USER_ID,
    amount: $.gte(100),
    type: $.in(['sale', 'transfer']),
    status: $.neq('new'),
  }),
  $.redact($.switch('$$PRUNE')
    .case($.eq('$type', 'sale'), '$$KEEP'),
    .case($.eq('$type', 'transfer'), '$$PRUNE'),
  }),
  $.addFields({
    payments: $.filter(
      '$payments',
      'payment',
      $.in('$$payment.status', ['complete', 'approved']),
    ),
  }),
  $.unwind('$payments'),
  $.group({
    _id: '$transactionId',
    payments: $.push('$payments.paymentId'),
    amountDue: $.last('$amount'),
    amountPaid: $.sum('$payments.amount'),
  })
  $.unwind('$payments', true)
]).toArray();

Use Minified Build

const $ = require('mongodb-pipelinejs/min');

OR

import * as $ from 'mongodb-pipelinejs/min';

Explicit Inclusion Style

// Include stages an operators only as needed
const { $match, $group, $sort } = require('mongodb-pipelinejs');

Purpose

In a nutshell, PipelineJS can allow for writing aggregations with less syntatical characters—less array brackets ([ & ]) and fewer object braces ({ & }).

For some linting configurations, using PipelineJS can result in fewer nominal lines. Eg. Less lines that contain a single opening or closing delimeter.

For those who use it, PipelineJS can offer the advantage of code completion and similar inflection utilities.

Safe Operators

Some operators, commonly mathematical operators, will cause the database server to complain if input to the operator doesn't resolve to the expected type.

PipelineJS's "Safe Operators" are simply shorts that ensure the operator input resolves to the correct type—often times avoiding a fatal error.

Some safe operators are presently included for these circumstances:

• $addSafe
• $concatArraysSafe
• $concatSafe
• $divideSafe
• $multiplySafe
• $subtractSafe

Utility Operators

These operators are exclusive to PipelineJS.

• $arrayElemFirst
• $arrayElemLast
• $ensureArray
• $ensureNumber
• $ensureString
• $if
• $increment
• $decrement
• $roundStandard

Rounding

MongoDB's built-in $round operator behaves differently than some might expect. PipelineJS includes a more standard rounding operator: $roundStandard.

With the sample documents:

{_id : 1, "value" : 10.5},
{_id : 2, "value" : 11.5},
{_id : 3, "value" : 12.5},
{_id : 4, "value" : 13.5}

MongoDB's default rounding with $round : [ "$value", 0] results in:

{_id : 1, "value" : 10},
{_id : 2, "value" : 12},
{_id : 3, "value" : 12},
{_id : 4, "value" : 14}

PipelineJS's rounding with $roundStandard('$value', 0) results in:

{_id : 1, "value" : 11},
{_id : 2, "value" : 12},
{_id : 3, "value" : 13},
{_id : 4, "value" : 14}

Mongo Round

PipelineJS can be used in lieu of mongo-round which is no longer maintained.

Change:

const round = require('mongo-round');

To:

const { roundStandard: round } = require('mongodb-pipelinejs');`

Documentation

Aside from a few niceties, the documentation is an abbreviation of the official MongoDB documentation—with specific API/interface information and usage examples.

Browse API Documentation »

Feedback (bugs, feature requests, etc)

Found a missing or incorrect operator?.. have an idea for a super handy operator? Let us know by posting an issue

Contributing

Pull requests are always welcome.

Next Steps

• PipelineJS Documentation
• Star us on GitHub

License

Apache 2.0