README

NPM npm

GitHub branch checks state Sonar Quality Gate

Sonar Tests Sonar Coverage

GitHub top language

GitHub code size in bytes GitHub commit activity GitHub last commit (branch)

-> Technical documentation <-

mongodb-pipeline-builder

mongodb-pipeline-builder is a pipeline builder for the db.collection.aggregate method and db.aggregate method.

Simplify pipelines by making them more readable
Pipelines are easier to edit.
Pipelines are testable on a dataset.
Pipeline stages appear in an array.
Sequential stages for documents

npm package

`npm i -S mongodb-pipeline-builder`

Usage:

Using `require()`

const PipelineBuilder = require("mongodb-pipeline-builder").PipelineBuilder;
const { EqualityPayload, OnlyPayload, Field } = require('mongodb-pipeline-builder/helpers');
const { LessThanEqual, ArrayElemAt, Equal, Expression } = require('mongodb-pipeline-builder/operators');

Using `import`

import { PipelineBuilder } from 'mongodb-pipeline-builder';
import { EqualityPayload, OnlyPayload, Field } from 'mongodb-pipeline-builder/helpers';
import { LessThanEqual, ArrayElemAt, Equal, Expression } from 'mongodb-pipeline-builder/operators';

Pagination example

const myNewPipeline = new PipelineBuilder( 'myPagination', { debug: true } )
    .Match( Expression( LessThanEqual( '$id', 20 ) ) )
    .Project( OnlyPayload( 'name', 'weight' ) )
    .Paging( 5, 3 ) // 5 per page, page 3
    .getPipeline();

is equivalent to

const myNewPipeline = [ {
    $facet: {
        docs: [
            { $match: { $expr: { $lte: ["$id", 20] } } },
            { $project: { _id: 0, name: 1, weight: 1 } },
            { $skip: 10 },
            { $limit: 5 }
        ],
        count: [
            { $match: { $expr: { $lte: ["$id", 20] } } },
            { $project: { _id: 0, name: 1, weight: 1 } },
            { $count: "totalElements" }
        ]
    }
} ];

No pagination example

const myNewPipeline = new PipelineBuilder( 'user-skills' )
    .Match( Expression( Equal( '$id', 123456 ) ) )
    .Lookup( EqualityPayload( 'profiles', 'profile', 'profileId', 'id' ) )
    .Project( OnlyPayload( 'firstname', 'lastname', 'email' ) )
    .AddFields(
        Field( 'skills', ArrayElemAt( '$profile.skills', 0 ) ),
        Field( 'availability', ArrayElemAt( '$profile.availability', 0 ) )
    )
    .Unset( 'profile' )
    .getPipeline();

is equivalent to

const myNewPipeline = [
    { $match: { $expr: { $eq: ["$id", 123456] } } },
    { $lookup: { from: "profiles", as: "profile", localField: "profileId", foreignField: "id" } },
    { $project: { _id: 0, firstname: 1, lastname: 1, email: 1 } },
    { $addFields: {
        skills: { $arrayElemAt: ["$profile.skills", 0] },
        availability: { $arrayElemAt: ["$profile.availability", 0] }
    } },
    { $unset: "profile" }
];

GetResult method

GetResult(): Promise<GetResultResponse | GetPagingResultResponse>

GetResult() is an asynchronous method that provides a very easy way to use aggregation pipelines on a target (collection or mongoose model having the aggregation method) with either pagination or not.

GetResultResponse

Without pagination, the GetResult() method returns a GetResultResponse object that contains two methods:

GetDocs(): any[] to get the documents found.
GetCount(): number to get the total number of documents found.

const result = await GetResult( target, pipeline ); 
result.GetDocs(); // () => any[]
result.GetCount(); // () => number

GetResult( target, pipeline ).then( result => {
    result.GetDocs(); // () => any[]
    result.GetCount(); // () => number
} );

`GetDocs()` method possibilities:

A particular document can be retrieved by specifying its index as an argument of the `GetDocs()` method.

To get the last document, the argument to provide is the string 'last'.

If the specified index is greater than the index of the last document, GetDocs() will return the last document.

// GetDocs() -> [document0, document1, document2, document3, ..., document51]
result.GetDocs(2); // will return document to index 2, document2
result.GetDocs('last'); // will return the last document, document51
result.GetDocs(99); // will return the last document, document51

GetPagingResultResponse

With pagination, GetResult() returns a GetPagingResultResponse object that contains three methods:

GetDocs() to get the documents found.
GetCount() to get the total number of documents found.
GetTotalPageNumber() to get the total number of pages.

const result = await GetResult(target, pipeline);
result.GetDocs(); // () => any[]
result.GetCount(); // () => number
result.GetTotalPageNumber(); // () => number

GetResult(target, pipeline).then( result => {
    result.GetDocs(); // () => any[]
    result.GetCount(); // () => number
    result.GetTotalPageNumber(); // () => number
} );

-> Try the lib on NPM RunKit with the require method <-

-> Aggregation Pipeline Stages <-

MONGODB NATIVE STAGES:

AddFields
Bucket
BucketAuto
CollStats
Count
Facet
GeoNear
GraphLookup
Group
IndexStats
Limit
ListSessions
Lookup
Match
Merge
Out
PlanCacheStats
Project
Redact
ReplaceRoot
ReplaceWith
Sample
Search
Set
Skip
Sort
SortByCount
UnionWith
Unset
Unwind

CUSTOM STAGE:

Paging

-> Aggregation Pipeline Helpers <-

STAGE HELPERS * :

Bucket ( GroupByPayload )
BucketAuto ( GroupByAutoPayload )
CurrentOp ( OpPayload )
GeoNear ( NearPayload )
Lookup ( ConditionPayload | EqualityPayload )
Merge ( IntoPayload )
Out ( DbCollPayload )
Project ( IgnorePayload | OnlyPayload )
Sample ( SizePayload )
UnionWith ( CollectionPayload )

COMMON HELPERS:

Field: AddFields( Field ** ) | Facet( Field ** ) | Set( Field ** ) | Sort( Field ** )
List

* If no helper is available for a stage, use stage method and pass it a valid value as a parameter.
** One or more Field helper(s) separated by a comma.

___

-> Aggregation Pipeline Operators <-

Usage no npm install needed!