Changed: support adding multiple uploaded files to a dataset with extended metadata

Author: GPortas

docs/useCases.md

@@ -909,41 +909,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 uploadedFileDTO: UploadedFileDTO = {
-  fileName: 'the-file-name',
-  storageId: 'localstack1://mybucket:19121faf7e7-2c40322ff54e',
-  checksumType: 'md5',
-  checksumValue: 'ede3d3b685b4e137ba4cb2521329a75e',
-  mimeType: 'text/plain'
-}
-
-addUploadedFileToDataset.execute(datasetId, uploadedFileDTO).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 `uploadedFileDTO` parameter is an instance of [UploadedFileDTO](../src/files/domain/dtos/UploadedFileDTO.ts) and includes properties related to the uploaded file. These properties should be calculated from the File Blob object previously sent through the upload file use case.
-
-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. These properties should be calculated from the uploaded File Blob objects and the resulting storage identifiers from the Upload File use case.
 
 ##### Error handling:
 

src/files/domain/dtos/UploadedFileDTO.ts

@@ -1,5 +1,9 @@
 export interface UploadedFileDTO {
   fileName: string
+  description?: string
+  directoryLabel?: string
+  categories?: string[]
+  restrict?: boolean
   storageId: string
   checksumValue: string
   checksumType: string

src/files/domain/repositories/IFilesRepository.ts

@@ -55,8 +55,8 @@ export interface IFilesRepository {
 
   getFileUploadDestination(datasetId: number | string, file: File): Promise<FileUploadDestination>
 
-  addUploadedFileToDataset(
+  addUploadedFilesToDataset(
     datasetId: number | string,
-    uploadedFileDTO: UploadedFileDTO
+    uploadedFileDTOs: UploadedFileDTO[]
   ): Promise<undefined>
 }

src/files/domain/useCases/AddUploadedFileToDataset.ts renamed to src/files/domain/useCases/AddUploadedFilesToDataset.ts

@@ -2,27 +2,27 @@ import { UseCase } from '../../../core/domain/useCases/UseCase'
 import { UploadedFileDTO } from '../dtos/UploadedFileDTO'
 import { IFilesRepository } from '../repositories/IFilesRepository'
 
-export class AddUploadedFileToDataset implements UseCase<void> {
+export class AddUploadedFilesToDataset implements UseCase<void> {
   private filesRepository: IFilesRepository
 
   constructor(filesRepository: IFilesRepository) {
     this.filesRepository = filesRepository
   }
 
   /**
-   * Adds a file that has been uploaded to remote storage to the dataset.
+   * Adds files that have been uploaded to remote storage to the dataset.
    *
    * This method completes the flow initiated by the UploadFile use case, which involves adding the uploaded file to the specified dataset.
    * (https://guides.dataverse.org/en/latest/developers/s3-direct-upload-api.html#adding-the-uploaded-file-to-the-dataset)
    *
-   * Note: This use case can be used independently of the UploadFile use case, e.g., supporting scenarios in which the file already exists in S3 or has been uploaded via some out-of-band method.
+   * 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 | string} [datasetId] - The dataset identifier, which can be a string (for persistent identifiers) or a number (for numeric identifiers).
-   * @param {UploadedFileDTO} [uploadedFileDTO] - A file DTO associated with the uploaded file.
+   * @param {UploadedFileDTO[]} [uploadedFileDTOs] - File DTOs associated with the uploaded files.
    * @returns {Promise<void>} A promise that resolves when the file has been successfully added to the dataset.
    * @throws {DirectUploadClientError} - If there are errors while performing the operation.
    */
-  async execute(datasetId: number | string, uploadedFileDTO: UploadedFileDTO): Promise<void> {
-    await this.filesRepository.addUploadedFileToDataset(datasetId, uploadedFileDTO)
+  async execute(datasetId: number | string, uploadedFileDTOs: UploadedFileDTO[]): Promise<void> {
+    await this.filesRepository.addUploadedFilesToDataset(datasetId, uploadedFileDTOs)
   }
 }

src/files/index.ts

@@ -10,7 +10,7 @@ import { GetFileCitation } from './domain/useCases/GetFileCitation'
 import { GetFileAndDataset } from './domain/useCases/GetFileAndDataset'
 import { UploadFile } from './domain/useCases/UploadFile'
 import { DirectUploadClient } from './infra/clients/DirectUploadClient'
-import { AddUploadedFileToDataset } from './domain/useCases/AddUploadedFileToDataset'
+import { AddUploadedFilesToDataset } from './domain/useCases/AddUploadedFilesToDataset'
 
 const filesRepository = new FilesRepository()
 const directUploadClient = new DirectUploadClient(filesRepository)
@@ -25,7 +25,7 @@ const getFile = new GetFile(filesRepository)
 const getFileAndDataset = new GetFileAndDataset(filesRepository)
 const getFileCitation = new GetFileCitation(filesRepository)
 const uploadFile = new UploadFile(directUploadClient)
-const addUploadedFileToDataset = new AddUploadedFileToDataset(filesRepository)
+const addUploadedFilesToDataset = new AddUploadedFilesToDataset(filesRepository)
 
 export {
   getDatasetFiles,
@@ -38,7 +38,7 @@ export {
   getFileAndDataset,
   getFileCitation,
   uploadFile,
-  addUploadedFileToDataset
+  addUploadedFilesToDataset
 }
 
 export { FileModel as File, FileEmbargo, FileChecksum } from './domain/models/FileModel'

src/files/infra/repositories/FilesRepository.ts

@@ -42,6 +42,22 @@ export interface GetFilesTotalDownloadSizeQueryParams {
   searchText?: string
 }
 
+export interface UploadedFileRequestBody {
+  fileName: string
+  description: string
+  directoryLabel: string
+  categories: string[]
+  restrict: boolean
+  checksum: ChecksumRequestBody
+  mimeType: string
+  storageIdentifier: string
+}
+
+export interface ChecksumRequestBody {
+  '@value': string
+  '@type': string
+}
+
 export class FilesRepository extends ApiRepository implements IFilesRepository {
   private readonly datasetsResourceName: string = 'datasets'
   private readonly filesResourceName: string = 'files'
@@ -223,21 +239,26 @@ export class FilesRepository extends ApiRepository implements IFilesRepository {
       })
   }
 
-  public async addUploadedFileToDataset(
+  public async addUploadedFilesToDataset(
     datasetId: number | string,
-    uploadedFileDTO: UploadedFileDTO
+    uploadedFileDTOs: UploadedFileDTO[]
   ): Promise<undefined> {
-    const fileArray = [
-      {
+    const fileArray: UploadedFileRequestBody[] = []
+    uploadedFileDTOs.forEach((uploadedFileDTO) => {
+      fileArray.push({
         fileName: uploadedFileDTO.fileName,
         checksum: {
           '@value': uploadedFileDTO.checksumValue,
           '@type': uploadedFileDTO.checksumType.toUpperCase()
         },
         mimeType: uploadedFileDTO.mimeType,
-        storageIdentifier: uploadedFileDTO.storageId
-      }
-    ]
+        storageIdentifier: uploadedFileDTO.storageId,
+        ...(uploadedFileDTO.description && { description: uploadedFileDTO.description }),
+        ...(uploadedFileDTO.categories && { categories: uploadedFileDTO.categories }),
+        ...(uploadedFileDTO.restrict && { restrict: uploadedFileDTO.restrict }),
+        ...(uploadedFileDTO.directoryLabel && { directoryLabel: uploadedFileDTO.directoryLabel })
+      })
+    })
     const formData = new FormData()
     formData.append('jsonData', JSON.stringify(fileArray))
     return this.doPost(

test/integration/files/DirectUpload.test.ts

@@ -121,7 +121,7 @@ describe('Direct Upload', () => {
       mimeType: singlepartFile.type
     }
 
-    await filesRepositorySut.addUploadedFileToDataset(testDataset1Ids.numericId, uploadedFileDTO)
+    await filesRepositorySut.addUploadedFilesToDataset(testDataset1Ids.numericId, [uploadedFileDTO])
 
     datasetFiles = await filesRepositorySut.getDatasetFiles(
       testDataset1Ids.numericId,
@@ -184,7 +184,7 @@ describe('Direct Upload', () => {
       mimeType: multipartFile.type
     }
 
-    await filesRepositorySut.addUploadedFileToDataset(testDataset2Ids.numericId, uploadedFileDTO)
+    await filesRepositorySut.addUploadedFilesToDataset(testDataset2Ids.numericId, [uploadedFileDTO])
 
     datasetFiles = await filesRepositorySut.getDatasetFiles(
       testDataset2Ids.numericId,

test/unit/files/AddUploadedFileToDataset.test.ts

@@ -1,35 +1,37 @@
 import { DirectUploadClientError } from '../../../src/files/domain/clients/DirectUploadClientError'
-import { AddUploadedFileToDataset } from '../../../src/files/domain/useCases/AddUploadedFileToDataset'
+import { AddUploadedFilesToDataset } from '../../../src/files/domain/useCases/AddUploadedFilesToDataset'
 import { IFilesRepository } from '../../../src/files/domain/repositories/IFilesRepository'
 
 describe('execute', () => {
-  const testUploadedFileDTO = {
-    fileName: 'testfile',
-    storageId: 'testStorageId',
-    checksumValue: 'testChecksumValue',
-    checksumType: 'md5',
-    mimeType: 'test/type'
-  }
+  const testUploadedFileDTOs = [
+    {
+      fileName: 'testfile',
+      storageId: 'testStorageId',
+      checksumValue: 'testChecksumValue',
+      checksumType: 'md5',
+      mimeType: 'test/type'
+    }
+  ]
 
   test('should return undefined on client success', async () => {
     const filesRepositoryStub: IFilesRepository = {} as IFilesRepository
-    filesRepositoryStub.addUploadedFileToDataset = jest.fn().mockResolvedValue(undefined)
+    filesRepositoryStub.addUploadedFilesToDataset = jest.fn().mockResolvedValue(undefined)
 
-    const sut = new AddUploadedFileToDataset(filesRepositoryStub)
+    const sut = new AddUploadedFilesToDataset(filesRepositoryStub)
 
-    const actual = await sut.execute(1, testUploadedFileDTO)
+    const actual = await sut.execute(1, testUploadedFileDTOs)
 
     expect(actual).toEqual(undefined)
   })
 
   test('should return error on client error', async () => {
     const filesRepositoryStub: IFilesRepository = {} as IFilesRepository
-    filesRepositoryStub.addUploadedFileToDataset = jest
+    filesRepositoryStub.addUploadedFilesToDataset = jest
       .fn()
       .mockRejectedValue(new DirectUploadClientError('test', 'test', 'test'))
 
-    const sut = new AddUploadedFileToDataset(filesRepositoryStub)
+    const sut = new AddUploadedFilesToDataset(filesRepositoryStub)
 
-    await expect(sut.execute(1, testUploadedFileDTO)).rejects.toThrow(DirectUploadClientError)
+    await expect(sut.execute(1, testUploadedFileDTOs)).rejects.toThrow(DirectUploadClientError)
   })
 })

test/unit/files/DirectUploadClient.test.ts

@@ -79,7 +79,7 @@ describe('uploadFile', () => {
       const filesRepositoryStub: IFilesRepository = {} as IFilesRepository
       const testDestination: FileUploadDestination = createSingleFileUploadDestinationModel()
       filesRepositoryStub.getFileUploadDestination = jest.fn().mockResolvedValue(testDestination)
-      filesRepositoryStub.addUploadedFileToDataset = jest.fn().mockResolvedValue(undefined)
+      filesRepositoryStub.addUploadedFilesToDataset = jest.fn().mockResolvedValue(undefined)
 
       jest.spyOn(axios, 'put').mockResolvedValue(undefined)
 
@@ -199,7 +199,7 @@ describe('uploadFile', () => {
       filesRepositoryStub.getFileUploadDestination = jest
         .fn()
         .mockResolvedValue(testMultipartDestination)
-      filesRepositoryStub.addUploadedFileToDataset = jest.fn().mockResolvedValue(undefined)
+      filesRepositoryStub.addUploadedFilesToDataset = jest.fn().mockResolvedValue(undefined)
 
       jest
         .spyOn(axios, 'put')