balda-js 0.0.1 → 0.0.2

package/docs/docs/plugins/file.md

@@ -1,382 +0,0 @@
----
-sidebar_position: 10
----
-
-# File Plugin
-
-The File plugin handles multipart/form-data file uploads in your Balda.js application. It automatically parses uploaded files, validates them against size limits, and provides convenient access to file data through `req.files` and `req.file`.
-
-## Features
-
-- **Multipart Form Data**: Handles file uploads from HTML forms
-- **Size Validation**: Configurable file size limits
-- **Automatic Cleanup**: Temporary files are cleaned up automatically
-- **Multiple Files**: Support for single and multiple file uploads
-- **File Metadata**: Access to file name, size, MIME type, and temporary path
-- **Error Handling**: Graceful handling of file upload errors
-
-## Basic Configuration
-
-### Simple Setup
-
-```typescript
-import { Server } from 'balda-js';
-
-const server = new Server({
-  port: 3000,
-  plugins: {
-    file: {
-      maxFileSize: 5 * 1024 * 1024 // 5MB
-    }
-  }
-});
-```
-
-### Advanced Configuration
-
-```typescript
-const server = new Server({
-  port: 3000,
-  plugins: {
-    file: {
-      maxFileSize: 10 * 1024 * 1024, // 10MB
-      allowedMimeTypes: ['image/jpeg', 'image/png', 'application/pdf']
-    }
-  }
-});
-```
-
-## Configuration Options
-
-### Basic Options
-
-```typescript
-file: {
-  maxFileSize: 5 * 1024 * 1024, // Maximum file size in bytes (default: 5MB)
-}
-```
-
-### Advanced Options
-
-```typescript
-file: {
-  maxFileSize: 10 * 1024 * 1024, // 10MB
-  allowedMimeTypes: ['image/jpeg', 'image/png', 'application/pdf'],
-  maxFiles: 5, // Maximum number of files per request
-  preserveExtension: true // Preserve original file extensions
-}
-```
-
-## Usage Examples
-
-### Basic File Upload
-
-```typescript
-@controller('/upload')
-export class UploadController {
-  @post('/single')
-  async uploadSingleFile(req: Request, res: Response) {
-    if (!req.files || req.files.length === 0) {
-      return res.badRequest({ error: 'No file uploaded' });
-    }
-
-    const file = req.files[0];
-
-    // Access file properties
-    console.log('File name:', file.originalName);
-    console.log('File size:', file.size);
-    console.log('MIME type:', file.mimeType);
-    console.log('Temporary path:', file.tmpPath);
-
-    // Process the file (e.g., move to permanent location)
-    const permanentPath = await moveFileToPermanentLocation(file.tmpPath, file.originalName);
-
-    res.json({
-      message: 'File uploaded successfully',
-      file: {
-        name: file.originalName,
-        size: file.size,
-        path: permanentPath
-      }
-    });
-  }
-}
-```
-
-### Multiple File Upload
-
-```typescript
-@controller('/upload')
-export class UploadController {
-  @post('/multiple')
-  async uploadMultipleFiles(req: Request, res: Response) {
-    if (!req.files || req.files.length === 0) {
-      return res.badRequest({ error: 'No files uploaded' });
-    }
-
-    const uploadedFiles = [];
-
-    for (const file of req.files) {
-      // Process each file
-      const permanentPath = await moveFileToPermanentLocation(file.tmpPath, file.originalName);
-
-      uploadedFiles.push({
-        name: file.originalName,
-        size: file.size,
-        mimeType: file.mimeType,
-        path: permanentPath
-      });
-    }
-
-    res.json({
-      message: `${uploadedFiles.length} files uploaded successfully`,
-      files: uploadedFiles
-    });
-  }
-}
-```
-
-### File Upload with Form Data
-
-```typescript
-@controller('/upload')
-export class UploadController {
-  @post('/with-data')
-  async uploadWithData(req: Request, res: Response) {
-    // Access uploaded files
-    const files = req.files || [];
-
-    // Access form data
-    const title = req.body.title;
-    const description = req.body.description;
-    const category = req.body.category;
-
-    if (files.length === 0) {
-      return res.badRequest({ error: 'No file uploaded' });
-    }
-
-    const file = files[0];
-
-    // Save file and metadata to database
-    const savedFile = await saveFileToDatabase({
-      title,
-      description,
-      category,
-      fileName: file.originalName,
-      fileSize: file.size,
-      mimeType: file.mimeType,
-      filePath: await moveFileToPermanentLocation(file.tmpPath, file.originalName)
-    });
-
-    res.json({
-      message: 'File uploaded with metadata',
-      file: savedFile
-    });
-  }
-}
-```
-
-### Image Upload with Validation
-
-```typescript
-@controller('/upload')
-export class ImageController {
-  @post('/image')
-  async uploadImage(req: Request, res: Response) {
-    if (!req.files || req.files.length === 0) {
-      return res.badRequest({ error: 'No image uploaded' });
-    }
-
-    const file = req.files[0];
-
-    // Validate image type
-    const allowedTypes = ['image/jpeg', 'image/png', 'image/gif', 'image/webp'];
-    if (!allowedTypes.includes(file.mimeType)) {
-      return res.badRequest({
-        error: 'Invalid file type. Only JPEG, PNG, GIF, and WebP are allowed.'
-      });
-    }
-
-    // Validate file size (max 2MB for images)
-    const maxSize = 2 * 1024 * 1024; // 2MB
-    if (file.size > maxSize) {
-      return res.badRequest({
-        error: 'File too large. Maximum size is 2MB.'
-      });
-    }
-
-    // Process image (e.g., resize, compress)
-    const processedPath = await processImage(file.tmpPath);
-
-    res.json({
-      message: 'Image uploaded successfully',
-      image: {
-        name: file.originalName,
-        size: file.size,
-        type: file.mimeType,
-        path: processedPath
-      }
-    });
-  }
-}
-```
-
-## File Object Properties
-
-### File Structure
-
-```typescript
-interface FormFile {
-  formName: string;      // The name of the form field
-  mimeType: string;      // MIME type (e.g., "image/png")
-  size: number;          // File size in bytes
-  tmpPath: string;       // Temporary file path
-  originalName: string;  // Original filename with extension
-}
-```
-
-### Accessing File Properties
-
-```typescript
-@post('/file-info')
-async getFileInfo(req: Request, res: Response) {
-  if (!req.files || req.files.length === 0) {
-    return res.badRequest({ error: 'No file uploaded' });
-  }
-
-  const file = req.files[0];
-
-  res.json({
-    formField: file.formName,
-    originalName: file.originalName,
-    mimeType: file.mimeType,
-    size: file.size,
-    sizeInMB: (file.size / (1024 * 1024)).toFixed(2),
-    temporaryPath: file.tmpPath
-  });
-}
-```
-
-## Error Handling
-
-### File Too Large
-
-```typescript
-// When a file exceeds maxFileSize
-// Response: 400 Bad Request
-{
-  "error": "File too large",
-  "message": "File 'large-file.zip' (15MB) exceeds the maximum allowed size of 5MB"
-}
-```
-
-### No Files Uploaded
-
-```typescript
-@post('/upload')
-async uploadFile(req: Request, res: Response) {
-  if (!req.files || req.files.length === 0) {
-    return res.badRequest({
-      error: 'No file uploaded',
-      message: 'Please select a file to upload'
-    });
-  }
-
-  // Process file...
-}
-```
-
-### Invalid File Type
-
-```typescript
-@post('/upload')
-async uploadFile(req: Request, res: Response) {
-  if (!req.files || req.files.length === 0) {
-    return res.badRequest({ error: 'No file uploaded' });
-  }
-
-  const file = req.files[0];
-  const allowedTypes = ['image/jpeg', 'image/png', 'application/pdf'];
-
-  if (!allowedTypes.includes(file.mimeType)) {
-    return res.badRequest({
-      error: 'Invalid file type',
-      message: `File type '${file.mimeType}' is not allowed. Allowed types: ${allowedTypes.join(', ')}`
-    });
-  }
-
-  // Process file...
-}
-```
-
-## File Processing Examples
-
-### Moving Files to Permanent Location
-
-```typescript
-@post('/upload')
-async uploadFile(req: Request, res: Response) {
-  if (!req.files || req.files.length === 0) {
-    return res.badRequest({ error: 'No file uploaded' });
-  }
-
-  const file = req.files[0];
-  const permanentPath = await moveFileToPermanentLocation(file.tmpPath, file.originalName);
-
-  res.json({
-    message: 'File uploaded successfully',
-    path: permanentPath
-  });
-}
-
-@post('/image')
-async uploadImage(req: Request, res: Response) {
-  if (!req.files || req.files.length === 0) {
-    return res.badRequest({ error: 'No image uploaded' });
-  }
-
-  const file = req.files[0];
-  const processedPath = await processImage(file.tmpPath);
-
-  res.json({
-    message: 'Image processed and uploaded',
-    path: processedPath
-  });
-}
-```
-
-## HTML Form Examples
-
-### Single File Upload
-
-```html
-<form action="/upload/single" method="post" enctype="multipart/form-data">
-  <input type="file" name="file" required>
-  <button type="submit">Upload File</button>
-</form>
-```
-
-### Multiple File Upload
-
-```html
-<form action="/upload/multiple" method="post" enctype="multipart/form-data">
-  <input type="file" name="files" multiple required>
-  <button type="submit">Upload Files</button>
-</form>
-```
-
-### File Upload with Form Data
-
-```html
-<form action="/upload/with-data" method="post" enctype="multipart/form-data">
-  <input type="text" name="title" placeholder="File title" required>
-  <textarea name="description" placeholder="File description"></textarea>
-  <select name="category">
-    <option value="document">Document</option>
-    <option value="image">Image</option>
-    <option value="video">Video</option>
-  </select>
-  <input type="file" name="file" required>
-  <button type="submit">Upload</button>
-</form>
-```