Adding $find utility operator

index.ts

@@ -37,7 +37,7 @@
  */
 type DateExpression = ObjectExpression | Date | string;
 
 type ArrayOfExpressions = Array<ObjectExpression>;
 
 type Timestamp = number;
 
@@ -2322,6 +2322,15 @@
   limit?: number,
 ) => new FilterOperator(inputExpr, asName, condExpr, limit);
 
+type FindParams = [
+  ArrayExpression,
+  string,
+  Expression,
+  number?,
+];
+
+const $find = (...args: FindParams) => $arrayElemAt($filter(...args), 0);
+
 type FirstOperator = {
   $first: Expression,
 };
@@ -2831,7 +2840,7 @@
 
 // TODO
 // * @category Safe Operators
 const $ninSafe = (...args: any[]) => {
   if (args.length === 2) {
     const [val, arr] = args;
     return $in(val, $ifNull(arr, []));
@@ -3789,6 +3798,8 @@
   facet: $facet,
   $filter,
   filter: $filter,
+  $find,
+  find: $find,
   $first,
   first: $first,
   $floor,

pipeline.test.ts

@@ -1062,6 +1062,24 @@ describe('aggregation', () => {
         });
       });
     });
+    describe('$find', () => {
+      it('exports expected vars', () => {
+        expect($.find).toBeDefined();
+        expect($.$find).toBeDefined();
+        expect($.find).toStrictEqual($.$find);
+      });
+      it('returns expected result', () => {
+        expect($.find('$input', 'foo', '$cond')).toEqual({
+          $arrayElemAt: [{
+            $filter: {
+              input: '$input',
+              as: 'foo',
+              cond: '$cond',
+            },
+          }, 0],
+        });
+      });
+    });
     describe('$first', () => {
       it('exports expected vars', () => {
         expect($.first).toBeDefined();