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.

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.

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

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.

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();

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

OR

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

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

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.

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

These operators are exclusive to PipelineJS.

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

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}

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');`

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 »

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

Pull requests are always welcome.

• PipelineJS Documentation
• Star us on GitHub

Apache 2.0