google · copybara-service · Apr 25, 2026
diff --git a/common/internal/BUILD.bazel b/common/internal/BUILD.bazel
@@ -147,3 +147,8 @@ cel_android_library(
     name = "date_time_helpers_android",
     exports = ["//common/src/main/java/dev/cel/common/internal:date_time_helpers_android"],
 )
+
+java_library(
+    name = "reflection_util",
+    exports = ["//common/src/main/java/dev/cel/common/internal:reflection_util"],
+)
diff --git a/common/src/main/java/dev/cel/common/internal/BUILD.bazel b/common/src/main/java/dev/cel/common/internal/BUILD.bazel
@@ -398,8 +398,12 @@ java_library(
 java_library(
     name = "reflection_util",
     srcs = ["ReflectionUtil.java"],
+    tags = [
+        "alt_dep=//common/internal:reflection_util",
+    ],
     deps = [
         "//common/annotations",
+        "@maven//:com_google_guava_guava",
     ],
 )
 

diff --git a/common/src/main/java/dev/cel/common/internal/ReflectionUtil.java b/common/src/main/java/dev/cel/common/internal/ReflectionUtil.java
@@ -14,9 +14,15 @@
 
 package dev.cel.common.internal;
 
+import com.google.common.reflect.TypeToken;
 import dev.cel.common.annotations.Internal;
 import java.lang.reflect.InvocationTargetException;
 import java.lang.reflect.Method;
+import java.lang.reflect.ParameterizedType;
+import java.lang.reflect.Type;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
 
 /**
  * Utility class for invoking Java reflection.
@@ -48,5 +54,48 @@ public static Object invoke(Method method, Object object, Object... params) {
     }
   }
 
+  /**
+   * Extracts the element type of a container type (List, Map, or Optional). Returns the type itself
+   * if it's not a container or if generic type info is missing.
+   */
+  public static Class<?> getElementType(Class<?> type, Type genericType) {
+    TypeToken<?> token = TypeToken.of(genericType);
+
+    if (List.class.isAssignableFrom(type)) {
+      return token.resolveType(List.class.getTypeParameters()[0]).getRawType();
+    }
+    if (Map.class.isAssignableFrom(type)) {
+      return token.resolveType(Map.class.getTypeParameters()[1]).getRawType();
+    }
+    if (type == Optional.class) {
+      return token.resolveType(Optional.class.getTypeParameters()[0]).getRawType();
+    }
+
+    return type;
+  }
+
+  /**
+   * Extracts the raw Class from a Type. Handles Class, ParameterizedType, and WildcardType (returns
+   * upper bound). Returns Object.class as fallback.
+   */
+  public static Class<?> getRawType(Type type) {
+    return TypeToken.of(type).getRawType();
+  }
+
+  /**
+   * Extracts the actual type arguments from a ParameterizedType, if it has at least the expected
+   * minimum number of arguments. Returns Optional.empty() if the type is not parameterized or has
+   * fewer arguments than expected.
+   */
+  public static Optional<Type[]> getTypeArguments(Type type, int minArgs) {
+    if (type instanceof ParameterizedType) {
+      Type[] args = ((ParameterizedType) type).getActualTypeArguments();
+      if (args.length >= minArgs) {
+        return Optional.of(args);
+      }
+    }
+    return Optional.empty();
+  }
+
   private ReflectionUtil() {}
 }
diff --git a/common/src/main/java/dev/cel/common/values/BUILD.bazel b/common/src/main/java/dev/cel/common/values/BUILD.bazel
@@ -60,7 +60,6 @@ java_library(
     deps = [
         "//common/values",
         "@maven//:com_google_errorprone_error_prone_annotations",
-        "@maven//:com_google_guava_guava",
     ],
 )
 
@@ -72,7 +71,6 @@ cel_android_library(
     deps = [
         "//common/values:values_android",
         "@maven//:com_google_errorprone_error_prone_annotations",
-        "@maven_android//:com_google_guava_guava",
     ],
 )
 
@@ -118,7 +116,6 @@ java_library(
     deps = [
         ":values",
         "//common/annotations",
-        "@maven//:com_google_errorprone_error_prone_annotations",
         "@maven//:com_google_guava_guava",
         "@maven//:org_jspecify_jspecify",
     ],
@@ -134,12 +131,31 @@ cel_android_library(
     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 = "preadapted_list",
+    srcs = [
+        "CelPreAdaptedList.java",
+    ],
+    tags = [
+    ],
+    deps = ["//common/annotations"],
+)
+
+cel_android_library(
+    name = "preadapted_list_android",
+    srcs = [
+        "CelPreAdaptedList.java",
+    ],
+    tags = [
+    ],
+    deps = ["//common/annotations"],
+)
+
 java_library(
     name = "values",
     srcs = CEL_VALUES_SOURCES,
@@ -148,6 +164,7 @@ java_library(
     deps = [
         ":cel_byte_string",
         ":cel_value",
+        ":preadapted_list",
         "//:auto_value",
         "//common/annotations",
         "//common/types",
@@ -198,6 +215,7 @@ cel_android_library(
     deps = [
         ":cel_byte_string",
         ":cel_value_android",
+        ":preadapted_list_android",
         "//:auto_value",
         "//common/annotations",
         "//common/types:type_providers_android",
@@ -226,14 +244,14 @@ java_library(
     ],
     deps = [
         ":cel_byte_string",
-        ":values",
         "//common/annotations",
         "//common/internal:proto_time_utils",
         "//common/internal:well_known_proto",
         "//common/values",
         "@maven//:com_google_errorprone_error_prone_annotations",
         "@maven//:com_google_guava_guava",
         "@maven//:com_google_protobuf_protobuf_java",
+        "@maven_android//:com_google_protobuf_protobuf_javalite",
     ],
 )
 
@@ -261,6 +279,7 @@ java_library(
     ],
     deps = [
         ":base_proto_cel_value_converter",
+        ":preadapted_list",
         ":values",
         "//:auto_value",
         "//common:options",
@@ -273,7 +292,7 @@ java_library(
         "@maven//:com_google_errorprone_error_prone_annotations",
         "@maven//:com_google_guava_guava",
         "@maven//:com_google_protobuf_protobuf_java",
-        "@maven//:org_jspecify_jspecify",
+        "@maven_android//:com_google_protobuf_protobuf_javalite",
     ],
 )
 
@@ -316,8 +335,6 @@ java_library(
         "//protobuf:cel_lite_descriptor",
         "@maven//:com_google_errorprone_error_prone_annotations",
         "@maven//:com_google_guava_guava",
-        "@maven//:com_google_protobuf_protobuf_java",
-        "@maven//:org_jspecify_jspecify",
         "@maven_android//:com_google_protobuf_protobuf_javalite",
     ],
 )
@@ -343,7 +360,6 @@ cel_android_library(
         "//protobuf:cel_lite_descriptor",
         "@maven//:com_google_errorprone_error_prone_annotations",
         "@maven//:com_google_guava_guava",
-        "@maven//:org_jspecify_jspecify",
         "@maven_android//:com_google_guava_guava",
         "@maven_android//:com_google_protobuf_protobuf_javalite",
     ],

diff --git a/common/src/main/java/dev/cel/common/values/CelPreAdaptedList.java b/common/src/main/java/dev/cel/common/values/CelPreAdaptedList.java
@@ -0,0 +1,50 @@
+// 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 dev.cel.common.annotations.Internal;
+import java.util.AbstractList;
+import java.util.List;
+import java.util.RandomAccess;
+
+/**
+ * A zero-allocation view over a list we know is already adapted.
+ *
+ * <p>This class purely exists as an optimization scheme to avoid redundant collection traversals
+ * in {@link CelValueConverter}, and is not intended for general use.
+ */
+@Internal
+final class CelPreAdaptedList<E> extends AbstractList<E>
+    implements RandomAccess {
+  private final List<E> delegate;
+
+  private CelPreAdaptedList(List<E> delegate) {
+    this.delegate = delegate;
+  }
+
+  static <E> CelPreAdaptedList<E> wrap(List<E> safeList) {
+    return new CelPreAdaptedList<>(safeList);
+  }
+
+  @Override
+  public E get(int index) {
+    return delegate.get(index);
+  }
+
+  @Override
+  public int size() {
+    return delegate.size();
+  }
+}
diff --git a/common/src/main/java/dev/cel/common/values/CelValueConverter.java b/common/src/main/java/dev/cel/common/values/CelValueConverter.java
@@ -20,8 +20,11 @@
 import com.google.errorprone.annotations.Immutable;
 import dev.cel.common.annotations.Internal;
 import java.util.Collection;
+import java.util.Iterator;
+import java.util.List;
 import java.util.Map;
 import java.util.Optional;
+import java.util.RandomAccess;
 import java.util.function.Function;
 
 /**
@@ -53,23 +56,46 @@ public static CelValueConverter getDefaultInstance() {
    * <p>The value may be a {@link CelValue}, a {@link Collection} or a {@link Map}.
    */
   public Object maybeUnwrap(Object value) {
-    if (value instanceof CelValue) {
-      return unwrap((CelValue) value);
+    if (value instanceof CelValue || value instanceof CelPreAdaptedList) {
+      return value instanceof CelValue ? unwrap((CelValue) value) : value;
     }
 
-    Object mapped = mapContainer(value, maybeUnwrapFunction);
-    if (mapped != value) {
-      return mapped;
-    }
-
-    return value;
+    return mapContainer(value, maybeUnwrapFunction);
   }
 
   /**
    * 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) {
+
+    // Zero allocation path for standard lists that support O(1) indexing
+    // Generally, protobuf lists (backed by arrays) fall into this category
+    if (value instanceof List && value instanceof RandomAccess) {
+      List<Object> list = (List<Object>) value;
+      for (int i = 0; i < list.size(); i++) {
+        Object element = list.get(i);
+        Object mapped = mapper.apply(element);
+
+        if (mapped != element) {
+          ImmutableList.Builder<Object> builder =
+              ImmutableList.builderWithExpectedSize(list.size());
+          for (int j = 0; j < i; j++) {
+            builder.add(list.get(j));
+          }
+          builder.add(mapped);
+          for (int j = i + 1; j < list.size(); j++) {
+            builder.add(mapper.apply(list.get(j)));
+          }
+          return builder.build();
+        }
+      }
+
+      // Zero allocations if unmodified
+      return value;
+    }
+
+    // Fallback for lists that are unordered
     if (value instanceof Collection) {
       Collection<Object> collection = (Collection<Object>) value;
       ImmutableList.Builder<Object> builder =
@@ -82,12 +108,32 @@ protected Object mapContainer(Object value, Function<Object, Object> mapper) {
 
     if (value instanceof Map) {
       Map<Object, Object> map = (Map<Object, Object>) value;
-      ImmutableMap.Builder<Object, Object> builder =
-          ImmutableMap.builderWithExpectedSize(map.size());
-      for (Map.Entry<Object, Object> entry : map.entrySet()) {
-        builder.put(mapper.apply(entry.getKey()), mapper.apply(entry.getValue()));
+      Iterator<Map.Entry<Object, Object>> iterator = map.entrySet().iterator();
+
+      while (iterator.hasNext()) {
+        Map.Entry<Object, Object> entry = iterator.next();
+        Object mappedKey = mapper.apply(entry.getKey());
+        Object mappedValue = mapper.apply(entry.getValue());
+
+        if (mappedKey != entry.getKey() || mappedValue != entry.getValue()) {
+          ImmutableMap.Builder<Object, Object> builder =
+              ImmutableMap.builderWithExpectedSize(map.size());
+
+          for (Map.Entry<Object, Object> prevEntry : map.entrySet()) {
+            if (prevEntry.getKey() == entry.getKey()) {
+              break;
+            }
+            builder.put(mapper.apply(prevEntry.getKey()), mapper.apply(prevEntry.getValue()));
+          }
+          builder.put(mappedKey, mappedValue);
+          while (iterator.hasNext()) {
+            Map.Entry<Object, Object> nextEntry = iterator.next();
+            builder.put(mapper.apply(nextEntry.getKey()), mapper.apply(nextEntry.getValue()));
+          }
+          return builder.buildOrThrow();
+        }
       }
-      return builder.buildOrThrow();
+      return value;
     }
 
     return value;
@@ -96,7 +142,7 @@ protected Object mapContainer(Object value, Function<Object, Object> mapper) {
   public Object toRuntimeValue(Object value) {
     Preconditions.checkNotNull(value);
 
-    if (value instanceof CelValue) {
+    if (value instanceof CelValue || value instanceof CelPreAdaptedList) {
       return value;
     }
 

diff --git a/common/src/main/java/dev/cel/common/values/ProtoCelValueConverter.java b/common/src/main/java/dev/cel/common/values/ProtoCelValueConverter.java
@@ -167,6 +167,18 @@ public Object fromProtoMessageFieldToCelValue(Message message, FieldDescriptor f
         break;
     }
 
+    if (fieldDescriptor.isRepeated()) {
+      switch (fieldDescriptor.getType()) {
+        case INT64:
+        case BOOL:
+        case STRING:
+        case DOUBLE:
+          return CelPreAdaptedList.wrap((List<?>) result);
+        default:
+          break;
+      }
+    }
+
     return toRuntimeValue(result);
   }