Merge pull request #316 from IQSS/feat/315-featured-items-dvobjects-extension

Featured Items Use Cases dvObjects extension

Author: ofahimIQSS

docs/useCases.md

@@ -23,6 +23,7 @@ The different use cases currently available in the package are classified below,
     - [Delete a Collection](#delete-a-collection)
     - [Update Collection Featured Items](#update-collection-featured-items)
     - [Delete Collection Featured Items](#delete-collection-featured-items)
+    - [Delete a Collection Featured Item](#delete-a-collection-featured-item)
 - [Datasets](#Datasets)
   - [Datasets read use cases](#datasets-read-use-cases)
     - [Get a Dataset](#get-a-dataset)
@@ -277,7 +278,7 @@ The `CollectionItemSubset`returned instance contains a property called `totalIte
 
 #### Get Collection Featured Items
 
-Returns a [CollectionFeaturedItem](../src/collections/domain/models/CollectionFeaturedItem.ts) array containing the featured items of the requested collection, given the collection identifier or alias.
+Returns a [FeaturedItem](../src/collections/domain/models/CollectionFeaturedItem.ts) array containing the featured items of the requested collection, given the collection identifier or alias.
 
 ##### Example call:
 
@@ -288,7 +289,7 @@ const collectionIdOrAlias = 12345
 
 getCollectionFeaturedItems
   .execute(collectionId)
-  .then((featuredItems: CollectionFeaturedItem[]) => {
+  .then((featuredItems: FeaturedItem[]) => {
     /* ... */
   })
   .catch((error: Error) => {
@@ -405,7 +406,7 @@ _See [use case](../src/collections/domain/useCases/DeleteCollection.ts)_ definit
 
 #### Update Collection Featured Items
 
-Updates all featured items, given a collection identifier and a CollectionFeaturedItemsDTO.
+Updates all featured items, given a collection identifier and a FeaturedItemsDTO.
 
 ##### Example call:
 
@@ -416,11 +417,9 @@ import { updateCollectionFeaturedItems } from '@iqss/dataverse-client-javascript
 
 const collectionIdOrAlias = 12345
 
-updateCollectionFeaturedItems
-  .execute(collectionIdOrAlias)
-  .then((collectionFeaturedItems: CollectionFeaturedItem[]) => {
-    /* ... */
-  })
+updateCollectionFeaturedItems.execute(collectionIdOrAlias).then((featuredItems: FeaturedItem[]) => {
+  /* ... */
+})
 
 /* ... */
 ```
@@ -451,6 +450,26 @@ The `collectionIdOrAlias` is a generic collection identifier, which can be eithe
 
 _See [use case](../src/collections/domain/useCases/DeleteCollectionFeaturedItems.ts)_ definition.
 
+#### Delete A Collection Featured Item
+
+Deletes a single featured item, given a featured item id.
+
+##### Example call:
+
+```typescript
+import { deleteCollectionFeaturedItem } from '@iqss/dataverse-client-javascript'
+
+/* ... */
+
+const featuredItemId = 12345
+
+deleteCollectionFeaturedItem.execute(featuredItemId)
+
+/* ... */
+```
+
+_See [use case](../src/collections/domain/useCases/DeleteCollectionFeaturedItem.ts)_ definition.
+
 ## Datasets
 
 ### Datasets Read Use Cases

src/collections/domain/dtos/CollectionFeaturedItemsDTO.ts

@@ -0,0 +1,19 @@
+import { CustomFeaturedItem, DvObjectFeaturedItem } from '../models/FeaturedItem'
+
+export type FeaturedItemsDTO = (CustomFeaturedItemDTO | DvObjectFeaturedItemDTO)[]
+
+export interface CustomFeaturedItemDTO {
+  id?: number
+  type: CustomFeaturedItem['type']
+  content: string
+  displayOrder: number
+  file?: File
+  keepFile: boolean
+}
+
+export interface DvObjectFeaturedItemDTO {
+  id?: number
+  type: DvObjectFeaturedItem['type']
+  dvObjectIdentifier: string
+  displayOrder: number
+}

src/collections/domain/dtos/FeaturedItemsDTO.ts

@@ -0,0 +1,25 @@
+export type FeaturedItem = CustomFeaturedItem | DvObjectFeaturedItem
+
+export interface CustomFeaturedItem {
+  id: number
+  type: FeaturedItemType.CUSTOM
+  content: string
+  imageFileName?: string
+  imageFileUrl?: string
+  displayOrder: number
+}
+
+export interface DvObjectFeaturedItem {
+  id: number
+  type: FeaturedItemType.COLLECTION | FeaturedItemType.DATASET | FeaturedItemType.FILE
+  dvObjectIdentifier: string
+  dvObjectDisplayName: string
+  displayOrder: number
+}
+
+export enum FeaturedItemType {
+  CUSTOM = 'custom',
+  COLLECTION = 'collection',
+  DATASET = 'dataset',
+  FILE = 'file'
+}

src/collections/domain/models/CollectionFeaturedItem.ts

@@ -1,8 +1,8 @@
 import { CollectionDTO } from '../dtos/CollectionDTO'
-import { CollectionFeaturedItemsDTO } from '../dtos/CollectionFeaturedItemsDTO'
+import { FeaturedItemsDTO } from '../dtos/FeaturedItemsDTO'
 import { Collection } from '../models/Collection'
 import { CollectionFacet } from '../models/CollectionFacet'
-import { CollectionFeaturedItem } from '../models/CollectionFeaturedItem'
+import { FeaturedItem } from '../models/FeaturedItem'
 import { CollectionItemSubset } from '../models/CollectionItemSubset'
 import { MyDataCollectionItemSubset } from '../models/MyDataCollectionItemSubset'
 import { CollectionSearchCriteria } from '../models/CollectionSearchCriteria'
@@ -42,12 +42,11 @@ export interface ICollectionsRepository {
     collectionIdOrAlias: number | string,
     updatedCollection: CollectionDTO
   ): Promise<void>
-  getCollectionFeaturedItems(
-    collectionIdOrAlias: number | string
-  ): Promise<CollectionFeaturedItem[]>
+  getCollectionFeaturedItems(collectionIdOrAlias: number | string): Promise<FeaturedItem[]>
   updateCollectionFeaturedItems(
     collectionIdOrAlias: number | string,
-    featuredItemDTOs: CollectionFeaturedItemsDTO
-  ): Promise<CollectionFeaturedItem[]>
+    featuredItemDTOs: FeaturedItemsDTO
+  ): Promise<FeaturedItem[]>
   deleteCollectionFeaturedItems(collectionIdOrAlias: number | string): Promise<void>
+  deleteCollectionFeaturedItem(featuredItemId: number): Promise<void>
 }

src/collections/domain/models/FeaturedItem.ts

@@ -0,0 +1,21 @@
+import { UseCase } from '../../../core/domain/useCases/UseCase'
+import { ICollectionsRepository } from '../repositories/ICollectionsRepository'
+
+export class DeleteCollectionFeaturedItem implements UseCase<void> {
+  private collectionsRepository: ICollectionsRepository
+
+  constructor(collectionsRepository: ICollectionsRepository) {
+    this.collectionsRepository = collectionsRepository
+  }
+
+  /**
+   * Deletes a single featured item, given a featured item id.
+   *
+   * @param {number} [featuredItemId] - The id of the featured item to delete.
+   * @returns {Promise<void>} - This method does not return anything upon successful completion.
+   * @throws {WriteError} - If there are errors while writing data.
+   */
+  async execute(featuredItemId: number): Promise<void> {
+    return await this.collectionsRepository.deleteCollectionFeaturedItem(featuredItemId)
+  }
+}

src/collections/domain/repositories/ICollectionsRepository.ts

@@ -1,25 +1,25 @@
 import { UseCase } from '../../../core/domain/useCases/UseCase'
 import { ICollectionsRepository } from '../repositories/ICollectionsRepository'
 import { ROOT_COLLECTION_ID } from '../models/Collection'
-import { CollectionFeaturedItem } from '../models/CollectionFeaturedItem'
+import { FeaturedItem } from '../models/FeaturedItem'
 
-export class GetCollectionFeaturedItems implements UseCase<CollectionFeaturedItem[]> {
+export class GetCollectionFeaturedItems implements UseCase<FeaturedItem[]> {
   private collectionsRepository: ICollectionsRepository
 
   constructor(collectionsRepository: ICollectionsRepository) {
     this.collectionsRepository = collectionsRepository
   }
 
   /**
-   * Returns a CollectionFeaturedItem array containing the featured items of the requested collection, given the collection identifier or alias.
+   * Returns a FeaturedItem array containing the featured items of the requested collection, given the collection identifier or alias.
    *
    * @param {number | string} [collectionIdOrAlias = ':root'] - A generic collection identifier, which can be either a string (for queries by CollectionAlias), or a number (for queries by CollectionId)
    * If this parameter is not set, the default value is: ':root'
-   * @returns {Promise<CollectionFeaturedItem[]>}
+   * @returns {Promise<FeaturedItem[]>}
    */
   async execute(
     collectionIdOrAlias: number | string = ROOT_COLLECTION_ID
-  ): Promise<CollectionFeaturedItem[]> {
+  ): Promise<FeaturedItem[]> {
     return await this.collectionsRepository.getCollectionFeaturedItems(collectionIdOrAlias)
   }
 }

src/collections/domain/useCases/DeleteCollectionFeaturedItem.ts

@@ -1,29 +1,29 @@
 import { UseCase } from '../../../core/domain/useCases/UseCase'
-import { CollectionFeaturedItemsDTO } from '../dtos/CollectionFeaturedItemsDTO'
+import { FeaturedItemsDTO } from '../dtos/FeaturedItemsDTO'
 import { ROOT_COLLECTION_ID } from '../models/Collection'
-import { CollectionFeaturedItem } from '../models/CollectionFeaturedItem'
+import { FeaturedItem } from '../models/FeaturedItem'
 import { ICollectionsRepository } from '../repositories/ICollectionsRepository'
 
-export class UpdateCollectionFeaturedItems implements UseCase<CollectionFeaturedItem[]> {
+export class UpdateCollectionFeaturedItems implements UseCase<FeaturedItem[]> {
   private collectionsRepository: ICollectionsRepository
 
   constructor(collectionsRepository: ICollectionsRepository) {
     this.collectionsRepository = collectionsRepository
   }
 
   /**
-   * Updates all featured items, given a collection identifier and a CollectionFeaturedItemsDTO.
+   * Updates all featured items, given a collection identifier and a FeaturedItemsDTO.
    *
    * @param {number | string} [collectionIdOrAlias = ':root'] - A generic collection identifier, which can be either a string (for queries by CollectionAlias), or a number (for queries by CollectionId)
    * If this parameter is not set, the default value is: ':root'
-   * @param {CollectionFeaturedItemsDTO} [newCollectionFeaturedItems] - CollectionFeaturedItemsDTO object including the updated collection featured items data.
-   * @returns {Promise<CollectionFeaturedItem[]>} -This method returns the updated collection featured items upon successful completion.
+   * @param {FeaturedItemsDTO} [featuredItemsDTO] - FeaturedItemsDTO object including the updated collection featured items data.
+   * @returns {Promise<FeaturedItem[]>} -This method returns the updated collection featured items upon successful completion.
    * @throws {WriteError} - If there are errors while writing data.
    */
   async execute(
     collectionIdOrAlias: number | string = ROOT_COLLECTION_ID,
-    featuredItemsDTO: CollectionFeaturedItemsDTO
-  ): Promise<CollectionFeaturedItem[]> {
+    featuredItemsDTO: FeaturedItemsDTO
+  ): Promise<FeaturedItem[]> {
     return await this.collectionsRepository.updateCollectionFeaturedItems(
       collectionIdOrAlias,
       featuredItemsDTO

src/collections/domain/useCases/GetCollectionFeaturedItems.ts

@@ -11,6 +11,7 @@ import { UpdateCollectionFeaturedItems } from './domain/useCases/UpdateCollectio
 import { DeleteCollectionFeaturedItems } from './domain/useCases/DeleteCollectionFeaturedItems'
 import { DeleteCollection } from './domain/useCases/DeleteCollection'
 import { GetMyDataCollectionItems } from './domain/useCases/GetMyDataCollectionItems'
+import { DeleteCollectionFeaturedItem } from './domain/useCases/DeleteCollectionFeaturedItem'
 
 const collectionsRepository = new CollectionsRepository()
 
@@ -26,6 +27,7 @@ const getCollectionFeaturedItems = new GetCollectionFeaturedItems(collectionsRep
 const updateCollectionFeaturedItems = new UpdateCollectionFeaturedItems(collectionsRepository)
 const deleteCollectionFeaturedItems = new DeleteCollectionFeaturedItems(collectionsRepository)
 const deleteCollection = new DeleteCollection(collectionsRepository)
+const deleteCollectionFeaturedItem = new DeleteCollectionFeaturedItem(collectionsRepository)
 
 export {
   getCollection,
@@ -39,7 +41,8 @@ export {
   getCollectionFeaturedItems,
   updateCollectionFeaturedItems,
   deleteCollectionFeaturedItems,
-  deleteCollection
+  deleteCollection,
+  deleteCollectionFeaturedItem
 }
 export { Collection, CollectionInputLevel } from './domain/models/Collection'
 export { CollectionFacet } from './domain/models/CollectionFacet'
@@ -48,5 +51,5 @@ export { CollectionDTO, CollectionInputLevelDTO } from './domain/dtos/Collection
 export { CollectionPreview } from './domain/models/CollectionPreview'
 export { CollectionItemType } from './domain/models/CollectionItemType'
 export { CollectionSearchCriteria } from './domain/models/CollectionSearchCriteria'
-export { CollectionFeaturedItem } from './domain/models/CollectionFeaturedItem'
-export { CollectionFeaturedItemsDTO } from './domain/dtos/CollectionFeaturedItemsDTO'
+export { FeaturedItem } from './domain/models/FeaturedItem'
+export { FeaturedItemsDTO } from './domain/dtos/FeaturedItemsDTO'