Obliterator

Common errors

• TypeError: (0 , _obliterator__WEBPACK_IMPORTED_MODULE_0__.default) is not a constructor

  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.
  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';`

• TypeError: chain is not a function

  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.
  fix Always import utility functions as named exports: `import { chain } from 'obliterator';`. For CommonJS, use `const { chain } = require('obliterator');`.

• RangeError: Invalid array length

  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.
  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.

Warnings

• gotcha 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.
  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]);`
• gotcha 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.
  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.
• gotcha 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.
  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.

Install

• npm install obliterator npm
• yarn add obliterator yarn
• pnpm add obliterator pnpm

Imports

• Iterator
  wrong:

  import Iterator from 'obliterator';

  correct:

  import { Iterator } from 'obliterator';

  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.
• chain
  wrong:

  import chain from 'obliterator';
  const chain = require('obliterator').chain;

  correct:

  import { chain } from 'obliterator';

  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.
• filter
  wrong:

  import filter from 'obliterator/filter';
  const filter = require('obliterator').filter;

  correct:

  import { filter } from 'obliterator';

  Similar to `chain`, `filter` is a named export. For CommonJS environments, ensure you access the named export from the `require`'d object.
• IterableLike

  import type { IterableLike } from 'obliterator';

  For TypeScript users, type imports like `IterableLike` (which represents the flexible iterable-like values the library accepts) are available from the main package.

Quickstart

This quickstart demonstrates creating an iterator, applying filter and map transformations, chaining with other iterables, and highlights a key `combinations` gotcha.

import { Iterator, filter, map, chain } from 'obliterator';

// Create an iterator from multiple values
const numbers = Iterator.of(1, 2, 3, 4, 5, 6, 7, 8, 9, 10);

// Filter for even numbers
const evenNumbers = filter(numbers, (n: number) => n % 2 === 0);

// Map to their squares
const squaredEvenNumbers = map(evenNumbers, (n: number) => n * n);

// Chain with another iterable (e.g., a simple array)
const combined = chain(squaredEvenNumbers, [121, 144, 169]);

console.log('Processed numbers:');
for (const value of combined) {
  console.log(value);
}

// Demonstrate combinations - careful with object mutation!
import { combinations } from 'obliterator';
const arr = ['A', 'B', 'C'];
const combos = combinations(arr, 2);

let firstCombo: string[] = [];
let secondCombo: string[] = [];

firstCombo = Array.from(combos.next().value);
secondCombo = Array.from(combos.next().value);

console.log('First combination:', firstCombo); // Should be ['A', 'B']
console.log('Second combination:', secondCombo); // Should be ['A', 'C']