@ls-stack/utils 3.7.0 → 3.9.0

package/lib/concurrentCalls.cjs

@@ -0,0 +1,311 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/concurrentCalls.ts
+var concurrentCalls_exports = {};
+__export(concurrentCalls_exports, {
+  concurrentCalls: () => concurrentCalls,
+  concurrentCallsWithMetadata: () => concurrentCallsWithMetadata
+});
+module.exports = __toCommonJS(concurrentCalls_exports);
+var import_t_result = require("t-result");
+
+// src/assertions.ts
+function invariant(condition, errorMsg = "Invariant violation") {
+  if (!condition) {
+    throw new Error(`Invariant violation: ${errorMsg}`);
+  }
+}
+function isObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isFunction(value) {
+  return typeof value === "function";
+}
+function isPromise(value) {
+  return isObject(value) && "then" in value && isFunction(value.then);
+}
+
+// src/arrayUtils.ts
+function truncateArray(array, maxLength, appendIfTruncated) {
+  const truncate = array.length > maxLength;
+  const result = truncate ? [...array.slice(0, maxLength)] : array;
+  if (truncate && appendIfTruncated) {
+    if (isFunction(appendIfTruncated)) {
+      return [...result, appendIfTruncated(array.length - maxLength)];
+    }
+    return [...result, appendIfTruncated];
+  }
+  return result;
+}
+
+// src/sleep.ts
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// src/stringUtils.ts
+function truncateString(str, length, ellipsis = "\u2026") {
+  if (str.length <= length) return str;
+  return str.slice(0, length - 1) + ellipsis;
+}
+
+// src/concurrentCalls.ts
+var ConcurrentCalls = class {
+  #pendingCalls = [];
+  #alreadyRun = false;
+  add(...calls) {
+    this.#pendingCalls.push(...calls);
+    return this;
+  }
+  resultifyAdd(...calls) {
+    const processedCalls = calls.map((call) => {
+      if (isPromise(call)) {
+        return call.then((value) => import_t_result.Result.ok(value)).catch((err) => import_t_result.Result.err((0, import_t_result.unknownToError)(err)));
+      } else {
+        const originalFn = call;
+        return async () => {
+          try {
+            const valueOrPromise = originalFn();
+            const value = isPromise(valueOrPromise) ? await valueOrPromise : valueOrPromise;
+            return import_t_result.Result.ok(value);
+          } catch (err) {
+            return import_t_result.Result.err((0, import_t_result.unknownToError)(err));
+          }
+        };
+      }
+    });
+    const correctlyTypedProcessedCalls = processedCalls;
+    return this.add(...correctlyTypedProcessedCalls);
+  }
+  async runAll({ delayStart } = {}) {
+    invariant(!this.#alreadyRun, "Already run");
+    this.#alreadyRun = true;
+    try {
+      const asyncResults = await Promise.all(
+        this.#pendingCalls.map(async (fn, i) => {
+          try {
+            const isP = isPromise(fn);
+            if (delayStart) {
+              invariant(
+                !isP,
+                "Delay start is not supported direct promise calls"
+              );
+              await sleep(delayStart(i));
+            }
+            const result = await (isP ? fn : fn());
+            if (!result.ok) throw result.error;
+            return result.value;
+          } catch (exception) {
+            throw (0, import_t_result.unknownToError)(exception);
+          }
+        })
+      );
+      return import_t_result.Result.ok(asyncResults);
+    } catch (exception) {
+      return import_t_result.Result.err((0, import_t_result.unknownToError)(exception));
+    } finally {
+      this.#pendingCalls = [];
+    }
+  }
+  async runAllSettled({ delayStart } = {}) {
+    invariant(!this.#alreadyRun, "Already run");
+    this.#alreadyRun = true;
+    const total = this.#pendingCalls.length;
+    const settledResults = await Promise.allSettled(
+      this.#pendingCalls.map(async (callOrPromise, i) => {
+        try {
+          const isP = isPromise(callOrPromise);
+          if (delayStart) {
+            invariant(
+              !isP,
+              "Delay start is not supported for direct promise calls"
+            );
+            await sleep(delayStart(i));
+          }
+          const result = await (isP ? callOrPromise : callOrPromise());
+          if (!result.ok) {
+            throw result.error;
+          }
+          return result.value;
+        } catch (exception) {
+          throw (0, import_t_result.unknownToError)(exception);
+        }
+      })
+    );
+    const succeeded = [];
+    const failed = [];
+    for (const settledResult of settledResults) {
+      if (settledResult.status === "fulfilled") {
+        succeeded.push(settledResult.value);
+      } else {
+        failed.push(settledResult.reason);
+      }
+    }
+    const allFailed = failed.length === total;
+    const aggregatedError = failed.length > 0 ? new AggregateError(failed, "One or more calls failed") : null;
+    this.#pendingCalls = [];
+    return {
+      succeeded,
+      failures: failed,
+      allFailed,
+      total,
+      aggregatedError
+    };
+  }
+};
+function concurrentCalls() {
+  return new ConcurrentCalls();
+}
+var ConcurrentCallsWithMetadata = class {
+  #pendingCalls = [];
+  #alreadyRun = false;
+  add(...calls) {
+    invariant(
+      !this.#alreadyRun,
+      "Cannot add calls after execution has started."
+    );
+    this.#pendingCalls.push(...calls);
+    return this;
+  }
+  resultifyAdd(...items) {
+    const processedItems = items.map(({ fn, metadata }) => {
+      const cb = isPromise(fn) ? (0, import_t_result.resultify)(fn) : () => (0, import_t_result.resultify)(async () => {
+        const result = await fn();
+        return result;
+      });
+      return {
+        fn: cb,
+        metadata
+      };
+    });
+    return this.add(...processedItems);
+  }
+  async runAll({ delayStart } = {}) {
+    invariant(!this.#alreadyRun, "Already run");
+    this.#alreadyRun = true;
+    const currentCalls = [...this.#pendingCalls];
+    this.#pendingCalls = [];
+    try {
+      const successfulResults = [];
+      for (let i = 0; i < currentCalls.length; i++) {
+        const call = currentCalls[i];
+        try {
+          if (delayStart) {
+            await sleep(delayStart(i));
+          }
+          const result = await (isPromise(call.fn) ? call.fn : call.fn());
+          if (!result.ok) {
+            throw { metadata: call.metadata, error: result.error };
+          }
+          successfulResults.push({
+            value: result.value,
+            metadata: call.metadata
+          });
+        } catch (exception) {
+          if (typeof exception === "object" && exception !== null && "metadata" in exception && "error" in exception && exception.metadata === call.metadata) {
+            throw exception;
+          } else {
+            throw {
+              metadata: call.metadata,
+              error: (0, import_t_result.unknownToError)(exception)
+            };
+          }
+        }
+      }
+      return import_t_result.Result.ok(successfulResults);
+    } catch (errorPayload) {
+      return import_t_result.Result.err(errorPayload);
+    }
+  }
+  async runAllSettled({ delayStart } = {}) {
+    invariant(!this.#alreadyRun, "Already run");
+    this.#alreadyRun = true;
+    const currentCalls = [...this.#pendingCalls];
+    this.#pendingCalls = [];
+    const total = currentCalls.length;
+    if (total === 0) {
+      return {
+        succeeded: [],
+        failed: [],
+        results: [],
+        allFailed: false,
+        total: 0,
+        aggregatedError: null
+      };
+    }
+    const settledOutcomes = await Promise.allSettled(
+      currentCalls.map(async (call, i) => {
+        try {
+          if (delayStart) {
+            await sleep(delayStart(i));
+          }
+          const result = await (isPromise(call.fn) ? call.fn : call.fn());
+          if (!result.ok) {
+            throw result.error;
+          }
+          return result.value;
+        } catch (innerException) {
+          throw (0, import_t_result.unknownToError)(innerException);
+        }
+      })
+    );
+    const succeededProcessing = [];
+    const failedProcessing = [];
+    const resultsProcessing = [];
+    for (let i = 0; i < settledOutcomes.length; i++) {
+      const outcome = settledOutcomes[i];
+      const { metadata } = currentCalls[i];
+      if (outcome.status === "fulfilled") {
+        const value = outcome.value;
+        succeededProcessing.push({ value, metadata });
+        resultsProcessing.push({ ok: true, value, metadata, error: false });
+      } else {
+        const error = outcome.reason;
+        failedProcessing.push({ error, metadata });
+        resultsProcessing.push({ ok: false, error, metadata });
+      }
+    }
+    const allFailed = failedProcessing.length === total;
+    const aggregatedError = failedProcessing.length > 0 ? new AggregateError(
+      failedProcessing.map((f) => f.error),
+      `${failedProcessing.length}/${total} calls failed: ${truncateArray(
+        failedProcessing.map((f) => truncateString(f.error.message, 20)),
+        5,
+        (count) => `+${count} more`
+      ).join("; ")}`
+    ) : null;
+    return {
+      succeeded: succeededProcessing,
+      failed: failedProcessing,
+      results: resultsProcessing,
+      allFailed,
+      total,
+      aggregatedError
+    };
+  }
+};
+function concurrentCallsWithMetadata() {
+  return new ConcurrentCallsWithMetadata();
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  concurrentCalls,
+  concurrentCallsWithMetadata
+});

package/lib/concurrentCalls.d.cts

@@ -0,0 +1,75 @@
+import { Result } from 't-result';
+
+type ValidMetadata = string | number | boolean | Record<string, unknown>;
+type RunProps = {
+    delayStart?: (index: number) => number;
+};
+type SucceededCall<R, M> = {
+    value: R;
+    metadata: M;
+};
+type FailedCall<M, E extends Error = Error> = {
+    metadata: M;
+    error: E;
+};
+type Action<R, E extends Error> = (() => Promise<Result<R, E>>) | Promise<Result<R, E>>;
+type SettledResultWithMetadata<R, M, E extends Error = Error> = {
+    ok: true;
+    value: R;
+    metadata: M;
+    error: false;
+} | {
+    ok: false;
+    error: E;
+    metadata: M;
+};
+declare class ConcurrentCalls<R = unknown, E extends Error = Error> {
+    #private;
+    add(...calls: Action<R, E>[]): this;
+    resultifyAdd(...calls: (Promise<R> | (() => R) | (() => Promise<R>))[]): this;
+    runAll({ delayStart }?: RunProps): Promise<Result<R[], E>>;
+    runAllSettled({ delayStart }?: RunProps): Promise<{
+        allFailed: boolean;
+        failures: E[];
+        succeeded: R[];
+        total: number;
+        aggregatedError: AggregateError | null;
+    }>;
+}
+/**
+ * Executes multiple asynchronous calls concurrently and collects the results in a easier to use format.
+ *
+ * @template R - The type of the result value.
+ * @template E - The type of the error.
+ */
+declare function concurrentCalls<R = unknown, E extends Error = Error>(): ConcurrentCalls<R, E>;
+declare class ConcurrentCallsWithMetadata<M extends ValidMetadata, R = unknown, E extends Error = Error> {
+    #private;
+    add(...calls: {
+        fn: Action<R, E>;
+        metadata: M;
+    }[]): this;
+    resultifyAdd(...items: {
+        fn: (() => R) | (() => Promise<R>) | Promise<R>;
+        metadata: M;
+    }[]): this;
+    runAll({ delayStart }?: RunProps): Promise<Result<SucceededCall<R, M>[], FailedCall<M, E>>>;
+    runAllSettled({ delayStart }?: RunProps): Promise<{
+        allFailed: boolean;
+        failed: FailedCall<M, E>[];
+        succeeded: SucceededCall<R, M>[];
+        total: number;
+        results: SettledResultWithMetadata<R, M, E>[];
+        aggregatedError: AggregateError | null;
+    }>;
+}
+/**
+ * Executes multiple asynchronous calls concurrently and collects the results in a easier to use format.
+ *
+ * @template M - The type of the call metadata.
+ * @template R - The type of the result value.
+ * @template E - The type of the error from individual Result objects.
+ */
+declare function concurrentCallsWithMetadata<M extends ValidMetadata, R = unknown, E extends Error = Error>(): ConcurrentCallsWithMetadata<M, R, E>;
+
+export { concurrentCalls, concurrentCallsWithMetadata };

package/lib/concurrentCalls.d.ts

@@ -0,0 +1,75 @@
+import { Result } from 't-result';
+
+type ValidMetadata = string | number | boolean | Record<string, unknown>;
+type RunProps = {
+    delayStart?: (index: number) => number;
+};
+type SucceededCall<R, M> = {
+    value: R;
+    metadata: M;
+};
+type FailedCall<M, E extends Error = Error> = {
+    metadata: M;
+    error: E;
+};
+type Action<R, E extends Error> = (() => Promise<Result<R, E>>) | Promise<Result<R, E>>;
+type SettledResultWithMetadata<R, M, E extends Error = Error> = {
+    ok: true;
+    value: R;
+    metadata: M;
+    error: false;
+} | {
+    ok: false;
+    error: E;
+    metadata: M;
+};
+declare class ConcurrentCalls<R = unknown, E extends Error = Error> {
+    #private;
+    add(...calls: Action<R, E>[]): this;
+    resultifyAdd(...calls: (Promise<R> | (() => R) | (() => Promise<R>))[]): this;
+    runAll({ delayStart }?: RunProps): Promise<Result<R[], E>>;
+    runAllSettled({ delayStart }?: RunProps): Promise<{
+        allFailed: boolean;
+        failures: E[];
+        succeeded: R[];
+        total: number;
+        aggregatedError: AggregateError | null;
+    }>;
+}
+/**
+ * Executes multiple asynchronous calls concurrently and collects the results in a easier to use format.
+ *
+ * @template R - The type of the result value.
+ * @template E - The type of the error.
+ */
+declare function concurrentCalls<R = unknown, E extends Error = Error>(): ConcurrentCalls<R, E>;
+declare class ConcurrentCallsWithMetadata<M extends ValidMetadata, R = unknown, E extends Error = Error> {
+    #private;
+    add(...calls: {
+        fn: Action<R, E>;
+        metadata: M;
+    }[]): this;
+    resultifyAdd(...items: {
+        fn: (() => R) | (() => Promise<R>) | Promise<R>;
+        metadata: M;
+    }[]): this;
+    runAll({ delayStart }?: RunProps): Promise<Result<SucceededCall<R, M>[], FailedCall<M, E>>>;
+    runAllSettled({ delayStart }?: RunProps): Promise<{
+        allFailed: boolean;
+        failed: FailedCall<M, E>[];
+        succeeded: SucceededCall<R, M>[];
+        total: number;
+        results: SettledResultWithMetadata<R, M, E>[];
+        aggregatedError: AggregateError | null;
+    }>;
+}
+/**
+ * Executes multiple asynchronous calls concurrently and collects the results in a easier to use format.
+ *
+ * @template M - The type of the call metadata.
+ * @template R - The type of the result value.
+ * @template E - The type of the error from individual Result objects.
+ */
+declare function concurrentCallsWithMetadata<M extends ValidMetadata, R = unknown, E extends Error = Error>(): ConcurrentCallsWithMetadata<M, R, E>;
+
+export { concurrentCalls, concurrentCallsWithMetadata };