Skip to main content
Version: 🚧 Canary

💾 File Storage Drivers

File storage drivers provide a consistent interface for secure file operations in NodeBlocks applications. They abstract cloud storage provider configurations and operations, allowing you to use different storage services without changing your business logic.

🎯 Overview​

File storage drivers in NodeBlocks are factory functions that create configured storage instances with signed URL capabilities. They provide:

  • Secure file operations with signed URLs for upload, download, and deletion
  • Consistent interface across different cloud storage providers
  • Simple configuration with project IDs and bucket names
  • Testing support with mock implementations

📋 Available File Storage Drivers​

Google Cloud Storage Driver​

The Google Cloud Storage driver creates a configured file storage instance with signed URL generation capabilities.

Prerequisites​

To use this driver, authenticate the Google Cloud SDK client by providing Application Default Credentials:

  • Create a Google Cloud service account with permissions to access your bucket
  • Download a service account JSON key file
  • Set the GOOGLE_APPLICATION_CREDENTIALS environment variable to the absolute path of the JSON key file

The driver relies on Google Cloud Application Default Credentials; no credentials are passed directly to createFileStorageDriver.

createFileStorageDriver​

Creates Google Cloud Storage file storage driver with signed URL capabilities.

Parameters:

  • projectId: string - Google Cloud project identifier
  • bucketName: string - Storage bucket name for file operations
  • options?: object - Optional configuration
    • signedUrlExpiresInSeconds?: number - Default URL validity duration in seconds (default: 900)

Returns: FileStorageDriver - File storage driver with signed URL generation methods

Usage:

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

const fileStorage = createFileStorageDriver(
  'my-project-id',
  'my-storage-bucket'
);

Example with Custom Expiry:

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

const fileStorage = createFileStorageDriver(
  'my-project-id',
  'my-storage-bucket',
  { signedUrlExpiresInSeconds: 1800 } // 30 minutes
);

🔧 File Storage Driver Methods​

The FileStorageDriver provides methods for secure file operations including deletion and signed URL generation:

deleteFile​

Deletes a file from Google Cloud Storage bucket.

Parameters:

  • objectName: string - Storage object name/path to delete from bucket

Returns: Promise<void> - Promise that resolves when file deletion is complete

Usage:

await fileStorage.deleteFile('uploads/temp-file.jpg');

generateSignedDeleteUrl​

Generates signed URL for file deletion operations in Google Cloud Storage.

Parameters:

  • objectName: string - Storage object name/path to delete

Returns: Promise<string> - Signed URL for file deletion

Usage:

const deleteUrl = await fileStorage.generateSignedDeleteUrl('uploads/temp-file.jpg');

generateSignedDownloadUrl​

Generates signed URL for file download operations in Google Cloud Storage.

Parameters:

  • objectName: string - Storage object name/path to download

Returns: Promise<string> - Signed URL for file download

Usage:

const downloadUrl = await fileStorage.generateSignedDownloadUrl('uploads/document.pdf');

generateSignedUploadUrl​

Generates signed URL for file upload operations in Google Cloud Storage.

Parameters:

  • contentType: string - MIME type of file to upload
  • contentLength: number - Maximum file size in bytes
  • objectName: string - Storage object name/path for upload

Returns: Promise<string> - Signed URL for file upload

Usage:

const uploadUrl = await fileStorage.generateSignedUploadUrl(
  'image/jpeg',
  5 * 1024 * 1024, // 5MB limit
  'uploads/profile-avatar.jpg'
);

cURL Example:

# Upload file using signed URL
curl -X PUT \
  -H "Content-Type: image/jpeg" \
  -H "Content-Length: 5242880" \
  --upload-file ./avatar.jpg \
  "https://storage.googleapis.com/my-bucket/uploads/profile-avatar.jpg?X-Goog-Algorithm=ALGORITHM&X-Goog-Credential=CREDENTIAL&X-Goog-Date=DATE&X-Goog-Expires=EXPIRES&X-Goog-SignedHeaders=host&X-Goog-Signature=SIGNATURE"

generateSignedDownloadUrl​

Generates signed URL for file download operations in Google Cloud Storage.

Parameters:

  • objectName: string - Storage object name/path to download

Returns: Promise<string> - Signed URL for file download

Usage:

const downloadUrl = await fileStorage.generateSignedDownloadUrl('uploads/document.pdf');

cURL Example:

# Download file using signed URL
curl -O \
  "https://storage.googleapis.com/my-bucket/uploads/document.pdf?X-Goog-Algorithm=ALGORITHM&X-Goog-Credential=CREDENTIAL&X-Goog-Date=DATE&X-Goog-Expires=EXPIRES&X-Goog-SignedHeaders=host&X-Goog-Signature=SIGNATURE"

generateSignedDeleteUrl​

Generates signed URL for file deletion operations in Google Cloud Storage.

Parameters:

  • objectName: string - Storage object name/path to delete

Returns: Promise<string> - Signed URL for file deletion

Usage:

const deleteUrl = await fileStorage.generateSignedDeleteUrl('uploads/temp-file.jpg');

cURL Example:

# Delete file using signed URL
curl -X DELETE \
  "https://storage.googleapis.com/my-bucket/uploads/temp-file.jpg?X-Goog-Algorithm=ALGORITHM&X-Goog-Credential=CREDENTIAL&X-Goog-Date=DATE&X-Goog-Expires=EXPIRES&X-Goog-SignedHeaders=host&X-Goog-Signature=SIGNATURE"

🔗 Related Documentation​