feat(firestore): add the parent expression

handwritten/firestore/api-report/firestore.api.md

@@ -1170,6 +1170,7 @@ abstract class Expression implements firestore.Pipelines.Expression, HasUserData
     notEqual(value: unknown): BooleanExpression;
     notEqualAny(values: Array<Expression | unknown>): BooleanExpression;
     notEqualAny(arrayExpression: Expression): BooleanExpression;
+    parent(): FunctionExpression;
     pow(exponent: Expression): FunctionExpression;
     pow(exponent: number): FunctionExpression;
     // (undocumented)
@@ -1887,10 +1888,16 @@ class Ordering implements HasUserData {
     _validateUserData(ignoreUndefinedProperties: boolean): void;
 }
 
+// @beta
+function parent_2(documentPath: string | firestore.DocumentReference): FunctionExpression;
+
+// @beta
+function parent_2(documentPathExpr: Expression): FunctionExpression;
+
 // @beta
 class Pipeline implements firestore.Pipelines.Pipeline {
     // Warning: (ae-forgotten-export) The symbol "Stage" needs to be exported by the entry point index.d.ts
-    constructor(db: Firestore, stages: Stage[]);
+    constructor(db: Firestore | undefined, stages: Stage[]);
     addFields(field: firestore.Pipelines.Selectable, ...additionalFields: firestore.Pipelines.Selectable[]): Pipeline;
     // Warning: (tsdoc-escape-right-brace) The "}" character should be escaped using a backslash to avoid confusion with a TSDoc inline tag
     addFields(options: firestore.Pipelines.AddFieldsStageOptions): Pipeline;
@@ -1939,8 +1946,8 @@ class Pipeline implements firestore.Pipelines.Pipeline {
     union(options: firestore.Pipelines.UnionStageOptions): Pipeline;
     unnest(selectable: firestore.Pipelines.Selectable, indexField?: string): Pipeline;
     unnest(options: firestore.Pipelines.UnnestStageOptions): Pipeline;
-    // Warning: (tsdoc-undefined-tag) The TSDoc tag "@private" is not defined in this configuration
-    _validateUserData<T extends Map<string, HasUserData> | HasUserData[] | HasUserData>(_: string, val: T): T;
+    // (undocumented)
+    _validateUserData(ignoreUndefinedProperties: boolean): void;
     where(condition: firestore.Pipelines.BooleanExpression): Pipeline;
     where(options: firestore.Pipelines.WhereStageOptions): Pipeline;
 }
@@ -2068,6 +2075,7 @@ declare namespace Pipelines {
         isError,
         substring,
         documentId,
+        parent_2 as parent,
         arrayContainsAll,
         constant,
         Field,

handwritten/firestore/dev/src/pipelines/expression.ts

@@ -2495,6 +2495,23 @@ export abstract class Expression
     return new FunctionExpression('document_id', [this]);
   }
 
+  /**
+   * @beta
+   *
+   * Creates an expression that returns the parent document of a document reference.
+   *
+   * @example
+   * ```typescript
+   * // Get the parent document of a document reference.
+   * field("__path__").parent();
+   * ```
+   *
+   * @returns A new `Expression` representing the parent operation.
+   */
+  parent(): FunctionExpression {
+    return new FunctionExpression('parent', [this]);
+  }
+
   /**
    * @beta
    * Creates an expression that returns a substring of the results of this expression.
@@ -4396,6 +4413,46 @@ export function documentId(
   return documentPathExpr.documentId();
 }
 
+/**
+ * @beta
+ *
+ * Creates an expression that returns the parent document of a document reference.
+ *
+ * @example
+ * ```typescript
+ * // Get the parent document of a document reference.
+ * parent(myDocumentReference);
+ * ```
+ *
+ * @param documentPath - A string path or DocumentReference to get the parent from.
+ * @returns A new `Expression` representing the parent operation.
+ */
+export function parent(
+  documentPath: string | firestore.DocumentReference,
+): FunctionExpression;
+
+/**
+ * @beta
+ *
+ * Creates an expression that returns the parent document of a document reference.
+ *
+ * @example
+ * ```typescript
+ * // Get the parent document of a document reference.
+ * parent(field("__path__"));
+ * ```
+ *
+ * @param documentPathExpr - An Expression evaluating to a document reference.
+ * @returns A new `Expression` representing the parent operation.
+ */
+export function parent(documentPathExpr: Expression): FunctionExpression;
+export function parent(
+  documentPath: Expression | string | firestore.DocumentReference,
+): FunctionExpression {
+  const documentPathExpr = valueToDefaultExpr(documentPath);
+  return documentPathExpr.parent();
+}
+
 /**
  * @beta
  * Creates an expression that returns a substring of a string or byte array.

handwritten/firestore/dev/src/pipelines/index.ts

@@ -94,6 +94,7 @@ export {
   isError,
   substring,
   documentId,
+  parent,
   arrayContainsAll,
   constant,
   Field,

handwritten/firestore/dev/system-test/pipeline.ts

@@ -69,6 +69,7 @@ import {
   isError,
   substring,
   documentId,
+  parent,
   arrayContainsAll,
   mapRemove,
   mapMerge,
@@ -4577,6 +4578,29 @@ describe.skipClassic('Pipeline class', () => {
       });
     });
 
+    it('supports parent', async () => {
+      const snapshot = await firestore
+        .pipeline()
+        .collection(randomCol.path)
+        .limit(1)
+        .select(
+          parent(randomCol.doc('book4/reviews/review1')).as('parentRefStatic'),
+          constant(randomCol.doc('book4/reviews/review1'))
+            .parent()
+            .as('parentRefInstance'),
+        )
+        .select(
+          field('parentRefStatic').documentId().as('parentIdStatic'),
+          field('parentRefInstance').documentId().as('parentIdInstance'),
+        )
+        .execute();
+
+      expectResults(snapshot, {
+        parentIdStatic: 'book4',
+        parentIdInstance: 'book4',
+      });
+    });
+
     it('supports substring', async () => {
       let snapshot = await firestore
         .pipeline()

handwritten/firestore/types/firestore.d.ts

@@ -5039,6 +5039,20 @@ declare namespace FirebaseFirestore {
        * @returns A new {@code Expression} representing the documentId operation.
        */
       documentId(): FunctionExpression;
+      /**
+       * @beta
+       *
+       * Creates an expression that returns the parent document of a document reference.
+       *
+       * @example
+       * ```typescript
+       * // Get the parent document of a document reference.
+       * field("__path__").parent();
+       * ```
+       *
+       * @returns A new `Expression` representing the parent operation.
+       */
+      parent(): FunctionExpression;
       /**
        * @beta
        * Creates an expression that returns a substring of the results of this expression.
@@ -6615,6 +6629,41 @@ declare namespace FirebaseFirestore {
     export function documentId(
       documentPathExpr: Expression,
     ): FunctionExpression;
+
+    /**
+     * @beta
+     *
+     * Creates an expression that returns the parent document of a document reference.
+     *
+     * @example
+     * ```typescript
+     * // Get the parent document of a document reference.
+     * parent(myDocumentReference);
+     * ```
+     *
+     * @param documentPath - A string path or DocumentReference to get the parent from.
+     * @returns A new {@code Expression} representing the parent operation.
+     */
+    export function parent(
+      documentPath: string | DocumentReference,
+    ): FunctionExpression;
+
+    /**
+     * @beta
+     *
+     * Creates an expression that returns the parent document of a document reference.
+     *
+     * @example
+     * ```typescript
+     * // Get the parent document of a document reference.
+     * parent(field("__path__"));
+     * ```
+     *
+     * @param documentPathExpr - An Expression evaluating to a document reference.
+     * @returns A new {@code Expression} representing the parent operation.
+     */
+    export function parent(documentPathExpr: Expression): FunctionExpression;
+
     /**
      * @beta
      * Creates an expression that returns a substring of a string or byte array.