https://github.com/blackglory/iterable-operator
🌳 Utilities for JavaScript Iterable and AsyncIterable
https://github.com/blackglory/iterable-operator
browser esm library nodejs npm-package typescript
Last synced: about 1 year ago
JSON representation
🌳 Utilities for JavaScript Iterable and AsyncIterable
- Host: GitHub
- URL: https://github.com/blackglory/iterable-operator
- Owner: BlackGlory
- License: mit
- Created: 2019-09-19T08:05:33.000Z (almost 7 years ago)
- Default Branch: master
- Last Pushed: 2024-04-20T07:01:03.000Z (about 2 years ago)
- Last Synced: 2025-05-25T09:06:30.475Z (about 1 year ago)
- Topics: browser, esm, library, nodejs, npm-package, typescript
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/iterable-operator
- Size: 3.25 MB
- Stars: 3
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# iterable-operator
Utilities for JavaScript `Iterable` and `AsyncIterable`.
## Install
```sh
npm install --save iterable-operator
# or
yarn add iterable-operator
```
## Usage
```ts
import { map, toArray } from 'iterable-operator'
const iter = [1, 2, 3]
const doubleIter = map(iter, x => x * 2)
const result = toArray(doubleIter)
```
You may need [a pipe function].
[a pipe function]: https://github.com/BlackGlory/extra-utils
## API
### isIterable
```ts
function isIterable(val: unknown): val is Iterable
function isntIterable(val: T): val is Exclude>
```
### isAsyncIterable
```ts
function isAsyncIterable(val: unknown): val is AsyncIterable
function isntAsyncIterable(
val: T
): val is Exclude>
```
### chunk, chunkAsync
```ts
function chunk(
iterable: Iterable
, size: number // size > 0
): IterableIterator
function chunkAsync(
iterable: AsyncIterable
, size: number // size > 0
): AsyncIterableIterator>>
```
```ts
chunk([1, 2, 3], 2) // [[1, 2], [3]]
chunk([1, 2, 3], 3) // [[1, 2, 3]]
chunk([1, 2, 3], 5) // [[1, 2, 3]]
chunk([1, 2, 3], 0) // throw Error
chunk([1, 2, 3], -1) // throw Error
```
The memory usage of this function depends on `size`.
### chunkBy, chunkByAsync
```ts
function chunkBy(
iterable: Iterable
, predicate: (element: T, index: number) => unknown
): IterableIterator
function chunkByAsync(
iterable: Iterable | AsyncIterable
, predicate: (element: Awaited, index: number) => Awaitable
): AsyncIterableIterator>>
```
```ts
chunkBy([1, 2, 3], x => x === 2) // [[1, 2], [3]]
chunkBy([1, 2, 3], x => x === 3) // [[1, 2, 3]]
chunkBy([1, 2, 3], x => x === 5) // [[1, 2, 3]]
```
The memory usage of this function depends on `iterable` and `predicate`.
### concat, concatAsync
```ts
function concat(
iterable: Iterable
, ...otherIterables: Iterable[]
): IterableIterator
function concatAsync(
iterable: Iterable | AsyncIterable
, ...otherIterables: Array> | AsyncIterable>>
): AsyncIterableIterator | Awaited>
```
```ts
concat([1, 2, 3]) // [1, 2, 3]
concat([1, 2, 3], ['a', 'b', 'c']) // [1, 2, 3, 'a', 'b', 'c']
```
### difference, differenceAsync
```ts
function difference(left: Iterable, right: Iterable): IterableIterator
function differenceAsync(
left: Iterable> | AsyncIterable>
, right: Iterable> | AsyncIterable>
): AsyncIterableIterator>
```
```ts
difference([1, 2, 3], [3, 4, 5]) // [1, 2]
```
The memory usage of this function depends on `right`.
### drop, dropAsync
```ts
function drop(
iterable: Iterable
, count: number // count >= 0
): IterableIterator
function dropAsync(
iterable: AsyncIterable
, count: number // count >= 0
): AsyncIterableIterator>
```
```ts
drop([1, 2, 3], 0) // [1, 2, 3]
drop([1, 2, 3], 2) // [3]
drop([1, 2, 3], 3) // []
drop([1, 2, 3], 5) // []
drop([1, 2, 3], -1) // throw Error
```
### dropRight, dropRightAsync
```ts
function dropRight(
iterable: Iterable
, count: number // count >= 0
): IterableIterator
function dropRightAsync(
iterable: AsyncIterable
, count: number // count >= 0
): AsyncIterableIterator>
```
```ts
dropRight([1, 2, 3], 0) // [1, 2, 3]
dropRight([1, 2, 3], 2) // [1]
dropRight([1, 2, 3], 3) // []
dropRight([1, 2, 3], 5) // []
dropRight([1, 2, 3], -1) // throw Error
```
The memory usage of this function depends on `iterable`.
### dropUntil, dropUntilAsync
```ts
function dropUntil(
iterable: Iterable
, predicate: (element: T, index: number) => unknown
): IterableIterator
function dropUntilAsync(
iterable: Iterable | AsyncIterable
, predicate: (element: Awaited, index: number) => Awaitable
): AsyncIterableIterator>
```
```ts
dropUntil([1, 2, 3], x => x === 2) // [2, 3]
```
The memory usage of this function depends on `iterable` and `predicate`.
### filter, filterAsync
```ts
function filter(
iterable: Iterable
, predicate: (element: T, index: number) => unknown
): IterableIterator
function filterAsync = Awaited>(
iterable: Iterable | AsyncIterable
, predicate: (element: Awaited, index: number) => Awaitable
): AsyncIterableIterator
```
```ts
filter([1, 2, 3], x => x % 2 === 1) // [1, 3]
```
### flatten, flattenAsync
```ts
function flatten(iterable: Iterable): IterableIterator
function flattenAsync(iterable: AsyncIterable): AsyncIterableIterator
```
```ts
flatten([]) // []
flatten('123') // ['1', '2', '3']
flatten(['one', ['two'], 0, [1, [2]]]) // ['o', 'n', 'e', 'two', 0, 1, [2]]
```
### flattenDeep, flattenDeepAsync
```ts
function flattenDeep(
iterable: Iterable
, depth: number = Infinity // depth >= 0
): IterableIterator
function flattenDeepAsync(
iterable: AsyncIterable
, depth: number = Infinity // depth >= 0
): AsyncIterableIterator
```
```ts
flattenDeep([]) // []
flattenDeep('123') // ['1', '2', '3']
flattenDeep([], -1) // throw Error
flattenDeep([0, [1]], 0) // [0, [1]]
flattenDeep(['one', ['two', ['three']], 0, [1, [2, [3]]]], 2) // ['o', 'n', 'e', 't', 'w', 'o', 'three', 0, 1, 2, [3]]
```
### flattenBy, flattenByAsync
```ts
function flattenBy(
iterable: Iterable
, predicate: (element: unknown, level: number) => boolean
): IterableIterator
function flattenByAsync(
iterable: Iterable | AsyncIterable
, predicate: (element: unknown, level: number) => Awaitable
): AsyncIterableIterator
```
```ts
flattenBy(['one', ['two'], 0, [1]], x => typeof x !== 'string') // ['one', 'two', 0, 1]
flattenBy([], () => true) // []
flattenBy('123', () => true) // ['1', '2', '3']
```
### intersection, intersectionAsync
```ts
function intersection(left: Iterable, right: Iterable): IterableIterator
function intersectionAsync(
left: Iterable> | AsyncIterable
, right: Iterable> | AsyncIterable
): AsyncIterableIterator>
```
The memory usage of this function depends on `right`.
```ts
intersection([1, 2], [2, 3]) // [2]
```
### map, mapAsync
```ts
function map(
iterable: Iterable
, fn: (element: T, index: number) => U
): IterableIterator
function mapAsync(
iterable: Iterable | AsyncIterable
, fn: (element: Awaited, index: number) => Awaitable
): AsyncIterableIterator>
```
```ts
map([1, 2, 3], x => x * 2) // [2, 4, 6]
```
### flatMap, flatMapAsync
```ts
function flatMap(
iterable: Iterable
, fn: (element: T, index: number) => Iterable
): IterableIterator
function flatMapAsync(
iterable: Iterable | AsyncIterable
, fn: (element: Awaited, index: number) => Awaitable | AsyncIterable>
): AsyncIterableIterator>
```
```ts
map([1, 2, 3], x => [x, x * 2]) // [1, 2, 2, 4, 3, 6]
```
### repeat, repeatAsync
```ts
function repeat(
iterable: Iterable
, times: number // times >= 0
): IterableIterator
function repeatAsync(
iterable: AsyncIterable
, times: number // times >= 0
): AsyncIterableIterator>
```
```ts
repeat([1, 2, 3], 2) // [1, 2, 3, 1, 2, 3]
repeat([1, 2, 3], 0) // []
repeat([1, 2, 3], -1) // throw Error
```
The memory usage of this function depends on `iterable`.
### slice, sliceAsync
```ts
function slice(
iterable: Iterable
, start: number // start >= 0
, end: number = Infinity // end >= start
): IterableIterator
function sliceAsync(
iterable: AsyncIterable
, start: number // start >= 0
, end: number = Infinity // end >= start
): AsyncIterableIterator>
```
```ts
slice([1, 2, 3], -1, 1) // throw Error
slice([1, 2, 3], 3, 5) // []
slice([1, 2, 3], 1, 2) // [2]
slice([1, 2, 3], 1, 1) // []
slice([1, 2, 3], 2, 1) // throw Error
```
### join, joinAsync
```ts
function join(iterable: Iterable, separator: U): IterableIterator
function joinAsync(
iterable: AsyncIterable
, separator: U
): AsyncIterableIterator | U>
```
```ts
join([1, 2, 3], '+') // [1, '+', 2, '+', 3]
```
### split, splitAsync
```ts
function split(iterable: Iterable, separator: T): IterableIterator
function splitAsync(
iterable: AsyncIterable
, separator: T
): AsyncIterableIterator>>
```
```ts
split([1, 2, 3, 4, 5], 3) // [[1, 2], [4, 5]]
split([1, 2, 3, 4, 5], 1) // [[], [2, 3, 4, 5]]
split([1, 2, 3, 4, 5], 5) // [[1, 2, 3, 4], []]
split([1, 2, 3, 4, 5], 0) // [[1, 2, 3, 4, 5]]
```
The memory usage of this function depends on `iterable` and `separator`.
### splitBy, splitByAsync
```ts
function splitBy(
iterable: Iterable
, predicate: (element: T, index: number) => unknown
): IterableIterator
function splitByAsync(
iterable: Iterable | AsyncIterable
, predicate: (element: Awaited, index: number) => Awaitable
): AsyncIterableIterator>>
```
```ts
splitBy([1, 2, 3, 4, 5], x => x === 3) // [[1, 2], [4, 5]]
splitBy([1, 2, 3, 4, 5], x => x === 1) // [[], [2, 3, 4, 5]]
splitBy([1, 2, 3, 4, 5], x => x === 5) // [[1, 2, 3, 4], []]
splitBy([1, 2, 3, 4, 5], x => x === 0) // [[1, 2, 3, 4, 5]]
```
The memory usage of this function depends on `iterable` and `predicate`.
### take, takeAsync
```ts
function take(iterable: Iterable, count: number): IterableIterator
function takeAsync(
iterable: AsyncIterable
, count: number
): AsyncIterableIterator>
```
```ts
take([1, 2, 3], 5) // [1, 2, 3]
take([1, 2, 3], 2) // [1, 2]
take([1, 2, 3], 0) // []
take([1, 2, 3], -1) // throw Error
```
### takeRight, takeRightAsync
```ts
function takeRight(iterable: Iterable, count: number): IterableIterator
function takeRightAsync(
iterable: AsyncIterable
, count: number
): AsyncIterableIterator>
```
```ts
takeRight([1, 2, 3], 2) // [2, 3]
takeRight([1, 2, 3], 5) // [1, 2, 3]
takeRight([1, 2, 3], 0) // []
takeRight([1, 2, 3], -1) // throw Error
```
The memory usage of this function depends on `count`.
### takeUntil, takeUntilAsync
```ts
function takeUntil(
iterable: Iterable
, predicate: (element: T, index: number) => unknown
): IterableIterator
function takeUntilAsync(
iterable: Iterable | AsyncIterable
, predicate: (element: Awaited, index: number) => Awaitable
): AsyncIterableIterator>
```
```ts
takeUntil([1, 2, 3], x => x === 2) // [1]
```
### tap, tapAsync
```ts
function tap(
iterable: Iterable
, fn: (element: T, index: number) => unknown
): IterableIterator
function tapAsync(
iterable: Iterable | AsyncIterable
, fn: (element: Awaited, index: number) => Awaitable
): AsyncIterableIterator>
```
```ts
tap([1, 2, 3], x => console.log(x)) // [1, 2, 3]
```
### toAsyncIterable
```ts
function toAsyncIterable(
iterable: Iterable>
): AsyncIterableIterator>
```
```ts
toAsyncIterable([1, 2, 3]) // AsyncIterable [1, 2, 3]
```
### transform, transformAsync
```ts
function transform(
iterable: Iterable
, transformer: (iterable: Iterable) => Iterable
): IterableIterator
function transformAsync(
iterable: Iterable
, transformer: (iterable: Iterable) => AsyncIterable
): AsyncIterableIterator>
function transformAsync(
iterable: AsyncIterable
, transformer: (iterable: AsyncIterable) => AsyncIterable
): AsyncIterableIterator>
```
```ts
transform([1, 2, 3], function* double(iter) {
for (const element of iter) {
yield element * 2
}
}) // [2, 4, 6]
```
### uniq, uniqAsync
```ts
function uniq(iterable: Iterable): IterableIterator
function uniqAsync(iterable: AsyncIterable): AsyncIterableIterator>
```
```ts
uniq([1, 1, 2, 2, 3, 3]) // [1, 2, 3]
```
The memory usage of this function depends on `iterable`.
### uniqBy, uniqByAsync
```ts
function uniqBy(
iterable: Iterable
, fn: (element: T, index: number) => U
): IterableIterator
function uniqByAsync(
iterable: Iterable | AsyncIterable
, fn: (element: Awaited, index: number) => Awaitable
): AsyncIterableIterator>
```
```ts
uniqBy([1, 2, 3], x => x % 2) // [1, 2]
```
The memory usage of this function depends on `fn`.
### zip, zipAsync
```ts
function zip>>(
iterable: Iterable
, ...otherIterables: U
): IterableIterator<[T, ...ExtractTypeTupleFromIterableTuple]>
function zipAsync<
T
, U extends Array> | AsyncIterable>>
>(
iterable: Iterable> | AsyncIterable>
, ...otherIterables: U
): AsyncIterableIterator<
[Awaited, ...ExtractTypeTupleFromAsyncLikeIterableTuple]
>
```
```ts
zip([1, 2, 3], ['a', 'b', 'c']) // [[1, 'a'], [2, 'b'], [3, 'c']]
zip([1, 2, 3], ['a', 'b']) // [[1, 'a'], [2, 'b']
zip([1, 2, 3], ['a', 'b'], ['i', 'ii', 'iii']) // [[1, 'a', 'i'], [2, 'b', 'ii']]
```
### consume, consumerAsync
```ts
function consume(iterable: Iterable, consumer: (iterable: Iterable) => U): U
function consumeAsync(
iterable: Iterable
, consumer: (iterable: Iterable) => Awaitable
): Promise>
function consumeAsync(
iterable: AsyncIterable
, consumer: (iterable: AsyncIterable) => Awaitable
): Promise>
```
```ts
consume([1, 2, 3], xs => new Set(xs)) // Set [1, 2, 3]
```
### each, eachAsync
```ts
function each(
iterable: Iterable
, fn: (element: T, index: number) => unknown
): void
function eachAsync(
iterable: Iterable | AsyncIterable
, fn: (element: Awaited, index: number) => Awaitable
): Promise
```
```ts
each([1, 2, 3], x => console.log(x)) // void
```
### every, everyAsync
```ts
function every(
iterable: Iterable
, predicate: (element: T, index: number) => unknown
): boolean
function everyAsync(
iterable: Iterable | AsyncIterable