{"id":16355893,"url":"https://github.com/yomguithereal/obliterator","last_synced_at":"2025-05-16T15:04:57.489Z","repository":{"id":47058150,"uuid":"89709482","full_name":"Yomguithereal/obliterator","owner":"Yomguithereal","description":"Higher order iterator library for JavaScript and TypeScript.","archived":false,"fork":false,"pushed_at":"2025-01-06T15:26:51.000Z","size":392,"stargazers_count":58,"open_issues_count":7,"forks_count":5,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-04-29T01:07:21.822Z","etag":null,"topics":["iterator"],"latest_commit_sha":null,"homepage":"","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/Yomguithereal.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":"support.js","governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-04-28T13:39:32.000Z","updated_at":"2025-04-02T21:04:04.000Z","dependencies_parsed_at":"2025-02-07T12:08:03.412Z","dependency_job_id":"bcac8951-b771-418c-b47f-0add453f0adf","html_url":"https://github.com/Yomguithereal/obliterator","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Yomguithereal%2Fobliterator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Yomguithereal%2Fobliterator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Yomguithereal%2Fobliterator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Yomguithereal%2Fobliterator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Yomguithereal","download_url":"https://codeload.github.com/Yomguithereal/obliterator/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253341969,"owners_count":21893547,"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":["iterator"],"created_at":"2024-10-11T01:42:05.728Z","updated_at":"2025-05-16T15:04:57.468Z","avatar_url":"https://github.com/Yomguithereal.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Build Status](https://github.com/Yomguithereal/obliterator/workflows/Tests/badge.svg)](https://github.com/Yomguithereal/obliterator/actions)\n\n# Obliterator\n\nObliterator is a dead simple JavaScript/TypeScript library providing miscellaneous higher-order iterator/iterable functions such as combining two or more iterators into a single one.\n\nNote that when possible, `obliterator` also consider sequences such as arrays, strings etc. as valid iterables (although they are not proper ES6 iterables values), for convenience.\n\n# Installation\n\n```\nnpm install --save obliterator\n```\n\nNote that `obliterator` comes along with its TypeScript declarations.\n\n# Usage\n\n## Summary\n\n_Classes_\n\n- [Iterator](#iterator)\n\n_Functions_\n\n- [chain](#chain)\n- [combinations](#combinations)\n- [consume](#consume)\n- [every](#every)\n- [filter](#filter)\n- [find](#find)\n- [forEach](#foreach)\n- [forEachWithNullKeys](#foreachwithnullkeys)\n- [includes](#includes)\n- [iter](#iter)\n- [map](#map)\n- [match](#match)\n- [permutations](#permutations)\n- [powerSet](#powerSet)\n- [some](#some)\n- [split](#split)\n- [take](#take)\n\n## Iterator\n\nA handy Iterator class easily usable with ES2015's `for ... of` loop constructs \u0026 spread operator.\n\n```js\nimport Iterator from 'obliterator/iterator';\n// Or\nimport {Iterator} from 'obliterator';\n\nconst iterator = new Iterator(function () {\n  // Define what the `next` function does\n  return {done: false, value: 34};\n});\n\n// Checking that the given value is an iterator (native or else)\nIterator.is(value);\n\n// Creating an empty iterator\nconst emptyIterator = Iterator.empty();\n\n// Creating a simple iterator from a single value\nconst simpleIterator = Iterator.of(34);\n\n// Creating a simple iterator from multiple values\nconst multipleIterator = Iterator.of(1, 2, 3);\n```\n\n## chain\n\nVariadic function chaining all the given iterable-like values.\n\n```js\nimport chain from 'obliterator/chain';\n// Or\nimport {chain} from 'obliterator';\n\nconst set1 = new Set('a');\nconst set2 = new Set('bc');\n\nconst chained = chain(set1.values(), set2);\n\nchained.next();\n\u003e\u003e\u003e {done: false, value: 'a'}\nchained.next();\n\u003e\u003e\u003e {done: false, value: 'b'}\n```\n\n## combinations\n\nReturns an iterator of combinations of the given array and of the given size.\n\nNote that for performance reasons, the yielded combination is always the same object.\n\n```js\nimport combinations from 'obliterator/combinations';\n// Or\nimport {combinations} from 'obliterator';\n\nconst iterator = combinations(['A', 'B', 'C', 'D'], 2);\n\niterator.next().value;\n\u003e\u003e\u003e ['A', 'B']\niterator.next().value;\n\u003e\u003e\u003e ['A', 'C']\n```\n\n## consume\n\nFunction consuming the given iterator fully or for n steps.\n\n```js\nimport consume from 'obliterator/consume';\n// Or\nimport {consume} from 'obliterator';\n\nconst set = new Set([1, 2, 3]);\n\n// Consuming the whole iterator\nlet iterator = set.values();\nconsume(iterator);\niterator.next().done \u003e\u003e\u003e true;\n\n// Consuming n steps\nlet iterator = set.values();\nconsume(iterator, 2);\niterator.next().value \u003e\u003e\u003e 3;\n```\n\n## every\n\nFunction returning whether all items of an iterable-like match the given predicate function.\n\n```js\nimport every from 'obliterator/every';\n// Or\nimport {every} from 'obliterator';\n\nevery([2, 4, 6], n =\u003e n % 2 === 0);\n\u003e\u003e\u003e true\n\nevery([1, 2, 3], n =\u003e n % 2 === 0);\n\u003e\u003e\u003e false\n```\n\n## filter\n\nFunction returning an iterator filtering another one's values using the given predicate function.\n\n```js\nimport filter from 'obliterator/filter';\n// Or\nimport {filter} from 'obliterator';\n\nconst set = new Set([1, 2, 3, 4, 5]);\n\nconst even = x =\u003e x % 2 === 0;\n\nconst iterator = filter(set.values(), even);\n\niterator.next().value \u003e\u003e\u003e 2;\niterator.next().value \u003e\u003e\u003e 4;\n```\n\n## find\n\nFunction returning the next item matching given predicate function in an iterable-like.\n\n```js\nimport find from 'obliterator/find';\n// Or\nimport {find} from 'obliterator';\n\nconst set = new Set([1, 2, 3, 4, 5]);\n\nconst even = x =\u003e x % 2 === 0;\n\nconst values = set.values();\n\nfind(values, even);\n\u003e\u003e\u003e 2\n\nfind(values, even);\n\u003e\u003e\u003e 4\n\nfind(values, even);\n\u003e\u003e\u003e undefined\n```\n\n## forEach\n\nFunction able to iterate over almost any JavaScript iterable value using a callback.\n\nSupported values range from arrays, typed arrays, sets, maps, objects, strings, arguments, iterators, arbitrary iterables etc.\n\n```js\nimport forEach from 'obliterator/foreach';\n// Or\nimport {forEach} from 'obliterator';\n\nconst set = new Set(['apple', 'banana']);\n\nforEach(set.values(), (value, i) =\u003e {\n  console.log(i, value);\n});\n\n// Iterating over a string\nforEach('abc', (char, i) =\u003e ...);\n\n// Iterating over a map\nforEach(map, (value, key) =\u003e ...);\n```\n\n## forEachWithNullKeys\n\nVariant of [forEach](#foreach) one can use to iterate over mixed values but with the twist that iterables without proper keys (lists, sets etc.), will yield `null` instead of an index key.\n\nSupported values range from arrays, typed arrays, sets, maps, objects, strings, arguments, iterators, arbitrary iterables etc.\n\n```js\nimport {forEachWithNullKeys} from 'obliterator/foreach';\n\nconst set = new Set(['apple', 'banana']);\n\nforEach(set, (value, key) =\u003e {\n  console.log(key, value);\n});\n\u003e\u003e\u003e null, 'apple'\n\u003e\u003e\u003e null, 'banana'\n```\n\n## includes\n\nFunction returning whether the given value can be found in given iterable-like.\n\n```js\nimport {includes} from 'obliterator';\n// Or\nimport includes from 'obliterator/includes';\n\nincludes([1, 2, 3], 3);\n\u003e\u003e\u003e true;\n\nincludes('test', 'a');\n\u003e\u003e\u003e false;\n```\n\n## iter\n\nFunction casting any iterable-like value to a proper iterator. Will throw an error if the given value cannot be cast as an iterator.\n\n```js\nimport {iter} from 'obliterator';\n// Or\nimport iter from 'obliterator/iter';\n\niter('test');\niter(new Set([1, 2, 3]));\n\n// This will throw:\niter(null);\n```\n\n## map\n\nFunction returning an iterator mapping another one's values using the given function.\n\n```js\nimport map from 'obliterator/map';\n// Or\nimport {map} from 'obliterator';\n\nconst set = new Set([1, 2, 3, 4, 5]);\n\nconst triple = x =\u003e x * 3;\n\nconst iterator = map(set.values(), triple);\n\niterator.next().value \u003e\u003e\u003e 3;\niterator.next().value \u003e\u003e\u003e 6;\n```\n\n## match\n\nFunction returning an iterator over the matches of a given regex applied to the target string.\n\n```js\nimport match from 'obliterator/match';\n// Or\nimport {match} from 'obliterator';\n\nconst iterator = match(/t/, 'test');\n\niterator.next().value.index \u003e\u003e\u003e 0;\niterator.next().value.index \u003e\u003e\u003e 3;\n```\n\n## permutations\n\nReturns an iterator of permutations of the given array and of the given size.\n\nNote that for performance reasons, the yielded permutation is always the same object.\n\n```js\nimport permutations from 'obliterator/permutations';\n// Or\nimport {permutations} from 'obliterator';\n\nlet iterator = permutations([1, 2, 3]);\n\niterator.next().value\n\u003e\u003e\u003e [1, 2, 3]\niterator.next().value\n\u003e\u003e\u003e [1, 3, 2]\n\niterator = permutations(['A', 'B', 'C', 'D'], 2);\n\niterator.next().value;\n\u003e\u003e\u003e ['A', 'B']\niterator.next().value;\n\u003e\u003e\u003e ['A', 'C']\n```\n\n## powerSet\n\nReturns an iterator of sets composing the power set of the given array.\n\n```js\nimport powerSet from 'obliterator/power-set';\n// Or\nimport {powerSet} from 'obliterator';\n\nconst iterator = powerSet(['A', 'B', 'C']);\n\niterator.next().value;\n\u003e\u003e\u003e []\niterator.next().value;\n\u003e\u003e\u003e ['A']\n```\n\n## some\n\nReturns whether the given iterable-like has some item matching the given predicate function.\n\n```js\nimport some from 'obliterator/some';\n// Or\nimport {some} from 'obliterator';\n\nsome(new Set([1, 2, 3]), n =\u003e n % 2 === 0);\n\u003e\u003e\u003e true\n\nsome('test', c =\u003e c === 'a');\n\u003e\u003e\u003e false\n```\n\n## split\n\nReturns an iterator over the splits of the target string, according to the given RegExp pattern.\n\n```js\nimport split from 'obliterator/split';\n// Or\nimport {split} from 'obliterator';\n\nconst iterator = split(/;/g, 'hello;world;super');\n\niterator.next().value;\n\u003e\u003e\u003e 'hello'\niterator.next().value;\n\u003e\u003e\u003e 'world'\n```\n\n## take\n\nFunction taking values from given iterator and returning them in an array.\n\n```js\nimport take from 'obliterator/take';\n// Or\nimport {take} from 'obliterator';\n\nconst set = new Set([1, 2, 3]);\n\n// To take n values from the iterator\ntake(set.values(), 2);\n\u003e\u003e\u003e [1, 2]\n\n// To convert the full iterator into an array\ntake(set.values());\n\u003e\u003e\u003e [1, 2, 3]\n```\n\n# Contribution\n\nContributions are obviously welcome. Please be sure to lint the code \u0026 add the relevant unit tests before submitting any PR.\n\n```\ngit clone git@github.com:Yomguithereal/obliterator.git\ncd obliterator\nnpm install\n\n# To lint the code\nnpm run lint\n\n# To run the unit tests\nnpm test\n```\n\n# License\n\n[MIT](LICENSE.txt)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyomguithereal%2Fobliterator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyomguithereal%2Fobliterator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyomguithereal%2Fobliterator/lists"}