types(aggregate): add $firstN, $lastN, $bottom, $bottomN, $minN and $maxN operators

Author: mlomnicki

test/types/PipelineStage.test.ts

@@ -217,6 +217,8 @@ const project14: PipelineStage = {
   }
 };
 const project15: PipelineStage = { $project: { item: 1, result: { $not: [{ $gt: ['$qty', 250] }] } } };
+const project16: PipelineStage = { $project: { maxScores: { $maxN: { input: '$scores', n: 3 } } } };
+const project17: PipelineStage = { $project: { first3Scores: { $firstN: { input: '$scores', n: 3 } } } };
 
 const sort1: PipelineStage = { $sort: { count: -1 } };
 const sortByCount1: PipelineStage = { $sortByCount: '$tags' };
@@ -311,6 +313,21 @@ const setWindowFields4: PipelineStage = {
   }
 };
 
+const setWindowFields5: PipelineStage = {
+  $setWindowFields: {
+    partitionBy: '$gameId',
+    sortBy: { score: 1 },
+    output: {
+      minScores: {
+        $firstN: { input: '$score', n: 3 },
+      },
+      maxScores: {
+        $lastN: { input: '$score', n: 3 },
+      }
+    }
+  }
+};
+
 const setWindowFieldsLinearFill: PipelineStage = {
   $setWindowFields: {
     partitionBy: '$stock',
@@ -419,6 +436,27 @@ const group5: PipelineStage = {
   }
 };
 const group6: PipelineStage = { $group: { _id: '$author', books: { $push: '$title' } } };
+const group7: PipelineStage = {
+  $group: {
+    _id: '$gameId',
+    topPlayers: {
+      $topN: {
+        output: ['$playerId', '$score'],
+        sortBy: { score: -1 },
+        n: 3
+      }
+    },
+    bottomPlayers: {
+      $bottomN: {
+        output: ['$playerId', '$score'],
+        sortBy: { score: 1 },
+        n: 3
+      }
+    },
+    maxScores: { $maxN: { input: '$score', n: 3 } },
+    minScores: { $minN: { input: '$score', n: 3 } },
+  }
+}
 
 const stages1: PipelineStage[] = [
   // First Stage

test/types/expressions.test.ts

@@ -79,6 +79,49 @@ const timewithOffset430DateToString: Expression = { $dateToString: { format: '%H
 const minutesOffsetNYDateToString: Expression = { $dateToString: { format: '%Z', date: '$date', timezone: 'America/New_York' } };
 const minutesOffset430DateToString: Expression = { $dateToString: { format: '%Z', date: '$date', timezone: '+04:30' } };
 
+const bottom: Expression.Bottom = {
+  $bottom: {
+    output: ['$playerId', '$score'],
+    sortBy: { score: 1 }
+  }
+}
+
+const bottomN: Expression.BottomN = {
+  $bottomN: {
+    output: ['$playerId', '$score'],
+    sortBy: { score: 1 },
+    n: 3
+  }
+}
+
+const firstN: Expression.FirstN = {
+  $firstN: {
+    input: '$score',
+    n: 3,
+  }
+}
+
+const lastN: Expression.LastN = {
+  $lastN: {
+    input: '$score',
+    n: 3,
+  }
+}
+
+const maxN: Expression.MaxN = {
+  $maxN: {
+    input: '$score',
+    n: 3,
+  }
+}
+
+const minN: Expression.MinN = {
+  $minN: {
+    input: '$score',
+    n: 3,
+  }
+}
+
 const top: Expression.Top = {
   $top: {
     output: ['$playerId', '$score'],

types/expressions.d.ts

@@ -1150,6 +1150,21 @@ declare module 'mongoose' {
       $first: Expression;
     }
 
+    export interface FirstN {
+      /**
+       * $firstN can be used as an aggregation accumulator or array operator.
+       * As an aggregation accumulator, it returns an aggregation of the first n elements within a group.
+       * As an array operator, it returns the specified number of elements from the beginning of an array.
+       *
+       * @version 5.2
+       * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/firstN/#mongodb-expression-exp.-first
+       */
+      $firstN: {
+        input: Expression
+        n: Expression,
+      };
+    }
+
     export interface In {
       /**
        * Returns a boolean indicating whether a specified value is in an array.
@@ -1190,6 +1205,21 @@ declare module 'mongoose' {
       $last: Expression;
     }
 
+    export interface LastN {
+      /**
+       * $lastN can be used as an aggregation accumulator or array operator.
+       * As an aggregation accumulator, it an aggregation of the last n elements within a group.
+       * As an array operator, it returns the specified number of elements from the end of an array.
+       *
+       * @version 5.2
+       * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/lastN/#mongodb-group-grp.-lastN
+       */
+      $lastN: {
+        input: Expression
+        n: Expression,
+      };
+    }
+
     export interface LinearFill {
       /**
        * Fills null and missing fields in a window using linear interpolation based on surrounding field values.
@@ -2000,6 +2030,34 @@ declare module 'mongoose' {
       $avg: Expression;
     }
 
+    export interface Bottom {
+      /**
+       * Returns the bottom element within a group according to the specified sort order.
+       *
+       * @version 5.2
+       * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/bottom/#mongodb-group-grp.-bottom
+       */
+      $bottom: {
+        sortBy: AnyObject,
+        output: Expression
+      };
+    }
+
+    export interface BottomN {
+      /**
+       * Returns an aggregation of the bottom n elements within a group, according to the specified sort order.
+       * If the group contains fewer than n elements, $bottomN returns all elements in the group.
+       *
+       * @version 5.2
+       * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/bottomN/#mongodb-group-grp.-bottomN
+       */
+      $bottomN: {
+        n: Expression,
+        sortBy: AnyObject,
+        output: Expression
+      };
+    }
+
     export interface Count {
       /**
        * Returns the number of documents in a group.
@@ -2158,6 +2216,20 @@ declare module 'mongoose' {
       $max: Expression | Expression[];
     }
 
+    export interface MaxN {
+      /**
+       * Returns an aggregation of the maxmimum value n elements within a group.
+       * If the group contains fewer than n elements, $maxN returns all elements in the group.
+       *
+       * @version 5.2
+       * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/maxN/#mongodb-group-grp.-maxN
+       */
+      $maxN: {
+        input: Expression
+        n: Expression,
+      };
+    }
+
     export interface Min {
       /**
        * Returns the minimum value. $min compares both value and type, using the specified BSON comparison order for
@@ -2169,6 +2241,20 @@ declare module 'mongoose' {
       $min: Expression | Expression[];
     }
 
+    export interface MinN {
+      /**
+       * Returns an aggregation of the minimum value n elements within a group.
+       * If the group contains fewer than n elements, $minN returns all elements in the group.
+       *
+       * @version 5.2
+       * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/minN/#mongodb-group-grp.-minN
+       */
+      $minN: {
+        input: Expression
+        n: Expression,
+      };
+    }
+
     export interface Push {
       /**
        * Returns an array of all values that result from applying an expression to documents.
@@ -2605,6 +2691,8 @@ declare module 'mongoose' {
   export type ArrayExpressionOperatorReturningArray =
     Expression.ConcatArrays |
     Expression.Filter |
+    Expression.FirstN |
+    Expression.LastN |
     Expression.Map |
     Expression.ObjectToArray |
     Expression.Range |
@@ -2763,12 +2851,16 @@ declare module 'mongoose' {
     Expression.DocumentNumber |
     Expression.ExpMovingAvg |
     Expression.First |
+    Expression.FirstN |
     Expression.Integral |
     Expression.Last |
+    Expression.LastN |
     Expression.LinearFill |
     Expression.Locf |
     Expression.Max |
+    Expression.MaxN |
     Expression.Min |
+    Expression.MinN |
     Expression.Push |
     Expression.Rank |
     Expression.Shift |
@@ -2783,6 +2875,10 @@ declare module 'mongoose' {
 
   export type WindowOperatorReturningArray =
     Expression.AddToSet |
+    Expression.FirstN |
+    Expression.LastN |
+    Expression.MaxN |
+    Expression.MinN |
     Expression.Push;
 
   export type WindowOperatorReturningNumber =
@@ -2858,12 +2954,18 @@ declare module 'mongoose' {
     Expression.Accumulator |
     Expression.AddToSet |
     Expression.Avg |
+    Expression.Bottom |
+    Expression.BottomN |
     Expression.Count |
     Expression.First |
+    Expression.FirstN |
     Expression.Last |
+    Expression.LastN |
     Expression.Max |
+    Expression.MaxN |
     Expression.MergeObjects |
     Expression.Min |
+    Expression.MinN |
     Expression.Push |
     Expression.StdDevPop |
     Expression.StdDevSamp |