Add CombinedCelValueConverter

common/src/main/java/dev/cel/common/values/BUILD.bazel

@@ -78,10 +78,14 @@ cel_android_library(
 
 java_library(
     name = "combined_cel_value_provider",
-    srcs = ["CombinedCelValueProvider.java"],
+    srcs = [
+        "CombinedCelValueProvider.java",
+    ],
     tags = [
     ],
     deps = [
+        ":combined_cel_value_converter",
+        ":values",
         "//common/values:cel_value_provider",
         "@maven//:com_google_errorprone_error_prone_annotations",
         "@maven//:com_google_guava_guava",
@@ -90,16 +94,52 @@ java_library(
 
 cel_android_library(
     name = "combined_cel_value_provider_android",
-    srcs = ["CombinedCelValueProvider.java"],
+    srcs = [
+        "CombinedCelValueProvider.java",
+    ],
     tags = [
     ],
     deps = [
+        ":combined_cel_value_converter_android",
+        ":values_android",
         "//common/values:cel_value_provider_android",
         "@maven//:com_google_errorprone_error_prone_annotations",
         "@maven_android//:com_google_guava_guava",
     ],
 )
 
+java_library(
+    name = "combined_cel_value_converter",
+    srcs = [
+        "CombinedCelValueConverter.java",
+    ],
+    tags = [
+    ],
+    deps = [
+        ":values",
+        "//common/annotations",
+        "@maven//:com_google_errorprone_error_prone_annotations",
+        "@maven//:com_google_guava_guava",
+        "@maven//:org_jspecify_jspecify",
+    ],
+)
+
+cel_android_library(
+    name = "combined_cel_value_converter_android",
+    srcs = [
+        "CombinedCelValueConverter.java",
+    ],
+    tags = [
+    ],
+    deps = [
+        ":values_android",
+        "//common/annotations",
+        "@maven//:com_google_errorprone_error_prone_annotations",
+        "@maven//:org_jspecify_jspecify",
+        "@maven_android//:com_google_guava_guava",
+    ],
+)
+
 java_library(
     name = "values",
     srcs = CEL_VALUES_SOURCES,

common/src/main/java/dev/cel/common/values/CelValueConverter.java

@@ -21,8 +21,8 @@
 import dev.cel.common.annotations.Internal;
 import java.util.Collection;
 import java.util.Map;
-import java.util.Map.Entry;
 import java.util.Optional;
+import java.util.function.Function;
 
 /**
  * {@code CelValueConverter} handles bidirectional conversion between native Java objects to {@link
@@ -37,6 +37,12 @@ public class CelValueConverter {
 
   private static final CelValueConverter DEFAULT_INSTANCE = new CelValueConverter();
 
+  @SuppressWarnings("Immutable") // Method reference is immutable
+  private final Function<Object, Object> maybeUnwrapFunction;
+
+  @SuppressWarnings("Immutable") // Method reference is immutable
+  private final Function<Object, Object> toRuntimeValueFunction;
+
   public static CelValueConverter getDefaultInstance() {
     return DEFAULT_INSTANCE;
   }
@@ -51,14 +57,26 @@ public Object maybeUnwrap(Object value) {
       return unwrap((CelValue) value);
     }
 
+    Object mapped = mapContainer(value, maybeUnwrapFunction);
+    if (mapped != value) {
+      return mapped;
+    }
+
+    return value;
+  }
+
+  /**
+   * Maps a container (Collection or Map) by applying the provided mapper function to its elements.
+   * Returns the original value if it's not a supported container.
+   */
+  protected Object mapContainer(Object value, Function<Object, Object> mapper) {
     if (value instanceof Collection) {
       Collection<Object> collection = (Collection<Object>) value;
       ImmutableList.Builder<Object> builder =
           ImmutableList.builderWithExpectedSize(collection.size());
       for (Object element : collection) {
-        builder.add(maybeUnwrap(element));
+        builder.add(mapper.apply(element));
       }
-
       return builder.build();
     }
 
@@ -67,34 +85,30 @@ public Object maybeUnwrap(Object value) {
       ImmutableMap.Builder<Object, Object> builder =
           ImmutableMap.builderWithExpectedSize(map.size());
       for (Map.Entry<Object, Object> entry : map.entrySet()) {
-        builder.put(maybeUnwrap(entry.getKey()), maybeUnwrap(entry.getValue()));
+        builder.put(mapper.apply(entry.getKey()), mapper.apply(entry.getValue()));
       }
-
       return builder.buildOrThrow();
     }
 
     return value;
   }
 
-  /**
-   * Canonicalizes an inbound {@code value} into a suitable Java object representation for
-   * evaluation.
-   */
   public Object toRuntimeValue(Object value) {
     Preconditions.checkNotNull(value);
 
     if (value instanceof CelValue) {
       return value;
     }
 
-    if (value instanceof Collection) {
-      return toListValue((Collection<Object>) value);
-    } else if (value instanceof Map) {
-      return toMapValue((Map<Object, Object>) value);
-    } else if (value instanceof Optional) {
+    Object mapped = mapContainer(value, toRuntimeValueFunction);
+    if (mapped != value) {
+      return mapped;
+    }
+
+    if (value instanceof Optional) {
       Optional<Object> optionalValue = (Optional<Object>) value;
       return optionalValue
-          .map(this::toRuntimeValue)
+          .map(toRuntimeValueFunction)
           .map(OptionalValue::create)
           .orElse(OptionalValue.EMPTY);
     }
@@ -136,31 +150,8 @@ private Object unwrap(CelValue celValue) {
     return celValue.value();
   }
 
-  private ImmutableList<Object> toListValue(Collection<Object> iterable) {
-    Preconditions.checkNotNull(iterable);
-
-    ImmutableList.Builder<Object> listBuilder =
-        ImmutableList.builderWithExpectedSize(iterable.size());
-    for (Object entry : iterable) {
-      listBuilder.add(toRuntimeValue(entry));
-    }
-
-    return listBuilder.build();
-  }
-
-  private ImmutableMap<Object, Object> toMapValue(Map<Object, Object> map) {
-    Preconditions.checkNotNull(map);
-
-    ImmutableMap.Builder<Object, Object> mapBuilder =
-        ImmutableMap.builderWithExpectedSize(map.size());
-    for (Entry<Object, Object> entry : map.entrySet()) {
-      Object mapKey = toRuntimeValue(entry.getKey());
-      Object mapValue = toRuntimeValue(entry.getValue());
-      mapBuilder.put(mapKey, mapValue);
-    }
-
-    return mapBuilder.buildOrThrow();
+  protected CelValueConverter() {
+    this.maybeUnwrapFunction = this::maybeUnwrap;
+    this.toRuntimeValueFunction = this::toRuntimeValue;
   }
-
-  protected CelValueConverter() {}
 }

common/src/main/java/dev/cel/common/values/CombinedCelValueConverter.java

@@ -0,0 +1,84 @@
+// Copyright 2026 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package dev.cel.common.values;
+
+import static com.google.common.base.Preconditions.checkNotNull;
+
+import com.google.common.collect.ImmutableList;
+import dev.cel.common.annotations.Internal;
+import org.jspecify.annotations.Nullable;
+
+/**
+ * {@code CombinedCelValueConverter} delegates value conversion to a list of underlying {@link
+ * CelValueConverter}s.
+ */
+@Internal
+public final class CombinedCelValueConverter extends CelValueConverter {
+  private final ImmutableList<CelValueConverter> converters;
+
+  public static CombinedCelValueConverter combine(ImmutableList<CelValueConverter> converters) {
+    return new CombinedCelValueConverter(converters);
+  }
+
+  private CombinedCelValueConverter(ImmutableList<CelValueConverter> converters) {
+    this.converters = checkNotNull(converters);
+  }
+
+  @Override
+  public @Nullable Object toRuntimeValue(Object value) {
+    if (value == null) {
+      return null;
+    }
+
+    // Let the base class handle CelValues, Optionals, Collections, Maps, and primitives.
+    Object baseResult = super.toRuntimeValue(value);
+    if (baseResult != value) {
+      return baseResult;
+    }
+
+    // If the base class left the object unchanged (e.g. a raw POJO), try the delegates.
+    for (CelValueConverter converter : converters) {
+      Object result = converter.toRuntimeValue(value);
+      if (result != value) {
+        return result;
+      }
+    }
+
+    return value;
+  }
+
+  @Override
+  public @Nullable Object maybeUnwrap(Object value) {
+    if (value == null) {
+      return null;
+    }
+
+    // Let the base class handle standard unwrapping and container unrolling.
+    Object baseResult = super.maybeUnwrap(value);
+    if (baseResult != value) {
+      return baseResult;
+    }
+
+    // Try delegates for specialized unwrapping.
+    for (CelValueConverter converter : converters) {
+      Object result = converter.maybeUnwrap(value);
+      if (result != value) {
+        return result;
+      }
+    }
+
+    return value;
+  }
+}

common/src/main/java/dev/cel/common/values/CombinedCelValueProvider.java

@@ -16,6 +16,7 @@
 
 import static com.google.common.base.Preconditions.checkArgument;
 import static com.google.common.base.Preconditions.checkNotNull;
+import static com.google.common.collect.ImmutableList.toImmutableList;
 
 import com.google.common.collect.ImmutableList;
 import com.google.errorprone.annotations.Immutable;
@@ -49,6 +50,14 @@ public Optional<Object> newValue(String structType, Map<String, Object> fields)
     return Optional.empty();
   }
 
+  @Override
+  public CelValueConverter celValueConverter() {
+    return CombinedCelValueConverter.combine(
+        celValueProviders.stream()
+            .map(CelValueProvider::celValueConverter)
+            .collect(toImmutableList()));
+  }
+
   /** Returns the underlying {@link CelValueProvider}s in order. */
   public ImmutableList<CelValueProvider> valueProviders() {
     return celValueProviders;

common/src/test/java/dev/cel/common/values/BUILD.bazel

@@ -24,6 +24,7 @@ java_library(
         "//common/values",
         "//common/values:cel_byte_string",
         "//common/values:cel_value_provider",
+        "//common/values:combined_cel_value_converter",
         "//common/values:combined_cel_value_provider",
         "//common/values:proto_message_lite_value",
         "//common/values:proto_message_lite_value_provider",