@uploadista/client-core 0.0.3

package/src/types/flow-upload-config.ts

@@ -0,0 +1,56 @@
+/**
+ * Configuration for uploading a file through a flow pipeline.
+ *
+ * Flows enable processing uploaded files through a sequence of transformation
+ * nodes (e.g., image resize, format conversion, validation) before final storage.
+ *
+ * @example Basic flow upload
+ * ```typescript
+ * const config: FlowUploadConfig = {
+ *   flowId: 'image-optimization',
+ *   storageId: 'processed-images',
+ * };
+ *
+ * await client.uploadWithFlow(file, config, {
+ *   onProgress: (progress) => console.log(`${progress}%`),
+ *   onSuccess: (result) => console.log('Processed:', result),
+ * });
+ * ```
+ *
+ * @example With specific output node
+ * ```typescript
+ * const config: FlowUploadConfig = {
+ *   flowId: 'multi-format-conversion',
+ *   storageId: 'images',
+ *   outputNodeId: 'webp-output', // Get WebP version instead of first output
+ *   metadata: {
+ *     userId: '123',
+ *     album: 'vacation-2024',
+ *   },
+ * };
+ * ```
+ */
+export type FlowUploadConfig = {
+  /** Unique identifier of the flow to execute */
+  flowId: string;
+
+  /** Storage backend where flow outputs will be saved */
+  storageId: string;
+
+  /**
+   * Specify which output node to use for single-value callbacks like onSuccess.
+   *
+   * For flows with multiple output nodes, this determines which output
+   * is passed to the onSuccess callback. If not specified, uses the first
+   * output node. The onFlowComplete callback receives all outputs regardless.
+   */
+  outputNodeId?: string;
+
+  /**
+   * Additional metadata to attach to the upload and flow execution.
+   *
+   * This metadata is stored with the upload and can be used for tracking,
+   * filtering, or providing context to flow nodes.
+   */
+  metadata?: Record<string, string>;
+};

package/src/types/flow-upload-item.ts

@@ -0,0 +1,16 @@
+import type { UploadFile } from "@uploadista/core";
+
+/**
+ * Flow upload item for multi-flow-upload tracking
+ */
+export interface FlowUploadItem<UploadInput> {
+  id: string;
+  file: UploadInput;
+  status: "pending" | "uploading" | "success" | "error" | "aborted";
+  progress: number;
+  bytesUploaded: number;
+  totalBytes: number;
+  error: Error | null;
+  result: UploadFile | null;
+  jobId: string | null;
+}

package/src/types/flow-upload-options.ts

@@ -0,0 +1,56 @@
+import type { UploadFile } from "@uploadista/core/types";
+import type { FlowUploadConfig } from "./flow-upload-config";
+
+export interface FlowUploadOptions<TOutput = UploadFile> {
+  /**
+   * Flow configuration
+   */
+  flowConfig: FlowUploadConfig;
+
+  /**
+   * Called when upload progress updates
+   */
+  onProgress?: (
+    progress: number,
+    bytesUploaded: number,
+    totalBytes: number | null,
+  ) => void;
+
+  /**
+   * Called when a chunk completes
+   */
+  onChunkComplete?: (
+    chunkSize: number,
+    bytesAccepted: number,
+    bytesTotal: number | null,
+  ) => void;
+
+  /**
+   * Called when the flow completes successfully (receives full flow outputs)
+   * This is the recommended callback for multi-output flows
+   * Format: { [outputNodeId]: result, ... }
+   */
+  onFlowComplete?: (outputs: Record<string, unknown>) => void;
+
+  /**
+   * Called when upload succeeds (legacy, single-output flows)
+   * For single-output flows, receives the value from the specified outputNodeId
+   * or the first output node if outputNodeId is not specified
+   */
+  onSuccess?: (result: TOutput) => void;
+
+  /**
+   * Called when upload fails
+   */
+  onError?: (error: Error) => void;
+
+  /**
+   * Called when upload is aborted
+   */
+  onAbort?: () => void;
+
+  /**
+   * Custom retry logic
+   */
+  onShouldRetry?: (error: Error, retryAttempt: number) => boolean;
+}

package/src/types/index.ts

@@ -0,0 +1,13 @@
+export * from "./chunk-metrics";
+export * from "./flow-result";
+export * from "./flow-upload-config";
+export * from "./flow-upload-item";
+export * from "./flow-upload-options";
+export * from "./multi-flow-upload-options";
+export * from "./multi-flow-upload-state";
+export * from "./performance-insights";
+export * from "./previous-upload";
+export * from "./upload-options";
+export * from "./upload-response";
+export * from "./upload-result";
+export * from "./upload-session-metrics";

package/src/types/multi-flow-upload-options.ts

@@ -0,0 +1,39 @@
+import type { FlowUploadConfig } from "./flow-upload-config";
+import type { FlowUploadItem } from "./flow-upload-item";
+
+export interface MultiFlowUploadOptions<UploadInput> {
+  /**
+   * Flow configuration
+   */
+  flowConfig: FlowUploadConfig;
+
+  /**
+   * Maximum number of concurrent uploads (default: 3)
+   */
+  maxConcurrent?: number;
+
+  /**
+   * Called when an individual upload progresses
+   */
+  onItemProgress?: (item: FlowUploadItem<UploadInput>) => void;
+
+  /**
+   * Called when an individual upload succeeds
+   */
+  onItemSuccess?: (item: FlowUploadItem<UploadInput>) => void;
+
+  /**
+   * Called when an individual upload fails
+   */
+  onItemError?: (item: FlowUploadItem<UploadInput>, error: Error) => void;
+
+  /**
+   * Called when all uploads complete
+   */
+  onComplete?: (items: FlowUploadItem<UploadInput>[]) => void;
+
+  /**
+   * Custom retry logic
+   */
+  onShouldRetry?: (error: Error, retryAttempt: number) => boolean;
+}

package/src/types/multi-flow-upload-state.ts

@@ -0,0 +1,9 @@
+import type { FlowUploadItem } from "./flow-upload-item";
+
+export interface MultiFlowUploadState<UploadInput> {
+  items: FlowUploadItem<UploadInput>[];
+  totalProgress: number;
+  activeUploads: number;
+  completedUploads: number;
+  failedUploads: number;
+}

package/src/types/performance-insights.ts

@@ -0,0 +1,7 @@
+export interface PerformanceInsights {
+  overallEfficiency: number; // 0-1 score
+  chunkingEffectiveness: number; // 0-1 score
+  networkStability: number; // 0-1 score
+  recommendations: string[];
+  optimalChunkSizeRange: { min: number; max: number };
+}

package/src/types/previous-upload.ts

@@ -0,0 +1,22 @@
+import z from "zod";
+
+export type PreviousUpload = {
+  size: number | null;
+  metadata: { [key: string]: string | number | boolean };
+  creationTime: string;
+  uploadId?: string;
+  parallelUploadUrls?: string[];
+  clientStorageKey: string;
+};
+
+export const previousUploadSchema = z.object({
+  size: z.number().nullable(),
+  metadata: z.record(
+    z.string(),
+    z.union([z.string(), z.number(), z.boolean()]),
+  ),
+  creationTime: z.string(),
+  uploadId: z.string().optional(),
+  parallelUploadUrls: z.array(z.string()).optional(),
+  clientStorageKey: z.string(),
+});

package/src/types/upload-options.ts

@@ -0,0 +1,56 @@
+import type { UploadFile } from "@uploadista/core";
+
+export interface UploadOptions {
+  /**
+   * Upload metadata to attach to the file
+   */
+  metadata?: Record<string, string>;
+
+  /**
+   * Whether to defer the upload size calculation
+   */
+  uploadLengthDeferred?: boolean;
+
+  /**
+   * Manual upload size override
+   */
+  uploadSize?: number;
+
+  /**
+   * Called when upload progress updates
+   */
+  onProgress?: (
+    progress: number,
+    bytesUploaded: number,
+    totalBytes: number | null,
+  ) => void;
+
+  /**
+   * Called when a chunk completes
+   */
+  onChunkComplete?: (
+    chunkSize: number,
+    bytesAccepted: number,
+    bytesTotal: number | null,
+  ) => void;
+
+  /**
+   * Called when upload succeeds
+   */
+  onSuccess?: (result: UploadFile) => void;
+
+  /**
+   * Called when upload fails
+   */
+  onError?: (error: Error) => void;
+
+  /**
+   * Called when upload is aborted
+   */
+  onAbort?: () => void;
+
+  /**
+   * Custom retry logic
+   */
+  onShouldRetry?: (error: Error, retryAttempt: number) => boolean;
+}

package/src/types/upload-response.ts

@@ -0,0 +1,6 @@
+import type { UploadFile } from "@uploadista/core";
+
+export type UploadResponse = {
+  upload?: UploadFile;
+  status: number;
+};

package/src/types/upload-result.ts

@@ -0,0 +1,60 @@
+import type { UploadFile } from "@uploadista/core";
+
+/**
+ * Discriminated union representing the result of an upload operation.
+ *
+ * Provides a type-safe way to handle the three possible outcomes of an upload:
+ * success, error, or cancellation. This pattern enables exhaustive checking
+ * of all cases at compile time.
+ *
+ * @template TOutput - The type of the successful result value. Defaults to UploadFile
+ *
+ * @example Handling upload results
+ * ```typescript
+ * function handleUploadResult(result: UploadResult) {
+ *   switch (result.type) {
+ *     case 'success':
+ *       console.log('Upload complete:', result.value.id);
+ *       break;
+ *     case 'error':
+ *       console.error('Upload failed:', result.error.message);
+ *       break;
+ *     case 'cancelled':
+ *       console.log('Upload was cancelled by user');
+ *       break;
+ *   }
+ * }
+ * ```
+ *
+ * @example With custom output type
+ * ```typescript
+ * interface ProcessedImage {
+ *   url: string;
+ *   width: number;
+ *   height: number;
+ * }
+ *
+ * const result: UploadResult<ProcessedImage> = await uploadAndProcess(file);
+ *
+ * if (result.type === 'success') {
+ *   console.log(`Image processed: ${result.value.width}x${result.value.height}`);
+ * }
+ * ```
+ */
+export type UploadResult<TOutput = UploadFile> =
+  | {
+      /** Indicates the upload completed successfully */
+      type: "success";
+      /** The successful result value (e.g., upload metadata or processed output) */
+      value: TOutput;
+    }
+  | {
+      /** Indicates the upload failed with an error */
+      type: "error";
+      /** The error that caused the upload to fail */
+      error: Error;
+    }
+  | {
+      /** Indicates the upload was cancelled by the user or application */
+      type: "cancelled";
+    };

package/src/types/upload-session-metrics.ts

@@ -0,0 +1,15 @@
+export interface UploadSessionMetrics {
+  uploadId: string;
+  totalSize: number;
+  totalDuration: number;
+  chunksCompleted: number;
+  chunksTotal: number;
+  averageSpeed: number;
+  peakSpeed: number;
+  minSpeed: number;
+  totalRetries: number;
+  successRate: number;
+  adaptiveChunkingEnabled: boolean;
+  startTime: number;
+  endTime?: number;
+}

package/src/upload/chunk-upload.ts

@@ -0,0 +1,151 @@
+import type { UploadistaApi } from "../client/uploadista-api";
+import { UploadistaError } from "../error";
+import type { Logger } from "../logger";
+import type { AbortControllerLike } from "../services";
+import type { FileSource } from "../services/file-reader-service";
+import type { PlatformService } from "../services/platform-service";
+import type { SmartChunker } from "../smart-chunker";
+import type { UploadResponse } from "../types/upload-response";
+import { inStatusCategory } from "./upload-utils";
+
+export type OnProgress = (
+  uploadId: string,
+  bytesSent: number,
+  bytesTotal: number | null,
+) => void;
+
+export type OnShouldRetry = (
+  error: UploadistaError,
+  retryAttempt: number,
+) => boolean;
+
+/**
+ * uploadChunk reads a chunk from the source and sends it using the
+ * supplied request object. It will not handle the response.
+ */
+export async function uploadChunk({
+  uploadId,
+  source,
+  offset,
+  uploadLengthDeferred,
+  abortController,
+  onProgress,
+  smartChunker,
+  uploadistaApi,
+  logger,
+}: {
+  uploadId: string;
+  source: FileSource;
+  offset: number;
+  uploadLengthDeferred: boolean | undefined;
+  abortController: AbortControllerLike;
+  onProgress?: OnProgress;
+  smartChunker: SmartChunker;
+  uploadistaApi: UploadistaApi;
+  logger: Logger;
+}): Promise<UploadResponse> {
+  const start = offset ?? 0;
+  const remainingBytes = source.size ? source.size - start : undefined;
+  const chunkSizeDecision = smartChunker.getNextChunkSize(remainingBytes);
+  const currentChunkSize = chunkSizeDecision.size;
+  let end = start + currentChunkSize;
+
+  // The specified chunkSize may be Infinity or the calcluated end position
+  // may exceed the file's size. In both cases, we limit the end position to
+  // the input's total size for simpler calculations and correctness.
+  if (
+    source.size &&
+    (end === Number.POSITIVE_INFINITY || end > source.size) &&
+    !uploadLengthDeferred
+  ) {
+    end = source.size;
+  }
+
+  const { value, size, done } = await source.slice(start, end);
+  const sizeOfValue = size ?? 0;
+  const chunkStartTime = Date.now();
+
+  // If the upload length is deferred, the upload size was not specified during
+  // upload creation. So, if the file reader is done reading, we know the total
+  // upload size and can tell the tus server.
+  if (uploadLengthDeferred && done) {
+    source.size = offset + sizeOfValue;
+  }
+
+  // The specified uploadSize might not match the actual amount of data that a source
+  // provides. In these cases, we cannot successfully complete the upload, so we
+  // rather error out and let the user know. If not, tus-js-client will be stuck
+  // in a loop of repeating empty PATCH requests.
+  // See https://community.transloadit.com/t/how-to-abort-hanging-companion-uploads/16488/13
+  const newSize = offset + sizeOfValue;
+  if (!uploadLengthDeferred && done && newSize !== source.size) {
+    throw new UploadistaError({
+      name: "WRONG_UPLOAD_SIZE",
+      message: `upload was configured with a size of ${size} bytes, but the source is done after ${newSize} bytes`,
+    });
+  }
+
+  const result = await uploadistaApi.uploadChunk(uploadId, value, {
+    onProgress: (bytes, total) => {
+      onProgress?.(uploadId, bytes, total);
+    },
+    abortController,
+  });
+
+  // Record performance metrics
+  const chunkDuration = Date.now() - chunkStartTime;
+  const success = result.status >= 200 && result.status < 300;
+
+  smartChunker.recordChunkResult(sizeOfValue, chunkDuration, success);
+
+  logger.log(
+    `Chunk upload ${success ? "succeeded" : "failed"}: ${sizeOfValue} bytes in ${chunkDuration}ms (${chunkSizeDecision.strategy} strategy)`,
+  );
+
+  return result;
+}
+
+/**
+ * Checks whether or not it is ok to retry a request.
+ * @param {UploadistaError} err the error returned from the last request
+ * @param {number} retryAttempt the number of times the request has already been retried
+ * @param {number[]} retryDelays configured retry delays
+ * @param {OnShouldRetry} onShouldRetry optional custom retry logic
+ */
+export function shouldRetry(
+  platformService: PlatformService,
+  err: UploadistaError,
+  retryAttempt: number,
+  retryDelays?: number[],
+  onShouldRetry?: OnShouldRetry,
+): boolean {
+  if (
+    retryDelays == null ||
+    retryAttempt >= retryDelays.length ||
+    !err.isNetworkError()
+  ) {
+    return false;
+  }
+
+  if (onShouldRetry) {
+    return onShouldRetry(err, retryAttempt);
+  }
+
+  return defaultOnShouldRetry(platformService, err);
+}
+
+/**
+ * determines if the request should be retried. Will only retry if not a status 4xx except a 409 or 423
+ * @param {UploadistaError} err
+ * @returns {boolean}
+ */
+export function defaultOnShouldRetry(
+  platformService: PlatformService,
+  err: UploadistaError,
+): boolean {
+  const status = err.status ?? 0;
+  return (
+    (!inStatusCategory(status, 400) || status === 409 || status === 423) &&
+    platformService.isOnline()
+  );
+}