@designbycode/uploader-core

A framework-agnostic JavaScript file uploader library with queue management, progress tracking, abort support, and file validation.

Features

• Framework-agnostic — Works in browsers and Node.js
• Dual module support — ESM and CommonJS
• Queue management — Add multiple files and upload them in sequence or parallel
• Progress tracking — Real-time upload progress via events
• Abort support — Cancel individual uploads or all at once
• File validation — Built-in size and MIME type validation with glob patterns
• Custom validators — Support for async validation functions
• Concurrency control — Limit simultaneous uploads with maxConcurrent
• Retry logic — Automatic retry for failed uploads
• Event-driven — Subscribe to add, progress, success, error, remove, retry events
• TypeScript — Full TypeScript support with type definitions

Installation

# Using bun
bun add @designbycode/uploader-core

# Using npm
npm install @designbycode/uploader-core

# Using pnpm
pnpm add @designbycode/uploader-core

Quick Start

import { Uploader } from "@designbycode/uploader-core";

const uploader = new Uploader({
  process: async (file, { signal, onProgress }) => {
    const formData = new FormData();
    formData.append("file", file);

    const response = await fetch("/api/upload", {
      method: "POST",
      body: formData,
      signal,
    });

    return { serverId: response.json().id };
  },
});

// Add files and upload
const input = document.querySelector('input[type="file"]');
input.addEventListener("change", async () => {
  const added = await uploader.addFiles(Array.from(input.files));
  uploader.uploadAll();
});

// Listen for events
uploader.on("progress", (file) => {
  console.log(`${file.file.name}: ${file.progress}%`);
});

uploader.on("success", (file) => {
  console.log(`${file.file.name} uploaded successfully`);
});

API

new Uploader(options?)

Creates a new uploader instance.

const uploader = new Uploader({
  autoUpload: false, // Automatically upload files when added
  maxConcurrent: 2, // Limit simultaneous uploads
  validation: {
    // File validation rules
    maxSize: 10 * 1024 * 1024, // 10MB
    acceptedMimeTypes: ["image/png", "image/jpeg"],
  },
  process: async (file, { signal, onProgress }) => {
    // Your upload logic here
    return { serverId: "file-id" };
  },
});

Options

| Option | Type | Description | | ------------------- | --------------------------------- | -------------------------------------------------- | | autoUpload | boolean | Automatically upload files when added | | maxConcurrent | number | Maximum simultaneous uploads (default: unlimited) | | validation | ValidationRule \| FileValidator | File validation rules or custom validator | | maxRetries | number | Maximum retry attempts for failed uploads | | retryDelay | number | Delay between retries in ms (default: 1000) | | process | ProcessFn | Function to handle the actual upload | | revert | RevertFn | Function to undo upload (e.g., delete from server) | | onAdd | Callback | Called when a file is added | | onProgress | Callback | Called when upload progress updates | | onSuccess | Callback | Called when upload succeeds | | onError | Callback | Called when upload fails | | onRemove | Callback | Called when a file is removed | | onRetry | Callback | Called when upload is retried | | onValidationError | Callback | Called when validation fails |

Methods

addFiles(files: File[]): Promise<UploadFile[]>

Add files to the upload queue. Returns the added UploadFile objects.

const added = await uploader.addFiles([file1, file2, file3]);
console.log(`Added ${added.length} files`);

uploadFile(id: string): Promise<void>

Upload a single file by its ID.

await uploader.uploadFile("file-uuid");

uploadAll(): void

Upload all queued files.

uploader.uploadAll();

cancelFile(id: string): void

Cancel an in-progress upload.

uploader.cancelFile("file-uuid");

cancelAll(): void

Cancel all in-progress uploads.

uploader.cancelAll();

removeFile(id: string): Promise<void>

Remove a file from the queue. Calls revert() if the file was uploaded.

await uploader.removeFile("file-uuid");

getFiles(): ReadonlyArray<UploadFile>

Get all files in the queue.

const files = uploader.getFiles();
files.forEach((f) => console.log(f.file.name, f.status));

getFile(id: string): UploadFile | undefined

Get a single file by ID.

const file = uploader.getFile("file-uuid");

getFileByServerId(serverId: string): UploadFile | undefined

Get a single file by its server ID (after upload).

const file = uploader.getFileByServerId("server-123");

clear(): void

Clear all files from the queue.

uploader.clear();

Events

on(event, callback): () => void

Subscribe to an event. Returns an unsubscribe function.

const unsubscribe = uploader.on("success", (file) => {
  console.log(`${file.file.name} uploaded!`);
});

// Later, unsubscribe
unsubscribe();

once(event, callback): () => void

Subscribe to an event for a single execution.

uploader.once("success", (file) => {
  console.log("First upload completed!");
});

off(event, callback): void

Unsubscribe from an event.

const handler = (file) => console.log(file.file.name);
uploader.on("success", handler);
uploader.off("success", handler);

Event Types

| Event | Payload | Description | | ---------- | --------------------------------------- | ----------------------- | | add | UploadFile | File added to queue | | progress | UploadFile | Upload progress updated | | success | UploadFile | Upload completed | | error | UploadFile | Upload failed | | remove | UploadFile | File removed from queue | | retry | { file: UploadFile, attempt: number } | Upload being retried |

Validation

Built-in Rules

const uploader = new Uploader({
  validation: {
    maxSize: 5 * 1024 * 1024, // 5MB max
    minSize: 1000, // 1KB min
    acceptedMimeTypes: ["image/png", "image/jpeg", "image/gif"],
    rejectedMimeTypes: ["application/exe"],
  },
  process: async (file, { signal, onProgress }) => {
    // ...
  },
});

uploader.on("validationError", (file, error) => {
  console.error(`${file.name} rejected: ${error}`);
});

Custom Validator

const uploader = new Uploader({
  validation: async (file) => {
    // Check file name
    if (!file.name.match(/^[a-zA-Z0-9-_]+\.[a-z]+$/)) {
      return { valid: false, error: "Invalid file name format" };
    }

    // Async validation (e.g., check against API)
    const isAllowed = await checkFileAllowed(file);
    if (!isAllowed) {
      return { valid: false, error: "File not allowed" };
    }

    return { valid: true };
  },
});

Concurrency Control

Limit simultaneous uploads:

const uploader = new Uploader({
  maxConcurrent: 2, // Only 2 uploads at a time
  process: async (file, { signal, onProgress }) => {
    // ...
  },
});

// Add 10 files, only 2 will upload at once
await uploader.addFiles(files);
uploader.uploadAll();

Retry Logic

Automatically retry failed uploads:

const uploader = new Uploader({
  maxRetries: 3, // Retry up to 3 times
  retryDelay: 1000, // Wait 1 second between retries
  process: async (file, { signal, onProgress }) => {
    // ...
  },
});

uploader.on("retry", ({ file, attempt }) => {
  console.log(`Retrying ${file.file.name} (attempt ${attempt})`);
});

Types

UploadFile

interface UploadFile {
  id: string;
  file: File;
  status: "idle" | "queued" | "uploading" | "success" | "error" | "cancelled";
  progress: number;
  serverId?: string;
  error?: string;
}

UploadStatus

type UploadStatus =
  | "idle"
  | "queued"
  | "uploading"
  | "success"
  | "error"
  | "cancelled";

ValidationRule

interface ValidationRule {
  maxSize?: number;
  minSize?: number;
  acceptedMimeTypes?: string[];
  rejectedMimeTypes?: string[];
}

License

MIT