Community Uploader

A file upload SDK with multipart upload, deduplication, and resumable upload support.

Features

- Multipart Upload: Automatically splits large files into chunks for parallel upload
- Deduplication: MD5-based file deduplication for instant upload
- Resumable Upload: Automatically resumes interrupted uploads
- Progress Tracking: Callbacks for both MD5 calculation and upload progress
- Cancellation: Support for aborting uploads at any time
- Auto Retry: Automatic retry on network failures
- Cross Platform: Works in both browser and Node.js environments

Installation

``bash
npm install tamar-community-uploader
`

Quick Start

`javascript
import CommunityUploader from 'tamar-community-uploader';

// Initialize
const uploader = new CommunityUploader({
baseUrl: 'https://api.example.com',
getToken: () => localStorage.getItem('token')
});

// Upload file
const result = await uploader.upload(file, {
onProgress: (percent) => console.log(Upload: ${percent}%),
onMD5Progress: (percent) => console.log(MD5: ${percent}%)
});

// Check if instant upload (deduplication hit)
if (result.deduplicated) {
console.log('File already exists, instant upload!');
}

console.log('File URL:', result.cdn_url || result.oss_url);
`

API Reference

$3

| Option | Type | Required | Default | Description |
|--------|------|----------|---------|-------------|
| baseUrl | string | Yes | - | API base URL |
| getToken | () => string \| Promise | Yes | - | Function to get auth token |
| concurrency | number | No | 3 | Number of concurrent chunk uploads |
| retryCount | number | No | 3 | Number of retries on failure |
| retryDelay | number | No | 1000 | Delay between retries (ms) |
| onLog | (message: string) => void | No | - | Log callback function |

$3

Upload a file with automatic MD5 calculation, deduplication, and resumable upload support.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| file | File \| Buffer | File to upload |
| fileName | string | Optional file name (required for Buffer) |
| options.category | string | File category: general, video, image, document |
| options.contentType | string | MIME type (auto-detected if not specified) |
| options.partSize | number | Chunk size in bytes |
| options.metadata | object | Extra metadata |
| options.onProgress | (percent) => void | Upload progress callback |
| options.onMD5Progress | (percent) => void | MD5 calculation progress callback |
| options.signal | AbortSignal | Abort signal for cancellation |

#### Returns

Promise - File information including URLs

$3

Cancel an ongoing upload and clean up server resources.

`javascript
await uploader.abortUpload(fileId);
`

$3

Calculate MD5 hash of a file.

`javascript
const md5 = await uploader.calculateMD5(file, (percent) => {
console.log(MD5 progress: ${percent}%);
});
`

$3

Get file information by ID.

`javascript
const info = await uploader.getFileInfo(fileId);
`

$3

List user's files with pagination.

`javascript
const result = await uploader.listFiles({
category: 'video',
status: 'confirmed',
page: 1,
page_size: 20
});
`

$3

Soft delete a file.

`javascript
await uploader.deleteFile(fileId);
`

Usage with AbortController

`javascript
const controller = new AbortController();

// Start upload
const uploadPromise = uploader.upload(file, {
signal: controller.signal,
onProgress: (percent) => console.log(${percent}%)
});

// Cancel after 5 seconds
setTimeout(() => controller.abort(), 5000);

try {
await uploadPromise;
} catch (error) {
if (error.name === 'AbortError') {
console.log('Upload cancelled');
}
}
`

React Hook Example

`tsx
import { useState, useCallback, useRef } from 'react';
import CommunityUploader from 'tamar-community-uploader';

export function useUploader(options) {
const [status, setStatus] = useState('idle');
const [progress, setProgress] = useState(0);
const controllerRef = useRef(null);

const uploader = useMemo(() => new CommunityUploader(options), []);

const upload = useCallback(async (file) => {
controllerRef.current = new AbortController();
setStatus('uploading');

try {
const result = await uploader.upload(file, {
signal: controllerRef.current.signal,
onProgress: setProgress
});
setStatus('success');
return result;
} catch (error) {
setStatus(error.name === 'AbortError' ? 'cancelled' : 'error');
throw error;
}
}, [uploader]);

const cancel = useCallback(() => {
controllerRef.current?.abort();
}, []);

return { status, progress, upload, cancel };
}
``

License

MIT