@shutterstock/p-map-iterable 1.1.0 → 1.1.2

package/dist/src/iterable-queue-mapper-simple.d.ts

@@ -1,29 +1,53 @@
-import { Mapper } from './iterable-mapper';
+import { IterableMapperOptions, Mapper } from './iterable-mapper';
 type Errors<T> = {
     item: T;
     error: string | {
         [key: string]: any;
     } | Error;
 }[];
+/**
+ * Options for IterableQueueMapperSimple
+ */
+export type IterableQueueMapperSimpleOptions = Pick<IterableMapperOptions, 'concurrency'>;
 /**
  * Accepts queue items via `enqueue` and calls the `mapper` on them
- * with specified concurrency, storing the
- * `mapper` result in a queue of specified max size, before
- * being iterated / read by the caller.  The `enqueue` method will block if
- * the queue is full, until an item is read.
+ * with specified `concurrency`, discards the results, and accumulates
+ * exceptions in the `errors` property.  When empty, `await enqueue()`
+ * will return immediately, but when `concurrency` items are in progress,
+ * `await enqueue()` will block until a slot is available to accept the item.
  *
  * @remarks
  *
- * Note: the name is somewhat of a misnomer as this wraps `IterableQueueMapper`
- * but is not itself an `Iterable`.
+ * ### Typical Use Case
+ * - Pushing items to an async I/O destination
+ * - In the simple sequential (`concurrency: 1`) case, allows 1 item to be flushed async while caller prepares next item
+ * - Results of the flushed items are not needed in a subsequent step (if they are, use `IterableQueueMapper`)
+ *
+ * ### Error Handling
+ *   The mapper should ideally handle all errors internally to enable error handling
+ *   closest to where they occur. However, if errors do escape the mapper:
+ *   - Processing continues despite errors
+ *   - All errors are collected in the `errors` property
+ *   - Errors can be checked/handled during processing via the `errors` property
+ *
+ *   Key Differences from `IterableQueueMapper`:
+ *   - `maxUnread` defaults to equal `concurrency` (simplifying queue management)
+ *   - Results are automatically iterated and discarded (all work should happen in mapper)
+ *   - Errors are collected rather than thrown (available via errors property)
  *
- * Accepts items for mapping in the background, discards the results,
- * but accumulates exceptions in the `errors` property.
+ * ### Usage
+ * - Items are added to the queue via the `await enqueue()` method
+ * - Check `errors` property to see if any errors occurred, stop if desired
+ * - IMPORTANT: `await enqueue()` method will block until a slot is available, if queue is full
+ * - IMPORTANT: Always `await onIdle()` to ensure all items are processed
  *
- * Allows up to `concurrency` mappers to be in progress before
- * `enqueue` will block until a mapper completes.
+ * Note: the name is somewhat of a misnomer as this wraps `IterableQueueMapper`
+ * but is not itself an `Iterable`.
  *
  * @category Enqueue Input
+ *
+ * @see {@link IterableQueueMapper} for related class with more configuration options
+ * @see {@link IterableMapper} for underlying mapper implementation and examples of combined usage
  */
 export declare class IterableQueueMapperSimple<Element> {
     private readonly _writer;
@@ -32,26 +56,17 @@ export declare class IterableQueueMapperSimple<Element> {
     private readonly _mapper;
     private _isIdle;
     /**
-     * Create a new `IterableQueueMapperSimple`
+     * Create a new `IterableQueueMapperSimple`, which uses `IterableQueueMapper` underneath, but
+     * automatically iterates and discards results as they complete.
      *
-     * @param mapper Function which is called for every item in `input`.
-     *    Expected to return a `Promise` or value.
-     *
-     *    The `mapper` *should* handle all errors and not allow an error to be thrown
-     *    out of the `mapper` function as this enables the best handling of errors
-     *    closest to the time that they occur.
-     *
-     *    If the `mapper` function does allow an error to be thrown then the
-     *    errors will be accumulated in the `errors` property.
+     * @param mapper Function called for every enqueued item. Returns a `Promise` or value.
      * @param options IterableQueueMapperSimple options
+     *
+     * @see {@link IterableQueueMapperSimple} for full class documentation
+     * @see {@link IterableQueueMapper} for related class with more configuration options
+     * @see {@link IterableMapper} for underlying mapper implementation and examples of combined usage
      */
-    constructor(mapper: Mapper<Element, void>, options?: {
-        /**
-         * Number of items to accept for mapping before requiring the caller to wait for one to complete.
-         * @default 4
-         */
-        concurrency?: number;
-    });
+    constructor(mapper: Mapper<Element, void>, options?: IterableQueueMapperSimpleOptions);
     private discardResults;
     private worker;
     /**
@@ -70,7 +85,7 @@ export declare class IterableQueueMapperSimple<Element> {
     /**
      * Accept a request for sending in the background if a concurrency slot is available.
      * Else, do not return until a concurrency slot is freed up.
-     * This provides concurrency background writes with back pressure to prevent
+     * This provides concurrency background writes with backpressure to prevent
      * the caller from getting too far ahead.
      *
      * MUST await `onIdle` for background `mappers`s to finish

package/dist/src/iterable-queue-mapper-simple.js

@@ -5,38 +5,55 @@ const iterable_queue_mapper_1 = require("./iterable-queue-mapper");
 const NoResult = Symbol('noresult');
 /**
  * Accepts queue items via `enqueue` and calls the `mapper` on them
- * with specified concurrency, storing the
- * `mapper` result in a queue of specified max size, before
- * being iterated / read by the caller.  The `enqueue` method will block if
- * the queue is full, until an item is read.
+ * with specified `concurrency`, discards the results, and accumulates
+ * exceptions in the `errors` property.  When empty, `await enqueue()`
+ * will return immediately, but when `concurrency` items are in progress,
+ * `await enqueue()` will block until a slot is available to accept the item.
  *
  * @remarks
  *
- * Note: the name is somewhat of a misnomer as this wraps `IterableQueueMapper`
- * but is not itself an `Iterable`.
+ * ### Typical Use Case
+ * - Pushing items to an async I/O destination
+ * - In the simple sequential (`concurrency: 1`) case, allows 1 item to be flushed async while caller prepares next item
+ * - Results of the flushed items are not needed in a subsequent step (if they are, use `IterableQueueMapper`)
+ *
+ * ### Error Handling
+ *   The mapper should ideally handle all errors internally to enable error handling
+ *   closest to where they occur. However, if errors do escape the mapper:
+ *   - Processing continues despite errors
+ *   - All errors are collected in the `errors` property
+ *   - Errors can be checked/handled during processing via the `errors` property
  *
- * Accepts items for mapping in the background, discards the results,
- * but accumulates exceptions in the `errors` property.
+ *   Key Differences from `IterableQueueMapper`:
+ *   - `maxUnread` defaults to equal `concurrency` (simplifying queue management)
+ *   - Results are automatically iterated and discarded (all work should happen in mapper)
+ *   - Errors are collected rather than thrown (available via errors property)
  *
- * Allows up to `concurrency` mappers to be in progress before
- * `enqueue` will block until a mapper completes.
+ * ### Usage
+ * - Items are added to the queue via the `await enqueue()` method
+ * - Check `errors` property to see if any errors occurred, stop if desired
+ * - IMPORTANT: `await enqueue()` method will block until a slot is available, if queue is full
+ * - IMPORTANT: Always `await onIdle()` to ensure all items are processed
+ *
+ * Note: the name is somewhat of a misnomer as this wraps `IterableQueueMapper`
+ * but is not itself an `Iterable`.
  *
  * @category Enqueue Input
+ *
+ * @see {@link IterableQueueMapper} for related class with more configuration options
+ * @see {@link IterableMapper} for underlying mapper implementation and examples of combined usage
  */
 class IterableQueueMapperSimple {
     /**
-     * Create a new `IterableQueueMapperSimple`
-     *
-     * @param mapper Function which is called for every item in `input`.
-     *    Expected to return a `Promise` or value.
+     * Create a new `IterableQueueMapperSimple`, which uses `IterableQueueMapper` underneath, but
+     * automatically iterates and discards results as they complete.
      *
-     *    The `mapper` *should* handle all errors and not allow an error to be thrown
-     *    out of the `mapper` function as this enables the best handling of errors
-     *    closest to the time that they occur.
-     *
-     *    If the `mapper` function does allow an error to be thrown then the
-     *    errors will be accumulated in the `errors` property.
+     * @param mapper Function called for every enqueued item. Returns a `Promise` or value.
      * @param options IterableQueueMapperSimple options
+     *
+     * @see {@link IterableQueueMapperSimple} for full class documentation
+     * @see {@link IterableQueueMapper} for related class with more configuration options
+     * @see {@link IterableMapper} for underlying mapper implementation and examples of combined usage
      */
     constructor(mapper, options = {}) {
         this._errors = [];
@@ -85,7 +102,7 @@ class IterableQueueMapperSimple {
     /**
      * Accept a request for sending in the background if a concurrency slot is available.
      * Else, do not return until a concurrency slot is freed up.
-     * This provides concurrency background writes with back pressure to prevent
+     * This provides concurrency background writes with backpressure to prevent
      * the caller from getting too far ahead.
      *
      * MUST await `onIdle` for background `mappers`s to finish

package/dist/src/iterable-queue-mapper-simple.js.map

@@ -1 +1 @@
-{"version":3,"file":"iterable-queue-mapper-simple.js","sourceRoot":"","sources":["../../src/iterable-queue-mapper-simple.ts"],"names":[],"mappings":";;;AACA,mEAA8D;AAK9D,MAAM,QAAQ,GAAG,MAAM,CAAC,UAAU,CAAC,CAAC;AAEpC;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAa,yBAAyB;IAOpC;;;;;;;;;;;;;OAaG;IACH,YACE,MAA6B,EAC7B,UAMI,EAAE;QA3BS,YAAO,GAAoB,EAAE,CAAC;QAGvC,YAAO,GAAG,KAAK,CAAC;QA0BtB,MAAM,EAAE,WAAW,GAAG,CAAC,EAAE,GAAG,OAAO,CAAC;QAEpC,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC;QACtB,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACrC,IAAI,CAAC,OAAO,GAAG,IAAI,2CAAmB,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,WAAW,EAAE,SAAS,EAAE,WAAW,EAAE,CAAC,CAAC;QAE7F,6BAA6B;QAC7B,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,cAAc,EAAE,CAAC;IACrC,CAAC;IAEO,KAAK,CAAC,cAAc;QAC1B,6DAA6D;QAC7D,IAAI,IAAI,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC;QACrC,OAAO,IAAI,CAAC,IAAI,KAAK,IAAI,EAAE;YACzB,+BAA+B;YAC/B,oEAAoE;YACpE,IAAI,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC;SAClC;IACH,CAAC;IAEO,KAAK,CAAC,MAAM,CAAC,IAAa,EAAE,KAAa;QAC/C,IAAI;YACF,MAAM,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;YAChC,8DAA8D;SAC/D;QAAC,OAAO,KAAU,EAAE;YACnB,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;SACpC;QACD,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED;;;;;;;;;;;OAWG;IACH,IAAW,MAAM;QACf,OAAO,IAAI,CAAC,OAAO,CAAC;IACtB,CAAC;IAED;;;;;;;;OAQG;IACI,KAAK,CAAC,OAAO,CAAC,IAAa;QAChC,4EAA4E;QAC5E,MAAM,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IACnC,CAAC;IAED;;;OAGG;IACI,KAAK,CAAC,MAAM;QACjB,IAAI,IAAI,CAAC,OAAO;YAAE,OAAO;QAEzB,4CAA4C;QAC5C,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC;QAEpB,MAAM,IAAI,CAAC,KAAK,CAAC;QAEjB,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;IACtB,CAAC;IAED;;;;OAIG;IACH,IAAW,MAAM;QACf,OAAO,IAAI,CAAC,OAAO,CAAC;IACtB,CAAC;CACF;AAlHD,8DAkHC"}
+{"version":3,"file":"iterable-queue-mapper-simple.js","sourceRoot":"","sources":["../../src/iterable-queue-mapper-simple.ts"],"names":[],"mappings":";;;AACA,mEAA8D;AAK9D,MAAM,QAAQ,GAAG,MAAM,CAAC,UAAU,CAAC,CAAC;AAOpC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,MAAa,yBAAyB;IAOpC;;;;;;;;;;OAUG;IACH,YAAY,MAA6B,EAAE,UAA4C,EAAE;QAhBxE,YAAO,GAAoB,EAAE,CAAC;QAGvC,YAAO,GAAG,KAAK,CAAC;QActB,MAAM,EAAE,WAAW,GAAG,CAAC,EAAE,GAAG,OAAO,CAAC;QAEpC,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC;QACtB,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACrC,IAAI,CAAC,OAAO,GAAG,IAAI,2CAAmB,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,WAAW,EAAE,SAAS,EAAE,WAAW,EAAE,CAAC,CAAC;QAE7F,6BAA6B;QAC7B,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,cAAc,EAAE,CAAC;IACrC,CAAC;IAEO,KAAK,CAAC,cAAc;QAC1B,6DAA6D;QAC7D,IAAI,IAAI,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC;QACrC,OAAO,IAAI,CAAC,IAAI,KAAK,IAAI,EAAE;YACzB,+BAA+B;YAC/B,oEAAoE;YACpE,IAAI,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC;SAClC;IACH,CAAC;IAEO,KAAK,CAAC,MAAM,CAAC,IAAa,EAAE,KAAa;QAC/C,IAAI;YACF,MAAM,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;YAChC,8DAA8D;SAC/D;QAAC,OAAO,KAAU,EAAE;YACnB,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;SACpC;QACD,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED;;;;;;;;;;;OAWG;IACH,IAAW,MAAM;QACf,OAAO,IAAI,CAAC,OAAO,CAAC;IACtB,CAAC;IAED;;;;;;;;OAQG;IACI,KAAK,CAAC,OAAO,CAAC,IAAa;QAChC,4EAA4E;QAC5E,MAAM,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IACnC,CAAC;IAED;;;OAGG;IACI,KAAK,CAAC,MAAM;QACjB,IAAI,IAAI,CAAC,OAAO;YAAE,OAAO;QAEzB,4CAA4C;QAC5C,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC;QAEpB,MAAM,IAAI,CAAC,KAAK,CAAC;QAEjB,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;IACtB,CAAC;IAED;;;;OAIG;IACH,IAAW,MAAM;QACf,OAAO,IAAI,CAAC,OAAO,CAAC;IACtB,CAAC;CACF;AAtGD,8DAsGC"}

package/dist/src/iterable-queue-mapper.d.ts

@@ -1,77 +1,57 @@
-import { Mapper } from './iterable-mapper';
-export interface IterableQueueMapperOptions {
-    /**
-     * Number of concurrently pending promises returned by `mapper`.
-     *
-     * Must be an integer from 1 and up or `Infinity`, must be <= `maxUnread`.
-     *
-     * @default 4
-     */
-    readonly concurrency?: number;
-    /**
-     * Number of pending unread iterable items.
-     *
-     * Must be an integer from 1 and up or `Infinity`, must be >= `concurrency`.
-     *
-     * @default 8
-     */
-    readonly maxUnread?: number;
-    /**
-     * When set to `false`, instead of stopping when a promise rejects, it will wait for all the promises to settle and then reject with an [aggregated error](https://github.com/sindresorhus/aggregate-error) containing all the errors from the rejected promises.
-     *
-     * @default true
-     */
-    readonly stopOnMapperError?: boolean;
-}
+import { IterableMapperOptions, Mapper } from './iterable-mapper';
+/**
+ * Options for IterableQueueMapper
+ */
+export type IterableQueueMapperOptions = IterableMapperOptions;
 /**
  * Accepts queue items via `enqueue` and calls the `mapper` on them
- * with specified concurrency, storing the
- * `mapper` result in a queue of specified max size, before
- * being iterated / read by the caller.  The `enqueue` method will block if
- * the queue is full, until an item is read.
+ * with specified `concurrency`, storing the `mapper` result in a queue
+ * of `maxUnread` size, before being iterated / read by the caller.
+ * The `enqueue` method will block if the queue is full, until an item is read.
  *
  * @remarks
  *
- * This allows performing a concurrent mapping with
- * back pressure for items added after queue creation
- * via a method call.
+ * ### Typical Use Case
+ * - Pushing items to an async I/O destination
+ * - In the simple sequential (`concurrency: 1`) case, allows 1 item to be flushed async while caller prepares next item
+ * - Results of the flushed items are needed in a subsequent step (if they are not, use `IterableQueueMapperSimple`)
+ * - Prevents the producer from racing ahead of the consumer if `maxUnread` is reached
+ *
+ * ### Error Handling
+ *   The mapper should ideally handle all errors internally to enable error handling
+ *   closest to where they occur. However, if errors do escape the mapper:
  *
- * Because items are added via a method call it is possible to
- * chain an `IterableMapper` that prefetches files and processes them,
- * with an `IterableQueueMapper` that processes the results of the
- * `mapper` function of the `IterableMapper`.
+ *   When `stopOnMapperError` is true (default):
+ *   - First error immediately stops processing
+ *   - Error is thrown from the `AsyncIterator`'s next() call
  *
- * Typical use case is for a `background uploader` that prevents
- * the producer from racing ahead of the upload process, consuming
- * too much memory or disk space. As items are ready for upload
- * they are added to the queue with the `enqueue` method, which is
- * `await`ed by the caller.  If the queue has room then `enqueue`
- * will return immediately, otherwise it will block until there is room.
+ *   When `stopOnMapperError` is false:
+ *   - Processing continues despite errors
+ *   - All errors are collected and thrown together
+ *   - Errors are thrown as `AggregateError` after all items complete
+ *
+ * ### Usage
+ * - Items are added to the queue via the `await enqueue()` method
+ * - IMPORTANT: `await enqueue()` method will block until a slot is available, if queue is full
+ * - Call `done()` when no more items will be enqueued
+ * - IMPORTANT: Always `await onIdle()` to ensure all items are processed
  *
  * @category Enqueue Input
+ *
+ * @see {@link IterableMapper} for underlying mapper implementation and examples of combined usage
  */
 export declare class IterableQueueMapper<Element, NewElement> implements AsyncIterable<NewElement> {
     private _iterableMapper;
     private _sourceIterable;
     /**
-     * Create a new `IterableQueueMapper`
-     *
-     * @param mapper Function which is called for every item in `input`.
-     *    Expected to return a `Promise` or value.
+     * Create a new `IterableQueueMapper`, which uses `IterableMapper` underneath, and exposes a
+     * queue interface for adding items that are not exposed via an iterator.
      *
-     *    The `mapper` *should* handle all errors and not allow an error to be thrown
-     *    out of the `mapper` function as this enables the best handling of errors
-     *    closest to the time that they occur.
-     *
-     *    If the `mapper` function does allow an error to be thrown then the
-     *   `stopOnMapperError` option controls the behavior:
-     *      - `stopOnMapperError`: `true` - will throw the error
-     *        out of `next` or the `AsyncIterator` returned from `[Symbol.asyncIterator]`
-     *        and stop processing.
-     *     - `stopOnMapperError`: `false` - will continue processing
-     *        and accumulate the errors to be thrown from `next` or the `AsyncIterator`
-     *        returned from `[Symbol.asyncIterator]` when all items have been processed.
+     * @param mapper Function called for every enqueued item. Returns a `Promise` or value.
      * @param options IterableQueueMapper options
+     *
+     * @see {@link IterableQueueMapper} for full class documentation
+     * @see {@link IterableMapper} for underlying mapper implementation and examples of combined usage
      */
     constructor(mapper: Mapper<Element, NewElement>, options?: IterableQueueMapperOptions);
     [Symbol.asyncIterator](): AsyncIterator<NewElement>;

package/dist/src/iterable-queue-mapper.js

@@ -8,51 +8,51 @@ const iterable_mapper_1 = require("./iterable-mapper");
 const iterable_queue_1 = require("./iterable-queue");
 /**
  * Accepts queue items via `enqueue` and calls the `mapper` on them
- * with specified concurrency, storing the
- * `mapper` result in a queue of specified max size, before
- * being iterated / read by the caller.  The `enqueue` method will block if
- * the queue is full, until an item is read.
+ * with specified `concurrency`, storing the `mapper` result in a queue
+ * of `maxUnread` size, before being iterated / read by the caller.
+ * The `enqueue` method will block if the queue is full, until an item is read.
  *
  * @remarks
  *
- * This allows performing a concurrent mapping with
- * back pressure for items added after queue creation
- * via a method call.
+ * ### Typical Use Case
+ * - Pushing items to an async I/O destination
+ * - In the simple sequential (`concurrency: 1`) case, allows 1 item to be flushed async while caller prepares next item
+ * - Results of the flushed items are needed in a subsequent step (if they are not, use `IterableQueueMapperSimple`)
+ * - Prevents the producer from racing ahead of the consumer if `maxUnread` is reached
  *
- * Because items are added via a method call it is possible to
- * chain an `IterableMapper` that prefetches files and processes them,
- * with an `IterableQueueMapper` that processes the results of the
- * `mapper` function of the `IterableMapper`.
+ * ### Error Handling
+ *   The mapper should ideally handle all errors internally to enable error handling
+ *   closest to where they occur. However, if errors do escape the mapper:
  *
- * Typical use case is for a `background uploader` that prevents
- * the producer from racing ahead of the upload process, consuming
- * too much memory or disk space. As items are ready for upload
- * they are added to the queue with the `enqueue` method, which is
- * `await`ed by the caller.  If the queue has room then `enqueue`
- * will return immediately, otherwise it will block until there is room.
+ *   When `stopOnMapperError` is true (default):
+ *   - First error immediately stops processing
+ *   - Error is thrown from the `AsyncIterator`'s next() call
+ *
+ *   When `stopOnMapperError` is false:
+ *   - Processing continues despite errors
+ *   - All errors are collected and thrown together
+ *   - Errors are thrown as `AggregateError` after all items complete
+ *
+ * ### Usage
+ * - Items are added to the queue via the `await enqueue()` method
+ * - IMPORTANT: `await enqueue()` method will block until a slot is available, if queue is full
+ * - Call `done()` when no more items will be enqueued
+ * - IMPORTANT: Always `await onIdle()` to ensure all items are processed
  *
  * @category Enqueue Input
+ *
+ * @see {@link IterableMapper} for underlying mapper implementation and examples of combined usage
  */
 class IterableQueueMapper {
     /**
-     * Create a new `IterableQueueMapper`
+     * Create a new `IterableQueueMapper`, which uses `IterableMapper` underneath, and exposes a
+     * queue interface for adding items that are not exposed via an iterator.
      *
-     * @param mapper Function which is called for every item in `input`.
-     *    Expected to return a `Promise` or value.
-     *
-     *    The `mapper` *should* handle all errors and not allow an error to be thrown
-     *    out of the `mapper` function as this enables the best handling of errors
-     *    closest to the time that they occur.
-     *
-     *    If the `mapper` function does allow an error to be thrown then the
-     *   `stopOnMapperError` option controls the behavior:
-     *      - `stopOnMapperError`: `true` - will throw the error
-     *        out of `next` or the `AsyncIterator` returned from `[Symbol.asyncIterator]`
-     *        and stop processing.
-     *     - `stopOnMapperError`: `false` - will continue processing
-     *        and accumulate the errors to be thrown from `next` or the `AsyncIterator`
-     *        returned from `[Symbol.asyncIterator]` when all items have been processed.
+     * @param mapper Function called for every enqueued item. Returns a `Promise` or value.
      * @param options IterableQueueMapper options
+     *
+     * @see {@link IterableQueueMapper} for full class documentation
+     * @see {@link IterableMapper} for underlying mapper implementation and examples of combined usage
      */
     constructor(mapper, options = {}) {
         this._sourceIterable = new iterable_queue_1.IterableQueue({

package/dist/src/iterable-queue-mapper.js.map

@@ -1 +1 @@
-{"version":3,"file":"iterable-queue-mapper.js","sourceRoot":"","sources":["../../src/iterable-queue-mapper.ts"],"names":[],"mappings":";;;AAAA,EAAE;AACF,sGAAsG;AACtG,EAAE;AACF,uDAA2D;AAC3D,qDAAiD;AA6BjD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAa,mBAAmB;IAK9B;;;;;;;;;;;;;;;;;;;OAmBG;IACH,YAAY,MAAmC,EAAE,UAAsC,EAAE;QACvF,IAAI,CAAC,eAAe,GAAG,IAAI,8BAAa,CAAC;YACvC,SAAS,EAAE,CAAC;SACb,CAAC,CAAC;QACH,IAAI,CAAC,eAAe,GAAG,IAAI,gCAAc,CAAC,IAAI,CAAC,eAAe,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;IACnF,CAAC;IAEM,CAAC,MAAM,CAAC,aAAa,CAAC;QAC3B,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;OAIG;IACI,KAAK,CAAC,IAAI;QACf,OAAO,IAAI,CAAC,eAAe,CAAC,IAAI,EAAE,CAAC;IACrC,CAAC;IAED;;;;OAIG;IACI,KAAK,CAAC,OAAO,CAAC,IAAa;QAChC,MAAM,IAAI,CAAC,eAAe,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3C,CAAC;IAED;;;;OAIG;IACI,IAAI;QACT,IAAI,CAAC,eAAe,CAAC,IAAI,EAAE,CAAC;IAC9B,CAAC;CACF;AA9DD,kDA8DC"}
+{"version":3,"file":"iterable-queue-mapper.js","sourceRoot":"","sources":["../../src/iterable-queue-mapper.ts"],"names":[],"mappings":";;;AAAA,EAAE;AACF,sGAAsG;AACtG,EAAE;AACF,uDAAkF;AAClF,qDAAiD;AAOjD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,MAAa,mBAAmB;IAK9B;;;;;;;;;OASG;IACH,YAAY,MAAmC,EAAE,UAAsC,EAAE;QACvF,IAAI,CAAC,eAAe,GAAG,IAAI,8BAAa,CAAC;YACvC,SAAS,EAAE,CAAC;SACb,CAAC,CAAC;QACH,IAAI,CAAC,eAAe,GAAG,IAAI,gCAAc,CAAC,IAAI,CAAC,eAAe,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;IACnF,CAAC;IAEM,CAAC,MAAM,CAAC,aAAa,CAAC;QAC3B,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;OAIG;IACI,KAAK,CAAC,IAAI;QACf,OAAO,IAAI,CAAC,eAAe,CAAC,IAAI,EAAE,CAAC;IACrC,CAAC;IAED;;;;OAIG;IACI,KAAK,CAAC,OAAO,CAAC,IAAa;QAChC,MAAM,IAAI,CAAC,eAAe,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3C,CAAC;IAED;;;;OAIG;IACI,IAAI;QACT,IAAI,CAAC,eAAe,CAAC,IAAI,EAAE,CAAC;IAC9B,CAAC;CACF;AApDD,kDAoDC"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@shutterstock/p-map-iterable",
-  "version": "1.1.0",
-  "description": "Set of classes that allow you to call mappers with controlled concurrency on iterables or on queues",
+  "version": "1.1.2",
+  "description": "Set of classes used for async prefetching with backpressure (IterableMapper) and async flushing with backpressure (IterableQueueMapper, IterableQueueMapperSimple)",
   "main": "dist/src/index.js",
   "types": "dist/src/index.d.ts",
   "publishConfig": {
@@ -24,7 +24,7 @@
     "AsyncIterator"
   ],
   "scripts": {
-    "build": "tsc --build tsconfig.json && echo 'examples/\n*.tsbuildinfo' > dist/.npmignore",
+    "build": "tsc --build tsconfig.json && echo 'examples/\n*.tsbuildinfo\n*.test.*\n*.d.ts.map' > dist/.npmignore",
     "build:docs": "typedoc src/index.ts",
     "example:iterable-mapper": "ts-node -r tsconfig-paths/register examples/iterable-mapper.ts",
     "example:iterable-queue-mapper": "ts-node -r tsconfig-paths/register examples/iterable-queue-mapper.ts",

package/dist/src/blocking-queue.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"blocking-queue.d.ts","sourceRoot":"","sources":["../../src/blocking-queue.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,oBAAoB;IACnC;;;;;;OAMG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAOD;;;;;;;GAOG;AACH,qBAAa,aAAa,CAAC,OAAO;IAChC,OAAO,CAAC,QAAQ,CAAiC;IAKjD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAA+B;IAO5D,OAAO,CAAC,QAAQ,CAAC,eAAe,CAA0C;IAO1E,OAAO,CAAC,QAAQ,CAAC,eAAe,CAA0C;IAE1E,OAAO,CAAC,WAAW,CAAS;IAE5B;;;;OAIG;gBACS,OAAO,GAAE,oBAAyB;IAuB9C,IAAW,MAAM,IAAI,MAAM,CAE1B;IAED;;;;OAIG;IACI,IAAI,IAAI,IAAI;IAcnB;;;;OAIG;IACU,OAAO,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IA0BlD;;;;OAIG;IACU,OAAO,IAAI,OAAO,CAAC,OAAO,GAAG,SAAS,CAAC;IAoCpD,OAAO,CAAC,iBAAiB;IAQzB,OAAO,CAAC,SAAS;IAqCjB;;OAEG;YACW,YAAY;IAW1B;;OAEG;YACW,WAAW;CAU1B"}

package/dist/src/blocking-queue.test.d.ts

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=blocking-queue.test.d.ts.map

package/dist/src/blocking-queue.test.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"blocking-queue.test.d.ts","sourceRoot":"","sources":["../../src/blocking-queue.test.ts"],"names":[],"mappings":""}

package/dist/src/blocking-queue.test.js

@@ -1,174 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-/// <reference types="jest" />
-const blocking_queue_1 = require("./blocking-queue");
-describe('BlockingQueue', () => {
-    beforeAll(() => {
-        // nothing
-    });
-    beforeEach(() => {
-        jest.clearAllMocks();
-    });
-    describe('maxUnread: 0', () => {
-        it('single item enqueue/dequeue works', async () => {
-            const queue = new blocking_queue_1.BlockingQueue({ maxUnread: 0 });
-            setTimeout(() => {
-                void queue.enqueue(1);
-            }, 1000);
-            const item = await queue.dequeue();
-            queue.done();
-            expect(item).toBe(1);
-        });
-        it('dequeue after done does not hang', async () => {
-            const queue = new blocking_queue_1.BlockingQueue({ maxUnread: 0 });
-            setTimeout(() => {
-                void queue.enqueue(1);
-            }, 1000);
-            const item = await queue.dequeue();
-            queue.done();
-            await queue.dequeue();
-            expect(item).toBe(1);
-        });
-        it('enqueue after done throws', async () => {
-            const queue = new blocking_queue_1.BlockingQueue({ maxUnread: 0 });
-            setTimeout(() => {
-                void queue.enqueue(1);
-            }, 1000);
-            const item = await queue.dequeue();
-            queue.done();
-            await expect(async () => queue.enqueue(2)).rejects.toThrowError('`enqueue` called after `done` called');
-            expect(item).toBe(1);
-        });
-        it('balanced enqueue/dequeue works', async () => {
-            const queue = new blocking_queue_1.BlockingQueue({ maxUnread: 0 });
-            const writers = [];
-            writers.push(queue.enqueue(1));
-            writers.push(queue.enqueue(2));
-            const readers = [];
-            readers.push(queue.dequeue());
-            readers.push(queue.dequeue());
-            await Promise.all(writers);
-            queue.done();
-            await Promise.all(readers);
-            expect(await readers[0]).toBe(1);
-            expect(await readers[1]).toBe(2);
-        });
-        it('full queue blocks enqueue until dequeue', async () => {
-            const queue = new blocking_queue_1.BlockingQueue({ maxUnread: 1 });
-            // Add first item
-            void queue.enqueue(1);
-            // Do not wait for second item to add (it will wait until an enqueue completes)
-            setTimeout(() => {
-                void queue.enqueue(2);
-            }, 2000);
-            const startTime = Date.now();
-            expect(await queue.dequeue()).toBe(1);
-            expect(Date.now() - startTime).toBeLessThan(2000);
-            expect(await queue.dequeue()).toBe(2);
-            expect(Date.now() - startTime).toBeGreaterThanOrEqual(2000);
-            queue.done();
-        });
-    });
-    describe('maxUnread: 1', () => {
-        it('single item enqueue/dequeue works', async () => {
-            const queue = new blocking_queue_1.BlockingQueue({ maxUnread: 1 });
-            await queue.enqueue(1);
-            const item = await queue.dequeue();
-            queue.done();
-            expect(item).toBe(1);
-        });
-        it('dequeue after done does not hang', async () => {
-            const queue = new blocking_queue_1.BlockingQueue({ maxUnread: 1 });
-            await queue.enqueue(1);
-            const item = await queue.dequeue();
-            queue.done();
-            await queue.dequeue();
-            expect(item).toBe(1);
-        });
-        it('dequeue after done and empty does not hang', async () => {
-            const queue = new blocking_queue_1.BlockingQueue({ maxUnread: 1 });
-            await queue.enqueue(1);
-            const item = await queue.dequeue();
-            queue.done();
-            await queue.dequeue();
-            expect(item).toBe(1);
-            await queue.dequeue();
-        });
-        it('enqueue after done throws', async () => {
-            const queue = new blocking_queue_1.BlockingQueue({ maxUnread: 1 });
-            await queue.enqueue(1);
-            const item = await queue.dequeue();
-            queue.done();
-            await expect(async () => queue.enqueue(2)).rejects.toThrowError('`enqueue` called after `done` called');
-            expect(item).toBe(1);
-        });
-        it('balanced enqueue/dequeue works', async () => {
-            const queue = new blocking_queue_1.BlockingQueue({ maxUnread: 1 });
-            const writers = [];
-            writers.push(queue.enqueue(1));
-            writers.push(queue.enqueue(2));
-            const readers = [];
-            readers.push(queue.dequeue());
-            readers.push(queue.dequeue());
-            await Promise.all(writers);
-            queue.done();
-            await Promise.all(readers);
-            expect(await readers[0]).toBe(1);
-            expect(await readers[1]).toBe(2);
-        });
-        it('more dequeue than enqueue works', async () => {
-            const queue = new blocking_queue_1.BlockingQueue({ maxUnread: 1 });
-            const writers = [];
-            writers.push(queue.enqueue(1));
-            writers.push(queue.enqueue(2));
-            const readers = [];
-            readers.push(queue.dequeue());
-            readers.push(queue.dequeue());
-            readers.push(queue.dequeue());
-            readers.push(queue.dequeue());
-            await Promise.all(writers);
-            queue.done();
-            await Promise.all(readers);
-            expect(await readers[0]).toBe(1);
-            expect(await readers[1]).toBe(2);
-            expect(await readers[2]).toBeUndefined();
-            expect(await readers[3]).toBeUndefined();
-        });
-        it('full queue blocks enqueue until dequeue', async () => {
-            const queue = new blocking_queue_1.BlockingQueue({ maxUnread: 1 });
-            // Wait for first item to add
-            await queue.enqueue(1);
-            // Do not wait for second item to add (it will wait until an enqueue completes)
-            setTimeout(() => {
-                void queue.enqueue(2);
-            }, 2000);
-            expect(await queue.dequeue()).toBe(1);
-            const startTime = Date.now();
-            expect(await queue.dequeue()).toBe(2);
-            const duration = Date.now() - startTime;
-            expect(duration).toBeGreaterThanOrEqual(2000);
-            queue.done();
-        });
-    });
-    describe('maxUnread: 2', () => {
-        it('no reads until done works', async () => {
-            const queue = new blocking_queue_1.BlockingQueue({ maxUnread: 2 });
-            const writers = [];
-            writers.push(queue.enqueue(1));
-            writers.push(queue.enqueue(2));
-            await Promise.all(writers);
-            queue.done();
-            const readers = [];
-            readers.push(queue.dequeue());
-            readers.push(queue.dequeue());
-            readers.push(queue.dequeue());
-            readers.push(queue.dequeue());
-            await Promise.all(readers);
-            expect(await readers[0]).toBe(1);
-            expect(await readers[1]).toBe(2);
-            expect(await readers[2]).toBeUndefined();
-            expect(await readers[3]).toBeUndefined();
-        });
-    });
-});
-//# sourceMappingURL=blocking-queue.test.js.map