Class GoogleFileStorage

Creates a new instance of GoogleFileStorage.

Initializes the connection to Google Cloud Storage using environment variables. Throws an error if any required environment variables are missing.

Checks if Google Cloud Storage provider is properly configured. Returns true if service account credentials and bucket name are present.

Copies an object within Google Cloud Storage.

This method creates a copy of an object at a new location without removing the original. It uses the GCS copy API, which allows for efficient copying within the same bucket.

Example

// Create a backup copy of an important file
const copied = await gcsStorage.CopyObject(
  'documents/contract.pdf',
  'backups/contract_2024-05-16.pdf'
);

if (copied) {
  console.log('File copied successfully');
} else {
  console.log('Failed to copy file');
}
Copy

Creates a directory (virtual) in Google Cloud Storage.

Since GCS doesn't have a native directory concept, this method creates a zero-byte object with a trailing slash to simulate a directory. The object has a special content type to indicate it's a directory.

Example

// Create a new directory structure
const created = await gcsStorage.CreateDirectory('documents/reports/annual/');

if (created) {
  console.log('Directory created successfully');
} else {
  console.log('Failed to create directory');
}
Copy

Creates a pre-authenticated download URL for an object in Google Cloud Storage.

This method generates a signed URL that allows for downloading an object from GCS without needing Google Cloud credentials. The URL is valid for 10 minutes and can be shared with clients.

Example

// Generate a pre-authenticated download URL for a PDF file
const downloadUrl = await gcsStorage.CreatePreAuthDownloadUrl('documents/report.pdf');

// The URL can be shared with users or used in applications for direct download
console.log(downloadUrl);
Copy

Creates a pre-authenticated upload URL for an object in Google Cloud Storage.

This method generates a signed URL that allows for uploading an object to GCS without needing Google Cloud credentials. The URL is valid for 10 minutes and includes the content type based on the file extension.

Example

// Generate a pre-authenticated upload URL for a PDF file
const { UploadUrl } = await gcsStorage.CreatePreAuthUploadUrl('documents/report.pdf');

// The URL can be used with fetch or other HTTP clients to upload the file
console.log(UploadUrl);
Copy

Deletes a directory (virtual) and optionally its contents from Google Cloud Storage.

For non-recursive deletion, this method simply deletes the directory placeholder object. For recursive deletion, it lists all objects with the directory path as prefix and deletes them in parallel.

Example

// Delete an empty directory
const deleted = await gcsStorage.DeleteDirectory('documents/temp/');

// Delete a directory and all its contents
const recursivelyDeleted = await gcsStorage.DeleteDirectory('documents/old_projects/', true);
Copy

Deletes an object from Google Cloud Storage.

This method attempts to delete the specified object. It uses the ignoreNotFound option to ensure it returns true even if the object didn't exist.

Example

// Delete a temporary file
const deleted = await gcsStorage.DeleteObject('temp/report-draft.pdf');

if (deleted) {
  console.log('File successfully deleted');
} else {
  console.log('Failed to delete file');
}
Copy

Checks if a directory (virtual) exists in Google Cloud Storage.

Since GCS doesn't have a native directory concept, this method checks for either:

1. The existence of a directory placeholder object (zero-byte object with trailing slash)
2. The existence of any objects with the directory path as a prefix

Example

// Check if a directory exists before trying to save files to it
const exists = await gcsStorage.DirectoryExists('documents/reports/');

if (!exists) {
  console.log('Directory does not exist, creating it first');
  await gcsStorage.CreateDirectory('documents/reports/');
}

// Now safe to use the directory
await gcsStorage.PutObject('documents/reports/new-report.pdf', fileData);
Copy

Downloads an object's content from Google Cloud Storage.

This method retrieves the full content of an object and returns it as a Buffer for processing in memory.

Throws

Error if the object doesn't exist or cannot be downloaded

Example

try {
  // For GCS, objectId and fullPath are the same (both are the object name)
  const content = await gcsStorage.GetObject({ fullPath: 'documents/config.json' });
  // Or equivalently:
  const content2 = await gcsStorage.GetObject({ objectId: 'documents/config.json' });

  // Parse the JSON content
  const config = JSON.parse(content.toString('utf8'));
  console.log('Configuration loaded:', config);
} catch (error) {
  console.error('Failed to download file:', error.message);
}
Copy

Retrieves metadata for a specific object in Google Cloud Storage.

This method fetches the properties of an object without downloading its content, which is more efficient for checking file attributes like size, content type, and last modified date.

Throws

Error if the object doesn't exist or cannot be accessed

Example

try {
  // For GCS, objectId and fullPath are the same (both are the object name)
  const metadata = await gcsStorage.GetObjectMetadata({ fullPath: 'documents/report.pdf' });
  // Or equivalently:
  const metadata2 = await gcsStorage.GetObjectMetadata({ objectId: 'documents/report.pdf' });

  console.log(`File: ${metadata.name}`);
  console.log(`Size: ${metadata.size} bytes`);
  console.log(`Last modified: ${metadata.lastModified}`);
} catch (error) {
  console.error('File does not exist or cannot be accessed');
}
Copy

Lists objects with the specified prefix in Google Cloud Storage.

This method returns a list of objects (files) and prefixes (directories) under the specified path prefix. It uses the GCS getFiles API which supports delimiter-based hierarchy simulation.

Note: This implementation fetches metadata for each file, which can be inefficient for directories with many files. In a production environment, you might want to optimize this for large directories.

Example

// List all files and directories in the documents folder
const result = await gcsStorage.ListObjects('documents/');

// Process files
for (const file of result.objects) {
  console.log(`File: ${file.name}, Size: ${file.size}, Type: ${file.contentType}`);
}

// Process subdirectories
for (const dir of result.prefixes) {
  console.log(`Directory: ${dir}`);
}
Copy

Moves an object from one location to another within Google Cloud Storage.

Unlike some other storage providers, GCS has a native rename operation that can be used to efficiently move objects without needing to copy and delete. This method leverages that capability.

Example

// Move a file from drafts to published folder
const success = await gcsStorage.MoveObject(
  'drafts/report.docx',
  'published/final-report.docx'
);

if (success) {
  console.log('File successfully moved');
} else {
  console.log('Failed to move file');
}
Copy

Checks if an object exists in Google Cloud Storage.

This method verifies the existence of an object without downloading its content. This is efficient for validation purposes.

Example

// Check if a file exists before attempting to use it
const exists = await gcsStorage.ObjectExists('documents/report.pdf');

if (exists) {
  console.log('File exists, proceeding with download');
  const content = await gcsStorage.GetObject('documents/report.pdf');
  // Process the content...
} else {
  console.log('File does not exist');
}
Copy

Uploads data to an object in Google Cloud Storage.

This method directly uploads a Buffer of data to an object with the specified name. It's useful for server-side operations where you already have the data in memory.

Example

// Upload a text file
const content = Buffer.from('Hello, World!', 'utf8');
const uploaded = await gcsStorage.PutObject(
  'documents/hello.txt',
  content,
  'text/plain',
  { author: 'John Doe', department: 'Engineering' }
);

if (uploaded) {
  console.log('File uploaded successfully');
} else {
  console.log('Failed to upload file');
}
Copy

Search is not supported by Google Cloud Storage. GCS is an object storage service without built-in search capabilities.

To search GCS objects, consider:

• Using BigQuery to query GCS data
• Maintaining a separate search index (Elasticsearch, etc.)
• Using object metadata for filtering with ListObjects
• Using Cloud Data Loss Prevention API for content discovery

Throws

UnsupportedOperationError always