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, metadata, options)

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,
  metadata: UploadMetadata,
  options: 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. metadata: 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. options: UploadOptions An object to configure the upload behavior.

   • url: string: The URL of the API endpoint that will receive the file chunks.
   • chunkSize?: number: (Optional) The size of each chunk in bytes. Default: 5 * 1024 * 1024 (5 MB).
   • baseDelay?: number: (Optional) The base delay in milliseconds for the exponential backoff retry mechanism. Default: 100.
   • onUploadProgress?: (progress: number) => void: (Optional) A callback function that receives the upload progress as a number between 0 and 1.
   • onUploadSuccess?: (message: string) => void: (Optional) A callback function that is called with a success message when the file is fully uploaded.
   • onUploadError?: (error: any) => void: (Optional) A callback function that is called if the upload fails after all retry attempts.

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
      },
      {
        url: "/api/upload", // Your backend endpoint
        uploadProgress: (p) => setProgress(p * 100),
        onUploadSuccess: (msg) => setMessage(msg),
        onUploadError: (err) => setMessage(`Upload failed: ${err}`),
      }
    );
  };

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

export default FileUploader;