itertools-ts/es/single.d.ts

Extended itertools port for TypeScript and JavaScript. Provides a huge set of functions for working with iterable collections (including async ones)

import { AsyncFlatMapper, Comparator, FlatMapper, Pair } from "./types";
/**
 * Map a function onto every element of the iteration.
 *
 * @param data
 * @param mapper
 */
export declare function map<TInput, TOutput>(data: Iterable<TInput> | Iterator<TInput>, mapper: (datum: TInput) => TOutput): Iterable<TOutput>;
/**
 * Map a function onto every element of the iteration for async collections.
 *
 * Mapper may be also async.
 *
 * @param data
 * @param mapper
 */
export declare function mapAsync<TInput, TOutput>(data: AsyncIterable<TInput> | AsyncIterator<TInput> | Iterable<TInput> | Iterator<TInput>, mapper: (datum: TInput) => TOutput | Promise<TOutput>): AsyncIterable<TOutput>;
/**
 * Compress an iterable by filtering out data that is not selected.
 *
 * Selectors indicate which data. True value selects item. False value filters out data.
 *
 * @param data
 * @param selectors
 */
export declare function compress<T>(data: Iterable<T> | Iterator<T>, selectors: Iterable<number | boolean> | Iterator<number | boolean>): Iterable<T>;
/**
 * Compress an async iterable by filtering out data that is not selected.
 *
 * Selectors indicate which data. True value selects item. False value filters out data.
 *
 * Selectors may be also async collection.
 *
 * @param data
 * @param selectors
 */
export declare function compressAsync<T>(data: AsyncIterable<T> | AsyncIterator<T> | Iterable<T> | Iterator<T>, selectors: AsyncIterable<number | boolean> | AsyncIterator<number | boolean> | Iterable<number | boolean> | Iterator<number | boolean>): AsyncIterable<T>;
/**
 * Drop elements from the iterable while the predicate function is true.
 *
 * Once the predicate function returns false once, all remaining elements are returned.
 *
 * @param data
 * @param predicate
 */
export declare function dropWhile<T>(data: Iterable<T> | Iterator<T>, predicate: (item: T) => boolean): Iterable<T>;
/**
 * Drop elements from the async iterable while the predicate function is true.
 *
 * Once the predicate function returns false once, all remaining elements are returned.
 *
 * Predicate may be also async.
 *
 * @param data
 * @param predicate
 */
export declare function dropWhileAsync<T>(data: AsyncIterable<T> | AsyncIterator<T> | Iterable<T> | Iterator<T>, predicate: (item: T) => boolean | Promise<boolean>): AsyncIterable<T>;
/**
 * Return elements from the iterable as long as the predicate is true.
 *
 * If no predicate is provided, the boolean value of the data is used.
 *
 * @param data
 * @param predicate
 */
export declare function takeWhile<T>(data: Iterable<T> | Iterator<T>, predicate: (item: T) => boolean): Iterable<T>;
/**
 * Return elements from the async iterable as long as the predicate is true.
 *
 * Predicate may be also async.
 *
 * If no predicate is provided, the boolean value of the data is used.
 *
 * @param data
 * @param predicate
 */
export declare function takeWhileAsync<T>(data: AsyncIterable<T> | AsyncIterator<T> | Iterable<T> | Iterator<T>, predicate: (item: T) => boolean | Promise<boolean>): AsyncIterable<T>;
/**
 * Repeat an item.
 *
 * @param item
 * @param repetitions
 */
export declare function repeat<T>(item: T, repetitions: number): Iterable<T>;
/**
 * Repeat an item given as promise.
 *
 * @param item
 * @param repetitions
 */
export declare function repeatAsync<T>(item: T | Promise<T>, repetitions: number): AsyncIterable<T>;
/**
 * Returns a new collection formed by applying a given callback mapper function to each element
 * of the given collection, and then flattening the result by one level.
 *
 * The mapper function can return scalar or collections as a result.
 *
 * @param data
 * @param mapper
 */
export declare function flatMap<TInput, TOutput>(data: Iterable<TInput> | Iterator<TInput>, mapper: FlatMapper<TInput, TOutput>): Iterable<TOutput>;
/**
 * Returns a new async collection formed by applying a given callback mapper function to each element
 * of the given async collection, and then flattening the result by one level.
 *
 * The mapper function can return scalar or collections as a result.
 *
 * The mapper function may be also async.
 *
 * @param data
 * @param mapper
 */
export declare function flatMapAsync<TInput, TOutput>(data: AsyncIterable<TInput> | AsyncIterator<TInput> | Iterable<TInput> | Iterator<TInput>, mapper: AsyncFlatMapper<TInput, TOutput>): AsyncIterable<TOutput>;
/**
 * Flatten an iterable by a number of dimensions.
 *
 * Ex: [[1, 2], [3, 4], 5] => [1, 2, 3, 4, 5] // Flattened by one dimension
 *
 * @param data
 * @param dimensions
 */
export declare function flatten(data: Iterable<unknown> | Iterator<unknown>, dimensions?: number): Iterable<unknown>;
/**
 * Flatten an async iterable by a number of dimensions.
 *
 * Ex: [[1, 2], [3, 4], 5] => [1, 2, 3, 4, 5] // Flattened by one dimension
 *
 * @param data
 * @param dimensions
 */
export declare function flattenAsync(data: AsyncIterable<unknown> | AsyncIterator<unknown> | Iterable<unknown> | Iterator<unknown>, dimensions?: number): AsyncIterable<unknown>;
/**
 * Filter out elements from the iterable only returning elements where there predicate function is true.
 *
 * @param data
 * @param predicate
 */
export declare function filter<T>(data: Iterable<T> | Iterator<T>, predicate: (datum: T) => boolean): Iterable<T>;
/**
 * Filter out elements from the async iterable only returning elements where there predicate function is true.
 *
 * Predicate may be also async.
 *
 * @param data
 * @param predicate
 */
export declare function filterAsync<T>(data: AsyncIterable<T> | AsyncIterator<T> | Iterable<T> | Iterator<T>, predicate: (datum: T) => boolean | Promise<boolean>): AsyncIterable<T>;
/**
 * Return overlapped chunks of elements from given collection.
 *
 * Chunk size must be at least 1.
 *
 * Overlap size must be less than chunk size.
 *
 * @param data
 * @param chunkSize
 * @param overlapSize
 * @param includeIncompleteTail
 */
export declare function chunkwiseOverlap<T>(data: Iterable<T> | Iterator<T>, chunkSize: number, overlapSize: number, includeIncompleteTail?: boolean): Iterable<Array<T>>;
/**
 * Return overlapped chunks of elements from given async collection.
 *
 * Chunk size must be at least 1.
 *
 * Overlap size must be less than chunk size.
 *
 * @param data
 * @param chunkSize
 * @param overlapSize
 * @param includeIncompleteTail
 */
export declare function chunkwiseOverlapAsync<T>(data: AsyncIterable<T> | AsyncIterator<T> | Iterable<T> | Iterator<T>, chunkSize: number, overlapSize: number, includeIncompleteTail?: boolean): AsyncIterable<Array<T>>;
/**
 * Return chunks of elements from given collection.
 *
 * Chunk size must be at least 1.
 *
 * @param data
 * @param chunkSize
 */
export declare function chunkwise<T>(data: Iterable<T> | Iterator<T>, chunkSize: number): Iterable<Array<T>>;
/**
 * Return chunks of elements from given async collection.
 *
 * Chunk size must be at least 1.
 *
 * @param data
 * @param chunkSize
 */
export declare function chunkwiseAsync<T>(data: AsyncIterable<T> | AsyncIterator<T> | Iterable<T> | Iterator<T>, chunkSize: number): AsyncIterable<Array<T>>;
/**
 * Return pairs of elements from given collection.
 *
 * Returns empty generator if given collection contains less than 2 elements.
 *
 * @param data
 */
export declare function pairwise<T>(data: Iterable<T> | Iterator<T>): Iterable<Pair<T>>;
/**
 * Return pairs of elements from given async collection.
 *
 * Returns empty generator if given collection contains less than 2 elements.
 *
 * @param data
 */
export declare function pairwiseAsync<T>(data: AsyncIterable<T> | AsyncIterator<T> | Iterable<T> | Iterator<T>): AsyncIterable<Pair<T>>;
/**
 * Limit iteration to a max size limit.
 *
 * @param data
 * @param count ≥ 0, max count of iteration
 */
export declare function limit<T>(data: Iterable<T> | Iterator<T>, count: number): Iterable<T>;
/**
 * Limit iteration of async iterable to a max size limit.
 *
 * @param data
 * @param count ≥ 0, max count of iteration
 */
export declare function limitAsync<T>(data: AsyncIterable<T> | AsyncIterator<T> | Iterable<T> | Iterator<T>, count: number): AsyncIterable<T>;
/**
 * Enumerates items of given collection.
 *
 * Ex: ['a', 'b', 'c'] => [[0, 'a'], [1, 'b'], [2, 'c']]
 *
 * @param data
 */
export declare function enumerate<T>(data: Iterable<T> | Iterator<T>): Iterable<[number, T]>;
/**
 * Enumerates items of given async collection.
 *
 * Ex: ['a', 'b', 'c'] => [[0, 'a'], [1, 'b'], [2, 'c']]
 *
 * @param data
 */
export declare function enumerateAsync<T>(data: AsyncIterable<T> | AsyncIterator<T> | Iterable<T> | Iterator<T>): AsyncIterable<[number, T]>;
/**
 * Extract a slice of the collection.
 *
 * @param data
 * @param start
 * @param count
 * @param step
 *
 * @throws InvalidArgumentError if `start` or `count` are negative or if `step` is not positive.
 */
export declare function slice<T>(data: Iterable<T> | Iterator<T>, start?: number, count?: number, step?: number): Iterable<T>;
/**
 * Extract a slice of the async collection.
 *
 * @param data
 * @param start
 * @param count
 * @param step
 *
 * @throws InvalidArgumentError if `start` or `count` are negative or if `step` is not positive.
 */
export declare function sliceAsync<T>(data: AsyncIterable<T> | AsyncIterator<T> | Iterable<T> | Iterator<T>, start?: number, count?: number, step?: number): AsyncIterable<T>;
/**
 * Iterates keys from the collection of key-value pairs.
 *
 * Ex: [[0, 'a'], [1, 'b'], [2, 'c']] => [0, 1, 2]
 *
 * @param collection
 */
export declare function keys<TKey, TValue>(collection: Iterable<[TKey, TValue]> | Iterator<[TKey, TValue]>): Iterable<TKey>;
/**
 * Iterates keys from the async collection of key-value pairs.
 *
 * Ex: [[0, 'a'], [1, 'b'], [2, 'c']] => [0, 1, 2]
 *
 * @param collection
 */
export declare function keysAsync<TKey, TValue>(collection: AsyncIterable<[TKey, TValue]> | AsyncIterator<[TKey, TValue]> | Iterable<[TKey, TValue]> | Iterator<[TKey, TValue]>): AsyncIterable<TKey>;
/**
 * Skip n elements in the iterable after optional offset.
 *
 * @param data
 * @param count
 * @param offset
 *
 * @throws InvalidArgumentError if `count` or `offset` is less then 0
 */
export declare function skip<T>(data: Iterable<T> | Iterator<T>, count: number, offset?: number): Iterable<T>;
/**
 * Skip n elements in the async iterable after optional offset.
 *
 * @param data
 * @param count
 * @param offset
 *
 * @throws InvalidArgumentError if `count` or `offset` is less then 0
 */
export declare function skipAsync<T>(data: AsyncIterable<T> | AsyncIterator<T> | Iterable<T> | Iterator<T>, count: number, offset?: number): AsyncIterable<T>;
/**
 * Iterates values from the collection of key-value pairs.
 *
 * Ex: [[0, 'a'], [1, 'b'], [2, 'c']] => ['a', 'b', 'c']
 *
 * @param collection
 */
export declare function values<TKey, TValue>(collection: Iterable<[TKey, TValue]> | Iterator<[TKey, TValue]>): Iterable<TValue>;
/**
 * Iterates values from the async collection of key-value pairs.
 *
 * Ex: [[0, 'a'], [1, 'b'], [2, 'c']] => ['a', 'b', 'c']
 *
 * @param collection
 */
export declare function valuesAsync<TKey, TValue>(collection: AsyncIterable<[TKey, TValue]> | AsyncIterator<[TKey, TValue]> | Iterable<[TKey, TValue]> | Iterator<[TKey, TValue]>): AsyncIterable<TValue>;
/**
 * Group data by a common data element.
 *
 * Iterate pairs of group name and collection of grouped items.
 *
 * Collection of grouped items may be an array or an object (depends on presence of `itemKeyFunction` param).
 *
 * @param data
 * @param groupKeyFunction - determines the key (or multiple keys) to group elements by.
 * @param itemKeyFunction - (optional) determines the key of element in group.
 */
export declare function groupBy<T, TItemKeyFunction extends ((item: T) => string) | undefined, TResultItem extends TItemKeyFunction extends undefined ? [string, Array<T>] : [string, Record<string, T>]>(data: Iterable<T> | Iterator<T>, groupKeyFunction: (item: T) => string, itemKeyFunction?: TItemKeyFunction): Iterable<TResultItem>;
/**
 * Group async data by a common data element.
 *
 * Iterate pairs of group name and collection of grouped items.
 *
 * Collection of grouped items may be an array or an object (depends on presence of `itemKeyFunction` param).
 *
 * Functions `groupKeyFunction` and `itemKeyFunction` may be async.
 *
 * @param data
 * @param groupKeyFunction - determines the key (or multiple keys) to group elements by.
 * @param itemKeyFunction - (optional) determines the key of element in group.
 */
export declare function groupByAsync<T, TItemKeyFunction extends ((item: T) => string) | undefined, TResultItem extends TItemKeyFunction extends undefined ? [string, Array<T>] : [string, Record<string, T>]>(data: AsyncIterable<T> | AsyncIterator<T> | Iterable<T> | Iterator<T>, groupKeyFunction: (item: T) => (string | Promise<string>), itemKeyFunction?: (item: T) => (string | Promise<string>)): AsyncIterable<TResultItem>;
/**
 * Sorts the given collection.
 *
 * If comparator is null, the elements of given iterable must be comparable.
 *
 * @param data
 * @param comparator
 */
export declare function sort<T>(data: Iterable<T> | Iterator<T>, comparator?: Comparator<T>): Iterable<T>;
/**
 * Sorts the given collection.
 *
 * If comparator is null, the elements of given iterable must be comparable.
 *
 * @param data
 * @param comparator
 */
export declare function sortAsync<T>(data: AsyncIterable<T> | AsyncIterator<T> | Iterable<T> | Iterator<T>, comparator?: Comparator<T>): AsyncIterable<T>;