Common-file-upload NPM

Common File Upload Middleware

This is a Node.js middleware for handling file uploads, built on top of Express.js. It allows you to upload files with configurable validation and save them to a specified directory.

Features

Flexible Configuration: Define multiple file upload fields with specific rules.
Validation Support: Enforce file types, number of files, and required fields.
Easy Integration: Plug-and-play middleware for Express.js applications.

Installation

Install the middleware using npm:

npm install common-file-upload

Usage example with detailed comments

Middleware using Express:

import { fileUpload, fileRead } from "common-file-upload";
import express from "express";

const app = express();

app.use(express.json());
app.use(express.urlencoded({ extended: true }));

// File upload configuration
const uploadConfig = [
	{
		field: "file", // The field name in the form-data
		uploadPath: "./uploads", // Directory to save the uploaded files
		validation: {
			required: true,
			min: 1,
			max: 5, // Maximum 5 files for this field
			filter: ["image/jpeg", "image/png"] // Allowed MIME types
		}
	}
];

// Define a route with file upload
app.post("/upload", fileUpload(uploadConfig), (req, res) => {
	// Access uploaded files
	const files = req.files;

	res.json({
		message: "Files uploaded successfully!",
		files
	});
});

// File read configuration
const readConfig = [
	{
		field: "file", // The field name in the form-data
		fileSize: 10 * 1024 * 1024, // Maximum file size: 10MB
		validation: {
			required: true,
			min: 1,
			max: 3, // Maximum 3 files for this field
			filter: ["application/pdf", "image/png"] // Allowed MIME types
		}
	}
];

// Define a route with file read
app.post("/read", fileRead(readConfig), (req, res) => {
	res.json({
		message: "Files read successfully!",
		files: req.files
	});
});

// Start the server
const PORT = 3030;
app.listen(PORT, () => {
	console.log(`Server is running on http://localhost:${PORT}`);
});

Example Usage of Custom response options (`option`) :

const option = {
	responses: {
		invalidField: {
			statusCode: 400,
			data: { success: false, message: "Unexpected file field or too many files uploaded." }
		},
		multerError: {
			statusCode: 500,
			data: { success: false, message: "File upload error occurred." }
		},
		requiredRes: {
			statusCode: 400,
			data: { success: false, message: "File is required." }
		},
		limitMin: {
			statusCode: 400,
			data: { success: false, message: "At least 1 file is required." }
		},
		limitMax: {
			statusCode: 400,
			data: { success: false, message: "Only 1 file is allowed." }
		}
	}
};

fileUpload(uploadConfig, option);

Pass the option object when calling the fileUpload function:

import { fileUpload, fileRead } from "common-file-upload";

app.post("/upload", fileUpload(uploadConfig, option), (req, res) => {
	// Access uploaded files
	const files = req.files;

	res.json({
		message: "Files uploaded successfully!",
		files
	});
});

Configuration Options

The middleware accepts an array of configurations for each file upload field:

Field Configuration

Option	Type	Description
`field`	`string`	The name of the form-data field for the file.
`uploadPath`	`string`	Directory path where the uploaded files will be saved.
`validation`	`object`	Validation rules for the file upload (see below).

Validation Rules

Option	Type	Description
`required`	`boolean`	Whether the field is required.
`min`	`number`	Minimum number of files to upload.
`max`	`number`	Maximum number of files to upload.
`filter`	`string[]`	Array of allowed MIME types (e.g.., image/jpeg, image/png).

Custom Response Options (`option`)

You can also define custom responses for various error scenarios such as invalid file fields, Multer errors, or required files not being uploaded. These responses are passed as an option object to the fileUpload middleware.

`option` Object

The option object contains custom responses for different error conditions:

Option	Type	Description
`responses`	`object`	Custom response configurations for errors.
`invalidField`	`object`	Response when an unexpected file field or too many files are uploaded.
`multerError`	`object`	Response for general Multer errors such as file size limits or disk errors.
`requiredRes`	`object`	Response when a required file is not uploaded.
`limitMin`	`object`	Response when the number of uploaded files is less than the minimum.
`limitMax`	`object`	Response when the number of uploaded files exceeds the maximum allowed.