feat: add alreadyLinked parameter to getCollectionsForLinking to get candidates for unlinking

Author: g-saracca

docs/useCases.md

@@ -367,6 +367,19 @@ getCollectionsForLinking
   .catch((error: Error) => {
     /* ... */
   })
+
+// Case 3: [alreadyLinked] Optional flag. When true, returns collections currently linked (candidates to unlink). Defaults to false.
+const alreadyLinked = true
+
+getCollectionsForLinking
+  .execute('dataset', persistentId, searchTerm, alreadyLinked)
+  .then((collections) => {
+    // collections: CollectionSummary[]
+    /* ... */
+  })
+  .catch((error: Error) => {
+    /* ... */
+  })
 ```
 
 _See [use case](../src/collections/domain/useCases/GetCollectionsForLinking.ts) implementation_.

src/collections/domain/repositories/ICollectionsRepository.ts

@@ -65,6 +65,7 @@ export interface ICollectionsRepository {
   getCollectionsForLinking(
     objectType: LinkingObjectType,
     id: number | string,
-    searchTerm: string
+    searchTerm: string,
+    alreadyLinked: boolean
   ): Promise<CollectionSummary[]>
 }

src/collections/domain/useCases/GetCollectionsForLinking.ts

@@ -4,6 +4,9 @@ import { CollectionSummary } from '../models/CollectionSummary'
 
 export type LinkingObjectType = 'collection' | 'dataset'
 
+// TODO:ME - Add to the interface and here the alreadyLinking param to get collections for unlinking
+// @param alreadyLinking - Optional flag. When true, returns collections currently linked (candidates to unlink). Defaults to false.
+
 export class GetCollectionsForLinking implements UseCase<CollectionSummary[]> {
   private collectionsRepository: ICollectionsRepository
 
@@ -16,12 +19,19 @@ export class GetCollectionsForLinking implements UseCase<CollectionSummary[]> {
    * @param objectType - 'dataverse' when providing a collection identifier/alias; 'dataset' when providing a dataset persistentId.
    * @param id - For objectType 'dataverse', a numeric id or alias string. For 'dataset', the persistentId string (e.g., doi:...)
    * @param searchTerm - Optional search term to filter by collection name. Defaults to empty string (no filtering).
+   * @param alreadyLinked - Optional flag. When true, returns collections currently linked (candidates to unlink). Defaults to false.
    */
   async execute(
     objectType: LinkingObjectType,
     id: number | string,
-    searchTerm = ''
+    searchTerm = '',
+    alreadyLinked = false
   ): Promise<CollectionSummary[]> {
-    return await this.collectionsRepository.getCollectionsForLinking(objectType, id, searchTerm)
+    return await this.collectionsRepository.getCollectionsForLinking(
+      objectType,
+      id,
+      searchTerm,
+      alreadyLinked
+    )
   }
 }

src/collections/infra/repositories/CollectionsRepository.ts

@@ -490,7 +490,8 @@ export class CollectionsRepository extends ApiRepository implements ICollections
   public async getCollectionsForLinking(
     objectType: LinkingObjectType,
     id: number | string,
-    searchTerm: string
+    searchTerm: string,
+    alreadyLinked: boolean
   ): Promise<CollectionSummary[]> {
     let path: string
     const queryParams = new URLSearchParams()
@@ -505,6 +506,10 @@ export class CollectionsRepository extends ApiRepository implements ICollections
       queryParams.set('searchTerm', searchTerm)
     }
 
+    if (alreadyLinked) {
+      queryParams.set('alreadyLinking', 'true')
+    }
+
     return this.doGet(path, true, queryParams)
       .then((response) => {
         const payload = response.data.data as {

test/integration/collections/CollectionsRepository.test.ts

@@ -819,7 +819,8 @@ describe('CollectionsRepository', () => {
       const results = await sut.getCollectionsForLinking(
         'collection',
         testCollectionAlias,
-        'Scientific'
+        'Scientific',
+        false
       )
 
       expect(Array.isArray(results)).toBe(true)
@@ -837,7 +838,12 @@ describe('CollectionsRepository', () => {
         testCollectionAlias
       )
 
-      const results = await sut.getCollectionsForLinking('dataset', persistentId, 'Scientific')
+      const results = await sut.getCollectionsForLinking(
+        'dataset',
+        persistentId,
+        'Scientific',
+        false
+      )
 
       // Cleanup dataset (unpublished)
       await deleteUnpublishedDatasetViaApi(numericId)
@@ -848,15 +854,44 @@ describe('CollectionsRepository', () => {
       expect(found?.displayName).toBe('Scientific Research')
     })
 
+    test('should return collections for unlking when sending alreadyLinked param to true', async () => {
+      // Link the test collection with the linking target collection
+      await sut.linkCollection(testCollectionAlias, linkingTargetAlias)
+
+      const collectionsForLinking = await sut.getCollectionsForLinking(
+        'collection',
+        testCollectionAlias,
+        '',
+        false
+      )
+
+      const collectionsForUnlinking = await sut.getCollectionsForLinking(
+        'collection',
+        testCollectionAlias,
+        '',
+        true
+      )
+
+      expect(collectionsForLinking.length).toBe(0)
+      expect(collectionsForUnlinking.length).toBeGreaterThan(0)
+      expect(collectionsForUnlinking[0].alias).toBe(linkingTargetAlias)
+      expect(collectionsForUnlinking[0].displayName).toBe('Scientific Research')
+    })
+
     it('should return error when collection does not exist', async () => {
       await expect(
-        sut.getCollectionsForLinking('collection', TestConstants.TEST_DUMMY_COLLECTION_ALIAS, '')
+        sut.getCollectionsForLinking(
+          'collection',
+          TestConstants.TEST_DUMMY_COLLECTION_ALIAS,
+          '',
+          false
+        )
       ).rejects.toThrow(ReadError)
     })
 
     it('should return error when dataset does not exist', async () => {
       await expect(
-        sut.getCollectionsForLinking('dataset', TestConstants.TEST_DUMMY_PERSISTENT_ID, '')
+        sut.getCollectionsForLinking('dataset', TestConstants.TEST_DUMMY_PERSISTENT_ID, '', false)
       ).rejects.toThrow(ReadError)
     })
   })