typedash/dist/single/index.d.cts

modern, type-safe collection of utility functions

import { M as Maybe } from '../Maybe-D6dwMjD9.cjs';

/**
 * Returns the single element of an iterable, or `undefined` if there are zero or multiple matches.
 * @param source The iterable to search.
 * @returns The single element, or `undefined` if there are zero or multiple matches.
 * @example
 * ```ts
 * single([1, 2, 3]); // undefined (because there are multiple elements in the array)
 * single([1]); // 1 (because there's only one element in the array)
 * ```
 */
declare function single<T>(source: Maybe<Iterable<T>>): T | undefined;
/**
 * Returns the single element of an iterable that satisfies a predicate.
 * @param source The iterable to search.
 * @param predicate The predicate function used to determine if an element is a match.
 * @returns The single matching element, or `undefined` if there are zero or multiple matches.
 * @example
 * ```ts
 * single([1, 2, 3], x => x % 2 === 0); // 2 (because there's only one even number in the array)
 * single([1, 2, 3], x => x >= 1); // undefined (because there are multiple matches for the predicate)
 * ```
 */
declare function single<T>(source: Maybe<Iterable<T>>, predicate?: (value: T, index: number) => boolean): T | undefined;
/**
 * Returns the single element of an iterable that satisfies a predicate.
 * @param source The iterable to search.
 * @param predicate The predicate function used to determine if an element is a match.
 * @returns The single matching element, or undefined if there are zero or multiple matches.
 * @example
 * ```ts
 * interface Person {
 *   name: string;
 *   age: number;
 * }
 *
 * const people: (Person | number)[] = [
 *   { name: 'Alice', age: 30 },
 *   50,
 * ];
 *
 * declare function isPerson(value: unknown): value is Person;
 *
 * const result = single(people, isPerson); // { name: 'Alice', age: 30 }
 * //     ^? Person | undefined
 * ```
 */
declare function single<T, S>(source: Maybe<Iterable<T>>, predicate?: (value: S, index: number) => value is S): S | undefined;

export { single };