Class FileStorageBaseAbstract

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

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

Checks whether this storage provider is properly configured and ready to use.

This abstract getter must be implemented by each provider to verify that all required configuration parameters (API keys, credentials, endpoints, etc.) are present and valid. This allows the system to determine which providers are actually available before attempting to use them.

Implementation Guidelines:

• Check for presence of all required configuration values
• Do NOT make network calls or expensive operations
• Return true only if the provider can be used immediately
• Return false if any required configuration is missing or invalid

Examples by Provider:

• Google Drive: Check for clientID, clientSecret, and refreshToken
• AWS S3: Check for accessKeyId, secretAccessKey, and bucketName
• SharePoint: Check for tenantId, clientId, clientSecret, siteUrl
• Azure Blob: Check for connectionString or account credentials

Indicates whether this provider supports streaming/ranged downloads via GetObjectStream.

The base default is false. Streaming-capable drivers override this getter to return true. Callers MUST check this getter before calling GetObjectStream, or be ready to catch StreamingNotSupportedError.

Copies an object within the storage system.

Unlike MoveObject which removes the source object, this creates a copy while leaving the original intact. This is useful for creating backups or versions of files.

Creates a directory in the storage system.

For storage systems that don't natively support directories (like AWS S3 or Google Cloud Storage), this may create a zero-byte object with a trailing delimiter to simulate a directory. For systems with native directory support, this will create an actual directory.

Generates a pre-authenticated URL for downloading files from a storage provider.

This method abstracts the process of generating download URLs across different storage providers, offering a unified interface for obtaining these URLs. When called with the name of the file or object to download, it creates a URL that includes necessary authentication tokens directly in the URL, allowing for secure access without requiring additional authentication at download time.

Generates a pre-authenticated URL for uploading files to a storage provider.

This method abstracts over different storage providers, allowing for a unified interface to obtain upload URLs, regardless of the underlying provider's specifics. The method takes the name of the file (or object) you wish to upload as input and returns a Promise. This Promise, when resolved, provides a payload containing two key pieces of information:

1. UploadUrl: The URL to which the file should be uploaded. This URL is pre-authenticated, meaning it includes any necessary authentication tokens or signatures. The URL's format and the authentication method depend on the storage provider being used.

2. ProviderKey (optional): Some storage providers assign their own unique key or name to the uploaded object instead of using the name provided by the user. If the provider you are using does this, the ProviderKey will be included in the payload. This key can be useful for future reference to the object within the storage provider's system.

Deletes a directory and optionally all of its contents recursively.

This method can be used to remove empty directories or, with the recursive flag set to true, to delete entire directory trees including all contained files and subdirectories.

Deletes an object or file from a storage provider's system.

This method provides a unified interface for object deletion across different storage providers. It takes the name of the object to delete and handles the provider-specific operations to remove it from storage.

Checks if a directory exists in the storage system.

For storage systems that don't natively support directories, this may check for the existence of a directory placeholder object or for any objects with the given prefix.

Downloads an object's content as a Buffer.

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

Retrieves metadata for a specific object without downloading its contents.

This method allows for checking properties of an object such as its size, content type, and last modified date without transferring the actual data, which can be efficient for large files.

Streams an object's content (optionally a byte range) without buffering the whole object in memory.

Use this instead of GetObject when serving large media (audio/video) over HTTP — pipe the returned ObjectStreamResult.Stream directly to the HTTP response and propagate ContentType/ContentLength/ContentRange to the response headers. GetObject returns the full object as a Buffer and is appropriate only for small payloads you need fully in memory.

Range semantics: params.Range is an inclusive byte range ({ Start, End }), matching the HTTP Range/Content-Range model. Omit End to stream from Start to EOF. When a range is honored, the result's ContentRange carries the actual Start/End returned and the object's Total size — enough to emit Content-Range: bytes Start-End/Total and a 206 Partial Content status. When no Range is supplied, the whole object is streamed and ContentRange is omitted.

Capability gating: The base class provides a default implementation that throws StreamingNotSupportedError. This means drivers that don't support streaming inherit the throw automatically (no boilerplate stubs) and SupportsStreaming stays false. Callers MUST therefore either check SupportsStreaming first, or be prepared to catch StreamingNotSupportedError and fall back to GetObject.

Initialize storage provider with optional configuration.

Standard Usage Pattern

ALWAYS call this method after creating a provider instance.

Simple Deployment (Environment Variables)

Constructor loads credentials from environment variables, then call initialize() with no config to complete setup:

// Set environment variables:
// STORAGE_AWS_ACCESS_KEY_ID=...
// STORAGE_AWS_SECRET_ACCESS_KEY=...
// STORAGE_AWS_BUCKET_NAME=...
// STORAGE_AWS_REGION=...

const storage = new AWSFileStorage(); // Constructor loads env vars
await storage.initialize(); // No config - uses env vars
await storage.ListObjects('/'); // Ready to use
Copy

Multi-Tenant Enterprise (Database)

Constructor loads defaults, then call initialize() with configuration to override with database credentials and track account:

// Preferred: Use infrastructure utility
const storage = await initializeDriverWithAccountCredentials({
  accountEntity,
  providerEntity,
  contextUser
});

// Alternative: Manual initialization
const storage = new AWSFileStorage();
await storage.initialize({
  accountId: account.id,
  accountName: account.name,
  accessKeyID: creds.accessKeyID,
  secretAccessKey: creds.secretAccessKey,
  region: creds.region,
  defaultBucket: creds.bucket
});
Copy

How It Works

• No config: Uses credentials already loaded by constructor from environment variables
• With config: Overrides constructor credentials with provided values
• accountId: Optional - provide for multi-tenant tracking

Implementation Notes for Subclasses

Subclass implementations should:

1. Call super.initialize(config) first to set accountId and accountName
2. Check if config is provided before attempting to override credentials
3. Only override values that are present in config
4. Reinitialize client/connection if credentials changed

Lists objects in a storage provider's system with the given prefix path.

This method returns a list of objects (files) and prefixes (directories) under the specified path. It supports a hierarchical directory-like structure through the use of prefixes that can represent "folders" within the storage, even for providers that don't natively support directories.

Moves an object or file from one location to another within a storage provider's system.

This method provides a unified interface for moving objects across different storage providers. It takes the original object name and the new desired name/location, and handles the appropriate operations to move the object while preserving its content.

Some implementations may perform this as a copy followed by a delete operation, while others might use native move capabilities of the underlying storage system.

Checks if an object exists in the storage system.

This method provides a way to verify the existence of an object without transferring its data or metadata, which can be more efficient when you only need to know if something exists.

Uploads object data to the storage provider.

This is a direct upload method that doesn't use a pre-authorized URL. Instead, it takes the data as a Buffer and handles the upload directly, making it suitable for server-side operations where you already have the data in memory.

Searches for files across the storage system using the provider's native search capabilities.

This method leverages each provider's built-in search APIs to find files matching the specified query. The search can include filenames, file content, and metadata depending on the provider's capabilities and the options specified.

Provider Support:

• Google Drive: Full support via Drive API search with content indexing
• SharePoint: Full support via Microsoft Graph Search API
• Dropbox: Full support via search_v2 API with content search
• Box: Full support via Box Search API
• AWS S3: Not supported - throws UnsupportedOperationError
• Azure Blob: Not supported - throws UnsupportedOperationError
• Google Cloud Storage: Not supported - throws UnsupportedOperationError

Query Syntax: The query parameter accepts natural language search terms. Advanced query syntax (like boolean operators, exact phrases, wildcards) varies by provider:

• Google Drive supports: "exact phrase", OR, -, wildcards
• SharePoint supports: KQL (Keyword Query Language)
• Dropbox supports: exact phrases in quotes
• Box supports: boolean AND/OR/NOT operators

Implementations should document their specific query syntax support.