@memberjunction/storage 2.38.0 → 2.40.0

package/dist/generic/FileStorageBase.d.ts

@@ -1,8 +1,31 @@
 /// <reference types="node" />
+/**
+ * Represents the payload returned by the CreatePreAuthUploadUrl method.
+ * This type contains the necessary information for uploading a file to a storage provider.
+ *
+ * @property UploadUrl - The pre-authenticated URL to which the file should be uploaded
+ * @property ProviderKey - Optional. Some storage providers assign their own unique key to the object
+ *                         that should be used for future operations instead of the original object name
+ */
 export type CreatePreAuthUploadUrlPayload = {
     UploadUrl: string;
     ProviderKey?: string | undefined;
 };
+/**
+ * Represents metadata information about a stored object or file.
+ * This comprehensive type includes common file metadata properties available across different storage providers.
+ *
+ * @property name - The name of the object (typically the filename without path)
+ * @property path - The directory path where the object is stored, without the object name
+ * @property fullPath - The complete path to the object including both path and name
+ * @property size - The size of the object in bytes
+ * @property contentType - The MIME type of the object
+ * @property lastModified - The date when the object was last modified
+ * @property isDirectory - Boolean flag indicating whether the object is a directory/folder
+ * @property etag - Optional. Entity tag used for cache validation and conditional operations
+ * @property cacheControl - Optional. Cache control directives for the object
+ * @property customMetadata - Optional. Additional custom metadata as key-value pairs
+ */
 export type StorageObjectMetadata = {
     name: string;
     path: string;
@@ -15,48 +38,84 @@ export type StorageObjectMetadata = {
     cacheControl?: string;
     customMetadata?: Record<string, string>;
 };
+/**
+ * Represents the result of a ListObjects operation.
+ * Contains both the objects (files) and prefixes (directories) found in the storage provider.
+ *
+ * @property objects - Array of StorageObjectMetadata for all objects/files found in the specified path
+ * @property prefixes - Array of directory path strings found in the specified path
+ */
 export type StorageListResult = {
     objects: StorageObjectMetadata[];
     prefixes: string[];
 };
 /**
- * Error thrown when a method is not supported by a storage provider
+ * Error thrown when a storage provider does not support a particular operation.
+ * This custom error provides clear information about which operation was attempted
+ * and which provider doesn't support it.
  */
 export declare class UnsupportedOperationError extends Error {
+    /**
+     * Creates a new UnsupportedOperationError instance.
+     *
+     * @param methodName - The name of the method that is not supported
+     * @param providerName - The name of the storage provider that doesn't support the method
+     */
     constructor(methodName: string, providerName: string);
 }
 /**
- * Represents an abstract base class for file storage. Provides methods for creating pre-authorized upload and download URLs, as well as deleting objects. This
- * interface is implemented in specific driver classes for each storage provider.
+ * Represents an abstract base class for file storage operations.
+ *
+ * This class defines a common interface for interacting with various cloud storage providers,
+ * allowing for consistent file operations regardless of the underlying storage system.
+ * Each storage provider implementation extends this base class and provides
+ * concrete implementations for all abstract methods.
+ *
+ * The class provides methods for:
+ * - Generating pre-authenticated upload and download URLs
+ * - Managing files (creating, copying, moving, deleting)
+ * - Managing directories (creating, deleting, listing contents)
+ * - Retrieving file metadata and content
+ * - Checking for file and directory existence
+ *
+ * Implementation notes:
+ * - All methods are designed to be provider-agnostic
+ * - Error handling should be implemented in derived classes to provide consistent behavior
+ * - Methods return Promises to support asynchronous operations across various providers
+ * - When a storage provider doesn't support a particular operation, implementations should throw UnsupportedOperationError
  */
 export declare abstract class FileStorageBase {
     /**
-     * The name of this storage provider, used in error messages
+     * The name of this storage provider, used in error messages and logging.
+     * Each implementation must define this property with a descriptive name.
      */
     protected abstract readonly providerName: string;
     /**
-     * Helper method to throw an UnsupportedOperationError
-     * @param methodName The name of the method that is not supported
+     * Helper method to throw an UnsupportedOperationError with appropriate context.
+     * This method simplifies implementation of methods not supported by specific providers.
+     *
+     * @param methodName - The name of the method that is not supported
+     * @throws UnsupportedOperationError with information about the unsupported method and provider
      */
     protected throwUnsupportedOperationError(methodName: string): never;
     /**
-     * This method is designed to generate a pre-authenticated URL for uploading files to a storage provider. It 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:
+     * Generates a pre-authenticated URL for uploading files to a storage provider.
      *
-     * 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.
+     * 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:
      *
-     * 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.
+     * 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.
      *
-     * @usage
-     *
-     * Suppose you have a file named "photo.jpg" that you want to upload to your storage provider. You would call this method with the object name "photo.jpg".
-     * After the Promise resolves, you will receive the upload URL and, if applicable, the provider's object key. You can then use this URL to upload your file
-     * directly to the storage provider.
+     * 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.
      *
+     * @example
      * ```typescript
      * const uploadPayload = await CreatePreAuthUploadUrl("photo.jpg");
      * console.log(uploadPayload.UploadUrl); // Use this URL to upload your file
@@ -66,149 +125,208 @@ export declare abstract class FileStorageBase {
      * }
      * ```
      *
-     * Note: This method is abstract and must be implemented by a subclass that specifies the logic for interacting with a specific storage provider.
+     * Note: This method is abstract and must be implemented by a subclass that specifies the logic
+     * for interacting with a specific storage provider.
      *
-     * @param objectName - The name of the object or file to be uploaded. This name is used by the storage provider and may also be included in the
-     *                     pre-authenticated URL.
-     * @returns A Promise that resolves to a payload containing the upload URL and, optionally, the provider's object key. This payload allows you to proceed with
-     *          uploading your file to the storage provider.
+     * @param objectName - The name of the object or file to be uploaded. This name is used by the
+     *                     storage provider and may also be included in the pre-authenticated URL.
+     * @returns A Promise that resolves to a payload containing the upload URL and, optionally, the
+     *          provider's object key. This payload allows you to proceed with uploading your file
+     *          to the storage provider.
      */
     abstract CreatePreAuthUploadUrl(objectName: string): Promise<CreatePreAuthUploadUrlPayload>;
     /**
-     * This abstract method is designed to generate a pre-authenticated URL that allows for the downloading of files or objects from a storage provider. Being
-     * abstract, it requires implementation in a subclass tailored to the specifics of the storage provider you're using. This method abstracts the process of
-     * generating download URLs across different storage providers, offering a unified interface for obtaining these URLs.
-     *
-     * When you call this method with the name of the file or object you wish to download, it initiates a process to create a URL. This URL is not just any link;
-     * it is pre-authenticated. This means it includes any necessary authentication tokens or signatures directly in the URL, allowing for secure access without
-     * requiring additional authentication steps at the time of download. The format of the URL and the authentication method depend on the storage provider.
-     *
-     * @usage
+     * Generates a pre-authenticated URL for downloading files from a storage provider.
      *
-     * Suppose you have a file named "report.pdf" stored in your cloud storage, and you want to generate a URL to download this file. You would call this method
-     * with the object name "report.pdf". After the Promise resolves, you will receive a URL that is ready to use for downloading the file.
+     * 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.
      *
+     * @example
      * ```typescript
      * const downloadUrl = await CreatePreAuthDownloadUrl("report.pdf");
      * console.log(downloadUrl); // Use this URL to download your file directly
      * ```
      *
-     * If a `ProviderKey` was previously returned by `CreatePreAuthUploadUrl`, use that as the `objectName` instead of the object's natural name.
+     * If a `ProviderKey` was previously returned by `CreatePreAuthUploadUrl`, use that as the
+     * `objectName` instead of the object's natural name:
      *
      * ```typescript
      * const downloadUrl = await CreatePreAuthDownloadUrl(file.ProviderKey);
      * console.log(downloadUrl); // Use this URL to download your file directly
      * ```
      *
-     * This method simplifies the process of securely sharing or accessing files stored in cloud storage by providing a direct, pre-authenticated link to the
-     * file. It's particularly useful in applications where files need to be accessed or shared without navigating through the storage provider's standard
+     * This method simplifies the process of securely sharing or accessing files stored in cloud storage
+     * by providing a direct, pre-authenticated link to the file. It's particularly useful in applications
+     * where files need to be accessed or shared without navigating through the storage provider's standard
      * authentication flow each time.
      *
-     * Note: Since this method is abstract, you must implement it in a subclass that defines the specific interactions with your chosen storage provider.
-     *
-     * @param objectName - The name of the object or file for which you want to generate a download URL. This is the name as it is known to the storage provider,
-     *                     and it will be used to locate the file and generate the URL.
-     * @returns A Promise that resolves to a string, which is the pre-authenticated download URL for the specified object or file. This URL can be used
-     *          immediately for downloading the file without further authentication.
+     * @param objectName - The name of the object or file for which you want to generate a download URL.
+     *                     This is the name as it is known to the storage provider, and it will be used
+     *                     to locate the file and generate the URL.
+     * @returns A Promise that resolves to a string, which is the pre-authenticated download URL for the
+     *          specified object or file. This URL can be used immediately for downloading the file
+     *          without further authentication.
      */
     abstract CreatePreAuthDownloadUrl(objectName: string): Promise<string>;
     /**
-     * This abstract method is designed to move an object or file from one location to another within a storage provider's system. Being abstract, it requires concrete implementation in subclasses that are tailored to interact with specific storage providers. The method aims to provide a unified interface for moving objects across different storage providers, simplifying the process regardless of the underlying provider's specifics.
+     * Moves an object or file from one location to another within a storage provider's system.
      *
-     * When invoking this method, you need to specify the name of the object you wish to move (`oldObjectName`) and the new name or location where you want to move the object (`newObjectName`). These names should match exactly as they are known to the storage provider, ensuring the correct object is targeted for the move operation.
+     * 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.
      *
-     * The method returns a Promise that, when resolved, indicates the success or failure of the move operation. A resolved value of `true` means the object was successfully moved, while `false` indicates a failure to move the object. It's important to handle both outcomes to ensure your application can respond appropriately to the move operation's result.
+     * 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.
      *
-     * @param oldObjectName - The name of the object or file to be moved. This is the identifier used by the storage provider to locate the object for moving.
-     * @param newObjectName - The new name or location where you want to move the object. This name should match exactly as it is known to the storage provider.
-     * @returns A Promise that resolves to a boolean value. `true` indicates that the object was successfully moved, while `false` indicates a failure in the move process.
+     * @example
+     * ```typescript
+     * const moved = await storage.MoveObject('documents/draft.docx', 'documents/final/report.docx');
+     * if (moved) {
+     *   console.log('File successfully moved');
+     * } else {
+     *   console.log('Failed to move file');
+     * }
+     * ```
+     *
+     * @param oldObjectName - The current name/path of the object to be moved. This is the identifier
+     *                      used by the storage provider to locate the object for moving.
+     * @param newObjectName - The new name/path where you want to move the object. This should match
+     *                      exactly as it is expected to be known to the storage provider after moving.
+     * @returns A Promise that resolves to a boolean value. `true` indicates that the object was
+     *          successfully moved, while `false` indicates a failure in the move process.
      */
     abstract MoveObject(oldObjectName: string, newObjectName: string): Promise<boolean>;
     /**
-     * This abstract method is designed for deleting an object or file from a storage provider's system. Being abstract, it requires concrete implementation in
-     * subclasses that are tailored to interact with specific storage providers. The method aims to provide a unified interface for object deletion across
-     * different storage providers, simplifying the deletion process regardless of the underlying provider's specifics.
-     *
-     * When invoking this method, you need to specify the name of the object you wish to delete. This name should match exactly as it is known to the storage
-     * provider, ensuring the correct object is targeted for deletion.
+     * Deletes an object or file from a storage provider's system.
      *
-     * The method returns a Promise that, when resolved, indicates the success or failure of the deletion operation. A resolved value of `true` means the object
-     * was successfully deleted, while `false` indicates a failure to delete the object. It's important to handle both outcomes to ensure your application can
-     * respond appropriately to the deletion operation's result.
-     *
-     * @usage
-     *
-     * Suppose you have a file named "old_report.pdf" that is no longer needed and you want to delete it from your cloud storage. You would call this method with
-     * the object name "old_report.pdf". After the Promise resolves, you can check the result to confirm the deletion.
+     * 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.
      *
+     * @example
      * ```typescript
-     * DeleteObject("old_report.pdf").then((isDeleted) => {
-     *   if (isDeleted) {
-     *     console.log("The file was successfully deleted.");
-     *   } else {
-     *     console.log("Failed to delete the file. It may not exist or there was an error in the deletion process.");
-     *   }
-     * });
+     * const deleted = await storage.DeleteObject('documents/old_report.pdf');
+     * if (deleted) {
+     *   console.log('File successfully deleted');
+     * } else {
+     *   console.log('Failed to delete file - it may not exist or there was an error');
+     * }
      * ```
      *
-     * If a `ProviderKey` was previously returned by `CreatePreAuthUploadUrl`, use that as the `objectName` instead of the object's natural name.
+     * If a `ProviderKey` was previously returned by `CreatePreAuthUploadUrl`, use that as the
+     * `objectName` instead of the object's natural name:
      *
      * ```typescript
-     * DeleteObject(file.ProviderKey).then((isDeleted) => {
-     *   if (isDeleted) {
-     *     console.log("The file was successfully deleted.");
-     *   } else {
-     *     console.log("Failed to delete the file. It may not exist or there was an error in the deletion process.");
-     *   }
-     * });
+     * const deleted = await storage.DeleteObject(file.ProviderKey);
+     * if (deleted) {
+     *   console.log('File successfully deleted');
+     * } else {
+     *   console.log('Failed to delete file');
+     * }
      * ```
      *
-     * Note: Since this method is abstract, it must be implemented in a subclass that defines the specific logic for interacting with your chosen storage
-     * provider. This implementation should handle the intricacies of the deletion process, including any authentication and authorization required by the storage
-     * provider.
-     *
-     * @param objectName - The name of the object or file to be deleted. This is the identifier used by the storage provider to locate the object for deletion.
-     * @returns A Promise that resolves to a boolean value. `true` indicates that the object was successfully deleted, while `false` indicates a failure in the
-     * deletion process.
+     * @param objectName - The name of the object or file to be deleted. This is the identifier
+     *                   used by the storage provider to locate the object for deletion.
+     * @returns A Promise that resolves to a boolean value. `true` indicates that the object was
+     *          successfully deleted, while `false` indicates a failure in the deletion process.
      */
     abstract DeleteObject(objectName: string): Promise<boolean>;
     /**
      * Lists objects in a storage provider's system with the given prefix path.
      *
-     * This method returns a list of objects and prefixes (directories) under the specified path.
-     * The method supports a hierarchical directory-like structure through the use of prefixes
-     * that can represent "folders" within the storage.
+     * 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.
      *
-     * @param prefix - The path prefix to list objects from. Use "/" for the root, or paths like "documents/"
-     *                 for specific directories.
-     * @param delimiter - The character used to group keys. Typically "/" is used to simulate directory structure.
-     *                    Defaults to "/".
-     * @returns A Promise that resolves to a StorageListResult containing both objects and prefixes (directories).
+     * @example
+     * ```typescript
+     * // List all objects in the "documents" directory
+     * const result = await storage.ListObjects('documents/');
+     *
+     * // Access the files
+     * for (const file of result.objects) {
+     *   console.log(`File: ${file.name}, Size: ${file.size}, Type: ${file.contentType}`);
+     * }
+     *
+     * // Access the subdirectories
+     * for (const dir of result.prefixes) {
+     *   console.log(`Directory: ${dir}`);
+     * }
+     * ```
+     *
+     * @param prefix - The path prefix to list objects from. Use "/" for the root, or paths like
+     *                 "documents/" for specific directories.
+     * @param delimiter - The character used to group keys. Typically "/" is used to simulate
+     *                    directory structure. Defaults to "/".
+     * @returns A Promise that resolves to a StorageListResult containing both objects and
+     *          prefixes (directories).
      */
     abstract ListObjects(prefix: string, delimiter?: string): Promise<StorageListResult>;
     /**
      * Creates a directory in the storage system.
      *
-     * For storage systems that don't natively support directories, 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.
+     * 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.
      *
-     * @param directoryPath - The path of the directory to create. Should end with a delimiter (typically "/").
-     * @returns A Promise that resolves to a boolean indicating success.
+     * @example
+     * ```typescript
+     * // Create a "reports" directory inside "documents"
+     * const created = await storage.CreateDirectory('documents/reports/');
+     * if (created) {
+     *   console.log('Directory created successfully');
+     * } else {
+     *   console.log('Failed to create directory');
+     * }
+     * ```
+     *
+     * @param directoryPath - The path of the directory to create. Should typically end with a
+     *                       delimiter (typically "/").
+     * @returns A Promise that resolves to a boolean indicating success of the directory creation.
      */
     abstract CreateDirectory(directoryPath: string): Promise<boolean>;
     /**
      * 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.
+     *
+     * @example
+     * ```typescript
+     * // Delete an empty directory
+     * const deleted = await storage.DeleteDirectory('documents/temp/');
+     *
+     * // Delete a directory and all its contents
+     * const deletedRecursively = await storage.DeleteDirectory('documents/old_project/', true);
+     * ```
+     *
      * @param directoryPath - The path of the directory to delete.
-     * @param recursive - If true, deletes all contents recursively. If false and the directory is not empty,
-     *                    the operation will fail. Defaults to false.
-     * @returns A Promise that resolves to a boolean indicating success.
+     * @param recursive - If true, deletes all contents recursively. If false and the directory
+     *                   is not empty, the operation will fail. Defaults to false.
+     * @returns A Promise that resolves to a boolean indicating success of the deletion operation.
      */
     abstract DeleteDirectory(directoryPath: string, recursive?: boolean): Promise<boolean>;
     /**
      * 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.
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   const metadata = await storage.GetObjectMetadata('documents/large_file.zip');
+     *   console.log(`File size: ${metadata.size} bytes`);
+     *   console.log(`Last modified: ${metadata.lastModified}`);
+     *   console.log(`Content type: ${metadata.contentType}`);
+     * } catch (error) {
+     *   console.error('File not found or error retrieving metadata', error);
+     * }
+     * ```
+     *
      * @param objectName - The name of the object to retrieve metadata for.
      * @returns A Promise that resolves to a StorageObjectMetadata object containing the metadata.
      *          If the object does not exist, the promise will be rejected.
@@ -217,6 +335,21 @@ export declare abstract class FileStorageBase {
     /**
      * 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.
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   const fileContent = await storage.GetObject('documents/config.json');
+     *   // Parse the JSON content
+     *   const config = JSON.parse(fileContent.toString('utf8'));
+     *   console.log('Loaded configuration:', config);
+     * } catch (error) {
+     *   console.error('Error downloading file', error);
+     * }
+     * ```
+     *
      * @param objectName - The name of the object to download.
      * @returns A Promise that resolves to a Buffer containing the object's data.
      *          If the object does not exist, the promise will be rejected.
@@ -225,29 +358,80 @@ export declare abstract class FileStorageBase {
     /**
      * Uploads object data to the storage provider.
      *
-     * This is a direct upload method that doesn't use a pre-authorized URL.
+     * 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.
+     *
+     * @example
+     * ```typescript
+     * // Upload a text file
+     * const content = Buffer.from('Hello, World!', 'utf8');
+     * const uploaded = await storage.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');
+     * }
+     * ```
      *
      * @param objectName - The name to assign to the uploaded object.
      * @param data - The Buffer containing the data to upload.
-     * @param contentType - Optional MIME type of the content.
+     * @param contentType - Optional MIME type of the content. If not provided,
+     *                     it may be inferred from the object name or set to a default.
      * @param metadata - Optional custom metadata to associate with the object.
-     * @returns A Promise that resolves to a boolean indicating success.
+     * @returns A Promise that resolves to a boolean indicating success of the upload.
      */
     abstract PutObject(objectName: string, data: Buffer, contentType?: string, metadata?: Record<string, string>): Promise<boolean>;
     /**
      * Copies an object within the storage system.
      *
      * Unlike MoveObject which removes the source object, this creates a copy while
-     * leaving the original intact.
+     * leaving the original intact. This is useful for creating backups or versions
+     * of files.
+     *
+     * @example
+     * ```typescript
+     * // Create a backup copy of a file
+     * const copied = await storage.CopyObject(
+     *   'documents/important.docx',
+     *   'documents/backups/important_backup.docx'
+     * );
+     *
+     * if (copied) {
+     *   console.log('File copied successfully');
+     * } else {
+     *   console.log('Failed to copy file');
+     * }
+     * ```
      *
      * @param sourceObjectName - The name of the object to copy.
      * @param destinationObjectName - The name to assign to the copied object.
-     * @returns A Promise that resolves to a boolean indicating success.
+     * @returns A Promise that resolves to a boolean indicating success of the copy operation.
      */
     abstract CopyObject(sourceObjectName: string, destinationObjectName: string): Promise<boolean>;
     /**
      * 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.
+     *
+     * @example
+     * ```typescript
+     * const exists = await storage.ObjectExists('documents/may_not_exist.pdf');
+     * if (exists) {
+     *   console.log('The file exists');
+     * } else {
+     *   console.log('The file does not exist');
+     * }
+     * ```
+     *
      * @param objectName - The name of the object to check.
      * @returns A Promise that resolves to a boolean indicating if the object exists.
      */
@@ -255,14 +439,48 @@ export declare abstract class FileStorageBase {
     /**
      * 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.
+     *
+     * @example
+     * ```typescript
+     * const exists = await storage.DirectoryExists('documents/reports/');
+     * if (exists) {
+     *   console.log('The directory exists');
+     * } else {
+     *   console.log('The directory does not exist');
+     * }
+     * ```
+     *
      * @param directoryPath - The path of the directory to check.
      * @returns A Promise that resolves to a boolean indicating if the directory exists.
      */
     abstract DirectoryExists(directoryPath: string): Promise<boolean>;
     /**
      * Optional initialization method for storage providers that require async setup.
+     *
      * This method can be overridden by subclasses that need to perform async initialization
-     * after construction, such as setting up access tokens or establishing connections.
+     * after construction, such as setting up access tokens, establishing connections,
+     * or verifying permissions.
+     *
+     * The default implementation does nothing and resolves immediately. Storage provider
+     * implementations should override this method if they need to perform async setup.
+     *
+     * @example
+     * ```typescript
+     * // In a specific provider implementation:
+     * public async initialize(): Promise<void> {
+     *   // Set up OAuth tokens or other async initialization
+     *   await this.refreshAccessToken();
+     *   await this.verifyBucketAccess();
+     * }
+     *
+     * // Usage:
+     * const storage = new MyStorageProvider();
+     * await storage.initialize();
+     * // Now the provider is ready to use
+     * ```
      *
      * @returns A Promise that resolves when initialization is complete.
      */

package/dist/generic/FileStorageBase.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"FileStorageBase.d.ts","sourceRoot":"","sources":["../../src/generic/FileStorageBase.ts"],"names":[],"mappings":";AAAA,MAAM,MAAM,6BAA6B,GAAG;IAC1C,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAClC,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,IAAI,CAAC;IACnB,WAAW,EAAE,OAAO,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACzC,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,OAAO,EAAE,qBAAqB,EAAE,CAAC;IACjC,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB,CAAC;AAEF;;GAEG;AACH,qBAAa,yBAA0B,SAAQ,KAAK;gBACtC,UAAU,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM;CAIrD;AAED;;;GAGG;AACH,8BAAsB,eAAe;IACnC;;OAEG;IACH,SAAS,CAAC,QAAQ,CAAC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAEjD;;;OAGG;IACH,SAAS,CAAC,8BAA8B,CAAC,UAAU,EAAE,MAAM,GAAG,KAAK;IAGnE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;aACa,sBAAsB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,6BAA6B,CAAC;IAElG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAoCG;aACa,wBAAwB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAE7E;;;;;;;;;;OAUG;aACa,UAAU,CAAC,aAAa,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAE1F;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8CG;aACa,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAElE;;;;;;;;;;;;OAYG;aACa,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAE3F;;;;;;;;;OASG;aACa,eAAe,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAExE;;;;;;;OAOG;aACa,eAAe,CAAC,aAAa,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IAE7F;;;;;;OAMG;aACa,iBAAiB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAErF;;;;;;OAMG;aACa,SAAS,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAE9D;;;;;;;;;;OAUG;aACa,SAAS,CACvB,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,MAAM,EACZ,WAAW,CAAC,EAAE,MAAM,EACpB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAChC,OAAO,CAAC,OAAO,CAAC;IAEnB;;;;;;;;;OASG;aACa,UAAU,CAAC,gBAAgB,EAAE,MAAM,EAAE,qBAAqB,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAErG;;;;;OAKG;aACa,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAElE;;;;;OAKG;aACa,eAAe,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAExE;;;;;;OAMG;IACU,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;CAGzC"}
+{"version":3,"file":"FileStorageBase.d.ts","sourceRoot":"","sources":["../../src/generic/FileStorageBase.ts"],"names":[],"mappings":"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"}