docs: use cases doc

Author: g-saracca

src/files/domain/useCases/ReplaceFile.ts

@@ -0,0 +1,28 @@
+import { UseCase } from '../../../core/domain/useCases/UseCase'
+import { UploadedFileDTO } from '../dtos/UploadedFileDTO'
+import { IFilesRepository } from '../repositories/IFilesRepository'
+
+export class ReplaceFile implements UseCase<void> {
+  private filesRepository: IFilesRepository
+
+  constructor(filesRepository: IFilesRepository) {
+    this.filesRepository = filesRepository
+  }
+
+  /**
+   * Replaces an existing file.
+   *
+   * This method completes the flow initiated by the UploadFile use case, which involves replacing an existing file with a new one just uploaded.
+   * (https://guides.dataverse.org/en/latest/developers/s3-direct-upload-api.html#replacing-an-existing-file-in-the-dataset)
+   *
+   * Note: This use case can be used independently of the UploadFile use case, e.g., supporting scenarios in which the files already exist in S3 or have been uploaded via some out-of-band method.
+   *
+   * @param {number} [fileId] - The File identifier.
+   * @param {UploadedFileDTO} [uploadedFileDTO] - File DTO associated with the uploaded file.
+   * @returns {Promise<void>} A promise that resolves when the file has been successfully replaced.
+   * @throws {WriteError} - If there are errors while writing data.
+   */
+  async execute(fileId: number, uploadedFileDTO: UploadedFileDTO): Promise<void> {
+    await this.filesRepository.replaceFile(fileId, uploadedFileDTO)
+  }
+}

src/files/domain/useCases/UploadFile.ts

@@ -12,7 +12,9 @@ export class UploadFile implements UseCase<string> {
    * Uploads a file to remote storage and returns the storage identifier.
    *
    * This use case is based on the Direct Upload API, particularly the first part of the flow, "Requesting Direct Upload of a DataFile".
-   * To fulfill the flow, you will need to call the AddUploadedFileToDataset Use Case to add the uploaded file to the dataset.
+   * To fulfill the flow, you could:
+   *  - Call the AddUploadedFilesToDataset Use Case to add the uploaded file to the dataset.
+   *  - Call the ReplaceFile Use Case to replace an existing file with the uploaded one.
    * (https://guides.dataverse.org/en/latest/developers/s3-direct-upload-api.html#requesting-direct-upload-of-a-datafile)
    *
    * @param {number | string} [datasetId] - The dataset identifier, which can be a string (for persistent identifiers) or a number (for numeric identifiers).