Add use case for getting dataset versions

CHANGELOG.md

@@ -15,6 +15,7 @@ This changelog follows the principles of [Keep a Changelog](https://keepachangel
 - Files: Added `getFileCitationByFormat` use case, repository method, and `FileCitationFormat` enum to support Dataverse file citation exports in `EndNote`, `RIS`, `BibTeX`, `CSL`, and `Internal` formats.
 - Datasets: Added `getDatasetReviews` use case and repository method to support Dataverse endpoint `GET /datasets/{identifier}/reviews`, for retrieving review datasets associated with a dataset by persistent id or numeric id.
 - Datasets: Added `exportDatasetMetadata` use case, repository method, and `ExportedDatasetMetadata` response type to support exporting dataset metadata by numeric id or persistent id through Dataverse endpoint `GET /datasets/export`.
+- Datasets: Added `getDatasetVersions` use case.
 - Collections: Added `allowedDatasetTypes` field to the [Collection](./src/collections/domain/models/Collection.ts) model. This field is optional and only populated the feature is enabled on the installation and configured on the collection.
 - Collections: Added theme information when retrieving a collection using `getCollection`.
 

docs/useCases.md

@@ -54,6 +54,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](#get-dataset-versions)
     - [Get Dataset Versions Summaries](#get-dataset-versions-summaries)
     - [Get Dataset Linked Collections](#get-dataset-linked-collections)
     - [Get Dataset Available Categories](#get-dataset-available-categories)
@@ -1262,6 +1263,36 @@ 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
+
+Returns an array of [Dataset](../src/datasets/domain/models/Dataset.ts) that contains information about every specific version.
+
+##### Example call:
+
+```typescript
+import { getDatasetVersions } from '@iqss/dataverse-client-javascript'
+
+/* ... */
+
+const datasetId = 'doi:10.77777/FK2/AAAAAA'
+
+getDatasetVersions
+  .execute(datasetId)
+  .then((datasetVersions: DatasetVersionSubset) => {
+    /* ... */
+  })
+
+/* ... */
+```
+
+_See [use case](../src/datasets/domain/useCases/GetDatasetVersions.ts) implementation_.
+
+- The `datasetId` parameter can be a string, for persistent identifiers, or a number, for numeric identifiers.
+- **limit**: (number) Limit for pagination.
+- **offset**: (number) Offset for pagination.
+- **excludeMetadataBlocks**: (boolean) Exclude metadata blocks (default: false).
+- Note that the **excludeFiles** parameter, which is available on Dataverse's "List Versions of a Dataset" API, is not available here. The list of files can be retrieved using the separate use case [List Files in a Dataset](#list-files-in-a-dataset).
+
 #### Get Dataset Versions Summaries
 
 Returns the total count of versions and an array of [DatasetVersionSummaryInfo](../src/datasets/domain/models/DatasetVersionSummaryInfo.ts) that contains information about what changed in every specific version.

src/datasets/domain/models/DatasetVersionSubset.ts

@@ -0,0 +1,5 @@
+import { Dataset, DatasetMetadataBlocks } from './Dataset'
+
+export interface DatasetVersionSubset {
+  versions: Array<Omit<Dataset, 'metadataBlocks'> & { metadataBlocks?: DatasetMetadataBlocks }>
+}

src/datasets/domain/repositories/IDatasetsRepository.ts

@@ -9,6 +9,7 @@ import { MetadataBlock } from '../../../metadataBlocks'
 import { DatasetVersionDiff } from '../models/DatasetVersionDiff'
 import { DatasetDownloadCount } from '../models/DatasetDownloadCount'
 import { DatasetVersionSummarySubset } from '../models/DatasetVersionSummaryInfo'
+import { DatasetVersionSubset } from '../models/DatasetVersionSubset'
 import { DatasetLinkedCollection } from '../models/DatasetLinkedCollection'
 import { CitationFormat } from '../models/CitationFormat'
 import { FormattedCitation } from '../models/FormattedCitation'
@@ -77,6 +78,13 @@ export interface IDatasetsRepository {
     limit?: number,
     offset?: number
   ): Promise<DatasetVersionSummarySubset>
+  getDatasetVersions(
+    datasetId: number | string,
+    limit?: number,
+    offset?: number,
+    excludeMetadataBlocks?: boolean,
+    keepRawFields?: boolean
+  ): Promise<DatasetVersionSubset>
   deleteDatasetDraft(datasetId: number | string): Promise<void>
   linkDataset(datasetId: number | string, collectionIdOrAlias: number | string): Promise<void>
   unlinkDataset(datasetId: number | string, collectionIdOrAlias: number | string): Promise<void>

src/datasets/domain/useCases/GetDatasetVersions.ts

@@ -0,0 +1,38 @@
+import { UseCase } from '../../../core/domain/useCases/UseCase'
+import { DatasetVersionSubset } from '../models/DatasetVersionSubset'
+import { IDatasetsRepository } from '../repositories/IDatasetsRepository'
+
+export class GetDatasetVersions implements UseCase<DatasetVersionSubset> {
+  private datasetsRepository: IDatasetsRepository
+
+  constructor(datasetsRepository: IDatasetsRepository) {
+    this.datasetsRepository = datasetsRepository
+  }
+
+  /**
+   * Returns a list of versions for a given dataset including (optionally) metadata blocks and files.
+   * 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).
+   * @param {number} [limit] - Limit for pagination (optional).
+   * @param {number} [offset] - Offset for pagination (optional).
+   * @param {boolean} [excludeMetadataBlocks] - Exclude metadata blocks (optional, default: false).
+   * @param {boolean} [keepRawFields=false] - Indicates whether or not the use case should keep the metadata fields as they are and avoid the transformation to markdown. The default value is false.
+   * @returns {Promise<DatasetVersionSubset>} - A DatasetVersionSubset containing the versions and total count.
+   */
+  async execute(
+    datasetId: number | string,
+    limit?: number,
+    offset?: number,
+    excludeMetadataBlocks?: boolean,
+    keepRawFields?: boolean
+  ): Promise<DatasetVersionSubset> {
+    return await this.datasetsRepository.getDatasetVersions(
+      datasetId,
+      limit,
+      offset,
+      excludeMetadataBlocks,
+      keepRawFields
+    )
+  }
+}

src/datasets/index.ts

@@ -19,6 +19,7 @@ import { GetDatasetVersionDiff } from './domain/useCases/GetDatasetVersionDiff'
 import { DeaccessionDataset } from './domain/useCases/DeaccessionDataset'
 import { GetDatasetDownloadCount } from './domain/useCases/GetDatasetDownloadCount'
 import { GetDatasetVersionsSummaries } from './domain/useCases/GetDatasetVersionsSummaries'
+import { GetDatasetVersions } from './domain/useCases/GetDatasetVersions'
 import { DeleteDatasetDraft } from './domain/useCases/DeleteDatasetDraft'
 import { LinkDataset } from './domain/useCases/LinkDataset'
 import { UnlinkDataset } from './domain/useCases/UnlinkDataset'
@@ -70,6 +71,7 @@ const updateDataset = new UpdateDataset(
 const deaccessionDataset = new DeaccessionDataset(datasetsRepository)
 const getDatasetDownloadCount = new GetDatasetDownloadCount(datasetsRepository)
 const getDatasetVersionsSummaries = new GetDatasetVersionsSummaries(datasetsRepository)
+const getDatasetVersions = new GetDatasetVersions(datasetsRepository)
 const deleteDatasetDraft = new DeleteDatasetDraft(datasetsRepository)
 const linkDataset = new LinkDataset(datasetsRepository)
 const unlinkDataset = new UnlinkDataset(datasetsRepository)
@@ -107,6 +109,7 @@ export {
   deaccessionDataset,
   getDatasetDownloadCount,
   getDatasetVersionsSummaries,
+  getDatasetVersions,
   deleteDatasetDraft,
   linkDataset,
   unlinkDataset,
@@ -143,6 +146,7 @@ export {
   TermsOfUse
 } from './domain/models/Dataset'
 export { DatasetPreview } from './domain/models/DatasetPreview'
+export { DatasetVersionSubset } from './domain/models/DatasetVersionSubset'
 export { DatasetVersionDiff } from './domain/models/DatasetVersionDiff'
 export { DatasetPreviewSubset } from './domain/models/DatasetPreviewSubset'
 export {

src/datasets/infra/repositories/DatasetsRepository.ts

@@ -3,7 +3,8 @@ import { IDatasetsRepository } from '../../domain/repositories/IDatasetsReposito
 import { Dataset, VersionUpdateType } from '../../domain/models/Dataset'
 import {
   transformVersionResponseToDataset,
-  transformDatasetModelToUpdateDatasetRequestPayload
+  transformDatasetModelToUpdateDatasetRequestPayload,
+  transformVersionPayloadToDataset
 } from './transformers/datasetTransformers'
 import { DatasetUserPermissions } from '../../domain/models/DatasetUserPermissions'
 import { transformDatasetUserPermissionsResponseToDatasetUserPermissions } from './transformers/datasetUserPermissionsTransformers'
@@ -20,6 +21,7 @@ import { DatasetVersionDiff } from '../../domain/models/DatasetVersionDiff'
 import { transformDatasetVersionDiffResponseToDatasetVersionDiff } from './transformers/datasetVersionDiffTransformers'
 import { DatasetDownloadCount } from '../../domain/models/DatasetDownloadCount'
 import { DatasetVersionSummarySubset } from '../../domain/models/DatasetVersionSummaryInfo'
+import { DatasetVersionSubset } from '../../domain/models/DatasetVersionSubset'
 import { DatasetLinkedCollection } from '../../domain/models/DatasetLinkedCollection'
 import { CitationFormat } from '../../domain/models/CitationFormat'
 import { transformDatasetLinkedCollectionsResponseToDatasetLinkedCollection } from './transformers/datasetLinkedCollectionsTransformers'
@@ -35,6 +37,7 @@ import { DatasetUploadLimits } from '../../domain/models/DatasetUploadLimits'
 import { DatasetReview } from '../../domain/models/DatasetReview'
 import { transformDatasetReviewsResponseToDatasetReviews } from './transformers/datasetReviewTransformers'
 import { ExportedDatasetMetadata } from '../../domain/models/ExportedDatasetMetadata'
+import { DatasetPayload } from './transformers/DatasetPayload'
 
 export interface GetAllDatasetPreviewsQueryParams {
   per_page?: number
@@ -372,6 +375,42 @@ export class DatasetsRepository extends ApiRepository implements IDatasetsReposi
       })
   }
 
+  public async getDatasetVersions(
+    datasetId: string | number,
+    limit?: number,
+    offset?: number,
+    excludeMetadataBlocks?: boolean,
+    keepRawFields?: boolean
+  ): Promise<DatasetVersionSubset> {
+    const queryParams = new URLSearchParams()
+
+    if (limit) {
+      queryParams.set('limit', limit.toString())
+    }
+
+    if (offset) {
+      queryParams.set('offset', offset.toString())
+    }
+
+    if (excludeMetadataBlocks !== undefined) {
+      queryParams.set('excludeMetadataBlocks', excludeMetadataBlocks.toString())
+    }
+
+    return this.doGet(
+      this.buildApiEndpoint(this.datasetsResourceName, 'versions', datasetId),
+      true,
+      queryParams
+    )
+      .then((response) => ({
+        versions: response.data.data.map((x: DatasetPayload) =>
+          transformVersionPayloadToDataset(x, keepRawFields ?? false)
+        )
+      }))
+      .catch((error) => {
+        throw error
+      })
+  }
+
   public async deleteDatasetDraft(datasetId: string | number): Promise<void> {
     return this.doDelete(
       this.buildApiEndpoint(this.datasetsResourceName, 'versions/:draft', datasetId)

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

@@ -254,10 +254,12 @@ export const transformVersionPayloadToDataset = (
         studyCompletion: transformPayloadText(keepRawFields, versionPayload.studyCompletion)
       }
     },
-    metadataBlocks: transformPayloadToDatasetMetadataBlocks(
-      versionPayload.metadataBlocks,
-      keepRawFields
-    ),
+    ...(versionPayload.metadataBlocks && {
+      metadataBlocks: transformPayloadToDatasetMetadataBlocks(
+        versionPayload.metadataBlocks,
+        keepRawFields
+      )
+    }),
     ...(versionPayload.isPartOf && {
       isPartOf: transformPayloadToOwnerNode(versionPayload.isPartOf)
     })