Skip to content

Latest commit

 

History

History
173 lines (111 loc) · 6.76 KB

README.md

File metadata and controls

173 lines (111 loc) · 6.76 KB

express-file-wizardry

License

express-file-wizardry is an Express middleware for handling file uploads with support for different storage types including memory, disk, cloudinary and Amazon S3.

Why express-file-wizardry

  • Simplified Configuration: express-file-wizardry provides a straightforward API for handling file uploads with various storage options. Whether you prefer in-memory storage, local disk storage, or cloud storage with services like Cloudinary, Amazon S3, Google cloud (upcoming), the configuration is simplified, allowing you to focus on your application logic.

  • Modularity and Separation of Concerns: The package is designed with modularity in mind, separating concerns such as storage configuration, file filtering, and middleware setup. This makes the codebase clean, maintainable, and easy to extend.

  • Versatile File Type Support: You can easily define the allowed file formats for uploads, ensuring that your application only accepts the types of files you expect. The package supports a wide range of file types, from images to documents and archives.

  • Flexible Storage Options: Choose the storage type that best fits your application requirements. Whether you need fast in-memory storage for temporary files, local disk storage for persistent storage, cloudinary or Amazon S3 for scalable cloud storage, express-file-wizardry has you covered.

Table of Contents

Installation

Install the package using npm:

npm install express-file-wizardry

Usage: JavaScript (CommonJS)

const express = require('express');
const { FileWizardry } = require('express-file-wizardry');

const app = express();

const fileWizardry = new FileWizardry();

// Use memory storage (default)
fileWizardry.setStorageType('memory');

// Alternatively, use disk storage (default destination: 'uploads')
// fileWizardry.setStorageType('disk', { destination: '/path/to/upload/folder' });


// Or use Amazon S3 storage
// fileWizardry.setStorageType('amazons3', { accessKeyId: 'your-access-key', secretAccessKey:   'your-secret-key', region: 'your-region', bucket: 'your-bucket' });

// Or use Cloudinary storage
// fileWizardry.setStorageType('cloudinary', { cloud_name: 'my-cloud', api_key: 'api-key', api_secret: 'api-secret' });

// Middleware for handling file uploads
app.post('/upload', fileWizardry.uploadFile({ formats: ['image/jpeg', 'image/png'], fieldName: 'image' }), (req, res) => {

    if (req.fileValidationError) {
        return res.status(400).json({ error: req.fileValidationError.message });
    }

    // Handle successful upload
    res.json({ message: 'File uploaded successfully' });
    });

    app.listen(3000, () => {
    console.log('Server running on http://localhost:3000');
});

Usage: TypeScript (ESM)

import express from 'express';
import { FileWizardry } from 'express-file-wizardry';

const app = express();

const fileWizardry = new FileWizardry();

// Use memory storage (default)
fileWizardry.setStorageType('memory');

// Alternatively, use disk storage (default destination: 'uploads')
// fileWizardry.setStorageType('disk', { destination: '/path/to/upload/folder' });

// Or use Amazon S3 storage
// fileWizardry.setStorageType('amazons3', { accessKeyId: 'your-access-key', secretAccessKey: 'your-secret-key', region: 'your-region', bucket: 'your-bucket' });

// Or use Cloudinary storage
// fileWizardry.setStorageType('cloudinary', { cloud_name: 'my-cloud', api_key: 'api-key', api_secret: 'api-secret' });

// Middleware for handling file uploads
app.post('/upload', fileWizardry.uploadFile({ formats: ['image/jpeg', 'image/png'], fieldName: 'image' }), (req, res) => {

    if (req.fileValidationError) {
        return res.status(400).json({ error: req.fileValidationError.message });
    }

    // Handle successful upload
    res.json({ message: 'File uploaded successfully' });
});

app.listen(3000, () => {
    console.log('Server running on http://localhost:3000');
});

API

FileWizardry

constructor(initialStorageType?: StorageType, options?: StorageTypeConfiguration)

  • initialStorageType (optional): Initial storage type. Default is 'memory'.
  • options (optional): Storage options.

uploadFile(options: UploadOptions): RequestHandler Middleware for handling file uploads.

  • options: Upload options.

    • storageType (optional): Storage type.

    • formats: Array of allowed file formats.

    • fieldName (optional): Name of the field in the request.

    • maxSize (optional): Maximum file size in bytes.

    • multiFile (optional): Boolean, set to true for multiple file uploads.

      When handling multiple file uploads:

      • If multiFile is true, the uploaded files will be accessible with req.files.
      • If multiFile is false or not specified, the uploaded file will be accessible with req.file.

setStorageType(storageType: StorageType, options?: StorageTypeConfiguration): void Set the storage type for file uploads.

  • storageType: Storage type ('memory', 'disk', or 'amazons3').
  • options: Storage options.

Examples

For more examples, check the examples directory.

Future Enhancements / To-Do

Feel free to contribute to the improvement of express-file-wizardry by working on or suggesting the following enhancements:

  • Advanced File Filtering: Enhance file filtering capabilities to support more advanced filtering options such as file size ranges, mime type checking, etc.

  • Middleware Options: Provide additional options for middleware configuration to offer more flexibility to users.

  • More Storage Options: Explore additional storage options based on user demand or emerging technologies.

If you have any suggestions or would like to contribute, feel free to open an issue or submit a pull request.

Contributing

Please contact [email protected] if you're interested. Contributions are welcome! See CONTRIBUTING.md for more information.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Credits

This project relies on the following packages:

  • multer-S3: A fantastic library for Amazon S3 storage. Special thanks to Linus Unnebäck for their valuable contribution to the Node.js community.

  • multer-storage-cloudinary: Excellent multer storage engine for Cloudinary. Kudos to the authors for their contribution.