@uploadista/client-core 0.1.2 → 0.1.3-beta.10

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@uploadista/client-core",
   "type": "module",
-  "version": "0.1.2",
+  "version": "0.1.3-beta.10",
   "description": "Platform-agnostic core upload client logic for Uploadista",
   "license": "MIT",
   "author": "Uploadista",
@@ -33,16 +33,16 @@
   },
   "dependencies": {
     "js-base64": "3.7.8",
-    "@uploadista/core": "0.1.2"
+    "@uploadista/core": "0.1.3-beta.10"
   },
   "peerDependencies": {
     "zod": "^4.0.0"
   },
   "devDependencies": {
-    "tsdown": "0.19.0",
-    "vitest": "4.0.17",
-    "zod": "4.3.5",
-    "@uploadista/typescript-config": "0.1.2"
+    "tsdown": "0.20.1",
+    "vitest": "4.0.18",
+    "zod": "4.3.6",
+    "@uploadista/typescript-config": "0.1.3-beta.10"
   },
   "scripts": {
     "build": "tsc --noEmit && tsdown",

package/src/client/create-uploadista-client.ts

@@ -9,7 +9,10 @@ import type { Logger } from "../logger";
 import { createLogger } from "../logger";
 import { defaultClientCapabilities } from "../mock-data-store";
 import { NetworkMonitor, type NetworkMonitorConfig } from "../network-monitor";
-import type { AbortControllerFactory } from "../services/abort-controller-service";
+import {
+  type AbortControllerFactory,
+  PausableAbortController,
+} from "../services/abort-controller-service";
 import type { ChecksumService } from "../services/checksum-service";
 import type { FileReaderService } from "../services/file-reader-service";
 import type { FingerprintService } from "../services/fingerprint-service";
@@ -671,13 +674,15 @@ export function createUploadistaClient<UploadInput>({
       onShouldRetry,
       onJobStart,
       onError,
+      onAbort,
     }: Omit<
       UploadistaUploadOptions,
       "uploadLengthDeferred" | "uploadSize" | "metadata"
-    > = {},
+    > & { onAbort?: () => void } = {},
   ): Promise<{
     abort: () => Promise<void>;
     pause: () => Promise<void>;
+    resume: () => Promise<void>;
     jobId: string;
   }> => {
     const source = await fileReader.openFile(file, chunkSize);
@@ -712,12 +717,17 @@ export function createUploadistaClient<UploadInput>({
       return {
         abort: async () => {},
         pause: async () => {},
+        resume: async () => {},
         jobId: "",
       };
     }
 
     const { jobId, uploadFile, inputNodeId } = result;
-    const abortController = abortControllerFactory.create();
+    // Use PausableAbortController to support pausing chunk uploads
+    // Pass a real AbortController from the factory to ensure fetch compatibility
+    const abortController = new PausableAbortController(
+      abortControllerFactory.create(),
+    );
 
     // Open upload WebSocket to receive upload progress events
     await wsManager.openUploadWebSocket(uploadFile.id);
@@ -742,6 +752,7 @@ export function createUploadistaClient<UploadInput>({
       onChunkComplete,
       onSuccess,
       onShouldRetry,
+      onAbort,
       onRetry: (timeout) => {
         timeoutId = timeout;
       },
@@ -769,7 +780,13 @@ export function createUploadistaClient<UploadInput>({
         wsManager.closeUploadWebSocket(uploadFile.id);
       },
       pause: async () => {
-        await uploadistaApi.pauseFlow(jobId);
+        // Pause client-side chunk uploads immediately
+        // This will cause the upload loop to wait at the start of the next chunk
+        abortController.pause();
+      },
+      resume: async () => {
+        // Resume client-side chunk uploads
+        abortController.resume();
       },
       jobId,
     };
@@ -812,6 +829,7 @@ export function createUploadistaClient<UploadInput>({
   ): Promise<{
     abort: () => Promise<void>;
     pause: () => Promise<void>;
+    resume: () => Promise<void>;
     jobId: string;
   }> => {
     // Start the flow and get job ID
@@ -905,7 +923,11 @@ export function createUploadistaClient<UploadInput>({
             input.inputType === "file" && input.uploadFile && input.source,
         )
         .map(async ({ nodeId, uploadFile, source }) => {
-          const abortController = abortControllerFactory.create();
+          // Use PausableAbortController to support pausing chunk uploads
+          // Pass a real AbortController from the factory to ensure fetch compatibility
+          const abortController = new PausableAbortController(
+            abortControllerFactory.create(),
+          );
           abortControllers.set(nodeId, abortController);
 
           const metrics = new UploadMetrics({
@@ -1009,7 +1031,23 @@ export function createUploadistaClient<UploadInput>({
         }
       },
       pause: async () => {
-        await uploadistaApi.pauseFlow(jobId);
+        // Pause all client-side chunk uploads
+        for (const controller of abortControllers.values()) {
+          if ("pause" in controller && typeof controller.pause === "function") {
+            controller.pause();
+          }
+        }
+      },
+      resume: async () => {
+        // Resume all client-side chunk uploads
+        for (const controller of abortControllers.values()) {
+          if (
+            "resume" in controller &&
+            typeof controller.resume === "function"
+          ) {
+            controller.resume();
+          }
+        }
       },
       jobId,
     };

package/src/managers/flow-manager.ts

@@ -6,7 +6,7 @@ import { detectInputType } from "../utils/input-detection";
 
 /**
  * Flow upload status representing the current state of a flow upload lifecycle.
- * Flow uploads progress through: idle → uploading → processing → success/error/aborted
+ * Flow uploads progress through: idle → uploading → processing → success/error/aborted/paused
  */
 export type FlowUploadStatus =
   | "idle"
@@ -14,7 +14,8 @@ export type FlowUploadStatus =
   | "processing"
   | "success"
   | "error"
-  | "aborted";
+  | "aborted"
+  | "paused";
 
 /**
  * Complete state information for a flow upload operation.
@@ -45,6 +46,8 @@ export interface FlowUploadState {
    * Available when status is "success".
    */
   flowOutputs: TypedOutput[] | null;
+  /** Node ID where the flow was paused (available when status is "paused") */
+  pausedAtNodeId: string | null;
 }
 
 /**
@@ -146,6 +149,11 @@ export interface FlowManagerCallbacks {
    * Called when upload or flow is aborted
    */
   onAbort?: () => void;
+
+  /**
+   * Called when flow is paused
+   */
+  onPause?: () => void;
 }
 
 /**
@@ -176,6 +184,7 @@ export interface FlowConfig {
 export interface FlowUploadAbortController {
   abort: () => void | Promise<void>;
   pause: () => void | Promise<void>;
+  resume: () => void | Promise<void>;
 }
 
 /**
@@ -293,6 +302,7 @@ const initialState: FlowUploadState = {
   currentNodeName: null,
   currentNodeType: null,
   flowOutputs: null,
+  pausedAtNodeId: null,
 };
 
 /**
@@ -378,6 +388,13 @@ export class FlowManager<TInput = FlowUploadInput> {
     return this.state.status === "processing";
   }
 
+  /**
+   * Check if flow is paused
+   */
+  isPaused(): boolean {
+    return this.state.status === "paused";
+  }
+
   /**
    * Get the current job ID
    */
@@ -385,6 +402,13 @@ export class FlowManager<TInput = FlowUploadInput> {
     return this.state.jobId;
   }
 
+  /**
+   * Get the node ID where the flow is paused (if applicable)
+   */
+  getPausedAtNodeId(): string | null {
+    return this.state.pausedAtNodeId;
+  }
+
   /**
    * Update the internal state and notify callbacks
    */
@@ -516,6 +540,14 @@ export class FlowManager<TInput = FlowUploadInput> {
         this.callbacks.onAbort?.();
         this.abortController = null;
         break;
+
+      case EventType.FlowPause:
+        this.updateState({
+          status: "paused",
+          pausedAtNodeId: event.pausedAt ?? null,
+        });
+        this.callbacks.onPause?.();
+        break;
     }
   }
 
@@ -723,22 +755,81 @@ export class FlowManager<TInput = FlowUploadInput> {
   }
 
   /**
-   * Abort the current flow upload
+   * Abort the current flow upload.
+   * This will:
+   * 1. Cancel the flow on the server
+   * 2. Abort any in-progress chunk uploads
+   * 3. Close WebSocket connections
    */
-  abort(): void {
+  async abort(): Promise<void> {
     if (this.abortController) {
-      this.abortController.abort();
+      await this.abortController.abort();
       // Note: State update happens in onAbort callback or FlowCancel event
     }
   }
 
   /**
-   * Pause the current flow upload
+   * Pause the current flow upload.
+   * During upload phase: Pauses chunk uploads client-side.
+   * During processing phase: Calls server to pause flow execution.
    */
-  pause(): void {
-    if (this.abortController) {
-      this.abortController.pause();
+  async pause(): Promise<void> {
+    // Only pause if we're actively uploading or processing
+    if (
+      this.state.status !== "uploading" &&
+      this.state.status !== "processing"
+    ) {
+      return;
     }
+
+    // Call abort controller's pause method if available
+    // This pauses chunk uploads during upload phase
+    if (this.abortController?.pause) {
+      try {
+        await this.abortController.pause();
+      } catch {
+        // If pause fails, continue with state update
+      }
+    }
+
+    // Update client state to paused
+    this.updateState({
+      status: "paused",
+      pausedAtNodeId: this.state.currentNodeName ?? null,
+    });
+  }
+
+  /**
+   * Resume a paused flow upload.
+   * Continues chunk uploads if paused during upload phase.
+   */
+  async resume(): Promise<void> {
+    // Only resume if we're paused
+    if (this.state.status !== "paused") {
+      return;
+    }
+
+    // Determine what status to resume to
+    // If we had started uploading, resume to uploading state
+    // Otherwise, this shouldn't happen (can only pause during upload/processing)
+    const resumeStatus: "uploading" | "processing" =
+      this.state.flowStarted ? "processing" : "uploading";
+
+    // Call abort controller's resume method if available
+    // This allows chunk uploads to continue
+    if (this.abortController?.resume) {
+      try {
+        await this.abortController.resume();
+      } catch {
+        // If resume fails, continue with state update
+      }
+    }
+
+    // Update client state to resume previous status
+    this.updateState({
+      status: resumeStatus,
+      pausedAtNodeId: null,
+    });
   }
 
   /**

package/src/services/abort-controller-service.ts

@@ -5,6 +5,23 @@
 export interface AbortControllerLike {
   readonly signal: AbortSignalLike;
   abort(reason?: unknown): void;
+  /**
+   * Pause the operation (optional, may not be supported by all implementations)
+   */
+  pause?(): void;
+  /**
+   * Resume a paused operation (optional, may not be supported by all implementations)
+   */
+  resume?(): void;
+  /**
+   * Whether the operation is currently paused
+   */
+  readonly isPaused?: boolean;
+  /**
+   * Wait for resume to be called (returns immediately if not paused)
+   * Used by upload loops to pause between chunk uploads
+   */
+  waitForResume?(): Promise<void>;
 }
 
 export interface AbortSignalLike {
@@ -19,3 +36,92 @@ export interface AbortControllerFactory {
    */
   create(): AbortControllerLike;
 }
+
+/**
+ * A wrapper that adds pause/resume functionality to an AbortController.
+ * Used by FlowManager and upload loops to support pausing chunk uploads.
+ *
+ * IMPORTANT: This class requires an inner AbortController to be provided.
+ * The inner controller's signal is used directly, which ensures compatibility
+ * with browser's fetch API (which requires a real AbortSignal).
+ */
+export class PausableAbortController implements AbortControllerLike {
+  private _isPaused = false;
+  private _resumeResolvers: Array<() => void> = [];
+  private readonly _innerController: AbortControllerLike;
+
+  /**
+   * Create a PausableAbortController that wraps an inner AbortController.
+   *
+   * @param innerController - The inner AbortController to wrap. This should be
+   *   a real AbortController (from the browser or platform) so that its signal
+   *   is compatible with fetch API.
+   */
+  constructor(innerController: AbortControllerLike) {
+    this._innerController = innerController;
+  }
+
+  /**
+   * Returns the inner controller's signal directly.
+   * This ensures compatibility with browser's fetch API which requires a real AbortSignal.
+   */
+  get signal(): AbortSignalLike {
+    return this._innerController.signal;
+  }
+
+  get isPaused(): boolean {
+    return this._isPaused;
+  }
+
+  abort(reason?: unknown): void {
+    // When aborting, also resolve any pending waitForResume promises
+    // so the upload loop can exit cleanly
+    for (const resolve of this._resumeResolvers) {
+      resolve();
+    }
+    this._resumeResolvers = [];
+
+    // Delegate to inner controller
+    this._innerController.abort(reason);
+  }
+
+  pause(): void {
+    this._isPaused = true;
+  }
+
+  resume(): void {
+    this._isPaused = false;
+    // Resolve all pending waitForResume promises
+    for (const resolve of this._resumeResolvers) {
+      resolve();
+    }
+    this._resumeResolvers = [];
+  }
+
+  /**
+   * Returns a promise that resolves when resume() is called.
+   * If not paused, resolves immediately.
+   * If aborted while waiting, resolves immediately (caller should check signal.aborted).
+   */
+  waitForResume(): Promise<void> {
+    if (!this._isPaused || this._innerController.signal.aborted) {
+      return Promise.resolve();
+    }
+
+    return new Promise<void>((resolve) => {
+      this._resumeResolvers.push(resolve);
+    });
+  }
+}
+
+/**
+ * Helper function to wait for resume if the controller supports it.
+ * Returns immediately if the controller doesn't support pause or isn't paused.
+ */
+export async function waitForResumeIfPaused(
+  controller: AbortControllerLike,
+): Promise<void> {
+  if (controller.isPaused && controller.waitForResume) {
+    await controller.waitForResume();
+  }
+}

package/src/upload/flow-upload.ts

@@ -8,6 +8,7 @@ import type { PlatformService, Timeout } from "../services/platform-service";
 import type { SmartChunker, SmartChunkerConfig } from "../smart-chunker";
 import type { FlowUploadConfig } from "../types/flow-upload-config";
 
+import { waitForResumeIfPaused } from "../services/abort-controller-service";
 import { shouldRetry } from "./chunk-upload";
 import type { Callbacks } from "./single-upload";
 import type { UploadMetrics } from "./upload-metrics";
@@ -185,6 +186,16 @@ export async function performFlowUpload({
   let currentOffset = offset;
 
   try {
+    // Check if paused before starting chunk upload
+    // This allows the upload loop to pause between chunks
+    await waitForResumeIfPaused(abortController);
+
+    // Check if aborted after waiting for resume
+    if (abortController.signal.aborted) {
+      callbacks.onAbort?.();
+      return;
+    }
+
     // Get optimal chunk size
     const remainingBytes = source.size ? source.size - offset : undefined;
     const chunkSizeDecision = smartChunker.getNextChunkSize(remainingBytes);
@@ -306,6 +317,20 @@ export async function performFlowUpload({
       ...callbacks,
     });
   } catch (err) {
+    // Check if this is an abort error (from fetch being cancelled)
+    const isAbortError =
+      abortController.signal.aborted ||
+      (err instanceof Error &&
+        (err.name === "AbortError" ||
+          (err as { code?: number }).code === 20 || // DOMException.ABORT_ERR
+          err.message?.includes("abort")));
+
+    if (isAbortError) {
+      logger.log(`Flow upload aborted for job ${jobId}`);
+      callbacks.onAbort?.();
+      return;
+    }
+
     // Retry logic similar to single-upload
     if (retryDelays != null) {
       const shouldResetDelays =

package/src/upload/single-upload.ts

@@ -10,6 +10,7 @@ import type { PlatformService, Timeout } from "../services/platform-service";
 import type { WebSocketLike } from "../services/websocket-service";
 import type { SmartChunker, SmartChunkerConfig } from "../smart-chunker";
 import type { ClientStorage } from "../storage/client-storage";
+import { waitForResumeIfPaused } from "../services/abort-controller-service";
 import {
   type OnProgress,
   type OnShouldRetry,
@@ -32,6 +33,7 @@ export type Callbacks = {
   ) => void;
   onSuccess?: (payload: UploadFile) => void;
   onError?: (error: Error | UploadistaError) => void;
+  onAbort?: () => void;
   onStart?: (file: { uploadId: string; size: number | null }) => void;
   onJobStart?: (jobId: string) => void;
   onShouldRetry?: OnShouldRetry;
@@ -84,6 +86,15 @@ export async function performUpload({
   let currentOffset = offset;
 
   try {
+    // Check if paused before starting chunk upload
+    // This allows the upload loop to pause between chunks
+    await waitForResumeIfPaused(abortController);
+
+    // Check if aborted after waiting for resume
+    if (abortController.signal.aborted) {
+      return;
+    }
+
     const res = await uploadChunk({
       uploadId,
       source,