asynciterator/dist/asynciterator.d.ts

An asynchronous iterator library for advanced object pipelines.

/**
 * An asynchronous iterator library for advanced object pipelines
 * @module asynciterator
 */
/// <reference types="node" />
import { EventEmitter } from 'events';
import { LinkedList } from './linkedlist';
import type { Task, TaskScheduler } from './taskscheduler';
export { LinkedList };
/** Schedules the given task for asynchronous execution. */
export declare function scheduleTask(task: Task): void;
/** Returns the asynchronous task scheduler. */
export declare function getTaskScheduler(): TaskScheduler;
/** Sets the asynchronous task scheduler. */
export declare function setTaskScheduler(scheduler: TaskScheduler): void;
/**
  ID of the INIT state.
  An iterator is initializing if it is preparing main item generation.
  It can already produce items.
  @type integer
*/
export declare const INIT: number;
/**
  ID of the OPEN state.
  An iterator is open if it can generate new items.
  @type integer
*/
export declare const OPEN: number;
/**
  ID of the CLOSING state.
  An iterator is closing if item generation is pending but will not be scheduled again.
  @type integer
*/
export declare const CLOSING: number;
/**
  ID of the CLOSED state.
  An iterator is closed if it no longer actively generates new items.
  Items might still be available.
  @type integer
*/
export declare const CLOSED: number;
/**
  ID of the ENDED state.
  An iterator has ended if no further items will become available.
  The 'end' event is guaranteed to have been called when in this state.
  @type integer
*/
export declare const ENDED: number;
/**
  ID of the DESTROYED state.
  An iterator has been destroyed
  after calling {@link module:asynciterator.AsyncIterator#destroy}.
  The 'end' event has not been called, as pending elements were voided.
  @type integer
*/
export declare const DESTROYED: number;
/**
  An asynchronous iterator provides pull-based access to a stream of objects.
  @extends module:asynciterator.EventEmitter
*/
export declare class AsyncIterator<T> extends EventEmitter implements AsyncIterable<T> {
    protected _state: number;
    private _readable;
    protected _properties?: {
        [name: string]: any;
    };
    protected _propertyCallbacks?: {
        [name: string]: [(value: any) => void];
    };
    /** Creates a new `AsyncIterator`. */
    constructor(initialState?: number);
    /**
      Changes the iterator to the given state if possible and necessary,
      possibly emitting events to signal that change.
      @protected
      @param {integer} newState The ID of the new state
      @param {boolean} [eventAsync=false] Whether resulting events should be emitted asynchronously
      @returns {boolean} Whether the state was changed
      @emits module:asynciterator.AsyncIterator.end
    */
    protected _changeState(newState: number, eventAsync?: boolean): boolean;
    /**
      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 {@link 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 {@link module:asynciterator.event:data} event.
      When in flow mode, do not use the `read` method.
      @returns {object?} The next item, or `null` if none is available
    */
    read(): T | null;
    /**
      The iterator emits a `readable` event when it might have new items available
      after having had no items available right before this event.
      If the iterator is not in flow mode, items can be retrieved
      by calling {@link module:asynciterator.AsyncIterator#read}.
      @event module:asynciterator.readable
    */
    /**
      The iterator emits a `data` event with a new item as soon as it becomes available.
      When one or more listeners are attached to the `data` event,
      the iterator switches to _flow mode_,
      generating and emitting new items as fast as possible.
      This drains the source and might create backpressure on the consumers,
      so only subscribe to this event if this behavior is intended.
      In flow mode, don't use {@link module:asynciterator.AsyncIterator#read}.
      To switch back to _on-demand mode_, remove all listeners from the `data` event.
      You can then obtain items through `read` again.
      @event module:asynciterator.data
      @param {object} item The new item
    */
    /**
      Invokes the callback for each remaining item in the iterator.
      Switches the iterator to flow mode.
      @param {Function} callback A function that will be called with each item
      @param {object?} self The `this` pointer for the callback
    */
    forEach(callback: (item: T) => void, self?: object): void;
    /**
      Stops the iterator from generating new items.
      Already generated items or terminating items can still be emitted.
      After this, the iterator will end asynchronously.
      @emits module:asynciterator.AsyncIterator.end
    */
    close(): void;
    /**
      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 {@link module:asynciterator.AsyncIterator#_destroy}.
      @param {Error} [cause] An optional error to emit.
      @emits module:asynciterator.AsyncIterator.end
      @emits module:asynciterator.AsyncIterator.error Only if an error is passed.
    */
    destroy(cause?: Error): void;
    /**
      Called by {@link module:asynciterator.AsyncIterator#destroy}.
      Implementers can override this, but this should not be called directly.
      @param {?Error} cause The reason why the iterator is destroyed.
      @param {Function} callback A callback function with an optional error argument.
    */
    protected _destroy(cause: Error | undefined, callback: (error?: Error) => void): void;
    /**
      Ends the iterator and cleans up.
      Should never be called before {@link module:asynciterator.AsyncIterator#close};
      typically, `close` is responsible for calling `_end`.
      @param {boolean} [destroy] If the iterator should be forcefully destroyed.
      @protected
      @emits module:asynciterator.AsyncIterator.end
    */
    protected _end(destroy?: boolean): void;
    /**
      Asynchronously calls `_end`.
      @protected
    */
    protected _endAsync(): void;
    /**
      The `end` event is emitted after the last item of the iterator has been read.
      @event module:asynciterator.end
    */
    /**
      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
      @emits module:asynciterator.AsyncIterator.readable
    */
    get readable(): boolean;
    set readable(readable: boolean);
    /**
      Gets whether the iterator has stopped generating new items.
      @type boolean
      @readonly
    */
    get closed(): boolean;
    /**
      Gets whether the iterator has finished emitting items.
      @type boolean
      @readonly
    */
    get ended(): boolean;
    /**
      Gets whether the iterator has been destroyed.
      @type boolean
      @readonly
    */
    get destroyed(): boolean;
    /**
      Gets whether the iterator will not emit anymore items,
      either due to being closed or due to being destroyed.
      @type boolean
      @readonly
    */
    get done(): boolean;
    toString(): string;
    /**
      Generates details for a textual representation of the iterator.
      @protected
    */
    protected _toStringDetails(): string;
    /**
      Consume all remaining items of the iterator into an array that will be returned asynchronously.
      @param {object} [options] Settings for array creation
      @param {integer} [options.limit] The maximum number of items to place in the array.
     */
    toArray(options?: {
        limit?: number;
    }): Promise<T[]>;
    /**
      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.
      @param {string} propertyName The name of the property to retrieve
      @param {Function?} [callback] A one-argument callback to receive the property value
      @returns {object?} The value of the property (if set and no callback is given)
    */
    getProperty<P>(propertyName: string, callback?: (value: P) => void): P | undefined;
    /**
      Sets the property with the given name to the value.
      @param {string} propertyName The name of the property to set
      @param {object?} value The new value of the property
    */
    setProperty<P>(propertyName: string, value: P): void;
    /**
      Retrieves all properties of the iterator.
      @returns {object} An object with property names as keys.
    */
    getProperties(): {
        [name: string]: any;
    };
    /**
      Sets all of the given properties.
      @param {object} properties Key/value pairs of properties to set
    */
    setProperties(properties: {
        [name: string]: any;
    }): void;
    /**
      Copies the given properties from the source iterator.
      @param {module:asynciterator.AsyncIterator} source The iterator to copy from
      @param {Array} propertyNames List of property names to copy
    */
    copyProperties(source: AsyncIterator<any>, propertyNames: string[]): void;
    /**
      Transforms items from this iterator.
      After this operation, only read the returned iterator instead of the current one.
      @param {object|Function} [options] Settings of the iterator, or the transformation function
      @param {integer} [options.maxbufferSize=4] The maximum number of items to keep in the buffer
      @param {boolean} [options.autoStart=true] Whether buffering starts directly after construction
      @param {integer} [options.offset] The number of items to skip
      @param {integer} [options.limit] The maximum number of items
      @param {Function} [options.filter] A function to synchronously filter items from the source
      @param {Function} [options.map] A function to synchronously transform items from the source
      @param {Function} [options.transform] A function to asynchronously transform items from the source
      @param {boolean} [options.optional=false] If transforming is optional, the original item is pushed when its mapping yields `null` or its transformation yields no items
      @param {Array|module:asynciterator.AsyncIterator} [options.prepend] Items to insert before the source items
      @param {Array|module:asynciterator.AsyncIterator} [options.append]  Items to insert after the source items
      @returns {module:asynciterator.AsyncIterator} A new iterator that maps the items from this iterator
    */
    transform<D>(options: TransformOptions<T, D>): AsyncIterator<D>;
    /**
      Maps items from this iterator using the given function.
      After this operation, only read the returned iterator instead of the current one.
      @param {Function} map A mapping function to call on this iterator's (remaining) items
      @param {object?} self The `this` pointer for the mapping function
      @returns {module:asynciterator.AsyncIterator} A new iterator that maps the items from this iterator
    */
    map<D>(map: MapFunction<T, D>, self?: any): AsyncIterator<D>;
    /**
      Return items from this iterator that match the filter.
      After this operation, only read the returned iterator instead of the current one.
      @param {Function} filter A filter function to call on this iterator's (remaining) items
      @param {object?} self The `this` pointer for the filter function
      @returns {module:asynciterator.AsyncIterator} A new iterator that filters items from this iterator
    */
    filter<K extends T>(filter: (item: T) => item is K, self?: any): AsyncIterator<K>;
    filter(filter: (item: T) => boolean, self?: any): AsyncIterator<T>;
    /**
     * Returns a new iterator containing all of the unique items in the original iterator.
     * @param by - The derived value by which to determine uniqueness (e.g., stringification).
                   Defaults to the identity function.
     * @returns An iterator with duplicates filtered out.
     */
    uniq(by?: (item: T) => any): AsyncIterator<T>;
    /**
      Prepends the items after those of the current iterator.
      After this operation, only read the returned iterator instead of the current one.
      @param {Array|module:asynciterator.AsyncIterator} items Items to insert before this iterator's (remaining) items
      @returns {module:asynciterator.AsyncIterator} A new iterator that prepends items to this iterator
    */
    prepend(items: T[] | AsyncIterator<T>): AsyncIterator<T>;
    /**
      Appends the items after those of the current iterator.
      After this operation, only read the returned iterator instead of the current one.
      @param {Array|module:asynciterator.AsyncIterator} items Items to insert after this iterator's (remaining) items
      @returns {module:asynciterator.AsyncIterator} A new iterator that appends items to this iterator
    */
    append(items: T[] | AsyncIterator<T>): AsyncIterator<T>;
    /**
      Surrounds items of the current iterator with the given items.
      After this operation, only read the returned iterator instead of the current one.
      @param {Array|module:asynciterator.AsyncIterator} prepend Items to insert before this iterator's (remaining) items
      @param {Array|module:asynciterator.AsyncIterator} append Items to insert after this iterator's (remaining) items
      @returns {module:asynciterator.AsyncIterator} A new iterator that appends and prepends items to this iterator
    */
    surround(prepend: AsyncIteratorOrArray<T>, append: AsyncIteratorOrArray<T>): AsyncIterator<T>;
    /**
      Skips the given number of items from the current iterator.
      The current iterator may not be read anymore until the returned iterator ends.
      @param {integer} offset The number of items to skip
      @returns {module:asynciterator.AsyncIterator} A new iterator that skips the given number of items
    */
    skip(offset: number): AsyncIterator<T>;
    /**
      Limits the current iterator to the given number of items.
      The current iterator may not be read anymore until the returned iterator ends.
      @param {integer} limit The maximum number of items
      @returns {module:asynciterator.AsyncIterator} A new iterator with at most the given number of items
    */
    take(limit: number): AsyncIterator<T>;
    /**
      Limits the current iterator to the given range.
      The current iterator may not be read anymore until the returned iterator ends.
      @param {integer} start Index of the first item to return
      @param {integer} end Index of the last item to return
      @returns {module:asynciterator.AsyncIterator} A new iterator with items in the given range
    */
    range(start: number, end: number): AsyncIterator<T>;
    /**
      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 {module:asynciterator.AsyncIterator} A new iterator that contains all future items of this iterator
    */
    clone(): ClonedIterator<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 {ESAsyncIterator<T>} An EcmaScript AsyncIterator
     */
    [Symbol.asyncIterator](): ESAsyncIterator<T>;
}
/**
  An iterator that doesn't emit any items.
  @extends module:asynciterator.AsyncIterator
*/
export declare class EmptyIterator<T> extends AsyncIterator<T> {
    /** Creates a new `EmptyIterator`. */
    constructor();
}
/**
  An iterator that emits a single item.
  @extends module:asynciterator.AsyncIterator
*/
export declare class SingletonIterator<T> extends AsyncIterator<T> {
    private _item;
    /**
      Creates a new `SingletonIterator`.
      @param {object} item The item that will be emitted.
    */
    constructor(item: T);
    read(): T | null;
    protected _toStringDetails(): string;
}
/**
  An iterator that emits the items of a given array.
  @extends module:asynciterator.AsyncIterator
*/
export declare class ArrayIterator<T> extends AsyncIterator<T> {
    private _buffer?;
    protected _index: number;
    protected _sourceStarted: boolean;
    protected _truncateThreshold: number;
    /**
      Creates a new `ArrayIterator`.
      @param {Array} items The items that will be emitted.
      @param {boolean} [options.autoStart=true] Whether buffering starts directly after construction
      @param {boolean} [options.preserve=true] If false, the passed array can be safely modified
    */
    constructor(items?: Iterable<T>, { autoStart, preserve }?: {
        autoStart?: boolean | undefined;
        preserve?: boolean | undefined;
    });
    read(): T | null;
    protected _toStringDetails(): string;
    protected _destroy(cause: Error | undefined, callback: (error?: Error) => void): void;
    /**
     Consume all remaining items of the iterator into an array that will be returned asynchronously.
     @param {object} [options] Settings for array creation
     @param {integer} [options.limit] The maximum number of items to place in the array.
     */
    toArray(options?: {
        limit?: number;
    }): Promise<T[]>;
}
/**
  An iterator that enumerates integers in a certain range.
  @extends module:asynciterator.AsyncIterator
*/
export declare class IntegerIterator extends AsyncIterator<number> {
    private _next;
    private _step;
    private _last;
    /**
      Creates a new `IntegerIterator`.
      @param {object} [options] Settings of the iterator
      @param {integer} [options.start=0] The first number to emit
      @param {integer} [options.end=Infinity] The last number to emit
      @param {integer} [options.step=1] The increment between two numbers
    */
    constructor({ start, step, end }?: {
        start?: number;
        step?: number;
        end?: number;
    });
    read(): number | null;
    protected _toStringDetails(): string;
}
/**
 * A synchronous mapping function from one element to another.
 * A return value of `null` means that nothing should be emitted for a particular item.
 */
export declare type MapFunction<S, D = S> = (item: S) => D | null;
/** Function that maps an element to itself. */
export declare function identity<S>(item: S): typeof item;
/** Key indicating the current consumer of a source. */
export declare const DESTINATION: unique symbol;
/**
 An iterator that synchronously transforms every item from its source
 by applying a mapping function.
 @extends module:asynciterator.AsyncIterator
*/
export declare class MappingIterator<S, D = S> extends AsyncIterator<D> {
    protected readonly _map: MapFunction<S, D>;
    protected readonly _source: InternalSource<S>;
    protected readonly _destroySource: boolean;
    /**
     * Applies the given mapping to the source iterator.
     */
    constructor(source: AsyncIterator<S>, map?: MapFunction<S, D>, options?: SourcedIteratorOptions);
    read(): D | null;
    protected _end(destroy: boolean): void;
}
/**
  An iterator that maintains an internal buffer of items.
  This class serves as a base class for other iterators
  with a typically complex item generation process.
  @extends module:asynciterator.AsyncIterator
*/
export declare class BufferedIterator<T> extends AsyncIterator<T> {
    private _buffer;
    private _maxBufferSize;
    protected _reading: boolean;
    protected _pushedCount: number;
    protected _sourceStarted: boolean;
    /**
      Creates a new `BufferedIterator`.
      @param {object} [options] Settings of the iterator
      @param {integer} [options.maxBufferSize=4] The number of items to preload in the internal buffer
      @param {boolean} [options.autoStart=true] Whether buffering starts directly after construction
    */
    constructor({ maxBufferSize, autoStart }?: BufferedIteratorOptions);
    /**
      The maximum number of items to preload in the internal buffer.
      A `BufferedIterator` tries to fill its buffer as far as possible.
      Set to `Infinity` to fully drain the source.
      @type number
    */
    get maxBufferSize(): number;
    set maxBufferSize(maxBufferSize: number);
    /**
      Initializing the iterator by calling {@link BufferedIterator#_begin}
      and changing state from INIT to OPEN.
      @protected
      @param {boolean} autoStart Whether reading of items should immediately start after OPEN.
    */
    protected _init(autoStart: boolean): void;
    /**
      Writes beginning items and opens iterator resources.
      Should never be called before {@link BufferedIterator#_init};
      typically, `_init` is responsible for calling `_begin`.
      @protected
      @param {function} done To be called when initialization is complete
    */
    protected _begin(done: () => void): void;
    /**
      Tries to read the next item from the iterator.
      If the buffer is empty,
      this method calls {@link BufferedIterator#_read} to fetch items.
      @returns {object?} The next item, or `null` if none is available
    */
    read(): T | null;
    /**
      Tries to generate the given number of items.
      Implementers should add `count` items through {@link BufferedIterator#_push}.
      @protected
      @param {integer} count The number of items to generate
      @param {function} done To be called when reading is complete
    */
    protected _read(count: number, done: () => void): void;
    /**
      Adds an item to the internal buffer.
      @protected
      @param {object} item The item to add
      @emits module:asynciterator.AsyncIterator.readable
    */
    protected _push(item: T): void;
    /**
      Fills the internal buffer until `this._maxBufferSize` items are present.
      This method calls {@link BufferedIterator#_read} to fetch items.
      @protected
      @emits module:asynciterator.AsyncIterator.readable
    */
    protected _fillBuffer(): void;
    /**
      Schedules `_fillBuffer` asynchronously.
    */
    protected _fillBufferAsync(): void;
    /**
      Stops the iterator from generating new items
      after a possible pending read operation has finished.
      Already generated, pending, or terminating items can still be emitted.
      After this, the iterator will end asynchronously.
      @emits module:asynciterator.AsyncIterator.end
    */
    close(): void;
    /**
      Stops the iterator from generating new items,
      switching from `CLOSING` state into `CLOSED` state.
      @protected
      @emits module:asynciterator.AsyncIterator.end
    */
    protected _completeClose(): void;
    protected _destroy(cause: Error | undefined, callback: (error?: Error) => void): void;
    /**
      Writes terminating items and closes iterator resources.
      Should never be called before {@link BufferedIterator#close};
      typically, `close` is responsible for calling `_flush`.
      @protected
      @param {function} done To be called when termination is complete
    */
    protected _flush(done: () => void): void;
    /**
      Generates details for a textual representation of the iterator.
      @protected
     */
    protected _toStringDetails(): string;
}
/**
  An iterator that generates items based on a source iterator.
  This class serves as a base class for other iterators.
  @extends module:asynciterator.BufferedIterator
*/
export declare class TransformIterator<S, D = S> extends BufferedIterator<D> {
    protected _source?: InternalSource<S>;
    protected _createSource?: (() => MaybePromise<AsyncIterator<S>>) | null;
    protected _destroySource: boolean;
    protected _optional: boolean;
    protected _boundPush: (item: D) => void;
    /**
      Creates a new `TransformIterator`.
      @param {module:asynciterator.AsyncIterator|Readable} [source] The source this iterator generates items from
      @param {object} [options] Settings of the iterator
      @param {integer} [options.maxBufferSize=4] The maximum number of items to keep in the buffer
      @param {boolean} [options.autoStart=true] Whether buffering starts directly after construction
      @param {boolean} [options.optional=false] If transforming is optional, the original item is pushed when its transformation yields no items
      @param {boolean} [options.destroySource=true] Whether the source should be destroyed when this transformed iterator is closed or destroyed
      @param {module:asynciterator.AsyncIterator} [options.source] The source this iterator generates items from
    */
    constructor(source?: SourceExpression<S>, options?: TransformIteratorOptions<S>);
    /**
      The source this iterator generates items from.
      @type module:asynciterator.AsyncIterator
    */
    get source(): AsyncIterator<S> | undefined;
    set source(value: AsyncIterator<S> | undefined);
    /**
      Initializes a source that was set through a promise
      @protected
    */
    protected _loadSourceAsync(): void;
    /**
      Validates whether the given iterator can be used as a source.
      @protected
      @param {object} source The source to validate
      @param {boolean} allowDestination Whether the source can already have a destination
    */
    protected _validateSource(source?: AsyncIterator<S>, allowDestination?: boolean): InternalSource<S>;
    /**
      Tries to read transformed items.
    */
    protected _read(count: number, done: () => void): void;
    /**
      Reads a transforms an item
    */
    protected _readAndTransform(next: () => void, done: () => void): void;
    /**
      Tries to transform the item;
      if the transformation yields no items, pushes the original item.
    */
    protected _optionalTransform(item: S, done: () => void): void;
    /**
      Generates items based on the item from the source.
      Implementers should add items through {@link BufferedIterator#_push}.
      The default implementation pushes the source item as-is.
      @protected
      @param {object} item The last read item from the source
      @param {function} done To be called when reading is complete
      @param {function} push A callback to push zero or more transformation results.
    */
    protected _transform(item: S, done: () => void, push: (i: D) => void): void;
    /**
      Closes the iterator when pending items are transformed.
      @protected
    */
    protected _closeWhenDone(): void;
    protected _end(destroy: boolean): void;
}
/**
  An iterator that generates items based on a source iterator
  and simple transformation steps passed as arguments.
  @extends module:asynciterator.TransformIterator
*/
export declare class SimpleTransformIterator<S, D = S> extends TransformIterator<S, D> {
    private _offset;
    private _limit;
    private _prepender?;
    private _appender?;
    private _filter;
    private _map?;
    /**
      Creates a new `SimpleTransformIterator`.
      @param {module:asynciterator.AsyncIterator|Readable} [source] The source this iterator generates items from
      @param {object|Function} [options] Settings of the iterator, or the transformation function
      @param {integer} [options.maxbufferSize=4] The maximum number of items to keep in the buffer
      @param {boolean} [options.autoStart=true] Whether buffering starts directly after construction
      @param {module:asynciterator.AsyncIterator} [options.source] The source this iterator generates items from
      @param {integer} [options.offset] The number of items to skip
      @param {integer} [options.limit] The maximum number of items
      @param {Function} [options.filter] A function to synchronously filter items from the source
      @param {Function} [options.map] A function to synchronously transform items from the source
      @param {Function} [options.transform] A function to asynchronously transform items from the source
      @param {boolean} [options.optional=false] If transforming is optional, the original item is pushed when its mapping yields `null` or its transformation yields no items
      @param {Array|module:asynciterator.AsyncIterator} [options.prepend] Items to insert before the source items
      @param {Array|module:asynciterator.AsyncIterator} [options.append]  Items to insert after the source items
    */
    constructor(source?: SourceExpression<S>, options?: TransformOptions<S, D> | (TransformOptions<S, D> & ((item: S, done: () => void) => void)));
    protected _read(count: number, done: () => void): void;
    protected _readAndTransformSimple(count: number, next: () => void, done: () => void): void;
    protected _begin(done: () => void): void;
    protected _flush(done: () => void): void;
    protected _insert(inserter: AsyncIterator<D> | undefined, done: () => void): void;
}
/**
  An iterator that generates items by transforming each item of a source
  with a different iterator.
  @extends module:asynciterator.TransformIterator
*/
export declare class MultiTransformIterator<S, D = S> extends TransformIterator<S, D> {
    private _transformerQueue;
    /**
     Creates a new `MultiTransformIterator`.
     @param {module:asynciterator.AsyncIterator|Readable} [source] The source this iterator generates items from
     @param {object|Function} [options] Settings of the iterator, or the transformation function
     @param {integer} [options.maxbufferSize=4] The maximum number of items to keep in the buffer
     @param {boolean} [options.autoStart=true] Whether buffering starts directly after construction
     @param {module:asynciterator.AsyncIterator} [options.source] The source this iterator generates items from
     @param {integer} [options.offset] The number of items to skip
     @param {integer} [options.limit] The maximum number of items
     @param {Function} [options.filter] A function to synchronously filter items from the source
     @param {Function} [options.map] A function to synchronously transform items from the source
     @param {Function} [options.transform] A function to asynchronously transform items from the source
     @param {boolean} [options.optional=false] If transforming is optional, the original item is pushed when its mapping yields `null` or its transformation yields no items
     @param {Function} [options.multiTransform] A function to asynchronously transform items to iterators from the source
     @param {Array|module:asynciterator.AsyncIterator} [options.prepend] Items to insert before the source items
     @param {Array|module:asynciterator.AsyncIterator} [options.append]  Items to insert after the source items
     */
    constructor(source: AsyncIterator<S>, options?: MultiTransformOptions<S, D> | (MultiTransformOptions<S, D> & ((item: S) => AsyncIterator<D>)));
    protected _read(count: number, done: () => void): void;
    /**
      Creates a transformer for the given item.
      @param {object} item The last read item from the source
      @returns {module:asynciterator.AsyncIterator} An iterator that transforms the given item
    */
    protected _createTransformer(item: S): AsyncIterator<D>;
    protected _closeWhenDone(): void;
    protected _end(destroy: boolean): void;
}
/**
  An iterator that generates items by reading from multiple other iterators.
  @extends module:asynciterator.BufferedIterator
*/
export declare class UnionIterator<T> extends BufferedIterator<T> {
    private _sources;
    private _pending?;
    private _currentSource;
    protected _destroySources: boolean;
    /**
      Creates a new `UnionIterator`.
      @param {module:asynciterator.AsyncIterator|Array} [sources] The sources to read from
      @param {object} [options] Settings of the iterator
      @param {boolean} [options.destroySource=true] Whether the sources should be destroyed when transformed iterator is closed or destroyed
    */
    constructor(sources: AsyncIteratorOrArray<AsyncIterator<T>> | AsyncIteratorOrArray<Promise<AsyncIterator<T>>> | AsyncIteratorOrArray<MaybePromise<AsyncIterator<T>>>, options?: BufferedIteratorOptions & {
        destroySources?: boolean;
    });
    protected _loadSources(): void;
    protected _addSource(source: MaybePromise<InternalSource<T>>): void;
    protected _removeEmptySources(): void;
    protected _read(count: number, done: () => void): void;
    protected _end(destroy?: boolean): void;
}
/**
  An iterator that copies items from another iterator.
  @extends module:asynciterator.TransformIterator
*/
export declare class ClonedIterator<T> extends TransformIterator<T> {
    private _readPosition;
    /**
      Creates a new `ClonedIterator`.
      @param {module:asynciterator.AsyncIterator|Readable} [source] The source this iterator copies items from
    */
    constructor(source: AsyncIterator<T>);
    protected _init(): void;
    close(): void;
    get source(): AsyncIterator<T> | undefined;
    set source(value: AsyncIterator<T> | undefined);
    /**
      Validates whether the given iterator can be used as a source.
      @protected
      @param {object} source The source to validate
      @param {boolean} allowDestination Whether the source can already have a destination
    */
    protected _validateSource(source?: AsyncIterator<T>, allowDestination?: boolean): InternalSource<T>;
    getProperty<P>(propertyName: string, callback?: (value: P) => void): P | undefined;
    protected _getSourceProperty<P>(propertyName: string, callback: (value: P) => void): void;
    getProperties(): {
        [name: string]: any;
    };
    protected _toStringDetails(): string;
    read(): T | null;
    protected _end(destroy: boolean): void;
}
/**
 * An iterator that takes a variety of iterable objects as a source.
 */
export declare class WrappingIterator<T> extends AsyncIterator<T> {
    protected _source: InternalSource<T> | null;
    protected _destroySource: boolean;
    constructor(source?: MaybePromise<IterableSource<T>>, opts?: SourcedIteratorOptions);
    set source(value: IterableSource<T>);
    read(): T | null;
    protected _end(destroy?: boolean): void;
}
/**
  Creates an iterator that wraps around a given iterator or readable stream.
  Use this to convert an iterator-like object into a full-featured AsyncIterator.
  After this operation, only read the returned iterator instead of the given one.
  @function
  @param [source] The source this iterator generates items from
  @param {object} [options] Settings of the iterator
  @returns {module:asynciterator.AsyncIterator} A new iterator with the items from the given iterator
*/
export declare function wrap<T>(source?: MaybePromise<IterableSource<T>> | null, options?: TransformIteratorOptions<T>): AsyncIterator<T>;
/**
  Creates an empty iterator.
 */
export declare function empty<T>(): AsyncIterator<T>;
/**
  Creates an iterator with a single item.
  @param {object} item the item
 */
export declare function single<T>(item: T): AsyncIterator<T>;
/**
  Creates an iterator for the given array.
  @param {Array} items the items
 */
export declare function fromArray<T>(items: Iterable<T>): AsyncIterator<T>;
/**
 Creates an iterator for the given Iterator.
 @param {Iterable} source the iterator
 */
export declare function fromIterator<T>(source: Iterable<T> | Iterator<T>): AsyncIterator<T>;
/**
 Creates an iterator for the given Iterable.
 @param {Iterable} source the iterable
 */
export declare function fromIterable<T>(source: Iterable<T> | Iterator<T>): AsyncIterator<T>;
/**
  Creates an iterator containing all items from the given iterators.
  @param {Array} items the items
 */
export declare function union<T>(sources: AsyncIteratorOrArray<AsyncIterator<T>> | AsyncIteratorOrArray<Promise<AsyncIterator<T>>> | AsyncIteratorOrArray<MaybePromise<AsyncIterator<T>>>): UnionIterator<T>;
/**
  Creates an iterator of integers for the given numeric range.
  @param {Array} items the items
 */
export declare function range(start: number, end: number, step?: number): IntegerIterator;
export declare type IterableSource<T> = T[] | AsyncIterator<T> | EventEmitter | Iterator<T> | Iterable<T>;
export interface SourcedIteratorOptions {
    destroySource?: boolean;
}
export interface BufferedIteratorOptions {
    maxBufferSize?: number;
    autoStart?: boolean;
}
export interface TransformIteratorOptions<S> extends SourcedIteratorOptions, BufferedIteratorOptions {
    source?: SourceExpression<S>;
    optional?: boolean;
}
export interface TransformOptions<S, D> extends TransformIteratorOptions<S> {
    offset?: number;
    limit?: number;
    prepend?: AsyncIteratorOrArray<D>;
    append?: AsyncIteratorOrArray<D>;
    filter?: (item: S) => boolean;
    map?: (item: S) => D;
    transform?: (item: S, done: () => void, push: (i: D) => void) => void;
}
export interface MultiTransformOptions<S, D> extends TransformOptions<S, D> {
    multiTransform?: (item: S) => AsyncIterator<D>;
}
/**
 * Copy of the EcmaScript AsyncIterator interface, which we can not use directly due to the name conflict.
 */
interface ESAsyncIterator<T> {
    next(value?: any): Promise<IteratorResult<T>>;
}
declare type MaybePromise<T> = T | Promise<T>;
declare type AsyncIteratorOrArray<T> = T[] | AsyncIterator<T>;
declare type SourceExpression<T> = MaybePromise<AsyncIterator<T>> | (() => MaybePromise<AsyncIterator<T>>);
declare type InternalSource<T> = AsyncIterator<T> & {
    [DESTINATION]?: AsyncIterator<any>;
};
export declare function isFunction(object: any): object is Function;
export declare function isEventEmitter(object: any): object is EventEmitter;
export declare function isPromise<T>(object: any): object is Promise<T>;
export declare function isSourceExpression<T>(object: any): object is SourceExpression<T>;
export declare function isIterable<T>(object: {
    [key: string]: any;
}): object is Iterable<T>;
export declare function isIterator<T>(object: {
    [key: string]: any;
}): object is Iterator<T>;