feat(collections/unstable): add interleave

collections/deno.json

@@ -53,6 +53,7 @@
     "./unstable-drop-while": "./unstable_drop_while.ts",
     "./unstable-find-single": "./unstable_find_single.ts",
     "./unstable-first-not-nullish-of": "./unstable_first_not_nullish_of.ts",
+    "./unstable-interleave": "./unstable_interleave.ts",
     "./unstable-join-to-string": "./unstable_join_to_string.ts",
     "./unstable-map-not-nullish": "./unstable_map_not_nullish.ts",
     "./unstable-max-by": "./unstable_max_by.ts",

collections/unstable_interleave.ts

@@ -0,0 +1,67 @@
+// Copyright 2018-2026 the Deno authors. MIT license.
+// This module is browser compatible.
+
+/**
+ * Merges multiple arrays into a single array by round-robin picking one
+ * element from each source in turn. Unlike {@linkcode zip}, which stops at
+ * the shortest array and produces tuples, `interleave` continues through
+ * all elements and returns a flat array.
+ *
+ * @experimental **UNSTABLE**: New API, yet to be vetted.
+ *
+ * @typeParam T Tuple of element types, one per input array; result is
+ * `T[number][]`.
+ *
+ * @param arrays The arrays to interleave.
+ * @returns A new array containing elements from all input arrays in
+ * round-robin order.
+ *
+ * @example Basic usage
+ * ```ts
+ * import { interleave } from "@std/collections/unstable-interleave";
+ * import { assertEquals } from "@std/assert";
+ *
+ * const numbers = [1, 2, 3];
+ * const letters = ["a", "b", "c"];
+ *
+ * assertEquals(interleave(numbers, letters), [1, "a", 2, "b", 3, "c"]);
+ * ```
+ *
+ * @example Unequal-length arrays
+ * ```ts
+ * import { interleave } from "@std/collections/unstable-interleave";
+ * import { assertEquals } from "@std/assert";
+ *
+ * assertEquals(
+ *   interleave([1, 2, 3], ["a", "b"], [true]),
+ *   [1, "a", true, 2, "b", 3],
+ * );
+ * ```
+ */
+export function interleave<T extends unknown[]>(
+  ...arrays: { [K in keyof T]: ReadonlyArray<T[K]> }
+): T[number][] {
+  const arrayCount = arrays.length;
+  if (arrayCount === 0) return [];
+
+  let maxLength = 0;
+  let totalLength = 0;
+  for (let i = 0; i < arrayCount; ++i) {
+    const len = arrays[i]!.length;
+    totalLength += len;
+    if (len > maxLength) maxLength = len;
+  }
+
+  const result: T[number][] = new Array(totalLength);
+  let k = 0;
+
+  for (let i = 0; i < maxLength; ++i) {
+    for (let j = 0; j < arrayCount; ++j) {
+      if (i < arrays[j]!.length) {
+        result[k++] = arrays[j]![i] as T[number];
+      }
+    }
+  }
+
+  return result;
+}

collections/unstable_interleave_test.ts

@@ -0,0 +1,81 @@
+// Copyright 2018-2026 the Deno authors. MIT license.
+
+import { assertEquals } from "@std/assert";
+import { interleave } from "./unstable_interleave.ts";
+
+Deno.test({
+  name: "interleave() handles no arguments",
+  fn() {
+    assertEquals(interleave(), []);
+  },
+});
+
+Deno.test({
+  name: "interleave() handles single array",
+  fn() {
+    assertEquals(interleave([1, 2, 3]), [1, 2, 3]);
+  },
+});
+
+Deno.test({
+  name: "interleave() handles two equal-length arrays",
+  fn() {
+    assertEquals(
+      interleave([1, 2, 3], ["a", "b", "c"]),
+      [1, "a", 2, "b", 3, "c"],
+    );
+  },
+});
+
+Deno.test({
+  name: "interleave() handles first array shorter",
+  fn() {
+    assertEquals(
+      interleave([1], ["a", "b", "c"]),
+      [1, "a", "b", "c"],
+    );
+  },
+});
+
+Deno.test({
+  name: "interleave() handles multiple unequal-length arrays",
+  fn() {
+    assertEquals(
+      interleave([1, 2, 3], ["a", "b"], [true]),
+      [1, "a", true, 2, "b", 3],
+    );
+  },
+});
+
+Deno.test({
+  name: "interleave() handles empty arrays in input",
+  fn() {
+    assertEquals(interleave([], [1, 2, 3]), [1, 2, 3]);
+    assertEquals(interleave([1, 2], [], [3, 4]), [1, 3, 2, 4]);
+    assertEquals(interleave([], [], []), []);
+  },
+});
+
+Deno.test({
+  name: "interleave() handles no mutation",
+  fn() {
+    const a = [1, 2, 3];
+    const b = ["x", "y"];
+    interleave(a, b);
+
+    assertEquals(a, [1, 2, 3]);
+    assertEquals(b, ["x", "y"]);
+  },
+});
+
+Deno.test({
+  name: "interleave() handles sparse arrays",
+  fn() {
+    // deno-lint-ignore no-sparse-arrays
+    const sparse = [1, , 3];
+    assertEquals(
+      interleave(sparse, ["a", "b", "c"]),
+      [1, "a", undefined, "b", 3, "c"],
+    );
+  },
+});