Merge pull request #395 from IQSS/394-add-pagination-query-parameters-to-datasetfile-version-summaries-use-case

ofahimIQSS · web-flow · commit 421af81099cd · 2025-10-31T15:10:18.000-04:00
Add pagination query parameters to Dataset&amp;File Version Summaries use case
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -13,6 +13,8 @@ This changelog follows the principles of [Keep a Changelog](https://keepachangel
 
 ### Changed
 
+- Add pagination query parameters to Dataset Version Summeries and File Version Summaries use cases
+
 ### Fixed
 
 ### Removed
diff --git a/docs/useCases.md b/docs/useCases.md
@@ -872,7 +872,7 @@ The `DatasetPreviewSubset`returned instance contains a property called `totalDat
 
 #### 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.
+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.
 
 ##### Example call:
 
@@ -885,7 +885,7 @@ const datasetId = 'doi:10.77777/FK2/AAAAAA'
 
 getDatasetVersionsSummaries
   .execute(datasetId)
-  .then((datasetVersionsSummaries: DatasetVersionSummaryInfo[]) => {
+  .then((datasetVersionsSummaries: DatasetVersionSummarySubset) => {
     /* ... */
   })
 
@@ -894,7 +894,9 @@ getDatasetVersionsSummaries
 
 _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.
+- 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.
 
 #### Get Dataset Linked Collections
 
@@ -2000,7 +2002,7 @@ The `fileId` parameter can be a string, for persistent identifiers, or a number,
 
 #### Get File Version Summaries
 
-Get the file versions summaries, return a list of summaries for each version
+Get the file versions summaries, return a total count of versions and a list of summaries for each version
 
 ##### Example call:
 
@@ -2011,7 +2013,7 @@ import { getFileVersionSummaries } from '@iqss/dataverse-client-javascript'
 
 const fileId = 1
 
-getFileVersionSummaries.execute(fileId).then((fileVersionSummaries: fileVersionSummaryInfo[]) => {
+getFileVersionSummaries.execute(fileId).then((fileVersionSummaries: fileVersionSummarySubset) => {
   /* ... */
 })
 
@@ -2020,6 +2022,9 @@ getFileVersionSummaries.execute(fileId).then((fileVersionSummaries: fileVersionS
 
 _See [use case](../src/files/domain/useCases/GetFileVersionSummaries.ts) implementation_.
 
+- **limit**: (number) Limit for pagination.
+- **offset**: (number) Offset for pagination.
+
 ## Metadata Blocks
 
 ### Metadata Blocks read use cases
diff --git a/src/datasets/domain/models/DatasetVersionSummaryInfo.ts b/src/datasets/domain/models/DatasetVersionSummaryInfo.ts
@@ -6,6 +6,11 @@ export interface DatasetVersionSummaryInfo {
   publishedOn?: string
 }
 
+export interface DatasetVersionSummarySubset {
+  summaries: DatasetVersionSummaryInfo[]
+  totalCount: number
+}
+
 export type DatasetVersionSummary = {
   [key: string]:
     | SummaryUpdates
diff --git a/src/datasets/domain/repositories/IDatasetsRepository.ts b/src/datasets/domain/repositories/IDatasetsRepository.ts
@@ -8,7 +8,7 @@ import { DatasetDeaccessionDTO } from '../dtos/DatasetDeaccessionDTO'
 import { MetadataBlock } from '../../../metadataBlocks'
 import { DatasetVersionDiff } from '../models/DatasetVersionDiff'
 import { DatasetDownloadCount } from '../models/DatasetDownloadCount'
-import { DatasetVersionSummaryInfo } from '../models/DatasetVersionSummaryInfo'
+import { DatasetVersionSummarySubset } from '../models/DatasetVersionSummaryInfo'
 import { DatasetLinkedCollection } from '../models/DatasetLinkedCollection'
 import { CitationFormat } from '../models/CitationFormat'
 import { FormattedCitation } from '../models/FormattedCitation'
@@ -66,7 +66,11 @@ export interface IDatasetsRepository {
     datasetId: number | string,
     includeMDC?: boolean
   ): Promise<DatasetDownloadCount>
-  getDatasetVersionsSummaries(datasetId: number | string): Promise<DatasetVersionSummaryInfo[]>
+  getDatasetVersionsSummaries(
+    datasetId: number | string,
+    limit?: number,
+    offset?: number
+  ): Promise<DatasetVersionSummarySubset>
   deleteDatasetDraft(datasetId: number | string): Promise<void>
   linkDataset(datasetId: number | string, collectionIdOrAlias: number | string): Promise<void>
   unlinkDataset(datasetId: number | string, collectionIdOrAlias: number | string): Promise<void>
diff --git a/src/datasets/domain/useCases/GetDatasetVersionsSummaries.ts b/src/datasets/domain/useCases/GetDatasetVersionsSummaries.ts
@@ -1,8 +1,8 @@
 import { UseCase } from '../../../core/domain/useCases/UseCase'
-import { DatasetVersionSummaryInfo } from '../models/DatasetVersionSummaryInfo'
+import { DatasetVersionSummarySubset } from '../models/DatasetVersionSummaryInfo'
 import { IDatasetsRepository } from '../repositories/IDatasetsRepository'
 
-export class GetDatasetVersionsSummaries implements UseCase<DatasetVersionSummaryInfo[]> {
+export class GetDatasetVersionsSummaries implements UseCase<DatasetVersionSummarySubset> {
   private datasetsRepository: IDatasetsRepository
 
   constructor(datasetsRepository: IDatasetsRepository) {
@@ -14,9 +14,15 @@ export class GetDatasetVersionsSummaries implements UseCase<DatasetVersionSummar
    * 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.
+   * @param {number} [limit] - Limit for pagination (optional).
+   * @param {number} [offset] - Offset for pagination (optional).
+   * @returns {Promise<DatasetVersionSummarySubset>} - A DatasetVersionSummarySubset containing the summaries and total count.
    */
-  async execute(datasetId: number | string): Promise<DatasetVersionSummaryInfo[]> {
-    return await this.datasetsRepository.getDatasetVersionsSummaries(datasetId)
+  async execute(
+    datasetId: number | string,
+    limit?: number,
+    offset?: number
+  ): Promise<DatasetVersionSummarySubset> {
+    return await this.datasetsRepository.getDatasetVersionsSummaries(datasetId, limit, offset)
   }
 }
diff --git a/src/datasets/index.ts b/src/datasets/index.ts
@@ -141,7 +141,8 @@ export { CreatedDatasetIdentifiers } from './domain/models/CreatedDatasetIdentif
 export { VersionUpdateType } from './domain/models/Dataset'
 export {
   DatasetVersionSummaryInfo,
-  DatasetVersionSummaryStringValues
+  DatasetVersionSummaryStringValues,
+  DatasetVersionSummarySubset
 } from './domain/models/DatasetVersionSummaryInfo'
 export { DatasetLinkedCollection } from './domain/models/DatasetLinkedCollection'
 export { DatasetType } from './domain/models/DatasetType'
diff --git a/src/datasets/infra/repositories/DatasetsRepository.ts b/src/datasets/infra/repositories/DatasetsRepository.ts
@@ -20,7 +20,7 @@ import { transformDatasetPreviewsResponseToDatasetPreviewSubset } from './transf
 import { DatasetVersionDiff } from '../../domain/models/DatasetVersionDiff'
 import { transformDatasetVersionDiffResponseToDatasetVersionDiff } from './transformers/datasetVersionDiffTransformers'
 import { DatasetDownloadCount } from '../../domain/models/DatasetDownloadCount'
-import { DatasetVersionSummaryInfo } from '../../domain/models/DatasetVersionSummaryInfo'
+import { DatasetVersionSummarySubset } from '../../domain/models/DatasetVersionSummaryInfo'
 import { DatasetLinkedCollection } from '../../domain/models/DatasetLinkedCollection'
 import { CitationFormat } from '../../domain/models/CitationFormat'
 import { transformDatasetLinkedCollectionsResponseToDatasetLinkedCollection } from './transformers/datasetLinkedCollectionsTransformers'
@@ -306,13 +306,29 @@ export class DatasetsRepository extends ApiRepository implements IDatasetsReposi
   }
 
   public async getDatasetVersionsSummaries(
-    datasetId: string | number
-  ): Promise<DatasetVersionSummaryInfo[]> {
+    datasetId: string | number,
+    limit?: number,
+    offset?: number
+  ): Promise<DatasetVersionSummarySubset> {
+    const queryParams = new URLSearchParams()
+
+    if (limit) {
+      queryParams.set('limit', limit.toString())
+    }
+
+    if (offset) {
+      queryParams.set('offset', offset.toString())
+    }
+
     return this.doGet(
       this.buildApiEndpoint(this.datasetsResourceName, 'versions/compareSummary', datasetId),
-      true
+      true,
+      queryParams
     )
-      .then((response) => response.data.data)
+      .then((response) => ({
+        summaries: response.data.data,
+        totalCount: response.data.totalCount
+      }))
       .catch((error) => {
         throw error
       })
diff --git a/src/files/domain/models/FileVersionSummaryInfo.ts b/src/files/domain/models/FileVersionSummaryInfo.ts
@@ -11,6 +11,11 @@ export interface FileVersionSummaryInfo {
   versionNote?: string
 }
 
+export interface FileVersionSummarySubset {
+  summaries: FileVersionSummaryInfo[]
+  totalCount: number
+}
+
 export type FileDifferenceSummary = {
   file?: FileChangeType
   fileAccess?: 'Restricted' | 'Unrestricted'
diff --git a/src/files/domain/repositories/IFilesRepository.ts b/src/files/domain/repositories/IFilesRepository.ts
@@ -10,7 +10,7 @@ import { FileUploadDestination } from '../models/FileUploadDestination'
 import { UploadedFileDTO } from '../dtos/UploadedFileDTO'
 import { UpdateFileMetadataDTO } from '../dtos/UpdateFileMetadataDTO'
 import { RestrictFileDTO } from '../dtos/RestrictFileDTO'
-import { FileVersionSummaryInfo } from '../models/FileVersionSummaryInfo'
+import { FileVersionSummarySubset } from '../models/FileVersionSummaryInfo'
 
 export interface IFilesRepository {
   getDatasetFiles(
@@ -88,7 +88,11 @@ export interface IFilesRepository {
     replace?: boolean
   ): Promise<void>
 
-  getFileVersionSummaries(fileId: number | string): Promise<FileVersionSummaryInfo[]>
+  getFileVersionSummaries(
+    fileId: number | string,
+    limit?: number,
+    offset?: number
+  ): Promise<FileVersionSummarySubset>
 
   isFileDeleted(fileId: number | string): Promise<boolean>
 }
diff --git a/src/files/domain/useCases/GetFileVersionSummaries.ts b/src/files/domain/useCases/GetFileVersionSummaries.ts
@@ -1,8 +1,8 @@
 import { UseCase } from '../../../core/domain/useCases/UseCase'
-import { FileVersionSummaryInfo } from '../models/FileVersionSummaryInfo'
+import { FileVersionSummarySubset } from '../models/FileVersionSummaryInfo'
 import { IFilesRepository } from '../repositories/IFilesRepository'
 
-export class GetFileVersionSummaries implements UseCase<FileVersionSummaryInfo[]> {
+export class GetFileVersionSummaries implements UseCase<FileVersionSummarySubset> {
   private filesRepository: IFilesRepository
 
   constructor(filesRepository: IFilesRepository) {
@@ -13,9 +13,15 @@ export class GetFileVersionSummaries implements UseCase<FileVersionSummaryInfo[]
    * Returns a list of versions for a given file including a summary of differences between consecutive versions
    *
    * @param {number | string} [fileId] - The file identifier, which can be a string (for persistent identifiers), or a number (for numeric identifiers).
-   * @returns {Promise<FileVersionSummaryInfo[]>} - An array of FileVersionSummaryInfo.
+   * @param {number} [limit] - Limit for pagination (optional).
+   * @param {number} [offset] - Offset for pagination (optional).
+   * @returns {Promise<FileVersionSummarySubset>} - A FileVersionSummarySubset containing the summaries and total count.
    */
-  async execute(fileId: number | string): Promise<FileVersionSummaryInfo[]> {
-    return await this.filesRepository.getFileVersionSummaries(fileId)
+  async execute(
+    fileId: number | string,
+    limit?: number,
+    offset?: number
+  ): Promise<FileVersionSummarySubset> {
+    return await this.filesRepository.getFileVersionSummaries(fileId, limit, offset)
   }
 }
diff --git a/src/files/index.ts b/src/files/index.ts
@@ -93,3 +93,10 @@ export { FilesSubset } from './domain/models/FilesSubset'
 export { FilePreview, FilePreviewChecksum } from './domain/models/FilePreview'
 export { UploadedFileDTO } from './domain/dtos/UploadedFileDTO'
 export { UpdateFileMetadataDTO } from './domain/dtos/UpdateFileMetadataDTO'
+export {
+  FileVersionSummaryInfo,
+  FileDifferenceSummary,
+  FileChangeType,
+  FileMetadataChange,
+  FileVersionSummarySubset
+} from './domain/models/FileVersionSummaryInfo'
diff --git a/src/files/infra/repositories/FilesRepository.ts b/src/files/infra/repositories/FilesRepository.ts
@@ -22,7 +22,7 @@ import { UploadedFileDTO } from '../../domain/dtos/UploadedFileDTO'
 import { UpdateFileMetadataDTO } from '../../domain/dtos/UpdateFileMetadataDTO'
 import { ApiConstants } from '../../../core/infra/repositories/ApiConstants'
 import { RestrictFileDTO } from '../../domain/dtos/RestrictFileDTO'
-import { FileVersionSummaryInfo } from '../../domain/models/FileVersionSummaryInfo'
+import { FileVersionSummarySubset } from '../../domain/models/FileVersionSummaryInfo'
 import { transformFileVersionSummaryInfoResponseToFileVersionSummaryInfo } from './transformers/fileVersionSummaryInfoTransformers'
 
 export interface GetFilesQueryParams {
@@ -423,10 +423,25 @@ export class FilesRepository extends ApiRepository implements IFilesRepository {
       })
   }
 
-  public async getFileVersionSummaries(fileId: number | string): Promise<FileVersionSummaryInfo[]> {
+  public async getFileVersionSummaries(
+    fileId: number | string,
+    limit?: number,
+    offset?: number
+  ): Promise<FileVersionSummarySubset> {
+    const queryParams = new URLSearchParams()
+
+    if (limit) {
+      queryParams.set('limit', limit.toString())
+    }
+
+    if (offset) {
+      queryParams.set('offset', offset.toString())
+    }
+
     return this.doGet(
       this.buildApiEndpoint(this.filesResourceName, 'versionDifferences', fileId),
-      true
+      true,
+      queryParams
     )
       .then((response) => transformFileVersionSummaryInfoResponseToFileVersionSummaryInfo(response))
       .catch((error) => {
diff --git a/src/files/infra/repositories/transformers/fileVersionSummaryInfoTransformers.ts b/src/files/infra/repositories/transformers/fileVersionSummaryInfoTransformers.ts
@@ -2,7 +2,8 @@ import { AxiosResponse } from 'axios'
 import {
   FileVersionSummaryInfo,
   FileMetadataChange,
-  FileDifferenceSummary
+  FileDifferenceSummary,
+  FileVersionSummarySubset
 } from '../../../domain/models/FileVersionSummaryInfo'
 import { DatasetVersionState } from '../../../../datasets/domain/models/Dataset'
 
@@ -29,10 +30,11 @@ export interface FileVersionSummaryInfoPayload {
 
 export const transformFileVersionSummaryInfoResponseToFileVersionSummaryInfo = (
   response: AxiosResponse
-): FileVersionSummaryInfo[] => {
+): FileVersionSummarySubset => {
   const payload = response.data.data
+  const totalCount = response.data.totalCount
 
-  return payload.map((item: FileVersionSummaryInfoPayload): FileVersionSummaryInfo => {
+  const summaries = payload.map((item: FileVersionSummaryInfoPayload): FileVersionSummaryInfo => {
     const summary = item.fileDifferenceSummary || {}
 
     const fileDifferenceSummary: FileDifferenceSummary = {
@@ -54,4 +56,9 @@ export const transformFileVersionSummaryInfoResponseToFileVersionSummaryInfo = (
       versionNote: item.versionNote
     }
   })
+
+  return {
+    summaries,
+    totalCount
+  }
 }
diff --git a/test/integration/datasets/DatasetsRepository.test.ts b/test/integration/datasets/DatasetsRepository.test.ts
diff --git a/test/integration/files/FilesRepository.test.ts b/test/integration/files/FilesRepository.test.ts
diff --git a/test/integration/notifications/NotificationsRepository.test.ts b/test/integration/notifications/NotificationsRepository.test.ts
diff --git a/test/unit/datasets/DatasetsRepository.test.ts b/test/unit/datasets/DatasetsRepository.test.ts
diff --git a/test/unit/datasets/GetDatasetVersionsSummaries.test.ts b/test/unit/datasets/GetDatasetVersionsSummaries.test.ts
diff --git a/test/unit/files/GetFileVersionSummaries.test.ts b/test/unit/files/GetFileVersionSummaries.test.ts
