File Upload Guide

Key Features

• ✅ Automatic Error Handling
• ✅ Class-Based API
• ✅ Legacy Compatibility
• ✅ Multipart Support
• ✅ Flexible Configuration
• ✅ Type Safety

Quick Start

Class-Based API (Recommended)

import { createServer, FileUploadAPI } from "xypriss";

const app = createServer({
    fileUpload: {
        enabled: true,
        maxFileSize: 5 * 1024 * 1024, // 5MB
        storage: "memory",
    },
});

// Create file upload instance
const fileUpload = new FileUploadAPI();
await fileUpload.initialize(app.options.fileUpload);

app.post("/upload", fileUpload.single("file"), (req, res) => {
    console.log(req.file); // File object available
    res.json({ success: true });
});

Functional API (Legacy)

import { createServer, uploadSingle } from "xypriss";

const app = createServer({
    fileUpload: {
        enabled: true,
        maxFileSize: 5 * 1024 * 1024,
    },
});

app.post("/upload", uploadSingle("file"), (req, res) => {
    res.json({ success: true, file: req.file });
});

Configuration Options

Core Options

const config = {
    enabled: true,
    maxFileSize: 5 * 1024 * 1024, // 5MB
    maxFiles: 1,
    storage: "memory", // or "disk"
    destination: "./uploads", // for disk storage
    allowedMimeTypes: [
        "image/jpeg",
        "image/png",
        "application/pdf"
    ],
    allowedExtensions: [".jpg", ".png", ".pdf"]
};

Upload Methods

Single File Upload

app.post("/upload", fileUpload.single("file"), (req, res) => {
    const file = req.file;
    res.json({ filename: file.originalname, size: file.size });
});

Multiple Files (Array)

app.post("/upload", fileUpload.array("files", 5), (req, res) => {
    console.log(`Uploaded ${req.files.length} files`);
    res.json({ count: req.files.length });
});

Multiple Fields

app.post("/upload", 
    fileUpload.fields([
        { name: "avatar", maxCount: 1 },
        { name: "documents", maxCount: 3 }
    ]), 
    (req, res) => {
        res.json({ files: req.files });
    }
);

Automatic Error Handling

XyPriss automatically handles file upload errors:

File Too Large

{
    "success": false,
    "error": "File too large",
    "message": "File size exceeds the maximum limit of 1.00MB",
    "details": {
        "maxSize": 1048576,
        "maxSizeMB": "1.00"
    }
}

File Type Not Allowed

{
    "success": false,
    "error": "File type not allowed",
    "message": "File type 'application/exe' not allowed"
}

Security Considerations

• Always validate file types and MIME types
• Set reasonable size limits to prevent DoS attacks
• Use memory storage for untrusted uploads
• Sanitize filenames to avoid path traversal
• Consider virus scanning for uploaded files

const secureConfig = {
    fileUpload: {
        enabled: true,
        maxFileSize: 2 * 1024 * 1024, // 2MB
        storage: "memory",
        allowedMimeTypes: ["image/jpeg", "image/png"],
        fileFilter: (req, file, cb) => {
            if (file.originalname.includes("..")) {
                return cb(new Error("Invalid filename"), false);
            }
            cb(null, true);
        }
    }
};