feat(collections): stabilize index argument in iterable methods

collections/deno.json

@@ -48,23 +48,7 @@
     "./union": "./union.ts",
     "./unstable-binary-search": "./unstable_binary_search.ts",
     "./unstable-cycle": "./unstable_cycle.ts",
-    "./unstable-distinct-by": "./unstable_distinct_by.ts",
-    "./unstable-drop-last-while": "./unstable_drop_last_while.ts",
-    "./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",
-    "./unstable-max-of": "./unstable_max_of.ts",
-    "./unstable-min-by": "./unstable_min_by.ts",
-    "./unstable-min-of": "./unstable_min_of.ts",
-    "./unstable-partition": "./unstable_partition.ts",
-    "./unstable-sort-by": "./unstable_sort_by.ts",
-    "./unstable-sum-of": "./unstable_sum_of.ts",
-    "./unstable-take-last-while": "./unstable_take_last_while.ts",
-    "./unstable-take-while": "./unstable_take_while.ts",
     "./unzip": "./unzip.ts",
     "./without-all": "./without_all.ts",
     "./zip": "./zip.ts"

collections/distinct_by.ts

@@ -12,7 +12,7 @@
  *
  * @param array The array to filter for distinct elements.
  * @param discriminator The function to extract the value to compare for
- * uniqueness.
+ * uniqueness. The function receives the element and its index.
  *
  * @returns An array of distinct elements in the input array.
  *
@@ -26,15 +26,27 @@
  *
  * assertEquals(uniqueUsers, [{ id: 1, name: "Anna" }, { id: 2, name: "Kim" }]);
  * ```
+ *
+ * @example Using the index parameter
+ * ```ts
+ * import { distinctBy } from "@std/collections/distinct-by";
+ * import { assertEquals } from "@std/assert";
+ *
+ * const items = [25, "asdf", true];
+ * const result = distinctBy(items, (_, index) => index > 1);
+ *
+ * assertEquals(result, [25, true]);
+ * ```
  */
 export function distinctBy<T, D>(
   array: Iterable<T>,
-  discriminator: (el: T) => D,
+  discriminator: (el: T, index: number) => D,
 ): T[] {
   const keys = new Set<D>();
   const result: T[] = [];
+  let index = 0;
   for (const element of array) {
-    const key = discriminator(element);
+    const key = discriminator(element, index++);
     if (!keys.has(key)) {
       keys.add(key);
       result.push(element);

collections/distinct_by_test.ts

@@ -2,7 +2,6 @@
 
 import { assertEquals } from "@std/assert";
 import { distinctBy } from "./distinct_by.ts";
-import * as unstable from "./unstable_distinct_by.ts";
 
 function distinctByTest<I>(
   array: Array<I>,
@@ -122,7 +121,7 @@ Deno.test({
 Deno.test({
   name: "distinctBy() passes index to discriminator",
   fn() {
-    const result = unstable.distinctBy(
+    const result = distinctBy(
       [25, "asdf", true],
       (_, index) => index > 1,
     );

collections/drop_last_while.ts

@@ -8,7 +8,8 @@
  * @typeParam T The type of the elements in the input iterable.
  *
  * @param iterable The iterable to drop elements from.
- * @param predicate The function to test each element for a condition.
+ * @param predicate The function to test each element for a condition. The
+ * function receives the element and its index.
  *
  * @returns An array that drops all elements until the last element that does
  * not match the given predicate.
@@ -24,14 +25,25 @@
  *
  * assertEquals(notFortyFour, [11, 42, 55, 20]);
  * ```
+ *
+ * @example Using the index parameter
+ * ```ts
+ * import { dropLastWhile } from "@std/collections/drop-last-while";
+ * import { assertEquals } from "@std/assert";
+ *
+ * const array = [20, 30, 20];
+ * const result = dropLastWhile(array, (_, index) => index > 1);
+ *
+ * assertEquals(result, [20, 30]);
+ * ```
  */
 export function dropLastWhile<T>(
   iterable: Iterable<T>,
-  predicate: (el: T) => boolean,
+  predicate: (el: T, index: number) => boolean,
 ): T[] {
   const array = Array.isArray(iterable) ? iterable : Array.from(iterable);
   let offset = array.length - 1;
-  while (offset >= 0 && predicate(array[offset]!)) {
+  while (offset >= 0 && predicate(array[offset]!, offset)) {
     offset--;
   }
   return array.slice(0, offset + 1);

collections/drop_last_while_test.ts

@@ -1,7 +1,6 @@
 // Copyright 2018-2026 the Deno authors. MIT license.
 import { dropLastWhile } from "./drop_last_while.ts";
 import { assertEquals } from "@std/assert";
-import * as unstable from "./unstable_drop_last_while.ts";
 
 Deno.test("dropLastWhile() handles num array", () => {
   const values = [20, 33, 44];
@@ -82,10 +81,10 @@ Deno.test("dropLastWhile() handles a generator", () => {
   assertEquals(actual, [20]);
 });
 
-Deno.test("unstable.dropLastWhile() passes index to predicate", () => {
+Deno.test("dropLastWhile() passes index to predicate", () => {
   const array = [20, 30, 20];
 
-  const actual = unstable.dropLastWhile(array, (_, index) => index > 1);
+  const actual = dropLastWhile(array, (_, index) => index > 1);
 
   assertEquals(actual, [20, 30]);
 });

collections/drop_while.ts

@@ -8,7 +8,8 @@
  * @typeParam T The type of the elements in the input iterable.
  *
  * @param iterable The iterable to drop elements from.
- * @param predicate The function to test each element for a condition.
+ * @param predicate The function to test each element for a condition. The
+ * function receives the element and its index.
  *
  * @returns An array that drops all elements until the first element that
  * does not match the given predicate.
@@ -23,22 +24,34 @@
  *
  * assertEquals(dropWhileNumbers, [2, 5, 2, 5]);
  * ```
+ *
+ * @example Using the index parameter
+ * ```ts
+ * import { dropWhile } from "@std/collections/drop-while";
+ * import { assertEquals } from "@std/assert";
+ *
+ * const array = [20, 30, 20];
+ * const result = dropWhile(array, (_, index) => index < 1);
+ *
+ * assertEquals(result, [30, 20]);
+ * ```
  */
 export function dropWhile<T>(
   iterable: Iterable<T>,
-  predicate: (el: T) => boolean,
+  predicate: (el: T, index: number) => boolean,
 ): T[] {
   if (Array.isArray(iterable)) {
-    const idx = iterable.findIndex((el) => !predicate(el));
+    const idx = iterable.findIndex((el, index) => !predicate(el, index));
     if (idx === -1) {
       return [];
     }
     return iterable.slice(idx);
   }
   const array: T[] = [];
+  let index = 0;
   let found = false;
   for (const item of iterable) {
-    if (found || !predicate(item)) {
+    if (found || !predicate(item, index++)) {
       found = true;
       array.push(item);
     }

collections/drop_while_test.ts

@@ -2,7 +2,6 @@
 
 import { assertEquals } from "@std/assert";
 import { dropWhile } from "./drop_while.ts";
-import * as unstable from "./unstable_drop_while.ts";
 
 Deno.test("dropWhile() handles Array", () => {
   const arr = [1, 2, 3, 4, 5, 6];
@@ -109,10 +108,10 @@ Deno.test("dropWhile() handles a Map", () => {
   ]);
 });
 
-Deno.test("unstable.dropWhile() passes index to predicate", () => {
+Deno.test("dropWhile() passes index to predicate", () => {
   const array = [20, 30, 20];
 
-  const actual = unstable.dropWhile(array, (_, index) => index < 1);
+  const actual = dropWhile(array, (_, index) => index < 1);
 
   assertEquals(actual, [30, 20]);
 });

collections/find_single.ts

@@ -8,7 +8,8 @@
  * @typeParam T The type of the elements in the input array.
  *
  * @param array The array to find a single element in.
- * @param predicate The function to test each element for a condition.
+ * @param predicate The function to test each element for a condition. The
+ * function receives the element and its index.
  *
  * @returns The single element that matches the given condition or `undefined`
  * if there are zero or more than one matching elements.
@@ -29,15 +30,27 @@
  * assertEquals(activeBooking, { month: "June", active: true });
  * assertEquals(inactiveBooking, undefined); // There are two applicable items
  * ```
+ *
+ * @example Using the index parameter
+ * ```ts
+ * import { findSingle } from "@std/collections/find-single";
+ * import { assertEquals } from "@std/assert";
+ *
+ * const array = [9, 12, 13];
+ * const result = findSingle(array, (_, index) => index === 1);
+ *
+ * assertEquals(result, 12);
+ * ```
  */
 export function findSingle<T>(
   array: Iterable<T>,
-  predicate: (el: T) => boolean,
+  predicate: (el: T, index: number) => boolean,
 ): T | undefined {
   let match: T | undefined;
   let found = false;
+  let index = 0;
   for (const element of array) {
-    if (predicate(element)) {
+    if (predicate(element, index++)) {
       if (found) return undefined;
       found = true;
       match = element;

collections/find_single_test.ts

@@ -2,7 +2,6 @@
 
 import { assertEquals } from "@std/assert";
 import { findSingle } from "./find_single.ts";
-import * as unstable from "./unstable_find_single.ts";
 
 function findSingleTest<I>(
   input: [Array<I>, (element: I) => boolean],
@@ -106,9 +105,9 @@ Deno.test({
 });
 
 Deno.test({
-  name: "unstable.findSingle() passes index to predicate",
+  name: "findSingle() passes index to predicate",
   fn() {
-    const result = unstable.findSingle(
+    const result = findSingle(
       [9, 12, 13],
       (_, index) => index === 1,
     );

collections/first_not_nullish_of.ts

@@ -33,10 +33,11 @@
  */
 export function firstNotNullishOf<T, O>(
   array: Iterable<T>,
-  selector: (item: T) => O | undefined | null,
+  selector: (item: T, index: number) => O | undefined | null,
 ): NonNullable<O> | undefined {
+  let index = 0;
   for (const current of array) {
-    const selected = selector(current);
+    const selected = selector(current, index++);
 
     if (selected !== null && selected !== undefined) {
       return selected as NonNullable<O>;

collections/first_not_nullish_of_test.ts

@@ -2,7 +2,6 @@
 
 import { assertEquals } from "@std/assert";
 import { firstNotNullishOf } from "./first_not_nullish_of.ts";
-import * as unstable from "./unstable_first_not_nullish_of.ts";
 
 function firstNotNullishOfTest<T, O>(
   input: [Array<T>, (el: T) => O | undefined | null],
@@ -88,9 +87,9 @@ Deno.test({
 });
 
 Deno.test({
-  name: "unstable.firstNotNullishOf() passes index to selector",
+  name: "firstNotNullishOf() passes index to selector",
   fn() {
-    const result = unstable.firstNotNullishOf(
+    const result = firstNotNullishOf(
       [1, 2, 3, 4],
       (it, index) => index < 1 ? null : it,
     );

collections/join_to_string.ts

@@ -77,7 +77,7 @@ export type JoinToStringOptions = {
  */
 export function joinToString<T>(
   array: Iterable<T>,
-  selector: (el: T) => string,
+  selector: (el: T, index: number) => string,
   options: Readonly<JoinToStringOptions> = {},
 ): string {
   const {
@@ -101,7 +101,7 @@ export function joinToString<T>(
       break;
     }
 
-    result += selector(el);
+    result += selector(el, index);
     index++;
   }
 

collections/join_to_string_test.ts

@@ -2,7 +2,6 @@
 
 import { assertEquals } from "@std/assert";
 import { joinToString } from "./join_to_string.ts";
-import * as unstable from "./unstable_join_to_string.ts";
 
 Deno.test({
   name: "joinToString() handles no mutation",
@@ -147,11 +146,11 @@ Deno.test({
 });
 
 Deno.test({
-  name: "unstable.joinToString() passes index to selector",
+  name: "joinToString() passes index to selector",
   fn() {
     const arr = ["Kim", "Anna", "Tim"];
 
-    const out = unstable.joinToString(arr, (it, index) => it + index);
+    const out = joinToString(arr, (it, index) => it + index);
 
     assertEquals(out, "Kim0,Anna1,Tim2");
   },

collections/map_not_nullish.ts

@@ -33,12 +33,13 @@
  */
 export function mapNotNullish<T, O>(
   array: Iterable<T>,
-  transformer: (el: T) => O,
+  transformer: (el: T, index: number) => O,
 ): NonNullable<O>[] {
   const result: NonNullable<O>[] = [];
+  let index = 0;
 
   for (const element of array) {
-    const transformedElement = transformer(element);
+    const transformedElement = transformer(element, index++);
 
     if (transformedElement !== undefined && transformedElement !== null) {
       result.push(transformedElement as NonNullable<O>);

collections/map_not_nullish_test.ts

@@ -2,7 +2,6 @@
 
 import { assertEquals } from "@std/assert";
 import { mapNotNullish } from "./map_not_nullish.ts";
-import * as unstable from "./unstable_map_not_nullish.ts";
 
 function mapNotNullishTest<T, O>(
   input: [Array<T>, (el: T) => O | undefined | null],
@@ -93,9 +92,9 @@ Deno.test({
 });
 
 Deno.test({
-  name: "unstable.mapNotNullish() passes index to transformer",
+  name: "mapNotNullish() passes index to transformer",
   fn() {
-    const result = unstable.mapNotNullish(
+    const result = mapNotNullish(
       [1, 2, 3, 4],
       (it, index) => index === 1 ? null : it + index,
     );