Skip to main content
Version: 🚧 Canary

🔧 File Storage Blocks

File storage blocks provide pure business logic functions for secure file management operations. These blocks handle file upload, download, and deletion through cloud storage providers with signed URLs.

🎯 Overview​

File storage blocks are designed to:

  • Generate secure signed URLs for file operations
  • Handle different file types with content type validation
  • Support avatar uploads with automatic UUID generation
  • Provide cloud storage integration through storage drivers
  • Ensure error handling with proper logging

📋 Available File Storage Blocks​

generateSignedUploadUrl​

Generates a signed upload URL for secure file uploads to cloud storage.

Purpose: Creates pre-signed URLs for secure file uploads to cloud storage

Parameters:

  • logger: Pick<Logger, 'error'> - Logger instance for error reporting
  • fileStorageDriver: FileStorageDriver - File storage driver for cloud storage operations
  • contentType: string - MIME type of the file to be uploaded
  • contentLength: number - Size of the file in bytes
  • objectName: string - Target object name/key in storage

Returns: Promise<Result<string, FileStorageServiceError>>

Handler Process:

  • Input: Logger, storage driver, contentType, contentLength, and objectName
  • Process: Delegates to storage driver to generate a signed PUT/POST URL for the given object name and constraints
  • Output: Pre-signed URL string usable by clients for direct upload
  • Errors: FileStorageServiceError when the storage driver cannot generate the URL

Example Usage:

import { blocks } from '@nodeblocks/backend-sdk';

const result = await blocks.generateSignedUploadUrl(
  logger,
  fileStorageDriver,
  'image/jpeg',
  1024000,
  'uploads/document.pdf'
);

if (result.isOk()) {
  const signedUrl = result.value;
  // Use signedUrl for file upload
}

generateSignedDownloadUrl​

Generates a signed download URL for secure file access from cloud storage.

Purpose: Creates pre-signed URLs for secure file downloads from cloud storage

Parameters:

  • logger: Pick<Logger, 'error'> - Logger instance for error reporting
  • fileStorageDriver: FileStorageDriver - File storage driver for cloud storage operations
  • objectName: string - Object name/key in storage to download

Returns: Promise<Result<string, FileStorageServiceError>>

Handler Process:

  • Input: Logger, storage driver, objectName
  • Process: Delegates to storage driver to generate a time-limited GET URL for the object
  • Output: Pre-signed URL string usable by clients for direct download
  • Errors: FileStorageServiceError when the storage driver cannot generate the URL

Example Usage:

import { blocks } from '@nodeblocks/backend-sdk';

const result = await blocks.generateSignedDownloadUrl(
  logger,
  fileStorageDriver,
  'uploads/document.pdf'
);

if (result.isOk()) {
  const signedUrl = result.value;
  // Use signedUrl for file download
}

generateSignedDeleteUrl​

Generates a signed delete URL for secure file deletion from cloud storage.

Purpose: Creates pre-signed URLs for secure file deletion from cloud storage

Parameters:

  • logger: Pick<Logger, 'error'> - Logger instance for error reporting
  • fileStorageDriver: FileStorageDriver - File storage driver for cloud storage operations
  • objectName: string - Object name/key in storage to delete

Returns: Promise<Result<string, FileStorageServiceError>>

Handler Process:

  • Input: Logger, storage driver, objectName
  • Process: Delegates to storage driver to generate a signed DELETE URL (or signed request) for the object
  • Output: Pre-signed URL string usable by clients to delete the object
  • Errors: FileStorageServiceError when the storage driver cannot generate the URL

Example Usage:

import { blocks } from '@nodeblocks/backend-sdk';

const result = await blocks.generateSignedDeleteUrl(
  logger,
  fileStorageDriver,
  'uploads/document.pdf'
);

if (result.isOk()) {
  const signedUrl = result.value;
  // Use signedUrl for file deletion
}

generateSignedAvatarUploadUrl​

Generates a signed upload URL for avatar file uploads with predefined settings.

Purpose: Creates pre-signed URLs for avatar uploads with automatic UUID filename generation

Parameters:

  • logger: Pick<Logger, 'error'> - Logger instance with error reporting capability
  • fileStorageDriver: FileStorageDriver - File storage driver for cloud storage operations
  • contentType: string - MIME type of the avatar file to be uploaded
  • contentLength: number - Size of the avatar file in bytes

Returns: Promise<Result<{objectId: string, url: string}, FileStorageServiceError>>

Handler Process:

  • Input: Logger, storage driver, contentType, contentLength
  • Process: Generates a UUID objectId with an extension inferred from contentType, asks driver for signed upload URL
  • Output: { objectId, url } where objectId is the storage key and url is the signed upload URL
  • Errors: FileStorageServiceError when the storage driver cannot generate the URL

Example Usage:

import { blocks } from '@nodeblocks/backend-sdk';

const result = await blocks.generateSignedAvatarUploadUrl(
  logger,
  fileStorageDriver,
  'image/png',
  512000
);

if (result.isOk()) {
  const { objectId, url } = result.value;
  // Use url for avatar upload, objectId for database storage
}

deleteFile​

Deletes a file from cloud storage using the storage driver.

Purpose: Removes an object from storage by key.

Parameters:

  • logger: Pick<Logger, 'error'> - Logger instance for error reporting
  • fileStorageDriver: FileStorageDriver - File storage driver for cloud storage operations
  • objectName: string - Object name/key in storage to delete

Returns: Promise<Result<void, FileStorageServiceError>>

Handler Process:

  • Input: Logger, storage driver, objectName
  • Process: Delegates to storage driver to remove the object; may be a direct API call instead of signed URL
  • Output: ok(undefined) on success
  • Errors: FileStorageServiceError if the driver fails to delete the file

Example Usage:

import { blocks } from '@nodeblocks/backend-sdk';

const result = await blocks.deleteFile(logger, fileStorageDriver, 'uploads/document.pdf');
if (result.isOk()) {
  // File deleted
}

🔗 Related Documentation​