obliterator

library2.0.5jsnpmunverified

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.

data serialization

npm install obliterator

github ↗package ↗

INSTALL

IMPORT

SIG · OBLITERATOR

obliterator

datajavascriptv2.0.5

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Iterator

✓ import { Iterator } from 'obliterator';

✗ 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

✓ import { chain } from 'obliterator';

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

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

✓ import { filter } from 'obliterator';

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

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.

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']

Debug

Known issues

gotchaWhen 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]);`

affects: >=2.0.0

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

affects: >=2.0.0

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

affects: >=2.0.0

Errors

Common errors & fixes

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

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

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

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.

Upgrade

Version history

2.0.5latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/yomguithereal/obliterator ↗

packagehttps://www.npmjs.com/package/obliterator ↗