@bernierllc/file-uploader

Multipart file upload handler with validation and progress tracking

Installation

npm install @bernierllc/file-uploader

Features

• Multipart form parsing - Handles multipart/form-data uploads
• File validation - Size limits, MIME type checking, file count limits
• Progress tracking - Real-time upload progress callbacks
• Framework agnostic - Works with Express, Koa, Fastify, etc.
• Stream-based - Efficient handling of large files
• TypeScript support - Full type safety

Usage

Basic Usage

import { FileUploader } from '@bernierllc/file-uploader';
import express from 'express';

const app = express();
const uploader = new FileUploader({
  maxFileSize: 10 * 1024 * 1024, // 10MB
  allowedMimeTypes: ['image/jpeg', 'image/png', 'image/webp'],
  onProgress: (progress) => {
    console.log(`Upload progress: ${progress.percentage}%`);
  }
});

app.post('/upload', async (req, res) => {
  try {
    const results = await uploader.handleMultipart(req);
    res.json({ files: results });
  } catch (error) {
    res.status(400).json({ error: error.message });
  }
});

File Validation

const uploader = new FileUploader({
  maxFileSize: 5 * 1024 * 1024, // 5MB
  allowedMimeTypes: ['image/jpeg', 'image/png'],
  maxFiles: 5
});

// Validate before upload
const fileInfo = {
  fieldname: 'file',
  filename: 'photo.jpg',
  encoding: '7bit',
  mimeType: 'image/jpeg',
  size: 1024 * 1024
};

const validation = uploader.validateFile(fileInfo);
if (!validation.valid) {
  console.error(validation.error);
}

Progress Tracking

const uploader = new FileUploader({
  onProgress: (progress) => {
    console.log(`File ${progress.fileId}: ${progress.percentage}%`);
    console.log(`Uploaded: ${progress.bytesUploaded}/${progress.totalBytes}`);
  }
});

Custom Destination

const uploader = new FileUploader({
  destination: async (file) => {
    // Generate custom path
    return `/uploads/${Date.now()}-${file.filename}`;
  }
});

API

new FileUploader(config?: UploadConfig)

Creates a new file uploader instance.

uploader.handleMultipart(req: IncomingMessage): Promise<UploadResult[]>

Processes a multipart form upload request.

uploader.validateFile(file: FileInfo): { valid: boolean; error?: string }

Validates a file against configuration rules.

uploader.getProgress(fileId: string): UploadProgress | null

Gets upload progress for a specific file.

Integration Status

Logger Integration

Status: ✅ Integrated

Uses @bernierllc/logger for upload events, errors, and progress tracking.

NeverHub Integration

Status: ⚠️ Optional

Can emit upload events to NeverHub for distributed monitoring and observability. File uploader can publish events like upload.started, upload.progress, upload.completed, and upload.failed to NeverHub when available.

Pattern: Optional service discovery integration - package can emit upload lifecycle events to NeverHub for distributed monitoring.

Example Integration:

// If NeverHub is available, emit events
if (typeof detectNeverHub === 'function') {
  uploader.on('upload.completed', (result) => {
    neverhub.emit('file-uploader.upload.completed', result);
  });
}

Docs-Suite Integration

Status: ✅ Ready

TypeDoc-compatible JSDoc comments are included throughout the source code. All public APIs are documented with examples and type information.

License

Copyright (c) 2025 Bernier LLC. All rights reserved.