Member Junction
    Preparing search index...

    Class GoogleFileStorage

    Google Cloud Storage implementation of the FileStorageBase interface.

    This class provides methods for interacting with Google Cloud Storage as a file storage provider. It implements all the abstract methods defined in FileStorageBase and handles Google-specific authentication, authorization, and file operations.

    It requires the following environment variables to be set:

    • STORAGE_GOOGLE_KEY_JSON: A JSON object containing Google Cloud service account credentials
    • STORAGE_GOOGLE_BUCKET_NAME: The GCS bucket name
    // Create an instance of GoogleFileStorage
    const gcsStorage = new GoogleFileStorage();

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

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

    // List files in a directory
    const files = await gcsStorage.ListObjects('documents/');

    Hierarchy (View Summary)

    Index

    Constructors

    constructor

    Properties

    _accountId _accountName providerName

    Accessors

    AccountId AccountName IsConfigured SupportsStreaming

    Methods

    CopyObject CreateDirectory CreatePreAuthDownloadUrl CreatePreAuthUploadUrl DeleteDirectory DeleteObject DirectoryExists GetObject GetObjectMetadata GetObjectStream initialize ListObjects MoveObject ObjectExists PutObject SearchFiles throwUnsupportedOperationError

    Constructors

    Properties

    Protected_accountId

    _accountId: string

    The ID of the FileStorageAccount this driver instance is operating for. Set during initialization via the config parameter.

    Protected_accountName

    _accountName: string

    The name of the FileStorageAccount (for logging/display purposes).

    providerName: "Google Cloud Storage" = 'Google Cloud Storage'

    The name of this storage provider, used in error messages

    Accessors

    • get AccountId(): string

      Gets the account ID this driver instance is operating for. Returns undefined if the driver was not initialized with an account.

      Returns string

    • get AccountName(): string

      Gets the account name this driver instance is operating for. Returns undefined if the driver was not initialized with an account.

      Returns string

    • get IsConfigured(): boolean

      Checks if Google Cloud Storage provider is properly configured. Returns true if service account credentials and bucket name are present. Logs detailed error messages if configuration is incomplete.

      Returns boolean

    Methods

    • 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.

      Parameters

      • sourceObjectName: string

        The name of the object to copy

      • destinationObjectName: string

        The name to assign to the copied object

      Returns Promise<boolean>

      A Promise resolving to a boolean indicating success

      // 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');
      }

    • 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.

      Parameters

      • directoryPath: string

        The path of the directory to create

      Returns Promise<boolean>

      A Promise resolving to a boolean indicating success

      // 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');
      }

    • 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.

      Parameters

      • objectName: string

        The name of the object to download (including any path/directory)

      Returns Promise<string>

      A Promise resolving to the download URL

      // 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);

    • 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.

      Parameters

      • objectName: string

        The name of the object to upload (including any path/directory)

      Returns Promise<CreatePreAuthUploadUrlPayload>

      A Promise resolving to an object with the upload URL

      // 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);

    • 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.

      Parameters

      • directoryPath: string

        The path of the directory to delete

      • recursive: boolean = false

        If true, deletes all contents recursively (default: false)

      Returns Promise<boolean>

      A Promise resolving to a boolean indicating success

      // 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);

    • 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.

      Parameters

      • objectName: string

        The name of the object to delete (including any path/directory)

      Returns Promise<boolean>

      A Promise resolving to a boolean indicating success

      // 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');
      }

    • 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

      Parameters

      • directoryPath: string

        The path of the directory to check

      Returns Promise<boolean>

      A Promise resolving to a boolean indicating if the directory exists

      // 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);

    • 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.

      Parameters

      • params: GetObjectParams

        Object identifier (objectId and fullPath are equivalent for GCS)

      Returns Promise<Buffer>

      A Promise resolving to a Buffer containing the object's data

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

      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);
      }

    • 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.

      Parameters

      Returns Promise<StorageObjectMetadata>

      A Promise resolving to a StorageObjectMetadata object

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

      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');
      }

    • Initialize Google Cloud Storage provider.

      Always call this method after creating an instance.

      Parameters

      • Optionalconfig: StorageProviderConfig

        Optional. Omit to use env vars, provide to override with database creds.

      Returns Promise<void>

      Simple Deployment (Environment Variables)
      const storage = new GoogleFileStorage(); // Constructor loads env vars
      await storage.initialize(); // No config - uses env vars
      await storage.ListObjects('/');

      Multi-Tenant (Database Credentials)
      const storage = new GoogleFileStorage();
      await storage.initialize({
        accountId: '12345',
        accountName: 'GCS Account',
        keyJSON: '{"type":"service_account",...}',
        projectID: 'my-project',
        defaultBucket: 'my-bucket'
      });

    • 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.

      Parameters

      • prefix: string

        The path prefix to list objects from (e.g., 'documents/')

      • delimiter: string = '/'

        The character used to simulate directory structure, defaults to '/'

      Returns Promise<StorageListResult>

      A Promise resolving to a StorageListResult containing objects and prefixes

      // 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}`);
      }

    • 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.

      Parameters

      • oldObjectName: string

        The current name/path of the object

      • newObjectName: string

        The new name/path for the object

      Returns Promise<boolean>

      A Promise resolving to a boolean indicating success

      // 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');
      }

    • 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.

      Parameters

      • objectName: string

        The name of the object to check

      Returns Promise<boolean>

      A Promise resolving to a boolean indicating if the object exists

      // 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');
      }

    • 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.

      Parameters

      • objectName: string

        The name to assign to the uploaded object

      • data: Buffer

        The Buffer containing the data to upload

      • OptionalcontentType: string

        Optional MIME type for the object (inferred from name if not provided)

      • Optionalmetadata: Record<string, string>

        Optional key-value pairs of custom metadata to associate with the object

      Returns Promise<boolean>

      A Promise resolving to a boolean indicating success

      // 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');
      }

    • Helper method to throw an UnsupportedOperationError with appropriate context. This method simplifies implementation of methods not supported by specific providers.

      Parameters

      • methodName: string

        The name of the method that is not supported

      Returns never

      UnsupportedOperationError with information about the unsupported method and provider

    Settings

    Member Visibility

    On This Page

    Constructors
    Properties
    Accessors
    Methods