Skip to content

Latest commit

 

History

History
1365 lines (887 loc) · 44.8 KB

useCases.md

File metadata and controls

1365 lines (887 loc) · 44.8 KB
Raw

Use Cases

In the context of Domain-Driven Design (DDD), a use case is a specific way to describe and capture a user's or system's interaction with the domain to achieve a particular goal.

This package exposes the functionality in the form of use cases, with the main goal that any package consumer can easily identify the desired functionality.

The different use cases currently available in the package are classified below, according to the subdomains they target:

Table of Contents

Collections

Collections Read Use Cases

Get a Collection

Returns a Collection instance, given the search parameters to identify it.

Example call:
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 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.

Get Collection Facets

Returns a CollectionFacet array containing the facets of the requested collection, given the collection identifier or alias.

Example call:
import { getCollectionFacets } from '@iqss/dataverse-client-javascript'

const collectionIdOrAlias = 12345

getCollectionFacets
  .execute(collectionId)
  .then((facets: CollectionFacet[]) => {
    /* ... */
  })
  .catch((error: Error) => {
    /* ... */
  })

See use case 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.

Get User Permissions on a Collection

Returns an instance of CollectionUserPermissions that includes the permissions that the calling user has on a particular Collection.

Example call:
import { getCollectionUserPermissions } from '@iqss/dataverse-client-javascript'

/* ... */

const collectionIdOrAlias = 12345

getCollectionUserPermissions
  .execute(collectionIdOrAlias)
  .then((permissions: CollectionUserPermissions) => {
    /* ... */
  })

/* ... */

See use case implementation.

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.

List All Collection Items

Returns an instance of CollectionItemSubset that contains reduced information for each collection item that the calling user can access in the installation.

Example call:
import { getCollectionItems } from '@iqss/dataverse-client-javascript'

/* ... */

const collectionId = 'subcollection1'
const limit = 10
const offset = 20

getCollectionItems.execute(collectionId, limit, offset).then((subset: CollectionItemSubset) => {
  /* ... */
})

/* ... */

See use case implementation.

Note that collectionId is an optional parameter to filter the items by a specific collection. If not set, the use case will return items starting from the root collection.

The CollectionItemSubsetreturned instance contains a property called totalItemCount which is necessary for pagination.

This use case supports the following optional parameters depending on the search goals:

  • limit: (number) Limit for pagination.
  • offset: (number) Offset for pagination.
  • collectionSearchCriteria: (CollectionSearchCriteria) Supports filtering the collection items by different properties.

Collections Write Use Cases

Create a Collection

Creates a new Collection, given a CollectionDTO object and an optional parent collection identifier, which defaults to :root.

Example call:
import { createCollection } from '@iqss/dataverse-client-javascript'

/* ... */

const collectionDTO: CollectionDTO = {
  alias: alias,
  name: 'Test Collection',
  contacts: ['[email protected]'],
  type: CollectionType.DEPARTMENT
}

createCollection.execute(collectionDTO).then((createdCollectionId: number) => {
  /* ... */
})

/* ... */

See use case implementation.

The above example creates the new collection in the root collection since no collection identifier is specified. If you want to create the collection in a different collection, you must add the collection identifier as a second parameter in the use case call.

The use case returns a number, which is the identifier of the created collection.

Update a Collection

Updates an existing collection, given a collection identifier and a CollectionDTO including the updated collection data.

Example call:
import { updateCollection } from '@iqss/dataverse-client-javascript'

/* ... */

const collectionIdOrAlias = 12345
const collectionDTO: CollectionDTO = {
  alias: alias,
  name: 'Updated Collection Name',
  contacts: ['[email protected]'],
  type: CollectionType.DEPARTMENT
}

updateCollection.execute(collectionIdOrAlias, collectionDTO)

/* ... */

See use case implementation.

The collectionIdOrAlias is a generic collection identifier, which can be either a string (for queries by CollectionAlias), or a number (for queries by CollectionId).

Publish a Collection

Publishes a Collection, given the collection identifier.

Example call:
import { publishCollection } from '@iqss/dataverse-client-javascript'

/* ... */

const collectionIdOrAlias = 12345

publishCollection.execute(collectionIdOrAlias)

/* ... */

The collectionIdOrAlias is a generic collection identifier, which can be either a string (for queries by CollectionAlias), or a number (for queries by CollectionId).

See use case definition.

Datasets

Datasets Read Use Cases

Get a Dataset

Returns a Dataset instance, given the search parameters to identify it.

Example call:
import { getDataset } from '@iqss/dataverse-client-javascript'

/* ... */

const datasetId = 'doi:10.77777/FK2/AAAAAA'
const datasetVersionId = '1.0'

getDataset.execute(datasetId, datasetVersionId).then((dataset: Dataset) => {
  /* ... */
})

/* ... */

See use case definition.

The datasetId parameter can be a string, for persistent identifiers, or a number, for numeric identifiers.

The optional datasetVersionId parameter can correspond to a numeric version identifier, as in the previous example, or a DatasetNotNumberedVersion enum value. If not set, the default value is DatasetNotNumberedVersion.LATEST.

There is an optional third parameter called includeDeaccessioned, which indicates whether to consider deaccessioned versions or not in the dataset search. If not set, the default value is false.

There is an optional fourth parameter called keepRawFields, which indicates whether or not to keep the metadata fields as they are and avoid the transformation to Markdown. The default value is false.

Get Dataset By Private URL Token

Returns a Dataset instance, given an associated Private URL Token.

import { getPrivateUrlDataset } from '@iqss/dataverse-client-javascript'

/* ... */

const token = 'a56444bc-7697-4711-8964-e0577f055fd2'

getPrivateUrlDataset.execute(token).then((dataset: Dataset) => {
  /* ... */
})

/* ... */

See use case definition.

There is an optional second parameter called keepRawFields, which indicates whether or not to keep the metadata fields as they are and avoid the transformation to Markdown. The default value is false.

Get Dataset Citation Text

Returns the Dataset citation text.

Example call:
import { getDatasetCitation } from '@iqss/dataverse-client-javascript'

/* ... */

const datasetId = 2
const datasetVersionId = '1.0'

getDatasetCitation.execute(datasetId, datasetVersionId).then((citationText: string) => {
  /* ... */
})

/* ... */

See use case implementation.

The datasetId parameter can be a string, for persistent identifiers, or a number, for numeric identifiers.

There is an optional third parameter called includeDeaccessioned, which indicates whether to consider deaccessioned versions or not in the dataset search. If not set, the default value is false.

Get Dataset Citation Text By Private URL Token

Returns the Dataset citation text, given an associated Private URL Token.

Example call:
import { getPrivateUrlDatasetCitation } from '@iqss/dataverse-client-javascript'

/* ... */

const token = 'a56444bc-7697-4711-8964-e0577f055fd2'

getPrivateUrlDatasetCitation.execute(token).then((citationText: string) => {
  /* ... */
})

/* ... */

See use case implementation.

Get Dataset Locks

Returns a DatasetLock array of all locks present in a Dataset.

Example call:
import { getDatasetLocks } from '@iqss/dataverse-client-javascript'

/* ... */

const datasetId = 'doi:10.77777/FK2/AAAAAA'

getDatasetLocks.execute(datasetId).then((datasetLocks: DatasetLock[]) => {
  /* ... */
})

/* ... */

See use case implementation.

The datasetId parameter can be a string, for persistent identifiers, or a number, for numeric identifiers.

Get Dataset Summary Field Names

Returns the names of the dataset summary fields configured in the installation.

Example call:
import { getDatasetSummaryFieldNames } from '@iqss/dataverse-client-javascript'

/* ... */

getDatasetSummaryFieldNames.execute().then((names: string[]) => {
  /* ... */
})

/* ... */

See use case implementation.

Get User Permissions on a Dataset

Returns an instance of DatasetUserPermissions that includes the permissions that the calling user has on a particular Dataset.

Example call:
import { getDatasetUserPermissions } from '@iqss/dataverse-client-javascript'

/* ... */

const datasetId = 'doi:10.77777/FK2/AAAAAA'

getDatasetUserPermissions.execute(datasetId).then((permissions: DatasetUserPermissions) => {
  /* ... */
})

/* ... */

See use case implementation.

The datasetId parameter can be a string, for persistent identifiers, or a number, for numeric identifiers.

Get Differences between Two Dataset Versions

Returns an instance of DatasetVersionDiff that contains the differences between two Dataset Versions.

Example call:
import { getDatasetVersionDiff } from '@iqss/dataverse-client-javascript'

/* ... */

const datasetId = 'doi:10.77777/FK2/AAAAAA'
const oldVersion = '1.0'
const newVersion = '2.0'

lgetDatasetVersionDiff
  .execute(datasetId, oldVersion, newVersion)
  .then((versionDiff: DatasetVersionDiff) => {
    /* ... */
  })

/* ... */

See use case implementation.

The datasetId parameter can be a string, for persistent identifiers, or a number, for numeric identifiers.

The oldVersion and newVersion parameters specify the versions of the dataset to compare.

List All Datasets

Returns an instance of DatasetPreviewSubset that contains reduced information for each dataset that the calling user can access in the installation.

Example call:
import { getAllDatasetPreviews } from '@iqss/dataverse-client-javascript'

/* ... */

const limit = 10
const offset = 20
const collectionId = 'subcollection1'

getAllDatasetPreviews.execute(limit, offset, collectionId).then((subset: DatasetPreviewSubset) => {
  /* ... */
})

/* ... */

See use case implementation.

Note that limit and offset are optional parameters for pagination.

Note that collectionId is an optional parameter to filter datasets by collection. If not set, the default value is :root.

The DatasetPreviewSubsetreturned instance contains a property called totalDatasetCount which is necessary for pagination.

Datasets Write Use Cases

Create a Dataset

Creates a new Dataset in a collection, given a DatasetDTO object and an optional collection identifier, which defaults to :root.

This use case validates the submitted fields of each metadata block and can return errors of type ResourceValidationError, which include sufficient information to determine which field value is invalid and why.

Example call:
import { createDataset } from '@iqss/dataverse-client-javascript'

/* ... */

const datasetDTO: DatasetDTO = {
  metadataBlockValues: [
    {
      name: 'citation',
      fields: {
        title: 'New Dataset',
        author: [
          {
            authorName: 'John Doe',
            authorAffiliation: 'Dataverse'
          },
          {
            authorName: 'John Lee',
            authorAffiliation: 'Dataverse'
          }
        ],
        datasetContact: [
          {
            datasetContactEmail: '[email protected]',
            datasetContactName: 'John'
          }
        ],
        dsDescription: [
          {
            dsDescriptionValue: 'This is the description of our new dataset'
          }
        ],
        subject: 'Earth and Environmental Sciences'

        /* Rest of field values... */
      }
    }
  ]
}

createDataset.execute(datasetDTO).then((newDatasetIds: CreatedDatasetIdentifiers) => {
  /* ... */
})

/* ... */

See use case implementation.

The above example creates the new dataset in the root collection since no collection identifier is specified. If you want to create the dataset in a different collection, you must add the collection identifier as a second parameter in the use case call.

The use case returns a CreatedDatasetIdentifiers object, which includes the persistent and numeric identifiers of the created dataset.

Update a Dataset

Updates an existing Dataset, given a DatasetDTO with the updated information.

If a draft of the dataset already exists, the metadata of that draft is overwritten; otherwise, a new draft is created with the updated metadata.

This use case validates the submitted fields of each metadata block and can return errors of type ResourceValidationError, which include sufficient information to determine which field value is invalid and why.

Example call:
import { updateDataset } from '@iqss/dataverse-client-javascript'

/* ... */

const datasetId = 1
const datasetDTO: DatasetDTO = {
  metadataBlockValues: [
    {
      name: 'citation',
      fields: {
        title: 'Updated Dataset',
        author: [
          {
            authorName: 'John Doe',
            authorAffiliation: 'Dataverse'
          },
          {
            authorName: 'John Lee',
            authorAffiliation: 'Dataverse'
          }
        ],
        datasetContact: [
          {
            datasetContactEmail: '[email protected]',
            datasetContactName: 'John'
          }
        ],
        dsDescription: [
          {
            dsDescriptionValue: 'This is the description of our new dataset'
          }
        ],
        subject: 'Earth and Environmental Sciences'

        /* Rest of field values... */
      }
    }
  ]
}

updateDataset.execute(datasetId, datasetDTO)

/* ... */

See use case implementation.

The datasetId parameter can be a string, for persistent identifiers, or a number, for numeric identifiers.

Publish a Dataset

Publishes a Dataset, given its identifier and the type of version update to perform.

Example call:
import { publishDataset } from '@iqss/dataverse-client-javascript'

/* ... */

const datasetId = 'doi:10.77777/FK2/AAAAAA'
const versionUpdateType = VersionUpdateType.MINOR

publishDataset.execute(datasetId, versionUpdateType)

/* ... */

See use case implementation.

The above example publishes the dataset with the specified identifier and performs a minor version update. If the response is successful, the use case does not return the dataset object, but the HTTP status code 200. Otherwise, it throws an error.
If you want to perform a major version update, you must set the versionUpdateType parameter to VersionUpdateType.MAJOR.
Superusers can pass VersionUpdateType.UPDATE_CURRENT to update metadata without changing the version number. This will overwrite the latest published version and therefore will only work for a dataset that has been published at least once. *Note that this will only work also if there were no file changes in the update.
The datasetId parameter can be a string, for persistent identifiers, or a number, for numeric identifiers.

The versionUpdateType parameter can be a VersionUpdateType enum value, which can be one of the following:

  • VersionUpdateType.MINOR
  • VersionUpdateType.MAJOR
  • VersionUpdateType.UPDATE_CURRENT

Files

Files read use cases

Get a File

Returns a FileModel instance, given the search parameters to identify it.

Example call:
import { getFile } from '@iqss/dataverse-client-javascript'

/* ... */

const fileId = 2
const datasetVersionId = '1.0'

getFile.execute(fileId, datasetVersionId).then((file: FileModel) => {
  /* ... */
})

/* ... */

See use case definition.

The fileId parameter can be a string, for persistent identifiers, or a number, for numeric identifiers.

The optional datasetVersionId parameter can correspond to a numeric version identifier, as in the previous example, or a DatasetNotNumberedVersion enum value. If not set, the default value is DatasetNotNumberedVersion.LATEST.

Get a File and its Dataset

Returns a tuple of FileModel and Dataset objects ([FileModel, Dataset]), given the search parameters to identify the file.

The returned dataset object corresponds to the dataset version associated with the requested file.

Example call:
import { getFileAndDataset } from '@iqss/dataverse-client-javascript'

/* ... */

const fileId = 2
const datasetVersionId = '1.0'

getFileAndDataset.execute(fileId, datasetVersionId).then((fileAndDataset: [FileModel, Dataset]) => {
  /* ... */
})

/* ... */

See use case definition.

The fileId parameter can be a string, for persistent identifiers, or a number, for numeric identifiers.

The optional datasetVersionId parameter can correspond to a numeric version identifier, as in the previous example, or a DatasetNotNumberedVersion enum value. If not set, the default value is DatasetNotNumberedVersion.LATEST.

Get File Citation Text

Returns the File citation text.

Example call:
import { getFileCitation } from '@iqss/dataverse-client-javascript'

/* ... */

const fileId = 3
const datasetVersionId = '1.0'

getFileCitation.execute(fileId, datasetVersionId).then((citationText: string) => {
  /* ... */
})

/* ... */

See use case implementation.

The fileId parameter can be a string, for persistent identifiers, or a number, for numeric identifiers.

There is an optional third parameter called includeDeaccessioned, which indicates whether to consider deaccessioned versions or not in the file search. If not set, the default value is false.

Get File Counts in a Dataset

Returns an instance of FileCounts, containing the requested Dataset total file count, as well as file counts for the following file properties:

  • Per content type
  • Per category name
  • Per tabular tag name
  • Per access status (Possible values: Public, Restricted, EmbargoedThenRestricted, EmbargoedThenPublic)
Example call:
import { getDatasetFileCounts } from '@iqss/dataverse-client-javascript'

/* ... */

const datasetId = 2
const datasetVersionId = '1.0'

getDatasetFileCounts.execute(datasetId, datasetVersionId).then((fileCounts: FileCounts) => {
  /* ... */
})

/* ... */

See use case implementation.

The datasetId parameter can be a string, for persistent identifiers, or a number, for numeric identifiers. The optional datasetVersionId parameter can correspond to a numeric version identifier, as in the previous example, or a DatasetNotNumberedVersion enum value. If not set, the default value is DatasetNotNumberedVersion.LATEST. There is an optional third parameter called includeDeaccessioned, which indicates whether to consider deaccessioned versions or not in the dataset search. If not set, the default value is false.

An optional fourth parameter fileSearchCriteria receives a FileSearchCriteria object to retrieve counts only for files that match the specified criteria.

Example call using optional parameters:
import { getDatasetFileCounts } from '@iqss/dataverse-client-javascript'

/* ... */

const datasetId: number = 2
const datasetVersionId: string = '1.0'
const includeDeaccessioned: boolean = true
const searchCriteria: FileSearchCriteria = {
  categoryName: 'physics'
}

getDatasetFileCounts
  .execute(datasetId, datasetVersionId, includeDeaccessioned, searchCriteria)
  .then((fileCounts: FileCounts) => {
    /* ... */
  })

/* ... */

Get File Data Tables

This use case is oriented toward tabular files and provides an array of FileDataTable objects for an existing tabular file.

Example call:
import { getFileDataTables } from '@iqss/dataverse-client-javascript'

/* ... */

const fileId = 2

getFileDataTables.execute(fileId).then((dataTables: FileDataTable[]) => {
  /* ... */
})

/* ... */

See use case implementation.

The fileId parameter can be a string, for persistent identifiers, or a number, for numeric identifiers.

Get File Download Count

Provides the download count for a particular File.

Example call:
import { getFileDownloadCount } from '@iqss/dataverse-client-javascript'

/* ... */

const fileId: number = 2

getFileDownloadCount.execute(fileId).then((count: number) => {
  /* ... */
})

/* ... */

See use case implementation.

The fileId parameter can be a string, for persistent identifiers, or a number, for numeric identifiers.

Get the size of Downloading all the files of a Dataset Version

Returns the combined size in bytes of all the files available for download from a particular Dataset.

Example call:
import { getDatasetFilesTotalDownloadSize } from '@iqss/dataverse-client-javascript'

/* ... */

const datasetId: number = 2
const datasetVersionId: string = '1.0'

getDatasetFilesTotalDownloadSize.execute(datasetId, datasetVersionId).then((size: number) => {
  /* ... */
})

/* ... */

See use case implementation.

The datasetId parameter can be a string, for persistent identifiers, or a number, for numeric identifiers. The optional datasetVersionId parameter can correspond to a numeric version identifier, as in the previous example, or a DatasetNotNumberedVersion enum value. If not set, the default value is DatasetNotNumberedVersion.LATEST. There is a third optional parameter called fileDownloadSizeMode which receives an enum type of FileDownloadSizeMode, and applies a filter criteria to the operation. This parameter supports the following values:

  • FileDownloadSizeMode.ALL (Default): Includes both archival and original sizes for tabular files
  • FileDownloadSizeMode.ARCHIVAL: Includes only the archival size for tabular files
  • FileDownloadSizeMode.ORIGINAL: Includes only the original size for tabular files

An optional fourth parameter called fileSearchCriteria receives a FileSearchCriteria object to only consider files that match the specified criteria.

An optional fifth parameter called includeDeaccessioned indicates whether to consider deaccessioned versions or not in the dataset search. If not set, the default value is false.

Example call using optional parameters:
import { getDatasetFilesTotalDownloadSize } from '@iqss/dataverse-client-javascript'

/* ... */

const datasetId: number = 2
const datasetVersionId: string = '1.0'
const mode: FileDownloadSizeMode = FileDownloadSizeMode.ARCHIVAL
const searchCriteria: FileDownloadSizeMode = {
  categoryName: 'physics'
}
const includeDeaccessioned: boolean = true

getDatasetFilesTotalDownloadSize
  .execute(datasetId, datasetVersionId, mode, searchCriteria, includeDeaccessioned)
  .then((size: number) => {
    /* ... */
  })

/* ... */

Get User Permissions on a File

This use case returns a FileUserPermissions object, which includes the permissions that the calling user has on a particular File.

The returned FileUserPermissions object contains the following permissions, as booleans:

  • Can download the file (canDownloadFile)
  • Can manage the file permissions (canManageFilePermissions)
  • Can edit the file owner dataset (canEditOwnerDataset)
Example call:
import { getFileUserPermissions } from '@iqss/dataverse-client-javascript'

/* ... */

const fileId: number = 2

getFileUserPermissions.execute(fileId).then((permissions: FileUserPermissions) => {
  /* ... */
})

/* ... */

See use case implementation.

The fileId parameter can be a string, for persistent identifiers, or a number, for numeric identifiers.

List Files in a Dataset

Returns an instance of FilesSubset, which contains the files from the requested Dataset and page (if pagination parameters are set).

Example call:
import { getDatasetFiles } from '@iqss/dataverse-client-javascript'

/* ... */

const datasetId = 2
const datasetVersionId = '1.0'

getDatasetFiles.execute(datasetId, datasetVersionId).then((subset: FilesSubset) => {
  /* ... */
})

/* ... */

See use case implementation.

The datasetId parameter can be a string, for persistent identifiers, or a number, for numeric identifiers. The optional datasetVersionId parameter can correspond to a numeric version identifier, as in the previous example, or a DatasetNotNumberedVersion enum value. If not set, the default value is DatasetNotNumberedVersion.LATEST. This use case supports the following optional parameters depending on the search goals:

  • includeDeaccessioned: (boolean) Indicates whether to consider deaccessioned versions or not in the dataset search. If not set, the default value is false.
  • limit: (number) Limit for pagination.
  • offset: (number) Offset for pagination.
  • fileSearchCriteria: (FileSearchCriteria) Supports filtering the files by different file properties.
  • fileOrderCriteria: (FileOrderCriteria) Supports ordering the results according to different criteria. If not set, the defalt value is FileOrderCriteria.NAME_AZ.
Example call using optional parameters:
import { getDatasetFiles } from '@iqss/dataverse-client-javascript'

/* ... */

const datasetId: number = 2
const datasetVersionId: string = '1.0'
const includeDeaccessioned: boolean = true
const limit: number = 10
const offset: number = 20
const searchCriteria: FileSearchCriteria = {
  searchText: 'file title'
}
const orderCriteria: FileOrderCriteria = FileOrderCriteria.NEWEST

getDatasetFiles
  .execute(
    datasetId,
    datasetVersionId,
    includeDeaccessioned,
    limit,
    offset,
    searchCriteria,
    orderCriteria
  )
  .then((subset: FilesSubset) => {
    /* ... */
  })

/* ... */

Files write use cases

File Uploading Use Cases

These use cases are designed to facilitate the uploading of files to a remote S3 storage and subsequently adding them to a dataset. This process involves two main steps / use cases:

  1. Uploading a file to remote S3 storage and obtaining a storage identifier.
  2. Adding one or more uploaded files to the dataset using the obtained storage identifiers.

This use case flow is entirely based on the Direct Upload API as described in the Dataverse documentation: https://guides.dataverse.org/en/latest/developers/s3-direct-upload-api.html

Upload File

This use case uploads a file to a remote S3 storage and returns the storage identifier associated with the file.

Example call:
import { uploadFile } from '@iqss/dataverse-client-javascript'

/* ... */

const datasetId: number | string = 123
const file = new File(['content'], 'example.txt', { type: 'text/plain' })
const progressCallback = (progress) => console.log(`Upload progress: ${progress}%`)
const abortController = new AbortController()

uploadFile.execute(datasetId, file, progressCallback, abortController).then((storageId) => {
  console.log(`File uploaded successfully with storage ID: ${storageId}`)
})

/* ... */

See use case implementation.

The datasetId parameter can be a string, for persistent identifiers, or a number, for numeric identifiers.

The file parameter is a subclass of Blob (Binary Large Object) that represents a file.

The progress parameter represents a callback function that allows the caller to monitor the progress of the file uploading operation.

The abortController is a built-in mechanism in modern web browsers that allows the cancellation of asynchronous operations. It works in conjunction with an associated AbortSignal, which will be passed to the file uploading API calls to monitor whether the operation should be aborted, if the caller decides to cancel the operation midway.

Add Uploaded Files to the Dataset

This use case involves adding files that have been previously uploaded to remote storage to the dataset.

Example call:
import { addUploadedFilesToDataset } from '@iqss/dataverse-client-javascript'
import { UploadedFileDTO } from '@iqss/dataverse-client-javascript'

/* ... */

const datasetId: number | string = 123
const uploadedFileDTOs: UploadedFileDTO[] = [
  {
    fileName: 'the-file-name',
    storageId: 'localstack1://mybucket:19121faf7e7-2c40322ff54e',
    checksumType: 'md5',
    checksumValue: 'ede3d3b685b4e137ba4cb2521329a75e',
    mimeType: 'text/plain'
  }
]

addUploadedFilesToDataset.execute(datasetId, uploadedFileDTOs).then(() => {
  console.log('Files added to the dataset successfully.')
})

/* ... */

See use case implementation.

The datasetId parameter can be a string, for persistent identifiers, or a number, for numeric identifiers.

The uploadedFileDTOs parameter is an array of UploadedFileDTO and includes properties related to the uploaded files. Some of these properties should be calculated from the uploaded File Blob objects and the resulting storage identifiers from the Upload File use case.

Error handling:

These use cases involve multiple steps, each associated with different API calls, which introduce various points of potential failure. Therefore, different error types have been implemented according to their nature, all of which extend DirectUploadClientError.

The following errors might arise from the UploadFile use case:

  • UrlGenerationError: This error indicates that the destination URLs for file upload could not be generated successfully.

  • FilePartUploadError: This error indicates that the retry limit has been exceeded for uploading one of the parts of a multipart file. If this error is received, it is because the abort endpoint has been successfully called.

  • MultipartAbortError: This error indicates that it was not possible to call the abort endpoint after an error occurred during the upload of one of the parts of a multipart file.

  • MultipartCompletionError: This error indicates that the multipart upload could not be completed due to an error encountered when calling the completion endpoint.

  • FileUploadError: This error indicates that there has been an error while uploading a single-part file.

  • FileUploadCancelError: This error is received when the caller cancels the operation through the abort controller.

The following error might arise from the AddUploadedFileToDataset use case:

  • AddUploadedFileToDatasetError: This error indicates that there was an error while adding the uploaded file to the dataset.

Metadata Blocks

Metadata Blocks read use cases

Get All Facetable Metadata Fields

Returns a MetadataFieldInfo array containing all facetable metadata fields defined in the installation.

Example call:
import { getAllFacetableMetadataFields } from '@iqss/dataverse-client-javascript'

/* ... */

getAllFacetableMetadataFields.execute().then((metadataFieldInfos: MetadataFieldInfo[]) => {
  /* ... */
})

/* ... */

See use case implementation.

Get All Metadata Blocks

Returns a MetadataBlock array containing the metadata blocks defined in the installation.

Example call:
import { getAllMetadataBlocks } from '@iqss/dataverse-client-javascript'

/* ... */

getAllMetadataBlocks.execute().then((metadataBlocks: MetadataBlock[]) => {
  /* ... */
})

/* ... */

See use case implementation.

Get Metadata Block By Name

Returns a MetadataBlock instance, given its name.

Example call:
import { getMetadataBlockByName } from '@iqss/dataverse-client-javascript'

/* ... */

const name = 'citation'

getMetadataBlockByName.execute(name).then((metadataBlock: MetadataBlock) => {
  /* ... */
})

/* ... */

See use case implementation.

Get Collection Metadata Blocks

Returns a MetadataBlock array containing the metadata blocks from the requested collection.

Example call:
import { getCollectionMetadataBlocks } from '@iqss/dataverse-client-javascript'

/* ... */

const collectionIdOrAlias = 'citation'

getCollectionMetadataBlocks.execute(collectionAlias).then((metadataBlocks: MetadataBlock[]) => {
  /* ... */
})

/* ... */

See use case implementation.

The collectionIdOrAlias is a generic collection identifier, which can be either a string (for queries by CollectionAlias), or a number (for queries by CollectionId).

There is a second optional parameter called onlyDisplayedOnCreate which indicates whether or not to return only the metadata blocks that are displayed on dataset creation. The default value is false.

Users

Users read use cases

Get Current Authenticated User

Returns the current AuthenticatedUser corresponding to the authentication mechanism provided through ApiConfig.

Example call:
import { getCurrentAuthenticatedUser } from '@iqss/dataverse-client-javascript'

/* ... */

getCurrentAuthenticatedUser.execute().then((user: AuthenticatedUser) => {
  /* ... */
})

/* ... */

See use case implementation.

Get Current API Token

Returns the current ApiTokenInfo corresponding to the current authenticated user.

Example call:
import { getCurrentApiToken } from '@iqss/dataverse-client-javascript'

/* ... */

getCurrentApiToken.execute().then((apiTokenInfo: ApiTokenInfo) => {
  /* ... */
})

/* ... */

See use case implementation.

Users write use cases

Delete Current API Token

Deletes the API token of the current authenticated user.

Example call:
import { deleteCurrentApiToken } from '@iqss/dataverse-client-javascript'

/* ... */

deleteCurrentApiToken.execute()

/* ... */

See use case implementation.

Recreate Current API Token

Reacreates the API token of the current authenticated user and returns the new ApiTokenInfo.

Example call:
import { recreateCurrentApiToken } from '@iqss/dataverse-client-javascript'

/* ... */

recreateCurrentApiToken.execute().then((apiTokenInfo: ApiTokenInfo) => {
  /* ... */
})

/* ... */

See use case implementation.

Info

Get Dataverse Backend Version

Returns a DataverseVersion object, which contains version information for the Dataverse backend installation.

Example call:
import { getDataverseVersion } from '@iqss/dataverse-client-javascript'

/* ... */

getDataverseVersion.execute().then((version: DataverseVersion) => {
  /* ... */
})

/* ... */

See use case implementation.

Get Maximum Embargo Duration In Months

Returns a number indicating the configured maximum embargo duration in months. For information on the possible values that can be returned, please refer to the MaxEmbargoDurationInMonths property in the Dataverse documentation: MaxEmbargoDurationInMonths.

Example call:
import { getMaxEmbargoDurationInMonths } from '@iqss/dataverse-client-javascript'

/* ... */

getMaxEmbargoDurationInMonths.execute().then((months: number) => {
  /* ... */
})

/* ... */

See use case implementation.

Get ZIP Download Limit

Returns a number indicating the configured ZIP download limit in bytes.

Example call:
import { getZipDownloadLimit } from '@iqss/dataverse-client-javascript'

/* ... */

getZipDownloadLimit.execute().then((downloadLimit: number) => {
  /* ... */
})

/* ... */

See use case implementation.