Merge pull request #220 from IQSS/197-compare-dataset-versions

197 compare dataset versions

Author: ofahimIQSS

docs/useCases.md

@@ -27,6 +27,7 @@ The different use cases currently available in the package are classified below,
     - [Get Dataset Locks](#get-dataset-locks)
     - [Get Dataset Summary Field Names](#get-dataset-summary-field-names)
     - [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)
   - [Datasets write use cases](#datasets-write-use-cases)
     - [Create a Dataset](#create-a-dataset)
@@ -457,6 +458,36 @@ _See [use case](../src/datasets/domain/useCases/GetDatasetUserPermissions.ts) im
 
 The `datasetId` parameter can be a string, for persistent identifiers, or a number, for numeric identifiers.
 
+#### Get Differences between Two Dataset Versions
+
+Returns an instance of [DatasetVersionDiff](../src/datasets/domain/models/DatasetVersionDiff.ts) that contains the differences between two Dataset Versions.
+
+##### Example call:
+
+```typescript
+import { getDatasetVersionDiff } from '@iqss/dataverse-client-javascript'
+
+/* ... */
+
+const datasetId = 'doi:10.77777/FK2/AAAAAA'
+const oldVersion = '1.0'
+const newVersion = '2.0'
+
+lgetDatasetVersionDiff
+  .execute(datasetId, oldVersion, newVersion)
+  .then((versionDiff: DatasetVersionDiff) => {
+    /* ... */
+  })
+
+/* ... */
+```
+
+_See [use case](../src/datasets/domain/useCases/GetDatasetVersionDiff.ts) implementation_.
+
+The `datasetId` parameter can be a string, for persistent identifiers, or a number, for numeric identifiers.
+
+The `oldVersion` and `newVersion` parameters specify the versions of the dataset to compare.
+
 #### List All Datasets
 
 Returns an instance of [DatasetPreviewSubset](../src/datasets/domain/models/DatasetPreviewSubset.ts) that contains reduced information for each dataset that the calling user can access in the installation.

src/datasets/domain/models/DatasetVersionDiff.ts

@@ -0,0 +1,48 @@
+export interface DatasetVersionDiff {
+  oldVersion: VersionSummary
+  newVersion: VersionSummary
+  metadataChanges?: MetadataBlockDiff[]
+  filesAdded?: FileSummary[]
+  filesRemoved?: FileSummary[]
+  fileChanges?: FileDiff[]
+  filesReplaced?: FileReplacement[]
+  termsOfAccess?: FieldDiff[]
+}
+
+export interface FileSummary {
+  fileName: string
+  MD5: string
+  type: string
+  fileId: number
+  filePath: string
+  description: string
+  isRestricted: boolean
+  tags: string[]
+  categories: string[]
+}
+
+export interface VersionSummary {
+  versionNumber: string
+  lastUpdatedDate: string
+}
+export interface MetadataBlockDiff {
+  blockName: string
+  changed: FieldDiff[]
+}
+
+export interface FileDiff {
+  fileName: string
+  md5: string
+  fileId: number
+  changed: FieldDiff[]
+}
+
+export interface FileReplacement {
+  oldFile: FileSummary
+  newFile: FileSummary
+}
+export interface FieldDiff {
+  fieldName: string
+  oldValue: string
+  newValue: string
+}

src/datasets/domain/repositories/IDatasetsRepository.ts

@@ -5,6 +5,7 @@ import { DatasetUserPermissions } from '../models/DatasetUserPermissions'
 import { CreatedDatasetIdentifiers } from '../models/CreatedDatasetIdentifiers'
 import { DatasetDTO } from '../dtos/DatasetDTO'
 import { MetadataBlock } from '../../../metadataBlocks'
+import { DatasetVersionDiff } from '../models/DatasetVersionDiff'
 
 export interface IDatasetsRepository {
   getDataset(
@@ -28,6 +29,11 @@ export interface IDatasetsRepository {
   getDatasetSummaryFieldNames(): Promise<string[]>
   getPrivateUrlDatasetCitation(token: string): Promise<string>
   getDatasetUserPermissions(datasetId: number | string): Promise<DatasetUserPermissions>
+  getDatasetVersionDiff(
+    datasetId: number | string,
+    newVersionId: string,
+    oldVersionId: string
+  ): Promise<DatasetVersionDiff>
   createDataset(
     newDataset: DatasetDTO,
     datasetMetadataBlocks: MetadataBlock[],

src/datasets/domain/useCases/GetDatasetVersionDiff.ts

@@ -0,0 +1,29 @@
+import { UseCase } from '../../../core/domain/useCases/UseCase'
+import { IDatasetsRepository } from '../repositories/IDatasetsRepository'
+import { DatasetVersionDiff } from '../models/DatasetVersionDiff'
+
+export class GetDatasetVersionDiff implements UseCase<DatasetVersionDiff> {
+  private datasetsRepository: IDatasetsRepository
+
+  constructor(datasetsRepository: IDatasetsRepository) {
+    this.datasetsRepository = datasetsRepository
+  }
+
+  /**
+   * Returns a DatasetVersionDiff instance, which contains the differences between the two given versions.
+   * @param {number | string} [datasetId] - The dataset identifier, which can be a string (for persistent identifiers), or a number (for numeric identifiers).
+   * @param {string } [oldVersionId] - The dataset version identifier, which can be a version-specific numeric string (for example, 1.0) or a DatasetNotNumberedVersion enum value.
+   * @param {string } [newVersionId] - The dataset version identifier, which can be a version-specific numeric string (for example, 1.0) or a DatasetNotNumberedVersion enum value.
+   */
+  async execute(
+    datasetId: number | string,
+    oldVersionId: string,
+    newVersionId: string
+  ): Promise<DatasetVersionDiff> {
+    return await this.datasetsRepository.getDatasetVersionDiff(
+      datasetId,
+      oldVersionId,
+      newVersionId
+    )
+  }
+}

src/datasets/index.ts

@@ -15,6 +15,7 @@ import { SingleMetadataFieldValidator } from './domain/useCases/validators/Singl
 import { MultipleMetadataFieldValidator } from './domain/useCases/validators/MultipleMetadataFieldValidator'
 import { PublishDataset } from './domain/useCases/PublishDataset'
 import { UpdateDataset } from './domain/useCases/UpdateDataset'
+import { GetDatasetVersionDiff } from './domain/useCases/GetDatasetVersionDiff'
 
 const datasetsRepository = new DatasetsRepository()
 
@@ -26,6 +27,7 @@ const getAllDatasetPreviews = new GetAllDatasetPreviews(datasetsRepository)
 const getDatasetUserPermissions = new GetDatasetUserPermissions(datasetsRepository)
 const getDatasetSummaryFieldNames = new GetDatasetSummaryFieldNames(datasetsRepository)
 const getPrivateUrlDatasetCitation = new GetPrivateUrlDatasetCitation(datasetsRepository)
+const getDatasetVersionDiff = new GetDatasetVersionDiff(datasetsRepository)
 const singleMetadataFieldValidator = new SingleMetadataFieldValidator()
 const metadataFieldValidator = new MetadataFieldValidator(
   new SingleMetadataFieldValidator(),
@@ -54,6 +56,7 @@ export {
   getDatasetUserPermissions,
   getDatasetSummaryFieldNames,
   getPrivateUrlDatasetCitation,
+  getDatasetVersionDiff,
   publishDataset,
   createDataset,
   updateDataset
@@ -73,6 +76,7 @@ export {
   DatasetMetadataFieldValue
 } from './domain/models/Dataset'
 export { DatasetPreview } from './domain/models/DatasetPreview'
+export { DatasetVersionDiff } from './domain/models/DatasetVersionDiff'
 export { DatasetPreviewSubset } from './domain/models/DatasetPreviewSubset'
 export {
   DatasetDTO,

src/datasets/infra/repositories/DatasetsRepository.ts

@@ -15,6 +15,8 @@ import { MetadataBlock } from '../../../metadataBlocks'
 import { transformDatasetModelToNewDatasetRequestPayload } from './transformers/datasetTransformers'
 import { transformDatasetLocksResponseToDatasetLocks } from './transformers/datasetLocksTransformers'
 import { transformDatasetPreviewsResponseToDatasetPreviewSubset } from './transformers/datasetPreviewsTransformers'
+import { DatasetVersionDiff } from '../../domain/models/DatasetVersionDiff'
+import { transformDatasetVersionDiffResponseToDatasetVersionDiff } from './transformers/datasetVersionDiffTransformers'
 
 export interface GetAllDatasetPreviewsQueryParams {
   per_page?: number
@@ -141,6 +143,24 @@ export class DatasetsRepository extends ApiRepository implements IDatasetsReposi
       })
   }
 
+  public async getDatasetVersionDiff(
+    datasetId: string | number,
+    oldVersionId: string,
+    newVersionId: string
+  ): Promise<DatasetVersionDiff> {
+    return this.doGet(
+      this.buildApiEndpoint(
+        this.datasetsResourceName,
+        `versions/${oldVersionId}/compare/${newVersionId}`,
+        datasetId
+      ),
+      true
+    )
+      .then((response) => transformDatasetVersionDiffResponseToDatasetVersionDiff(response))
+      .catch((error) => {
+        throw error
+      })
+  }
   public async createDataset(
     newDataset: DatasetDTO,
     datasetMetadataBlocks: MetadataBlock[],

src/datasets/infra/repositories/transformers/DatasetVersionDiffPayload.ts

@@ -0,0 +1,48 @@
+export interface DatasetVersionDiffPayload {
+  oldVersion: VersionSummaryPayload
+  newVersion: VersionSummaryPayload
+  metadataChanges: MetadataBlockDiffPayload[]
+  filesAdded: FileSummaryPayload[]
+  filesRemoved: FileSummaryPayload[]
+  fileChanges: FileDiffPayload[]
+  filesReplaced: FileReplacementPayload[]
+  TermsOfAccess: FieldDiffPayload[]
+}
+
+export interface FileSummaryPayload {
+  fileName: string
+  MD5: string
+  type: string
+  fileId: number
+  filePath: string
+  description: string
+  isRestricted: boolean
+  tags: string[]
+  categories: string[]
+}
+
+export interface VersionSummaryPayload {
+  versionNumber: string
+  lastUpdatedDate: string
+}
+export interface MetadataBlockDiffPayload {
+  blockName: string
+  changed: FieldDiffPayload[]
+}
+
+export interface FileDiffPayload {
+  fileName: string
+  md5: string
+  fileId: number
+  changed: FieldDiffPayload[]
+}
+export interface FieldDiffPayload {
+  fieldName: string
+  oldValue: string
+  newValue: string
+}
+
+export interface FileReplacementPayload {
+  oldFile: FileSummaryPayload
+  newFile: FileSummaryPayload
+}

src/datasets/infra/repositories/transformers/datasetVersionDiffTransformers.ts

@@ -0,0 +1,19 @@
+import { AxiosResponse } from 'axios'
+import { DatasetVersionDiff } from '../../../domain/models/DatasetVersionDiff'
+
+export const transformDatasetVersionDiffResponseToDatasetVersionDiff = (
+  response: AxiosResponse
+): DatasetVersionDiff => {
+  const datasetVersionDiffPayload = response.data.data
+  const retValue = {
+    oldVersion: datasetVersionDiffPayload.oldVersion,
+    newVersion: datasetVersionDiffPayload.newVersion,
+    metadataChanges: datasetVersionDiffPayload.metadataChanges,
+    filesAdded: datasetVersionDiffPayload.filesAdded,
+    filesRemoved: datasetVersionDiffPayload.filesRemoved,
+    fileChanges: datasetVersionDiffPayload.fileChanges,
+    filesReplaced: datasetVersionDiffPayload.filesReplaced,
+    termsOfAccess: datasetVersionDiffPayload.TermsOfAccess
+  }
+  return retValue
+}