197 compare dataset versions

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,50 @@
+// Details API
+
+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,178 @@
+/*
+{
+    "status": "OK",
+    "data": {
+        "oldVersion": {
+            "versionNumber": "1.0",
+            "lastUpdatedDate": "2024-10-24T15:17:11Z"
+        },
+        "newVersion": {
+            "versionNumber": "DRAFT",
+            "lastUpdatedDate": "2024-10-24T15:17:16Z"
+        },
+        "metadataChanges": [
+            {
+                "blockName": "Citation Metadata",
+                "changed": [
+                    {
+                        "fieldName": "Author",
+                        "oldValue": "Finch, Fiona; (Birds Inc.)",
+                        "newValue": "Finch, Fiona; (Birds Inc.); Poe, Edgar Allen; (Baltimore Poets); Mulligan, Hercules; (Sons of Liberty)"
+                    },
+                    {
+                        "fieldName": "Subject",
+                        "oldValue": "Medicine, Health and Life Sciences",
+                        "newValue": "Medicine, Health and Life Sciences; Astronomy and Astrophysics; Other"
+                    },
+                    {
+                        "fieldName": "Producer",
+                        "oldValue": "",
+                        "newValue": "Allen, Irwin; (MGM); Spielberg, Stephen; (ILM)"
+                    }
+                ]
+            },
+            {
+                "blockName": "Life Sciences Metadata",
+                "changed": [
+                    {
+                        "fieldName": "Design Type",
+                        "oldValue": "",
+                        "newValue": "Parallel Group Design; Nested Case Control Design"
+                    }
+                ]
+            }
+        ],
+        "filesAdded": [
+            {
+                "fileName": "test.tab",
+                "filePath": "data/subdir1",
+                "MD5": "77c7f03a7d7772907b43f0b322cef723",
+                "type": "text/tab-separated-values",
+                "fileId": 42,
+                "description": "my description",
+                "isRestricted": false,
+                "categories": [
+                    "Data"
+                ],
+                "tags": [
+                    "Survey"
+                ]
+            }
+        ],
+        "filesRemoved": [
+            {
+                "fileName": "dataverseproject_logo.jpg",
+                "filePath": "data/subdir1",
+                "MD5": "c1edbefa86a55c5037873370ae7fd7b6",
+                "type": "image/jpeg",
+                "fileId": 40,
+                "description": "my description",
+                "isRestricted": false,
+                "categories": [
+                    "Data"
+                ]
+            }
+        ],
+        "filesReplaced": [
+            {
+                "oldFile": {
+                    "fileName": "favicon-16x16.png",
+                    "filePath": "data/subdir1",
+                    "MD5": "d3c852e7ecb92fd105ba4018116a9be8",
+                    "type": "image/png",
+                    "fileId": 41,
+                    "description": "my description",
+                    "isRestricted": false,
+                    "categories": [
+                        "Data"
+                    ]
+                },
+                "newFile": {
+                    "fileName": "favicon-32x32.png",
+                    "filePath": "data/subdir1",
+                    "MD5": "c931f7add8b6a1f9a691046b77c231fa",
+                    "type": "image/png",
+                    "fileId": 43,
+                    "description": "my description",
+                    "isRestricted": false,
+                    "categories": [
+                        "Data"
+                    ]
+                }
+            }
+        ],
+        "fileChanges": [
+            {
+                "fileName": "dataverse-icon-1200.png",
+                "MD5": "a23eb44803d9127bc6e055f77b869816",
+                "fileId": 39,
+                "changed": [
+                    {
+                        "fieldName": "isRestricted",
+                        "oldValue": "false",
+                        "newValue": "true"
+                    }
+                ]
+            }
+        ],
+        "TermsOfAccess": {
+            "changed": [
+                {
+                    "fieldName": "Data Access Place",
+                    "oldValue": "",
+                    "newValue": "Somewhere"
+                }
+            ]
+        }
+    }
+}
+ */
+
+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
+}