multermate 1.1.0 → 1.1.1

package/readme.md

@@ -1,159 +1,335 @@
 # Multer Mate
 
-`multermate` is a flexible and customizable npm package for configuring Multer, a Node.js middleware for handling `multipart/form-data` (file uploads). This package allows you to easily configure Multer for various use cases, including storing files in different directories and specifying allowed file types.
+A robust and flexible file upload utility built on top of Multer, providing advanced file handling capabilities for Node.js applications. Now with full TypeScript support!
 
 ## Features
 
-- Customizable storage destinations
-- Unique file naming using `uuid`
-- Support for various file types (images, videos, PDFs, etc.)
-- Configurable file size limits
-- Single and multiple file uploads
-- Specify custom MIME types within broader categories
-- Default behavior for allowing all MIME types if none specified
+- 📁 Flexible file storage configuration
+- 🔒 Built-in file type validation
+- 📦 Single and multiple file uploads
+- 🎯 Field-specific file type restrictions
+- 🗑️ File deletion utility
+- ⚡ Configurable file size limits
+- 🎨 Custom MIME type support
+- 🔄 Unique file naming with UUID
+- 🛡️ Path sanitization
+- 📝 Comprehensive error handling
+- 🔌 Works with CommonJS, ES Modules, and TypeScript
+- 📘 Full TypeScript definitions and type safety
 
 ## Installation
 
-Install the package using npm:
-
 ```bash
 npm install multermate
 ```
 
-## Usage
+## Basic Usage
+
+### CommonJS
+
+```javascript
+const { uploadSingle, uploadMultiple, deleteFile } = require("multermate");
+```
 
-### Import the package
+### ES Modules
 
 ```javascript
-const {
+import { uploadSingle, uploadMultiple, deleteFile } from "multermate";
+```
+
+### TypeScript
+
+```typescript
+import {
   uploadSingle,
   uploadMultiple,
-  ALLOWED_FILE_TYPES,
-} = require("multermate");
+  deleteFile,
+  UploadSingleOptions,
+  UploadMultipleOptions,
+} from "multermate";
+
+// With type definitions
+const options: UploadSingleOptions = {
+  destination: "uploads/images",
+  fileTypes: ["images"],
+  fileSizeLimit: 5 * 1024 * 1024,
+};
 ```
 
+## Upload Configurations
+
 ### Single File Upload
 
 ```javascript
-const express = require("express");
-const { uploadSingle } = require("multermate");
-
-const app = express();
+// Basic single file upload
+app.post("/upload", uploadSingle(), (req, res) => {
+  res.json({ file: req.file });
+});
 
+// Advanced single file upload
 app.post(
-  "/upload/single",
+  "/upload/advanced",
   uploadSingle({
     destination: "uploads/images",
-    filename: "image",
+    filename: "profile",
     fileTypes: ["images"],
-    fileSizeLimit: 1024 * 1024 * 10, // 10MB limit
+    fileSizeLimit: 5 * 1024 * 1024, // 5MB
+    preservePath: false,
   }),
   (req, res) => {
-    res.send("Single file uploaded!");
+    res.json({ file: req.file });
   }
 );
-
-app.listen(3000, () => {
-  console.log("Server started on http://localhost:3000");
-});
 ```
 
-### Multiple Files Upload (Mixed File Types)
+### Multiple Files Upload
 
 ```javascript
-const express = require("express");
-const { uploadMultiple } = require("multermate");
-
-const app = express();
-
+// Multiple fields with different configurations
 app.post(
   "/upload/multiple",
   uploadMultiple({
     fields: [
-      { name: "media", maxCount: 1, fileTypes: ["images", "videos"] },
-      { name: "pdf", maxCount: 1, fileTypes: ["pdfs"] },
+      {
+        name: "avatar",
+        maxCount: 1,
+        fileTypes: ["images"],
+      },
+      {
+        name: "documents",
+        maxCount: 5,
+        fileTypes: ["pdfs"],
+      },
+      {
+        name: "media",
+        maxCount: 3,
+        fileTypes: ["images", "videos"],
+      },
     ],
+    destination: "uploads/mixed",
+    fileSizeLimit: 10 * 1024 * 1024, // 10MB per file
   }),
   (req, res) => {
-    res.send("Multiple files uploaded!");
+    res.json({ files: req.files });
   }
 );
-
-app.listen(3000, () => {
-  console.log("Server started on http://localhost:3000");
-});
 ```
 
-### Custom MIME Types (e.g., Only PNGs and PDFs)
+### Custom MIME Types
 
 ```javascript
-const express = require("express");
-const { uploadSingle, uploadMultiple } = require("multermate");
-
-const app = express();
-
-// Single PNG or PDF file upload
 app.post(
-  "/upload-custom",
+  "/upload/custom",
   uploadSingle({
     destination: "uploads/custom",
-    customMimeTypes: ["image/png", "application/pdf"],
-    fileSizeLimit: 1024 * 1024 * 15, // 15MB limit
-  }),
-  (req, res) => {
-    res.send("PNG or PDF file uploaded!");
-  }
-);
-
-// Multiple PNGs or PDFs upload
-app.post(
-  "/upload-custom-multiple",
-  uploadMultiple({
-    fields: [
-      { name: "images", maxCount: 5, customMimeTypes: ["image/png"] },
-      { name: "pdfs", maxCount: 2, customMimeTypes: ["application/pdf"] },
+    customMimeTypes: [
+      "application/vnd.ms-excel",
+      "application/json",
+      "text/csv",
     ],
+    fileSizeLimit: 1024 * 1024, // 1MB
   }),
   (req, res) => {
-    res.send("PNG images and PDF files uploaded!");
+    res.json({ file: req.file });
   }
 );
+```
+
+### File Deletion
 
-app.listen(3000, () => {
-  console.log("Server started on http://localhost:3000");
+```javascript
+// Simple file deletion
+app.delete("/files/:filename", async (req, res) => {
+  const isDeleted = await deleteFile(`uploads/${req.params.filename}`);
+  res.json({ success: isDeleted });
+});
+
+// Advanced file deletion with error handling
+app.delete("/files/:type/:filename", async (req, res) => {
+  try {
+    const filePath = path.join("uploads", req.params.type, req.params.filename);
+    const isDeleted = await deleteFile(filePath);
+
+    if (isDeleted) {
+      res.json({
+        success: true,
+        message: "File deleted successfully",
+      });
+    } else {
+      res.status(404).json({
+        success: false,
+        message: "File not found or unable to delete",
+      });
+    }
+  } catch (error) {
+    res.status(500).json({
+      success: false,
+      message: error.message,
+    });
+  }
 });
 ```
 
-### Default Behavior (Allow All MIME Types)
+## API Reference
+
+### uploadSingle(options)
+
+Configures single file upload with the following options:
+
+| Option          | Type     | Default   | Description            |
+| --------------- | -------- | --------- | ---------------------- |
+| destination     | string   | 'uploads' | Upload directory path  |
+| filename        | string   | 'file'    | Form field name        |
+| fileTypes       | string[] | ['all']   | Allowed file types     |
+| customMimeTypes | string[] | []        | Custom MIME types      |
+| fileSizeLimit   | number   | 50MB      | Max file size in bytes |
+| preservePath    | boolean  | false     | Preserve original path |
+
+### uploadMultiple(options)
+
+Configures multiple file uploads with the following options:
+
+| Option          | Type     | Default   | Description          |
+| --------------- | -------- | --------- | -------------------- |
+| fields          | Field[]  | []        | Field configurations |
+| destination     | string   | 'uploads' | Upload directory     |
+| customMimeTypes | string[] | []        | Custom MIME types    |
+| fileSizeLimit   | number   | 50MB      | Max file size        |
+| preservePath    | boolean  | false     | Preserve paths       |
+
+#### Field Configuration
+
+| Option        | Type     | Default | Description           |
+| ------------- | -------- | ------- | --------------------- |
+| name          | string   | -       | Field name (required) |
+| maxCount      | number   | 10      | Max files per field   |
+| fileTypes     | string[] | ['all'] | Allowed types         |
+| fileSizeLimit | number   | 50MB    | Max file size         |
+
+### deleteFile(filePath)
+
+Deletes a file from the filesystem:
+
+| Parameter | Type             | Description      |
+| --------- | ---------------- | ---------------- |
+| filePath  | string           | Path to file     |
+| Returns   | Promise<boolean> | Deletion success |
+
+### Supported MIME Types
 
 ```javascript
-const express = require("express");
-const { uploadSingle, uploadMultiple } = require("multermate");
+const ALLOWED_MIME_TYPES = {
+  images: ["image/jpeg", "image/jpg", "image/png", "image/gif"],
+  videos: ["video/mp4", "video/mpeg", "video/ogg", "video/webm", "video/avi"],
+  pdfs: ["application/pdf"],
+  all: [
+    "image/jpeg",
+    "image/jpg",
+    "image/png",
+    "image/gif",
+    "video/mp4",
+    "video/mpeg",
+    "video/ogg",
+    "video/webm",
+    "video/avi",
+    "application/pdf",
+  ],
+};
+```
 
-const app = express();
+## Error Handling
+
+MulterMate adds a `fileValidationError` property to the request object when validation fails:
 
-// Single file upload (default behavior allows all MIME types)
+```javascript
 app.post("/upload", uploadSingle(), (req, res) => {
-  res.send("File uploaded!");
+  try {
+    // File size validation
+    if (req.fileValidationError) {
+      return res.status(400).json({
+        error: req.fileValidationError,
+      });
+    }
+
+    // File existence check
+    if (!req.file) {
+      return res.status(400).json({
+        error: "No file uploaded",
+      });
+    }
+
+    // Success response
+    res.json({
+      success: true,
+      file: {
+        filename: req.file.filename,
+        path: req.file.path,
+        size: req.file.size,
+        mimetype: req.file.mimetype,
+      },
+    });
+  } catch (error) {
+    res.status(500).json({
+      error: error.message,
+    });
+  }
 });
+```
 
-// Multiple files upload (default behavior allows all MIME types)
-app.post("/upload-multiple", uploadMultiple(), (req, res) => {
-  res.send("Files uploaded!");
-});
+## TypeScript Support
 
-app.listen(3000, () => {
-  console.log("Server started on http://localhost:3000");
-});
-```
+MulterMate includes complete TypeScript definitions for all functions and options:
 
-### Exported Constants
+```typescript
+// Type definitions for all options
+import {
+  UploadSingleOptions,
+  UploadMultipleOptions,
+  FieldConfig,
+} from "multermate";
 
-```javascript
-const { ALLOWED_FILE_TYPES } = require("multermate");
-console.log(ALLOWED_FILE_TYPES); // ['images', 'videos', 'pdfs', 'all']
+// Using with Express and TypeScript
+import express from "express";
+import { uploadSingle } from "multermate";
+
+const app = express();
+
+app.post(
+  "/upload",
+  uploadSingle({
+    destination: "uploads/typescript",
+    fileTypes: ["images"],
+    fileSizeLimit: 5 * 1024 * 1024,
+  }),
+  (req, res) => {
+    res.json({ success: true, file: req.file });
+  }
+);
 ```
 
-## Conclusion
+## Best Practices
+
+1. Always implement proper error handling
+2. Set appropriate file size limits
+3. Validate file types on the server
+4. Use custom storage destinations for different file types
+5. Implement file cleanup mechanisms
+6. Consider implementing file type verification beyond MIME types
+7. Create upload directories if they don't exist (MulterMate does this automatically)
+8. Use TypeScript types for better development experience
+
+## License
+
+MIT
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit issues and pull requests.
+
+## Author
+
+Wasim Zaman
+
+## Support
 
-multermate provides a flexible and easy-to-use configuration for handling file uploads in Node.js applications. Whether you need to handle single or multiple file uploads, restrict uploads to certain file types, or specify custom MIME types, this package has you covered.
+For support, please open an issue in the GitHub repository: https://github.com/Wasim-Zaman/multermate

package/types/index.d.ts

@@ -0,0 +1,58 @@
+import { NextFunction, Request, Response } from 'express';
+export interface UploadSingleOptions {
+    destination?: string;
+    filename?: string;
+    fileTypes?: string[];
+    customMimeTypes?: string[];
+    fileSizeLimit?: number;
+    preservePath?: boolean;
+}
+export interface FieldConfig {
+    name: string;
+    maxCount?: number;
+    fileTypes?: string[];
+    fileSizeLimit?: number;
+}
+export interface UploadMultipleOptions {
+    fields: FieldConfig[];
+    destination?: string;
+    customMimeTypes?: string[];
+    fileSizeLimit?: number;
+    preservePath?: boolean;
+}
+/**
+ * Function to handle a single file upload.
+ *
+ * @param options - Configuration options for the single file upload.
+ * @returns Multer middleware configured for single file upload.
+ */
+export declare function uploadSingle(options?: UploadSingleOptions): (req: Request, res: Response, next: NextFunction) => void;
+/**
+ * Function to handle multiple file uploads across multiple fields.
+ *
+ * @param options - Configuration options for multiple file uploads.
+ * @returns Multer middleware configured for multiple file uploads.
+ */
+export declare function uploadMultiple(options: UploadMultipleOptions): (req: Request, res: Response, next: NextFunction) => void;
+/**
+ * Utility function to delete a file from the filesystem
+ *
+ * @param filePath - The path to the file that needs to be deleted
+ * @returns Promise that resolves to true if deletion was successful, false otherwise
+ */
+export declare function deleteFile(filePath: string): Promise<boolean>;
+declare global {
+    namespace Express {
+        interface Request {
+            fileValidationError?: string;
+        }
+    }
+}
+export declare const ALLOWED_FILE_TYPES: string[];
+declare const _default: {
+    uploadSingle: typeof uploadSingle;
+    uploadMultiple: typeof uploadMultiple;
+    deleteFile: typeof deleteFile;
+    ALLOWED_FILE_TYPES: string[];
+};
+export default _default;

package/babel.config.js

@@ -1,12 +0,0 @@
-module.exports = {
-  presets: [
-    [
-      "@babel/preset-env",
-      {
-        targets: {
-          node: "current",
-        },
-      },
-    ],
-  ],
-};

package/dist/index.cjs.js

@@ -1,197 +0,0 @@
-const path = require("path");
-const multer = require("multer");
-const { v4: uuidv4 } = require("uuid");
-
-// Constants for allowed MIME types
-const ALLOWED_MIME_TYPES = {
-  images: ["image/jpeg", "image/jpg", "image/png", "image/gif"],
-  videos: ["video/mp4", "video/mpeg", "video/ogg", "video/webm", "video/avi"],
-  pdfs: ["application/pdf"],
-  all: [
-    "image/jpeg",
-    "image/jpg",
-    "image/png",
-    "image/gif",
-    "video/mp4",
-    "video/mpeg",
-    "video/ogg",
-    "video/webm",
-    "video/avi",
-    "application/pdf",
-  ],
-};
-
-/**
- * Function to configure storage for Multer.
- *
- * @param {string} destination - The destination folder where files will be stored. Default is "uploads".
- * @returns {object} - Multer storage configuration object.
- */
-const configureStorage = (destination) => {
-  return multer.diskStorage({
-    destination: (req, file, cb) => {
-      cb(null, destination || "uploads"); // Default folder is "uploads" if none is provided.
-    },
-    filename: (req, file, cb) => {
-      const sanitizedFilename = file.originalname.replace(/\\/g, "/");
-      const extension = path.extname(sanitizedFilename);
-      const fieldName = file.fieldname || "file"; // Use the field name as part of the filename.
-      const uniqueName = uuidv4(); // Generate a unique name using uuid.
-      let fileName = `${uniqueName}-${fieldName}${extension}`;
-
-      // Replace backslashes with forward slashes in the final filename
-      fileName = fileName.replace(/\\/g, "/");
-
-      cb(null, fileName); // Set the final filename.
-    },
-  });
-};
-
-/**
- * Function to configure file filter for Multer.
- *
- * @param {Array} allowedMimeTypes - Array of allowed MIME types.
- * @returns {function} - File filter function for Multer.
- */
-const configureFileFilter = (allowedMimeTypes) => {
-  return (req, file, cb) => {
-    if (allowedMimeTypes.includes(file.mimetype)) {
-      cb(null, true); // Allow the file if its MIME type is allowed.
-    } else {
-      cb(
-        new Error("Invalid file type. Only specified file types are allowed."),
-        false
-      ); // Reject the file if its MIME type is not allowed.
-    }
-  };
-};
-
-/**
- * Function to configure Multer with the provided options.
- *
- * @param {object} options - Configuration options for Multer.
- * @param {string} [options.destination] - Destination folder for files. Default is "uploads".
- * @param {string} [options.filename] - Custom filename template for saved files.
- * @param {Array<string>} [options.fileTypes] - Array of file types to allow (e.g., ['images', 'videos']).
- * @param {Array<string>} [options.customMimeTypes] - Array of custom MIME types to allow.
- * @param {number} [options.fileSizeLimit] - Maximum file size allowed (in bytes). Default is 50MB.
- * @param {boolean} [options.preservePath] - Preserve the full path of files. Default is false.
- * @returns {object} - Multer instance configured with the provided options.
- */
-const configureMulter = ({
-  destination,
-  filename,
-  fileTypes = [],
-  customMimeTypes = [],
-  fileSizeLimit,
-  preservePath = false,
-}) => {
-  const storage = configureStorage(destination);
-
-  // Combine allowed MIME types based on fileTypes array
-  let allowedMimeTypes = [];
-
-  if (customMimeTypes.length > 0) {
-    // Use custom MIME types if provided
-    allowedMimeTypes = customMimeTypes;
-  } else {
-    // Use default MIME types for specified fileTypes
-    fileTypes.forEach((type) => {
-      if (ALLOWED_MIME_TYPES[type]) {
-        allowedMimeTypes = allowedMimeTypes.concat(ALLOWED_MIME_TYPES[type]);
-      }
-    });
-
-    // If no specific file types are provided, use all allowed MIME types
-    if (allowedMimeTypes.length === 0) {
-      allowedMimeTypes = ALLOWED_MIME_TYPES.all;
-    }
-  }
-
-  const fileFilter = configureFileFilter(allowedMimeTypes);
-
-  return multer({
-    storage,
-    fileFilter,
-    limits: { fileSize: fileSizeLimit || 1024 * 1024 * 50 }, // Default 50MB file size limit
-    preservePath,
-  });
-};
-
-/**
- * Function to handle multiple fields in a single form submission.
- *
- * @param {Array} fields - Array of field configurations, each containing:
- *   @param {string} fields.name - The name of the form field.
- *   @param {number} [fields.maxCount=10] - The maximum number of files to accept per field.
- *   @param {Array<string>} [fields.fileTypes] - Array of file types to allow for this field (e.g., ['images']).
- * @returns {function} - Multer instance configured to handle multiple fields.
- */
-const uploadFields = (fields) => {
-  const fieldConfigs = fields.map((field) => ({
-    name: field.name,
-    maxCount: field.maxCount || 10, // Default maxCount is 10 if not specified.
-  }));
-
-  let allowedFileTypes = [];
-
-  fields.forEach((field) => {
-    const types = field.fileTypes || [];
-    types.forEach((type) => {
-      if (ALLOWED_MIME_TYPES[type]) {
-        allowedFileTypes = allowedFileTypes.concat(ALLOWED_MIME_TYPES[type]);
-      }
-    });
-  });
-
-  const multerInstance = configureMulter({
-    fileTypes: allowedFileTypes,
-    customMimeTypes: [],
-    fileSizeLimit: fields[0]?.fileSizeLimit, // Assuming all fields share the same limit.
-  });
-
-  return multerInstance.fields(fieldConfigs);
-};
-
-// Export functions to configure multer and available file types
-module.exports = {
-  /**
-   * Function to handle a single file upload.
-   *
-   * @param {object} options - Configuration options for the single file upload.
-   * @param {string} [options.destination] - Destination folder for the uploaded file.
-   * @param {string} [options.filename] - Custom filename template for the uploaded file.
-   * @param {Array<string>} [options.fileTypes] - Array of file types to allow (e.g., ['images']).
-   * @param {Array<string>} [options.customMimeTypes] - Array of custom MIME types to allow.
-   * @param {number} [options.fileSizeLimit] - Maximum file size allowed (in bytes). Default is 50MB.
-   * @param {boolean} [options.preservePath] - Preserve the full path of the uploaded file. Default is false.
-   * @returns {function} - Multer instance configured for single file upload.
-   */
-  uploadSingle: (options = {}) => {
-    const multerInstance = configureMulter(options);
-    return multerInstance.single(options.filename || "file");
-  },
-
-  /**
-   * Function to handle multiple file uploads across multiple fields.
-   *
-   * @param {object} options - Configuration options for multiple file uploads.
-   * @param {Array<object>} options.fields - Array of field configurations for multiple file uploads.
-   * @param {string} [options.destination] - Destination folder for the uploaded files.
-   * @param {Array<string>} [options.customMimeTypes] - Array of custom MIME types to allow.
-   * @param {number} [options.fileSizeLimit] - Maximum file size allowed (in bytes). Default is 50MB.
-   * @param {boolean} [options.preservePath] - Preserve the full path of the uploaded files. Default is false.
-   * @returns {function} - Multer instance configured for multiple file uploads.
-   */
-  uploadMultiple: (options = {}) => {
-    const multerInstance = configureMulter(options);
-    return multerInstance.fields(options.fields || []);
-  },
-
-  /**
-   * Export the allowed file types for reference.
-   *
-   * @type {Array<string>}
-   */
-  ALLOWED_FILE_TYPES: Object.keys(ALLOWED_MIME_TYPES),
-};