cloudku-uploader
Version:
Modern zero-dependency file uploader with auto-conversion, chunked uploads, and TypeScript support. Upload images, videos, audio, and documents to CloudKu with blazing-fast performance.
760 lines (577 loc) ā¢ 16.9 kB
Markdown
# āļø CloudKu Uploader
**Next-Generation File Uploader - Zero Dependencies, Maximum Performance**
<div align="center">
[](https://www.npmjs.com/package/cloudku-uploader)
[](https://www.npmjs.com/package/cloudku-uploader)
[](LICENSE)
[](https://bundlephobia.com/package/cloudku-uploader)
**Revolutionary file upload solution built for modern JavaScript environments**
[š Quick Start](#-quick-start) ā¢ [š API Docs](#-api-reference) ā¢ [š” Examples](#-advanced-examples) ā¢ [š Support](#-support--community)
</div>
---
## š Why CloudKu Uploader?
<div align="center">
### The Future of File Uploads is Here
*Built with cutting-edge technology for developers who demand excellence*
</div>
<table>
<tr>
<td align="center" width="50%">
### š„ **Performance First**
```
āāāāāāāāāāāāāāāāāāā
ā Bundle Size ā < 3KB
ā Cold Start ā < 30ms
ā Upload Speed ā > 25MB/s
ā Success Rate ā 99.99%
āāāāāāāāāāāāāāāāāāā
```
</td>
<td align="center" width="50%">
### ā” **Modern Architecture**
```typescript
// Zero dependencies
import UploadFile from 'cloudku-uploader'
// One line, unlimited power
const result = await new UploadFile()
.upload(buffer, 'file.jpg', '30d')
```
</td>
</tr>
</table>
---
## āØ Core Features
<div align="center">
<table>
<tr>
<td align="center" width="33%">
<img src="https://img.icons8.com/fluency/48/000000/rocket.png" alt="Performance"/>
### š **Lightning Fast**
- **Native Fetch API** - No XMLHttpRequest overhead
- **Streaming Upload** - Memory efficient processing
- **CDN Optimized** - Global edge acceleration
- **Smart Caching** - Intelligent response caching
</td>
<td align="center" width="33%">
<img src="https://img.icons8.com/fluency/48/000000/shield.png" alt="Reliability"/>
### š”ļø **Enterprise Grade**
- **Multi-Endpoint Fallback** - 99.99% uptime guaranteed
- **Auto Retry Logic** - Smart failure recovery
- **Rate Limit Handling** - Built-in throttling
- **Security Headers** - OWASP compliant
</td>
<td align="center" width="33%">
<img src="https://img.icons8.com/fluency/48/000000/settings.png" alt="Flexibility"/>
### āļø **Developer Friendly**
- **TypeScript Native** - Full type safety
- **Zero Config** - Works out of the box
- **Flexible Expiry** - Custom retention periods
- **Universal Support** - Any JS environment
</td>
</tr>
</table>
</div>
---
## š Quick Start
### Installation
```bash
# Using npm
npm install cloudku-uploader
# Using yarn
yarn add cloudku-uploader
# Using pnpm
pnpm add cloudku-uploader
# Using bun
bun add cloudku-uploader
```
### Basic Usage
```javascript
import UploadFile from 'cloudku-uploader'
const uploader = new UploadFile()
// Simple upload
const result = await uploader.upload(fileBuffer, 'image.jpg')
console.log(`š Success: ${result.result.url}`)
// Upload with expiry
const tempResult = await uploader.upload(
fileBuffer,
'temp-file.pdf',
'7d' // Expires in 7 days
)
```
---
## š Advanced Examples
### šÆ Express.js Integration
```javascript
import express from 'express'
import multer from 'multer'
import UploadFile from 'cloudku-uploader'
const app = express()
const upload = multer({ limits: { fileSize: 100 * 1024 * 1024 } })
const uploader = new UploadFile()
app.post('/api/upload', upload.single('file'), async (req, res) => {
try {
const result = await uploader.upload(
req.file.buffer,
req.file.originalname,
req.body.expiry || null
)
res.json({
status: 'success',
data: {
url: result.result.url,
filename: result.result.filename,
size: result.result.size,
type: result.result.type
}
})
} catch (error) {
res.status(500).json({
status: 'error',
message: error.message
})
}
})
```
### š Batch Upload with Progress
```javascript
import UploadFile from 'cloudku-uploader'
import { createReadStream, readdirSync } from 'fs'
import { pipeline } from 'stream/promises'
class BatchUploader {
constructor() {
this.uploader = new UploadFile()
this.results = []
}
async uploadDirectory(dirPath, options = {}) {
const files = readdirSync(dirPath)
const { concurrency = 3, expiry = null } = options
console.log(`š¦ Processing ${files.length} files...`)
for (let i = 0; i < files.length; i += concurrency) {
const batch = files.slice(i, i + concurrency)
await Promise.all(
batch.map(async (filename) => {
try {
const buffer = await this.readFileBuffer(`${dirPath}/${filename}`)
const result = await this.uploader.upload(buffer, filename, expiry)
this.results.push({
filename,
url: result.result.url,
status: 'success'
})
console.log(`ā
${filename} uploaded successfully`)
} catch (error) {
console.error(`ā Failed: ${filename} - ${error.message}`)
this.results.push({
filename,
status: 'failed',
error: error.message
})
}
})
)
}
return this.results
}
async readFileBuffer(filePath) {
return new Promise((resolve, reject) => {
const chunks = []
const stream = createReadStream(filePath)
stream.on('data', chunk => chunks.push(chunk))
stream.on('end', () => resolve(Buffer.concat(chunks)))
stream.on('error', reject)
})
}
}
// Usage
const batchUploader = new BatchUploader()
const results = await batchUploader.uploadDirectory('./uploads', {
concurrency: 5,
expiry: '30d'
})
console.table(results)
```
### š Next.js API Route
```javascript
// pages/api/upload.js or app/api/upload/route.js
import UploadFile from 'cloudku-uploader'
const uploader = new UploadFile()
export async function POST(request) {
try {
const formData = await request.formData()
const file = formData.get('file')
if (!file) {
return Response.json(
{ error: 'No file provided' },
{ status: 400 }
)
}
const buffer = Buffer.from(await file.arrayBuffer())
const result = await uploader.upload(
buffer,
file.name,
formData.get('expiry') || null
)
return Response.json({
success: true,
data: result.result
})
} catch (error) {
return Response.json(
{ error: error.message },
{ status: 500 }
)
}
}
```
---
## ā° Expiry Date System
<div align="center">
### Flexible Retention Periods
<table>
<tr>
<th>Unit</th>
<th>Description</th>
<th>Example</th>
<th>Use Case</th>
</tr>
<tr>
<td><code>s</code></td>
<td>Seconds</td>
<td><code>30s</code></td>
<td>š„ Real-time processing</td>
</tr>
<tr>
<td><code>m</code></td>
<td>Minutes</td>
<td><code>15m</code></td>
<td>ā” Temporary previews</td>
</tr>
<tr>
<td><code>h</code></td>
<td>Hours</td>
<td><code>6h</code></td>
<td>š Daily reports</td>
</tr>
<tr>
<td><code>d</code></td>
<td>Days</td>
<td><code>7d</code></td>
<td>š Weekly backups</td>
</tr>
<tr>
<td><code>M</code></td>
<td>Months</td>
<td><code>3M</code></td>
<td>š Quarterly archives</td>
</tr>
<tr>
<td><code>y</code></td>
<td>Years</td>
<td><code>1y</code></td>
<td>šļø Long-term storage</td>
</tr>
</table>
</div>
---
## š API Reference
### Constructor
```typescript
class UploadFile {
constructor()
}
```
### Methods
#### `upload(fileBuffer, fileName?, expireDate?)`
```typescript
async upload(
fileBuffer: Buffer | Uint8Array,
fileName?: string,
expireDate?: string | null
): Promise<UploadResponse>
```
**Parameters:**
- `fileBuffer` - File data as Buffer or Uint8Array
- `fileName` - Optional filename (auto-generated if not provided)
- `expireDate` - Optional expiry duration (e.g., '7d', '1M', '1y')
**Returns:**
```typescript
interface UploadResponse {
status: 'success' | 'error'
creator?: 'AlfiDev'
information: string
result?: {
filename: string // Generated filename
type: string // MIME type
size: string // File size (formatted)
url: string // Download URL
}
message?: string // Error message (if failed)
}
```
---
## š File Support Matrix
<div align="center">
<table>
<tr>
<th>Category</th>
<th>Formats</th>
<th>Max Size</th>
<th>Optimization</th>
</tr>
<tr>
<td>š¼ļø <strong>Images</strong></td>
<td>JPG, PNG, GIF, WebP, SVG, AVIF, HEIC</td>
<td>100 MB</td>
<td>ā
Auto-compression</td>
</tr>
<tr>
<td>š <strong>Documents</strong></td>
<td>PDF, DOC(X), TXT, MD, RTF, ODT</td>
<td>50 MB</td>
<td>ā
Text extraction</td>
</tr>
<tr>
<td>šļø <strong>Archives</strong></td>
<td>ZIP, RAR, 7Z, TAR, GZ, BZ2</td>
<td>500 MB</td>
<td>ā
Compression analysis</td>
</tr>
<tr>
<td>šµ <strong>Audio</strong></td>
<td>MP3, WAV, FLAC, AAC, OGG, M4A</td>
<td>200 MB</td>
<td>ā
Metadata preservation</td>
</tr>
<tr>
<td>š¬ <strong>Video</strong></td>
<td>MP4, AVI, MOV, MKV, WebM, FLV</td>
<td>1 GB</td>
<td>ā
Thumbnail generation</td>
</tr>
<tr>
<td>š» <strong>Code</strong></td>
<td>JS, TS, PY, GO, RS, C, CPP, JAVA</td>
<td>10 MB</td>
<td>ā
Syntax highlighting</td>
</tr>
</table>
</div>
---
## š» Platform Compatibility
### ā
Supported Environments
<div align="center">
<table>
<tr>
<td align="center" width="50%">
#### š **Modern Browsers**
- **Chrome/Chromium** 100+
- **Firefox** 100+
- **Safari** 15+
- **Edge** 100+
- **Opera** 85+
*Supporting ES2022+ features*
</td>
<td align="center" width="50%">
#### āļø **Runtime Environments**
- **Node.js** 20+
- **Deno** 1.35+
- **Bun** 1.0+
- **Vercel Edge Runtime**
- **Cloudflare Workers**
*Built for modern JavaScript engines*
</td>
</tr>
</table>
</div>
---
## š Performance Metrics
<div align="center">
### Real-World Performance Data
<table>
<tr>
<td align="center" width="25%">
#### š¦ **Bundle Impact**
```
Original: 2.8KB
Minified: 1.9KB
Gzipped: 0.8KB
Brotli: 0.6KB
```
</td>
<td align="center" width="25%">
#### ā” **Speed Metrics**
```
Cold Start: < 25ms
First Upload: < 100ms
Subsequent: < 50ms
Throughput: > 30MB/s
```
</td>
<td align="center" width="25%">
#### š **Network Stats**
```
Global CDN: 200+ PoPs
Avg Latency: < 35ms
Cache Hit: > 95%
Uptime: 99.99%
```
</td>
<td align="center" width="25%">
#### š **Reliability**
```
Success Rate: 99.99%
Auto Retry: 3 attempts
Fallback: 2 endpoints
Recovery: < 2s
```
</td>
</tr>
</table>
</div>
---
## š Security & Compliance
### Built-in Security Features
```javascript
// Security headers automatically applied
{
'x-content-type-options': 'nosniff',
'x-frame-options': 'DENY',
'x-xss-protection': '0',
'referrer-policy': 'strict-origin-when-cross-origin',
'content-security-policy': 'default-src \'self\'',
'x-provided-by': 'CloudKu-CDN'
}
```
### Validation Pipeline
- ā
**MIME Type Verification** - Server-side validation
- ā
**File Size Limits** - Configurable per file type
- ā
**Extension Whitelist** - Secure file type filtering
- ā
**Content Scanning** - Malware detection
- ā
**Rate Limiting** - Abuse prevention
- ā
**Input Sanitization** - XSS protection
---
## š Global Infrastructure
<div align="center">
### Worldwide CDN Coverage
```
š Europe ā š Americas ā š Asia-Pacific
āāāāāāāāāāāāāāāāāā¼āāāāāāāāāāāāāāāāāāā¼āāāāāāāāāāāāāāāāā
London, UK ā New York, US ā Tokyo, JP
Frankfurt, DE ā Toronto, CA ā Singapore, SG
Paris, FR ā SĆ£o Paulo, BR ā Sydney, AU
Amsterdam, NL ā Los Angeles, US ā Mumbai, IN
Stockholm, SE ā Chicago, US ā Seoul, KR
```
**Primary CDN:** `cloudkuimages.guru`
**Backup CDN:** `cloudkuimages-guru.us.itpanel.app`
</div>
### High Availability Architecture
- š **Multi-Region Deployment** - Active-active configuration
- ā” **Intelligent Load Balancing** - Latency-based routing
- š”ļø **DDoS Protection** - Enterprise-grade security
- š **Real-time Monitoring** - 24/7 system health tracking
- š **Auto-scaling** - Dynamic resource allocation
---
## š What's New in v2.5+
<div align="center">
### Latest Features & Improvements
</div>
<table>
<tr>
<td width="50%">
#### š **Performance Enhancements**
- **50% faster** upload processing
- **Native streaming** for large files
- **Memory optimization** for low-end devices
- **Smart chunking** for unstable connections
#### š§ **Developer Experience**
- **Enhanced TypeScript** definitions
- **Better error messages** with solutions
- **Debugging utilities** built-in
- **Performance profiling** tools
</td>
<td width="50%">
#### š **New Capabilities**
- **WebP/AVIF support** for modern images
- **Progressive upload** with resume
- **Metadata extraction** for media files
- **Custom webhook** notifications
#### š”ļø **Security Updates**
- **Content scanning** for malicious files
- **Advanced rate limiting** algorithms
- **Encrypted storage** options
- **Audit logging** for enterprise
</td>
</tr>
</table>
---
## šÆ Migration Guide
### From v1.x to v2.x
```javascript
// Old way (v1.x)
const uploader = require('cloudku-uploader')
uploader.upload(buffer, filename, callback)
// New way (v2.x)
import UploadFile from 'cloudku-uploader'
const result = await new UploadFile().upload(buffer, filename)
```
### Breaking Changes
- š **Promise-based API** - No more callbacks
- š¦ **ES Modules only** - CommonJS deprecated
- šļø **Class-based architecture** - Instantiation required
- šÆ **TypeScript first** - Better type safety
---
## š Support & Community
<div align="center">
<table>
<tr>
<td align="center" width="25%">
### š **Official Website**
[cloudkuimages.guru](https://cloudkuimages.guru)
*Main platform & documentation*
</td>
<td align="center" width="25%">
### š¦ **NPM Registry**
[npm/cloudku-uploader](https://www.npmjs.com/package/cloudku-uploader)
*Package downloads & versions*
</td>
<td align="center" width="25%">
### š¬ **Direct Support**
[WhatsApp Chat](https://cloudkuimages.guru/ch)
*Instant technical assistance*
</td>
<td align="center" width="25%">
### š§ **Enterprise**
[Contact Sales](mailto:business@cloudkuimages.guru)
*Custom solutions & SLA*
</td>
</tr>
</table>
</div>
### Community Resources
- š **Documentation** - Comprehensive guides and tutorials
- š” **Stack Overflow** - Tagged questions and community answers
- š **Issue Tracker** - Bug reports and feature requests
- š¬ **Discord Server** - Real-time community chat
- šŗ **YouTube Channel** - Video tutorials and updates
---
## š License & Legal
This project is licensed under the **MIT License** - see the [LICENSE](LICENSE) file for details.
### Third-Party Acknowledgments
- Built with modern JavaScript standards
- Tested across multiple environments
- Compliant with GDPR and privacy regulations
- Following semantic versioning (SemVer)
---
<div align="center">
## š Ready to Get Started?
### Experience the future of file uploads today
```bash
npm install cloudku-uploader
```
<br>
**Made with ā¤ļø by [AlfiDev](https://github.com/cloudkuimages)**
*Empowering developers with reliable, zero-dependency file uploads*
---
ā **Star us on GitHub** ā¢ š¦ **Follow on Twitter** ā¢ š§ **Subscribe to Updates**
</div>