Merge pull request #173 from IQSS/163-improve-file-upload-use-case

Enhanced File Uploading

Author: ekraffmiller

docs/useCases.md

@@ -873,7 +873,7 @@ getDatasetFiles
 These use cases are designed to facilitate the uploading of files to a remote S3 storage and subsequently adding them to a dataset. This process involves two main steps / use cases:
 
 1. Uploading a file to remote S3 storage and obtaining a storage identifier.
-2. Adding the uploaded file to the dataset using the obtained storage identifier.
+2. Adding one or more uploaded files to the dataset using the obtained storage identifiers.
 
 This use case flow is entirely based on the Direct Upload API as described in the Dataverse documentation: https://guides.dataverse.org/en/latest/developers/s3-direct-upload-api.html
 
@@ -910,35 +910,41 @@ The `progress` parameter represents a callback function that allows the caller t
 
 The `abortController` is a built-in mechanism in modern web browsers that allows the cancellation of asynchronous operations. It works in conjunction with an associated AbortSignal, which will be passed to the file uploading API calls to monitor whether the operation should be aborted, if the caller decides to cancel the operation midway.
 
-##### Add Uploaded File to the Dataset
+##### Add Uploaded Files to the Dataset
 
-This use case involves adding a file that has been previously uploaded to remote storage to the dataset.
+This use case involves adding files that have been previously uploaded to remote storage to the dataset.
 
 ###### Example call:
 
 ```typescript
-import { addUploadedFileToDataset } from '@iqss/dataverse-client-javascript'
+import { addUploadedFilesToDataset } from '@iqss/dataverse-client-javascript'
+import { UploadedFileDTO } from '@iqss/dataverse-client-javascript'
 
 /* ... */
 
 const datasetId: number | string = 123
-const file: File = new File(['content'], 'example.txt', { type: 'text/plain' })
-const storageId: string = 'some-storage-identifier'
-
-addUploadedFileToDataset.execute(datasetId, file, storageId).then(() => {
-  console.log('File added to the dataset successfully.')
+const uploadedFileDTOs: UploadedFileDTO[] = [
+  {
+    fileName: 'the-file-name',
+    storageId: 'localstack1://mybucket:19121faf7e7-2c40322ff54e',
+    checksumType: 'md5',
+    checksumValue: 'ede3d3b685b4e137ba4cb2521329a75e',
+    mimeType: 'text/plain'
+  }
+]
+
+addUploadedFilesToDataset.execute(datasetId, uploadedFileDTOs).then(() => {
+  console.log('Files added to the dataset successfully.')
 })
 
 /* ... */
 ```
 
-_See [use case](../src/files/domain/useCases/AddUploadedFileToDataset.ts) implementation_.
+_See [use case](../src/files/domain/useCases/AddUploadedFilesToDataset.ts) implementation_.
 
 The `datasetId` parameter can be a string, for persistent identifiers, or a number, for numeric identifiers.
 
-The `file` parameter is a subclass of Blob (Binary Large Object) that represents a file.
-
-The `storageId` parameter represents the storage identifier obtained after a successful call to the UploadFile use case.
+The `uploadedFileDTOs` parameter is an array of [UploadedFileDTO](../src/files/domain/dtos/UploadedFileDTO.ts) and includes properties related to the uploaded files. Some of these properties should be calculated from the uploaded File Blob objects and the resulting storage identifiers from the Upload File use case.
 
 ##### Error handling: