feat: use case for dataset download count

Author: ChengShi-1

docs/useCases.md

@@ -807,6 +807,29 @@ The `version` parameter should be a string or a [DatasetNotNumberedVersion](../s
 
 You cannot deaccession a dataset more than once. If you call this endpoint twice for the same dataset version, you will get a not found error on the second call, since the dataset you are looking for will no longer be published since it is already deaccessioned.
 
+#### Get Download Count of a Dataset
+
+Total number of downloads requested for a dataset, given a dataset numeric identifier,
+
+##### Example call:
+
+```typescript
+import { getDatasetDownloadCount } from '@iqss/dataverse-client-javascript'
+
+/* ... */
+
+const datasetId = 1
+const includeMDC = true
+
+getDatasetDownloadCount.execute(datasetId, includeMDC)
+
+/* ... */
+```
+
+_See [use case](../src/datasets/domain/useCases/GetDatasetDownloadCount.ts) implementation_.
+The `datasetId` parameter is a number for numeric identifiers.
+The `includeMDC` parameter is optional. If MDC is enabled the count will be limited to the time before MDC start if the optional `includeMDC` parameter is not included or set to False. Setting `includeMDC` to True will ignore the `:MDCStartDate` setting and return a total count.
+
 ## Files
 
 ### Files read use cases

src/datasets/domain/repositories/IDatasetsRepository.ts

@@ -51,4 +51,5 @@ export interface IDatasetsRepository {
     datasetVersionId: string,
     deaccessionDTO: DatasetDeaccessionDTO
   ): Promise<void>
+  getDatasetDownloadCount(datasetId: number, includeMDC?: boolean): Promise<number>
 }

src/datasets/domain/useCases/GetDatasetDownloadCount.ts

@@ -0,0 +1,20 @@
+import { UseCase } from '../../../core/domain/useCases/UseCase'
+import { IDatasetsRepository } from '../repositories/IDatasetsRepository'
+export class GetDatasetDownloadCount implements UseCase<number> {
+  private datasetsRepository: IDatasetsRepository
+
+  constructor(datasetsRepository: IDatasetsRepository) {
+    this.datasetsRepository = datasetsRepository
+  }
+
+  /**
+   * Returns the Dataset Download Count.
+   *
+   * @param {number} [datasetId] - The dataset identifier.
+   * @param {boolean} [includeMDC(optional)] - Indicates whether to consider include counts from MDC start date or not. The default value is false
+   * @returns {Promise<number>}
+   */
+  async execute(datasetId: number, includeMDC?: boolean): Promise<number> {
+    return await this.datasetsRepository.getDatasetDownloadCount(datasetId, includeMDC)
+  }
+}

src/datasets/index.ts

@@ -17,6 +17,7 @@ import { PublishDataset } from './domain/useCases/PublishDataset'
 import { UpdateDataset } from './domain/useCases/UpdateDataset'
 import { GetDatasetVersionDiff } from './domain/useCases/GetDatasetVersionDiff'
 import { DeaccessionDataset } from './domain/useCases/DeaccessionDataset'
+import { GetDatasetDownloadCount } from './domain/useCases/GetDatasetDownloadCount'
 
 const datasetsRepository = new DatasetsRepository()
 
@@ -48,6 +49,7 @@ const updateDataset = new UpdateDataset(
   datasetResourceValidator
 )
 const deaccessionDataset = new DeaccessionDataset(datasetsRepository)
+const getDatasetDownloadCount = new GetDatasetDownloadCount(datasetsRepository)
 
 export {
   getDataset,
@@ -62,7 +64,8 @@ export {
   publishDataset,
   createDataset,
   updateDataset,
-  deaccessionDataset
+  deaccessionDataset,
+  getDatasetDownloadCount
 }
 export { DatasetNotNumberedVersion } from './domain/models/DatasetNotNumberedVersion'
 export { DatasetUserPermissions } from './domain/models/DatasetUserPermissions'

src/datasets/infra/repositories/DatasetsRepository.ts

@@ -235,4 +235,18 @@ export class DatasetsRepository extends ApiRepository implements IDatasetsReposi
         throw error
       })
   }
+
+  public async getDatasetDownloadCount(datasetId: number, includeMDC?: boolean): Promise<number> {
+    const queryParams = includeMDC !== undefined ? { includeMDC } : {}
+
+    return this.doGet(
+      this.buildApiEndpoint(this.datasetsResourceName, `${datasetId}/download/count`),
+      true,
+      queryParams
+    )
+      .then((response) => response.data.downloadCount)
+      .catch((error) => {
+        throw error
+      })
+  }
 }

test/functional/datasets/GetDatasetDownloadCount.test.ts

@@ -0,0 +1,98 @@
+import {
+  getDatasetDownloadCount,
+  createDataset,
+  publishDataset,
+  VersionUpdateType
+} from '../../../src/datasets'
+import { ApiConfig, ReadError } from '../../../src'
+import { TestConstants } from '../../testHelpers/TestConstants'
+import { DataverseApiAuthMechanism } from '../../../src/core/infra/repositories/ApiConfig'
+import {
+  deletePublishedDatasetViaApi,
+  deleteUnpublishedDatasetViaApi
+} from '../../testHelpers/datasets/datasetHelper'
+
+const testDataset = {
+  license: {
+    name: 'CC0 1.0',
+    uri: 'http://creativecommons.org/publicdomain/zero/1.0',
+    iconUri: 'https://licensebuttons.net/p/zero/1.0/88x31.png'
+  },
+  metadataBlockValues: [
+    {
+      name: 'citation',
+      fields: {
+        title: 'Dataset for download count testing',
+        author: [
+          {
+            authorName: 'Test, User',
+            authorAffiliation: 'Dataverse.org'
+          }
+        ],
+        datasetContact: [
+          {
+            datasetContactEmail: '[email protected]',
+            datasetContactName: 'User, Test'
+          }
+        ],
+        dsDescription: [
+          {
+            dsDescriptionValue: 'This dataset is used for testing the download count API.'
+          }
+        ],
+        subject: ['Computer Science']
+      }
+    }
+  ]
+}
+
+describe('execute', () => {
+  beforeEach(async () => {
+    ApiConfig.init(
+      TestConstants.TEST_API_URL,
+      DataverseApiAuthMechanism.API_KEY,
+      process.env.TEST_API_KEY
+    )
+  })
+
+  test('should return download count for a dataset', async () => {
+    const createdDatasetIdentifiers = await createDataset.execute(testDataset)
+
+    await publishDataset.execute(createdDatasetIdentifiers.persistentId, VersionUpdateType.MAJOR)
+
+    const downloadCount = await getDatasetDownloadCount.execute(createdDatasetIdentifiers.numericId)
+
+    expect(downloadCount).toBe(0)
+
+    await deletePublishedDatasetViaApi(createdDatasetIdentifiers.persistentId)
+  })
+
+  test('should return download count including MDC data', async () => {
+    const createdDatasetIdentifiers = await createDataset.execute(testDataset)
+
+    await publishDataset.execute(createdDatasetIdentifiers.persistentId, VersionUpdateType.MAJOR)
+
+    const downloadCount = await getDatasetDownloadCount.execute(
+      createdDatasetIdentifiers.numericId,
+      true
+    )
+
+    expect(downloadCount).toBe(0)
+
+    await deletePublishedDatasetViaApi(createdDatasetIdentifiers.persistentId)
+  })
+
+  test('should throw an error when dataset ID is invalid', async () => {
+    await expect(getDatasetDownloadCount.execute(999999)).rejects.toBeInstanceOf(ReadError)
+  })
+
+  test('should return zero if dataset has no downloads', async () => {
+    const createdDatasetIdentifiers = await createDataset.execute(testDataset)
+
+    const downloadCount = await getDatasetDownloadCount.execute(createdDatasetIdentifiers.numericId)
+
+    expect(downloadCount).toBe(0)
+
+    await deleteUnpublishedDatasetViaApi(createdDatasetIdentifiers.numericId)
+  })
+})

test/integration/datasets/DatasetsRepository.test.ts

@@ -925,4 +925,41 @@ describe('DatasetsRepository', () => {
       ).rejects.toBeInstanceOf(WriteError)
     })
   })
+
+  describe('getDatasetDownloadCount', () => {
+    test('should return download count for a dataset', async () => {
+      const testDatasetIds = await createDataset.execute(TestConstants.TEST_NEW_DATASET_DTO)
+      const fileMetadata = {
+        description: 'test description',
+        directoryLabel: 'directoryLabel',
+        categories: ['category1', 'category2']
+      }
+      await uploadFileViaApi(testDatasetIds.numericId, testTextFile1Name, fileMetadata)
+      await publishDatasetViaApi(testDatasetIds.numericId)
+      await waitForNoLocks(testDatasetIds.numericId, 10)
+      const actual = await sut.getDatasetDownloadCount(testDatasetIds.numericId)
+
+      expect(actual).toBe(0)
+
+      await deletePublishedDatasetViaApi(testDatasetIds.persistentId)
+    })
+
+    test('should return download count including MDC data', async () => {
+      const testDatasetIds = await createDataset.execute(TestConstants.TEST_NEW_DATASET_DTO)
+      await publishDatasetViaApi(testDatasetIds.numericId)
+      await waitForNoLocks(testDatasetIds.numericId, 10)
+
+      const actual = await sut.getDatasetDownloadCount(testDatasetIds.numericId, true)
+
+      expect(actual).toBe(0)
+
+      await deletePublishedDatasetViaApi(testDatasetIds.persistentId)
+    })
+
+    test('should return error when dataset does not exist', async () => {
+      await expect(sut.getDatasetDownloadCount(nonExistentTestDatasetId)).rejects.toBeInstanceOf(
+        ReadError
+      )
+    })
+  })
 })

test/unit/datasets/GetDatasetDownloadCount.test.ts

@@ -0,0 +1,30 @@
+import { GetDatasetDownloadCount } from '../../../src/datasets/domain/useCases/GetDatasetDownloadCount'
+import { IDatasetsRepository } from '../../../src/datasets/domain/repositories/IDatasetsRepository'
+import { ReadError } from '../../../src/core/domain/repositories/ReadError'
+
+describe('execute', () => {
+  const testDatasetId = 1
+  const testCount = 10
+
+  test('should return count on repository success filtering by id', async () => {
+    const filesRepositoryStub: IDatasetsRepository = {} as IDatasetsRepository
+    filesRepositoryStub.getDatasetDownloadCount = jest.fn().mockResolvedValue(testCount)
+    const sut = new GetDatasetDownloadCount(filesRepositoryStub)
+
+    const actual = await sut.execute(testDatasetId)
+
+    expect(actual).toBe(testCount)
+    expect(filesRepositoryStub.getDatasetDownloadCount).toHaveBeenCalledWith(
+      testDatasetId,
+      undefined
+    )
+  })
+
+  test('should return error result on repository error', async () => {
+    const filesRepositoryStub: IDatasetsRepository = {} as IDatasetsRepository
+    filesRepositoryStub.getDatasetDownloadCount = jest.fn().mockRejectedValue(new ReadError())
+    const sut = new GetDatasetDownloadCount(filesRepositoryStub)
+
+    await expect(sut.execute(testDatasetId)).rejects.toThrow(ReadError)
+  })
+})