From 99f2183890e943a5a7e4d0dbe3fabddd594dfc5d Mon Sep 17 00:00:00 2001 From: ashutoshkhainar33-star Date: Wed, 5 Aug 2026 01:21:42 +0530 Subject: [PATCH 1/4] SEO optimized readme doc --- README.md | 418 +++++++++++++++++++++++++++++++----------------------- 1 file changed, 241 insertions(+), 177 deletions(-) diff --git a/README.md b/README.md index 74065ea..5ceaf7f 100644 --- a/README.md +++ b/README.md @@ -1,177 +1,241 @@ -# Uploads SDK - -This SDK helps you efficiently upload large files from the browser by splitting them into chunks and also gives you the ability to pause and resume your uploads. While the SDK itself is written in TypeScript, we are publishing only the JavaScript output as npm package. Types support for TypeScript users will be released in a later version. - -Please note that this SDK is designed to work only with FastPix and is not a general purpose uploads SDK. - -# Features: - -- **Chunking:** Files are automatically split into chunks (configurable, default size is 16MB/chunk). -- **Pause and Resume:** Allows temporarily pausing the upload and resuming after a while. -- **Retry:** Uploads might fail due to temporary network failures. Individual chunks are retried for 5 times with exponential backoff to recover automatically from such failures. -- **Lifecycle Event Listeners:** Listen to various upload lifecycle events to provide real-time feedback to users. -- **Error Handling and Reporting:** Comprehensive error handling to manage upload failures gracefully and inform users of issues. -- **Customizability:** Developers can customize the chunk size and retry attempts based on their specific needs and network conditions. - -# Prerequisites: - -## Getting started with FastPix: - -To get started with SDK, you will need a signed URL. - -To make API requests, you'll need a valid **Access Token** and **Secret Key**. See the [Basic Authentication Guide](https://fastpix.com/docs/getting-started/activate-your-account) for details on retrieving these credentials. - -Once you have your credentials, use the [Upload media from device](https://fastpix.com/docs/video-on-demand-api/upload-and-import-videos/direct-upload-video-media) API to generate a signed URL for uploading media. - -## Installation: - -To install the SDK, you can use NPM, CDN, or your preferred package manager: - -### Using NPM: - -```bash -npm i @fastpix/resumable-uploads -``` - -### Using CDN: - -```bash - -``` - -## Basic Usage - -## Import - -```javascript -import { Uploader } from "@fastpix/resumable-uploads"; -``` - -## Integration - -```javascript -try { - const fileUploader = Uploader.init({ - endpoint: "https://example.com/signed-url", // Replace with the signed URL. - file: mediaFile, // Provide the media file you want to upload. From - chunkSize: 5 * 1024, // Minimum allowed chunk size is 5120KB (5MB). - - // Additional optional parameters can be specified here as needed - }); -} catch (error) { - // Handle initialization errors, such as invalid configuration or missing file - console.error("Failed to initialize uploads:", error?.message); -} -``` - -## Monitor the upload progress through lifecycle events - -```javascript -// Track upload progress -fileUploader.on("progress", (event) => { - console.log("Upload Progress:", event.detail.progress); -}); - -// Handle errors during the upload process -fileUploader.on("error", (event) => { - console.error("Upload Error:", event.detail.message); -}); - -// Trigger actions when the upload completes successfully -fileUploader.on("success", (event) => { - console.log("Upload Completed"); -}); - -// Track the initiation of each chunk upload -fileUploader.on("chunkAttempt", (event) => { - console.log("Chunk Upload Attempt:", event.detail); -}); - -// Track failures of each chunk upload attempt -fileUploader.on("chunkAttemptFailure", (event) => { - console.log("Chunk Attempt Failure:", event.detail); -}); - -// Perform an action when a chunk is successfully uploaded -fileUploader.on("chunkSuccess", (event) => { - console.log("Chunk Successfully Uploaded:", event.detail); -}); - -// Triggers when the connection is back online -fileUploader.on("online", (event) => { - console.log("Connection Online"); -}); - -// Triggers when the connection goes offline -fileUploader.on("offline", (event) => { - console.log("Connection Offline"); -}); -``` - -## Managing Uploads - -You can control the upload lifecycle with the following methods: - -- **Pause an Upload:** - - ```javascript - fileUploader.pause(); // Pauses the current upload - ``` - -- **Resume an Upload:** - - ```javascript - fileUploader.resume(); // Resume the current upload - ``` - -- **Abort an Upload:** - - ```javascript - fileUploader.abort(); // Abort the current upload - ``` - -## Parameters Accepted - -The upload function accepts the following parameters: - -| Name | Type | Required | Description | -| ------------------- | ----------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `endpoint` | `string` or `() => Promise` | Required | The signed URL endpoint where the file will be uploaded. Can be a static string or a function returning a `Promise` that resolves to the upload URL. | -| `file` | `File` or `Object` | Required | The file object to be uploaded. Typically a `File` retrieved from an `` element, but can also be a generic object representing the file. | -| `chunkSize` | `number` (in KB) | Optional | Size of each chunk in kilobytes. Default is `16384` KB (16 MB).
**Minimum:** 5120 KB (5 MB), **Maximum:** 512000 KB (500 MB). | -| `maxFileSize` | `number` (in KB) | Optional | Maximum allowed file size for upload, specified in kilobytes. Files exceeding this limit will be rejected. | -| `retryChunkAttempt` | `number` | Optional | Number of retry attempts per chunk in case of failure. Default is `5`. | -| `delayRetry` | `number` (in seconds) | Optional | Delay between retry attempts after a failed chunk upload. Default is `1` second. | -| `stallTimeout` | `number` (in seconds) | Optional | Time without any upload progress before the in-flight chunk request is treated as stalled, aborted and retried on a fresh connection. Default is `30` seconds, minimum `1`. | -| `connectionRefreshInterval` | `number` (in seconds) | Optional | Time a chunk request may keep running before the connection is re-established, continuing from the last byte the server committed. This recovers connections stuck at a stale speed (e.g. a transfer that started on a slow network staying slow after conditions improve). Backs off automatically on genuinely slow networks. Default is `45` seconds, minimum `5`. | - -### Example usage of integrating all parameters with `Uploader.init` - -```js -// Get the selected file from the input -const selectedFile = document.querySelector("#fileInput").files[0]; - -try { - const fileUploader = Uploader.init({ - endpoint: "https://example.com/signed-url", // Signed URL for uploading - file: selectedFile, // File or Object to upload - chunkSize: 10 * 1024, // 10 MB per chunk - maxFileSize: 100 * 1024, // 100 MB max file size - retryChunkAttempt: 6, // Retry each failed chunk up to 6 times - delayRetry: 2, // Wait 2 seconds between retry attempts - }); -} catch (error) { - // Handle initialization errors - console.error("Failed to initialize upload:", error?.message); -} -``` - -# References - -[FastPix Homepage](https://www.fastpix.com/) -[FastPix Dashboard](https://dashboard.fastpix.com/) -[Uploads github](https://github.com/FastPix/web-uploads-sdk) - -# Detailed Usage: - -For more detailed steps and advanced usage, please refer to the official [FastPix Documentation](https://fastpix.com/docs/upload-videos/upload-videos-from-device#resumable-uploading-of-large-files). +# Resumable, chunked file uploads for the browser + +[![npm version](https://img.shields.io/npm/v/@fastpix/resumable-uploads)](https://www.npmjs.com/package/@fastpix/resumable-uploads) +[![npm downloads](https://img.shields.io/npm/dm/@fastpix/resumable-uploads)](https://www.npmjs.com/package/@fastpix/resumable-uploads) +[![Bundle size](https://img.shields.io/bundlephobia/minzip/@fastpix/resumable-uploads)](https://bundlephobia.com/package/@fastpix/resumable-uploads) +[![License](https://img.shields.io/github/license/FastPix/web-uploads-sdk)](./LICENSE) +[![Built with TypeScript](https://img.shields.io/badge/Built%20with-TypeScript-blue?logo=typescript)](https://www.typescriptlang.org/) + +Upload large files from the browser without the fragility. This SDK splits a file into chunks and adds pause/resume, automatic retries with exponential backoff, and real-time progress events, so large uploads survive flaky networks. Written in TypeScript, works with plain JavaScript or any framework, via npm or a CDN. + +> This SDK is designed to work with FastPix - it uploads to a FastPix signed URL - and is not a general-purpose uploads SDK. + +**Works with:** Browsers 路 JavaScript 路 TypeScript 路 any framework 路 npm or CDN + +馃摉 **Docs:** https://fastpix.com/docs/upload-videos/upload-videos-from-device#resumable-uploading-of-large-files  路  馃殌 **Free account:** https://dashboard.fastpix.com + +## Why this SDK? + +- **Chunked large-file uploads** - files are split into configurable chunks (default 16 MB) so big uploads are reliable. +- **Pause and resume** - temporarily pause an upload and resume it later. +- **Automatic retry** - individual chunks retry up to 5 times with exponential backoff to recover from temporary network failures. +- **Lifecycle events** - subscribe to progress, success, error and chunk events for real-time feedback. +- **Robust error handling** - upload failures are surfaced gracefully so you can inform users. +- **Customizable** - tune chunk size, retries and stall/connection behavior to your network conditions. + +## Features: + +- **Chunking:** Files are automatically split into chunks (configurable, default size is 16MB/chunk). +- **Pause and Resume:** Allows temporarily pausing the upload and resuming after a while. +- **Retry:** Uploads might fail due to temporary network failures. Individual chunks are retried for 5 times with exponential backoff to recover automatically from such failures. +- **Lifecycle Event Listeners:** Listen to various upload lifecycle events to provide real-time feedback to users. +- **Error Handling and Reporting:** Comprehensive error handling to manage upload failures gracefully and inform users of issues. +- **Customizability:** Developers can customize the chunk size and retry attempts based on their specific needs and network conditions. + +## Before you start + +To get started with the SDK, you will need a signed URL. + +To make API requests, you'll need a valid **Access Token** and **Secret Key**. See the [Basic Authentication Guide](https://fastpix.com/docs/getting-started/activate-your-account) for details on retrieving these credentials. + +Once you have your credentials, use the [Upload media from device](https://fastpix.com/docs/video-on-demand-api/upload-and-import-videos/direct-upload-video-media) API to generate a signed URL for uploading media. + +## Install the large-file upload SDK + +To install the SDK, you can use NPM, CDN, or your preferred package manager: + +### Using NPM: + +```bash +npm i @fastpix/resumable-uploads +``` + +### Using CDN: + +```bash + +``` + +## How to upload a file + +### Import + +```javascript +import { Uploader } from "@fastpix/resumable-uploads"; +``` + +### Initialize the uploader + +```javascript +try { + const fileUploader = Uploader.init({ + endpoint: "https://example.com/signed-url", // Replace with the signed URL. + file: mediaFile, // Provide the media file you want to upload. From + chunkSize: 5 * 1024, // Minimum allowed chunk size is 5120KB (5MB). + + // Additional optional parameters can be specified here as needed + }); +} catch (error) { + // Handle initialization errors, such as invalid configuration or missing file + console.error("Failed to initialize uploads:", error?.message); +} +``` + +## Monitor upload progress through lifecycle events + +```javascript +// Track upload progress +fileUploader.on("progress", (event) => { + console.log("Upload Progress:", event.detail.progress); +}); + +// Handle errors during the upload process +fileUploader.on("error", (event) => { + console.error("Upload Error:", event.detail.message); +}); + +// Trigger actions when the upload completes successfully +fileUploader.on("success", (event) => { + console.log("Upload Completed"); +}); + +// Track the initiation of each chunk upload +fileUploader.on("chunkAttempt", (event) => { + console.log("Chunk Upload Attempt:", event.detail); +}); + +// Track failures of each chunk upload attempt +fileUploader.on("chunkAttemptFailure", (event) => { + console.log("Chunk Attempt Failure:", event.detail); +}); + +// Perform an action when a chunk is successfully uploaded +fileUploader.on("chunkSuccess", (event) => { + console.log("Chunk Successfully Uploaded:", event.detail); +}); + +// Triggers when the connection is back online +fileUploader.on("online", (event) => { + console.log("Connection Online"); +}); + +// Triggers when the connection goes offline +fileUploader.on("offline", (event) => { + console.log("Connection Offline"); +}); +``` + +## Pause, resume and abort an upload + +You can control the upload lifecycle with the following methods: + +- **Pause an Upload:** + + ```javascript + fileUploader.pause(); // Pauses the current upload + ``` + +- **Resume an Upload:** + + ```javascript + fileUploader.resume(); // Resume the current upload + ``` + +- **Abort an Upload:** + + ```javascript + fileUploader.abort(); // Abort the current upload + ``` + +## Configuration parameters + +The upload function accepts the following parameters: + +| Name | Type | Required | Description | +| ------------------- | ----------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `endpoint` | `string` or `() => Promise` | Required | The signed URL endpoint where the file will be uploaded. Can be a static string or a function returning a `Promise` that resolves to the upload URL. | +| `file` | `File` or `Object` | Required | The file object to be uploaded. Typically a `File` retrieved from an `` element, but can also be a generic object representing the file. | +| `chunkSize` | `number` (in KB) | Optional | Size of each chunk in kilobytes. Default is `16384` KB (16 MB).
**Minimum:** 5120 KB (5 MB), **Maximum:** 512000 KB (500 MB). | +| `maxFileSize` | `number` (in KB) | Optional | Maximum allowed file size for upload, specified in kilobytes. Files exceeding this limit will be rejected. | +| `retryChunkAttempt` | `number` | Optional | Number of retry attempts per chunk in case of failure. Default is `5`. | +| `delayRetry` | `number` (in seconds) | Optional | Delay between retry attempts after a failed chunk upload. Default is `1` second. | +| `stallTimeout` | `number` (in seconds) | Optional | Time without any upload progress before the in-flight chunk request is treated as stalled, aborted and retried on a fresh connection. Default is `30` seconds, minimum `1`. | +| `connectionRefreshInterval` | `number` (in seconds) | Optional | Time a chunk request may keep running before the connection is re-established, continuing from the last byte the server committed. This recovers connections stuck at a stale speed (e.g. a transfer that started on a slow network staying slow after conditions improve). Backs off automatically on genuinely slow networks. Default is `45` seconds, minimum `5`. | + +### Example usage of integrating all parameters with `Uploader.init` + +```js +// Get the selected file from the input +const selectedFile = document.querySelector("#fileInput").files[0]; + +try { + const fileUploader = Uploader.init({ + endpoint: "https://example.com/signed-url", // Signed URL for uploading + file: selectedFile, // File or Object to upload + chunkSize: 10 * 1024, // 10 MB per chunk + maxFileSize: 100 * 1024, // 100 MB max file size + retryChunkAttempt: 6, // Retry each failed chunk up to 6 times + delayRetry: 2, // Wait 2 seconds between retry attempts + }); +} catch (error) { + // Handle initialization errors + console.error("Failed to initialize upload:", error?.message); +} +``` + +## Which FastPix upload SDK for your platform + +Uploading from a different platform or framework? FastPix has a resumable upload SDK for each. + +| Platform / framework | FastPix upload SDK | +|---|---| +| Web (this repo) | **web-uploads-sdk** | +| React (web) | [react-web-uploader](https://github.com/FastPix/react-web-uploader) | +| Astro | [astro-web-uploader](https://github.com/FastPix/astro-web-uploader) | +| Android | [android-uploads-sdk](https://github.com/FastPix/android-uploads-sdk) | +| iOS | [iOS-Uploads](https://github.com/FastPix/iOS-Uploads) | +| Flutter | [flutter-uploads](https://github.com/FastPix/flutter-uploads) | +| React Native | [react-native-uploader](https://github.com/FastPix/react-native-uploader) | + +## FAQ + +**How do I upload large files from the browser?** +Generate a FastPix signed URL, then call `Uploader.init({ endpoint, file })` with the file from an ``. The SDK chunks the file and uploads it, as shown in "How to upload a file." + +**How do I pause and resume an upload?** +Use `fileUploader.pause()` and `fileUploader.resume()` on the instance returned by `Uploader.init`. See "Pause, resume and abort an upload." + +**What happens if a chunk fails or the network drops?** +Each chunk retries automatically (up to `retryChunkAttempt`, default 5) with exponential backoff, and the SDK emits `online`/`offline` events so you can react to connectivity changes. + +**Can I set the chunk size and maximum file size?** +Yes - `chunkSize` (min 5 MB, max 500 MB; default 16 MB) and `maxFileSize`. See "Configuration parameters." + +**How do I track upload progress?** +Listen to the `progress` lifecycle event, plus `success`, `error` and the per-chunk events. See "Monitor upload progress through lifecycle events." + +**Does it support TypeScript?** +The SDK is written in TypeScript. + +**Can I use it without npm?** +Yes - load it from a CDN with the ` ``` +
+ ## How to upload a file ### Import @@ -81,6 +91,8 @@ try { } ``` +
+ ## Monitor upload progress through lifecycle events ```javascript @@ -125,6 +137,8 @@ fileUploader.on("offline", (event) => { }); ``` +
+ ## Pause, resume and abort an upload You can control the upload lifecycle with the following methods: @@ -147,6 +161,8 @@ You can control the upload lifecycle with the following methods: fileUploader.abort(); // Abort the current upload ``` +
+ ## Configuration parameters The upload function accepts the following parameters: @@ -162,6 +178,8 @@ The upload function accepts the following parameters: | `stallTimeout` | `number` (in seconds) | Optional | Time without any upload progress before the in-flight chunk request is treated as stalled, aborted and retried on a fresh connection. Default is `30` seconds, minimum `1`. | | `connectionRefreshInterval` | `number` (in seconds) | Optional | Time a chunk request may keep running before the connection is re-established, continuing from the last byte the server committed. This recovers connections stuck at a stale speed (e.g. a transfer that started on a slow network staying slow after conditions improve). Backs off automatically on genuinely slow networks. Default is `45` seconds, minimum `5`. | +
+ ### Example usage of integrating all parameters with `Uploader.init` ```js @@ -183,6 +201,8 @@ try { } ``` +
+ ## Which FastPix upload SDK for your platform Uploading from a different platform or framework? FastPix has a resumable upload SDK for each. @@ -197,45 +217,72 @@ Uploading from a different platform or framework? FastPix has a resumable upload | Flutter | [flutter-uploads](https://github.com/FastPix/flutter-uploads) | | React Native | [react-native-uploader](https://github.com/FastPix/react-native-uploader) | +
+ ## FAQ **How do I upload large files from the browser?** + Generate a FastPix signed URL, then call `Uploader.init({ endpoint, file })` with the file from an ``. The SDK chunks the file and uploads it, as shown in "How to upload a file." **How do I pause and resume an upload?** + Use `fileUploader.pause()` and `fileUploader.resume()` on the instance returned by `Uploader.init`. See "Pause, resume and abort an upload." **What happens if a chunk fails or the network drops?** + Each chunk retries automatically (up to `retryChunkAttempt`, default 5) with exponential backoff, and the SDK emits `online`/`offline` events so you can react to connectivity changes. **Can I set the chunk size and maximum file size?** + Yes - `chunkSize` (min 5 MB, max 500 MB; default 16 MB) and `maxFileSize`. See "Configuration parameters." **How do I track upload progress?** + Listen to the `progress` lifecycle event, plus `success`, `error` and the per-chunk events. See "Monitor upload progress through lifecycle events." **Does it support TypeScript?** + The SDK is written in TypeScript. **Can I use it without npm?** + Yes - load it from a CDN with the `