Added: getDatasetFilesTotalDownloadSize docs

docs/useCases.md

@@ -21,6 +21,7 @@ The different use cases currently available in the package are classified below,
 - [Files](#Files)
   - [Files read use cases](#files-read-use-cases)
     - [Get File Counts in a Dataset](#get-file-counts-in-a-dataset)
+    - [Get the size of Downloading all the files of a Dataset Version](#get-the-size-of-downloading-all-the-files-of-a-dataset-version)
     - [List Files in a Dataset](#list-files-in-a-dataset)
 - [Metadata Blocks](#metadata-blocks)
 - [Users](#Users)
@@ -57,7 +58,7 @@ The `datasetId` parameter can be a string, for persistent identifiers, or a numb
 
 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`.
 
-There is a third optional 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 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 By Private URL Token
 
@@ -102,7 +103,7 @@ getDatasetCitation.execute(datasetId, datasetVersionId).then((citationText: stri
 
 _See [use case](../src/datasets/domain/useCases/GetDatasetCitation.ts) definition_.
 
-There is a third optional 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 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
 
@@ -310,9 +311,9 @@ getDatasetFileCounts.execute(datasetId, datasetVersionId).then((fileCounts: File
 
 _See [use case](../src/files/domain/useCases/GetDatasetFileCounts.ts) definition_.
 
-There is a third optional 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 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`.
 
-A fourth optional parameter `fileSearchCriteria` receives a [FileSearchCriteria](../src/files/domain/models/FileCriteria.ts) parameter to retrieve counts only for files that match the specified criteria.
+An optional fourth parameter `fileSearchCriteria` receives a [FileSearchCriteria](../src/files/domain/models/FileCriteria.ts) object to retrieve counts only for files that match the specified criteria.
 
 ##### Example call using optional parameters:
 
@@ -325,7 +326,7 @@ const datasetId: number = 2;
 const datasetVersionId: string = '1.0';
 const includeDeaccessioned: boolean = true;
 const searchCriteria: FileSearchCriteria = {
-  categoryName: 'Physics',
+  categoryName: 'physics',
 };
 
 getDatasetFileCounts
@@ -337,6 +338,61 @@ getDatasetFileCounts
 /* ... */
 ```
 
+### 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:
+
+```typescript
+import { getDatasetFilesTotalDownloadSize } from '@iqss/dataverse-client-javascript';
+
+/* ... */
+
+const datasetId: number = 2;
+const datasetVersionId: string = '1.0';
+
+getDatasetFilesTotalDownloadSize.execute(datasetId, datasetVersionId).then((size: number) => {
+  /* ... */
+});
+
+/* ... */
+```
+
+There is a third optional parameter called `fileDownloadSizeMode` which receives an enum type of [FileDownloadSizeMode](../src/files/domain/models/FileDownloadSizeMode.ts), 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](../src/files/domain/models/FileCriteria.ts) 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:
+
+```typescript
+import { getDatasetFilesTotalDownloadSize } from '@iqss/dataverse-client-javascript';
+
+/* ... */
+
+const datasetId: number = 2;
+const datasetVersionId: string = '1.0';
+const fileDownloadSizeMode: FileDownloadSizeMode = FileDownloadSizeMode.ARCHIVAL;
+const fileSearchCriteria: FileDownloadSizeMode = {
+  categoryName: 'physics',
+};
+const includeDeaccessioned: boolean = true;
+
+getDatasetFilesTotalDownloadSize
+  .execute(datasetId, datasetVersionId, fileDownloadSizeMode, fileSearchCriteria, includeDeaccessioned)
+  .then((size: number) => {
+    /* ... */
+  });
+
+/* ... */
+```
+
 ## Metadata Blocks
 
 TODO

src/files/domain/useCases/GetDatasetFilesTotalDownloadSize.ts

@@ -11,6 +11,16 @@ export class GetDatasetFilesTotalDownloadSize implements UseCase<number> {
     this.filesRepository = filesRepository;
   }
 
+  /**
+   * Returns the combined size in bytes of all the files available for download from a particular Dataset.
+   *
+   * @param {number | string} [datasetId] - The dataset 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
+   * @param {FileDownloadSizeMode} [fileDownloadSizeMode=FileDownloadSizeMode.ALL] - Applies a filter mode to the operation to consider only archival sizes, original or both (all). The default value is FileDownloadSizeMode.ALL.
+   * @param {FileSearchCriteria} [fileSearchCriteria] - Supports filtering the files to obtain their combined size by different file properties (optional).
+   * @param {boolean} [includeDeaccessioned=false] - Indicates whether to consider deaccessioned versions in the dataset search or not. The default value is false.
+   * @returns {Promise<number>}
+   */
   async execute(
     datasetId: number | string,
     datasetVersionId: string | DatasetNotNumberedVersion = DatasetNotNumberedVersion.LATEST,