{"id":15663690,"url":"https://github.com/blakeembrey/iterative","last_synced_at":"2025-05-05T23:32:07.509Z","repository":{"id":53032944,"uuid":"130567330","full_name":"blakeembrey/iterative","owner":"blakeembrey","description":"Functions for working with iterators in JavaScript and TypeScript","archived":false,"fork":false,"pushed_at":"2023-12-12T06:55:01.000Z","size":612,"stargazers_count":16,"open_issues_count":1,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-17T17:56:51.687Z","etag":null,"topics":["helpers","iterable","iterator","itertools","typescript","utility"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/blakeembrey.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-04-22T12:56:17.000Z","updated_at":"2025-02-11T15:50:29.000Z","dependencies_parsed_at":"2024-06-19T05:25:36.422Z","dependency_job_id":"51dfedb6-3fe7-41b7-9cd1-e060b7b1eb9e","html_url":"https://github.com/blakeembrey/iterative","commit_stats":null,"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blakeembrey%2Fiterative","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blakeembrey%2Fiterative/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blakeembrey%2Fiterative/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blakeembrey%2Fiterative/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/blakeembrey","download_url":"https://codeload.github.com/blakeembrey/iterative/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252592774,"owners_count":21773330,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["helpers","iterable","iterator","itertools","typescript","utility"],"created_at":"2024-10-03T13:39:25.149Z","updated_at":"2025-05-05T23:32:07.493Z","avatar_url":"https://github.com/blakeembrey.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Iterative\n\n[![NPM version][npm-image]][npm-url]\n[![NPM downloads][downloads-image]][downloads-url]\n[![Build status][travis-image]][travis-url]\n[![Test coverage][coveralls-image]][coveralls-url]\n\n\u003e Functions for working with iterators in JavaScript, with TypeScript.\n\n_(Inspired by [itertools](https://docs.python.org/3/library/itertools.html#itertools-recipes))_\n\n## Installation\n\n```\nnpm install iterative --save\n```\n\n## Usage\n\n**🚨 The packages comes in two flavors, `Iterator` and `AsyncIterator`. Use `iterative/dist/async` for async iterators. 🚨**\n\n### `range(start = 0, stop = Infinity, step = 1): Iterable\u003cnumber\u003e`\n\nThis is a versatile function to create lists containing arithmetic progressions.\n\n```ts\nrange(); //=\u003e [0, 1, 2, 3, 4, 5, 6, 7, 8, ...]\nrange(10, 20, 5); //=\u003e [10, 15]\n```\n\n### `cycle\u003cT\u003e(iterable: Iterable\u003cT\u003e): Iterable\u003cT\u003e`\n\nMake an iterator returning elements from the iterable and saving a copy of each. When the iterable is exhausted, return elements from the saved copy. Repeats indefinitely.\n\n```ts\ncycle([1, 2, 3]); //=\u003e [1, 2, 3, 1, 2, 3, 1, 2, ...]\n```\n\n### `repeat\u003cT\u003e(value: T, times?: number): Iterable\u003cT\u003e`\n\nMake an iterator that repeats `value` over and over again.\n\n```ts\nrepeat(true); //=\u003e [true, true, true, true, ...]\n```\n\n### `flatten\u003cT\u003e(iterable: Iterable\u003cIterable\u003cT\u003e\u003e): Iterable\u003cT\u003e`\n\nReturn an iterator flattening one level of nesting in an iterable of iterables.\n\n```ts\nflatten([\n  [1, 2, 3],\n  [4, 5, 6],\n  [7, 8, 9],\n]); //=\u003e [1, 2, 3, 4, 5, 6, 7, 8, 9]\n```\n\n### `chain\u003cT\u003e(...iterables: Array\u003cIterable\u003cT\u003e\u003e): Iterable\u003cT\u003e`\n\nMake an iterator that returns elements from the first iterable until it is exhausted, then proceeds to the next iterable, until all of the iterables are exhausted. Used for treating consecutive sequences as a single sequence.\n\n```ts\nchain([1, 2, 3], [4, 5, 6], [7, 8, 9]); //=\u003e [1, 2, 3, 4, 5, 6, 7, 8, 9]\n```\n\n### `slice\u003cT\u003e(iterable: Iterable\u003cT\u003e, start = 0, stop = Infinity, step = 1): Iterable\u003cT\u003e`\n\nMake an iterator that returns selected elements from the `iterable`.\n\n```ts\nslice([1, 2, 3, 4, 5]); //=\u003e [1, 2, 3, 4, 5]\nslice(range(), 2, 5); //=\u003e [2, 3, 4]\n```\n\n### `map\u003cT, U\u003e(iterable: Iterable\u003cT\u003e, func: (x: T) =\u003e U): Iterable\u003cU\u003e`\n\nApply function to every item of iterable and return an iterable of the results.\n\n```ts\nmap([1, 2, 3], (x) =\u003e x * x); //=\u003e [1, 4, 9]\n```\n\n### `spreadmap\u003cT, U\u003e(iterable: Iterable\u003cT\u003e, func: (...args: T) =\u003e U): Iterable\u003cU\u003e`\n\nMake an iterator that computes the function using arguments obtained from the iterable. Used instead of `map()` when argument parameters are already grouped in tuples from a single iterable (the data has been \"pre-zipped\"). The difference between `map()` and `spreadmap()` parallels the distinction between `function(a, b)` and `function(...c)`.\n\n```ts\nmap(\n  [\n    [1, 2],\n    [3, 4],\n    [5, 6],\n  ],\n  (a, b) =\u003e a + b\n); //=\u003e [3, 7, 11]\n```\n\n### `filter\u003cT, U extends T\u003e(iterable: Iterable\u003cT\u003e, func: Predicate\u003cT, U\u003e = Boolean): Iterable\u003cU\u003e`\n\nConstruct an `iterator` from those elements of `iterable` for which `func` returns true.\n\n```ts\nfilter(range(0, 10), (x) =\u003e x % 2 === 0); //=\u003e [0, 2, 4, 6, 8]\n```\n\n### `reduce\u003cT, U\u003e(iterable: Iterable\u003cT\u003e, reducer: Reducer\u003cT, U\u003e, initializer?: U): U`\n\nApply function of two arguments cumulatively to the items of `iterable`, from left to right, so as to reduce the iterable to a single value.\n\n```ts\nreduce([1, 2, 3], (sum, val) =\u003e sum + val); //=\u003e 6\n```\n\n### `accumulate\u003cT\u003e(iterable: Iterable\u003cT\u003e, func: Reducer\u003cT, T\u003e): Iterable\u003cT\u003e`\n\nMake an iterator that returns accumulated results of binary functions.\n\n```ts\naccumulate([1, 2, 3], (sum, val) =\u003e sum + val); //=\u003e [1, 3, 6]\n```\n\n### `all\u003cT, U extends T\u003e(iterable: Iterable\u003cT\u003e, predicate: Predicate\u003cT, U\u003e = Boolean): boolean`\n\nReturns `true` when all values in iterable are truthy.\n\n```ts\nall([1, 2, 3], (x) =\u003e x % 2 === 0); //=\u003e false\n```\n\n### `any\u003cT, U extends T\u003e(iterable: Iterable\u003cT\u003e, predicate: Predicate\u003cT, U\u003e = Boolean): boolean`\n\nReturns `true` when any value in iterable is truthy.\n\n```ts\nany([1, 2, 3], (x) =\u003e x % 2 === 0); //=\u003e true\n```\n\n### `contains\u003cT\u003e(iterable: Iterable\u003cT\u003e, needle: T): boolean`\n\nReturns `true` when any value in iterable is equal to `needle`.\n\n```ts\ncontains(\"test\", \"t\"); //=\u003e true\n```\n\n### `dropWhile\u003cT\u003e(iterable: Iterable\u003cT\u003e, predicate: Predicate\u003cT\u003e): Iterable\u003cT\u003e`\n\nMake an iterator that drops elements from the iterable as long as the predicate is true; afterwards, returns every element.\n\n```ts\ndropWhile([1, 2, 3, 4, 5], (x) =\u003e x \u003c 3); //=\u003e [3, 4, 5]\n```\n\n### `takeWhile\u003cT\u003e(iterable: Iterable\u003cT\u003e, predicate: Predicate\u003cT\u003e): Iterable\u003cT\u003e`\n\nMake an iterator that returns elements from the iterable as long as the predicate is true.\n\n```ts\ntakeWhile([1, 2, 3, 4, 5], (x) =\u003e x \u003c 3); //=\u003e [1, 2]\n```\n\n### `groupBy\u003cT, U\u003e(iterable: Iterable\u003cT\u003e, func: (x: T) =\u003e U): Iterable\u003c[U, Iterable\u003cT\u003e]\u003e`\n\nMake an iterator that returns consecutive keys and groups from the `iterable`. The `func` is a function computing a key value for each element.\n\n```ts\ngroupBy(range(0, 6), (x) =\u003e Math.floor(x / 2)); //=\u003e [[0, [0, 1]], [1, [2, 3]], [2, [4, 5]]]\n```\n\n### `enumerate\u003cT\u003e(iterable: Iterable\u003cT\u003e, offset = 0): Iterable\u003c[number, T]\u003e`\n\nReturns an iterable of enumeration pairs.\n\n```ts\nenumerate(\"test\"); //=\u003e [[0, 't'], [1, 'e'], [2, 's'], [3, 't']]\n```\n\n### `zip\u003cT\u003e(...iterables: Iterable\u003cT\u003e[]): Iterable\u003cT[]\u003e`\n\nReturns an iterator of tuples, where the `i`-th tuple contains the `i`-th element from each of the argument sequences or iterables. The iterator stops when the shortest input iterable is exhausted.\n\n```ts\nzip([1, 2, 3], [\"a\", \"b\", \"c\"]); //=\u003e [[1, 'a'], [2, 'b'], [3, 'c']]\n```\n\n### `zipLongest\u003cT\u003e(...iterables: Iterable\u003cT\u003e[]): Iterable\u003c(T | undefined)[]\u003e`\n\nMake an iterator that aggregates elements from each of the iterables. If the iterables are of uneven length, missing values are `undefined`. Iteration continues until the longest iterable is exhausted.\n\n```ts\nzipLongest([1, 2], [\"a\", \"b\", \"c\", \"d\"]); //=\u003e [[1, 'a'], [2, 'b'], [undefined, 'c'], [undefined, 'd']]\n```\n\n### `zipWithValue\u003cT, U\u003e(fillValue: U, iterables: Iterable\u003cT\u003e[]): Iterable\u003c(T | U)[]\u003e`\n\nMake an iterator that aggregates elements from each of the iterables. If the iterables are of uneven length, missing values are `fillValue`. Iteration continues until the longest iterable is exhausted.\n\n```ts\nzipWithValue(\"example\", [1, 2], [\"a\", \"b\", \"c\", \"d\"]); //=\u003e [[1, 'a'], [2, 'b'], ['example', 'c'], ['example', 'd']]\n```\n\n### `tee\u003cT\u003e(iterable: Iterable\u003cT\u003e): [Iterable\u003cT\u003e, Iterable\u003cT\u003e]`\n\nReturn two independent iterables from a single iterable.\n\n```ts\ntee([1, 2, 3]); //=\u003e [[1, 2, 3], [1, 2, 3]]\n```\n\n### `chunk\u003cT\u003e(iterable: Iterable\u003cT\u003e, size: number): Iterable\u003cT[]\u003e`\n\nBreak iterable into lists of length `size`.\n\n```ts\nchunk(range(0, 10), 2); //=\u003e [[0, 1], [2, 3], [4, 5], [6, 7], [8, 9]]\n```\n\n### `pairwise\u003cT\u003e(iterable: Iterable\u003cT\u003e): Iterable\u003c[T, T]\u003e`\n\nReturns an iterator of paired items, overlapping, from the original. When the input iterable has a finite number of items `n`, the outputted iterable will have `n - 1` items.\n\n```ts\npairwise(range(0, 5)); //=\u003e [[0, 1], [1, 2], [2, 3], [3, 4]]\n```\n\n### `compress\u003cT\u003e(iterable: Iterable\u003cT\u003e, selectors: Iterable\u003cboolean\u003e): Iterable\u003cT\u003e`\n\nMake an iterator that filters elements from `iterable` returning only those that have a corresponding element in selectors that evaluates to `true`.\n\n```ts\ncompress([1, 2, 3, 4, 5], [true, false, true, false, true]); //=\u003e [1, 3, 5]\n```\n\n### `sorted\u003cT, U\u003e(iterable: Iterable\u003cT\u003e, key: (x: T) =\u003e U, cmp: (x: U, y: U) =\u003e number, reverse?: boolean): T[]`\n\nReturn a sorted array from the items in iterable.\n\n```ts\nsorted(slice(range(), 0, 10), (x) =\u003e x);\n```\n\n### `list\u003cT\u003e(iterable: Iterable\u003cT\u003e): T[]`\n\nCreates an array from an iterable object.\n\n```ts\nlist(range(0, 5)); //=\u003e [0, 1, 2, 3, 4]\n```\n\n### `dict\u003cK, V\u003e(iterable: Iterable\u003c[K, V]\u003e): Record\u003cK, V\u003e`\n\nReturn an object from an iterable, i.e. `Array.from` for objects.\n\n```ts\ndict(zip(range(0, 5), repeat(true))); //=\u003e { 0: true, 1: true, 2: true, 3: true, 4: true }\n```\n\n### `len(iterable: Iterable\u003cany\u003e): number`\n\nReturn the length (the number of items) of an iterable.\n\n```ts\nlen(range(0, 5)); //=\u003e 5\n```\n\n_Note:_ This method iterates over `iterable` to return the length.\n\n### `min\u003cT\u003e(iterable: Iterable\u003cT\u003e, key?: (x: T) =\u003e number): T`\n\nReturn the smallest item in an iterable.\n\n```ts\nmin([1, 2, 3, 4, 5]); //=\u003e 1\n```\n\n### `max\u003cT\u003e(iterable: Iterable\u003cT\u003e, key?: (x: T) =\u003e number): T`\n\nReturn the largest item in an iterable.\n\n```ts\nmax([1, 2, 3, 4, 5]); //=\u003e 5\n```\n\n### `sum(iterable: Iterable\u003cnumber\u003e, start?: number): number`\n\nSums `start` and the items of an `iterable` from left to right and returns the total.\n\n```ts\nsum([1, 2, 3, 4, 5]); //=\u003e 15\n```\n\n### `product\u003cT\u003e(...iterables: Iterable\u003cT\u003e[]): Iterable\u003cT[]\u003e`\n\nCartesian product of input iterables.\n\n```ts\nproduct(\"ABCD\", \"xy\"); //=\u003e Ax Ay Bx By Cx Cy Dx Dy\n```\n\n## Reference\n\n- [Itertools Recipes](https://docs.python.org/3/library/itertools.html#itertools-recipes)\n\n## TypeScript\n\nThis project uses [TypeScript](https://github.com/Microsoft/TypeScript) and publishes definitions on NPM.\n\n## License\n\nApache 2.0\n\n[npm-image]: https://img.shields.io/npm/v/iterative.svg?style=flat\n[npm-url]: https://npmjs.org/package/iterative\n[downloads-image]: https://img.shields.io/npm/dm/iterative.svg?style=flat\n[downloads-url]: https://npmjs.org/package/iterative\n[travis-image]: https://img.shields.io/travis/blakeembrey/iterative.svg?style=flat\n[travis-url]: https://travis-ci.org/blakeembrey/iterative\n[coveralls-image]: https://img.shields.io/coveralls/blakeembrey/iterative.svg?style=flat\n[coveralls-url]: https://coveralls.io/r/blakeembrey/iterative?branch=master\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblakeembrey%2Fiterative","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fblakeembrey%2Fiterative","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblakeembrey%2Fiterative/lists"}