@knime/utils 1.0.16 → 1.1.0

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # @knime/utils
 
+## 1.1.0
+
+### Minor Changes
+
+- a8eebec: - Add `promise` utils
+  - `retryPromise` util function to retry async calls
+  - `createAbortablePromise` util function to leverage AbortControllers and
+    add abort behavior to an async call
+  - Add uploadManager util. Multi-file and multi-part upload handler
+
+## 1.0.17
+
+### Patch Changes
+
+- Updated dependencies [df2caa5]
+  - @knime/styles@1.1.0
+
 ## 1.0.16
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knime/utils",
-  "version": "1.0.16",
+  "version": "1.1.0",
   "description": "Internal utility functions and constants shared across @knime packages.",
   "homepage": "https://knime.github.io/webapps-common/",
   "license": "GPL 3 and Additional Permissions according to Sec. 7 (SEE the file LICENSE)",
@@ -10,7 +10,7 @@
     "consola": "3.2.3",
     "date-fns": "2.30.0",
     "date-fns-tz": "2.0.0",
-    "@knime/styles": "1.0.11"
+    "@knime/styles": "1.1.0"
   },
   "main": "src/index.ts",
   "module": "src/index.ts",
@@ -33,7 +33,8 @@
     }
   },
   "devDependencies": {
-    "flush-promises": "^1.0.2"
+    "flush-promises": "^1.0.2",
+    "mock-xmlhttprequest": "^8.3.0"
   },
   "scripts": {
     "test:unit": "TZ='Europe/Berlin' vitest"

package/src/dateMinMaxCheck.ts

@@ -1,6 +1,7 @@
 import { isAfter, isBefore } from "date-fns";
-import updateTime from "./updateTime";
+
 import updateDate from "./updateDate";
+import updateTime from "./updateTime";
 
 /**
  * Check if date is before min.

package/src/fileTypeIcons.ts

@@ -8,13 +8,13 @@ import odtIcon from "@knime/styles/img/icons/file-odt.svg";
 import pdfIcon from "@knime/styles/img/icons/file-pdf.svg";
 import pptxIcon from "@knime/styles/img/icons/file-pptx.svg";
 import psIcon from "@knime/styles/img/icons/file-ps.svg";
+import fileIcon from "@knime/styles/img/icons/file-question.svg";
+import txtIcon from "@knime/styles/img/icons/file-text.svg";
 import xlsIcon from "@knime/styles/img/icons/file-xls.svg";
 import xlsxIcon from "@knime/styles/img/icons/file-xlsx.svg";
 import xmlIcon from "@knime/styles/img/icons/file-xml.svg";
-import zipIcon from "@knime/styles/img/icons/file-zip.svg";
 import exeIcon from "@knime/styles/img/icons/file-zip-exe.svg";
-import txtIcon from "@knime/styles/img/icons/file-text.svg";
-import fileIcon from "@knime/styles/img/icons/file-question.svg";
+import zipIcon from "@knime/styles/img/icons/file-zip.svg";
 
 export const icons = {
   csvIcon,

package/src/index.ts

@@ -1,36 +1,37 @@
 import { capitalize, caseFormatter } from "./capitalize";
+import { isAfterMaxDate, isBeforeMinDate } from "./dateMinMaxCheck";
 import debounce from "./debounce";
-import { filters } from "./filters";
-import truncateString from "./truncateString";
-import getWrappedAroundIndex from "./getWrappedAroundIndex";
-import sleep from "./sleep";
 import { icons, isIconExisting } from "./fileTypeIcons";
-
-import updateDate from "./updateDate";
-import updateTime from "./updateTime";
-import { isAfterMaxDate, isBeforeMinDate } from "./dateMinMaxCheck";
+import { filters } from "./filters";
 import {
   formatDateString,
   formatDateTimeString,
   formatLocalDateTimeString,
   formatTimeString,
 } from "./format";
-
-import getLocalTimeZone from "./localTimezone";
-import numIntegerDigits from "./numIntegerDigits";
-
 import {
-  formatHotkeys,
   formatHotkey,
+  formatHotkeys,
   getDefaultSeparator,
 } from "./formatHotkeys";
-
 import type {
   Hotkey as _Hotkey,
   KnownHotkey as _KnownHotkey,
 } from "./formatHotkeys";
-
+import getWrappedAroundIndex from "./getWrappedAroundIndex";
+import getLocalTimeZone from "./localTimezone";
 import * as navigatorUtils from "./navigator";
+import numIntegerDigits from "./numIntegerDigits";
+import * as promise from "./promise";
+import sleep from "./sleep";
+import truncateString from "./truncateString";
+import updateDate from "./updateDate";
+import updateTime from "./updateTime";
+import type {
+  UploaderManagerConfig as _UploadManagerConfig,
+  UploadStateName as _UploadStateName,
+} from "./uploadManager";
+import * as uploadManager from "./uploadManager";
 
 const hotkeys = { formatHotkeys, formatHotkey, getDefaultSeparator };
 
@@ -39,7 +40,14 @@ export namespace HotkeysNS {
   export type KnownHotkey = _KnownHotkey;
 }
 
+export namespace UploadManagerNS {
+  export type UploaderConfig = _UploadManagerConfig;
+  export type UploadStateName = _UploadStateName;
+}
+
 export {
+  uploadManager,
+  promise,
   capitalize,
   caseFormatter,
   debounce,

package/src/promise/__tests__/createAbortablePromise.test.ts

@@ -0,0 +1,31 @@
+import { describe, expect, it, vi } from "vitest";
+import flushPromises from "flush-promises";
+
+import { AbortError, createAbortablePromise } from "../createAbortablePromise";
+
+describe("createAbortablePromise", () => {
+  it("should abort promise", async () => {
+    const mockFetchCall = () =>
+      new Promise((r) => setTimeout(() => r("resolved-value"), 300));
+
+    const { abortController, runAbortablePromise } = createAbortablePromise();
+
+    const catchSpy = vi.fn((e) => {
+      if (e instanceof AbortError) {
+        return "aborted";
+      }
+
+      throw e;
+    });
+
+    const promise = runAbortablePromise(() => mockFetchCall()).catch(catchSpy);
+
+    const abortError = new AbortError("aborting");
+    abortController.abort(abortError);
+
+    await flushPromises();
+
+    expect(catchSpy).toHaveBeenCalledWith(abortError);
+    expect(promise).resolves.toBe("aborted");
+  });
+});

package/src/promise/__tests__/retryPromise.test.ts

@@ -0,0 +1,73 @@
+import { describe, expect, it, vi } from "vitest";
+
+import { retryPromise } from "../retryPromise";
+
+describe("retryPromise", () => {
+  it("should retry", async () => {
+    let callCount = 0;
+    const mockFetchCall = vi.fn(
+      () =>
+        new Promise((resolve, reject) => {
+          callCount++;
+
+          if (callCount < 3) {
+            reject(new Error("failure"));
+            return;
+          }
+
+          if (callCount >= 3) {
+            resolve("success");
+          }
+        }),
+    );
+
+    const doneSpy = vi.fn();
+    const catchSpy = vi.fn();
+
+    const promise = retryPromise(() => mockFetchCall())
+      .then(doneSpy)
+      .catch(catchSpy);
+
+    await promise;
+
+    expect(doneSpy).toHaveBeenCalledOnce();
+    expect(catchSpy).not.toHaveBeenCalled();
+    expect(mockFetchCall).toHaveBeenCalledTimes(3);
+  });
+
+  it("should throw if retry count is exceeded", async () => {
+    const error = new Error("failure");
+    const mockFetchCall = vi.fn(() => Promise.reject(error));
+
+    const doneSpy = vi.fn();
+
+    const promise = retryPromise(() => mockFetchCall()).then(doneSpy);
+
+    await promise.catch(() => {}); // ignore errors caught by test
+    expect(() => promise).rejects.toThrowError(error);
+
+    expect(doneSpy).not.toHaveBeenCalled();
+    expect(mockFetchCall).toHaveBeenCalledTimes(6);
+  });
+
+  it("should not retry for specific errors", async () => {
+    class MyError extends Error {}
+    const myError = new MyError("failure");
+    const mockFetchCall = vi.fn(() => Promise.reject(myError));
+
+    const doneSpy = vi.fn();
+
+    const promise = retryPromise(
+      () => mockFetchCall(),
+      2,
+      0,
+      (e) => e instanceof MyError,
+    ).then(doneSpy);
+
+    await promise.catch(() => {}); // ignore errors caught by test
+    expect(() => promise).rejects.toThrowError(myError);
+
+    expect(doneSpy).not.toHaveBeenCalled();
+    expect(mockFetchCall).toHaveBeenCalledOnce();
+  });
+});

package/src/promise/createAbortablePromise.ts

@@ -0,0 +1,56 @@
+export class AbortError extends Error {}
+
+/**
+ * Helper to create an abortable promise. Returns an AbortController and a Function
+ * that you can pass your async handler to. Whenever the AbortController signal is
+ * aborted then the async handler's promise will reject with an AbortError
+ *
+ * Example:
+ * ```
+ * import { abortUtils } from "@knime/utils"
+ * const myFetchCall = async (params...) => {...};
+ *
+ * try {
+ *   const { runAbortablePromise, abortController } = createAbortablePromise(() =>
+ *     myFetchCall(params...),
+ *   );
+ * } catch (e) {
+ *   if (e instanceof abortUtils.AbortError) {
+ *     console.info('ignore due to abort');
+ *     return;
+ *   }
+ * }
+ *
+ * // somewhere else (while request is in-flight)
+ * abortController.abort(new abortUtils.AbortError('reason here'))
+ * ```
+ */
+export const createAbortablePromise = () => {
+  const abortController: AbortController = new AbortController();
+
+  const runAbortablePromise = <T = unknown>(request: () => Promise<T>) => {
+    return new Promise<T>((resolve, reject) => {
+      // abort logic
+      const abortListener = ({ target }: Event) => {
+        abortController.signal.removeEventListener("abort", abortListener);
+        const reason = (target as AbortSignal).reason;
+        reject(reason instanceof AbortError ? reason : new AbortError(reason));
+      };
+
+      // the actual call
+      request()
+        .then(resolve)
+        .catch((error) => {
+          if (error instanceof AbortError) {
+            return;
+          }
+
+          reject(error instanceof Error ? error : new Error(error));
+        });
+
+      abortController.signal.addEventListener("abort", abortListener);
+    });
+  };
+
+  return { abortController, runAbortablePromise };
+};

package/src/promise/index.ts

@@ -0,0 +1,2 @@
+export * from "./createAbortablePromise";
+export * from "./retryPromise";

package/src/promise/retryPromise.ts

@@ -0,0 +1,36 @@
+/* eslint-disable func-style */
+import sleep from "../sleep";
+
+const DEFAULT_RETRY_DELAY_MS = 0;
+const DEFAULT_RETRY_COUNT = 5;
+
+/**
+ * Helper to add retry capability to an async function
+ * @param fn async function
+ * @param retryCount max number of retries. defaults to 5
+ * @param retryDelayMS delay in-between retries in millisecs. defaults to 0
+ * @param excludeError predicate fn to exclude specific errors from causing a retry
+ */
+export async function retryPromise<T>(
+  fn: () => Promise<T>,
+  retryCount = DEFAULT_RETRY_COUNT,
+  retryDelayMS = DEFAULT_RETRY_DELAY_MS,
+  excludeError?: (error: Error) => boolean,
+) {
+  try {
+    return await fn();
+  } catch (error) {
+    if (excludeError?.(error as Error)) {
+      throw error;
+    }
+
+    if (retryCount > 0) {
+      await sleep(retryDelayMS);
+
+      // eslint-disable-next-line no-return-await
+      return await retryPromise(fn, retryCount - 1, retryDelayMS);
+    }
+
+    throw error;
+  }
+}

package/src/updateDate.ts

@@ -1,4 +1,4 @@
-import { isValid, getYear, getMonth, getDate, set } from "date-fns";
+import { getDate, getMonth, getYear, isValid, set } from "date-fns";
 /**
  * Updates the date part (year, day and month) of a date object (base)
  * time, offset (timezone) and so on will be left untouched.

package/src/uploadManager/__tests__/index.test.ts

@@ -0,0 +1,302 @@
+/* eslint-disable vitest/no-disabled-tests */
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { newServer } from "mock-xmlhttprequest";
+
+import { createUploadManager } from "..";
+
+describe("uploadManager", () => {
+  const fiftyBytes = new Array(50).fill("A");
+
+  const file = new File(fiftyBytes, "mock-file.txt", {
+    type: "text/plain",
+  });
+
+  type MockXHRHandler = NonNullable<Parameters<typeof newServer>[0]>[string][1];
+
+  const defaultUploadPartResponse: MockXHRHandler = {
+    // status: 200 is the default
+    headers: { "Content-Type": "application/json", Etag: '"partId"' },
+    body: "{}",
+  };
+
+  type Options = {
+    uploadPartResponse?: MockXHRHandler;
+  };
+
+  const setup = ({ uploadPartResponse }: Options = {}) => {
+    const server = newServer({
+      put: ["/success", uploadPartResponse ?? defaultUploadPartResponse],
+    });
+
+    server.install();
+
+    return { server };
+  };
+
+  const mockUploadURLMetadata = { method: "PUT", url: "/success" };
+  const resolveFilePartUploadURL = vi.fn();
+
+  beforeEach(() => {
+    resolveFilePartUploadURL.mockImplementation(() =>
+      Promise.resolve(mockUploadURLMetadata),
+    );
+  });
+
+  const createIdGenerator = () => {
+    const generator = (function* () {
+      let id = 0;
+      while (true) {
+        yield id++;
+      }
+    })();
+
+    return () => `mock-upload--${generator.next().value}`;
+  };
+
+  const getUploadId = createIdGenerator();
+
+  describe("success", () => {
+    it("should handle `uploadFiles`", async () => {
+      setup();
+      const { uploadFiles } = createUploadManager({
+        resolveFilePartUploadURL,
+      });
+
+      const uploadId = getUploadId();
+      const { completed, failed, cancelled } = await uploadFiles([
+        { uploadId, file },
+      ]);
+
+      expect(completed).toEqual([uploadId]);
+      expect(failed.length).toBe(0);
+      expect(cancelled.length).toBe(0);
+      expect(resolveFilePartUploadURL).toHaveBeenCalled();
+    });
+
+    it("should succeed if resolveFilePartUrl is retried successfully", async () => {
+      let callCount = 0;
+      resolveFilePartUploadURL.mockImplementation(() => {
+        callCount++;
+        if (callCount < 2) {
+          return Promise.reject(new Error("error that will be retried"));
+        }
+
+        return Promise.resolve(mockUploadURLMetadata);
+      });
+
+      setup();
+      const { uploadFiles } = createUploadManager({
+        resolveFilePartUploadURL,
+      });
+
+      const uploadId = getUploadId();
+      const { completed, failed, cancelled } = await uploadFiles([
+        { uploadId, file },
+      ]);
+
+      expect(completed).toEqual([uploadId]);
+      expect(failed.length).toBe(0);
+      expect(cancelled.length).toBe(0);
+      expect(resolveFilePartUploadURL).toHaveBeenCalled();
+    });
+
+    it("should succeed if uploadPart request is retried successfully", async () => {
+      let callCount = 0;
+      setup({
+        uploadPartResponse: (request) => {
+          callCount++;
+          if (callCount <= 3) {
+            request.respond(400, {});
+          }
+
+          request.respond(200, { Etag: '"partId"' });
+        },
+      });
+
+      const uploadId = getUploadId();
+      const { uploadFiles } = createUploadManager({
+        resolveFilePartUploadURL,
+      });
+
+      const { completed, failed, cancelled } = await uploadFiles([
+        { uploadId, file },
+      ]);
+
+      expect(completed).toEqual([uploadId]);
+      expect(failed.length).toBe(0);
+      expect(cancelled.length).toBe(0);
+      expect(resolveFilePartUploadURL).toHaveBeenCalled();
+    });
+  });
+
+  describe("callbacks", () => {
+    it("should call onFileUploadComplete", async () => {
+      setup();
+      const onComplete = vi.fn();
+      const onFailed = vi.fn();
+      const { uploadFiles } = createUploadManager({
+        resolveFilePartUploadURL,
+        onFileUploadComplete: onComplete,
+        onFileUploadFailed: onFailed,
+      });
+
+      const uploadId1 = getUploadId();
+      const uploadId2 = getUploadId();
+
+      const { completed, failed, cancelled } = await uploadFiles([
+        { uploadId: uploadId1, file },
+        { uploadId: uploadId2, file },
+      ]);
+
+      expect(completed).toEqual([uploadId1, uploadId2]);
+      expect(failed.length).toBe(0);
+      expect(cancelled.length).toBe(0);
+      expect(onComplete).toHaveBeenCalledWith({
+        uploadId: uploadId1,
+        filePartIds: { 1: "partId" },
+      });
+      expect(onComplete).toHaveBeenCalledWith({
+        uploadId: uploadId2,
+        filePartIds: { 1: "partId" },
+      });
+      expect(onFailed).not.toHaveBeenCalled();
+    });
+
+    it("should call onFileUploadFailed", async () => {
+      setup({
+        uploadPartResponse: (request) => {
+          request.respond(400, {});
+        },
+      });
+      const onComplete = vi.fn();
+      const onFailed = vi.fn();
+      const { uploadFiles } = createUploadManager({
+        resolveFilePartUploadURL,
+        onFileUploadComplete: onComplete,
+        onFileUploadFailed: onFailed,
+      });
+
+      const uploadId1 = getUploadId();
+      const uploadId2 = getUploadId();
+      const { completed, failed, cancelled } = await uploadFiles([
+        { uploadId: uploadId1, file },
+        { uploadId: uploadId2, file },
+      ]);
+
+      expect(completed.length).toBe(0);
+      expect(failed).toEqual([uploadId1, uploadId2]);
+      expect(cancelled.length).toBe(0);
+      expect(onFailed).toHaveBeenCalledWith(
+        uploadId1,
+        new Error("Failed to upload chunk 0"),
+      );
+      expect(onFailed).toHaveBeenCalledWith(
+        uploadId2,
+        new Error("Failed to upload chunk 0"),
+      );
+      expect(onComplete).not.toHaveBeenCalled();
+    });
+
+    it("should call onProgress callback", async () => {
+      setup();
+      const onProgress = vi.fn();
+
+      const { uploadFiles } = createUploadManager({
+        resolveFilePartUploadURL,
+        onProgress,
+      });
+
+      await uploadFiles([{ uploadId: getUploadId(), file }]);
+
+      expect(onProgress).toHaveBeenCalled();
+    });
+  });
+
+  describe("cancellation", () => {
+    it("should handle cancellation", async () => {
+      setup();
+      const { uploadFiles, cancel } = createUploadManager({
+        resolveFilePartUploadURL,
+      });
+
+      const uploadId = getUploadId();
+      const upload = uploadFiles([{ uploadId, file }]);
+
+      cancel(uploadId);
+
+      const { completed, cancelled, failed } = await upload;
+      expect(completed.length).toBe(0);
+      expect(cancelled).toEqual([uploadId]);
+      expect(failed.length).toBe(0);
+    });
+  });
+
+  describe("failures", () => {
+    it("should fail when resolving upload url fails", async () => {
+      resolveFilePartUploadURL.mockImplementation(() =>
+        Promise.reject(new Error("error")),
+      );
+
+      setup();
+      const { uploadFiles } = createUploadManager({
+        resolveFilePartUploadURL,
+      });
+
+      const uploadId = getUploadId();
+      const { completed, failed, cancelled } = await uploadFiles([
+        { uploadId, file },
+      ]);
+
+      expect(completed.length).toBe(0);
+      expect(failed).toEqual([uploadId]);
+      expect(cancelled.length).toBe(0);
+      expect(resolveFilePartUploadURL).toHaveBeenCalled();
+    });
+
+    it("should fail when uploading part request fails", async () => {
+      setup({
+        uploadPartResponse: (request) => {
+          request.respond(400, {});
+        },
+      });
+
+      const { uploadFiles } = createUploadManager({
+        resolveFilePartUploadURL,
+      });
+
+      const uploadId = getUploadId();
+
+      const { completed, failed, cancelled } = await uploadFiles([
+        { uploadId, file },
+      ]);
+
+      expect(completed.length).toBe(0);
+      expect(failed).toEqual([uploadId]);
+      expect(cancelled.length).toBe(0);
+      expect(resolveFilePartUploadURL).toHaveBeenCalled();
+    });
+
+    it("should fail when etag is missing from upload part response", async () => {
+      setup({
+        uploadPartResponse: (request) => {
+          request.respond(200, {});
+        },
+      });
+
+      const { uploadFiles } = createUploadManager({
+        resolveFilePartUploadURL,
+      });
+
+      const uploadId = getUploadId();
+
+      const { completed, failed, cancelled } = await uploadFiles([
+        { uploadId, file },
+      ]);
+
+      expect(completed.length).toBe(0);
+      expect(failed).toEqual([uploadId]);
+      expect(cancelled.length).toBe(0);
+      expect(resolveFilePartUploadURL).toHaveBeenCalled();
+    });
+  });
+});

package/src/uploadManager/index.ts

@@ -0,0 +1,363 @@
+import { AbortError, createAbortablePromise, retryPromise } from "../promise";
+
+// eslint-disable-next-line no-magic-numbers
+const CHUNK_SIZE = 50 * 1024 * 1024; // 50 MB per chunk
+
+const DEFAULT_RETRY_COUNT = 5;
+const DEFAULT_RETRY_DELAY_MS = 50;
+
+export type UploadStateName =
+  | "idle"
+  | "inprogress"
+  | "cancelled"
+  | "failed"
+  | "complete";
+
+export type PartUploadResponse = {
+  partId: string;
+};
+
+const uploadChunkWithProgress = (params: {
+  method: string;
+  url: string;
+  chunk: Blob;
+  chunkIndex: number;
+  onProgress: (progress: number) => void;
+  abortSignal: AbortSignal;
+}) => {
+  const { method, url, chunk, chunkIndex, onProgress, abortSignal } = params;
+
+  const OK = 200;
+
+  return new Promise<{ partId: string }>((resolve, reject) => {
+    const xhr = new XMLHttpRequest();
+
+    xhr.open(method, url, true);
+
+    abortSignal.addEventListener("abort", () => xhr.abort());
+
+    // Track the upload progress of the current chunk
+    xhr.upload.onprogress = (event) => {
+      if (event.lengthComputable) {
+        onProgress(event.loaded);
+      }
+    };
+
+    xhr.onload = () => {
+      if (xhr.status === OK) {
+        const etag = xhr.getResponseHeader("ETag");
+
+        if (!etag) {
+          reject(new Error("Invalid part upload response"));
+          return;
+        }
+
+        // remove possible doublequotes (") around the etag and/or weak identifier (if either is present)
+        // https://datatracker.ietf.org/doc/html/rfc7232#section-2.3
+        resolve({ partId: etag.replace(/^(?:W\/)?"|"$/g, "") });
+      } else {
+        reject(new Error(`Failed to upload chunk ${chunkIndex}`));
+      }
+    };
+
+    xhr.onerror = () =>
+      reject(new Error(`Failed to upload chunk ${chunkIndex}`));
+
+    xhr.send(chunk);
+  });
+};
+
+export type UploaderManagerConfig = {
+  /**
+   * Function to resolve the metadata for a request to upload a file part
+   * @param uploadId
+   * @param partNumber
+   * @returns
+   */
+  resolveFilePartUploadURL: (
+    uploadId: string,
+    partNumber: number,
+  ) => Promise<{ method: string; url: string }>;
+
+  /**
+   * Callback that gets triggered when the whole file is uploaded.
+   * @param
+   * @returns
+   */
+  onFileUploadComplete?: (payload: {
+    /**
+     * Identifier of the upload for this file (must be unique)
+     */
+    uploadId: string;
+    /**
+     * Ids of all the uploaded file parts
+     */
+    filePartIds: Record<number, string>;
+  }) => void;
+
+  /**
+   * Callback that gets triggered when an upload has failed.
+   * @param uploadId
+   * @param error the error that cause the failure if it exists
+   * @returns
+   */
+  onFileUploadFailed?: (uploadId: string, error: Error) => void;
+
+  /**
+   * Callback that gets triggered when the progress of a file part upload
+   * for a specific upload id is updated
+   * @param uploadId
+   * @param progress
+   * @returns
+   */
+  onProgress?: (uploadId: string, progress: number) => void;
+};
+
+type UploadState = {
+  uploadId: string;
+  file: File;
+  completedChunkCount: number;
+  uploadedByteCount: number;
+  state: UploadStateName;
+  abortController: AbortController;
+};
+
+/**
+ * Creates and returns an `uploadManager`, a comprehensive multi-file, multi-part upload handler.
+ *
+ * The `uploadManager` offers functionality for handling file uploads in parts and provides
+ * several built-in mechanisms to ensure the process is reliable and adaptable.
+ *
+ * Key features include:
+ *
+ * - **Chunked File Uploads**: Splits provided files into manageable chunks and initiates the upload
+ *   for each part using the `resolveFilePartUploadURL` function provided in the configuration.
+ *
+ * - **Retry Mechanism**: Automatically retries failed upload attempts up to a maximum of 5 times
+ *   per failed request.
+ *
+ * - **Upload Cancellation**: Allows cancellation of ongoing uploads, giving users control over the process.
+ *
+ * - **Progress Tracking**: Monitors the progress of each file part upload and triggers the `onProgress`
+ *   callback to provide updates.
+ *
+ * - **Error Handling**: The returned `uploadFiles` function does not throw errors directly. Instead,
+ *   it manages retries and stops any failed uploads after the retry limit is reached, marking them as failed.
+ *   This ensures that the promise it returns completes gracefully without uncaught exceptions.
+ *
+ */
+export const createUploadManager = (config: UploaderManagerConfig) => {
+  const {
+    resolveFilePartUploadURL: getUploadFilePartUrl,
+    onFileUploadComplete,
+    onFileUploadFailed,
+  } = config;
+  const uploadStateMap = new Map<string, UploadState>();
+
+  const completedUploads = new Set<string>();
+  const cancelledUploads = new Set<string>();
+  const failedUploads = new Set<string>();
+
+  const assertState = (uploadId: string, state: UploadStateName) =>
+    uploadStateMap.has(uploadId) &&
+    uploadStateMap.get(uploadId)!.state === state;
+
+  const getUploadState = (uploadId: string) => uploadStateMap.get(uploadId);
+  const setUploadState = (uploadId: string, state: Partial<UploadState>) => {
+    uploadStateMap.set(uploadId, {
+      ...uploadStateMap.get(uploadId)!,
+      ...state,
+    });
+  };
+
+  const isFailed = (uploadId: string) => assertState(uploadId, "failed");
+  const isCancelled = (uploadId: string) => assertState(uploadId, "cancelled");
+
+  const getTotalFileParts = (file: File) => Math.ceil(file.size / CHUNK_SIZE);
+
+  const abortInFlightUpload = (uploadId: string, reason: string) => {
+    const currentState = uploadStateMap.get(uploadId);
+
+    if (!currentState) {
+      return;
+    }
+
+    currentState.abortController.abort(
+      new AbortError(
+        `Upload (${currentState.uploadId}) for file "${currentState.file.name}" aborted. Reason: "${reason}"`,
+      ),
+    );
+  };
+
+  const cancel = (uploadId: string) => {
+    if (!uploadStateMap.has(uploadId)) {
+      consola.error("cancel:: Invalid upload id");
+      return;
+    }
+
+    setUploadState(uploadId, { state: "cancelled" });
+
+    abortInFlightUpload(uploadId, "upload cancelled");
+    cancelledUploads.add(uploadId);
+  };
+
+  const setFailed = (uploadId: string, error: Error) => {
+    if (!uploadStateMap.has(uploadId)) {
+      consola.error("failed:: Invalid upload id");
+      return;
+    }
+
+    setUploadState(uploadId, { state: "failed" });
+    onFileUploadFailed?.(uploadId, error);
+    failedUploads.add(uploadId);
+
+    if (completedUploads.has(uploadId)) {
+      completedUploads.delete(uploadId);
+    }
+  };
+
+  const uploadFileFromChunkIndex = async (
+    uploadId: string,
+    file: File,
+    initialChunkIndex = 0,
+  ) => {
+    const totalChunks = getTotalFileParts(file);
+    const totalBytes = file.size;
+    const completedPartIds: Record<number, string> = {};
+
+    const { abortController, runAbortablePromise } = createAbortablePromise();
+
+    uploadStateMap.set(uploadId, {
+      uploadId,
+      file,
+      state: "inprogress",
+      uploadedByteCount: uploadStateMap.get(uploadId)?.uploadedByteCount ?? 0,
+      completedChunkCount:
+        uploadStateMap.get(uploadId)?.completedChunkCount ?? 0,
+      abortController,
+    });
+
+    let chunkIndex = initialChunkIndex;
+    let uploadedBytes = uploadStateMap.get(uploadId)?.uploadedByteCount;
+
+    while (chunkIndex < totalChunks) {
+      if (isCancelled(uploadId) || isFailed(uploadId)) {
+        break;
+      }
+
+      const start = chunkIndex * CHUNK_SIZE;
+      const end = Math.min(start + CHUNK_SIZE, file.size);
+
+      const chunk = file.slice(start, end);
+
+      try {
+        const { method, url } = await retryPromise(
+          () => getUploadFilePartUrl(uploadId, chunkIndex + 1),
+          DEFAULT_RETRY_COUNT,
+          DEFAULT_RETRY_DELAY_MS,
+        );
+
+        consola.trace("File part upload url resolved", { method, url });
+
+        const onChunkUploadProgress = (uploadedChunkBytes: number) => {
+          uploadedBytes = uploadedChunkBytes + start;
+          setUploadState(uploadId, { uploadedByteCount: uploadedBytes });
+
+          const progress = Math.round((uploadedBytes / totalBytes) * 100);
+
+          config.onProgress?.(uploadId, progress);
+        };
+
+        const filePartResponse = await runAbortablePromise(() =>
+          retryPromise(
+            () =>
+              uploadChunkWithProgress({
+                method,
+                url,
+                chunk,
+                chunkIndex,
+                onProgress: onChunkUploadProgress,
+                abortSignal: abortController.signal,
+              }),
+            DEFAULT_RETRY_COUNT,
+            DEFAULT_RETRY_DELAY_MS,
+          ),
+        );
+
+        consola.trace(
+          `${file.name}: Chunk ${chunkIndex + 1} of ${totalChunks} uploaded successfully`,
+        );
+
+        completedPartIds[chunkIndex + 1] = filePartResponse.partId;
+
+        setUploadState(uploadId, {
+          completedChunkCount:
+            uploadStateMap.get(uploadId)!.completedChunkCount + 1,
+        });
+      } catch (error) {
+        if (error instanceof AbortError) {
+          consola.info("Aborted::", error);
+          return;
+        }
+
+        setFailed(
+          uploadId,
+          error instanceof Error ? error : new Error(error as any),
+        );
+        return;
+      }
+
+      chunkIndex++;
+    }
+
+    if (isCancelled(uploadId) || isFailed(uploadId)) {
+      return;
+    }
+
+    setUploadState(uploadId, {
+      completedChunkCount: totalChunks,
+      state: "complete",
+    });
+    completedUploads.add(uploadId);
+    onFileUploadComplete?.({ uploadId, filePartIds: completedPartIds });
+  };
+
+  const uploadFiles = (files: Array<{ uploadId: string; file: File }>) => {
+    const result: Array<Promise<any>> = [];
+
+    for (const { uploadId, file } of files) {
+      result.push(uploadFileFromChunkIndex(uploadId, file));
+    }
+
+    return Promise.allSettled(result).then(() => {
+      // state cleanup
+      const completed = [...completedUploads.values()];
+      const cancelled = [...cancelledUploads.values()];
+      const failed = [...failedUploads.values()];
+
+      [...completed, ...cancelled, ...failed].forEach((uploadId) =>
+        uploadStateMap.delete(uploadId),
+      );
+
+      completedUploads.clear();
+      cancelledUploads.clear();
+      failedUploads.clear();
+
+      return {
+        completed,
+        cancelled,
+        failed,
+      };
+    });
+  };
+
+  return {
+    uploadFiles,
+
+    getUploadState,
+    isFailed,
+    isCancelled,
+    cancel,
+    setFailed,
+  };
+};