Class: AsyncIterator

asynciterator~AsyncIterator()

An asynchronous iterator provides pull-based access to a stream of objects.

Constructor

new AsyncIterator()

Creates a new AsyncIterator.

Extends

  • module:asynciterator.EventEmitter

Members

(readonly) closed :boolean

Gets whether the iterator has stopped generating new items.

Type:
  • boolean

(readonly) destroyed :boolean

Gets whether the iterator has been destroyed.

Type:
  • boolean

(readonly) done :boolean

Gets whether the iterator will not emit anymore items, either due to being closed or due to being destroyed.

Type:
  • boolean

(readonly) ended :boolean

Gets whether the iterator has finished emitting items.

Type:
  • boolean

readable :boolean

Gets or sets whether this iterator might have items available for read. A value of false means there are definitely no items available; a value of true means items might be available.

Type:
  • boolean
Fires:
  • module:asynciterator.AsyncIterator.event:readable

Methods

Symbol.asyncIterator() → {ESAsyncIterator.<T>}

An AsyncIterator is async iterable. This allows iterators to be used via the for-await syntax.

In cases where the returned EcmaScript AsyncIterator will not be fully consumed, it is recommended to manually listen for error events on the main AsyncIterator to avoid uncaught error messages.

Returns:

An EcmaScript AsyncIterator

Type
ESAsyncIterator.<T>

(protected) _changeState(newState, eventAsyncopt) → {boolean}

Changes the iterator to the given state if possible and necessary, possibly emitting events to signal that change.

Parameters:
Name Type Attributes Default Description
newState integer

The ID of the new state
eventAsync boolean <optional>
 false

Whether resulting events should be emitted asynchronously
Fires:
  • module:asynciterator.AsyncIterator.event:end
Returns:

Whether the state was changed

Type
boolean

_destroy(causenullable, callback)

Called by module:asynciterator.AsyncIterator#destroy. Implementers can override this, but this should not be called directly.

Parameters:
Name Type Attributes Description
cause Error <nullable>

The reason why the iterator is destroyed.
callback function

A callback function with an optional error argument.

(protected) _end(destroyopt)

Ends the iterator and cleans up. Should never be called before module:asynciterator.AsyncIterator#close; typically, close is responsible for calling _end.

Parameters:
Name Type Attributes Default Description
destroy boolean <optional>
 false

If the iterator should be forcefully destroyed.
Fires:
  • module:asynciterator.AsyncIterator.event:end

(protected) _endAsync()

Asynchronously calls _end.

(protected) _toStringDetails()

Generates details for a textual representation of the iterator.

append(items) → {module:asynciterator.AsyncIterator}

Appends the items after those of the current iterator. After this operation, only read the returned iterator instead of the current one.

Parameters:
Name Type Description
items Array | module:asynciterator.AsyncIterator

Items to insert after this iterator's (remaining) items
Returns:

A new iterator that appends items to this iterator

Type
module:asynciterator.AsyncIterator

clone() → {module:asynciterator.AsyncIterator}

Creates a copy of the current iterator, containing all items emitted from this point onward. Further copies can be created; they will all start from this same point. After this operation, only read the returned copies instead of the original iterator.

Returns:

A new iterator that contains all future items of this iterator

Type
module:asynciterator.AsyncIterator

close()

Stops the iterator from generating new items. Already generated items or terminating items can still be emitted. After this, the iterator will end asynchronously.

Fires:
  • module:asynciterator.AsyncIterator.event:end

copyProperties(source, propertyNames)

Copies the given properties from the source iterator.

Parameters:
Name Type Description
source module:asynciterator.AsyncIterator

The iterator to copy from
propertyNames Array

List of property names to copy

destroy(causeopt)

Destroy the iterator and stop it from generating new items. This will not do anything if the iterator was already ended or destroyed. All internal resources will be released an no new items will be emitted, even not already generated items. Implementors should not override this method, but instead implement module:asynciterator.AsyncIterator#_destroy.

Parameters:
Name Type Attributes Description
cause Error <optional>

An optional error to emit.
Fires:
  • module:asynciterator.AsyncIterator.event:end
  • module:asynciterator.AsyncIterator.event:error Only if an error is passed.

forEach(callback, selfnullable)

Invokes the callback for each remaining item in the iterator. Switches the iterator to flow mode.

Parameters:
Name Type Attributes Description
callback function

A function that will be called with each item
self object <nullable>

The this pointer for the callback

getProperties() → {object}

Retrieves all properties of the iterator.

Returns:

An object with property names as keys.

Type
object

getProperty(propertyName, callbackopt, nullable) → (nullable) {object}

Retrieves the property with the given name from the iterator. If no callback is passed, it returns the value of the property or undefined if the property is not set. If a callback is passed, it returns undefined and calls the callback with the property the moment it is set.

Parameters:
Name Type Attributes Description
propertyName string

The name of the property to retrieve
callback function <optional>
<nullable>

A one-argument callback to receive the property value
Returns:

The value of the property (if set and no callback is given)

Type
object

map(map, selfnullable) → {module:asynciterator.AsyncIterator}

Maps items from this iterator using the given function. After this operation, only read the returned iterator instead of the current one.

Parameters:
Name Type Attributes Description
map function

A mapping function to call on this iterator's (remaining) items
self object <nullable>

The this pointer for the mapping function
Returns:

A new iterator that maps the items from this iterator

Type
module:asynciterator.AsyncIterator

prepend(items) → {module:asynciterator.AsyncIterator}

Prepends the items after those of the current iterator. After this operation, only read the returned iterator instead of the current one.

Parameters:
Name Type Description
items Array | module:asynciterator.AsyncIterator

Items to insert before this iterator's (remaining) items
Returns:

A new iterator that prepends items to this iterator

Type
module:asynciterator.AsyncIterator

range(start, end) → {module:asynciterator.AsyncIterator}

Limits the current iterator to the given range. The current iterator may not be read anymore until the returned iterator ends.

Parameters:
Name Type Description
start integer

Index of the first item to return
end integer

Index of the last item to return
Returns:

A new iterator with items in the given range

Type
module:asynciterator.AsyncIterator

read() → (nullable) {object}

Tries to read the next item from the iterator. This is the main method for reading the iterator in on-demand mode, where new items are only created when needed by consumers. If no items are currently available, this methods returns null. The module:asynciterator.event:readable event will then signal when new items might be ready. To read all items from the iterator, switch to flow mode by subscribing to the module:asynciterator.event:data event. When in flow mode, do not use the read method.

Returns:

The next item, or null if none is available

Type
object

setProperties(properties)

Sets all of the given properties.

Parameters:
Name Type Description
properties object

Key/value pairs of properties to set

setProperty(propertyName, valuenullable)

Sets the property with the given name to the value.

Parameters:
Name Type Attributes Description
propertyName string

The name of the property to set
value object <nullable>

The new value of the property

skip(offset) → {module:asynciterator.AsyncIterator}

Skips the given number of items from the current iterator. The current iterator may not be read anymore until the returned iterator ends.

Parameters:
Name Type Description
offset integer

The number of items to skip
Returns:

A new iterator that skips the given number of items

Type
module:asynciterator.AsyncIterator

surround(prepend, append) → {module:asynciterator.AsyncIterator}

Surrounds items of the current iterator with the given items. After this operation, only read the returned iterator instead of the current one.

Parameters:
Name Type Description
prepend Array | module:asynciterator.AsyncIterator

Items to insert before this iterator's (remaining) items
append Array | module:asynciterator.AsyncIterator

Items to insert after this iterator's (remaining) items
Returns:

A new iterator that appends and prepends items to this iterator

Type
module:asynciterator.AsyncIterator

take(limit) → {module:asynciterator.AsyncIterator}

Limits the current iterator to the given number of items. The current iterator may not be read anymore until the returned iterator ends.

Parameters:
Name Type Description
limit integer

The maximum number of items
Returns:

A new iterator with at most the given number of items

Type
module:asynciterator.AsyncIterator

toArray(optionsopt)

Consume all remaining items of the iterator into an array that will be returned asynchronously.

Parameters:
Name Type Attributes Description
options object <optional>

Settings for array creation

Properties
Name Type Attributes Description
limit integer <optional>

The maximum number of items to place in the array.

transform(optionsopt) → {module:asynciterator.AsyncIterator}

Transforms items from this iterator. After this operation, only read the returned iterator instead of the current one.

Parameters:
Name Type Attributes Description
options object | function <optional>

Settings of the iterator, or the transformation function

Properties
Name Type Attributes Default Description
maxbufferSize integer <optional>
 4

The maximum number of items to keep in the buffer
autoStart boolean <optional>
 true

Whether buffering starts directly after construction
offset integer <optional>

The number of items to skip
limit integer <optional>

The maximum number of items
filter function <optional>

A function to synchronously filter items from the source
map function <optional>

A function to synchronously transform items from the source
transform function <optional>

A function to asynchronously transform items from the source
optional boolean <optional>
 false

If transforming is optional, the original item is pushed when its mapping yields null or its transformation yields no items
prepend Array | module:asynciterator.AsyncIterator <optional>

Items to insert before the source items
append Array | module:asynciterator.AsyncIterator <optional>

Items to insert after the source items
Returns:

A new iterator that maps the items from this iterator

Type
module:asynciterator.AsyncIterator

uniq(by)

Returns a new iterator containing all of the unique items in the original iterator.

Parameters:
Name Type Description
by

The derived value by which to determine uniqueness (e.g., stringification). Defaults to the identity function.
Returns:

An iterator with duplicates filtered out.