feat(collections/unstable): add cycle iterator utility (#6386)

Author: EGAMAGZ

collections/deno.json

@@ -47,6 +47,7 @@
     "./take-while": "./take_while.ts",
     "./union": "./union.ts",
     "./unstable-chunk": "./unstable_chunk.ts",
+    "./unstable-cycle": "./unstable_cycle.ts",
     "./unstable-drop-while": "./unstable_drop_while.ts",
     "./unstable-drop-last-while": "./unstable_drop_last_while.ts",
     "./unstable-intersect": "./unstable_intersect.ts",

collections/unstable_cycle.ts

@@ -0,0 +1,42 @@
+// Copyright 2018-2025 the Deno authors. MIT license.
+
+/**
+ * Creates an iterator that cycles indefinitely over the provided iterable.
+ *
+ * Each time the iterable is exhausted, a new iterator is obtained to start the cycle again.
+ * This generator will yield the values from the iterable continuously.
+ *
+ * > **Note:** If the iterable is empty, the generator will keep restarting and yield nothing.
+ *
+ * @typeParam T The type of the elements in the iterable.
+ * @param iterable The iterable whose values are to be cycled.
+ * @returns A generator that yields values from the iterable in an endless cycle.
+ *
+ * @example Basic usage
+ * ```ts
+ * import { cycle } from "@std/collections/unstable-cycle";
+ * import { assertEquals } from "@std/assert";
+ *
+ * const cyclic = cycle([1, 2, 3]);
+ * const result: number[] = [];
+ *
+ * for (const num of cyclic) {
+ *   result.push(num);
+ *   if (result.length === 7) break;
+ * }
+ *
+ * assertEquals(result, [1, 2, 3, 1, 2, 3, 1]);
+ * ```
+ */
+export function* cycle<T>(iterable: Iterable<T>): Generator<T> {
+  let iterator = iterable[Symbol.iterator]();
+
+  while (true) {
+    const result = iterator.next();
+    if (result.done) {
+      iterator = iterable[Symbol.iterator]();
+    } else {
+      yield result.value;
+    }
+  }
+}

collections/unstable_cycle_test.ts

@@ -0,0 +1,62 @@
+// Copyright 2018-2025 the Deno authors. MIT license.
+
+import { assertEquals } from "@std/assert";
+import { cycle } from "./unstable_cycle.ts";
+
+Deno.test({
+  name: "cycle() basic usage with an array",
+  fn() {
+    const cyclic = cycle([1, 2, 3]);
+    const result = [];
+
+    for (const num of cyclic) {
+      result.push(num);
+      if (result.length === 7) break;
+    }
+    assertEquals(result, [1, 2, 3, 1, 2, 3, 1]);
+  },
+});
+
+Deno.test({
+  name: "cycle() works with a string iterable",
+  fn() {
+    const cyclic = cycle("ab");
+    const result = [];
+
+    for (const ch of cyclic) {
+      result.push(ch);
+      if (result.length === 5) break;
+    }
+    assertEquals(result, ["a", "b", "a", "b", "a"]);
+  },
+});
+
+Deno.test({
+  name: "cycle() works with a single element iterable",
+  fn() {
+    const cyclic = cycle([42]);
+    const result = [];
+
+    for (const num of cyclic) {
+      result.push(num);
+      if (result.length === 4) break;
+    }
+    assertEquals(result, [42, 42, 42, 42]);
+  },
+});
+
+Deno.test({
+  name: "cycle() does not mutate the input iterable",
+  fn() {
+    const input = [1, 2, 3];
+    const cyclic = cycle(input);
+
+    const result = [];
+    for (const num of cyclic) {
+      result.push(num);
+      if (result.length === 5) break;
+    }
+
+    assertEquals(input, [1, 2, 3]);
+  },
+});