Prep-work to make java.lang.Iterable implement the JS iterator protocol

PiperOrigin-RevId: 888280380

Author: kevinoconnor7

jre/java/BUILD

@@ -72,6 +72,7 @@ package_sources(
         "javaemul/internal/Casts.java",  # J2WASM doesn't need it.
         "javaemul/internal/ArrayStamper.java",  # Unused in Wasm
         "javaemul/internal/Comparables.java",  # Unused in Wasm
+        "javaemul/internal/JsIterableHelper.java",  # Unused in Wasm
         "javaemul/internal/Objects.java",  # Unused in Wasm
         "javaemul/internal/Ref.java",  # Unused in Wasm
     ],

jre/java/java/lang/Iterable.java

@@ -21,6 +21,10 @@
 import java.util.Spliterator;
 import java.util.Spliterators;
 import java.util.function.Consumer;
+import javaemul.internal.JsIterableHelper;
+import javaemul.internal.JsIterableHelper.JsIterable;
+import jsinterop.annotations.JsMethod;
+import jsinterop.annotations.JsNonNull;
 
 /**
  * Allows an instance of a class implementing this interface to be used in the foreach statement.

jre/java/java/util/Iterator.java

@@ -18,14 +18,16 @@
 import static javaemul.internal.InternalPreconditions.checkNotNull;
 
 import java.util.function.Consumer;
+import javaemul.internal.JsIterableHelper;
+import javaemul.internal.JsIterableHelper.JsIterator;
 
 /**
  * See <a href="https://docs.oracle.com/javase/8/docs/api/java/util/Iterator.html">the official Java
  * API doc</a> for details.
  *
  * @param <T> element type
  */
-public interface Iterator<T> {
+public interface Iterator<T> extends JsIterator<T> {
 
   boolean hasNext();
 
@@ -41,4 +43,11 @@ default void forEachRemaining(Consumer<? super T> consumer) {
   default void remove() {
     throw new UnsupportedOperationException();
   }
+
+  @Override
+  default JsIterableHelper.IIterableResult<T> _private_jsNext__() {
+    return hasNext()
+        ? JsIterableHelper.makeResult(next(), false)
+        : JsIterableHelper.makeResult((T) null, true);
+  }
 }

jre/java/javaemul/internal/JsIterableHelper.java

@@ -0,0 +1,90 @@
+/*
+ * Copyright 2026 Google Inc.
+ *
+ * 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 javaemul.internal;
+
+import java.util.Iterator;
+import jsinterop.annotations.JsMethod;
+import jsinterop.annotations.JsPackage;
+import jsinterop.annotations.JsType;
+
+/** A helper class to create JavaScript iterable objects. */
+public final class JsIterableHelper {
+
+  /** Abstraction for JavaScript Iterable. */
+  @JsType(isNative = true, name = "Iterable", namespace = JsPackage.GLOBAL)
+  public interface JsIterable<T> {
+    @JsMethod(name = "[Symbol.iterator]")
+    JsIterator<T> _private_jsIterator__();
+  }
+
+  /** Abstraction for JavaScript Iterator. */
+  @JsType(isNative = true, name = "Iterator", namespace = JsPackage.GLOBAL)
+  public interface JsIterator<T> {
+    @JsMethod(name = "next")
+    IIterableResult<T> _private_jsNext__();
+  }
+
+  /** Abstraction for JavaScript IIterableResult. */
+  @JsType(isNative = true, namespace = JsPackage.GLOBAL)
+  public interface IIterableResult<T> {}
+
+  @JsMethod
+  public static native <T> IIterableResult<T> makeResult(T value, boolean done);
+
+  public static <T> JsIterable<T> asJsIterable(Iterable<T> iterable) {
+    return new JsIterableAdapter<T>(iterable);
+  }
+
+  private static final class JsIterableAdapter<T> implements JsIterable<T> {
+    private final Iterable<T> delegate;
+
+    private JsIterableAdapter(Iterable<T> delegate) {
+      this.delegate = delegate;
+    }
+
+    @Override
+    public final JsIterableIteratorAdapter<T> _private_jsIterator__() {
+      return new JsIterableIteratorAdapter<>(delegate.iterator());
+    }
+  }
+
+  /**
+   * Adapts a Java {@link Iterator} to also implement the {@link JsIterable} API. This ultimately
+   * makes this type an {@code IteratorIterable} for JS.
+   *
+   * <p>In general JS expects all Iterators to themselves be iterable, see:
+   * https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_iterator_protocol:~:text=Such%20object%20is,not%20iterators.)
+   */
+  private static final class JsIterableIteratorAdapter<T> implements JsIterator<T>, JsIterable<T> {
+    private final JsIterator<T> delegate;
+
+    private JsIterableIteratorAdapter(JsIterator<T> delegate) {
+      this.delegate = delegate;
+    }
+
+    @Override
+    public final IIterableResult<T> _private_jsNext__() {
+      return delegate._private_jsNext__();
+    }
+
+    @Override
+    public final JsIterator<T> _private_jsIterator__() {
+      return this;
+    }
+  }
+
+  private JsIterableHelper() {}
+}

jre/java/javaemul/internal/JsIterableHelper.native.js

@@ -0,0 +1,9 @@
+/**
+ * @param {?T} value
+ * @param {boolean} done
+ * @return {!IIterableResult<T>}
+ * @template T
+ */
+JsIterableHelper.makeResult = function(value, done) {
+  return {value: value, done: done};
+};

jre/java/super-wasm/java/lang/Iterable.java

@@ -0,0 +1,45 @@
+/*
+ * Copyright 2007 Google Inc.
+ *
+ * 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
+ *
+ * http://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 java.lang;
+
+import static javaemul.internal.InternalPreconditions.checkNotNull;
+
+import java.util.Iterator;
+import java.util.Spliterator;
+import java.util.Spliterators;
+import java.util.function.Consumer;
+
+/**
+ * Allows an instance of a class implementing this interface to be used in the foreach statement.
+ * See <a href="https://docs.oracle.com/javase/8/docs/api/java/lang/Iterable.html">the official Java
+ * API doc</a> for details.
+ *
+ * @param <T> type of returned iterator
+ */
+public interface Iterable<T> {
+  Iterator<T> iterator();
+
+  default void forEach(Consumer<? super T> action) {
+    checkNotNull(action);
+    for (T t : this) {
+      action.accept(t);
+    }
+  }
+
+  default Spliterator<T> spliterator() {
+    return Spliterators.spliteratorUnknownSize(iterator(), 0);
+  }
+}

jre/java/super-wasm/java/util/Iterator.java

@@ -0,0 +1,44 @@
+/*
+ * Copyright 2007 Google Inc.
+ *
+ * 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
+ *
+ * http://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 java.util;
+
+import static javaemul.internal.InternalPreconditions.checkNotNull;
+
+import java.util.function.Consumer;
+
+/**
+ * See <a href="https://docs.oracle.com/javase/8/docs/api/java/util/Iterator.html">the official Java
+ * API doc</a> for details.
+ *
+ * @param <T> element type
+ */
+public interface Iterator<T> {
+
+  boolean hasNext();
+
+  T next();
+
+  default void forEachRemaining(Consumer<? super T> consumer) {
+    checkNotNull(consumer);
+    while (hasNext()) {
+      consumer.accept(next());
+    }
+  }
+
+  default void remove() {
+    throw new UnsupportedOperationException();
+  }
+}

jre/javatests/com/google/j2cl/jre/JsSuite.java

@@ -19,6 +19,7 @@
 import com.google.j2cl.jre.java.lang.JsStringTest;
 import com.google.j2cl.jre.java.lang.JsThrowableTest;
 import com.google.j2cl.jre.java.util.JsCollectionTest;
+import com.google.j2cl.jre.java.util.JsIteratorTest;
 import org.junit.runner.RunWith;
 import org.junit.runners.Suite;
 import org.junit.runners.Suite.SuiteClasses;
@@ -30,5 +31,6 @@
   JsThrowableTest.class,
   JsStringTest.class,
   JsCollectionTest.class,
+  JsIteratorTest.class,
 })
 public class JsSuite {}

jre/javatests/com/google/j2cl/jre/java/util/JsIteratorTest.java

@@ -0,0 +1,33 @@
+/*
+ * Copyright 2026 Google Inc.
+ *
+ * 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
+ *
+ * http://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 com.google.j2cl.jre.java.util;
+
+import static org.junit.Assert.assertArrayEquals;
+
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.LinkedHashSet;
+import javaemul.internal.JsIterableHelper.JsIterable;
+import jsinterop.annotations.JsMethod;
+import jsinterop.annotations.JsPackage;
+import junit.framework.TestCase;
+
+/** Testing JS contract of Iterator interface. */
+public class JsIteratorTest extends TestCase {
+
+  @JsMethod(namespace = JsPackage.GLOBAL, name = "Array.from")
+  private static native String[] arrayFrom(JsIterable<String> jsIterable);
+}

transpiler/java/com/google/j2cl/transpiler/ast/JsUtils.java

@@ -33,7 +33,7 @@ public final class JsUtils {
    * characters but we disallow those for the time being.
    */
   public static boolean isValidJsIdentifier(String name) {
-    return name.matches(VALID_JS_NAME_REGEX);
+    return name.equals("[Symbol.iterator]") || name.matches(VALID_JS_NAME_REGEX);
   }
 
   /**