feat(firestore): Add array expressions (#2350)

Author: milaGGL

java-firestore/google-cloud-firestore/src/main/java/com/google/cloud/firestore/pipeline/expressions/Expression.java

@@ -2707,6 +2707,196 @@ public static Expression arrayReverse(String arrayFieldName) {
     return arrayReverse(field(arrayFieldName));
   }
 
+  /**
+   * Filters an array expression based on a predicate.
+   *
+   * @param array The expression representing the array to filter.
+   * @param alias The alias for the current element in the filter expression.
+   * @param filter The predicate boolean expression used to filter the elements.
+   * @return A new {@link Expression} representing the filtered array.
+   */
+  @BetaApi
+  public static Expression arrayFilter(Expression array, String alias, BooleanExpression filter) {
+    return new FunctionExpression("array_filter", ImmutableList.of(array, constant(alias), filter));
+  }
+
+  /**
+   * Filters an array field based on a predicate.
+   *
+   * @param arrayFieldName The field name of the array to filter.
+   * @param alias The alias for the current element in the filter expression.
+   * @param filter The predicate boolean expression used to filter the elements.
+   * @return A new {@link Expression} representing the filtered array.
+   */
+  @BetaApi
+  public static Expression arrayFilter(
+      String arrayFieldName, String alias, BooleanExpression filter) {
+    return arrayFilter(field(arrayFieldName), alias, filter);
+  }
+
+  /**
+   * Creates an expression that applies a provided transformation to each element in an array.
+   *
+   * @param array The expression representing the array to transform.
+   * @param elementAlias The alias for the current element in the transform expression.
+   * @param transform The expression used to transform the elements.
+   * @return A new {@link Expression} representing the transformed array.
+   */
+  @BetaApi
+  public static Expression arrayTransform(
+      Expression array, String elementAlias, Expression transform) {
+    return new FunctionExpression(
+        "array_transform", ImmutableList.of(array, constant(elementAlias), transform));
+  }
+
+  /**
+   * Creates an expression that applies a provided transformation to each element in an array.
+   *
+   * @param arrayFieldName The field name of the array to transform.
+   * @param elementAlias The alias for the current element in the transform expression.
+   * @param transform The expression used to transform the elements.
+   * @return A new {@link Expression} representing the transformed array.
+   */
+  @BetaApi
+  public static Expression arrayTransform(
+      String arrayFieldName, String elementAlias, Expression transform) {
+    return arrayTransform(field(arrayFieldName), elementAlias, transform);
+  }
+
+  /**
+   * Creates an expression that applies a provided transformation to each element in an array,
+   * providing the element's index to the transformation expression.
+   *
+   * @param array The expression representing the array to transform.
+   * @param elementAlias The alias for the current element in the transform expression.
+   * @param indexAlias The alias for the current index.
+   * @param transform The expression used to transform the elements.
+   * @return A new {@link Expression} representing the transformed array.
+   */
+  @BetaApi
+  public static Expression arrayTransformWithIndex(
+      Expression array, String elementAlias, String indexAlias, Expression transform) {
+    return new FunctionExpression(
+        "array_transform",
+        ImmutableList.of(array, constant(elementAlias), constant(indexAlias), transform));
+  }
+
+  /**
+   * Creates an expression that applies a provided transformation to each element in an array,
+   * providing the element's index to the transformation expression.
+   *
+   * @param arrayFieldName The field name of the array to transform.
+   * @param elementAlias The alias for the current element in the transform expression.
+   * @param indexAlias The alias for the current index.
+   * @param transform The expression used to transform the elements.
+   * @return A new {@link Expression} representing the transformed array.
+   */
+  @BetaApi
+  public static Expression arrayTransformWithIndex(
+      String arrayFieldName, String elementAlias, String indexAlias, Expression transform) {
+    return arrayTransformWithIndex(field(arrayFieldName), elementAlias, indexAlias, transform);
+  }
+
+  /**
+   * Creates an expression that returns a slice of an array.
+   *
+   * @param array The expression representing the array to slice.
+   * @param offset The starting index.
+   * @param length The number of elements to return.
+   * @return A new {@link Expression} representing the array slice.
+   */
+  @BetaApi
+  public static Expression arraySlice(Expression array, Expression offset, Expression length) {
+    return new FunctionExpression("array_slice", ImmutableList.of(array, offset, length));
+  }
+
+  /**
+   * Creates an expression that returns a slice of an array.
+   *
+   * @param array The expression representing the array to slice.
+   * @param offset The starting index.
+   * @param length The number of elements to return.
+   * @return A new {@link Expression} representing the array slice.
+   */
+  @BetaApi
+  public static Expression arraySlice(Expression array, int offset, int length) {
+    return arraySlice(array, constant(offset), constant(length));
+  }
+
+  /**
+   * Creates an expression that returns a slice of an array.
+   *
+   * @param arrayFieldName The field name of the array to slice.
+   * @param offset The starting index.
+   * @param length The number of elements to return.
+   * @return A new {@link Expression} representing the array slice.
+   */
+  @BetaApi
+  public static Expression arraySlice(String arrayFieldName, int offset, int length) {
+    return arraySlice(field(arrayFieldName), constant(offset), constant(length));
+  }
+
+  /**
+   * Creates an expression that returns a slice of an array.
+   *
+   * @param arrayFieldName The field name of the array to slice.
+   * @param offset The starting index.
+   * @param length The number of elements to return.
+   * @return A new {@link Expression} representing the array slice.
+   */
+  @BetaApi
+  public static Expression arraySlice(String arrayFieldName, Expression offset, Expression length) {
+    return arraySlice(field(arrayFieldName), offset, length);
+  }
+
+  /**
+   * Creates an expression that returns a slice of an array to its end.
+   *
+   * @param array The expression representing the array to slice.
+   * @param offset The expression representing the starting index.
+   * @return A new {@link Expression} representing the array slice.
+   */
+  @BetaApi
+  public static Expression arraySliceToEnd(Expression array, Expression offset) {
+    return new FunctionExpression("array_slice", ImmutableList.of(array, offset));
+  }
+
+  /**
+   * Creates an expression that returns a slice of an array to its end.
+   *
+   * @param array The expression representing the array to slice.
+   * @param offset The starting index.
+   * @return A new {@link Expression} representing the array slice.
+   */
+  @BetaApi
+  public static Expression arraySliceToEnd(Expression array, int offset) {
+    return arraySliceToEnd(array, constant(offset));
+  }
+
+  /**
+   * Creates an expression that returns a slice of an array to its end.
+   *
+   * @param arrayFieldName The field name of the array to slice.
+   * @param offset The starting index.
+   * @return A new {@link Expression} representing the array slice.
+   */
+  @BetaApi
+  public static Expression arraySliceToEnd(String arrayFieldName, int offset) {
+    return arraySliceToEnd(field(arrayFieldName), constant(offset));
+  }
+
+  /**
+   * Creates an expression that returns a slice of an array to its end.
+   *
+   * @param arrayFieldName The field name of the array to slice.
+   * @param offset The expression representing the starting index.
+   * @return A new {@link Expression} representing the array slice.
+   */
+  @BetaApi
+  public static Expression arraySliceToEnd(String arrayFieldName, Expression offset) {
+    return arraySliceToEnd(field(arrayFieldName), offset);
+  }
+
   /**
    * Creates an expression that checks if an array contains a specified element.
    *
@@ -6583,6 +6773,91 @@ public final Expression arrayReverse() {
     return arrayReverse(this);
   }
 
+  /**
+   * Filters this array based on a predicate.
+   *
+   * @param alias The alias for the current element in the filter expression.
+   * @param filter The predicate boolean expression used to filter the elements.
+   * @return A new {@link Expression} representing the filtered array.
+   */
+  @BetaApi
+  public final Expression arrayFilter(String alias, BooleanExpression filter) {
+    return arrayFilter(this, alias, filter);
+  }
+
+  /**
+   * Creates an expression that applies a provided transformation to each element in an array.
+   *
+   * @param elementAlias The alias for the current element in the transform expression.
+   * @param transform The expression used to transform the elements.
+   * @return A new {@link Expression} representing the transformed array.
+   */
+  @BetaApi
+  public final Expression arrayTransform(String elementAlias, Expression transform) {
+    return arrayTransform(this, elementAlias, transform);
+  }
+
+  /**
+   * Creates an expression that applies a provided transformation to each element in an array,
+   * providing the element's index to the transformation expression.
+   *
+   * @param elementAlias The alias for the current element in the transform expression.
+   * @param indexAlias The alias for the current index.
+   * @param transform The expression used to transform the elements.
+   * @return A new {@link Expression} representing the transformed array.
+   */
+  @BetaApi
+  public final Expression arrayTransformWithIndex(
+      String elementAlias, String indexAlias, Expression transform) {
+    return arrayTransformWithIndex(this, elementAlias, indexAlias, transform);
+  }
+
+  /**
+   * Returns a slice of this array.
+   *
+   * @param offset The starting index.
+   * @param length The number of elements to return.
+   * @return A new {@link Expression} representing the array slice.
+   */
+  @BetaApi
+  public final Expression arraySlice(int offset, int length) {
+    return arraySlice(this, offset, length);
+  }
+
+  /**
+   * Returns a slice of this array.
+   *
+   * @param offset The starting index expressed as an Expression.
+   * @param length The number of elements to return expressed as an Expression.
+   * @return A new {@link Expression} representing the array slice.
+   */
+  @BetaApi
+  public final Expression arraySlice(Expression offset, Expression length) {
+    return arraySlice(this, offset, length);
+  }
+
+  /**
+   * Returns a slice of this array to its end.
+   *
+   * @param offset The starting index.
+   * @return A new {@link Expression} representing the array slice.
+   */
+  @BetaApi
+  public final Expression arraySliceToEnd(int offset) {
+    return arraySliceToEnd(this, offset);
+  }
+
+  /**
+   * Returns a slice of this array to its end.
+   *
+   * @param offset The starting index expressed as an Expression.
+   * @return A new {@link Expression} representing the array slice.
+   */
+  @BetaApi
+  public final Expression arraySliceToEnd(Expression offset) {
+    return arraySliceToEnd(this, offset);
+  }
+
   /**
    * Creates an expression that checks if array contains a specific {@code element}.
    *