{"id":15414951,"url":"https://github.com/lxsmnsyc/iterable-js","last_synced_at":"2026-02-12T11:01:54.697Z","repository":{"id":34448867,"uuid":"177481829","full_name":"lxsmnsyc/iterable-js","owner":"lxsmnsyc","description":"An extensions for objects with Iterator Protocol for JS","archived":false,"fork":false,"pushed_at":"2023-01-03T18:27:00.000Z","size":719,"stargazers_count":0,"open_issues_count":7,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-08-22T11:51:46.745Z","etag":null,"topics":["iterable","iterables","iteration","iterator","iterator-pattern"],"latest_commit_sha":null,"homepage":"https://lxsmnsyc.github.io/iterable-js","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lxsmnsyc.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":null,"support":null}},"created_at":"2019-03-24T23:27:08.000Z","updated_at":"2021-06-05T13:49:16.000Z","dependencies_parsed_at":"2023-01-15T07:09:03.226Z","dependency_job_id":null,"html_url":"https://github.com/lxsmnsyc/iterable-js","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/lxsmnsyc/iterable-js","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lxsmnsyc%2Fiterable-js","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lxsmnsyc%2Fiterable-js/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lxsmnsyc%2Fiterable-js/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lxsmnsyc%2Fiterable-js/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lxsmnsyc","download_url":"https://codeload.github.com/lxsmnsyc/iterable-js/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lxsmnsyc%2Fiterable-js/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29363627,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-12T08:51:36.827Z","status":"ssl_error","status_checked_at":"2026-02-12T08:51:26.849Z","response_time":55,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["iterable","iterables","iteration","iterator","iterator-pattern"],"created_at":"2024-10-01T17:05:21.231Z","updated_at":"2026-02-12T11:01:54.680Z","avatar_url":"https://github.com/lxsmnsyc.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# iterable-js\n\nAn extensions for objects with Iteration Protocol for JS\n\n[![](https://data.jsdelivr.com/v1/package/npm/@lxsmnsyc/iterable-js/badge)](https://www.jsdelivr.com/package/npm/@lxsmnsyc/iterable-js)\n\n| Platform | Build Status |\n| --- | --- |\n| Linux | [![Build Status](https://travis-ci.org/LXSMNSYC/iterable-js.svg?branch=master)](https://travis-ci.org/LXSMNSYC/iterable-js) |\n| Windows | [![Build status](https://ci.appveyor.com/api/projects/status/272hv6jnglgamb0g?svg=true)](https://ci.appveyor.com/project/LXSMNSYC/iterable-js) |\n\n[![codecov](https://codecov.io/gh/LXSMNSYC/iterable-js/branch/master/graph/badge.svg)](https://codecov.io/gh/LXSMNSYC/iterable-js)\n\n\n### Introduction\n\n### Iterations Protocol\n\nES2015 introduces a new feature, namely the [Iterations Protocol](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols). The protocol consists of 2 protocols:\n\n* The iterable protocol allows JavaScript objects to define or customize their iteration behavior, such as what values are looped over in a for..of construct. Some built-in types are built-in iterables with a default iteration behavior, such as Array or Map, while other types (such as Object) are not.\n  \n  In order to be iterable, an object must implement the @@iterator method, meaning that the object (or one of the objects up its prototype chain) must have a property with a @@iterator key which is available via constant Symbol.iterator:\n\n  * ```[Symbol.iterator]``` \n    * A zero arguments function that returns an object, conforming to the iterator protocol.\n\n  Whenever an object needs to be iterated (such as at the beginning of a for..of loop), its @@iterator method is called with no arguments, and the returned iterator is used to obtain the values to be iterated.\n\n* The iterator protocol defines a standard way to produce a sequence of values (either finite or infinite), and potentially a return value when all values have been generated.\n  \n  An object is an iterator when it implements a next() method with the following semantics:\n\n  * next\n    * A zero arguments function that returns an object with at least the following two properties: \n      * ```done``` (boolean)\n        * Has the value ```true``` if the iterator is past the end of the iterated sequence. In this case ```value``` optionally specifies the return value of the iterator.\n        * Has the value ```false``` if the iterator was able to produce the next value in the sequence. This is equivalent of not specifying the done property altogether.\n      * ```value``` \n        * any JavaScript value returned by the iterator.\n        * Can be omitted when ```done``` is ```true```.\n    * The next method always has to return an object with appropriate properties including ```done``` and ```value```.\n    * If a non-object value gets returned (such as ```false``` or ```undefined```), a TypeError (\"iterator.next() returned a non-object value\") will be thrown.\n\n### Iterable and Iteration Protocol\n\nIterable intends to unify all iterable objects, be it a built-in iterable (e.g. Array, String, Map) or a user-made iterable (e.g. user-defined generators, objects with Symbol.iterator property), acting as the de-facto superset.\n\nBy taking advantage of the Iteration Protocol, Iterable can provide operators that allows to transform any iterable objects.\n\nIterable operators are not strict to Iterable instance, they expect the first parameters to be an iterable object, regardless of the implementation. For example,\n\n```js\nIterable.concat('Hello', [1, 2, 3, 4, 5]);\n```\n\ncreates an iterable that yields the characters of 'Hello' and the values of ```[1, 2, 3, 4, 5]``` sequentially.\n\n### Iterable vs IxJS\n\nFirst, I would like to point out that at the time I have written almost half of the library, I stumbled upon the library [IxJS](https://github.com/ReactiveX/IxJS) while looking for Rx libraries, and to my surprise, it has the same goal as my library's.\n\nSo, what are the differences?\n\nIterable doesn't/isn't:\n\n* support async.\n* expose the operators as an individual module.\n* written in TypeScript.\n* have operators that returns a single value from an aggregation (e.g reduce), instead, they are considered as a singular Iterable (an Iterable with one element).\n* handle errors.\n\nIterable does/is:\n\n* support chaining operators for an Iterable as well as provide these operators as a static member, allowing class deconstruction.\n* allow bracket notation for accessing the nth-yield of the Iterable.\n* throw runtime errors. If an error occurs, the errors are thrown synchronously on iteration.\n* know if an object is iterable by concept or not, allowing non-Iterable instances to have access with the Iterable operators.\n\nMethod Counterparts\n\n| Iterable | IxJS | Notes |\n| --- | --- | --- |\n| ```all``` | ```every``` | Returns a singular Iterable that yields the boolean result. |\n| ```any``` | ```some``` | Returns a singular Iterable that yields the boolean result.  |\n| ```average``` | ```average``` | Returns a singular Iterable that yields the number result. |\n| ```breadthFirst``` | | |\n| ```breakWith``` | | |\n| ```buffer``` | ```buffer``` | Doesn't have the skip mechanism. |\n| ```cache``` | | |\n| ```compose``` | ```pipe``` | |\n| ```concat``` | ```concat```, ```of```, ```endWith``` | Unlike the IxJS ```concat```, Iterable ```concat``` allows to concat non-Iterable values. |\n| ```contains``` | ```includes``` | Doesn't have the skip mechanism. Returns a singular Iterable that yields the boolean result. |\n| ```count``` | ```count``` | Returns a singular Iterable that yields the number result. |\n| ```defaultIfEmpty``` | ```defaultIfEmpty``` | |\n| ```depthFirst``` | | |\n| ```diff``` | | |\n| ```distinct``` | ```distinct``` | Doesn't have the compare mechanism. Strict equality is used. |\n| ```distinctAdjacent``` | ```distinctUntilChanged``` | Doesn't have the compare mechanism. Strict equality is used. |\n| ```doWhile``` | ```doWhile``` | |\n| ```elementAt``` | ```elementAt``` | Returns a singular Iterable that yields the result. |\n| ```empty``` | ```empty``` | |\n| ```equal``` | ```sequenceEqual``` | Returns a singular Iterable that yields the boolean result. |\n| ```filter``` | ```filter``` | |\n| ```find``` | ```find``` | Instead of yielding the passing value, ```find`` yields the index. Returns a singular Iterable that yields the number result. |\n| ```first``` | ```first``` | Returns a singular Iterable that yields the result. |\n| ```flat``` | ```flatten``` | Iterable ```flat``` only flattens a single layer. To flatten all layers, use ```depthFirst``` |\n| ```flatMap``` | ```flatMap``` | |\n| ```ignoreElements``` | ```ignoreElements``` | |\n| ```indexOf``` | | |\n| ```innerJoin``` | ```innerJoin``` | |\n| ```intercalate``` | | |\n| ```intersect``` | ```intersect``` | |\n| ```intersperse``` | | |\n| ```isEmpty``` | ```isEmpty``` | Returns a singular Iterable that yields the boolean result. |\n| ```just``` | | |\n| ```last``` | ```last``` | |\n| ```leftJoin``` | | |\n| ```map``` | ```map``` | |\n| ```max``` | ```max``` | Returns a singular Iterable that yields the result. |\n| ```min``` | ```min``` | Returns a singular Iterable that yields the result. |\n| ```onDone``` | | |\n| ```onStart``` | | |\n| ```onYield``` | | |\n| ```outerJoin``` | | |\n| ```partition``` | ```partition``` | |\n| ```range``` | ```range``` | Unlike IxJS, Iterable ```range``` allows negative slope, and custom step size. |\n| ```reduce``` | ```reduce``` | Returns a singular Iterable that yields the result. |\n| ```reduceRight``` | ```reduceRight``` | Returns a singular Iterable that yields the result. |\n| ```repeat``` | ```repeat``` | |\n| ```replace``` | | |\n| ```reverse```  |```reverse``` | |\n| ```scan``` | ```scan``` | |\n| ```scanRight``` | ```scanRight``` | |\n| ```skip``` | ```skip``` | |\n| ```skipLast``` | ```skipLast``` | |\n| ```skipUntil``` | | |\n| ```skipWhile``` | ```skipWhile``` | |\n| ```sort``` | ```orderBy``` | |\n| ```sorted``` | | Returns a singular Iterable that yields the boolean result. |\n| ```spanWith``` | | |\n| ```split``` | | |\n| ```startWith``` | ```startWith``` | |\n| ```step``` | | |\n| ```sum``` | ```sum``` | Returns a singular Iterable that yields the result. |\n| ```take``` | ```take``` | |\n| ```takeLast``` | ```takeLast``` | |\n| ```takeUntil``` | | |\n| ```takeWhile``` | ```takeWhile``` | |\n| ```toArray``` | ```toArray``` | |\n| ```whileDo``` | ```while``` | |\n| ```zip``` | ```zip``` | |\n| | ```case``` | |\n| | ```catch``` | Iterable throws the error synchronously. |\n| | ```catchWith``` | Iterable throws the error synchronously. |\n| | ```chain``` | |\n| | ```concatAll``` | |\n| | ```defer``` | Meh |\n| | ```expand``` | |\n| | ```find``` | |\n| | ```for``` | |\n| | ```generate``` | Iterable supports Generators. |\n| | ```groupBy``` | |\n| | ```groupJoin``` | |\n| | ```if``` | |\n| | ```memoize``` | |\n| | ```ofEntries``` | Use ```Object.entries``` instead. |\n| | ```ofKeys``` | Use ```Object.keys``` instead. |\n| | ```ofValues``` | Use ```Object.values``` instead. |\n| | ```onErrorResumeNext``` | Iterable doesn't support fallbacks. |\n| | ```pairwise``` | |\n| | ```pluck``` | |\n| | ```publish``` | |\n| | ```retry``` | Iterable doesn't support fallbacks. |\n| | ```share``` | |\n| | ```single``` | Isn't encouraged. |\n| | ```tap``` | use the ```doXXXX``` operators. |\n| | ```union``` | |\n\n## Usage\n\n### Installing\n\nNPM\n```\nnpm install @lxsmnsyc/iterable-js\n```\n\nCDN\n\n* jsDelivr\n  \n```html\n\u003cscript src=\"https://cdn.jsdelivr.net/npm/@lxsmnsyc/iterable-js/dist/index.min.js\"\u003e\u003c/script\u003e\n```\n\n* unpkg\n  \n```html\n\u003cscript src=\"https://unpkg.com/@lxsmnsyc/iterable-js/dist/index.min.js\"\u003e\u003c/script\u003e\n```\n\n\n### Loading the module\n\n#### CommonJS\n\n```js\nconst Iterable = require('iterable-js');\n```\n\nLoading the CommonJS module provides the Iterable class.\n\n#### Browser\n\nLoading the JavaScript file for the iterable-js provides the Iterable class.\n\n### Example\n\nCreates a partition of iterables in which the first iterable yields the even numbers, while the second iterable yields the odd numbers.\n```js\nconst evenOdd = Iterable.range(1, 200).partition(x =\u003e x % 2 === 0);\n\nfor (const i of evenOdd[0].map(x =\u003e `Next Even: ${x}`)) {\n  console.log(i);\n}\nfor (const i of evenOdd[1].map(x =\u003e `Next Odd: ${x}`)) {\n  console.log(i);\n}\n```\n\n### Static and non-Static\n\nAll operators of Iterable are both static and non-static (except for a few ones), allowing chainable and direct transformations.\n\nBoth examples below does the same thing.\n\n```js\nfor (const i of Iterable.filter('Hello World', x =\u003e x === x.toUpperCase())) {\n  console.log(i);\n}\n```\n\n```js\nfor (const i of new Iterable('Hello World').filter(x =\u003e x === x.toUpperCase())) {\n  console.log(i);\n}\n```\n\n### Generators\n\nIterable treats generator functions as an iterable object, even if it doesn't implement the iterable protocol.\n\n```js\nconst iterable = new Iterable(function* () {\n  yield 1;\n  yield 2;\n  yield 3;\n});\nfor (const i of iterable) {\n  console.log(i);\n}\n```\n\n### Creating your own operators\n\nTo create your own operator, you must pass functions to the ```compose``` method. The functions provided must receive a single parameter, which refers to the chained Iterable, and must return an Iterable.\n\n```js\nconst getOdds = source =\u003e source.filter(x =\u003e x % 2 === 1);\n\nfor (const i of Iterable.range(1, 1000).compose(getOdds)) {\n  console.log(i);\n}\n```\n\n```compose``` can accept multiple functions, allowing to build pipelines of operators.\n\n## Build\n\nClone the repo then run\n\n```bash\nnpm install\n```\n\nTo build distributables, coverages and tests:\n```bash\nnpm run build\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flxsmnsyc%2Fiterable-js","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flxsmnsyc%2Fiterable-js","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flxsmnsyc%2Fiterable-js/lists"}