mongo-pipeline-kit
Advanced tools
A feature-rich MongoDB pipeline builder kit for creating, reusing, and managing aggregation pipelines with enhanced JSON support and advanced utilities
A feature-rich MongoDB pipeline builder kit for creating, reusing, and managing aggregation pipelines with ease. Now with enhanced JSON support, pipeline utilities, and advanced analysis capabilities.
npm install mongo-pipeline-kit
import { PipelineBuilder } from "mongo-pipeline-kit";
// Create a new pipeline builder
const builder = new PipelineBuilder();
// Add stages to your pipeline
const pipeline = builder
.match({ status: "active" })
.group({
_id: "$category",
total: { $sum: 1 },
items: { $push: "$$ROOT" },
})
.sort({ total: -1 })
.limit(10)
.build();
// Use the pipeline with MongoDB
const results = await collection.aggregate(pipeline).toArray();
import { PipelineBuilder } from "mongo-pipeline-kit";
const builder = new PipelineBuilder()
.match({ status: "active" })
.group({ _id: "$category", count: { $sum: 1 } })
.sort({ count: -1 })
.limit(10);
// Get JSON string (compact)
const jsonString = builder.toJSON();
console.log(jsonString);
// Output: [{"$match":{"status":"active"}},{"$group":{"_id":"$category","count":{"$sum":1}}},{"$sort":{"count":-1}},{"$limit":10}]
// Get JSON string (pretty formatted)
const prettyJson = builder.toJSON(true);
console.log(prettyJson);
// Output: Formatted JSON with indentation
// Export with metadata
const exportData = builder.exportWithMetadata({
description: "Active users by category",
author: "John Doe",
version: "1.0.0",
});
import { PipelineUtils } from "mongo-pipeline-kit";
const jsonString = `[
{"$match": {"status": "active"}},
{"$group": {"_id": "$category", "count": {"$sum": 1}}},
{"$sort": {"count": -1}},
{"$limit": 10}
]`;
// Parse JSON string to pipeline
const pipeline = PipelineUtils.fromJSON(jsonString);
// Use with PipelineBuilder
const builder = new PipelineBuilder();
pipeline.forEach((stage) => builder.addStage(stage));
import { PipelineUtils } from "mongo-pipeline-kit";
const pipeline = [
{ $match: { status: "active" } },
{ $group: { _id: "$category", count: { $sum: 1 } } },
{ $sort: { count: -1 } },
{ $limit: 10 },
];
// Get pipeline statistics
const stats = PipelineUtils.getStats(pipeline);
console.log(stats);
// Output:
// {
// stageCount: 4,
// stageTypes: { '$match': 1, '$group': 1, '$sort': 1, '$limit': 1 },
// totalSize: 156,
// estimatedComplexity: 6
// }
// Get human-readable description
const description = PipelineUtils.describe(pipeline);
console.log(description);
// Clone a pipeline
const clonedPipeline = PipelineUtils.clone(pipeline);
// Filter stages by type
const matchStages = PipelineUtils.filterByStageType(pipeline, "$match");
// Remove specific stage type
const pipelineWithoutLimit = PipelineUtils.removeStageType(pipeline, "$limit");
// Insert a stage at specific position
const newPipeline = PipelineUtils.insertStage(pipeline, 1, {
$addFields: { processed: true },
});
// Replace a stage
const modifiedPipeline = PipelineUtils.replaceStage(pipeline, 0, {
$match: { status: "inactive" },
});
const pipeline1 = [
{ $match: { status: "active" } },
{ $group: { _id: "$category", count: { $sum: 1 } } },
];
const pipeline2 = [
{ $match: { status: "active" } },
{ $group: { _id: "$category", count: { $sum: 1 } } },
{ $sort: { count: -1 } },
];
const comparison = PipelineUtils.compare(pipeline1, pipeline2);
console.log(comparison);
import { PipelineBuilder, PipelineStage } from "mongo-pipeline-kit";
// Define a reusable pipeline component
const activeUsersStage: PipelineStage = {
$match: {
status: "active",
lastLogin: { $gte: new Date(Date.now() - 30 * 24 * 60 * 60 * 1000) },
},
};
// Use the component in multiple pipelines
const userStatsPipeline = builder
.addStage(activeUsersStage)
.group({
_id: "$role",
count: { $sum: 1 },
})
.build();
import { PipelineBuilder, PipelineComposer } from "mongo-pipeline-kit";
const composer = new PipelineComposer();
// Create separate pipeline segments
const filteringPipeline = builder.match({ status: "active" }).build();
const aggregationPipeline = builder
.group({
_id: "$category",
total: { $sum: "$amount" },
})
.build();
// Compose pipelines
const finalPipeline = composer
.compose(filteringPipeline, aggregationPipeline)
.build();
// Export composed pipeline with metadata
const exportData = composer.exportWithMetadata({
description: "Composed pipeline for user analytics",
tags: ["analytics", "users"],
});
The main class for building MongoDB aggregation pipelines.
addFields(fields: object): Add a $addFields stageaddStage(stage: PipelineStage): Add a custom pipeline stagebucket(options: object): Add a $bucket stagebucketAuto(options: object): Add a $bucketAuto stagebuild(): Build the final pipeline arraycollStats(options: object): Add a $collStats stagecount(fieldName: string): Add a $count stagefacet(options: object): Add a $facet stagegeoNear(options: object): Add a $geoNear stagegraphLookup(options: object): Add a $graphLookup stagegroup(expression: object): Add a $group stageindexStats(options: object): Add a $indexStats stagelimit(n: number): Add a $limit stagelookup(options: object): Add a $lookup stagematch(condition: object): Add a $match stagemerge(options: object): Add a $merge stageout(collection: string | object): Add an $out stageproject(projection: object): Add a $project stageredact(expression: object): Add a $redact stagereplaceRoot(newRoot: object): Add a $replaceRoot stagereplaceWith(newRoot: object): Add a $replaceWith stagesample(options: { size: number }): Add a $sample stagesetWindowFields(options: object): Add a $setWindowFields stageskip(n: number): Add a $skip stagesort(sort: object): Add a $sort stagesortByCount(expression: any): Add a $sortByCount stageunionWith(options: string | object): Add a $unionWith stageunset(fields: string | string[]): Add an $unset stageunwind(field: string | object): Add a $unwind stagetoJSON(pretty?: boolean): Convert pipeline to JSON stringtoObject(): Get pipeline as plain objectexportWithMetadata(metadata): Export pipeline with additional metadatatoString(): Get human-readable string representationclear(): Clear all stages from the pipelinegetStageCount(): Get the current number of stagesgetStage(index: number): Get a specific stagereplaceStage(index: number, stage: PipelineStage): Replace a stageremoveStage(index: number): Remove a stageUtility class for composing and reusing pipeline segments.
compose(...pipelines: Pipeline[]): Compose multiple pipelinesextend(basePipeline: Pipeline, extension: Pipeline): Extend an existing pipelinevalidate(pipeline: Pipeline): Validate a pipeline structuretoJSON(pretty?: boolean): Convert composed pipeline to JSONtoObject(): Get composed pipeline as plain objectexportWithMetadata(metadata): Export with metadatatoString(): Get human-readable representationhasStage(operator: string): Check if pipeline contains specific stage typegetStagesByType(operator: string): Get all stages of a specific typeStatic utility class for pipeline operations and analysis.
fromJSON(jsonString: string): Parse JSON string to pipelinetoJSON(pipeline: Pipeline, pretty?: boolean): Convert pipeline to JSONvalidate(pipeline: Pipeline, options?): Validate pipeline structureclone(pipeline: Pipeline): Deep copy pipelinegetStats(pipeline: Pipeline): Get pipeline statisticsdescribe(pipeline: Pipeline): Get human-readable descriptioncompare(pipeline1: Pipeline, pipeline2: Pipeline): Compare two pipelinesfilterByStageType(pipeline: Pipeline, operator: string): Filter stages by typeremoveStageType(pipeline: Pipeline, operator: string): Remove stages by typeinsertStage(pipeline: Pipeline, index: number, stage: PipelineStage): Insert stagereplaceStage(pipeline: Pipeline, index: number, stage: PipelineStage): Replace stageFor comprehensive examples of all features, see EXAMPLES.md.
If you encounter any issues or need help with mongo-pipeline-kit:
For detailed information about reporting issues, see ISSUES.md.
We welcome contributions! Please see our Contributing Guide for details on how to get started.
For information about publishing new versions, please refer to our Publishing Guide.
MIT
[0.3.3] - 2024-01-15
FAQs
A feature-rich MongoDB pipeline builder kit for creating, reusing, and managing aggregation pipelines with enhanced JSON support and advanced utilities
We found that mongo-pipeline-kit demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Following last week’s supply chain attack, Nx published findings on the GitHub Actions exploit and moved npm publishing to Trusted Publishers.
Security News
AGENTS.md is a fast-growing open format giving AI coding agents a shared, predictable way to understand project setup, style, and workflows.
Security News
/Research
Malicious npm package impersonates Nodemailer and drains wallets by hijacking crypto transactions across multiple blockchains.