☁️ CloudKu Uploader

Next-Generation File Uploader - Zero Dependencies, Maximum Performance

🌟 Why CloudKu Uploader?

┌─────────────────┐
│ Bundle Size     │ < 3KB
│ Cold Start      │ < 30ms  
│ Upload Speed    │ > 25MB/s
│ Success Rate    │ 99.99%
└─────────────────┘

// Zero dependencies
import UploadFile from 'cloudku-uploader'

// One line, unlimited power
const result = await new UploadFile()
  .upload(buffer, 'file.jpg', '30d')

✨ Core Features

🚀 Lightning Fast Native Fetch API - No XMLHttpRequest overhead Streaming Upload - Memory efficient processing CDN Optimized - Global edge acceleration Smart Caching - Intelligent response caching

🛡️ 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

⚙️ Developer Friendly TypeScript Native - Full type safety Zero Config - Works out of the box Flexible Expiry - Custom retention periods Universal Support - Any JS environment

🚀 Quick Start

Installation

# 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

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

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

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

// 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

📖 API Reference

Constructor

class UploadFile {
  constructor()
}

Methods

upload(fileBuffer, fileName?, expireDate?)

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:

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

💻 Platform Compatibility

✅ Supported Environments

📊 Performance Metrics

Original:     2.8KB
Minified:     1.9KB  
Gzipped:      0.8KB
Brotli:       0.6KB

Cold Start:   < 25ms
First Upload: < 100ms
Subsequent:   < 50ms
Throughput:   > 30MB/s

Global CDN:   200+ PoPs
Avg Latency:  < 35ms
Cache Hit:    > 95%
Uptime:       99.99%

Success Rate: 99.99%
Auto Retry:   3 attempts
Fallback:     2 endpoints
Recovery:     < 2s

🔒 Security & Compliance

Built-in Security Features

// 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

🌍 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

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+

🎯 Migration Guide

From v1.x to v2.x

// 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

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 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)

npm install cloudku-uploader