{"id":11484,"library":"obliterator","title":"Obliterator","description":"Obliterator is a JavaScript/TypeScript library designed to provide higher-order functions for working with iterators and iterable-like values. It offers a suite of utilities for common iterable operations such as chaining multiple iterators, generating combinations and permutations, filtering, mapping, and consuming iterators. A key differentiator is its pragmatic approach to iterables, treating standard sequences like arrays and strings as valid inputs for convenience, even if they aren't strict ES6 iterables. The current stable version is 2.0.5, and it ships with full TypeScript declarations. The library is actively maintained, with the latest update noted in January 2025 on npm, focusing on utility functions for managing data streams and collections.","status":"active","version":"2.0.5","language":"javascript","source_language":"en","source_url":"https://github.com/yomguithereal/obliterator","tags":["javascript","iterator","typescript"],"install":[{"cmd":"npm install obliterator","lang":"bash","label":"npm"},{"cmd":"yarn add obliterator","lang":"bash","label":"yarn"},{"cmd":"pnpm add obliterator","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The `Iterator` class can be imported either as a named export from the main package or as a default export from the submodule `obliterator/iterator`. The named export is generally preferred.","wrong":"import Iterator from 'obliterator';","symbol":"Iterator","correct":"import { Iterator } from 'obliterator';"},{"note":"Most utility functions like `chain`, `filter`, `map`, etc., are named exports. While the library also provides default exports from their respective submodules (e.g., `obliterator/chain`), importing them as named exports from the main package is the recommended approach for tree-shaking and clarity.","wrong":"import chain from 'obliterator';\nconst chain = require('obliterator').chain;","symbol":"chain","correct":"import { chain } from 'obliterator';"},{"note":"Similar to `chain`, `filter` is a named export. For CommonJS environments, ensure you access the named export from the `require`'d object.","wrong":"import filter from 'obliterator/filter';\nconst filter = require('obliterator').filter;","symbol":"filter","correct":"import { filter } from 'obliterator';"},{"note":"For TypeScript users, type imports like `IterableLike` (which represents the flexible iterable-like values the library accepts) are available from the main package.","symbol":"IterableLike","correct":"import type { IterableLike } from 'obliterator';"}],"quickstart":{"code":"import { Iterator, filter, map, chain } from 'obliterator';\n\n// Create an iterator from multiple values\nconst numbers = Iterator.of(1, 2, 3, 4, 5, 6, 7, 8, 9, 10);\n\n// Filter for even numbers\nconst evenNumbers = filter(numbers, (n: number) => n % 2 === 0);\n\n// Map to their squares\nconst squaredEvenNumbers = map(evenNumbers, (n: number) => n * n);\n\n// Chain with another iterable (e.g., a simple array)\nconst combined = chain(squaredEvenNumbers, [121, 144, 169]);\n\nconsole.log('Processed numbers:');\nfor (const value of combined) {\n  console.log(value);\n}\n\n// Demonstrate combinations - careful with object mutation!\nimport { combinations } from 'obliterator';\nconst arr = ['A', 'B', 'C'];\nconst combos = combinations(arr, 2);\n\nlet firstCombo: string[] = [];\nlet secondCombo: string[] = [];\n\nfirstCombo = Array.from(combos.next().value);\nsecondCombo = Array.from(combos.next().value);\n\nconsole.log('First combination:', firstCombo); // Should be ['A', 'B']\nconsole.log('Second combination:', secondCombo); // Should be ['A', 'C']","lang":"typescript","description":"This quickstart demonstrates creating an iterator, applying filter and map transformations, chaining with other iterables, and highlights a key `combinations` gotcha."},"warnings":[{"fix":"When consuming results from `combinations` or `permutations` that need to be stored, clone the yielded array: `const combo = Array.from(iterator.next().value);` or `const allCombos = [...combinations(array, k)].map(c => [...c]);`","message":"When using functions like `combinations` or `permutations`, the yielded combination/permutation object is often the same mutable array reference for performance reasons. If you need to store these results, you must clone them (e.g., using `Array.from()` or spread syntax `[...]`) to prevent subsequent iterations from overwriting previously stored values.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"Be aware of this distinction when integrating with other libraries that strictly adhere to the ES6 iterable protocol. Use `Iterator.is(value)` for Obliterator's own definition of an iterable.","message":"Obliterator's functions are designed to work with 'iterable-like' values, which includes standard ES6 iterables (like `Set.prototype.values()`) but also non-standard iterables like plain arrays and strings. While convenient, this flexibility means that direct type checking against `Symbol.iterator` might not always align with Obliterator's broader definition of what can be iterated.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"If you need to iterate over the same sequence multiple times, ensure you create a new iterator instance each time, or convert the iterator to a collection (e.g., an array) after the first pass if memory allows.","message":"Iterators are single-pass by nature. Once an iterator is consumed (fully or partially), it cannot be re-iterated from the beginning unless a new iterator is created. Functions like `consume` explicitly advance the iterator, potentially exhausting it.","severity":"gotcha","affected_versions":">=2.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Use a named import for `Iterator` from the main package: `import { Iterator } from 'obliterator';` or ensure the default import is from the specific submodule: `import Iterator from 'obliterator/iterator';`","cause":"Attempting to instantiate `Iterator` using a default import when it's primarily exported as a named export from the main package, or incorrect import path for the default export.","error":"TypeError: (0 , _obliterator__WEBPACK_IMPORTED_MODULE_0__.default) is not a constructor"},{"fix":"Always import utility functions as named exports: `import { chain } from 'obliterator';`. For CommonJS, use `const { chain } = require('obliterator');`.","cause":"Trying to use `chain` (or other utility functions) after importing it incorrectly as a default import from the main `obliterator` package, or from a CommonJS `require` call that doesn't destructure the named export.","error":"TypeError: chain is not a function"},{"fix":"Ensure the 'k' value for `combinations` or `permutations` is reasonable and does not lead to an combinatorial explosion that exceeds system memory or JavaScript engine limits. Re-evaluate your algorithm if very large 'k' values are truly needed.","cause":"Passing an extremely large number for 'k' to `combinations` or `permutations` that results in an impossibly large intermediate array, exceeding JavaScript's maximum array size.","error":"RangeError: Invalid array length"}],"ecosystem":"npm"}