diff --git a/docs/useCases.md b/docs/useCases.md index 7ed393bc..7344934f 100644 --- a/docs/useCases.md +++ b/docs/useCases.md @@ -20,6 +20,7 @@ The different use cases currently available in the package are classified below, - [List All Datasets](#list-all-datasets) - [Files](#Files) - [Files read use cases](#files-read-use-cases) + - [Get a File](#get-a-file) - [Get File Counts in a Dataset](#get-file-counts-in-a-dataset) - [Get File Data Tables](#get-file-data-tables) - [Get File Download Count](#get-file-download-count) @@ -238,6 +239,33 @@ The `DatasetPreviewSubset`returned instance contains a property called `totalDat ### Files read use cases +#### Get a File + +Returns a [File](../src/files/domain/models/Dataset.ts) instance, given the search parameters to identify it. + +##### Example call: + +```typescript +import { getFile } from '@iqss/dataverse-client-javascript'; + +/* ... */ + +const fileId = 2; +const datasetVersionId = '1.0'; + +getFile.execute(fileId, datasetVersionId).then((file: File) => { + /* ... */ +}); + +/* ... */ +``` + +_See [use case](../src/files/domain/useCases/GetFile.ts)_ definition. + +The `fileId` parameter can be a string, for persistent identifiers, or a number, for numeric identifiers. + +The `datasetVersionId` parameter can correspond to a numeric version identifier, as in the previous example, or a [DatasetNotNumberedVersion](../src/datasets/domain/models/DatasetNotNumberedVersion.ts) enum value. If not set, the default value is `DatasetNotNumberedVersion.LATEST`. + #### Get File Counts in a Dataset Returns an instance of [FileCounts](../src/files/domain/models/FileCounts.ts), containing the requested Dataset total file count, as well as file counts for the following file properties: diff --git a/src/files/domain/useCases/GetFile.ts b/src/files/domain/useCases/GetFile.ts index 64f30052..6eb65991 100644 --- a/src/files/domain/useCases/GetFile.ts +++ b/src/files/domain/useCases/GetFile.ts @@ -5,6 +5,13 @@ import { DatasetNotNumberedVersion } from '../../../datasets'; export class GetFile { constructor(private readonly filesRepository: IFilesRepository) {} + /** + * Returns a File instance, given the search parameters to identify it. + * + * @param {number | string} [fileId] - The File identifier, which can be a string (for persistent identifiers), or a number (for numeric identifiers). + * @param {string | DatasetNotNumberedVersion} [datasetVersionId=DatasetNotNumberedVersion.LATEST] - The dataset version identifier, which can be a version-specific numeric string (for example, 1.0) or a DatasetNotNumberedVersion enum value. If this parameter is not set, the default value is: DatasetNotNumberedVersion.LATEST + * @returns {Promise} + */ async execute( fileId: number | string, datasetVersionId: string | DatasetNotNumberedVersion = DatasetNotNumberedVersion.LATEST,