@reliverse/mapkit 2.2.7

package/dist/mod.d.ts

@@ -0,0 +1,86 @@
+type BaseOptions = {
+    /**
+     * Number of concurrently pending promises returned by `mapkit`.
+     *
+     * Must be an integer from 1 and up or `Infinity`.
+     *
+     * @default Infinity
+     */
+    readonly concurrency?: number;
+};
+export type Options = BaseOptions & {
+    /**
+     * When `true`, the first mapkit rejection will be rejected back to the consumer.
+     *
+     * When `false`, instead of stopping when a promise rejects, it will wait for all
+     * the promises to settle and then reject with an `AggregateError` containing all
+     * the errors from the rejected promises.
+     *
+     * Caveat: When `true`, any already-started async mapkits will continue to run
+     * until they resolve or reject. In the case of infinite concurrency with sync
+     * iterables, all mapkits are invoked on startup and will continue after the first
+     * rejection. AbortControl can be used to stop pulling new items.
+     *
+     * @default true
+     */
+    readonly stopOnError?: boolean;
+    /**
+     * You can abort the promises using `AbortController`.
+     *
+     * Rejects with the `signal.reason` immediately, stops pulling new items, and
+     * attempts to close the underlying iterator via `.return()` if available.
+     */
+    readonly signal?: AbortSignal;
+};
+export type IterableOptions = BaseOptions & {
+    /**
+     * Maximum number of promises returned by `mapkit` that have resolved but not yet
+     * collected by the consumer of the async iterable. Calls to `mapkit` will be
+     * limited so that there is never too much backpressure.
+     *
+     * Useful whenever you are consuming the iterable slower than what the mapkit
+     * function can produce concurrently.
+     *
+     * Default: `options.concurrency`
+     */
+    readonly backpressure?: number;
+};
+type MaybePromise<T> = T | Promise<T>;
+/**
+ * Function which is called for every item in `input`. Expected to return a
+ * `Promise` or value.
+ *
+ * @param element - Iterated element.
+ * @param index - Index of the element in the source array.
+ */
+export type mapkit<Element = unknown, NewElement = unknown> = (element: Element, index: number) => MaybePromise<NewElement | typeof pMapSkip>;
+/**
+ * Return this value from a `mapkit` function to skip including the value in the
+ * returned array.
+ */
+export declare const pMapSkip: unique symbol;
+/**
+ * @param input - Synchronous or asynchronous iterable that is iterated over
+ * concurrently, calling the `mapkit` function for each element. Each iterated
+ * item is `await`'d before the `mapkit` is invoked so the iterable may return a
+ * `Promise` that resolves to an item.
+ * @param mapkit - Function which is called for every item in `input`. Expected
+ * to return a `Promise` or value.
+ * @returns A `Promise` that is fulfilled when all promises in `input` and ones
+ * returned from `mapkit` are fulfilled, or rejects if any of the promises
+ * reject. The fulfilled value is an `Array` of the fulfilled values returned
+ * from `mapkit` in `input` order, excluding `pMapSkip`.
+ */
+export default function pMap<Element, NewElement>(input: AsyncIterable<Element | Promise<Element>> | Iterable<Element | Promise<Element>>, mapkit: mapkit<Element, NewElement>, options?: Options): Promise<Array<Exclude<NewElement, typeof pMapSkip>>>;
+/**
+ * @param input - Synchronous or asynchronous iterable that is iterated over
+ * concurrently, calling the `mapkit` function for each element. Each iterated
+ * item is `await`'d before the `mapkit` is invoked so the iterable may return a
+ * `Promise` that resolves to an item.
+ * @param mapkit - Function which is called for every item in `input`. Expected
+ * to return a `Promise` or value.
+ * @returns An async iterable that streams each return value from `mapkit` in
+ * order, excluding `pMapSkip`.
+ */
+export declare function pMapIterable<Element, NewElement>(input: AsyncIterable<Element | Promise<Element>> | Iterable<Element | Promise<Element>>, mapkit: mapkit<Element, NewElement>, options?: IterableOptions): AsyncIterable<Exclude<NewElement, typeof pMapSkip>>;
+export {};

package/dist/mod.js

@@ -0,0 +1,251 @@
+export const pMapSkip = /* @__PURE__ */ Symbol("skip");
+export default async function pMap(input, mapkit, options = {}) {
+  const {
+    concurrency = Number.POSITIVE_INFINITY,
+    stopOnError = true,
+    signal
+  } = options;
+  if (!("Symbol" in globalThis) || input[Symbol.iterator] === void 0 && input[Symbol.asyncIterator] === void 0) {
+    throw new TypeError(
+      `Expected \`input\` to be either an \`Iterable\` or \`AsyncIterable\`, got (${typeof input})`
+    );
+  }
+  if (typeof mapkit !== "function") {
+    throw new TypeError("mapkit function is required");
+  }
+  if (!(Number.isSafeInteger(concurrency) && concurrency >= 1 || concurrency === Number.POSITIVE_INFINITY)) {
+    throw new TypeError(
+      `Expected \`concurrency\` to be an integer from 1 and up or \`Infinity\`, got \`${concurrency}\` (${typeof concurrency})`
+    );
+  }
+  return new Promise((resolve, reject) => {
+    const isAsyncIterable = input[Symbol.asyncIterator] !== void 0;
+    const iterator = isAsyncIterable ? input[Symbol.asyncIterator]() : input[Symbol.iterator]();
+    const results = [];
+    const errors = [];
+    let activeCount = 0;
+    let currentIndex = 0;
+    let isIterableDone = false;
+    let isSettled = false;
+    let isPumping = false;
+    let iteratorClosed = false;
+    const safeCloseIterator = async () => {
+      if (iteratorClosed) return;
+      const ret = iterator?.return;
+      if (typeof ret === "function") {
+        try {
+          iteratorClosed = true;
+          await ret.call(iterator);
+        } catch {
+        }
+      } else {
+        iteratorClosed = true;
+      }
+    };
+    const onAbort = () => {
+      if (isSettled) return;
+      isSettled = true;
+      void safeCloseIterator();
+      cleanup();
+      reject(signal?.reason);
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
+    function cleanup() {
+      signal?.removeEventListener("abort", onAbort);
+    }
+    function settleWithAggregateIfNeeded() {
+      if (errors.length > 0 && !stopOnError) {
+        cleanup();
+        reject(new AggregateError(errors, "One or more promises rejected"));
+        return true;
+      }
+      return false;
+    }
+    function resolveResults() {
+      cleanup();
+      const out = [];
+      for (let i = 0; i < results.length; i++) {
+        const v = results[i];
+        if (v !== void 0 && v !== pMapSkip) {
+          out.push(v);
+        }
+      }
+      resolve(out);
+    }
+    function checkCompletion() {
+      if (isSettled) return;
+      if (!isIterableDone) return;
+      if (activeCount > 0) return;
+      isSettled = true;
+      if (settleWithAggregateIfNeeded()) {
+        return;
+      }
+      resolveResults();
+    }
+    async function startmapkit(valueOrPromise, index) {
+      try {
+        const item = await valueOrPromise;
+        const result = await mapkit(item, index);
+        if (!isSettled) {
+          results[index] = result;
+        }
+      } catch (error) {
+        if (isSettled) return;
+        if (stopOnError) {
+          isSettled = true;
+          void safeCloseIterator();
+          cleanup();
+          reject(error);
+          return;
+        }
+        errors.push(error);
+      } finally {
+        if (!isSettled) {
+          activeCount--;
+          checkCompletion();
+          void pump();
+        }
+      }
+    }
+    async function pump() {
+      if (isSettled || isPumping) return;
+      isPumping = true;
+      try {
+        while (!isSettled && !isIterableDone && activeCount < concurrency) {
+          let next;
+          try {
+            next = iterator.next();
+            next = await next;
+          } catch (error) {
+            if (!isSettled) {
+              isSettled = true;
+              void safeCloseIterator();
+              cleanup();
+              reject(error);
+            }
+            return;
+          }
+          if (next.done) {
+            isIterableDone = true;
+            break;
+          }
+          const index = currentIndex++;
+          activeCount++;
+          void startmapkit(next.value, index);
+        }
+        checkCompletion();
+      } finally {
+        isPumping = false;
+      }
+    }
+    void pump();
+  });
+}
+export function pMapIterable(input, mapkit, options = {}) {
+  const { concurrency = Number.POSITIVE_INFINITY, backpressure = concurrency } = options;
+  if (!("Symbol" in globalThis) || input[Symbol.iterator] === void 0 && input[Symbol.asyncIterator] === void 0) {
+    throw new TypeError(
+      `Expected \`input\` to be either an \`Iterable\` or \`AsyncIterable\`, got (${typeof input})`
+    );
+  }
+  if (typeof mapkit !== "function") {
+    throw new TypeError("mapkit function is required");
+  }
+  if (!(Number.isSafeInteger(concurrency) && concurrency >= 1 || concurrency === Number.POSITIVE_INFINITY)) {
+    throw new TypeError(
+      `Expected \`concurrency\` to be an integer from 1 and up or \`Infinity\`, got \`${concurrency}\` (${typeof concurrency})`
+    );
+  }
+  if (!(Number.isSafeInteger(backpressure) && backpressure >= concurrency || backpressure === Number.POSITIVE_INFINITY)) {
+    throw new TypeError(
+      `Expected \`backpressure\` to be an integer from \`concurrency\` (${concurrency}) and up or \`Infinity\`, got \`${backpressure}\` (${typeof backpressure})`
+    );
+  }
+  return {
+    async *[Symbol.asyncIterator]() {
+      const iterator = input[Symbol.asyncIterator] !== void 0 ? input[Symbol.asyncIterator]() : input[Symbol.iterator]();
+      const resultQueue = [];
+      let runningCount = 0;
+      let currentIndex = 0;
+      let isDone = false;
+      let pulling = false;
+      let iteratorClosed = false;
+      const safeCloseIterator = async () => {
+        if (iteratorClosed) return;
+        const ret = iterator?.return;
+        if (typeof ret === "function") {
+          try {
+            iteratorClosed = true;
+            await ret.call(iterator);
+          } catch {
+          }
+        } else {
+          iteratorClosed = true;
+        }
+      };
+      const schedulePull = () => {
+        if (pulling || isDone) return;
+        pulling = true;
+        (async () => {
+          try {
+            while (!isDone && runningCount < concurrency && resultQueue.length < backpressure) {
+              let next;
+              try {
+                next = iterator.next();
+                next = await next;
+              } catch (error) {
+                isDone = true;
+                resultQueue.push(
+                  Promise.resolve({
+                    error,
+                    done: false
+                  })
+                );
+                break;
+              }
+              if (next.done) {
+                isDone = true;
+                resultQueue.push(Promise.resolve({ done: true }));
+                break;
+              }
+              const index = currentIndex++;
+              runningCount++;
+              const promise = (async () => {
+                try {
+                  const element = await next.value;
+                  const result = await mapkit(element, index);
+                  return { value: result, done: false };
+                } catch (error) {
+                  return { error, done: false };
+                } finally {
+                  runningCount--;
+                  schedulePull();
+                }
+              })();
+              resultQueue.push(promise);
+            }
+          } finally {
+            pulling = false;
+          }
+        })();
+      };
+      schedulePull();
+      while (resultQueue.length > 0) {
+        const result = await resultQueue.shift();
+        if (result.error) {
+          await safeCloseIterator();
+          throw result.error;
+        }
+        if (result.done) {
+          await safeCloseIterator();
+          return;
+        }
+        schedulePull();
+        if (result.value !== pMapSkip) {
+          yield result.value;
+        }
+      }
+      await safeCloseIterator();
+    }
+  };
+}

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@reliverse/mapkit",
+  "version": "2.2.7",
+  "private": false,
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/mod.d.ts",
+      "default": "./dist/mod.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {},
+  "files": [
+    "dist",
+    "package.json"
+  ],
+  "license": "MIT"
+}