@nodezor/upload-flow

Zero-dependency resumable chunked file upload pipeline and state tracking engine.

The Problem

Handling multi-gigabyte resumable file uploads across different cloud providers (AWS S3, Cloudflare R2, GCP Storage) requires complex client/server state tracking, chunking algorithms, signed URL generation, and automatic retries on dropped networks. Developers spend weeks reinventing this upload pipeline for every new project.

Features

• 📦 Resumable Chunk Calculation: Calculates byte boundaries for large multi-part uploads.
• 📊 Real-Time Progress Tracking: Calculates chunk completion percentages and byte counters.
• ⚡ Zero External Dependencies: Powered by native TypeScript primitives.
• 🛡️ Configuration Guard: Validates storage environment settings.

Installation

# pnpm
pnpm add @nodezor/upload-flow

# npm
npm install @nodezor/upload-flow

# yarn
yarn add @nodezor/upload-flow

Quick Start / Usage Example

import { createUploadSession, markChunkCompleted, getUploadProgress } from '@nodezor/upload-flow';

// 1. Initialize a 50MB upload session with 5MB chunks
let session = createUploadSession('video.mp4', 50 * 1024 * 1024, 5 * 1024 * 1024);

console.log(`Total Chunks: ${session.totalChunks}`); // 10 chunks

// 2. Mark chunk #0 as completed
session = markChunkCompleted(session, 0);

// 3. Compute progress
const progress = getUploadProgress(session);
console.log(`Uploaded ${progress.percentage}% (${progress.uploadedBytes} / ${progress.totalBytes} bytes)`);

API Reference

createUploadSession(fileName: string, totalSize: number, chunkSize?: number): UploadSession

Initializes a new resumable upload session with metadata.

calculateChunkRanges(totalSize: number, chunkSize?: number): ChunkMeta[]

Computes explicit byte ranges (startByte, endByte, size) for file chunking.

markChunkCompleted(session: UploadSession, chunkIndex: number): UploadSession

Marks a chunk index as uploaded and updates session status (PENDING -> UPLOADING -> COMPLETED).

getUploadProgress(session: UploadSession): UploadProgress

Returns metrics (percentage, uploadedBytes, totalBytes, completedChunks).

License

MIT © PRX2112