Merge pull request #270 from IQSS/feat/260-get-dataset-versions-use-case

Get Dataset Versions Summaries use case

Author: ofahimIQSS

docs/useCases.md

@@ -33,6 +33,7 @@ The different use cases currently available in the package are classified below,
     - [Get User Permissions on a Dataset](#get-user-permissions-on-a-dataset)
     - [Get Differences between Two Dataset Versions](#get-differences-between-two-dataset-versions)
     - [List All Datasets](#list-all-datasets)
+    - [Get Dataset Versions Summaries](#get-dataset-versions-summaries)
   - [Datasets write use cases](#datasets-write-use-cases)
     - [Create a Dataset](#create-a-dataset)
     - [Update a Dataset](#update-a-dataset)
@@ -577,7 +578,7 @@ const datasetId = 'doi:10.77777/FK2/AAAAAA'
 const oldVersion = '1.0'
 const newVersion = '2.0'
 
-lgetDatasetVersionDiff
+getDatasetVersionDiff
   .execute(datasetId, oldVersion, newVersion)
   .then((versionDiff: DatasetVersionDiff) => {
     /* ... */
@@ -622,6 +623,32 @@ Note that `collectionId` is an optional parameter to filter datasets by collecti
 
 The `DatasetPreviewSubset`returned instance contains a property called `totalDatasetCount` which is necessary for pagination.
 
+#### Get Dataset Versions Summaries
+
+Returns an array of [DatasetVersionSummaryInfo](../src/datasets/domain/models/DatasetVersionSummaryInfo.ts) that contains information about what changed in every specific version.
+
+##### Example call:
+
+```typescript
+import { getDatasetVersionsSummaries } from '@iqss/dataverse-client-javascript'
+
+/* ... */
+
+const datasetId = 'doi:10.77777/FK2/AAAAAA'
+
+getDatasetVersionsSummaries
+  .execute(datasetId)
+  .then((datasetVersionsSummaries: DatasetVersionSummaryInfo[]) => {
+    /* ... */
+  })
+
+/* ... */
+```
+
+_See [use case](../src/datasets/domain/useCases/GetDatasetVersionsSummaries.ts) implementation_.
+
+The `datasetId` parameter can be a string, for persistent identifiers, or a number, for numeric identifiers.
+
 ### Datasets Write Use Cases
 
 #### Create a Dataset

jest.config.ts

@@ -9,7 +9,7 @@ const config: Config = {
   moduleFileExtensions: ['ts', 'js', 'json', 'node'],
   coveragePathIgnorePatterns: ['node_modules', 'testHelpers'],
   globalSetup: '<rootDir>/test/environment/setup.ts',
-  testTimeout: 25000,
+  testTimeout: 35000,
   coverageThreshold: {
     global: {
       branches: 90,

src/datasets/domain/models/DatasetVersionSummaryInfo.ts

@@ -0,0 +1,36 @@
+export interface DatasetVersionSummaryInfo {
+  id: number
+  versionNumber: string
+  summary?: DatasetVersionSummary | DatasetVersionSummaryStringValues
+  contributors: string
+  publishedOn?: string
+}
+
+export type DatasetVersionSummary = {
+  [key: string]: SummaryUpdates | SummaryUpdatesWithFields | FilesSummaryUpdates | boolean
+}
+
+interface SummaryUpdates {
+  added: number
+  deleted: number
+  changed: number
+}
+
+interface SummaryUpdatesWithFields {
+  [key: string]: SummaryUpdates
+}
+
+interface FilesSummaryUpdates {
+  added: number
+  removed: number
+  replaced: number
+  changedFileMetaData: number
+  changedVariableMetadata: number
+}
+
+export enum DatasetVersionSummaryStringValues {
+  firstPublished = 'firstPublished',
+  firstDraft = 'firstDraft',
+  versionDeaccessioned = 'versionDeaccessioned',
+  previousVersionDeaccessioned = 'previousVersionDeaccessioned'
+}

src/datasets/domain/repositories/IDatasetsRepository.ts

@@ -7,6 +7,7 @@ import { DatasetDTO } from '../dtos/DatasetDTO'
 import { DatasetDeaccessionDTO } from '../dtos/DatasetDeaccessionDTO'
 import { MetadataBlock } from '../../../metadataBlocks'
 import { DatasetVersionDiff } from '../models/DatasetVersionDiff'
+import { DatasetVersionSummaryInfo } from '../models/DatasetVersionSummaryInfo'
 
 export interface IDatasetsRepository {
   getDataset(
@@ -51,4 +52,5 @@ export interface IDatasetsRepository {
     datasetVersionId: string,
     deaccessionDTO: DatasetDeaccessionDTO
   ): Promise<void>
+  getDatasetVersionsSummaries(datasetId: number | string): Promise<DatasetVersionSummaryInfo[]>
 }

src/datasets/domain/useCases/GetDatasetVersionsSummaries.ts

@@ -0,0 +1,22 @@
+import { UseCase } from '../../../core/domain/useCases/UseCase'
+import { DatasetVersionSummaryInfo } from '../models/DatasetVersionSummaryInfo'
+import { IDatasetsRepository } from '../repositories/IDatasetsRepository'
+
+export class GetDatasetVersionsSummaries implements UseCase<DatasetVersionSummaryInfo[]> {
+  private datasetsRepository: IDatasetsRepository
+
+  constructor(datasetsRepository: IDatasetsRepository) {
+    this.datasetsRepository = datasetsRepository
+  }
+
+  /**
+   * Returns a list of versions for a given dataset including a summary of differences between consecutive versions where available.
+   * Draft versions will only be available to users who have permission to view unpublished drafts.
+   *
+   * @param {number | string} [datasetId] - The dataset identifier, which can be a string (for persistent identifiers), or a number (for numeric identifiers).
+   * @returns {Promise<DatasetVersionSummaryInfo[]>} - An array of DatasetVersionSummaryInfo.
+   */
+  async execute(datasetId: number | string): Promise<DatasetVersionSummaryInfo[]> {
+    return await this.datasetsRepository.getDatasetVersionsSummaries(datasetId)
+  }
+}

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 { GetDatasetVersionsSummaries } from './domain/useCases/GetDatasetVersionsSummaries'
 
 const datasetsRepository = new DatasetsRepository()
 
@@ -48,6 +49,7 @@ const updateDataset = new UpdateDataset(
   datasetResourceValidator
 )
 const deaccessionDataset = new DeaccessionDataset(datasetsRepository)
+const getDatasetVersionsSummaries = new GetDatasetVersionsSummaries(datasetsRepository)
 
 export {
   getDataset,
@@ -62,7 +64,8 @@ export {
   publishDataset,
   createDataset,
   updateDataset,
-  deaccessionDataset
+  deaccessionDataset,
+  getDatasetVersionsSummaries
 }
 export { DatasetNotNumberedVersion } from './domain/models/DatasetNotNumberedVersion'
 export { DatasetUserPermissions } from './domain/models/DatasetUserPermissions'
@@ -92,3 +95,7 @@ export {
 export { DatasetDeaccessionDTO } from './domain/dtos/DatasetDeaccessionDTO'
 export { CreatedDatasetIdentifiers } from './domain/models/CreatedDatasetIdentifiers'
 export { VersionUpdateType } from './domain/models/Dataset'
+export {
+  DatasetVersionSummaryInfo,
+  DatasetVersionSummaryStringValues
+} from './domain/models/DatasetVersionSummaryInfo'

src/datasets/infra/repositories/DatasetsRepository.ts

@@ -18,6 +18,7 @@ import { transformDatasetLocksResponseToDatasetLocks } from './transformers/data
 import { transformDatasetPreviewsResponseToDatasetPreviewSubset } from './transformers/datasetPreviewsTransformers'
 import { DatasetVersionDiff } from '../../domain/models/DatasetVersionDiff'
 import { transformDatasetVersionDiffResponseToDatasetVersionDiff } from './transformers/datasetVersionDiffTransformers'
+import { DatasetVersionSummaryInfo } from '../../domain/models/DatasetVersionSummaryInfo'
 
 export interface GetAllDatasetPreviewsQueryParams {
   per_page?: number
@@ -235,4 +236,17 @@ export class DatasetsRepository extends ApiRepository implements IDatasetsReposi
         throw error
       })
   }
+
+  public async getDatasetVersionsSummaries(
+    datasetId: string | number
+  ): Promise<DatasetVersionSummaryInfo[]> {
+    return this.doGet(
+      this.buildApiEndpoint(this.datasetsResourceName, 'versions/compareSummary', datasetId),
+      true
+    )
+      .then((response) => response.data.data)
+      .catch((error) => {
+        throw error
+      })
+  }
 }

test/environment/.env

@@ -1,6 +1,6 @@
 POSTGRES_VERSION=13
 DATAVERSE_DB_USER=dataverse
-SOLR_VERSION=9.3.0
+SOLR_VERSION=9.8.0
 DATAVERSE_IMAGE_REGISTRY=docker.io
 DATAVERSE_IMAGE_TAG=unstable
 DATAVERSE_BOOTSTRAP_TIMEOUT=5m