@xstd/enumerable

Provides Enumerable, Enumerator, EnumeratorObject and their async counterparts, as better alternatives to Iterable and Iterator.

Indeed, Iterable and Iterator are not very well typed, especially the next and return methods.

Using Enumerable and Enumerator gives you better type safety.

NOTE: currently IteratorObject methods are not typed.

Example

Issue:

const iterator = (function *(): Generator<void, void, number> {
  console.log(yield);
})();

iterator.next(1); // valid
iterator.next(); // invalid, but no typing error

Solution:

const enumerator: Enumerator<number, void, void> = (function *(): Generator<void, void, number> {
  console.log(yield);
})();

enumerator.next(1); // valid
enumerator.next(); // invalid, WITH typing error

📦 Installation

yarn add @xstd/enumerable
# or
npm install @xstd/enumerable --save

📜 Documentation

interface Enumerator<GIn, GOut, GReturn> {
  next(...args: EnumeratorNextArguments<GIn>): EnumeratorResult<GOut, GReturn>;

  throw(error?: unknown): EnumeratorResult<GOut, GReturn>;

  return(...args: EnumeratorReturnArguments<GReturn>): EnumeratorResult<GOut, GReturn>;
}

interface Enumerable<GIn, GOut, GReturn> {
  [Symbol.asyncIterator](): Enumerator<GIn, GOut, GReturn>;
}

interface EnumeratorObject<GIn, GOut, GReturn>
  extends Enumerator<GIn, GOut, GReturn>,
    Disposable {
  [Symbol.asyncIterator](): EnumeratorObject<GIn, GOut, GReturn>;
}

The lib also provides the Async counterparts.