open_cloud_upload

A simple, reusable utility for chunked file uploads with progress reporting and retries.

Installation

npm install open_cloud_upload

API Reference

The library exports a ChunkedUploader class with a single static method, uploadFile.

ChunkedUploader.uploadFile(file, shapeObject, data)

This static method handles the logic for slicing a file into chunks and uploading them sequentially to a server. It includes features like progress tracking, error handling, and automatic retries with exponential backoff.

Signature

import { ChunkedUploader, UploadMetadata, UploadOptions } from 'open_cloud_upload';

ChunkedUploader.uploadFile(
  file: File,
  shapeObject: UploadMetadata,
  data: UploadOptions
): Promise<void>;

Parameters

1. file: File The File object that you want to upload. This is typically obtained from an <input type="file"> element.

2. shapeObject: UploadMetadata An object containing metadata required by the upload endpoint.

   • token: string: An authentication token or session identifier.
   • type: string: A string identifying the type of object being uploaded (e.g., 'profile-picture', 'document').
   • _id?: string: (Optional) A unique ID for the file object. If not provided, a random one will be generated.

3. data: UploadOptions An object to configure the upload behavior.

   • url: string: The URL of the API endpoint that will receive the file chunks.
   • update?: boolean: (Optional) If true, sends a PUT request instead of POST. Used for updating existing files. Default: false.
   • socketUrl?: string: (Optional) The URL of the WebSocket endpoint for real-time feedback.
   • objectKey?: string: (Optional) The object key to be sent in the X-Object-Key header, typically used when update is true.
   • chunkSize?: number: (Optional) The size of each chunk in bytes. Default: 5 * 1024 * 1024 (5 MB).
   • maxRetries?: number: (Optional) The maximum number of times to retry uploading a failed chunk. Default: 5.
   • baseDelay?: number: (Optional) The base delay in milliseconds for the exponential backoff retry mechanism. Default: 100.
   • startChunkIndex?: number: (Optional) The index of the chunk to start the upload from. Default: 0.
   • prefix?: string: (Optional) A prefix to add to the filename when uploading. Default: "default_".
   • uploadProgress?: (progress: number) => void: (Optional) A callback function that receives the upload progress as a number between 0 and 1 (e.g., 0.5 for 50%).
   • onUploadSuccess?: (message: string, data: any) => void: (Optional) A callback function that is called with a success message and any additional data from the server when the file is fully uploaded and processed by the server.
   • onServerUploadDone?: (message: string) => void: (Optional) A callback function that is called when all chunks have been successfully uploaded to the server, but before the server has necessarily finished processing the file.
   • onUploadError?: (message: string, details?: { chunkIndex: number, error: any }) => void: (Optional) A callback function that is called if the upload fails after all retry attempts. It receives an error message and an optional details object.

Usage Example

Here is an example of how to use ChunkedUploader in a React/Next.js component.

import React, { useState } from "react";
import { ChunkedUploader } from "open_cloud_upload";

const FileUploader = () => {
  const [progress, setProgress] = useState(0);
  const [message, setMessage] = useState("");

  const handleFileChange = async (
    event: React.ChangeEvent<HTMLInputElement>
  ) => {
    const file = event.target.files?.[0];
    if (!file) return;

    setMessage("Starting upload...");
    setProgress(0);

    await ChunkedUploader.uploadFile(
      file,
      {
        token: "your-auth-token-here",
        type: "user-avatar",
        // _id is optional
      },
      {
        update: "false" //use true if you want to update but also include objectKey when uploading;
        url: "/api/upload",// Your backend endpoint (e.g., /api/upload)
        socketUrl?: "socket url"
        objectKey: "", //use the key on which u what the update to be
        onUploadProgress: (p) => setProgress(p * 100), // Convert 0-1 progress to 0-100 for the progress bar
        onUploadSuccess: (msg, data) => {
          setMessage(`Success: ${msg}`);
          console.log("Server data:", data);
        },
        onUploadError: (msg, details) => {
          setMessage(`Upload failed: ${msg}`);
          console.error("Failure details:", details);
        },
      }
    );
  };

  return (
    <div>
      <input type="file" onChange={handleFileChange} />
      {progress > 0 && <progress value={progress} max="100" />}
      <p>{message}</p>
    </div>
  );
};

export default FileUploader;