Merge branch 'develop' of https://github.com/IQSS/dataverse-client-javascript into feature/133-add-publish-dataset-use-case

Author: MellyGray

.gitignore

@@ -8,4 +8,5 @@ node_modules
 coverage
 
 # ignore npm lock
-package-json.lock
+package-json.lock
+.npmrc

docs/useCases.md

@@ -8,6 +8,9 @@ The different use cases currently available in the package are classified below,
 
 ## Table of Contents
 
+- [Collections](#Collections)
+  - [Collections read use cases](#collections-read-use-cases)
+    - [Get a Collection](#get-a-collection)
 - [Datasets](#Datasets)
   - [Datasets read use cases](#datasets-read-use-cases)
     - [Get a Dataset](#get-a-dataset)
@@ -43,6 +46,54 @@ The different use cases currently available in the package are classified below,
   - [Get Maximum Embargo Duration In Months](#get-maximum-embargo-duration-in-months)
   - [Get ZIP Download Limit](#get-zip-download-limit)
 
+## Collections
+
+### Collections Read Use Cases
+
+#### Get a Collection
+
+Returns a [Collection](../src/collections/domain/models/Collection.ts) instance, given the search parameters to identify it.
+
+##### Example call:
+
+```typescript
+import { getCollection } from '@iqss/dataverse-client-javascript'
+
+/* ... */
+// Case 1: Fetch Collection by its numerical ID
+const collectionIdOrAlias = 12345
+
+getCollection
+  .execute(collectionId)
+  .then((collection: Collection) => {
+    /* ... */
+  })
+  .catch((error: Error) => {
+    /* ... */
+  })
+
+/* ... */
+
+// Case 2: Fetch Collection by its alias
+const collectionIdOrAlias = 'classicLiterature'
+getCollection
+  .execute(collectionAlias)
+  .then((collection: Collection) => {
+    /* ... */
+  })
+  .catch((error: Error) => {
+    /* ... */
+  })
+
+/* ... */
+```
+
+_See [use case](../src/collections/domain/useCases/GetCollection.ts)_ definition.
+
+The `collectionIdOrAlias` is a generic collection identifier, which can be either a string (for queries by CollectionAlias), or a number (for queries by CollectionId).
+
+If no collection identifier is specified, the default collection identifier; `root` will be used. If you want to search for a different collection, you must add the collection identifier as a parameter in the use case call.
+
 ## Datasets
 
 ### Datasets Read Use Cases

src/collections/domain/models/Collection.ts

@@ -0,0 +1,11 @@
+import { DvObjectOwnerNode } from '../../../core'
+export interface Collection {
+  id: number
+  alias: string
+  name: string
+  affiliation?: string
+  description?: string
+  isPartOf: DvObjectOwnerNode
+}
+
+export const ROOT_COLLECTION_ALIAS = 'root'

src/collections/domain/repositories/ICollectionsRepository.ts

@@ -0,0 +1,4 @@
+import { Collection } from '../models/Collection'
+export interface ICollectionsRepository {
+  getCollection(collectionIdOrAlias: number | string): Promise<Collection>
+}

src/collections/domain/useCases/GetCollection.ts

@@ -0,0 +1,22 @@
+import { UseCase } from '../../../core/domain/useCases/UseCase'
+import { ICollectionsRepository } from '../repositories/ICollectionsRepository'
+import { Collection, ROOT_COLLECTION_ALIAS } from '../models/Collection'
+
+export class GetCollection implements UseCase<Collection> {
+  private collectionsRepository: ICollectionsRepository
+
+  constructor(collectionsRepository: ICollectionsRepository) {
+    this.collectionsRepository = collectionsRepository
+  }
+
+  /**
+   * Returns a Collection instance, given the search parameters to identify it.
+   *
+   * @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<Collection>}
+   */
+  async execute(collectionIdOrAlias: number | string = ROOT_COLLECTION_ALIAS): Promise<Collection> {
+    return await this.collectionsRepository.getCollection(collectionIdOrAlias)
+  }
+}

src/collections/index.ts

@@ -0,0 +1,10 @@
+import { GetCollection } from './domain/useCases/GetCollection'
+
+import { CollectionsRepository } from './infra/repositories/CollectionsRepository'
+
+const collectionsRepository = new CollectionsRepository()
+
+const getCollection = new GetCollection(collectionsRepository)
+
+export { getCollection }
+export { Collection } from './domain/models/Collection'

src/collections/infra/repositories/CollectionsRepository.ts

@@ -0,0 +1,26 @@
+import { ApiRepository } from '../../../core/infra/repositories/ApiRepository'
+import { ICollectionsRepository } from '../../domain/repositories/ICollectionsRepository'
+import { transformCollectionResponseToCollection } from './transformers/collectionTransformers'
+import { Collection, ROOT_COLLECTION_ALIAS } from '../../domain/models/Collection'
+export class CollectionsRepository extends ApiRepository implements ICollectionsRepository {
+  private readonly collectionsResourceName: string = 'dataverses'
+  private readonly collectionsDefaultOperationType: string = 'get'
+
+  public async getCollection(
+    collectionIdOrAlias: number | string = ROOT_COLLECTION_ALIAS
+  ): Promise<Collection> {
+    return this.doGet(
+      this.buildApiEndpoint(
+        this.collectionsResourceName,
+        this.collectionsDefaultOperationType,
+        collectionIdOrAlias
+      ),
+      true,
+      { returnOwners: true }
+    )
+      .then((response) => transformCollectionResponseToCollection(response))
+      .catch((error) => {
+        throw error
+      })
+  }
+}

src/collections/infra/repositories/transformers/CollectionPayload.ts

@@ -0,0 +1,9 @@
+import { OwnerNodePayload } from '../../../../core/infra/repositories/transformers/OwnerNodePayload'
+export interface CollectionPayload {
+  id: number
+  alias: string
+  name: string
+  affiliation?: string
+  description?: string
+  isPartOf: OwnerNodePayload
+}

src/collections/infra/repositories/transformers/collectionTransformers.ts

@@ -0,0 +1,23 @@
+import { Collection } from '../../../domain/models/Collection'
+import { AxiosResponse } from 'axios'
+import { CollectionPayload } from './CollectionPayload'
+import { transformPayloadToOwnerNode } from '../../../../core/infra/repositories/transformers/dvObjectOwnerNodeTransformer'
+
+export const transformCollectionResponseToCollection = (response: AxiosResponse): Collection => {
+  const collectionPayload = response.data.data
+  return transformPayloadToCollection(collectionPayload)
+}
+
+const transformPayloadToCollection = (collectionPayload: CollectionPayload): Collection => {
+  const collectionModel: Collection = {
+    id: collectionPayload.id,
+    alias: collectionPayload.alias,
+    name: collectionPayload.name,
+    affiliation: collectionPayload.affiliation,
+    description: collectionPayload.description,
+    ...(collectionPayload.isPartOf && {
+      isPartOf: transformPayloadToOwnerNode(collectionPayload.isPartOf)
+    })
+  }
+  return collectionModel
+}

src/core/infra/repositories/ApiRepository.ts

@@ -39,15 +39,15 @@ export abstract class ApiRepository {
     operation: string,
     resourceId: number | string = undefined
   ) {
-    let endpoint
-    if (typeof resourceId === 'number') {
-      endpoint = `/${resourceName}/${resourceId}/${operation}`
-    } else if (typeof resourceId === 'string') {
-      endpoint = `/${resourceName}/:persistentId/${operation}?persistentId=${resourceId}`
-    } else {
-      endpoint = `/${resourceName}/${operation}`
+    if (resourceName === 'dataverses') {
+      return `/${resourceName}/${resourceId}`
     }
-    return endpoint
+
+    return typeof resourceId === 'number'
+      ? `/${resourceName}/${resourceId}/${operation}`
+      : typeof resourceId === 'string'
+      ? `/${resourceName}/:persistentId/${operation}?persistentId=${resourceId}`
+      : `/${resourceName}/${operation}`
   }
 
   private buildRequestConfig(authRequired: boolean, queryParams: object): AxiosRequestConfig {
@@ -61,7 +61,7 @@ export abstract class ApiRepository {
     switch (ApiConfig.dataverseApiAuthMechanism) {
       case DataverseApiAuthMechanism.SESSION_COOKIE:
         /*
-          We set { withCredentials: true } to send the JSESSIONID cookie in the requests for API authentication. 
+          We set { withCredentials: true } to send the JSESSIONID cookie in the requests for API authentication.
           This is required, along with the session auth feature flag enabled in the backend, to be able to authenticate using the JSESSIONID cookie.
           Auth mechanisms like this are configurable to set the one that fits the particular use case of js-dataverse. (For the SPA MVP, it is the session cookie API auth).
         */