BufferedFile Class - 🌲 Sonamu

The BufferedFile class provides information about uploaded files and saves files using the saveToDisk() method.

BufferedFile Overview

File Info

filename, mimetype, size extname, md5

saveToDisk()

Save to storage Auto URL generation

buffer

Buffer access .buffer getter

URL Properties

url, signedUrl Auto-set after saving

Basic Properties

File Information

import type { BufferedFile } from "sonamu";

class FileModel extends BaseModelClass {
  @upload()
  async upload(): Promise<any> {
    const { bufferedFiles } = Sonamu.getContext();
    const file = bufferedFiles?.[0];
    if (!file) throw new Error("File is required");

    // Access file info
    console.log({
      filename: file.filename, // Original filename: "photo.jpg"
      mimetype: file.mimetype, // MIME type: "image/jpeg"
      size: file.size, // File size (bytes): 524288
      extname: file.extname, // Extension: "jpg" (without dot)
    });

    return {
      filename: file.filename,
      mimetype: file.mimetype,
      size: file.size,
      extname: file.extname,
    };
  }
}

Property List:

filename: string - Original filename
mimetype: string - MIME type
size: number - File size (bytes)
extname: string | false - Extension (without dot)
url: string | undefined - Public URL after saving
signedUrl: string | undefined - Signed URL after saving

saveToDisk() Method

Basic Usage

class FileModel extends BaseModelClass {
  @upload()
  async upload(): Promise<{ url: string }> {
    const { bufferedFiles } = Sonamu.getContext();
    const file = bufferedFiles?.[0];
    if (!file) throw new Error("File is required");

    // Save file (using default disk)
    const url = await file.saveToDisk("fs", `uploads/${Date.now()}-${file.filename}`);

    // Automatically saved to url property
    console.log(file.url); // Public URL
    console.log(file.signedUrl); // Signed URL

    return { url };
  }
}

Save to Specific Disk

class FileModel extends BaseModelClass {
  @upload()
  async uploadToS3(): Promise<{ url: string }> {
    const { bufferedFiles } = Sonamu.getContext();
    const file = bufferedFiles?.[0];
    if (!file) throw new Error("File is required");

    // Save to S3 disk
    const url = await file.saveToDisk("s3", `uploads/${Date.now()}-${file.filename}`);

    return { url };
  }

  @upload()
  async uploadPublic(): Promise<{ url: string }> {
    const { bufferedFiles } = Sonamu.getContext();
    const file = bufferedFiles?.[0];
    if (!file) throw new Error("File is required");

    // Save to public disk
    const url = await file.saveToDisk("public", `public/${Date.now()}-${file.filename}`);

    return { url };
  }
}

buffer Getter

buffer Property

class FileModel extends BaseModelClass {
  @upload()
  async processImage(): Promise<{ url: string }> {
    const { bufferedFiles } = Sonamu.getContext();
    const image = bufferedFiles?.[0];
    if (!image) throw new Error("Image is required");

    // Access Buffer directly
    const buffer = image.buffer;

    console.log("Buffer size:", buffer.length);

    // Image processing using Buffer
    const sharp = require("sharp");
    const resized = await sharp(buffer).resize(800, 600).toBuffer();

    // Save processed image
    // (saveToDisk saves original file,
    // use Storage Manager directly for processed Buffer)
    const disk = Sonamu.storage.use();
    const key = `images/${Date.now()}.jpg`;

    await disk.put(key, new Uint8Array(resized), {
      contentType: "image/jpeg",
    });

    const url = await disk.getUrl(key);

    return { url };
  }
}

.buffer is a getter that returns the pre-loaded Buffer from multipart parsing.

MD5 Hash

md5() Method

class FileModel extends BaseModelClass {
  @upload()
  async uploadWithHash(): Promise<{
    url: string;
    md5: string;
  }> {
    const { bufferedFiles } = Sonamu.getContext();
    const file = bufferedFiles?.[0];
    if (!file) throw new Error("File is required");

    // Calculate MD5 hash
    const md5Hash = await file.md5();
    console.log("MD5:", md5Hash); // "abc123def456..."

    // Check for duplicate files
    const rdb = this.getPuri("r");
    const existing = await rdb.table("files").where("md5_hash", md5Hash).first();

    if (existing) {
      // Same file already exists
      return {
        url: existing.url,
        md5: md5Hash,
      };
    }

    // Save new file
    const url = await file.saveToDisk("fs", `uploads/${md5Hash}.${file.extname}`);

    // Save to DB
    const wdb = this.getPuri("w");
    await wdb.table("files").insert({
      filename: file.filename,
      mime_type: file.mimetype,
      size: file.size,
      md5_hash: md5Hash,
      url,
    });

    return { url, md5: md5Hash };
  }
}

File Validation

Size Validation

class FileValidator {
  static validateSize(file: UploadedFile, maxSize: number): void {
    if (file.size > maxSize) {
      throw new Error(`File too large: ${file.size} bytes (max ${maxSize} bytes)`);
    }
  }
}

// Usage
class FileModel extends BaseModelClass {
  @upload()
  async upload(): Promise<{ url: string }> {
    const { bufferedFiles } = Sonamu.getContext();
    const file = bufferedFiles?.[0];
    if (!file) throw new Error("File is required");

    // Size validation (10MB)
    FileValidator.validateSize(file, 10 * 1024 * 1024);

    const url = await file.saveToDisk("fs", `uploads/${Date.now()}.${file.extname}`);

    return { url };
  }
}

MIME Type Validation

class FileValidator {
  static validateMimeType(file: UploadedFile, allowedTypes: string[]): void {
    if (!allowedTypes.includes(file.mimetype)) {
      throw new Error(
        `Invalid file type: ${file.mimetype}. ` + `Allowed: ${allowedTypes.join(", ")}`,
      );
    }
  }
}

// Usage
class ImageModel extends BaseModelClass {
  @upload()
  async uploadImage(): Promise<{ url: string }> {
    const { bufferedFiles } = Sonamu.getContext();
    const image = bufferedFiles?.[0];
    if (!image) throw new Error("Image is required");

    // MIME type validation
    FileValidator.validateMimeType(image, ["image/jpeg", "image/png", "image/gif", "image/webp"]);

    const url = await image.saveToDisk("fs", `images/${Date.now()}.${image.extname}`);

    return { url };
  }
}

Extension Validation

class FileValidator {
  static validateExtension(file: UploadedFile, allowedExtensions: string[]): void {
    const ext = file.extname;

    if (!ext || !allowedExtensions.includes(ext.toLowerCase())) {
      throw new Error(
        `Invalid file extension: ${ext}. ` + `Allowed: ${allowedExtensions.join(", ")}`,
      );
    }
  }
}

// Usage
class DocumentModel extends BaseModelClass {
  @upload()
  async uploadDocument(): Promise<{ url: string }> {
    const { bufferedFiles } = Sonamu.getContext();
    const document = bufferedFiles?.[0];
    if (!document) throw new Error("Document is required");

    // Extension validation
    FileValidator.validateExtension(document, ["pdf", "doc", "docx", "txt"]);

    const url = await document.saveToDisk("fs", `documents/${Date.now()}.${document.extname}`);

    return { url };
  }
}

Integrated Validation Class

class FileValidator {
  static validateImage(file: UploadedFile): void {
    // Check size (5MB)
    if (file.size > 5 * 1024 * 1024) {
      throw new Error("Image too large (max 5MB)");
    }

    // Check MIME type
    const allowedTypes = ["image/jpeg", "image/png", "image/gif", "image/webp"];
    if (!allowedTypes.includes(file.mimetype)) {
      throw new Error(`Invalid image type: ${file.mimetype}`);
    }

    // Check extension
    const allowedExtensions = ["jpg", "jpeg", "png", "gif", "webp"];
    if (!file.extname || !allowedExtensions.includes(file.extname.toLowerCase())) {
      throw new Error(`Invalid image extension: ${file.extname}`);
    }
  }

  static validateDocument(file: UploadedFile): void {
    // Check size (20MB)
    if (file.size > 20 * 1024 * 1024) {
      throw new Error("Document too large (max 20MB)");
    }

    // Check MIME type
    const allowedTypes = [
      "application/pdf",
      "application/msword",
      "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
      "text/plain",
    ];

    if (!allowedTypes.includes(file.mimetype)) {
      throw new Error(`Invalid document type: ${file.mimetype}`);
    }
  }

  static validateVideo(file: UploadedFile): void {
    // Check size (100MB)
    if (file.size > 100 * 1024 * 1024) {
      throw new Error("Video too large (max 100MB)");
    }

    // Check MIME type
    const allowedTypes = ["video/mp4", "video/mpeg", "video/quicktime", "video/x-msvideo"];

    if (!allowedTypes.includes(file.mimetype)) {
      throw new Error(`Invalid video type: ${file.mimetype}`);
    }
  }
}

// Usage
class MediaModel extends BaseModelClass {
  @upload()
  async uploadImage(): Promise<{ url: string }> {
    const { bufferedFiles } = Sonamu.getContext();
    const image = bufferedFiles?.[0];
    if (!image) throw new Error("Image is required");

    FileValidator.validateImage(image);

    const url = await image.saveToDisk("fs", `images/${Date.now()}.${image.extname}`);

    return { url };
  }
}

Practical Examples

Profile Image Upload

class UserModel extends BaseModelClass {
  @upload()
  async uploadProfileImage(): Promise<{
    imageId: number;
    url: string;
    thumbnailUrl: string;
  }> {
    const context = Sonamu.getContext();

    if (!context.user) {
      throw new Error("Authentication required");
    }

    const { bufferedFiles } = context;
    const image = bufferedFiles?.[0];
    if (!image) throw new Error("Image is required");

    // Validation
    FileValidator.validateImage(image);

    // Original image Buffer
    const buffer = image.buffer;

    // Create thumbnail
    const sharp = require("sharp");
    const thumbnailBuffer = await sharp(buffer)
      .resize(200, 200, { fit: "cover" })
      .jpeg({ quality: 80 })
      .toBuffer();

    // Save original
    const originalKey = `profiles/${context.user.id}/original-${Date.now()}.${image.extname}`;
    const originalUrl = await image.saveToDisk("fs", originalKey);

    // Save thumbnail (using Storage Manager directly)
    const disk = Sonamu.storage.use();
    const thumbnailKey = `profiles/${context.user.id}/thumb-${Date.now()}.jpg`;
    await disk.put(thumbnailKey, new Uint8Array(thumbnailBuffer), {
      contentType: "image/jpeg",
    });
    const thumbnailUrl = await disk.getUrl(thumbnailKey);

    // Save to DB
    const wdb = this.getPuri("w");
    const [record] = await wdb
      .table("profile_images")
      .insert({
        user_id: context.user.id,
        original_key: originalKey,
        thumbnail_key: thumbnailKey,
        original_url: originalUrl,
        thumbnail_url: thumbnailUrl,
        mime_type: image.mimetype,
        size: image.size,
      })
      .returning("id");

    return {
      imageId: record.id,
      url: originalUrl,
      thumbnailUrl,
    };
  }
}

Batch Processing Multiple Files

class FileModel extends BaseModelClass {
  @upload()
  async uploadMultiple(params: { category?: string }): Promise<{
    uploadedFiles: Array<{
      fileId: number;
      filename: string;
      url: string;
      md5: string;
    }>;
  }> {
    const { bufferedFiles } = Sonamu.getContext();
    const { category } = params;

    if (!bufferedFiles || bufferedFiles.length === 0) {
      throw new Error("At least one file is required");
    }

    if (bufferedFiles.length > 10) {
      throw new Error("Maximum 10 files allowed");
    }

    const uploadedFiles = [];
    const wdb = this.getPuri("w");

    for (const file of bufferedFiles) {
      // Validation
      if (file.size > 20 * 1024 * 1024) {
        throw new Error(`File ${file.filename} too large (max 20MB)`);
      }

      // MD5 hash
      const md5Hash = await file.md5();

      // Duplicate check
      const rdb = this.getPuri("r");
      const existing = await rdb.table("files").where("md5_hash", md5Hash).first();

      if (existing) {
        // File already exists
        uploadedFiles.push({
          fileId: existing.id,
          filename: existing.filename,
          url: existing.url,
          md5: md5Hash,
        });
        continue;
      }

      // Save new file
      const key = `uploads/${category}/${Date.now()}.${file.extname}`;
      const url = await file.saveToDisk("fs", key);

      // Save to DB
      const [record] = await wdb
        .table("files")
        .insert({
          key,
          filename: file.filename,
          mime_type: file.mimetype,
          size: file.size,
          md5_hash: md5Hash,
          url,
          category,
        })
        .returning("id");

      uploadedFiles.push({
        fileId: record.id,
        filename: file.filename,
        url,
        md5: md5Hash,
      });
    }

    return { uploadedFiles };
  }
}

Accessing Original MultipartFile

raw Property

class FileModel extends BaseModelClass {
  @upload()
  async uploadAdvanced(): Promise<any> {
    const { bufferedFiles } = Sonamu.getContext();
    const file = bufferedFiles?.[0];
    if (!file) throw new Error("File is required");

    // Access original Fastify MultipartFile
    const rawFile = file.raw;

    console.log({
      encoding: rawFile.encoding,
      fieldname: rawFile.fieldname,
      // ...
    });

    const url = await file.saveToDisk("fs", `uploads/${Date.now()}.${file.extname}`);

    return { url };
  }
}

Cautions

Cautions when using UploadedFile: 1. Validation is required before calling saveToDisk() 2. .buffer gives direct access to the pre-loaded Buffer 3. url, signedUrl are only available after saving 4. Consider streaming for large files 5. Verify Storage configuration

Next Steps

File Upload Setup

@upload decorator setup

Saving Files

Using Storage Manager

URL Generation

Generating URLs

@api Decorator

API basic usage

​BufferedFile Overview

File Info

saveToDisk()

buffer

URL Properties

​Basic Properties

​File Information

​saveToDisk() Method

​Basic Usage

​Save to Specific Disk

​buffer Getter

​buffer Property

​MD5 Hash

​md5() Method

​File Validation

​Size Validation

​MIME Type Validation

​Extension Validation

​Integrated Validation Class

​Practical Examples

​Profile Image Upload

​Batch Processing Multiple Files

​Accessing Original MultipartFile

​raw Property

​Cautions

​Next Steps

File Upload Setup

Saving Files

URL Generation

@api Decorator

BufferedFile Overview

Basic Properties

File Information

saveToDisk() Method

Basic Usage

Save to Specific Disk

buffer Getter

buffer Property

MD5 Hash

md5() Method

File Validation

Size Validation

MIME Type Validation

Extension Validation

Integrated Validation Class

Practical Examples

Profile Image Upload

Batch Processing Multiple Files

Accessing Original MultipartFile

raw Property

Cautions

Next Steps