iterates
Version:
Iterator and AsyncIterator helper functions with typings
403 lines • 13.7 kB
TypeScript
/**
* Either an Iterable (for example an Array) or an Iterator
* (for example the result of a generator function)
*/
export declare type IterableOrIterator<T> = Iterable<T> | Iterator<T>;
export declare type Ordering = number;
/** @internal */
export declare const isIterator: (iterator: any) => iterator is Iterator<unknown, any, undefined>;
/**
* @internal
*/
export declare const asIterable: <T>(iterator: IterableOrIterator<T>) => Iterable<T>;
/**
* Collect all values of the iterator in an Array.
*/
export declare function asArray<T>(iterator: IterableOrIterator<T>): Array<T>;
/**
* Creates an iterator with values from `start` to `end`.
*
* If end is undefined, the iterator will have an infinite length.
* If end is equal to start, no value will be emitted.
*
* The iterator will step with the specified `step` size which defaults to `1`.
* The step size can be set to negative if the start value is higher than the end value
*
* The iterator will end with a return value of the value following the end value.
*
* ## Examples
* ```typescript
* [...range({start: 0, end: 3})] // [0, 1, 2]
* [...range({start: 3, end: 2, step: -1})] // [2, 1, 0]
* [...range({start: 0})] // (0, 1, 2, 3, 4, ...)
* [...range({start: 0, step: -2})] // (0, -2, -4, -6, -8, ...)
* ```
*/
export declare function range({ start, end, step, }: {
start: number;
end?: number;
step?: number;
}): Generator<number, number, unknown>;
/**
* Creates an iterator which gives the current iteration count
* as well as the next value.
*
* The iterator returned yields objects of {index, item}, where index is the
* current index of iteration and item is the value returned by the iterator.
*
* ## Example
* ```typescript
* [...enumerate(['a', 'b', 'c'])]
* // [{index: 0, item: 'a'}, {index: 1, item: 'b'}, {index: 2, item: 'c'}]
* ```
*/
export declare function enumerate<T>(iterator: IterableOrIterator<T>): IterableIterator<{
index: number;
item: T;
}>;
/**
* Calls fn for every item in the iterator to produce an iterator
* with the results of fn(item)
*
* ## Example
* ```typescript
* [...map(e => e*e), [1, 2, 3]] // [1, 4, 9]
* ```
*/
export declare const map: {
<T, U>(fn: (item: T) => U, iterator: IterableOrIterator<T>): IterableIterator<U>;
<T, U>(fn: (item: T) => U): (iterator: IterableOrIterator<T>) => IterableIterator<U>;
};
/**
* Like map but filter out undefined results
*
* ## Example
* ```typescript
* [...flatMap(e => e % 2 === 0 ? undefined : e*e), [1, 2, 3]] // [1, 9]
* ```
*
* ## Why not map(filter())?
* filterMap is functionally equivalent to map(filter()) but can give
* cleaner code and higher performance for cases where filtering is applied
* to the mapped value and not the input value.
*/
export declare const filterMap: {
<T, U>(fn: (item: T) => U | undefined, iterator: IterableOrIterator<T>): IterableIterator<U>;
<T, U>(fn: (item: T) => U | undefined): (iterator: IterableOrIterator<T>) => IterableIterator<U>;
};
/**
* Like map but flattens the result a single level
*
* ## Example
* ```typescript
* [...flatMap(e => [e, e*e]), [1, 2, 3]] // [1, 1, 2, 4, 3, 9]
* ```
*/
export declare const flatMap: {
<T, U>(fn: (item: T) => IterableOrIterator<U>, iterator: IterableOrIterator<T>): IterableIterator<U>;
<T, U>(fn: (item: T) => IterableOrIterator<U>): (iterator: IterableOrIterator<T>) => IterableIterator<U>;
};
/**
* Flattens an iterator a single level
*
* ## Example
* ```typescript
* [...flatten([[1, 2], [], [3]])] // [1, 2, 3]
* ```
*/
export declare function flatten<T>(iterator: IterableOrIterator<IterableOrIterator<T>>): IterableIterator<T>;
/**
* Calls predicate for every item in the iterator to produce an iterator
* with only the items for which predicate returns true
*
* ## Example
* ```typescript
* [...filter(e => e > 2, [1, 2, 3])] // [2, 3]
* ```
*/
export declare const filter: {
<T>(predicate: (item: T) => boolean, iterator: IterableOrIterator<T>): IterableIterator<T>;
<T>(predicate: (item: T) => boolean): (iterator: IterableOrIterator<T>) => IterableIterator<T>;
};
/**
* Reduces an iterator to a single value by iteratively combining each
* item of the iterator with an existing value
*
* Uses initialValue as the initial value, then iterates through the elements
* and updates the value with each element using the combine function.
*
* If the iterator is empty, the initialValue is returned.
*
* ## Example
* ```typescript
* fold(0, (sum, item) => sum + item, [1, 2, 3]) // 6
* ```
*/
export declare const fold: {
<T, U>(initialValue: U, combine: (previousItem: U, item: T) => U, iterator: IterableOrIterator<T>): U;
<T, U>(initialValue: U, combine: (previousItem: U, item: T) => U): (iterator: IterableOrIterator<T>) => U;
};
/**
* Like fold, scan iteratively combines each item of the iterator with
* an existing value. Scan does however yield each intermediate value.
*
* If the iterator is empty, no value is yielded.
*
* ## Example
* ```typescript
* scan(0, (sum, item) => sum + item, [1, 2, 3]) // [1, 3, 6]
* ```
*/
export declare const scan: {
<T, U>(initialValue: U, combine: (previousItem: U, item: T) => U, iterator: IterableOrIterator<T>): IterableIterator<U>;
<T, U>(initialValue: U, combine: (previousItem: U, item: T) => U): (iterator: IterableOrIterator<T>) => IterableIterator<U>;
};
/**
* Transforms an iterator into a Map.
*
* Calls `fn` for every item in the iterator. `fn` should return a tuple of `[key, value]`
* for that item.
*
* If multiple items returns the same key the latter will overwrite the former.
* This behavior can be changed by passing `merge` in the options object.
*
* `merge` takes the current value, the new value and the key and should return a combined
* value. It can also throw to dissallow multiple items returning the same key.
*
* ## Example
* ```typescript
* collect(e => [e, e*e], [1, 2, 3]) // Map {1 => 1, 2 => 4, 3 => 9}
* ```
*
* ### Using merge
* ```typescript
* collect(
* e => [e % 2 === 0 ? 'even' : 'odd', [e]],
* [1, 2, 3],
* {merge: (a, b) => a.concat(b)}
* )
* // Map {'odd' => [1, 3], 'even' => [2]}
* ```
*/
export declare const collect: {
<T, U, K = string>(fn: (item: T) => [K, U], iterator: IterableOrIterator<T>, options?: {
merge?: (currentValue: U, newValue: U, key: K) => U;
}): Map<K, U>;
<T, U, K = string>(fn: (item: T) => [K, U], options: {
merge?: (currentValue: U, newValue: U, key: K) => U;
}): (iterator: IterableOrIterator<T>) => Map<K, U>;
<T, U, K = string>(fn: (item: T) => [K, U]): (iterator: IterableOrIterator<T>, options?: {
merge?: (currentValue: U, newValue: U, key: K) => U;
}) => Map<K, U>;
};
/**
* Transforms an iterator into an Object.
*
* Calls `fn` for every item in the iterator. `fn` should return a tuple of `[key, value]`
* for that item.
*
* If multiple items returns the same key the latter will overwrite the former.
* This behavior can be changed by passing `merge` in the options object.
*
* `merge` takes the current value, the new value and the key and should return a combined
* value. It can also throw to dissallow multiple items returning the same key.
*
* ## Example
* ```typescript
* collectRecord(e => [e, e*e], [1, 2, 3]) // {1: 1, 2: 4, 3: 9}
* ```
*
* ### Using merge
* ```typescript
* collect(
* e => [e % 2 === 0 ? 'even' : 'odd', [e]],
* [1, 2, 3],
* {merge: (a, b) => a.concat(b)}
* )
* // {odd: [1, 3], even: [2]}
* ```
*/
export declare const collectRecord: {
<T, U, K extends string>(fn: (item: T) => [K, U], iterator: IterableOrIterator<T>, options?: {
merge?: (currentValue: U, newValue: U, key: K) => U;
}): Record<K, U>;
<T, U, K extends string>(fn: (item: T) => [K, U], options: {
merge?: (currentValue: U, newValue: U, key: K) => U;
}): (iterator: IterableOrIterator<T>) => Record<K, U>;
<T, U, K extends string>(fn: (item: T) => [K, U]): (iterator: IterableOrIterator<T>, options?: {
merge?: (currentValue: U, newValue: U, key: K) => U;
}) => Record<K, U>;
};
/**
* Zips two iterators by taking the next value of each iterator as a tuple
*
* If the two iterators have a different length, it will zip until the first iterator ends
* and then end with a return value of the longer iterator.
*
* ## Example
* ```typescript
* [...zip([1, 2, 3], ['a', 'b', 'c']) // [[1, 'a'], [2, 'b'], [3, 'c']]
* ```
*/
export declare const zip: {
<A, B>(a: IterableOrIterator<A>, b: IterableOrIterator<B>): IterableIterator<[
A,
B
]>;
<A, B>(a: IterableOrIterator<A>): (b: IterableOrIterator<B>) => IterableIterator<[A, B]>;
};
/**
* Returns true if predicate returns true for every item in the iterator
*
* Returns true if the iterator is empty
*
* ## Example
* ```typescript
* all(e => e > 1, [1, 2, 3]) // false
* all(e => e > 0, [1, 2, 3]) // true
* all(e => e > 1, []) // true
* ```
*/
export declare const all: {
<T>(predicate: (item: T) => boolean, iterator: IterableOrIterator<T>): boolean;
<T>(predicate: (item: T) => boolean): (iterator: IterableOrIterator<T>) => boolean;
};
/**
* Returns true if predicate returns true for any item in the iterator
*
* Returns false if the iterator is empty
*
* ## Example
* ```typescript
* any(e => e > 1, [1, 2, 3]) // true
* any(e => e > 3, [1, 2, 3]) // false
* any(e => e > 1, []) // false
* ```
*/
export declare const any: {
<T>(predicate: (item: T) => boolean, iterator: IterableOrIterator<T>): boolean;
<T>(predicate: (item: T) => boolean): (iterator: IterableOrIterator<T>) => boolean;
};
/**
* Calls fn for every item and returns the first item for which fn returns true
*
* Returns undefined if fn return fals for all items or if the iterator is empty
*
* ## Example
* ```typescript
* find(e => e > 1, [1, 2, 3]) // 2
* ```
*/
export declare const find: {
<T>(fn: (item: T) => boolean, iterator: IterableOrIterator<T>): T | undefined;
<T>(fn: (item: T) => boolean): (iterator: IterableOrIterator<T>) => T | undefined;
};
/**
* Consumes an iterator, creating two Arrays from it
*
* The predicate passed to partition() can return true, or false.
* partition() returns a pair, all of the elements for which it returned
* true, and all of the elements for which it returned false.
*
* ## Example
* ```typescript
* const [even, odd] = partition(e => e % 2 === 0, [1, 2, 3])
*
* expect(even).toEqual([2])
* expect(odd).toEqual([1, 3])
* ```
*/
export declare const partition: {
<T>(fn: (item: T) => boolean, iterator: IterableOrIterator<T>): [
Array<T>,
Array<T>
];
<T>(fn: (item: T) => boolean): (iterator: IterableOrIterator<T>) => [Array<T>, Array<T>];
};
/**
* Returns the first value of the iterator or undefined if it's empty
*
* ## Example
* ```typescript
* first([1, 2, 3]) // 1
* ```
*/
export declare function first<T>(iterator: IterableOrIterator<T>): T | undefined;
/**
* Returns an iterator that provides all but the first count items.
*
* If the iterator has fewer than count items, then the resulting iterator is empty.
*
* The count must not be negative.
*
* ## Example
* ```typescript
* skip(2, [1, 2, 3]) // [3]
* ```
*/
export declare const skip: {
<T>(count: number, iterator: IterableOrIterator<T>): IterableIterator<T>;
<T>(count: number): (iterator: IterableOrIterator<T>) => IterableIterator<T>;
};
/**
* Returns an iterator that skips leading items while test is satisfied.
*
* The returned iterator yields items from the passed iterator,
* but skipping over all initial items where `test(item)` returns `true`.
* If all items satisfy test the resulting iterator is empty, otherwise
* it iterates the remaining items in their original order, starting with
* the first item for which `test(item)` returns `false`.
*
* ## Example
* ```typescript
* skipWhile(item => item < 3, [1, 2, 3]) // [3]
* ```
*/
export declare const skipWhile: {
<T>(test: (item: T) => boolean, iterator: IterableOrIterator<T>): IterableIterator<T>;
<T>(test: (item: T) => boolean): (iterator: IterableOrIterator<T>) => IterableIterator<T>;
};
/**
* Returns an iterator with the first count values of the iterator
*
* The returned iterator may hold fewer than `count` values if the
* iterator contains less items than `count`
*
* ## Example
* ```typescript
* take(2, [1, 2, 3]) // [1, 2]
* ```
*/
export declare const take: {
<T>(count: number, iterator: IterableOrIterator<T>): IterableIterator<T>;
<T>(count: number): (iterator: IterableOrIterator<T>) => IterableIterator<T>;
};
/**
* Returns an iterator of the leading items satisfying test.
*
* The returned iterator will yield items from the passed iterator until
* test returns `false`. At that point, the returned iterator stops.
*
* ## Example
* ```typescript
* takeWhile(item => item < 3, [1, 2, 3]) // [1, 2]
* ```
*/
export declare const takeWhile: {
<T>(test: (item: T) => boolean, iterator: IterableOrIterator<T>): IterableIterator<T>;
<T>(test: (item: T) => boolean): (iterator: IterableOrIterator<T>) => IterableIterator<T>;
};
/**
* Returns the last value of the iterator or undefined if it's empty
*
* ## Example
* ```typescript
* last([1, 2, 3]) // 3
* ```
*/
export declare function last<T>(iterator: IterableOrIterator<T>): T | undefined;
export declare const sort: {
<T>(fn: (a: T, b: T) => Ordering, iterator: IterableOrIterator<T>): Array<T>;
<T>(fn: (a: T, b: T) => Ordering): (iterator: IterableOrIterator<T>) => Array<T>;
};
//# sourceMappingURL=sync.d.ts.map