Iterables

/**
 * Returns true if the given test function returns true for every value
 * @param iterable - The iterable to test
 * @param test - Predicate function to test each element
 * @returns True if all elements pass the test, false otherwise
 */
function every(iterable: Iterable<any>, test: (value: any, index: number) => boolean): boolean;

import { every } from "d3-array";

every([2, 4, 6, 8], x => x % 2 === 0); // true (all even)
every([1, 2, 3, 4], x => x > 0); // true (all positive)
every([1, 2, 3, 4], x => x > 2); // false (not all > 2)

// Works with any iterable
every(new Set([1, 3, 5, 7]), x => x & 1); // true (all odd)

/**
 * Returns true if the given test function returns true for any value
 * @param iterable - The iterable to test
 * @param test - Predicate function to test each element
 * @returns True if any element passes the test, false otherwise
 */
function some(iterable: Iterable<any>, test: (value: any, index: number) => boolean): boolean;

import { some } from "d3-array";

some([1, 2, 3, 4], x => x > 3); // true (4 > 3)
some([1, 2, 3, 4], x => x > 10); // false (none > 10)

// Works with any iterable
some(new Set([0, 2, 3, 4]), x => x & 1); // true (3 is odd)

/**
 * Returns a new array containing the values that pass the given test
 * @param iterable - The iterable to filter
 * @param test - Predicate function to test each element
 * @returns New array with filtered elements
 */
function filter(iterable: Iterable<any>, test: (value: any, index: number) => boolean): any[];

import { filter } from "d3-array";

filter([1, 2, 3, 4, 5], x => x % 2 === 0); // [2, 4]

// Works with any iterable
filter(new Set([0, 2, 3, 4]), x => x & 1); // [3]
filter(new Map([['a', 1], ['b', 2], ['c', 3]]), ([key, value]) => value > 1);
// [['b', 2], ['c', 3]]

/**
 * Returns a new array containing the mapped values from iterable
 * @param iterable - The iterable to map
 * @param mapper - Function to transform each element
 * @returns New array with transformed elements
 */
function map(iterable: Iterable<any>, mapper: (value: any, index: number) => any): any[];

import { map } from "d3-array";

map([1, 2, 3, 4], x => x * 2); // [2, 4, 6, 8]
map(['hello', 'world'], s => s.toUpperCase()); // ['HELLO', 'WORLD']

// Works with any iterable
map(new Set([0, 2, 3, 4]), x => x & 1); // [0, 0, 1, 0]

/**
 * Returns the reduced value by repeatedly invoking the reducer function
 * @param iterable - The iterable to reduce
 * @param reducer - Function to combine values
 * @param initialValue - Optional initial value
 * @returns The final reduced value
 */
function reduce(
  iterable: Iterable<any>, 
  reducer: (accumulator: any, currentValue: any, index: number) => any, 
  initialValue?: any
): any;

import { reduce } from "d3-array";

// Sum with initial value
reduce([1, 2, 3, 4], (acc, val) => acc + val, 0); // 10

// Find maximum
reduce([3, 1, 4, 1, 5], (max, val) => val > max ? val : max, -Infinity); // 5

// Works with any iterable
reduce(new Set([0, 2, 3, 4]), (sum, val) => sum + val, 0); // 9

/**
 * Returns an array containing the values in reverse order
 * @param iterable - The iterable to reverse
 * @returns New array with elements in reverse order (does not mutate input)
 */
function reverse(iterable: Iterable<any>): any[];

import { reverse } from "d3-array";

reverse([1, 2, 3, 4]); // [4, 3, 2, 1]

// Works with any iterable (doesn't mutate original)
const originalSet = new Set([0, 2, 3, 1]);
reverse(originalSet); // [1, 3, 2, 0]
console.log(originalSet); // Set {0, 2, 3, 1} (unchanged)

/**
 * Returns an array containing the values in sorted order
 * @param iterable - The iterable to sort
 * @param comparator - Optional comparison function (defaults to ascending)
 * @returns New array with elements in sorted order (does not mutate input)
 */
function sort(iterable: Iterable<any>, comparator?: (a: any, b: any) => number): any[];

/**
 * Returns an array sorted by multiple accessor functions (for tie-breaking)
 * @param iterable - The iterable to sort
 * @param accessors - One or more accessor functions for sorting
 * @returns New array with elements in sorted order
 */
function sort(iterable: Iterable<any>, ...accessors: Array<(d: any) => any>): any[];

import { sort, ascending, descending } from "d3-array";

// Basic sort (natural order, not lexicographic)
sort([3, 1, 4, 1, 5]); // [1, 1, 3, 4, 5]
sort(['banana', 'apple', 'cherry']); // ['apple', 'banana', 'cherry']

// With comparator
sort([3, 1, 4, 1, 5], descending); // [5, 4, 3, 1, 1]

// With accessor (equivalent to comparator using ascending)
const data = [{name: 'Alice', age: 30}, {name: 'Bob', age: 25}];
sort(data, d => d.age); // [{name: 'Bob', age: 25}, {name: 'Alice', age: 30}]

// Multiple accessors for tie-breaking
const points = [{x: 1, y: 2}, {x: 1, y: 1}, {x: 0, y: 5}];
sort(points, d => d.x, d => d.y); // [{x: 0, y: 5}, {x: 1, y: 1}, {x: 1, y: 2}]

// Works with any iterable
sort(new Set([3, 1, 4, 1, 5])); // [1, 3, 4, 5] (duplicates removed by Set)

import { map, filter, reduce, sort } from "d3-array";

// Arrays (built-in methods available, but d3-array provides consistency)
const arr = [1, 2, 3, 4, 5];
map(arr, x => x * 2);

// Sets
const set = new Set([1, 2, 3, 4, 5]);
filter(set, x => x % 2 === 0); // [2, 4]

// Maps (iterates over [key, value] pairs)
const map1 = new Map([['a', 1], ['b', 2], ['c', 3]]);
map(map1, ([key, value]) => key + value); // ['a1', 'b2', 'c3']

// Generators
function* fibonacci() {
  let [a, b] = [0, 1];
  while (a < 20) {
    yield a;
    [a, b] = [b, a + b];
  }
}
const fibArray = Array.from(fibonacci()); // [0, 1, 1, 2, 3, 5, 8, 13]
sort(fibArray, descending); // [13, 8, 5, 3, 2, 1, 1, 0]

import { map, filter, sort, ascending } from "d3-array";

const data = [
  {name: 'Alice', score: 85, active: true},
  {name: 'Bob', score: 92, active: false},
  {name: 'Charlie', score: 78, active: true},
  {name: 'Diana', score: 96, active: true}
];

// Chain operations using function composition
const result = sort(
  map(
    filter(data, d => d.active),
    d => ({...d, grade: d.score >= 90 ? 'A' : d.score >= 80 ? 'B' : 'C'})
  ),
  (a, b) => ascending(a.score, b.score)
);

// Result: Active students with grades, sorted by score
// [{name: 'Charlie', score: 78, active: true, grade: 'C'},
//  {name: 'Alice', score: 85, active: true, grade: 'B'},
//  {name: 'Diana', score: 96, active: true, grade: 'A'}]