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:

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: Storage driver, content type, content length, and object name
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(
  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:

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: File storage driver and object name for file download
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(
  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:

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: File storage driver and object name to generate delete URL for
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(
  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 automatic object ID generation.

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

Parameters:

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: Storage driver, content type, and content length for avatar upload
Process: Creates UUID objectId, derives file extension from content type, generates signed upload URL
Output: Result with objectId and signed upload URL for avatar file
Errors: FileStorageServiceError if URL generation fails

Example Usage:

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

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

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

`generateFileUploadUrl`

Generates a signed upload URL with automatic UUID object ID generation for generic file uploads.

Purpose: Creates pre-signed URLs for generic file uploads with auto-generated filenames

Parameters:

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

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

Handler Process:

Input: File storage driver, content type, and content length
Process: Creates a UUID objectId, derives object name with file extension, delegates to signed URL generator
Output: Object containing objectId and a signed upload URL
Errors: FileStorageServiceError if URL generation fails

Key Features:

Automatic UUID generation for unique file identification
File extension automatically derived from MIME type
Works with any content type supported by the storage driver
Suitable for logos, certificates, documents, and other generic files

Example Usage:

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

// Used in route composition:
const fileUploadRoute = withRoute({
  handler: compose(
    applyPayloadArgs(blocks.generateFileUploadUrl, [
      ['context', 'fileStorageDriver'],
      ['params', 'requestQuery', 'contentType'],
      ['params', 'requestQuery', 'contentLength']
    ])
  )
});

// Generate file upload URL:
const result = await blocks.generateFileUploadUrl(
  fileStorageDriver,
  'application/pdf',
  1024000
);

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

`deleteFile`

Deletes a file from cloud storage using the provided object name.

Purpose: Removes an object from storage by key.

Parameters:

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: File storage driver and object name to delete
Process: Delegates to storage driver to remove the object; may be a direct API call instead of signed URL
Output: Result with deletion confirmation or error
Errors: FileStorageServiceError if the driver fails to delete the file

Example Usage:

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

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

`normalizeFile`

Normalizes file data with signed download URL generation for API responses.

Purpose: Transforms file metadata by generating signed download URLs for secure file access, enabling API responses to include accessible file URLs instead of just object identifiers.

Parameters:

fileStorageDriver: FileStorageDriver - File storage driver for generating signed download URLs
file: { objectId: string; type: string } & Record<string, unknown> - File object containing objectId, type, and additional metadata

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

Handler Process:

Input: File storage driver and file object with objectId, content type, and additional properties
Process: Generates signed download URL using objectId with file extension, preserves all other file properties
Output: Normalized file object with signed URL and original type/metadata
Errors: FileStorageServiceError when URL generation fails

Key Features:

URL Generation: Automatically creates signed download URLs for secure file access
File Extension Handling: Derives file extension from MIME type for proper storage paths
Data Preservation: Maintains all original file metadata while adding URL
Error Handling: Comprehensive error handling for storage operations

Example Usage:

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

// Used in handler composition:
const handler = compose(normalizeFile, nextHandler);

// Direct usage:
const result = await blocks.normalizeFile(
  fileStorageDriver,
  {
    objectId: 'file-123',
    type: 'image/jpeg',
    name: 'photo.jpg',
    size: 1024000
  }
);

if (result.isOk()) {
  const normalizedFile = result.value;
  // normalizedFile.url contains signed download URL
  // normalizedFile.type contains 'image/jpeg'
  // normalizedFile.name and size are preserved
}

File Storage Overview - File storage domain overview
File Storage Schemas - Schema documentation

🎯 Overview​

📋 Available File Storage Blocks​

generateSignedUploadUrl​

generateSignedDownloadUrl​

generateSignedDeleteUrl​

generateSignedAvatarUploadUrl​

generateFileUploadUrl​

deleteFile​

normalizeFile​

🔗 Related Documentation​

🎯 Overview

📋 Available File Storage Blocks

`generateSignedUploadUrl`

`generateSignedDownloadUrl`

`generateSignedDeleteUrl`

`generateSignedAvatarUploadUrl`

`generateFileUploadUrl`

`deleteFile`

`normalizeFile`

🔗 Related Documentation