All files / collections / mod.ts

/**
 * Pure functions for common tasks around collection types like arrays and
 * objects.
 *
 * Inspired by
 * {@link https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.collections/ | Kotlin's Collections}
 * package and {@link https://lodash.com/ | Lodash}.
 *
 * ```ts
 * import { intersect, sample, pick } from "@std/collections";
 * import { assertEquals, assertArrayIncludes } from "@std/assert";
 *
 * const lisaInterests = ["Cooking", "Music", "Hiking"];
 * const kimInterests = ["Music", "Tennis", "Cooking"];
 *
 * assertEquals(intersect(lisaInterests, kimInterests), ["Cooking", "Music"]);
 *
 * assertArrayIncludes(lisaInterests, [sample(lisaInterests)]);
 *
 * const cat = { name: "Lulu", age: 3, breed: "Ragdoll" };
 *
 * assertEquals(pick(cat, ["name", "breed"]), { name: "Lulu", breed: "Ragdoll"});
 * ```
 *
 * @module
 */
import { aggregateGroups as _function_aggregateGroups } from "jsr:@std/[email protected]"
/**
 * Applies the given aggregator to each group in the given grouping, returning the
 * results together with the respective group keys
 *
 * @template T Type of the values in the input record.
 * @template A Type of the accumulator value, which will match the returned
 * record's values.
 *
 * @param record The grouping to aggregate.
 * @param aggregator The function to apply to each group.
 *
 * @return A record with the same keys as the input record, but with the values
 * being the result of applying the aggregator to each group.
 *
 * @example Basic usage
 * ```ts
 * import { aggregateGroups } from "@std/collections/aggregate-groups";
 * import { assertEquals } from "@std/assert";
 *
 * const foodProperties = {
 *   Curry: ["spicy", "vegan"],
 *   Omelette: ["creamy", "vegetarian"],
 * };
 *
 * const descriptions = aggregateGroups(
 *   foodProperties,
 *   (current, key, first, acc) => {
 *     return first
 *       ? `${key} is ${current}`
 *       : `${acc} and ${current}`;
 *   },
 * );
 *
 * assertEquals(descriptions, {
 *   Curry: "Curry is spicy and vegan",
 *   Omelette: "Omelette is creamy and vegetarian",
 * });
 * ```
 */
const aggregateGroups = _function_aggregateGroups as typeof _function_aggregateGroups
export { aggregateGroups }

import { associateBy as _function_associateBy } from "jsr:@std/[email protected]"
/**
 * Creates a record by associating each element of the input array with a key
 * generated by the selector function.
 *
 * If the selector produces the same key for multiple elements, the latest one
 * will be used (overriding the ones before it).
 *
 * @template T Type of the elements in the input array.
 *
 * @param array The array to transform.
 * @param selector The function to extract the key from each element.
 *
 * @return A record with the keys produced by the selector and the elements as
 * values.
 *
 * @example Basic usage
 * ```ts
 * import { associateBy } from "@std/collections/associate-by";
 * import { assertEquals } from "@std/assert";
 *
 * const users = [
 *   { id: "a2e", userName: "Anna" },
 *   { id: "5f8", userName: "Arnold" },
 *   { id: "d2c", userName: "Kim" },
 * ];
 *
 * const usersById = associateBy(users, (user) => user.id);
 *
 * assertEquals(usersById, {
 *   "a2e": { id: "a2e", userName: "Anna" },
 *   "5f8": { id: "5f8", userName: "Arnold" },
 *   "d2c": { id: "d2c", userName: "Kim" },
 * });
 * ```
 */
const associateBy = _function_associateBy as typeof _function_associateBy
export { associateBy }

import { associateWith as _function_associateWith } from "jsr:@std/[email protected]"
/**
 * Associates each string element of an array with a value returned by a selector
 * function.
 *
 * If any of two pairs would have the same value, the latest one will be used
 * (overriding the ones before it).
 *
 * @template T The type of the values returned by the selector function.
 *
 * @param array The array of elements to associate with values.
 * @param selector The selector function that returns a value for each element.
 *
 * @return An object where each element of the array is associated with a value
 * returned by the selector function.
 *
 * @example Basic usage
 * ```ts
 * import { associateWith } from "@std/collections/associate-with";
 * import { assertEquals } from "@std/assert";
 *
 * const names = ["Kim", "Lara", "Jonathan"];
 *
 * const namesToLength = associateWith(names, (person) => person.length);
 *
 * assertEquals(namesToLength, {
 *   "Kim": 3,
 *   "Lara": 4,
 *   "Jonathan": 8,
 * });
 * ```
 */
const associateWith = _function_associateWith as typeof _function_associateWith
export { associateWith }

import { chunk as _function_chunk } from "jsr:@std/[email protected]"
/**
 * Splits the given array into chunks of the given size and returns them.
 *
 * @template T Type of the elements in the input array.
 *
 * @param array The array to split into chunks.
 * @param size The size of the chunks. This must be a positive integer.
 *
 * @return An array of chunks of the given size.
 *
 * @example Basic usage
 * ```ts
 * import { chunk } from "@std/collections/chunk";
 * import { assertEquals } from "@std/assert";
 *
 * const words = [
 *   "lorem",
 *   "ipsum",
 *   "dolor",
 *   "sit",
 *   "amet",
 *   "consetetur",
 *   "sadipscing",
 * ];
 * const chunks = chunk(words, 3);
 *
 * assertEquals(
 *   chunks,
 *   [
 *     ["lorem", "ipsum", "dolor"],
 *     ["sit", "amet", "consetetur"],
 *     ["sadipscing"],
 *   ],
 * );
 * ```
 */
const chunk = _function_chunk as typeof _function_chunk
export { chunk }

import { deepMerge as _function_deepMerge } from "jsr:@std/[email protected]"
/** UNDOCUMENTED */
const deepMerge = _function_deepMerge as typeof _function_deepMerge
export { deepMerge }

import type { MergingStrategy as _typeAlias_MergingStrategy } from "jsr:@std/[email protected]"
/**
 * Merging strategy
 */
type MergingStrategy = _typeAlias_MergingStrategy
export type { MergingStrategy }

import type { DeepMergeOptions as _typeAlias_DeepMergeOptions } from "jsr:@std/[email protected]"
/**
 * Options for {@linkcode deepMerge}.
 */
type DeepMergeOptions = _typeAlias_DeepMergeOptions
export type { DeepMergeOptions }

import type { ExpandRecursively as _typeAlias_ExpandRecursively } from "jsr:@std/[email protected]"
/**
 * Force intellisense to expand the typing to hide merging typings
 */
type ExpandRecursively<T> = _typeAlias_ExpandRecursively<T>
export type { ExpandRecursively }

import type { PartialByType as _typeAlias_PartialByType } from "jsr:@std/[email protected]"
/**
 * Filter of keys matching a given type
 */
type PartialByType<T, U> = _typeAlias_PartialByType<T, U>
export type { PartialByType }

import type { SetValueType as _typeAlias_SetValueType } from "jsr:@std/[email protected]"
/**
 * Get set values type
 */
type SetValueType<T> = _typeAlias_SetValueType<T>
export type { SetValueType }

import type { MergeAllSets as _typeAlias_MergeAllSets } from "jsr:@std/[email protected]"
/**
 * Merge all sets types definitions from keys present in both objects
 */
type MergeAllSets<T, U, X = PartialByType<T, Set<unknown>>, Y = PartialByType<U, Set<unknown>>, Z = { [K in keyof X & keyof Y]: Set<SetValueType<X[K]> | SetValueType<Y[K]>> }> = _typeAlias_MergeAllSets<T, U, X, Y, Z>
export type { MergeAllSets }

import type { ArrayValueType as _typeAlias_ArrayValueType } from "jsr:@std/[email protected]"
/**
 * Get array values type
 */
type ArrayValueType<T> = _typeAlias_ArrayValueType<T>
export type { ArrayValueType }

import type { MergeAllArrays as _typeAlias_MergeAllArrays } from "jsr:@std/[email protected]"
/**
 * Merge all sets types definitions from keys present in both objects
 */
type MergeAllArrays<T, U, X = PartialByType<T, Array<unknown>>, Y = PartialByType<U, Array<unknown>>, Z = { [K in keyof X & keyof Y]: Array<ArrayValueType<X[K]> | ArrayValueType<Y[K]>> }> = _typeAlias_MergeAllArrays<T, U, X, Y, Z>
export type { MergeAllArrays }

import type { MapKeyType as _typeAlias_MapKeyType } from "jsr:@std/[email protected]"
/**
 * Get map values types
 */
type MapKeyType<T> = _typeAlias_MapKeyType<T>
export type { MapKeyType }

import type { MapValueType as _typeAlias_MapValueType } from "jsr:@std/[email protected]"
/**
 * Get map values types
 */
type MapValueType<T> = _typeAlias_MapValueType<T>
export type { MapValueType }

import type { MergeAllMaps as _typeAlias_MergeAllMaps } from "jsr:@std/[email protected]"
/**
 * Merge all sets types definitions from keys present in both objects
 */
type MergeAllMaps<T, U, X = PartialByType<T, Map<unknown, unknown>>, Y = PartialByType<U, Map<unknown, unknown>>, Z = { [K in keyof X & keyof Y]: Map<MapKeyType<X[K]> | MapKeyType<Y[K]>, MapValueType<X[K]> | MapValueType<Y[K]>> }> = _typeAlias_MergeAllMaps<T, U, X, Y, Z>
export type { MergeAllMaps }

import type { MergeAllRecords as _typeAlias_MergeAllRecords } from "jsr:@std/[email protected]"
/**
 * Merge all records types definitions from keys present in both objects
 */
type MergeAllRecords<T, U, Options, X = PartialByType<T, Record<PropertyKey, unknown>>, Y = PartialByType<U, Record<PropertyKey, unknown>>, Z = { [K in keyof X & keyof Y]: DeepMerge<X[K], Y[K], Options> }> = _typeAlias_MergeAllRecords<T, U, Options, X, Y, Z>
export type { MergeAllRecords }

import type { OmitComplexes as _typeAlias_OmitComplexes } from "jsr:@std/[email protected]"
/**
 * Exclude map, sets and array from type
 */
type OmitComplexes<T> = _typeAlias_OmitComplexes<T>
export type { OmitComplexes }

import type { ObjectXorKeys as _typeAlias_ObjectXorKeys } from "jsr:@std/[email protected]"
/**
 * Object with keys in either T or U but not in both
 */
type ObjectXorKeys<T, U, X = Omit<T, keyof U> & Omit<U, keyof T>, Y = { [K in keyof X]: X[K] }> = _typeAlias_ObjectXorKeys<T, U, X, Y>
export type { ObjectXorKeys }

import type { MergeRightOmitComplexes as _typeAlias_MergeRightOmitComplexes } from "jsr:@std/[email protected]"
/**
 * Merge two objects, with left precedence
 */
type MergeRightOmitComplexes<T, U, X = ObjectXorKeys<T, U> & OmitComplexes<{ [K in keyof U]: U[K] }>> = _typeAlias_MergeRightOmitComplexes<T, U, X>
export type { MergeRightOmitComplexes }

import type { Merge as _typeAlias_Merge } from "jsr:@std/[email protected]"
/**
 * Merge two objects
 */
type Merge<
  T,
  U,
  Options,
  X =
    & MergeRightOmitComplexes<T, U>
    & MergeAllRecords<T, U, Options>
    & (Options extends { sets: "replace" } ? PartialByType<U, Set<unknown>> : MergeAllSets<T, U>)
    & (Options extends { arrays: "replace" } ? PartialByType<U, Array<unknown>> : MergeAllArrays<T, U>)
    & (Options extends { maps: "replace" } ? PartialByType<U, Map<unknown, unknown>> : MergeAllMaps<T, U>),
> = _typeAlias_Merge<T, U, Options, X>
export type { Merge }

import type { DeepMerge as _typeAlias_DeepMerge } from "jsr:@std/[email protected]"
/**
 * Merge deeply two objects
 */
type DeepMerge<T, U, Options = Record<string, MergingStrategy>> = _typeAlias_DeepMerge<T, U, Options>
export type { DeepMerge }

import { distinct as _function_distinct } from "jsr:@std/[email protected]"
/**
 * Returns all distinct elements in the given array, preserving order by first
 * occurrence.
 *
 * @template T The type of the elements in the input array.
 *
 * @param array The array to filter for distinct elements.
 *
 * @return An array of distinct elements in the input array.
 *
 * @example Basic usage
 * ```ts
 * import { distinct } from "@std/collections/distinct";
 * import { assertEquals } from "@std/assert";
 *
 * const numbers = [3, 2, 5, 2, 5];
 * const distinctNumbers = distinct(numbers);
 *
 * assertEquals(distinctNumbers, [3, 2, 5]);
 * ```
 */
const distinct = _function_distinct as typeof _function_distinct
export { distinct }

import { distinctBy as _function_distinctBy } from "jsr:@std/[email protected]"
/**
 * Returns all elements in the given array that produce a distinct value using
 * the given selector, preserving order by first occurrence.
 *
 * @template T The type of the elements in the input array.
 * @template D The type of the values produced by the selector function.
 *
 * @param array The array to filter for distinct elements.
 * @param selector The function to extract the value to compare for
 * distinctness.
 *
 * @return An array of distinct elements in the input array.
 *
 * @example Basic usage
 * ```ts
 * import { distinctBy } from "@std/collections/distinct-by";
 * import { assertEquals } from "@std/assert";
 *
 * const names = ["Anna", "Kim", "Arnold", "Kate"];
 * const exampleNamesByFirstLetter = distinctBy(names, (name) => name.charAt(0));
 *
 * assertEquals(exampleNamesByFirstLetter, ["Anna", "Kim"]);
 * ```
 */
const distinctBy = _function_distinctBy as typeof _function_distinctBy
export { distinctBy }

import { dropLastWhile as _function_dropLastWhile } from "jsr:@std/[email protected]"
/**
 * Returns a new array that drops all elements in the given collection until the
 * last element that does not match the given predicate.
 *
 * @template T The type of the elements in the input array.
 *
 * @param array The array to drop elements from.
 * @param predicate The function to test each element for a condition.
 *
 * @return A new array that drops all elements until the last element that does
 * not match the given predicate.
 *
 * @example Basic usage
 * ```ts
 * import { dropLastWhile } from "@std/collections/drop-last-while";
 * import { assertEquals } from "@std/assert";
 *
 * const numbers = [11, 42, 55, 20, 33, 44];
 *
 * const notFortyFour = dropLastWhile(numbers, (number) => number > 30);
 *
 * assertEquals(notFortyFour, [11, 42, 55, 20]);
 * ```
 */
const dropLastWhile = _function_dropLastWhile as typeof _function_dropLastWhile
export { dropLastWhile }

import { dropWhile as _function_dropWhile } from "jsr:@std/[email protected]"
/**
 * Returns a new array that drops all elements in the given collection until the
 * first element that does not match the given predicate.
 *
 * @template T The type of the elements in the input array.
 *
 * @param array The array to drop elements from.
 * @param predicate The function to test each element for a condition.
 *
 * @return A new array that drops all elements until the first element that
 * does not match the given predicate.
 *
 * @example Basic usage
 * ```ts
 * import { dropWhile } from "@std/collections/drop-while";
 * import { assertEquals } from "@std/assert";
 *
 * const numbers = [3, 2, 5, 2, 5];
 * const dropWhileNumbers = dropWhile(numbers, (number) => number !== 2);
 *
 * assertEquals(dropWhileNumbers, [2, 5, 2, 5]);
 * ```
 */
const dropWhile = _function_dropWhile as typeof _function_dropWhile
export { dropWhile }

import { filterEntries as _function_filterEntries } from "jsr:@std/[email protected]"
/**
 * Returns a new record with all entries of the given record except the ones
 * that do not match the given predicate.
 *
 * @template T The type of the values in the input record.
 *
 * @param record The record to filter entries from.
 * @param predicate The function to test each entry for a condition.
 *
 * @return A new record with all entries that match the given predicate.
 *
 * @example Basic usage
 * ```ts
 * import { filterEntries } from "@std/collections/filter-entries";
 * import { assertEquals } from "@std/assert";
 *
 * const menu = {
 *   Salad: 11,
 *   Soup: 8,
 *   Pasta: 13,
 * };
 *
 * const myOptions = filterEntries(
 *   menu,
 *   ([item, price]) => item !== "Pasta" && price < 10,
 * );
 *
 * assertEquals(myOptions, { Soup: 8 });
 * ```
 */
const filterEntries = _function_filterEntries as typeof _function_filterEntries
export { filterEntries }

import { filterKeys as _function_filterKeys } from "jsr:@std/[email protected]"
/**
 * Returns a new record with all entries of the given record except the ones that
 * have a key that does not match the given predicate.
 *
 * @template T The type of the values in the input record.
 *
 * @param record The record to filter keys from.
 * @param predicate The function to test each key for a condition.
 *
 * @return A new record with all entries that have a key that matches the given
 * predicate.
 *
 * @example Basic usage
 * ```ts
 * import { filterKeys } from "@std/collections/filter-keys";
 * import { assertEquals } from "@std/assert";
 *
 * const menu = {
 *   Salad: 11,
 *   Soup: 8,
 *   Pasta: 13,
 * };
 *
 * const menuWithoutSalad = filterKeys(menu, (item) => item !== "Salad");
 *
 * assertEquals(
 *   menuWithoutSalad,
 *   {
 *     Soup: 8,
 *     Pasta: 13,
 *   },
 * );
 * ```
 */
const filterKeys = _function_filterKeys as typeof _function_filterKeys
export { filterKeys }

import { filterValues as _function_filterValues } from "jsr:@std/[email protected]"
/**
 * Returns a new record with all entries of the given record except the ones
 * that have a value that does not match the given predicate.
 *
 * @template T The type of the values in the input record.
 *
 * @param record The record to filter values from.
 * @param predicate The function to test each value for a condition.
 *
 * @return A new record with all entries that have a value that matches the
 * given predicate.
 *
 * @example Basic usage
 * ```ts
 * import { filterValues } from "@std/collections/filter-values";
 * import { assertEquals } from "@std/assert";
 *
 * const people = {
 *   Arnold: 37,
 *   Sarah: 7,
 *   Kim: 23,
 * };
 * const adults = filterValues(people, (person) => person >= 18);
 *
 * assertEquals(
 *   adults,
 *   {
 *     Arnold: 37,
 *     Kim: 23,
 *   },
 * );
 * ```
 */
const filterValues = _function_filterValues as typeof _function_filterValues
export { filterValues }

import { findSingle as _function_findSingle } from "jsr:@std/[email protected]"
/**
 * Returns an element if and only if that element is the only one matching the
 * given condition. Returns `undefined` otherwise.
 *
 * @template 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.
 *
 * @return The single element that matches the given condition or `undefined`
 * if there are zero or more than one matching elements.
 *
 * @example Basic usage
 * ```ts
 * import { findSingle } from "@std/collections/find-single";
 * import { assertEquals } from "@std/assert";
 *
 * const bookings = [
 *   { month: "January", active: false },
 *   { month: "March", active: false },
 *   { month: "June", active: true },
 * ];
 * const activeBooking = findSingle(bookings, (booking) => booking.active);
 * const inactiveBooking = findSingle(bookings, (booking) => !booking.active);
 *
 * assertEquals(activeBooking, { month: "June", active: true });
 * assertEquals(inactiveBooking, undefined); // There are two applicable items
 * ```
 */
const findSingle = _function_findSingle as typeof _function_findSingle
export { findSingle }

import { firstNotNullishOf as _function_firstNotNullishOf } from "jsr:@std/[email protected]"
/**
 * Applies the given selector to elements in the given array until a value is
 * produced that is neither `null` nor `undefined` and returns that value.
 * Returns `undefined` if no such value is produced.
 *
 * @template T The type of the elements in the input array.
 * @template O The type of the value produced by the selector function.
 *
 * @param array The array to select a value from.
 * @param selector The function to extract a value from an element.
 *
 * @return The first non-`null` and non-`undefined` value produced by the
 * selector function, or `undefined` if no such value is produced.
 *
 * @example Basic usage
 * ```ts
 * import { firstNotNullishOf } from "@std/collections/first-not-nullish-of";
 * import { assertEquals } from "@std/assert";
 *
 * const tables = [
 *   { number: 11, order: null },
 *   { number: 12, order: "Soup" },
 *   { number: 13, order: "Salad" },
 * ];
 *
 * const nextOrder = firstNotNullishOf(tables, (table) => table.order);
 *
 * assertEquals(nextOrder, "Soup");
 * ```
 */
const firstNotNullishOf = _function_firstNotNullishOf as typeof _function_firstNotNullishOf
export { firstNotNullishOf }

import { includesValue as _function_includesValue } from "jsr:@std/[email protected]"
/**
 * Returns true if the given value is part of the given object, otherwise it
 * returns false.
 *
 * Note: this doesn't work with non-primitive values. For example,
 * `includesValue({x: {}}, {})` returns false.
 *
 * @template T The type of the values in the input record.
 *
 * @param record The record to check for the given value.
 * @param value The value to check for in the record.
 *
 * @return `true` if the value is part of the record, otherwise `false`.
 *
 * @example Basic usage
 * ```ts
 * import { includesValue } from "@std/collections/includes-value";
 * import { assertEquals } from "@std/assert";
 *
 * const input = {
 *   first: 33,
 *   second: 34,
 * };
 *
 * assertEquals(includesValue(input, 34), true);
 * ```
 */
const includesValue = _function_includesValue as typeof _function_includesValue
export { includesValue }

import { intersect as _function_intersect } from "jsr:@std/[email protected]"
/**
 * Returns all distinct elements that appear at least once in each of the given
 * arrays.
 *
 * @template T The type of the elements in the input arrays.
 *
 * @param arrays The arrays to intersect.
 *
 * @return An array of distinct elements that appear at least once in each of
 * the given arrays.
 *
 * @example Basic usage
 * ```ts
 * import { intersect } from "@std/collections/intersect";
 * import { assertEquals } from "@std/assert";
 *
 * const lisaInterests = ["Cooking", "Music", "Hiking"];
 * const kimInterests = ["Music", "Tennis", "Cooking"];
 * const commonInterests = intersect(lisaInterests, kimInterests);
 *
 * assertEquals(commonInterests, ["Cooking", "Music"]);
 * ```
 */
const intersect = _function_intersect as typeof _function_intersect
export { intersect }

import type { InvertByResult as _typeAlias_InvertByResult } from "jsr:@std/[email protected]"
/**
 * Return type for {@linkcode invertBy}.
 */
type InvertByResult<T extends Record<PropertyKey, PropertyKey>, K extends keyof T> = _typeAlias_InvertByResult<T, K>
export type { InvertByResult }

import { invertBy as _function_invertBy } from "jsr:@std/[email protected]"
/**
 * Composes a new record with all keys and values inverted.
 *
 * The new record is generated from the result of running each element of the
 * input record through the given transformer function.
 *
 * The corresponding inverted value of each inverted key is an array of keys
 * responsible for generating the inverted value.
 *
 * @template R The type of the input record.
 * @template T The type of the iterator function.
 *
 * @param record The record to invert.
 * @param transformer The function to transform keys.
 *
 * @return A new record with all keys and values inverted.
 *
 * @example Basic usage
 * ```ts
 * import { invertBy } from "@std/collections/invert-by";
 * import { assertEquals } from "@std/assert";
 *
 * const record = { a: "x", b: "y", c: "z" };
 *
 * assertEquals(
 *   invertBy(record, (key) => String(key).toUpperCase()),
 *   { X: ["a"], Y: ["b"], Z: ["c"] }
 * );
 * ```
 */
const invertBy = _function_invertBy as typeof _function_invertBy
export { invertBy }

import type { InvertResult as _typeAlias_InvertResult } from "jsr:@std/[email protected]"
/**
 * Return type for {@linkcode invert}.
 */
type InvertResult<T extends Record<PropertyKey, PropertyKey>> = _typeAlias_InvertResult<T>
export type { InvertResult }

import { invert as _function_invert } from "jsr:@std/[email protected]"
/**
 * Composes a new record with all keys and values inverted.
 *
 * If the record contains duplicate values, subsequent values overwrite property
 * assignments of previous values. If the record contains values which aren't
 * {@linkcode PropertyKey}s their string representation is used as the key.
 *
 * @template T The type of the input record.
 *
 * @param record The record to invert.
 *
 * @return A new record with all keys and values inverted.
 *
 * @example Basic usage
 * ```ts
 * import { invert } from "@std/collections/invert";
 * import { assertEquals } from "@std/assert";
 *
 * const record = { a: "x", b: "y", c: "z" };
 *
 * assertEquals(invert(record), { x: "a", y: "b", z: "c" });
 * ```
 */
const invert = _function_invert as typeof _function_invert
export { invert }

import type { JoinToStringOptions as _typeAlias_JoinToStringOptions } from "jsr:@std/[email protected]"
/**
 * Options for {@linkcode joinToString}.
 */
type JoinToStringOptions = _typeAlias_JoinToStringOptions
export type { JoinToStringOptions }

import { joinToString as _function_joinToString } from "jsr:@std/[email protected]"
/**
 * Transforms the elements in the given array to strings using the given
 * selector. Joins the produced strings into one using the given `separator`
 * and applying the given `prefix` and `suffix` to the whole string afterwards.
 *
 * If the array could be huge, you can specify a non-negative value of `limit`,
 * in which case only the first `limit` elements will be appended, followed by
 * the `truncated` string.
 *
 * @template T The type of the elements in the input array.
 *
 * @param array The array to join elements from.
 * @param selector The function to transform elements to strings.
 * @param options The options to configure the joining.
 *
 * @return The resulting string.
 *
 * @example Usage with options
 * ```ts
 * import { joinToString } from "@std/collections/join-to-string";
 * import { assertEquals } from "@std/assert";
 *
 * const users = [
 *   { name: "Kim" },
 *   { name: "Anna" },
 *   { name: "Tim" },
 * ];
 *
 * const message = joinToString(users, (user) => user.name, {
 *   suffix: " are winners",
 *   prefix: "result: ",
 *   separator: " and ",
 *   limit: 1,
 *   truncated: "others",
 * });
 *
 * assertEquals(message, "result: Kim and others are winners");
 * ```
 */
const joinToString = _function_joinToString as typeof _function_joinToString
export { joinToString }

import { mapEntries as _function_mapEntries } from "jsr:@std/[email protected]"
/**
 * Applies the given transformer to all entries in the given record and returns
 * a new record containing the results.
 *
 * @template T The type of the values in the input record.
 * @template O The type of the values in the output record.
 *
 * @param record The record to map entries from.
 * @param transformer The function to transform each entry.
 *
 * @return A new record with all entries transformed by the given transformer.
 *
 * @example Basic usage
 * ```ts
 * import { mapEntries } from "@std/collections/map-entries";
 * import { assertEquals } from "@std/assert";
 *
 * const usersById = {
 *   "a2e": { name: "Kim", age: 22 },
 *   "dfe": { name: "Anna", age: 31 },
 *   "34b": { name: "Tim", age: 58 },
 * };
 *
 * const agesByNames = mapEntries(usersById, ([id, { name, age }]) => [name, age]);
 *
 * assertEquals(
 *   agesByNames,
 *   {
 *     Kim: 22,
 *     Anna: 31,
 *     Tim: 58,
 *   },
 * );
 * ```
 */
const mapEntries = _function_mapEntries as typeof _function_mapEntries
export { mapEntries }

import { mapKeys as _function_mapKeys } from "jsr:@std/[email protected]"
/**
 * Applies the given transformer to all keys in the given record's entries and
 * returns a new record containing the transformed entries.
 *
 * If the transformed entries contain the same key multiple times, only the last
 * one will appear in the returned record.
 *
 * @template T The type of the values in the input record.
 *
 * @param record The record to map keys from.
 * @param transformer The function to transform each key.
 *
 * @return A new record with all keys transformed by the given transformer.
 *
 * @example Basic usage
 * ```ts
 * import { mapKeys } from "@std/collections/map-keys";
 * import { assertEquals } from "@std/assert";
 *
 * const counts = { a: 5, b: 3, c: 8 };
 *
 * assertEquals(
 *   mapKeys(counts, (key) => key.toUpperCase()),
 *   {
 *     A: 5,
 *     B: 3,
 *     C: 8,
 *   },
 * );
 * ```
 */
const mapKeys = _function_mapKeys as typeof _function_mapKeys
export { mapKeys }

import { mapNotNullish as _function_mapNotNullish } from "jsr:@std/[email protected]"
/**
 * Returns a new array, containing all elements in the given array transformed
 * using the given transformer, except the ones that were transformed to `null`
 * or `undefined`.
 *
 * @template T The type of the elements in the input array.
 * @template O The type of the elements in the output array.
 *
 * @param array The array to map elements from.
 * @param transformer The function to transform each element.
 *
 * @return A new array with all elements transformed by the given transformer,
 * except the ones that were transformed to `null` or `undefined`.
 *
 * @example Basic usage
 * ```ts
 * import { mapNotNullish } from "@std/collections/map-not-nullish";
 * import { assertEquals } from "@std/assert";
 *
 * const people = [
 *   { middleName: null },
 *   { middleName: "William" },
 *   { middleName: undefined },
 *   { middleName: "Martha" },
 * ];
 * const foundMiddleNames = mapNotNullish(people, (people) => people.middleName);
 *
 * assertEquals(foundMiddleNames, ["William", "Martha"]);
 * ```
 */
const mapNotNullish = _function_mapNotNullish as typeof _function_mapNotNullish
export { mapNotNullish }

import { mapValues as _function_mapValues } from "jsr:@std/[email protected]"
/** UNDOCUMENTED */
const mapValues = _function_mapValues as typeof _function_mapValues
export { mapValues }

import { maxBy as _function_maxBy } from "jsr:@std/[email protected]"
/** UNDOCUMENTED */
const maxBy = _function_maxBy as typeof _function_maxBy
export { maxBy }

import { maxOf as _function_maxOf } from "jsr:@std/[email protected]"
/** UNDOCUMENTED */
const maxOf = _function_maxOf as typeof _function_maxOf
export { maxOf }

import { maxWith as _function_maxWith } from "jsr:@std/[email protected]"
/**
 * Returns the first element having the largest value according to the provided
 * comparator or undefined if there are no elements.
 *
 * The comparator is expected to work exactly like one passed to `Array.sort`,
 * which means that `comparator(a, b)` should return a negative number if
 * `a < b`, a positive number if `a > b` and `0` if `a === b`.
 *
 * @template T The type of the elements in the array.
 *
 * @param array The array to find the maximum element in.
 * @param comparator The function to compare elements.
 *
 * @return The first element that is the largest value of the given function or
 * undefined if there are no elements.
 *
 * @example Basic usage
 * ```ts
 * import { maxWith } from "@std/collections/max-with";
 * import { assertEquals } from "@std/assert";
 *
 * const people = ["Kim", "Anna", "John", "Arthur"];
 * const largestName = maxWith(people, (a, b) => a.length - b.length);
 *
 * assertEquals(largestName, "Arthur");
 * ```
 */
const maxWith = _function_maxWith as typeof _function_maxWith
export { maxWith }

import { minBy as _function_minBy } from "jsr:@std/[email protected]"
/** UNDOCUMENTED */
const minBy = _function_minBy as typeof _function_minBy
export { minBy }

import { minOf as _function_minOf } from "jsr:@std/[email protected]"
/** UNDOCUMENTED */
const minOf = _function_minOf as typeof _function_minOf
export { minOf }

import { minWith as _function_minWith } from "jsr:@std/[email protected]"
/**
 * Returns the first element having the smallest value according to the provided
 * comparator or undefined if there are no elements.
 *
 * @template T The type of the elements in the array.
 *
 * @param array The array to find the minimum element in.
 * @param comparator The function to compare elements.
 *
 * @return The first element that is the smallest value of the given function
 * or undefined if there are no elements.
 *
 * @example Basic usage
 * ```ts
 * import { minWith } from "@std/collections/min-with";
 * import { assertEquals } from "@std/assert";
 *
 * const people = ["Kim", "Anna", "John"];
 * const smallestName = minWith(people, (a, b) => a.length - b.length);
 *
 * assertEquals(smallestName, "Kim");
 * ```
 */
const minWith = _function_minWith as typeof _function_minWith
export { minWith }

import { omit as _function_omit } from "jsr:@std/[email protected]"
/**
 * Creates a new object by excluding the specified keys from the provided object.
 *
 * @template T The type of the object.
 * @template K The type of the keys to omit.
 *
 * @param obj The object to omit keys from.
 * @param keys The keys to omit from the object.
 *
 * @return A new object with the specified keys omitted.
 *
 * @example Basic usage
 * ```ts
 * import { omit } from "@std/collections/omit";
 * import { assertEquals } from "@std/assert";
 *
 * const obj = { a: 5, b: 6, c: 7, d: 8 };
 * const omitted = omit(obj, ["a", "c"]);
 *
 * assertEquals(omitted, { b: 6, d: 8 });
 * ```
 */
const omit = _function_omit as typeof _function_omit
export { omit }

import { partition as _function_partition } from "jsr:@std/[email protected]"
/** UNDOCUMENTED */
const partition = _function_partition as typeof _function_partition
export { partition }

import { partitionEntries as _function_partitionEntries } from "jsr:@std/[email protected]"
/**
 * Returns a tuple of two records with the first one containing all entries of
 * the given record that match the given predicate and the second one containing
 * all that do not.
 *
 * @template T The type of the values in the record.
 *
 * @param record The record to partition.
 * @param predicate The predicate function to determine which entries go where.
 *
 * @return A tuple containing two records, the first one containing all entries
 * that match the predicate and the second one containing all that do not.
 *
 * @example Basic usage
 * ```ts
 * import { partitionEntries } from "@std/collections/partition-entries";
 * import { assertEquals } from "@std/assert";
 *
 * const menu = {
 *   Salad: 11,
 *   Soup: 8,
 *   Pasta: 13,
 * };
 * const myOptions = partitionEntries(
 *   menu,
 *   ([item, price]) => item !== "Pasta" && price < 10,
 * );
 *
 * assertEquals(
 *   myOptions,
 *   [
 *     { Soup: 8 },
 *     { Salad: 11, Pasta: 13 },
 *   ],
 * );
 * ```
 */
const partitionEntries = _function_partitionEntries as typeof _function_partitionEntries
export { partitionEntries }

import { permutations as _function_permutations } from "jsr:@std/[email protected]"
/**
 * Builds all possible orders of all elements in the given array
 * Ignores equality of elements, meaning this will always return the same
 * number of permutations for a given length of input.
 *
 * @template T The type of the elements in the array.
 *
 * @param inputArray The array to build permutations from.
 *
 * @return An array of all possible permutations of the given array.
 *
 * @example Basic usage
 * ```ts
 * import { permutations } from "@std/collections/permutations";
 * import { assertEquals } from "@std/assert";
 *
 * const numbers = [ 1, 2 ];
 * const windows = permutations(numbers);
 *
 * assertEquals(windows, [
 *   [ 1, 2 ],
 *   [ 2, 1 ],
 * ]);
 * ```
 */
const permutations = _function_permutations as typeof _function_permutations
export { permutations }

import { pick as _function_pick } from "jsr:@std/[email protected]"
/**
 * Creates a new object by including the specified keys from the provided
 * object.
 *
 * @template T The type of the object.
 * @template K The type of the keys.
 *
 * @param obj The object to pick keys from.
 * @param keys The keys to include in the new object.
 *
 * @return A new object with the specified keys from the provided object.
 *
 * @example Basic usage
 * ```ts
 * import { pick } from "@std/collections/pick";
 * import { assertEquals } from "@std/assert";
 *
 * const obj = { a: 5, b: 6, c: 7, d: 8 };
 * const picked = pick(obj, ["a", "c"]);
 *
 * assertEquals(picked, { a: 5, c: 7 });
 * ```
 */
const pick = _function_pick as typeof _function_pick
export { pick }

import { reduceGroups as _function_reduceGroups } from "jsr:@std/[email protected]"
/**
 * Applies the given reducer to each group in the given grouping, returning the
 * results together with the respective group keys.
 *
 * @template T input type of an item in a group in the given grouping.
 * @template A type of the accumulator value, which will match the returned
 * record's values.
 *
 * @param record The grouping to reduce.
 * @param reducer The reducer function to apply to each group.
 * @param initialValue The initial value of the accumulator.
 *
 * @return A record with the same keys as the input grouping, where each value
 * is the result of applying the reducer to the respective group.
 *
 * @example Basic usage
 * ```ts
 * import { reduceGroups } from "@std/collections/reduce-groups";
 * import { assertEquals } from "@std/assert";
 *
 * const votes = {
 *   Woody: [2, 3, 1, 4],
 *   Buzz: [5, 9],
 * };
 *
 * const totalVotes = reduceGroups(votes, (sum, vote) => sum + vote, 0);
 *
 * assertEquals(totalVotes, {
 *   Woody: 10,
 *   Buzz: 14,
 * });
 * ```
 */
const reduceGroups = _function_reduceGroups as typeof _function_reduceGroups
export { reduceGroups }

import { runningReduce as _function_runningReduce } from "jsr:@std/[email protected]"
/**
 * Calls the given reducer on each element of the given collection, passing its
 * result as the accumulator to the next respective call, starting with the
 * given initialValue. Returns all intermediate accumulator results.
 *
 * @template T The type of the elements in the array.
 * @template O The type of the accumulator.
 *
 * @param array The array to reduce.
 * @param reducer The reducer function to apply to each element.
 * @param initialValue The initial value of the accumulator.
 *
 * @return An array of all intermediate accumulator results.
 *
 * @example Basic usage
 * ```ts
 * import { runningReduce } from "@std/collections/running-reduce";
 * import { assertEquals } from "@std/assert";
 *
 * const numbers = [1, 2, 3, 4, 5];
 * const sumSteps = runningReduce(numbers, (sum, current) => sum + current, 0);
 *
 * assertEquals(sumSteps, [1, 3, 6, 10, 15]);
 * ```
 */
const runningReduce = _function_runningReduce as typeof _function_runningReduce
export { runningReduce }

import { sample as _function_sample } from "jsr:@std/[email protected]"
/**
 * Returns a random element from the given array.
 *
 * @template T The type of the elements in the array.
 * @template O The type of the accumulator.
 *
 * @param array The array to sample from.
 *
 * @return A random element from the given array, or `undefined` if the array
 * is empty.
 *
 * @example Basic usage
 * ```ts
 * import { sample } from "@std/collections/sample";
 * import { assertArrayIncludes } from "@std/assert";
 *
 * const numbers = [1, 2, 3, 4];
 * const random = sample(numbers);
 *
 * assertArrayIncludes(numbers, [random]);
 * ```
 */
const sample = _function_sample as typeof _function_sample
export { sample }

import type { SlidingWindowsOptions as _interface_SlidingWindowsOptions } from "jsr:@std/[email protected]"
/**
 * Options for {@linkcode slidingWindows}.
 */
interface SlidingWindowsOptions extends _interface_SlidingWindowsOptions {}
export type { SlidingWindowsOptions }

import { slidingWindows as _function_slidingWindows } from "jsr:@std/[email protected]"
/**
 * Generates sliding views of the given array of the given size and returns a
 * new array containing all of them.
 *
 * If step is set, each window will start that many elements after the last
 * window's start. (Default: 1)
 *
 * If partial is set, windows will be generated for the last elements of the
 * collection, resulting in some undefined values if size is greater than 1.
 *
 * @template T The type of the array elements.
 *
 * @param array The array to generate sliding windows from.
 * @param size The size of the sliding windows.
 * @param options The options for generating sliding windows.
 *
 * @return A new array containing all sliding windows of the given size.
 *
 * @example Usage
 * ```ts
 * import { slidingWindows } from "@std/collections/sliding-windows";
 * import { assertEquals } from "@std/assert";
 * const numbers = [1, 2, 3, 4, 5];
 *
 * const windows = slidingWindows(numbers, 3);
 * assertEquals(windows, [
 *   [1, 2, 3],
 *   [2, 3, 4],
 *   [3, 4, 5],
 * ]);
 *
 * const windowsWithStep = slidingWindows(numbers, 3, { step: 2 });
 * assertEquals(windowsWithStep, [
 *   [1, 2, 3],
 *   [3, 4, 5],
 * ]);
 *
 * const windowsWithPartial = slidingWindows(numbers, 3, { partial: true });
 * assertEquals(windowsWithPartial, [
 *   [1, 2, 3],
 *   [2, 3, 4],
 *   [3, 4, 5],
 *   [4, 5],
 *   [5],
 * ]);
 * ```
 */
const slidingWindows = _function_slidingWindows as typeof _function_slidingWindows
export { slidingWindows }

import type { Order as _typeAlias_Order } from "jsr:@std/[email protected]"
/**
 * Order option for {@linkcode SortByOptions}.
 */
type Order = _typeAlias_Order
export type { Order }

import type { SortByOptions as _typeAlias_SortByOptions } from "jsr:@std/[email protected]"
/**
 * Options for {@linkcode sortBy}.
 */
type SortByOptions = _typeAlias_SortByOptions
export type { SortByOptions }

import { sortBy as _function_sortBy } from "jsr:@std/[email protected]"
/** UNDOCUMENTED */
const sortBy = _function_sortBy as typeof _function_sortBy
export { sortBy }

import { sumOf as _function_sumOf } from "jsr:@std/[email protected]"
/**
 * Applies the given selector to all elements in the given collection and
 * calculates the sum of the results.
 *
 * @template T The type of the array elements.
 *
 * @param array The array to calculate the sum of.
 * @param selector The selector function to get the value to sum.
 *
 * @return The sum of all elements in the collection.
 *
 * @example Basic usage
 * ```ts
 * import { sumOf } from "@std/collections/sum-of";
 * import { assertEquals } from "@std/assert";
 *
 * const people = [
 *   { name: "Anna", age: 34 },
 *   { name: "Kim", age: 42 },
 *   { name: "John", age: 23 },
 * ];
 *
 * const totalAge = sumOf(people, (person) => person.age);
 *
 * assertEquals(totalAge, 99);
 * ```
 */
const sumOf = _function_sumOf as typeof _function_sumOf
export { sumOf }

import { takeLastWhile as _function_takeLastWhile } from "jsr:@std/[email protected]"
/**
 * Returns all elements in the given array after the last element that does not
 * match the given predicate.
 *
 * @template T The type of the array elements.
 *
 * @param array The array to take elements from.
 * @param predicate The predicate function to determine if an element should be
 * included.
 *
 * @return A new array containing all elements after the last element that does
 * not match the predicate.
 *
 * @example Basic usage
 * ```ts
 * import { takeLastWhile } from "@std/collections/take-last-while";
 * import { assertEquals } from "@std/assert";
 *
 * const numbers = [1, 2, 3, 4, 5, 6];
 *
 * const result = takeLastWhile(numbers, (number) => number > 4);
 *
 * assertEquals(result, [5, 6]);
 * ```
 */
const takeLastWhile = _function_takeLastWhile as typeof _function_takeLastWhile
export { takeLastWhile }

import { takeWhile as _function_takeWhile } from "jsr:@std/[email protected]"
/**
 * Returns all elements in the given collection until the first element that
 * does not match the given predicate.
 *
 * Note: If you want to process any iterable, use the new version of
 * `takeWhile` from `@std/collections/unstable-take-while`.
 *
 * @template T The type of the array elements.
 *
 * @param array The array to take elements from.
 * @param predicate The predicate function to determine if an element should be
 * included.
 *
 * @return A new array containing all elements until the first element that
 * does not match the predicate.
 *
 * @example Basic usage
 * ```ts
 * import { takeWhile } from "@std/collections/take-while";
 * import { assertEquals } from "@std/assert";
 *
 * const numbers = [1, 2, 3, 4, 5, 6];
 *
 * const result = takeWhile(numbers, (number) => number < 4);
 *
 * assertEquals(result, [1, 2, 3]);
 * ```
 */
const takeWhile = _function_takeWhile as typeof _function_takeWhile
export { takeWhile }

import { union as _function_union } from "jsr:@std/[email protected]"
/**
 * Returns all distinct elements that appear in any of the given arrays.
 *
 * @template T The type of the array elements.
 *
 * @param arrays The arrays to get the union of.
 *
 * @return A new array containing all distinct elements from the given arrays.
 *
 * @example Basic usage
 * ```ts
 * import { union } from "@std/collections/union";
 * import { assertEquals } from "@std/assert";
 *
 * const soupIngredients = ["Pepper", "Carrots", "Leek"];
 * const saladIngredients = ["Carrots", "Radicchio", "Pepper"];
 *
 * const shoppingList = union(soupIngredients, saladIngredients);
 *
 * assertEquals(shoppingList, ["Pepper", "Carrots", "Leek", "Radicchio"]);
 * ```
 */
const union = _function_union as typeof _function_union
export { union }

import { unzip as _function_unzip } from "jsr:@std/[email protected]"
/**
 * Builds two separate arrays from the given array of 2-tuples, with the first
 * returned array holding all first tuple elements and the second one holding
 * all the second elements.
 *
 * @template T The type of the first tuple elements.
 * @template U The type of the second tuple elements.
 *
 * @param pairs The array of 2-tuples to unzip.
 *
 * @return A tuple containing two arrays, the first one holding all first tuple
 * elements and the second one holding all second elements.
 *
 * @example Basic usage
 * ```ts
 * import { unzip } from "@std/collections/unzip";
 * import { assertEquals } from "@std/assert";
 *
 * const parents = [
 *   ["Maria", "Jeff"],
 *   ["Anna", "Kim"],
 *   ["John", "Leroy"],
 * ] as [string, string][];
 *
 * const [moms, dads] = unzip(parents);
 *
 * assertEquals(moms, ["Maria", "Anna", "John"]);
 * assertEquals(dads, ["Jeff", "Kim", "Leroy"]);
 * ```
 */
const unzip = _function_unzip as typeof _function_unzip
export { unzip }

import { withoutAll as _function_withoutAll } from "jsr:@std/[email protected]"
/**
 * Returns an array excluding all given values.
 *
 * @template T The type of the array elements.
 *
 * @param array The array to exclude values from.
 * @param values The values to exclude from the array.
 *
 * @return A new array containing all elements from the given array except the
 * ones that are in the values array.
 *
 * @example Basic usage
 * ```ts
 * import { withoutAll } from "@std/collections/without-all";
 * import { assertEquals } from "@std/assert";
 *
 * const withoutList = withoutAll([2, 1, 2, 3], [1, 2]);
 *
 * assertEquals(withoutList, [3]);
 * ```
 */
const withoutAll = _function_withoutAll as typeof _function_withoutAll
export { withoutAll }

import { zip as _function_zip } from "jsr:@std/[email protected]"
/**
 * Builds N-tuples of elements from the given N arrays with matching indices,
 * stopping when the smallest array's end is reached.
 *
 * @template T the type of the tuples produced by this function.
 *
 * @param arrays The arrays to zip.
 *
 * @return A new array containing N-tuples of elements from the given arrays.
 *
 * @example Basic usage
 * ```ts
 * import { zip } from "@std/collections/zip";
 * import { assertEquals } from "@std/assert";
 *
 * const numbers = [1, 2, 3, 4];
 * const letters = ["a", "b", "c", "d"];
 * const pairs = zip(numbers, letters);
 *
 * assertEquals(
 *   pairs,
 *   [
 *     [1, "a"],
 *     [2, "b"],
 *     [3, "c"],
 *     [4, "d"],
 *   ],
 * );
 * ```
 */
const zip = _function_zip as typeof _function_zip
export { zip }