@uploadista/client-core 0.0.13 → 0.0.14

package/src/managers/upload-manager.ts

@@ -0,0 +1,353 @@
+import type { UploadFile } from "@uploadista/core/types";
+import type { UploadOptions } from "../types/upload-options";
+
+/**
+ * Upload status representing the current state of an upload
+ */
+export type UploadStatus =
+  | "idle"
+  | "uploading"
+  | "success"
+  | "error"
+  | "aborted";
+
+/**
+ * Complete upload state
+ */
+export interface UploadState {
+  /** Current status of the upload */
+  status: UploadStatus;
+  /** Upload progress percentage (0-100) */
+  progress: number;
+  /** Number of bytes uploaded */
+  bytesUploaded: number;
+  /** Total bytes to upload, null if unknown/deferred */
+  totalBytes: number | null;
+  /** Error if upload failed */
+  error: Error | null;
+  /** Result if upload succeeded */
+  result: UploadFile | null;
+}
+
+/**
+ * Callbacks that UploadManager invokes during the upload lifecycle
+ */
+export interface UploadManagerCallbacks {
+  /**
+   * Called when the upload state changes
+   */
+  onStateChange: (state: UploadState) => void;
+
+  /**
+   * Called when upload progress updates
+   * @param uploadId - The unique identifier for this upload
+   * @param bytesUploaded - Number of bytes uploaded
+   * @param totalBytes - Total bytes to upload, null if unknown
+   */
+  onProgress?: (
+    uploadId: string,
+    bytesUploaded: number,
+    totalBytes: number | null,
+  ) => void;
+
+  /**
+   * Called when a chunk completes
+   * @param chunkSize - Size of the completed chunk
+   * @param bytesAccepted - Total bytes accepted so far
+   * @param bytesTotal - Total bytes to upload, null if unknown
+   */
+  onChunkComplete?: (
+    chunkSize: number,
+    bytesAccepted: number,
+    bytesTotal: number | null,
+  ) => void;
+
+  /**
+   * Called when upload completes successfully
+   * @param result - The uploaded file result
+   */
+  onSuccess?: (result: UploadFile) => void;
+
+  /**
+   * Called when upload fails with an error
+   * @param error - The error that occurred
+   */
+  onError?: (error: Error) => void;
+
+  /**
+   * Called when upload is aborted
+   */
+  onAbort?: () => void;
+}
+
+/**
+ * Generic upload input type - can be any value that the upload client accepts
+ */
+export type UploadInput = unknown;
+
+/**
+ * Abort controller interface for canceling uploads
+ */
+export interface UploadAbortController {
+  abort: () => void;
+}
+
+/**
+ * Upload function that performs the actual upload.
+ * Returns a promise that resolves to an abort controller.
+ */
+export type UploadFunction<
+  TInput = UploadInput,
+  TOptions extends UploadOptions = UploadOptions,
+> = (input: TInput, options: TOptions) => Promise<UploadAbortController>;
+
+/**
+ * Initial state for a new upload
+ */
+const initialState: UploadState = {
+  status: "idle",
+  progress: 0,
+  bytesUploaded: 0,
+  totalBytes: null,
+  error: null,
+  result: null,
+};
+
+/**
+ * Platform-agnostic upload manager that handles upload state machine,
+ * progress tracking, error handling, abort, reset, and retry logic.
+ *
+ * Framework packages (React, Vue, React Native) should wrap this manager
+ * with framework-specific hooks/composables.
+ *
+ * @example
+ * ```typescript
+ * const uploadFn = (input, options) => client.upload(input, options);
+ * const manager = new UploadManager(uploadFn, {
+ *   onStateChange: (state) => setState(state),
+ *   onProgress: (progress) => console.log(`${progress}%`),
+ *   onSuccess: (result) => console.log('Upload complete:', result),
+ *   onError: (error) => console.error('Upload failed:', error),
+ * });
+ *
+ * await manager.upload(file);
+ * ```
+ */
+export class UploadManager<
+  TInput = UploadInput,
+  TOptions extends UploadOptions = UploadOptions,
+> {
+  private state: UploadState;
+  private abortController: UploadAbortController | null = null;
+  private lastInput: TInput | null = null;
+  private uploadId: string | null = null;
+
+  /**
+   * Create a new UploadManager
+   *
+   * @param uploadFn - Upload function to use for uploads
+   * @param callbacks - Callbacks to invoke during upload lifecycle
+   * @param options - Upload configuration options
+   */
+  constructor(
+    private readonly uploadFn: UploadFunction<TInput, TOptions>,
+    private readonly callbacks: UploadManagerCallbacks,
+    private readonly options?: TOptions,
+  ) {
+    this.state = { ...initialState };
+  }
+
+  /**
+   * Get the current upload state
+   */
+  getState(): UploadState {
+    return { ...this.state };
+  }
+
+  /**
+   * Check if an upload is currently active
+   */
+  isUploading(): boolean {
+    return this.state.status === "uploading";
+  }
+
+  /**
+   * Check if the upload can be retried
+   */
+  canRetry(): boolean {
+    return (
+      (this.state.status === "error" || this.state.status === "aborted") &&
+      this.lastInput !== null
+    );
+  }
+
+  /**
+   * Update the internal state and notify callbacks
+   */
+  private updateState(update: Partial<UploadState>): void {
+    this.state = { ...this.state, ...update };
+    this.callbacks.onStateChange(this.state);
+  }
+
+  /**
+   * Start uploading a file or input
+   *
+   * @param input - File or input to upload (type depends on platform)
+   */
+  async upload(input: TInput): Promise<void> {
+    // Determine totalBytes from input if possible (File/Blob on browser platforms)
+    let totalBytes: number | null = null;
+    if (input && typeof input === "object") {
+      if ("size" in input && typeof input.size === "number") {
+        totalBytes = input.size;
+      }
+    }
+
+    // Reset state but keep reference for retries
+    this.updateState({
+      status: "uploading",
+      progress: 0,
+      bytesUploaded: 0,
+      totalBytes,
+      error: null,
+      result: null,
+    });
+
+    this.lastInput = input;
+
+    try {
+      // Build complete options with our callbacks
+      const uploadOptions = {
+        ...this.options,
+        onProgress: (
+          uploadId: string,
+          bytesUploaded: number,
+          bytes: number | null,
+        ) => {
+          // Store uploadId on first progress callback
+          if (!this.uploadId) {
+            this.uploadId = uploadId;
+          }
+
+          const progressPercent = bytes
+            ? Math.round((bytesUploaded / bytes) * 100)
+            : 0;
+
+          this.updateState({
+            progress: progressPercent,
+            bytesUploaded,
+            totalBytes: bytes,
+          });
+
+          this.callbacks.onProgress?.(uploadId, bytesUploaded, bytes);
+          this.options?.onProgress?.(uploadId, bytesUploaded, bytes);
+        },
+        onChunkComplete: (
+          chunkSize: number,
+          bytesAccepted: number,
+          bytesTotal: number | null,
+        ) => {
+          this.callbacks.onChunkComplete?.(
+            chunkSize,
+            bytesAccepted,
+            bytesTotal,
+          );
+          this.options?.onChunkComplete?.(chunkSize, bytesAccepted, bytesTotal);
+        },
+        onSuccess: (result: UploadFile) => {
+          this.updateState({
+            status: "success",
+            result,
+            progress: 100,
+            bytesUploaded: result.size || 0,
+            totalBytes: result.size || null,
+          });
+
+          this.callbacks.onSuccess?.(result);
+          this.options?.onSuccess?.(result);
+          this.abortController = null;
+        },
+        onError: (error: Error) => {
+          this.updateState({
+            status: "error",
+            error,
+          });
+
+          this.callbacks.onError?.(error);
+          this.options?.onError?.(error);
+          this.abortController = null;
+        },
+        onAbort: () => {
+          this.updateState({
+            status: "aborted",
+          });
+
+          this.callbacks.onAbort?.();
+          this.options?.onAbort?.();
+          this.abortController = null;
+        },
+        onShouldRetry: this.options?.onShouldRetry,
+      } as TOptions;
+
+      // Start the upload
+      this.abortController = await this.uploadFn(input, uploadOptions);
+    } catch (error) {
+      // Handle errors from upload initiation
+      const uploadError =
+        error instanceof Error ? error : new Error(String(error));
+      this.updateState({
+        status: "error",
+        error: uploadError,
+      });
+
+      this.callbacks.onError?.(uploadError);
+      this.options?.onError?.(uploadError);
+      this.abortController = null;
+    }
+  }
+
+  /**
+   * Abort the current upload
+   */
+  abort(): void {
+    if (this.abortController) {
+      this.abortController.abort();
+      // Note: State update happens in onAbort callback
+    }
+  }
+
+  /**
+   * Reset the upload state to idle
+   */
+  reset(): void {
+    if (this.abortController) {
+      this.abortController.abort();
+      this.abortController = null;
+    }
+
+    this.state = { ...initialState };
+    this.lastInput = null;
+    this.uploadId = null;
+    this.callbacks.onStateChange(this.state);
+  }
+
+  /**
+   * Retry the last failed or aborted upload
+   */
+  retry(): void {
+    if (this.canRetry() && this.lastInput !== null) {
+      this.upload(this.lastInput);
+    }
+  }
+
+  /**
+   * Clean up resources (call when disposing the manager)
+   */
+  cleanup(): void {
+    if (this.abortController) {
+      this.abortController.abort();
+      this.abortController = null;
+    }
+    this.uploadId = null;
+  }
+}

package/src/services/service-container.ts

@@ -7,18 +7,230 @@ import type { IdGenerationService } from "./id-generation-service";
 import type { PlatformService } from "./platform-service";
 import type { StorageService } from "./storage-service";
 import type { WebSocketFactory } from "./websocket-service";
+
 /**
- * Service container for dependency injection
+ * Service container for dependency injection in the Uploadista client.
+ *
+ * This container provides all platform-specific services needed by the upload client.
+ * Different platforms (browser, React Native, Node.js) provide their own implementations
+ * of these services to handle platform-specific APIs and behaviors.
+ *
+ * @template UploadInput - The type of input accepted by the file reader (e.g., File, Blob, string path)
+ *
+ * @example Browser implementation
+ * ```typescript
+ * const services: ServiceContainer<File | Blob> = {
+ *   storage: new LocalStorageService(),
+ *   idGeneration: new BrowserIdGenerationService(),
+ *   httpClient: new FetchHttpClient(),
+ *   fileReader: new BrowserFileReaderService(),
+ *   base64: new BrowserBase64Service(),
+ *   websocket: new BrowserWebSocketFactory(),
+ *   abortController: new BrowserAbortControllerFactory(),
+ *   platform: new BrowserPlatformService(),
+ *   checksumService: new WebCryptoChecksumService(),
+ *   fingerprintService: new BrowserFingerprintService(),
+ * };
+ * ```
+ *
+ * @example React Native implementation
+ * ```typescript
+ * const services: ServiceContainer<FilePickResult> = {
+ *   storage: new AsyncStorageService(),
+ *   idGeneration: new ReactNativeIdGenerationService(),
+ *   httpClient: new FetchHttpClient(),
+ *   fileReader: new ReactNativeFileReaderService(),
+ *   websocket: new ReactNativeWebSocketFactory(),
+ *   abortController: new ReactNativeAbortControllerFactory(),
+ *   platform: new ReactNativePlatformService(),
+ *   checksumService: new ReactNativeChecksumService(),
+ *   fingerprintService: new ReactNativeFingerprintService(),
+ * };
+ * ```
  */
 export interface ServiceContainer<UploadInput> {
+  /**
+   * Storage service for persisting upload state and metadata.
+   *
+   * **Required**: Yes
+   *
+   * **Used for**:
+   * - Storing upload progress for resumption
+   * - Caching upload fingerprints
+   * - Persisting partial upload state across sessions
+   *
+   * **Platform implementations**:
+   * - Browser: `localStorage`, `IndexedDB`
+   * - React Native: `AsyncStorage`, `MMKV`
+   * - Node.js: File system, Redis
+   */
   storage: StorageService;
+
+  /**
+   * ID generation service for creating unique identifiers.
+   *
+   * **Required**: Yes
+   *
+   * **Used for**:
+   * - Generating upload IDs
+   * - Creating request correlation IDs
+   * - Generating chunk identifiers
+   *
+   * **Platform implementations**:
+   * - Browser: `crypto.randomUUID()` or fallback
+   * - React Native: UUID libraries
+   * - Node.js: `crypto.randomUUID()`
+   */
   idGeneration: IdGenerationService;
+
+  /**
+   * HTTP client for making upload requests.
+   *
+   * **Required**: Yes
+   *
+   * **Used for**:
+   * - Uploading file chunks
+   * - Making API calls to the upload server
+   * - Fetching upload metadata
+   *
+   * **Platform implementations**:
+   * - Browser: `fetch()` with connection pooling
+   * - React Native: `fetch()` or `XMLHttpRequest`
+   * - Node.js: `node:http`, `node:https`, or libraries like `undici`
+   *
+   * **Important**: Should support connection pooling for optimal performance
+   */
   httpClient: HttpClient;
+
+  /**
+   * File reader service for reading file contents.
+   *
+   * **Required**: Yes
+   *
+   * **Used for**:
+   * - Reading file data for upload
+   * - Slicing files into chunks
+   * - Computing file checksums and fingerprints
+   *
+   * **Platform implementations**:
+   * - Browser: `FileReader` API, `Blob.slice()`
+   * - React Native: Native file system modules, `react-native-fs`
+   * - Node.js: `fs.createReadStream()`, `fs.promises.open()`
+   *
+   * **Generic type**: Accepts platform-specific input types (File, Blob, path string)
+   */
   fileReader: FileReaderService<UploadInput>;
+
+  /**
+   * Base64 encoding/decoding service.
+   *
+   * **Required**: No (optional)
+   *
+   * **Used for**:
+   * - Encoding binary data for transport
+   * - Decoding server responses
+   * - Optional data transformations
+   *
+   * **Platform implementations**:
+   * - Browser: `btoa()`, `atob()`
+   * - React Native: `base64-js` or built-in
+   * - Node.js: `Buffer.from().toString('base64')`
+   *
+   * **Note**: Only needed for specific upload protocols that require base64 encoding
+   */
   base64?: Base64Service;
+
+  /**
+   * WebSocket factory for creating WebSocket connections.
+   *
+   * **Required**: Yes
+   *
+   * **Used for**:
+   * - Real-time upload progress updates
+   * - Server-side event notifications
+   * - Live upload status from server
+   *
+   * **Platform implementations**:
+   * - Browser: Native `WebSocket` API
+   * - React Native: `react-native-websocket` or polyfills
+   * - Node.js: `ws` library
+   *
+   * **Important**: Must support standard WebSocket protocol
+   */
   websocket: WebSocketFactory;
+
+  /**
+   * Abort controller factory for creating cancellation tokens.
+   *
+   * **Required**: Yes
+   *
+   * **Used for**:
+   * - Aborting in-flight upload requests
+   * - Cancelling file read operations
+   * - Implementing upload timeout logic
+   *
+   * **Platform implementations**:
+   * - Browser: Native `AbortController` API
+   * - React Native: `AbortController` polyfill
+   * - Node.js: Native `AbortController` (Node 15+)
+   */
   abortController: AbortControllerFactory;
+
+  /**
+   * Platform detection service.
+   *
+   * **Required**: Yes
+   *
+   * **Used for**:
+   * - Detecting runtime environment (browser, React Native, Node.js)
+   * - Applying platform-specific optimizations
+   * - Conditional feature availability
+   *
+   * **Platform implementations**:
+   * - Browser: Checks `window`, `document` availability
+   * - React Native: Checks `navigator.product === 'ReactNative'`
+   * - Node.js: Checks `process` availability
+   */
   platform: PlatformService;
+
+  /**
+   * Checksum service for computing file checksums.
+   *
+   * **Required**: Yes
+   *
+   * **Used for**:
+   * - Verifying upload integrity
+   * - Detecting corrupted uploads
+   * - Implementing upload deduplication
+   *
+   * **Platform implementations**:
+   * - Browser: `crypto.subtle` Web Crypto API
+   * - React Native: Native crypto modules or JavaScript implementations
+   * - Node.js: `crypto` module
+   *
+   * **Common algorithms**: SHA-256, MD5, CRC32
+   */
   checksumService: ChecksumService;
+
+  /**
+   * Fingerprint service for generating unique file identifiers.
+   *
+   * **Required**: Yes
+   *
+   * **Used for**:
+   * - Upload resumption (matching partial uploads)
+   * - Deduplication (detecting duplicate files)
+   * - Cache key generation
+   *
+   * **Platform implementations**:
+   * - Browser: Combines file metadata (size, name, modified date, first/last bytes)
+   * - React Native: Similar to browser but uses platform-specific file APIs
+   * - Node.js: File stat info + content sampling
+   *
+   * **Generic type**: Accepts platform-specific input types
+   *
+   * **Note**: Fingerprints should be stable (same file = same fingerprint) but
+   * fast to compute (avoid reading entire file if possible)
+   */
   fingerprintService: FingerprintService<UploadInput>;
 }

package/src/testing/index.ts

@@ -0,0 +1,16 @@
+export {
+	MockAbortController,
+	MockAbortControllerFactory,
+	MockBase64Service,
+	MockChecksumService,
+	MockFileReaderService,
+	MockFingerprintService,
+	MockHttpClient,
+	type MockHttpResponseConfig,
+	MockIdGenerationService,
+	MockPlatformService,
+	MockStorageService,
+	MockWebSocket,
+	MockWebSocketFactory,
+	createMockServiceContainer,
+} from "./mock-service-container";