From e27af2d4a276d85569b9e9157aef11e83ef6570f Mon Sep 17 00:00:00 2001 From: GPortas Date: Wed, 24 Jan 2024 08:05:40 +0000 Subject: [PATCH 01/51] Stash: new docs structure WIP --- README.md | 84 +++-------------------------------- docs/installation.md | 13 ++++++ docs/localDevelopment.md | 95 ++++++++++++++++++++++++++++++++++++++++ 3 files changed, 113 insertions(+), 79 deletions(-) create mode 100644 docs/installation.md create mode 100644 docs/localDevelopment.md diff --git a/README.md b/README.md index 85e21130..80680ee5 100644 --- a/README.md +++ b/README.md @@ -4,82 +4,8 @@ A JavaScript/TypeScript API wrapper for [Dataverse](http://guides.dataverse.org/en/latest/api/). -## NPM - -A stable 1.x version of this package is available as `js-dataverse` at https://www.npmjs.com/package/js-dataverse - -An unstable 2.x version of this package with breaking changes is under development. Until a 2.0 version is officially released, it can be installed from https://github.com/IQSS/dataverse-client-javascript/pkgs/npm/dataverse-client-javascript - -## Getting Started - -This package is built using `node v19`, so it is recommended to use that version. - -Make sure that you install all the project dependencies: - -`npm install` - -## Build project - -In order to build the project, we need to run the following command: - -`npm run build` - -the build generated will be placed in `dist` folder. - -## Tests - -### Run all tests - -`npm run test` - -### Run unit tests - -`npm run test:unit` - -### Run integration tests - -`npm run test:integration` - -#### Configure the integration testing environment - -The integration testing environment is implemented with Test Containers and Docker Compose. The environment uses different environment variables, defined in a .env file, available in the _test/integration/environment_ folder. - -These environment variables can be updated as needed for integration testing. For example, we can specify the Dataverse image registry and tag, to point to the particular Dataverse image to test. - -- To test images generated in Dataverse PRs: Set `ghcr.io` as the image registry (DATAVERSE_IMAGE_REGISTRY) and the source branch name of a particular PR as the image tag (DATAVERSE_IMAGE_TAG). - -- To test the Dataverse develop branch: Set `docker.io` as the image registry (DATAVERSE_IMAGE_REGISTRY) and `unstable` as the image tag (DATAVERSE_IMAGE_TAG). - -### Run test coverage - -`npm run test:coverage` - -## Format and lint - -### Run formatter - -`npm run format` - -### Run linter - -Running a linting check on the code: - -`npm run lint` - -Fix linting checks on the code: - -`npm run lint:fix` - -## Publishing new version - -Automated publishing of versions could be automated when merging to master. Below are the steps that would be required to publish a new version: - -1. Run tests and checks -2. Build the project -3. Commit changes -4. Upgrade npm version -5. Publish, `npm publish` - -## Contributing - -We love contributors! Please see [CONTRIBUTING.md](CONTRIBUTING.md). +- [Installation](./docs/installation.md) +- [Use Cases Documentation](./docs/api.md) +- [Local Development](./docs/localDevelopment.md) +- [Contributing](./CONTRIBUTING.md) +- [License](./LICENSE) diff --git a/docs/installation.md b/docs/installation.md new file mode 100644 index 00000000..f01cfbc1 --- /dev/null +++ b/docs/installation.md @@ -0,0 +1,13 @@ +# Installation + +A stable 1.x version of this package is available as `js-dataverse` at https://www.npmjs.com/package/js-dataverse + +Install the package stable version using npm: + +```bash +npm install js-dataverse +``` + +An unstable 2.x version of this package with breaking changes is under development. + +Until a 2.0 version is officially released, it can be installed from https://github.com/IQSS/dataverse-client-javascript/pkgs/npm/dataverse-client-javascript diff --git a/docs/localDevelopment.md b/docs/localDevelopment.md new file mode 100644 index 00000000..9527a778 --- /dev/null +++ b/docs/localDevelopment.md @@ -0,0 +1,95 @@ +# Local Development + +To set up your local development environment for working on this project, follow these steps: + +## Prerequisites + +### Node.js and npm + +Make sure you have Node.js and npm installed on your machine. + +This package is built using `node v19`, so it is recommended to use that version. + +### Docker and Docker Compose + +We use [Test Containers](https://github.com/testcontainers/testcontainers-node) for running integration tests. + +In our Test Containers setup we use Docker Compose, as our tests involve multiple containers that need to be orchestrated together. + +If you want to run integration tests, you need Docker and Docker Compose installed on your machine. + +## Install Dependencies + +Make sure that you install all the project dependencies: + +```bash +npm install +``` + +## Build + +In order to build the project, we need to run the following command: + +```bash +npm run build +``` + +the build generated will be placed in `dist` folder. + +## Tests + +### Run all tests + +```bash +npm run test +``` + +### Run unit tests + +```bash +npm run test:unit +``` + +### Run integration tests + +```bash +npm run test:integration +``` + +#### Configure the integration testing environment + +The integration testing environment uses different environment variables, defined in a .env file, available in the _test/integration/environment_ folder. + +These environment variables can be updated as needed for integration testing. For example, we can specify the Dataverse image registry and tag, to point to the particular Dataverse image to test. + +- To test images generated in Dataverse PRs: Set `ghcr.io` as the image registry (DATAVERSE_IMAGE_REGISTRY) and the source branch name of a particular PR as the image tag (DATAVERSE_IMAGE_TAG). + +- To test the Dataverse develop branch: Set `docker.io` as the image registry (DATAVERSE_IMAGE_REGISTRY) and `unstable` as the image tag (DATAVERSE_IMAGE_TAG). + +### Run test coverage + +```bash +npm run test:coverage +``` + +## Format and lint + +### Run formatter + +```bash +npm run format +``` + +### Run linter + +Running a linting check on the code: + +```bash +npm run lint +``` + +Fix linting checks on the code: + +```bash +npm run lint:fix +``` \ No newline at end of file From 6fb2f1b261f308b46a580f01a8dbbd12b2d458d5 Mon Sep 17 00:00:00 2001 From: GPortas Date: Wed, 24 Jan 2024 08:48:51 +0000 Subject: [PATCH 02/51] Added: new useCases section and Api Config installation subsection (empty) --- docs/installation.md | 6 ++++++ docs/useCases.md | 27 +++++++++++++++++++++++++++ 2 files changed, 33 insertions(+) create mode 100644 docs/useCases.md diff --git a/docs/installation.md b/docs/installation.md index f01cfbc1..564ed89d 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -1,5 +1,7 @@ # Installation +## NPM + A stable 1.x version of this package is available as `js-dataverse` at https://www.npmjs.com/package/js-dataverse Install the package stable version using npm: @@ -11,3 +13,7 @@ npm install js-dataverse An unstable 2.x version of this package with breaking changes is under development. Until a 2.0 version is officially released, it can be installed from https://github.com/IQSS/dataverse-client-javascript/pkgs/npm/dataverse-client-javascript + +## API Config + +TODO diff --git a/docs/useCases.md b/docs/useCases.md new file mode 100644 index 00000000..23a30118 --- /dev/null +++ b/docs/useCases.md @@ -0,0 +1,27 @@ +# 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: + +## Datasets + +TODO + +## Files + +TODO + +## Metadata Blocks + +TODO + +## Users + +TODO + +## Info + +TODO From 4e63e54e5c8162977577adb2fb4422b86b4161e3 Mon Sep 17 00:00:00 2001 From: GPortas Date: Wed, 24 Jan 2024 09:19:42 +0000 Subject: [PATCH 03/51] Stash: initialization docs WIP --- README.md | 2 +- docs/installation.md | 16 ++++++++++++++-- 2 files changed, 15 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 80680ee5..97440490 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@ A JavaScript/TypeScript API wrapper for [Dataverse](http://guides.dataverse.org/en/latest/api/). - [Installation](./docs/installation.md) -- [Use Cases Documentation](./docs/api.md) +- [Use Cases](./docs/useCases.md) - [Local Development](./docs/localDevelopment.md) - [Contributing](./CONTRIBUTING.md) - [License](./LICENSE) diff --git a/docs/installation.md b/docs/installation.md index 564ed89d..00520cd8 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -2,6 +2,8 @@ ## NPM +### Stable version + A stable 1.x version of this package is available as `js-dataverse` at https://www.npmjs.com/package/js-dataverse Install the package stable version using npm: @@ -10,10 +12,20 @@ Install the package stable version using npm: npm install js-dataverse ``` +### Development versions + An unstable 2.x version of this package with breaking changes is under development. Until a 2.0 version is officially released, it can be installed from https://github.com/IQSS/dataverse-client-javascript/pkgs/npm/dataverse-client-javascript -## API Config +## Initialization + +In order for the package to connect to the Dataverse API, there is an `APIConfig` object that should be initialized to set the preferred authentication mechanism with the associated credentials for connecting to the Dataverse API. + +Currently, the supported authentication mechanisms are: + +- API Key: The recommended mechanism and the original one from the initial package versions. The API Key should correspond to a particular Dataverse user. + +- Session Cookie: This is an experimental feature primarily designed for Dataverse SPA development. It is necessary to enable the corresponding feature flag in the Dataverse installation (See https://guides.dataverse.org/en/latest/installation/config.html?#feature-flags). It is recommended not to use this mechanism. -TODO +TODO \ No newline at end of file From e79e4d17d27a50edd9429127662a9412afd370a6 Mon Sep 17 00:00:00 2001 From: GPortas Date: Wed, 24 Jan 2024 15:25:42 +0000 Subject: [PATCH 04/51] Added: info to installation/initialization section --- docs/installation.md | 34 +++++++++++++++++++++++++++++++--- 1 file changed, 31 insertions(+), 3 deletions(-) diff --git a/docs/installation.md b/docs/installation.md index 00520cd8..d3177635 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -24,8 +24,36 @@ In order for the package to connect to the Dataverse API, there is an `APIConfig Currently, the supported authentication mechanisms are: -- API Key: The recommended mechanism and the original one from the initial package versions. The API Key should correspond to a particular Dataverse user. +- **API Key**: The recommended authentication mechanism. The API Key should correspond to a particular Dataverse user account. -- Session Cookie: This is an experimental feature primarily designed for Dataverse SPA development. It is necessary to enable the corresponding feature flag in the Dataverse installation (See https://guides.dataverse.org/en/latest/installation/config.html?#feature-flags). It is recommended not to use this mechanism. +- **Session Cookie**: This is an experimental feature primarily designed for Dataverse SPA development. It is necessary to enable the corresponding feature flag in the Dataverse installation to use this mechanism (See https://guides.dataverse.org/en/latest/installation/config.html?#feature-flags). It is recommended not to use this mechanism and instead use API Key authentication. -TODO \ No newline at end of file +It is recommended to globally initialize the `ApiConfig` object from the consuming application, as the configuration will be read on every API call made by the package's use cases. + +For example, in a React application, we can globally initialize the `ApiConfig` object in the `App` file, like this: + +```typescript +ApiConfig.init(, DataverseApiAuthMechanism.API_KEY, ) + +function App() { + /* Yor App code */ +} + +export default App +```` + +The same example but with example values set: + +```typescript +ApiConfig.init('http://localhost:8000/api/v1', DataverseApiAuthMechanism.API_KEY, 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx') + +function App() { + /* Yor App code */ +} + +export default App +```` + +We can initialize the `ApiConfig` object as an unauthenticated user, by setting `undefined` as the API Key value. + +This will allow use cases that do not require authentication to be successfully executed, but those that do require authentication will fail. From 0db5faa5b74611a3da28e776772bbd2d22fc8b69 Mon Sep 17 00:00:00 2001 From: GPortas Date: Wed, 24 Jan 2024 16:09:01 +0000 Subject: [PATCH 05/51] Stash: useCase docs WIP. Added initial docs for GetAllDatasetPreviews use case --- docs/useCases.md | 29 +++++++++++++++++++ .../domain/useCases/GetAllDatasetPreviews.ts | 7 +++++ 2 files changed, 36 insertions(+) diff --git a/docs/useCases.md b/docs/useCases.md index 23a30118..f7b5d79a 100644 --- a/docs/useCases.md +++ b/docs/useCases.md @@ -8,6 +8,35 @@ The different use cases currently available in the package are classified below, ## Datasets +### Read operations + +#### [GetAllDatasetPreviews](../src/datasets/domain/useCases/GetAllDatasetPreviews.ts) + +Returns an instance of [DatasetPreviewSubset](../src/datasets/domain/models/DatasetPreviewSubset.ts) that contains information for each dataset that the calling user can access in the installation. + +##### Example call: + +````typescript +import { getAllDatasetPreviews } from '@iqss/dataverse-client-javascript' + +/* ... */ + +const limit = 10; +const offset = 20; + +getAllDatasetPreviews + .execute(limit, offset) + .then((subset: DatasetPreviewSubset) => { + /* ... */ + }); + +/* ... */ +```` + +Note that `limit` and `offset` are optional parameters for pagination. + +#### [GetDataset](../src/datasets/domain/useCases/GetDataset.ts) + TODO ## Files diff --git a/src/datasets/domain/useCases/GetAllDatasetPreviews.ts b/src/datasets/domain/useCases/GetAllDatasetPreviews.ts index e10cd9c3..66266a9f 100644 --- a/src/datasets/domain/useCases/GetAllDatasetPreviews.ts +++ b/src/datasets/domain/useCases/GetAllDatasetPreviews.ts @@ -9,6 +9,13 @@ export class GetAllDatasetPreviews implements UseCase { this.datasetsRepository = datasetsRepository; } + /** + * Returns an instance of DatasetPreviewSubset that contains information for each dataset that the calling user can access in the installation. + * + * @param {number} [limit] - Limit for pagination (optional). + * @param {number} [offset] - Offset for pagination (optional). + * @returns {Promise} + */ async execute(limit?: number, offset?: number): Promise { return await this.datasetsRepository.getAllDatasetPreviews(limit, offset); } From 9d0dbcb3e60f26dc7b80b967bb57ef50b130bf8b Mon Sep 17 00:00:00 2001 From: GPortas Date: Wed, 24 Jan 2024 16:20:38 +0000 Subject: [PATCH 06/51] Added: GetAllDatasetPreviews doc tweak --- docs/useCases.md | 2 +- src/datasets/domain/useCases/GetAllDatasetPreviews.ts | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/useCases.md b/docs/useCases.md index f7b5d79a..89168365 100644 --- a/docs/useCases.md +++ b/docs/useCases.md @@ -12,7 +12,7 @@ The different use cases currently available in the package are classified below, #### [GetAllDatasetPreviews](../src/datasets/domain/useCases/GetAllDatasetPreviews.ts) -Returns an instance of [DatasetPreviewSubset](../src/datasets/domain/models/DatasetPreviewSubset.ts) that contains information for each dataset that the calling user can access in the installation. +Returns an instance of [DatasetPreviewSubset](../src/datasets/domain/models/DatasetPreviewSubset.ts) that contains reduced information for each dataset that the calling user can access in the installation. ##### Example call: diff --git a/src/datasets/domain/useCases/GetAllDatasetPreviews.ts b/src/datasets/domain/useCases/GetAllDatasetPreviews.ts index 66266a9f..baa0c7ea 100644 --- a/src/datasets/domain/useCases/GetAllDatasetPreviews.ts +++ b/src/datasets/domain/useCases/GetAllDatasetPreviews.ts @@ -10,7 +10,7 @@ export class GetAllDatasetPreviews implements UseCase { } /** - * Returns an instance of DatasetPreviewSubset that contains information for each dataset that the calling user can access in the installation. + * Returns an instance of DatasetPreviewSubset that contains reduced information for each dataset that the calling user can access in the installation. * * @param {number} [limit] - Limit for pagination (optional). * @param {number} [offset] - Offset for pagination (optional). From 16cdf9a987341b69a15aca57492415c5e6f04f63 Mon Sep 17 00:00:00 2001 From: GPortas Date: Fri, 26 Jan 2024 12:34:50 +0000 Subject: [PATCH 07/51] Added: table of contents to useCases md and structure tweaks --- docs/useCases.md | 47 ++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 42 insertions(+), 5 deletions(-) diff --git a/docs/useCases.md b/docs/useCases.md index 89168365..821f37c1 100644 --- a/docs/useCases.md +++ b/docs/useCases.md @@ -6,11 +6,48 @@ This package exposes the functionality in the form of use cases, with the main g The different use cases currently available in the package are classified below, according to the subdomains they target: +## Table of Contents + +- [Datasets](#Datasets) + - [Datasets read use cases](#datasets-read-use-cases) + - [Get a dataset](#get-a-dataset) + - [List all datasets](#list-all-datasets) +- [Installation](#installation) +- [Usage](#usage) +- [Examples](#examples) +- [Conclusion](#conclusion) + ## Datasets -### Read operations +### Datasets read use cases + +#### Get a dataset + +Returns a [Dataset](../src/datasets/domain/models/Dataset.ts) instance, given the parameters that identify it. + +##### Example call: + +````typescript +import { getAllDatasetPreviews } from '@iqss/dataverse-client-javascript' + +/* ... */ -#### [GetAllDatasetPreviews](../src/datasets/domain/useCases/GetAllDatasetPreviews.ts) +const datasetId = 'doi:10.77777/FK2/AAAAAA'; +const datasetVersionId = 20; + +getDataset + .execute(datasetId, datasetVersionId) + .then((dataset: Dataset) => { + /* ... */ + }); + +/* ... */ +```` + +*See [use case](../src/datasets/domain/useCases/GetDataset.ts)* definition. + + +#### List all datasets Returns an instance of [DatasetPreviewSubset](../src/datasets/domain/models/DatasetPreviewSubset.ts) that contains reduced information for each dataset that the calling user can access in the installation. @@ -33,11 +70,11 @@ getAllDatasetPreviews /* ... */ ```` -Note that `limit` and `offset` are optional parameters for pagination. +*See [use case](../src/datasets/domain/useCases/GetAllDatasetPreviews.ts) definition*. -#### [GetDataset](../src/datasets/domain/useCases/GetDataset.ts) +Note that `limit` and `offset` are optional parameters for pagination. -TODO +The `DatasetPreviewSubset`returned instance contains a property called `totalDatasetCount` which is necessary for pagination. ## Files From a0f4ffd9d5ba280b27af9135012716d7600963da Mon Sep 17 00:00:00 2001 From: GPortas Date: Fri, 26 Jan 2024 12:38:25 +0000 Subject: [PATCH 08/51] Added: empty TOC sections to useCases.md --- docs/useCases.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/useCases.md b/docs/useCases.md index 821f37c1..fae3c1eb 100644 --- a/docs/useCases.md +++ b/docs/useCases.md @@ -12,10 +12,10 @@ The different use cases currently available in the package are classified below, - [Datasets read use cases](#datasets-read-use-cases) - [Get a dataset](#get-a-dataset) - [List all datasets](#list-all-datasets) -- [Installation](#installation) -- [Usage](#usage) -- [Examples](#examples) -- [Conclusion](#conclusion) +- [Files](#Files) +- [Metadata Blocks](#metadata-blocks) +- [Users](#Users) +- [Info](#Info) ## Datasets From 167801eeef2f3fc406f96c93934009a379f2930f Mon Sep 17 00:00:00 2001 From: GPortas Date: Fri, 26 Jan 2024 12:42:12 +0000 Subject: [PATCH 09/51] Added: DDD link --- docs/useCases.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/useCases.md b/docs/useCases.md index fae3c1eb..7b4f33b0 100644 --- a/docs/useCases.md +++ b/docs/useCases.md @@ -1,6 +1,6 @@ # 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. +In the context of [Domain-Driven Design (DDD)](https://martinfowler.com/bliki/DomainDrivenDesign.html), 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. From e65723e6ffbfc5ff7d8e1d6612a1d83979a83f7f Mon Sep 17 00:00:00 2001 From: GPortas Date: Fri, 26 Jan 2024 13:03:49 +0000 Subject: [PATCH 10/51] Added: GetDataset use case docs --- docs/useCases.md | 11 +++++++++-- src/datasets/domain/useCases/GetDataset.ts | 8 ++++++++ 2 files changed, 17 insertions(+), 2 deletions(-) diff --git a/docs/useCases.md b/docs/useCases.md index 7b4f33b0..4bbff16c 100644 --- a/docs/useCases.md +++ b/docs/useCases.md @@ -23,7 +23,7 @@ The different use cases currently available in the package are classified below, #### Get a dataset -Returns a [Dataset](../src/datasets/domain/models/Dataset.ts) instance, given the parameters that identify it. +Returns a [Dataset](../src/datasets/domain/models/Dataset.ts) instance, given the search parameters to identify it. ##### Example call: @@ -33,7 +33,7 @@ import { getAllDatasetPreviews } from '@iqss/dataverse-client-javascript' /* ... */ const datasetId = 'doi:10.77777/FK2/AAAAAA'; -const datasetVersionId = 20; +const datasetVersionId = '1.0'; getDataset .execute(datasetId, datasetVersionId) @@ -46,6 +46,13 @@ getDataset *See [use case](../src/datasets/domain/useCases/GetDataset.ts)* definition. +The `datasetId` 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. This parameter is optional and if it is 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`. + + #### List all datasets diff --git a/src/datasets/domain/useCases/GetDataset.ts b/src/datasets/domain/useCases/GetDataset.ts index 4cbef29d..d5e2fc0c 100644 --- a/src/datasets/domain/useCases/GetDataset.ts +++ b/src/datasets/domain/useCases/GetDataset.ts @@ -10,6 +10,14 @@ export class GetDataset implements UseCase { this.datasetsRepository = datasetsRepository; } + /** + * Returns a Dataset instance, given the search parameters to identify it. + * + * @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 {boolean} [includeDeaccessioned=false] - Indicates whether to consider deaccessioned versions in the dataset search or not. The default value is false + * @returns {Promise} + */ async execute( datasetId: number | string, datasetVersionId: string | DatasetNotNumberedVersion = DatasetNotNumberedVersion.LATEST, From bd407a9242a36a575ef944f106632011a1dcb0f5 Mon Sep 17 00:00:00 2001 From: GPortas Date: Fri, 26 Jan 2024 13:05:57 +0000 Subject: [PATCH 11/51] Added: doc tweaks --- docs/useCases.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/useCases.md b/docs/useCases.md index 4bbff16c..1e392dab 100644 --- a/docs/useCases.md +++ b/docs/useCases.md @@ -23,7 +23,7 @@ The different use cases currently available in the package are classified below, #### Get a dataset -Returns a [Dataset](../src/datasets/domain/models/Dataset.ts) instance, given the search parameters to identify it. +Returns a [Dataset](../src/datasets/domain/models/Dataset.ts) instance, given the search parameters to identify it. ##### Example call: @@ -48,9 +48,9 @@ getDataset The `datasetId` 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. This parameter is optional and if it is not set, the default value is: `DatasetNotNumberedVersion.LATEST`. +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, parameter 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 a third optional parameter called `includeDeaccessioned`, which indicates whether to consider deaccessioned versions or not in the dataset search. If not set, parameter the default value is `false`. From 579b98e72a66c13162371008a22067f29cf6e39e Mon Sep 17 00:00:00 2001 From: GPortas Date: Fri, 26 Jan 2024 13:11:41 +0000 Subject: [PATCH 12/51] Stash: GetDatasetCitation docs WIP --- docs/useCases.md | 21 ++++++++++++++------- 1 file changed, 14 insertions(+), 7 deletions(-) diff --git a/docs/useCases.md b/docs/useCases.md index 1e392dab..6d3091e3 100644 --- a/docs/useCases.md +++ b/docs/useCases.md @@ -10,8 +10,9 @@ The different use cases currently available in the package are classified below, - [Datasets](#Datasets) - [Datasets read use cases](#datasets-read-use-cases) - - [Get a dataset](#get-a-dataset) - - [List all datasets](#list-all-datasets) + - [Get a Dataset](#get-a-dataset) + - [Get Citation Text from a Dataset](#get-citation-text-from-a-dataset) + - [List all Datasets](#list-all-datasets) - [Files](#Files) - [Metadata Blocks](#metadata-blocks) - [Users](#Users) @@ -19,9 +20,9 @@ The different use cases currently available in the package are classified below, ## Datasets -### Datasets read use cases +### Datasets Read Use Cases -#### Get a dataset +#### Get a Dataset Returns a [Dataset](../src/datasets/domain/models/Dataset.ts) instance, given the search parameters to identify it. @@ -48,13 +49,19 @@ getDataset The `datasetId` 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, parameter the default value is `DatasetNotNumberedVersion.LATEST`. +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, parameter the default value is `false`. +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`. +#### Get Citation Text from a Dataset +TODO + +##### Example call: + +*See [use case](../src/datasets/domain/useCases/GetDatasetCitation.ts) definition*. -#### List all datasets +#### List All Datasets Returns an instance of [DatasetPreviewSubset](../src/datasets/domain/models/DatasetPreviewSubset.ts) that contains reduced information for each dataset that the calling user can access in the installation. From 291b4a0916f0fbc3af7368fe76863cb016049fb1 Mon Sep 17 00:00:00 2001 From: GPortas Date: Wed, 31 Jan 2024 10:33:20 +0000 Subject: [PATCH 13/51] Added: GetDatasetCitation docs --- docs/useCases.md | 21 ++++++++++++++++++- .../domain/useCases/GetDatasetCitation.ts | 8 +++++++ 2 files changed, 28 insertions(+), 1 deletion(-) diff --git a/docs/useCases.md b/docs/useCases.md index 6d3091e3..ff66d77f 100644 --- a/docs/useCases.md +++ b/docs/useCases.md @@ -55,12 +55,31 @@ There is a third optional parameter called `includeDeaccessioned`, which indicat #### Get Citation Text from a Dataset -TODO +Returns the Dataset citation text. ##### Example call: +````typescript +import { getDatasetCitation } from '@iqss/dataverse-client-javascript' + +/* ... */ + +const datasetId = 'doi:10.77777/FK2/AAAAAA'; +const datasetVersionId = '1.0'; + +getDatasetCitation + .execute(datasetId, datasetVersionId) + .then((citationText: string) => { + /* ... */ + }); + +/* ... */ +```` + *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`. + #### List All Datasets Returns an instance of [DatasetPreviewSubset](../src/datasets/domain/models/DatasetPreviewSubset.ts) that contains reduced information for each dataset that the calling user can access in the installation. diff --git a/src/datasets/domain/useCases/GetDatasetCitation.ts b/src/datasets/domain/useCases/GetDatasetCitation.ts index 384a3e6c..73bba66c 100644 --- a/src/datasets/domain/useCases/GetDatasetCitation.ts +++ b/src/datasets/domain/useCases/GetDatasetCitation.ts @@ -9,6 +9,14 @@ export class GetDatasetCitation implements UseCase { this.datasetsRepository = datasetsRepository; } + /** + * Returns the Dataset citation text. + * + * @param {number} [datasetId] - The dataset identifier. + * @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 {boolean} [includeDeaccessioned=false] - Indicates whether to consider deaccessioned versions in the dataset search or not. The default value is false + * @returns {Promise} + */ async execute( datasetId: number, datasetVersionId: string | DatasetNotNumberedVersion = DatasetNotNumberedVersion.LATEST, From c1039f11ef3acc1103b0aaeee92883381fee71f4 Mon Sep 17 00:00:00 2001 From: GPortas Date: Wed, 31 Jan 2024 10:43:56 +0000 Subject: [PATCH 14/51] Added: getDatasetLocks docs --- docs/useCases.md | 35 ++++++++++++++++--- .../domain/useCases/GetDatasetLocks.ts | 6 ++++ 2 files changed, 37 insertions(+), 4 deletions(-) diff --git a/docs/useCases.md b/docs/useCases.md index ff66d77f..395723f2 100644 --- a/docs/useCases.md +++ b/docs/useCases.md @@ -11,8 +11,9 @@ The different use cases currently available in the package are classified below, - [Datasets](#Datasets) - [Datasets read use cases](#datasets-read-use-cases) - [Get a Dataset](#get-a-dataset) - - [Get Citation Text from a Dataset](#get-citation-text-from-a-dataset) - - [List all Datasets](#list-all-datasets) + - [Get Dataset Citation Text](#get-dataset-citation-text) + - [Get Dataset Locks](#get-dataset-locks) + - [List All Datasets](#list-all-datasets) - [Files](#Files) - [Metadata Blocks](#metadata-blocks) - [Users](#Users) @@ -53,7 +54,7 @@ The `datasetVersionId` parameter can correspond to a numeric version identifier, 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`. -#### Get Citation Text from a Dataset +#### Get Dataset Citation Text Returns the Dataset citation text. @@ -64,7 +65,7 @@ import { getDatasetCitation } from '@iqss/dataverse-client-javascript' /* ... */ -const datasetId = 'doi:10.77777/FK2/AAAAAA'; +const datasetId = 2; const datasetVersionId = '1.0'; getDatasetCitation @@ -80,6 +81,32 @@ getDatasetCitation 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`. +#### Get Dataset Locks + +Returns a [DatasetLock](../src/datasets/domain/models/DatasetLock.ts) array of all locks present in a Dataset. + +##### Example call: + +````typescript +import { getDatasetLocks } from '@iqss/dataverse-client-javascript' + +/* ... */ + +const datasetId = 'doi:10.77777/FK2/AAAAAA'; + +getDatasetLocks + .execute(datasetId) + .then((datasetLocks: DatasetLock[]) => { + /* ... */ + }); + +/* ... */ +```` + +*See [use case](../src/datasets/domain/useCases/GetDatasetLocks.ts) definition*. + +The `datasetId` parameter can be a string, for persistent identifiers, or a number, for numeric identifiers. + #### List All Datasets Returns an instance of [DatasetPreviewSubset](../src/datasets/domain/models/DatasetPreviewSubset.ts) that contains reduced information for each dataset that the calling user can access in the installation. diff --git a/src/datasets/domain/useCases/GetDatasetLocks.ts b/src/datasets/domain/useCases/GetDatasetLocks.ts index f44dccda..b4164567 100644 --- a/src/datasets/domain/useCases/GetDatasetLocks.ts +++ b/src/datasets/domain/useCases/GetDatasetLocks.ts @@ -9,6 +9,12 @@ export class GetDatasetLocks implements UseCase { this.datasetsRepository = datasetsRepository; } + /** + * Returns all locks present in a Dataset. + * + * @param {number | string} [datasetId] - The dataset identifier, which can be a string (for persistent identifiers), or a number (for numeric identifiers). + * @returns {Promise} + */ async execute(datasetId: number | string): Promise { return await this.datasetsRepository.getDatasetLocks(datasetId); } From 5a76991fdeaa538f2e5c8081ef48e319344b2254 Mon Sep 17 00:00:00 2001 From: GPortas Date: Wed, 31 Jan 2024 10:49:35 +0000 Subject: [PATCH 15/51] Added: GetDatasetSummaryFieldNames docs --- docs/useCases.md | 23 +++++++++++++++++++ .../useCases/GetDatasetSummaryFieldNames.ts | 5 ++++ 2 files changed, 28 insertions(+) diff --git a/docs/useCases.md b/docs/useCases.md index 395723f2..bcedbf1c 100644 --- a/docs/useCases.md +++ b/docs/useCases.md @@ -13,6 +13,7 @@ The different use cases currently available in the package are classified below, - [Get a Dataset](#get-a-dataset) - [Get Dataset Citation Text](#get-dataset-citation-text) - [Get Dataset Locks](#get-dataset-locks) + - [Get Dataset Summary Field Names](#get-dataset-summary-field-names) - [List All Datasets](#list-all-datasets) - [Files](#Files) - [Metadata Blocks](#metadata-blocks) @@ -107,6 +108,28 @@ getDatasetLocks 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: + +````typescript +import { getDatasetSummaryFieldNames } from '@iqss/dataverse-client-javascript' + +/* ... */ + +getDatasetSummaryFieldNames + .execute() + .then((names: string[]) => { + /* ... */ + }); + +/* ... */ +```` + +*See [use case](../src/datasets/domain/useCases/GetDatasetSummaryFieldNames.ts) definition*. + #### List All Datasets Returns an instance of [DatasetPreviewSubset](../src/datasets/domain/models/DatasetPreviewSubset.ts) that contains reduced information for each dataset that the calling user can access in the installation. diff --git a/src/datasets/domain/useCases/GetDatasetSummaryFieldNames.ts b/src/datasets/domain/useCases/GetDatasetSummaryFieldNames.ts index 4041e408..4b67afc3 100644 --- a/src/datasets/domain/useCases/GetDatasetSummaryFieldNames.ts +++ b/src/datasets/domain/useCases/GetDatasetSummaryFieldNames.ts @@ -8,6 +8,11 @@ export class GetDatasetSummaryFieldNames implements UseCase { this.datasetsRepository = datasetsRepository; } + /** + * Returns the names of the dataset summary fields configured in the installation. + * + * @returns {Promise} + */ async execute(): Promise { return await this.datasetsRepository.getDatasetSummaryFieldNames(); } From 2a175bc9de9c91b83642532c5fa3d1f00d4419c8 Mon Sep 17 00:00:00 2001 From: GPortas Date: Wed, 31 Jan 2024 10:55:29 +0000 Subject: [PATCH 16/51] Added: GetDatasetUserPermissions docs --- docs/useCases.md | 27 +++++++++++++++++++ .../useCases/GetDatasetUserPermissions.ts | 6 +++++ 2 files changed, 33 insertions(+) diff --git a/docs/useCases.md b/docs/useCases.md index bcedbf1c..448a91e2 100644 --- a/docs/useCases.md +++ b/docs/useCases.md @@ -14,6 +14,7 @@ The different use cases currently available in the package are classified below, - [Get Dataset Citation Text](#get-dataset-citation-text) - [Get Dataset Locks](#get-dataset-locks) - [Get Dataset Summary Field Names](#get-dataset-summary-field-names) + - [Get User Permissions on a Dataset](#get-user-permissions-on-a-dataset) - [List All Datasets](#list-all-datasets) - [Files](#Files) - [Metadata Blocks](#metadata-blocks) @@ -130,6 +131,32 @@ getDatasetSummaryFieldNames *See [use case](../src/datasets/domain/useCases/GetDatasetSummaryFieldNames.ts) definition*. +#### Get User Permissions on a Dataset + +Returns an instance of [DatasetUserPermissions](../src/datasets/domain/models/DatasetUserPermissions.ts) that includes the permissions that the calling user has on a particular Dataset. + +##### Example call: + +````typescript +import { getDatasetUserPermissions } from '@iqss/dataverse-client-javascript' + +/* ... */ + +const datasetId = 'doi:10.77777/FK2/AAAAAA'; + +getDatasetUserPermissions + .execute(datasetId) + .then((permissions: DatasetUserPermissions) => { + /* ... */ + }); + +/* ... */ +```` + +*See [use case](../src/datasets/domain/useCases/GetDatasetUserPermissions.ts) definition*. + +The `datasetId` parameter can be a string, for persistent identifiers, or a number, for numeric identifiers. + #### List All Datasets Returns an instance of [DatasetPreviewSubset](../src/datasets/domain/models/DatasetPreviewSubset.ts) that contains reduced information for each dataset that the calling user can access in the installation. diff --git a/src/datasets/domain/useCases/GetDatasetUserPermissions.ts b/src/datasets/domain/useCases/GetDatasetUserPermissions.ts index 594e0ba6..13055977 100644 --- a/src/datasets/domain/useCases/GetDatasetUserPermissions.ts +++ b/src/datasets/domain/useCases/GetDatasetUserPermissions.ts @@ -9,6 +9,12 @@ export class GetDatasetUserPermissions implements UseCase} + */ async execute(datasetId: number | string): Promise { return await this.datasetsRepository.getDatasetUserPermissions(datasetId); } From ed05893c41124953a1023e73ececd2bd5adaf736 Mon Sep 17 00:00:00 2001 From: GPortas Date: Wed, 31 Jan 2024 15:07:08 +0000 Subject: [PATCH 17/51] Added: Private URL use cases docs --- docs/useCases.md | 154 +++++++++++------- .../domain/useCases/GetPrivateUrlDataset.ts | 6 + .../useCases/GetPrivateUrlDatasetCitation.ts | 6 + 3 files changed, 105 insertions(+), 61 deletions(-) diff --git a/docs/useCases.md b/docs/useCases.md index 448a91e2..ceffb1b1 100644 --- a/docs/useCases.md +++ b/docs/useCases.md @@ -1,6 +1,6 @@ # Use Cases -In the context of [Domain-Driven Design (DDD)](https://martinfowler.com/bliki/DomainDrivenDesign.html), 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. +In the context of [Domain-Driven Design (DDD)](https://martinfowler.com/bliki/DomainDrivenDesign.html), 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. @@ -11,7 +11,9 @@ The different use cases currently available in the package are classified below, - [Datasets](#Datasets) - [Datasets read use cases](#datasets-read-use-cases) - [Get a Dataset](#get-a-dataset) + - [Get Dataset By Private URL Token](#get-dataset-by-private-url-token) - [Get Dataset Citation Text](#get-dataset-citation-text) + - [Get Dataset Citation Text By Private URL](#get-dataset-citation-text-by-private-url) - [Get Dataset Locks](#get-dataset-locks) - [Get Dataset Summary Field Names](#get-dataset-summary-field-names) - [Get User Permissions on a Dataset](#get-user-permissions-on-a-dataset) @@ -31,24 +33,22 @@ Returns a [Dataset](../src/datasets/domain/models/Dataset.ts) instance, given th ##### Example call: -````typescript -import { getAllDatasetPreviews } from '@iqss/dataverse-client-javascript' +```typescript +import { getAllDatasetPreviews } from '@iqss/dataverse-client-javascript'; /* ... */ const datasetId = 'doi:10.77777/FK2/AAAAAA'; const datasetVersionId = '1.0'; -getDataset - .execute(datasetId, datasetVersionId) - .then((dataset: Dataset) => { - /* ... */ - }); - +getDataset.execute(datasetId, datasetVersionId).then((dataset: Dataset) => { + /* ... */ +}); + /* ... */ -```` +``` -*See [use case](../src/datasets/domain/useCases/GetDataset.ts)* definition. +_See [use case](../src/datasets/domain/useCases/GetDataset.ts)_ definition. The `datasetId` parameter can be a string, for persistent identifiers, or a number, for numeric identifiers. @@ -56,56 +56,94 @@ The `datasetVersionId` parameter can correspond to a numeric version identifier, 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`. +#### Get Dataset By Private URL Token + +Returns a [Dataset](../src/datasets/domain/models/Dataset.ts) instance, given an associated Private URL Token. + +```typescript +import { getPrivateUrlDataset } from '@iqss/dataverse-client-javascript'; + +/* ... */ + +const token = 'a56444bc-7697-4711-8964-e0577f055fd2'; + +getPrivateUrlDataset.execute(token).then((dataset: Dataset) => { + /* ... */ +}); + +/* ... */ +``` + +_See [use case](../src/datasets/domain/useCases/GetPrivateUrlDataset.ts)_ definition. + #### Get Dataset Citation Text Returns the Dataset citation text. ##### Example call: -````typescript -import { getDatasetCitation } from '@iqss/dataverse-client-javascript' +```typescript +import { getDatasetCitation } from '@iqss/dataverse-client-javascript'; /* ... */ const datasetId = 2; const datasetVersionId = '1.0'; -getDatasetCitation - .execute(datasetId, datasetVersionId) - .then((citationText: string) => { - /* ... */ - }); - +getDatasetCitation.execute(datasetId, datasetVersionId).then((citationText: string) => { + /* ... */ +}); + /* ... */ -```` +``` -*See [use case](../src/datasets/domain/useCases/GetDatasetCitation.ts) definition*. +_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`. +#### Get Dataset Citation Text By Private URL + +Returns the Dataset citation text, given an associated Private URL Token. + +##### Example call: + +```typescript +import { getPrivateUrlDatasetCitation } from '@iqss/dataverse-client-javascript'; + +/* ... */ + +const token = 'a56444bc-7697-4711-8964-e0577f055fd2'; + +getPrivateUrlDatasetCitation.execute(token).then((citationText: string) => { + /* ... */ +}); + +/* ... */ +``` + +_See [use case](../src/datasets/domain/useCases/GetPrivateUrlDatasetCitation.ts) definition_. + #### Get Dataset Locks Returns a [DatasetLock](../src/datasets/domain/models/DatasetLock.ts) array of all locks present in a Dataset. ##### Example call: -````typescript -import { getDatasetLocks } from '@iqss/dataverse-client-javascript' +```typescript +import { getDatasetLocks } from '@iqss/dataverse-client-javascript'; /* ... */ const datasetId = 'doi:10.77777/FK2/AAAAAA'; -getDatasetLocks - .execute(datasetId) - .then((datasetLocks: DatasetLock[]) => { - /* ... */ - }); - +getDatasetLocks.execute(datasetId).then((datasetLocks: DatasetLock[]) => { + /* ... */ +}); + /* ... */ -```` +``` -*See [use case](../src/datasets/domain/useCases/GetDatasetLocks.ts) definition*. +_See [use case](../src/datasets/domain/useCases/GetDatasetLocks.ts) definition_. The `datasetId` parameter can be a string, for persistent identifiers, or a number, for numeric identifiers. @@ -115,21 +153,19 @@ Returns the names of the dataset summary fields configured in the installation. ##### Example call: -````typescript -import { getDatasetSummaryFieldNames } from '@iqss/dataverse-client-javascript' +```typescript +import { getDatasetSummaryFieldNames } from '@iqss/dataverse-client-javascript'; /* ... */ -getDatasetSummaryFieldNames - .execute() - .then((names: string[]) => { - /* ... */ - }); - +getDatasetSummaryFieldNames.execute().then((names: string[]) => { + /* ... */ +}); + /* ... */ -```` +``` -*See [use case](../src/datasets/domain/useCases/GetDatasetSummaryFieldNames.ts) definition*. +_See [use case](../src/datasets/domain/useCases/GetDatasetSummaryFieldNames.ts) definition_. #### Get User Permissions on a Dataset @@ -137,23 +173,21 @@ Returns an instance of [DatasetUserPermissions](../src/datasets/domain/models/Da ##### Example call: -````typescript -import { getDatasetUserPermissions } from '@iqss/dataverse-client-javascript' +```typescript +import { getDatasetUserPermissions } from '@iqss/dataverse-client-javascript'; /* ... */ const datasetId = 'doi:10.77777/FK2/AAAAAA'; -getDatasetUserPermissions - .execute(datasetId) - .then((permissions: DatasetUserPermissions) => { - /* ... */ - }); - +getDatasetUserPermissions.execute(datasetId).then((permissions: DatasetUserPermissions) => { + /* ... */ +}); + /* ... */ -```` +``` -*See [use case](../src/datasets/domain/useCases/GetDatasetUserPermissions.ts) definition*. +_See [use case](../src/datasets/domain/useCases/GetDatasetUserPermissions.ts) definition_. The `datasetId` parameter can be a string, for persistent identifiers, or a number, for numeric identifiers. @@ -163,24 +197,22 @@ Returns an instance of [DatasetPreviewSubset](../src/datasets/domain/models/Data ##### Example call: -````typescript -import { getAllDatasetPreviews } from '@iqss/dataverse-client-javascript' +```typescript +import { getAllDatasetPreviews } from '@iqss/dataverse-client-javascript'; /* ... */ const limit = 10; const offset = 20; -getAllDatasetPreviews - .execute(limit, offset) - .then((subset: DatasetPreviewSubset) => { - /* ... */ - }); - +getAllDatasetPreviews.execute(limit, offset).then((subset: DatasetPreviewSubset) => { + /* ... */ +}); + /* ... */ -```` +``` -*See [use case](../src/datasets/domain/useCases/GetAllDatasetPreviews.ts) definition*. +_See [use case](../src/datasets/domain/useCases/GetAllDatasetPreviews.ts) definition_. Note that `limit` and `offset` are optional parameters for pagination. diff --git a/src/datasets/domain/useCases/GetPrivateUrlDataset.ts b/src/datasets/domain/useCases/GetPrivateUrlDataset.ts index 3580632c..2e05906d 100644 --- a/src/datasets/domain/useCases/GetPrivateUrlDataset.ts +++ b/src/datasets/domain/useCases/GetPrivateUrlDataset.ts @@ -9,6 +9,12 @@ export class GetPrivateUrlDataset implements UseCase { this.datasetsRepository = datasetsRepository; } + /** + * Returns a Dataset instance, given an associated Private URL Token. + * + * @param {string} [token] - A Private URL token. + * @returns {Promise} + */ async execute(token: string): Promise { return await this.datasetsRepository.getPrivateUrlDataset(token); } diff --git a/src/datasets/domain/useCases/GetPrivateUrlDatasetCitation.ts b/src/datasets/domain/useCases/GetPrivateUrlDatasetCitation.ts index 7ff06f47..508376e8 100644 --- a/src/datasets/domain/useCases/GetPrivateUrlDatasetCitation.ts +++ b/src/datasets/domain/useCases/GetPrivateUrlDatasetCitation.ts @@ -8,6 +8,12 @@ export class GetPrivateUrlDatasetCitation implements UseCase { this.datasetsRepository = datasetsRepository; } + /** + * Returns the Dataset citation text, given an associated Private URL Token. + * + * @param {string} [token] - A Private URL token. + * @returns {Promise} + */ async execute(token: string): Promise { return await this.datasetsRepository.getPrivateUrlDatasetCitation(token); } From 54d92f0e914c588d4c5af92dda4e862ace90d157 Mon Sep 17 00:00:00 2001 From: GPortas Date: Thu, 1 Feb 2024 12:44:31 +0000 Subject: [PATCH 18/51] Added: GetDatasetFiles docs --- docs/useCases.md | 61 +++++++++++++++++++- src/files/domain/useCases/GetDatasetFiles.ts | 12 +++- 2 files changed, 71 insertions(+), 2 deletions(-) diff --git a/docs/useCases.md b/docs/useCases.md index ceffb1b1..124b2b48 100644 --- a/docs/useCases.md +++ b/docs/useCases.md @@ -19,6 +19,8 @@ The different use cases currently available in the package are classified below, - [Get User Permissions on a Dataset](#get-user-permissions-on-a-dataset) - [List All Datasets](#list-all-datasets) - [Files](#Files) + - [Files read use cases](#files-read-use-cases) + - [List Files in a Dataset](#list-files-in-a-dataset) - [Metadata Blocks](#metadata-blocks) - [Users](#Users) - [Info](#Info) @@ -220,7 +222,64 @@ The `DatasetPreviewSubset`returned instance contains a property called `totalDat ## Files -TODO +### Files read use cases + +#### List Files in a Dataset + +Returns an instance of [FilesSubset](../src/files/domain/models/FilesSubset.ts), which contains the files from the requested Dataset and page (if pagination parameters are set). + +##### Example call: + +```typescript +import { getDatasetFiles } from '@iqss/dataverse-client-javascript'; + +/* ... */ + +const datasetId = 2; +const datasetVersionId = '1.0'; + +getDatasetFiles.execute(datasetId, datasetVersionId).then((subset: FilesSubset) => { + /* ... */ +}); + +/* ... */ +``` + +_See [use case](../src/files/domain/useCases/GetDatasetFiles.ts) definition_. + +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](../src/files/domain/models/FileCriteria.ts)) Supports filtering the files by different file properties. +- **fileOrderCriteria**: ([FileOrderCriteria](../src/files/domain/models/FileCriteria.ts)) Supports ordering the results according to different criteria. If not set, the defalt value is `FileOrderCriteria.NAME_AZ`. + +##### Example call using optional parameters: + +```typescript +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) => { + /* ... */ + }); + +/* ... */ +``` ## Metadata Blocks diff --git a/src/files/domain/useCases/GetDatasetFiles.ts b/src/files/domain/useCases/GetDatasetFiles.ts index 9099f9a3..d533f815 100644 --- a/src/files/domain/useCases/GetDatasetFiles.ts +++ b/src/files/domain/useCases/GetDatasetFiles.ts @@ -1,6 +1,6 @@ import { UseCase } from '../../../core/domain/useCases/UseCase'; import { IFilesRepository } from '../repositories/IFilesRepository'; -import { FilesSubset } from "../models/FilesSubset"; +import { FilesSubset } from '../models/FilesSubset'; import { FileSearchCriteria, FileOrderCriteria } from '../models/FileCriteria'; import { DatasetNotNumberedVersion } from '../../../datasets'; @@ -11,6 +11,16 @@ export class GetDatasetFiles implements UseCase { this.filesRepository = filesRepository; } + /** + * Returns an instance of FilesSubset, which contains the files from the requested Dataset and page (if pagination parameters are set). + * + * @param {boolean} [includeDeaccessioned=false] - Indicates whether to consider deaccessioned versions in the dataset search or not. The default value is false. + * @param {number} [limit] - Limit for pagination (optional). + * @param {number} [offset] - Offset for pagination (optional). + * @param {FileSearchCriteria} [fileSearchCriteria] - Supports filtering the files by different file properties (optional). + * @param {FileOrderCriteria} [fileOrderCriteria=FileOrderCriteria.NAME_AZ] - Supports ordering the results according to different criteria. If not set, the defalt value is FileOrderCriteria.NAME_AZ. + * @returns {Promise} + */ async execute( datasetId: number | string, datasetVersionId: string | DatasetNotNumberedVersion = DatasetNotNumberedVersion.LATEST, From 71cc2f0ef9de7c3a67bcb25a04810c8aa2829454 Mon Sep 17 00:00:00 2001 From: GPortas Date: Thu, 1 Feb 2024 12:49:05 +0000 Subject: [PATCH 19/51] Fixed: usecase doc title --- docs/useCases.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/useCases.md b/docs/useCases.md index 124b2b48..b73badeb 100644 --- a/docs/useCases.md +++ b/docs/useCases.md @@ -13,7 +13,7 @@ The different use cases currently available in the package are classified below, - [Get a Dataset](#get-a-dataset) - [Get Dataset By Private URL Token](#get-dataset-by-private-url-token) - [Get Dataset Citation Text](#get-dataset-citation-text) - - [Get Dataset Citation Text By Private URL](#get-dataset-citation-text-by-private-url) + - [Get Dataset Citation Text By Private URL Token](#get-dataset-citation-text-by-private-url-token) - [Get Dataset Locks](#get-dataset-locks) - [Get Dataset Summary Field Names](#get-dataset-summary-field-names) - [Get User Permissions on a Dataset](#get-user-permissions-on-a-dataset) @@ -103,7 +103,7 @@ _See [use case](../src/datasets/domain/useCases/GetDatasetCitation.ts) definitio 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`. -#### Get Dataset Citation Text By Private URL +#### Get Dataset Citation Text By Private URL Token Returns the Dataset citation text, given an associated Private URL Token. From 4f19efd234061c0a9184e9f80df9cd544aca1f11 Mon Sep 17 00:00:00 2001 From: GPortas Date: Thu, 1 Feb 2024 13:21:31 +0000 Subject: [PATCH 20/51] Added: GetDatasetFileCounts docs --- docs/useCases.md | 33 +++++++++++++++++++ .../domain/useCases/GetDatasetFileCounts.ts | 9 +++++ src/files/domain/useCases/GetDatasetFiles.ts | 2 ++ 3 files changed, 44 insertions(+) diff --git a/docs/useCases.md b/docs/useCases.md index b73badeb..26fd96d9 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 File Counts in a Dataset](#get-file-counts-in-a-dataset) - [List Files in a Dataset](#list-files-in-a-dataset) - [Metadata Blocks](#metadata-blocks) - [Users](#Users) @@ -281,6 +282,38 @@ getDatasetFiles /* ... */ ``` +### 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: + +- **Per content type** +- **Per category name** +- **Per tabular tag name** +- **Per access status** (Possible values: *Public*, *Restricted*, *EmbargoedThenRestricted*, *EmbargoedThenPublic*) + +##### Example call: + +```typescript +import { getDatasetFileCounts } from '@iqss/dataverse-client-javascript'; + +/* ... */ + +const datasetId = 2; +const datasetVersionId = '1.0'; + +getDatasetFileCounts.execute(datasetId, datasetVersionId).then((subset: FilesSubset) => { + /* ... */ +}); + +/* ... */ +``` + +_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`. + +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. + ## Metadata Blocks TODO diff --git a/src/files/domain/useCases/GetDatasetFileCounts.ts b/src/files/domain/useCases/GetDatasetFileCounts.ts index 2ca43c03..6e69b112 100644 --- a/src/files/domain/useCases/GetDatasetFileCounts.ts +++ b/src/files/domain/useCases/GetDatasetFileCounts.ts @@ -11,6 +11,15 @@ export class GetDatasetFileCounts implements UseCase { this.filesRepository = filesRepository; } + /** + * Returns an instance of FileCounts, containing the requested Dataset total file count, as well as file counts for different file properties. + * + * @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 {boolean} [includeDeaccessioned=false] - Indicates whether to consider deaccessioned versions in the dataset search or not. The default value is false. + * @param {FileSearchCriteria} [fileSearchCriteria] - Supports filtering the files by different file properties (optional). + * @returns {Promise} + */ async execute( datasetId: number | string, datasetVersionId: string | DatasetNotNumberedVersion = DatasetNotNumberedVersion.LATEST, diff --git a/src/files/domain/useCases/GetDatasetFiles.ts b/src/files/domain/useCases/GetDatasetFiles.ts index d533f815..9162a910 100644 --- a/src/files/domain/useCases/GetDatasetFiles.ts +++ b/src/files/domain/useCases/GetDatasetFiles.ts @@ -14,6 +14,8 @@ export class GetDatasetFiles implements UseCase { /** * Returns an instance of FilesSubset, which contains the files from the requested Dataset and page (if pagination parameters are set). * + * @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 {boolean} [includeDeaccessioned=false] - Indicates whether to consider deaccessioned versions in the dataset search or not. The default value is false. * @param {number} [limit] - Limit for pagination (optional). * @param {number} [offset] - Offset for pagination (optional). From 4714b74a52019a9a0edf0e4a6d4284140254de11 Mon Sep 17 00:00:00 2001 From: GPortas Date: Fri, 2 Feb 2024 11:10:40 +0000 Subject: [PATCH 21/51] Added: doc tweaks for getDatasetFileCounts use case --- docs/useCases.md | 27 +++++++++++++++++++++++++-- 1 file changed, 25 insertions(+), 2 deletions(-) diff --git a/docs/useCases.md b/docs/useCases.md index 26fd96d9..9345ba12 100644 --- a/docs/useCases.md +++ b/docs/useCases.md @@ -289,7 +289,7 @@ Returns an instance of [FileCounts](../src/files/domain/models/FileCounts.ts), c - **Per content type** - **Per category name** - **Per tabular tag name** -- **Per access status** (Possible values: *Public*, *Restricted*, *EmbargoedThenRestricted*, *EmbargoedThenPublic*) +- **Per access status** (Possible values: _Public_, _Restricted_, _EmbargoedThenRestricted_, _EmbargoedThenPublic_) ##### Example call: @@ -301,7 +301,7 @@ import { getDatasetFileCounts } from '@iqss/dataverse-client-javascript'; const datasetId = 2; const datasetVersionId = '1.0'; -getDatasetFileCounts.execute(datasetId, datasetVersionId).then((subset: FilesSubset) => { +getDatasetFileCounts.execute(datasetId, datasetVersionId).then((fileCounts: FileCounts) => { /* ... */ }); @@ -314,6 +314,29 @@ There is a third optional parameter called `includeDeaccessioned`, which indicat 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. +##### Example call using optional parameters: + +```typescript +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) => { + /* ... */ + }); + +/* ... */ +``` + ## Metadata Blocks TODO From b419cd4726cc2d445bd335a2148a3a85a59bc0ea Mon Sep 17 00:00:00 2001 From: GPortas Date: Fri, 2 Feb 2024 14:07:40 +0000 Subject: [PATCH 22/51] Added: getDatasetFilesTotalDownloadSize docs --- docs/useCases.md | 66 +++++++++++++++++-- .../GetDatasetFilesTotalDownloadSize.ts | 10 +++ 2 files changed, 71 insertions(+), 5 deletions(-) diff --git a/docs/useCases.md b/docs/useCases.md index 9345ba12..c7ffb5fb 100644 --- a/docs/useCases.md +++ b/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 diff --git a/src/files/domain/useCases/GetDatasetFilesTotalDownloadSize.ts b/src/files/domain/useCases/GetDatasetFilesTotalDownloadSize.ts index 8fdbaa6a..c6a32c93 100644 --- a/src/files/domain/useCases/GetDatasetFilesTotalDownloadSize.ts +++ b/src/files/domain/useCases/GetDatasetFilesTotalDownloadSize.ts @@ -11,6 +11,16 @@ export class GetDatasetFilesTotalDownloadSize implements UseCase { 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} + */ async execute( datasetId: number | string, datasetVersionId: string | DatasetNotNumberedVersion = DatasetNotNumberedVersion.LATEST, From b1886fe21432e99d67f4649e9844a1922d1b76bd Mon Sep 17 00:00:00 2001 From: GPortas Date: Fri, 2 Feb 2024 14:23:19 +0000 Subject: [PATCH 23/51] Added: GetFileDownloadCount docs and general doc structure tweaks --- docs/useCases.md | 163 +++++++++++------- .../domain/useCases/GetFileDownloadCount.ts | 6 + 2 files changed, 105 insertions(+), 64 deletions(-) diff --git a/docs/useCases.md b/docs/useCases.md index c7ffb5fb..2b94727a 100644 --- a/docs/useCases.md +++ b/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 File Download Count](#get-file-download-count) - [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) @@ -101,7 +102,9 @@ getDatasetCitation.execute(datasetId, datasetVersionId).then((citationText: stri /* ... */ ``` -_See [use case](../src/datasets/domain/useCases/GetDatasetCitation.ts) definition_. +_See [use case](../src/datasets/domain/useCases/GetDatasetCitation.ts) 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`. @@ -125,7 +128,7 @@ getPrivateUrlDatasetCitation.execute(token).then((citationText: string) => { /* ... */ ``` -_See [use case](../src/datasets/domain/useCases/GetPrivateUrlDatasetCitation.ts) definition_. +_See [use case](../src/datasets/domain/useCases/GetPrivateUrlDatasetCitation.ts) implementation. #### Get Dataset Locks @@ -147,7 +150,7 @@ getDatasetLocks.execute(datasetId).then((datasetLocks: DatasetLock[]) => { /* ... */ ``` -_See [use case](../src/datasets/domain/useCases/GetDatasetLocks.ts) definition_. +_See [use case](../src/datasets/domain/useCases/GetDatasetLocks.ts) implementation. The `datasetId` parameter can be a string, for persistent identifiers, or a number, for numeric identifiers. @@ -169,7 +172,7 @@ getDatasetSummaryFieldNames.execute().then((names: string[]) => { /* ... */ ``` -_See [use case](../src/datasets/domain/useCases/GetDatasetSummaryFieldNames.ts) definition_. +_See [use case](../src/datasets/domain/useCases/GetDatasetSummaryFieldNames.ts) implementation. #### Get User Permissions on a Dataset @@ -191,7 +194,7 @@ getDatasetUserPermissions.execute(datasetId).then((permissions: DatasetUserPermi /* ... */ ``` -_See [use case](../src/datasets/domain/useCases/GetDatasetUserPermissions.ts) definition_. +_See [use case](../src/datasets/domain/useCases/GetDatasetUserPermissions.ts) implementation. The `datasetId` parameter can be a string, for persistent identifiers, or a number, for numeric identifiers. @@ -216,7 +219,7 @@ getAllDatasetPreviews.execute(limit, offset).then((subset: DatasetPreviewSubset) /* ... */ ``` -_See [use case](../src/datasets/domain/useCases/GetAllDatasetPreviews.ts) definition_. +_See [use case](../src/datasets/domain/useCases/GetAllDatasetPreviews.ts) implementation. Note that `limit` and `offset` are optional parameters for pagination. @@ -226,167 +229,199 @@ The `DatasetPreviewSubset`returned instance contains a property called `totalDat ### Files read use cases -#### List Files in a Dataset +#### Get File Counts in a Dataset -Returns an instance of [FilesSubset](../src/files/domain/models/FilesSubset.ts), which contains the files from the requested Dataset and page (if pagination parameters are set). +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: + +- **Per content type** +- **Per category name** +- **Per tabular tag name** +- **Per access status** (Possible values: _Public_, _Restricted_, _EmbargoedThenRestricted_, _EmbargoedThenPublic_) ##### Example call: ```typescript -import { getDatasetFiles } from '@iqss/dataverse-client-javascript'; +import { getDatasetFileCounts } from '@iqss/dataverse-client-javascript'; /* ... */ const datasetId = 2; const datasetVersionId = '1.0'; -getDatasetFiles.execute(datasetId, datasetVersionId).then((subset: FilesSubset) => { +getDatasetFileCounts.execute(datasetId, datasetVersionId).then((fileCounts: FileCounts) => { /* ... */ }); /* ... */ ``` -_See [use case](../src/files/domain/useCases/GetDatasetFiles.ts) definition_. +_See [use case](../src/files/domain/useCases/GetDatasetFileCounts.ts) implementation. -This use case supports the following optional parameters depending on the search goals: +The `datasetId` parameter can be a string, for persistent identifiers, or a number, for numeric identifiers. -- **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](../src/files/domain/models/FileCriteria.ts)) Supports filtering the files by different file properties. -- **fileOrderCriteria**: ([FileOrderCriteria](../src/files/domain/models/FileCriteria.ts)) Supports ordering the results according to different criteria. If not set, the defalt value is `FileOrderCriteria.NAME_AZ`. +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](../src/files/domain/models/FileCriteria.ts) object to retrieve counts only for files that match the specified criteria. ##### Example call using optional parameters: ```typescript -import { getDatasetFiles } from '@iqss/dataverse-client-javascript'; +import { getDatasetFileCounts } 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', + categoryName: 'physics', }; -const orderCriteria: FileOrderCriteria = FileOrderCriteria.NEWEST; -getDatasetFiles - .execute(datasetId, datasetVersionId, includeDeaccessioned, limit, offset, searchCriteria, orderCriteria) - .then((subset: FilesSubset) => { +getDatasetFileCounts + .execute(datasetId, datasetVersionId, includeDeaccessioned, searchCriteria) + .then((fileCounts: FileCounts) => { /* ... */ }); /* ... */ ``` -### Get File Counts in a Dataset +#### Get File Download Count -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: +Provides the download count for a particular File. -- **Per content type** -- **Per category name** -- **Per tabular tag name** -- **Per access status** (Possible values: _Public_, _Restricted_, _EmbargoedThenRestricted_, _EmbargoedThenPublic_) +##### Example call: + +```typescript +import { getFileDownloadCount } from '@iqss/dataverse-client-javascript'; + +/* ... */ + +const fileId: number = 2; + +getFileDownloadCount.execute(fileId).then((count: number) => { + /* ... */ +}); + +/* ... */ +``` + +_See [use case](../src/files/domain/useCases/GetFileDownloadCount.ts) 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: ```typescript -import { getDatasetFileCounts } from '@iqss/dataverse-client-javascript'; +import { getDatasetFilesTotalDownloadSize } from '@iqss/dataverse-client-javascript'; /* ... */ -const datasetId = 2; -const datasetVersionId = '1.0'; +const datasetId: number = 2; +const datasetVersionId: string = '1.0'; -getDatasetFileCounts.execute(datasetId, datasetVersionId).then((fileCounts: FileCounts) => { +getDatasetFilesTotalDownloadSize.execute(datasetId, datasetVersionId).then((size: number) => { /* ... */ }); /* ... */ ``` -_See [use case](../src/files/domain/useCases/GetDatasetFileCounts.ts) definition_. +_See [use case](../src/files/domain/useCases/GetDatasetFilesTotalDownloadSize.ts) implementation. -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`. +The `datasetId` parameter can be a string, for persistent identifiers, or a number, for numeric identifiers. -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. +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 { getDatasetFileCounts } from '@iqss/dataverse-client-javascript'; +import { getDatasetFilesTotalDownloadSize } from '@iqss/dataverse-client-javascript'; /* ... */ const datasetId: number = 2; const datasetVersionId: string = '1.0'; -const includeDeaccessioned: boolean = true; -const searchCriteria: FileSearchCriteria = { +const mode: FileDownloadSizeMode = FileDownloadSizeMode.ARCHIVAL; +const searchCriteria: FileDownloadSizeMode = { categoryName: 'physics', }; +const includeDeaccessioned: boolean = true; -getDatasetFileCounts - .execute(datasetId, datasetVersionId, includeDeaccessioned, searchCriteria) - .then((fileCounts: FileCounts) => { +getDatasetFilesTotalDownloadSize + .execute(datasetId, datasetVersionId, mode, searchCriteria, includeDeaccessioned) + .then((size: number) => { /* ... */ }); /* ... */ ``` -### Get the size of Downloading all the files of a Dataset Version +#### List Files in a Dataset -Returns the combined size in bytes of all the files available for download from a particular Dataset. +Returns an instance of [FilesSubset](../src/files/domain/models/FilesSubset.ts), which contains the files from the requested Dataset and page (if pagination parameters are set). ##### Example call: ```typescript -import { getDatasetFilesTotalDownloadSize } from '@iqss/dataverse-client-javascript'; +import { getDatasetFiles } from '@iqss/dataverse-client-javascript'; /* ... */ -const datasetId: number = 2; -const datasetVersionId: string = '1.0'; +const datasetId = 2; +const datasetVersionId = '1.0'; -getDatasetFilesTotalDownloadSize.execute(datasetId, datasetVersionId).then((size: number) => { +getDatasetFiles.execute(datasetId, datasetVersionId).then((subset: FilesSubset) => { /* ... */ }); /* ... */ ``` -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: +_See [use case](../src/files/domain/useCases/GetDatasetFiles.ts) implementation. -- `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 +The `datasetId` parameter can be a string, for persistent identifiers, or a number, for numeric identifiers. -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. +This use case supports the following optional parameters depending on the search goals: -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`. +- **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](../src/files/domain/models/FileCriteria.ts)) Supports filtering the files by different file properties. +- **fileOrderCriteria**: ([FileOrderCriteria](../src/files/domain/models/FileCriteria.ts)) Supports ordering the results according to different criteria. If not set, the defalt value is `FileOrderCriteria.NAME_AZ`. ##### Example call using optional parameters: ```typescript -import { getDatasetFilesTotalDownloadSize } from '@iqss/dataverse-client-javascript'; +import { getDatasetFiles } 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; +const limit: number = 10; +const offset: number = 20; +const searchCriteria: FileSearchCriteria = { + searchText: 'file title', +}; +const orderCriteria: FileOrderCriteria = FileOrderCriteria.NEWEST; -getDatasetFilesTotalDownloadSize - .execute(datasetId, datasetVersionId, fileDownloadSizeMode, fileSearchCriteria, includeDeaccessioned) - .then((size: number) => { +getDatasetFiles + .execute(datasetId, datasetVersionId, includeDeaccessioned, limit, offset, searchCriteria, orderCriteria) + .then((subset: FilesSubset) => { /* ... */ }); diff --git a/src/files/domain/useCases/GetFileDownloadCount.ts b/src/files/domain/useCases/GetFileDownloadCount.ts index 4d2b41eb..e527e1ef 100644 --- a/src/files/domain/useCases/GetFileDownloadCount.ts +++ b/src/files/domain/useCases/GetFileDownloadCount.ts @@ -8,6 +8,12 @@ export class GetFileDownloadCount implements UseCase { this.filesRepository = filesRepository; } + /** + * Provides the download count for a particular File. + * + * @param {number | string} [fileId] - The file identifier, which can be a string (for persistent identifiers), or a number (for numeric identifiers). + * @returns {Promise} + */ async execute(fileId: number | string): Promise { return await this.filesRepository.getFileDownloadCount(fileId); } From 4c931767eb28ed99ffaa2e580d65fe4403cfc03b Mon Sep 17 00:00:00 2001 From: GPortas Date: Fri, 2 Feb 2024 14:25:07 +0000 Subject: [PATCH 24/51] Fixed: docs structure --- docs/useCases.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/useCases.md b/docs/useCases.md index 2b94727a..2149e35c 100644 --- a/docs/useCases.md +++ b/docs/useCases.md @@ -102,7 +102,7 @@ getDatasetCitation.execute(datasetId, datasetVersionId).then((citationText: stri /* ... */ ``` -_See [use case](../src/datasets/domain/useCases/GetDatasetCitation.ts) implementation. +_See [use case](../src/datasets/domain/useCases/GetDatasetCitation.ts) implementation_. The `datasetId` parameter can be a string, for persistent identifiers, or a number, for numeric identifiers. @@ -128,7 +128,7 @@ getPrivateUrlDatasetCitation.execute(token).then((citationText: string) => { /* ... */ ``` -_See [use case](../src/datasets/domain/useCases/GetPrivateUrlDatasetCitation.ts) implementation. +_See [use case](../src/datasets/domain/useCases/GetPrivateUrlDatasetCitation.ts) implementation_. #### Get Dataset Locks @@ -150,7 +150,7 @@ getDatasetLocks.execute(datasetId).then((datasetLocks: DatasetLock[]) => { /* ... */ ``` -_See [use case](../src/datasets/domain/useCases/GetDatasetLocks.ts) implementation. +_See [use case](../src/datasets/domain/useCases/GetDatasetLocks.ts) implementation_. The `datasetId` parameter can be a string, for persistent identifiers, or a number, for numeric identifiers. @@ -172,7 +172,7 @@ getDatasetSummaryFieldNames.execute().then((names: string[]) => { /* ... */ ``` -_See [use case](../src/datasets/domain/useCases/GetDatasetSummaryFieldNames.ts) implementation. +_See [use case](../src/datasets/domain/useCases/GetDatasetSummaryFieldNames.ts) implementation_. #### Get User Permissions on a Dataset @@ -194,7 +194,7 @@ getDatasetUserPermissions.execute(datasetId).then((permissions: DatasetUserPermi /* ... */ ``` -_See [use case](../src/datasets/domain/useCases/GetDatasetUserPermissions.ts) implementation. +_See [use case](../src/datasets/domain/useCases/GetDatasetUserPermissions.ts) implementation_. The `datasetId` parameter can be a string, for persistent identifiers, or a number, for numeric identifiers. @@ -219,7 +219,7 @@ getAllDatasetPreviews.execute(limit, offset).then((subset: DatasetPreviewSubset) /* ... */ ``` -_See [use case](../src/datasets/domain/useCases/GetAllDatasetPreviews.ts) implementation. +_See [use case](../src/datasets/domain/useCases/GetAllDatasetPreviews.ts) implementation_. Note that `limit` and `offset` are optional parameters for pagination. @@ -255,7 +255,7 @@ getDatasetFileCounts.execute(datasetId, datasetVersionId).then((fileCounts: File /* ... */ ``` -_See [use case](../src/files/domain/useCases/GetDatasetFileCounts.ts) implementation. +_See [use case](../src/files/domain/useCases/GetDatasetFileCounts.ts) implementation_. The `datasetId` parameter can be a string, for persistent identifiers, or a number, for numeric identifiers. @@ -306,7 +306,7 @@ getFileDownloadCount.execute(fileId).then((count: number) => { /* ... */ ``` -_See [use case](../src/files/domain/useCases/GetFileDownloadCount.ts) implementation. +_See [use case](../src/files/domain/useCases/GetFileDownloadCount.ts) implementation_. The `fileId` parameter can be a string, for persistent identifiers, or a number, for numeric identifiers. @@ -331,7 +331,7 @@ getDatasetFilesTotalDownloadSize.execute(datasetId, datasetVersionId).then((size /* ... */ ``` -_See [use case](../src/files/domain/useCases/GetDatasetFilesTotalDownloadSize.ts) implementation. +_See [use case](../src/files/domain/useCases/GetDatasetFilesTotalDownloadSize.ts) implementation_. The `datasetId` parameter can be a string, for persistent identifiers, or a number, for numeric identifiers. @@ -390,7 +390,7 @@ getDatasetFiles.execute(datasetId, datasetVersionId).then((subset: FilesSubset) /* ... */ ``` -_See [use case](../src/files/domain/useCases/GetDatasetFiles.ts) implementation. +_See [use case](../src/files/domain/useCases/GetDatasetFiles.ts) implementation_. The `datasetId` parameter can be a string, for persistent identifiers, or a number, for numeric identifiers. From 7e9a38414812517a4ac7e1c6767815e967f7ee41 Mon Sep 17 00:00:00 2001 From: GPortas Date: Fri, 2 Feb 2024 14:33:48 +0000 Subject: [PATCH 25/51] Added: getFileDataTables docs --- docs/useCases.md | 25 +++++++++++++++++++ .../domain/useCases/GetFileDataTables.ts | 6 +++++ 2 files changed, 31 insertions(+) diff --git a/docs/useCases.md b/docs/useCases.md index 2149e35c..cac3ca1d 100644 --- a/docs/useCases.md +++ b/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 File Data Tables](#get-file-data-tables) - [Get File Download Count](#get-file-download-count) - [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) @@ -286,6 +287,30 @@ getDatasetFileCounts /* ... */ ``` +#### Get File Data Tables + +This use case is oriented toward tabular files and provides an array of [FileDataTable](../src/files/domain/models/FileDataTable.ts) objects for an existing tabular file. + +##### Example call: + +```typescript +import { getFileDataTables } from '@iqss/dataverse-client-javascript'; + +/* ... */ + +const fileId = 2; + +getFileDataTables.execute(fileId).then((dataTables: FileDataTable[]) => { + /* ... */ +}); + +/* ... */ +``` + +_See [use case](../src/files/domain/useCases/GetFileDataTables.ts) 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. diff --git a/src/files/domain/useCases/GetFileDataTables.ts b/src/files/domain/useCases/GetFileDataTables.ts index d8a65891..07ffdeda 100644 --- a/src/files/domain/useCases/GetFileDataTables.ts +++ b/src/files/domain/useCases/GetFileDataTables.ts @@ -9,6 +9,12 @@ export class GetFileDataTables implements UseCase { this.filesRepository = filesRepository; } + /** + * This use case is oriented toward tabular files and provides an array of FileDataTable objects for an existing tabular file. + * + * @param {number | string} [fileId] - The file identifier, which can be a string (for persistent identifiers), or a number (for numeric identifiers). + * @returns {Promise} + */ async execute(fileId: number | string): Promise { return await this.filesRepository.getFileDataTables(fileId); } From bc65e6e8cc6db2c8161e3bda5c8238f63a7fa3b8 Mon Sep 17 00:00:00 2001 From: GPortas Date: Fri, 2 Feb 2024 14:41:04 +0000 Subject: [PATCH 26/51] Added: GetFileUserPermissions docs --- docs/useCases.md | 31 +++++++++++++++++++ .../domain/useCases/GetFileUserPermissions.ts | 6 ++++ 2 files changed, 37 insertions(+) diff --git a/docs/useCases.md b/docs/useCases.md index cac3ca1d..dbdcd1f3 100644 --- a/docs/useCases.md +++ b/docs/useCases.md @@ -24,6 +24,7 @@ The different use cases currently available in the package are classified below, - [Get File Data Tables](#get-file-data-tables) - [Get File Download Count](#get-file-download-count) - [Get the size of Downloading all the files of a Dataset Version](#get-the-size-of-downloading-all-the-files-of-a-dataset-version) + - [Get User Permissions on a File](#get-user-permissions-on-a-file) - [List Files in a Dataset](#list-files-in-a-dataset) - [Metadata Blocks](#metadata-blocks) - [Users](#Users) @@ -394,6 +395,36 @@ getDatasetFilesTotalDownloadSize /* ... */ ``` +#### Get User Permissions on a File + +This use case returns a [FileUserPermissions](../src/files/domain/models/FileUserPermissions.ts) 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: + +```typescript +import { getFileUserPermissions } from '@iqss/dataverse-client-javascript'; + +/* ... */ + +const fileId: number = 2; + +getFileUserPermissions.execute(fileId).then((permissions: FileUserPermissions) => { + /* ... */ +}); + +/* ... */ +``` + +_See [use case](../src/files/domain/useCases/GetFileUserPermissions.ts) 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](../src/files/domain/models/FilesSubset.ts), which contains the files from the requested Dataset and page (if pagination parameters are set). diff --git a/src/files/domain/useCases/GetFileUserPermissions.ts b/src/files/domain/useCases/GetFileUserPermissions.ts index 454984ef..ed2ee266 100644 --- a/src/files/domain/useCases/GetFileUserPermissions.ts +++ b/src/files/domain/useCases/GetFileUserPermissions.ts @@ -9,6 +9,12 @@ export class GetFileUserPermissions implements UseCase { this.filesRepository = filesRepository; } + /** + * Returns a FileUserPermissions object, which includes the permissions that the calling user has on a particular File. + * + * @param {number | string} [fileId] - The file identifier, which can be a string (for persistent identifiers), or a number (for numeric identifiers). + * @returns {Promise} + */ async execute(fileId: number | string): Promise { return await this.filesRepository.getFileUserPermissions(fileId); } From 53c7da7eabb8e972c29b4d5aed3bad7be43ba512 Mon Sep 17 00:00:00 2001 From: GPortas Date: Fri, 2 Feb 2024 14:47:26 +0000 Subject: [PATCH 27/51] Added: GetMetadataBlockByName docs --- docs/useCases.md | 33 ++++++++++++++++--- .../domain/useCases/GetMetadataBlockByName.ts | 6 ++++ 2 files changed, 34 insertions(+), 5 deletions(-) diff --git a/docs/useCases.md b/docs/useCases.md index dbdcd1f3..11634bcf 100644 --- a/docs/useCases.md +++ b/docs/useCases.md @@ -27,6 +27,7 @@ The different use cases currently available in the package are classified below, - [Get User Permissions on a File](#get-user-permissions-on-a-file) - [List Files in a Dataset](#list-files-in-a-dataset) - [Metadata Blocks](#metadata-blocks) + - [Metadata Blocks read use cases](#metadata-blocks-read-use-cases) - [Users](#Users) - [Info](#Info) @@ -399,11 +400,11 @@ getDatasetFilesTotalDownloadSize This use case returns a [FileUserPermissions](../src/files/domain/models/FileUserPermissions.ts) object, which includes the permissions that the calling user has on a particular File. -The returned *FileUserPermissions* object contains the following permissions, as booleans: +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*) +- Can download the file (_canDownloadFile_) +- Can manage the file permissions (_canManageFilePermissions_) +- Can edit the file owner dataset (_canEditOwnerDataset_) ##### Example call: @@ -486,7 +487,29 @@ getDatasetFiles ## Metadata Blocks -TODO +### Metadata Blocks read use cases + +#### Get Metadata Block By Name + +Returns a [MetadataBlock](../src/metadataBlocks/domain/models/MetadataBlock.ts) instance, given its name. + +##### Example call: + +```typescript +import { getMetadataBlockByName } from '@iqss/dataverse-client-javascript'; + +/* ... */ + +const name = 'citation'; + +getMetadataBlockByName.execute(name).then((metadataBlock: MetadataBlock) => { + /* ... */ +}); + +/* ... */ +``` + +_See [use case](../src/metadataBlocks/domain/useCases/GetMetadataBlockByName.ts) implementation_. ## Users diff --git a/src/metadataBlocks/domain/useCases/GetMetadataBlockByName.ts b/src/metadataBlocks/domain/useCases/GetMetadataBlockByName.ts index dc09c1c4..a34953e3 100644 --- a/src/metadataBlocks/domain/useCases/GetMetadataBlockByName.ts +++ b/src/metadataBlocks/domain/useCases/GetMetadataBlockByName.ts @@ -9,6 +9,12 @@ export class GetMetadataBlockByName implements UseCase { this.metadataBlocksRepository = metadataBlocksRepository; } + /** + * Returns a MetadataBlock instance, given its name. + * + * @param {string} [metadataBlockName] - The requested metadata block name. + * @returns {Promise} + */ async execute(metadataBlockName: string): Promise { return await this.metadataBlocksRepository.getMetadataBlockByName(metadataBlockName); } From 236e862847d19b50da25d512b2604a9d2a51cb8a Mon Sep 17 00:00:00 2001 From: GPortas Date: Fri, 2 Feb 2024 14:48:41 +0000 Subject: [PATCH 28/51] Added: table of contents tweak --- docs/useCases.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/useCases.md b/docs/useCases.md index 11634bcf..1c65667a 100644 --- a/docs/useCases.md +++ b/docs/useCases.md @@ -28,6 +28,7 @@ The different use cases currently available in the package are classified below, - [List Files in a Dataset](#list-files-in-a-dataset) - [Metadata Blocks](#metadata-blocks) - [Metadata Blocks read use cases](#metadata-blocks-read-use-cases) + - [Get Metadata Block By Name](#get-metadata-block-by-name) - [Users](#Users) - [Info](#Info) From 5d2bd024b0c7c0e98b925a6cfbb0b0e097ca5b32 Mon Sep 17 00:00:00 2001 From: GPortas Date: Fri, 2 Feb 2024 14:55:19 +0000 Subject: [PATCH 29/51] Added: GetCurrentAuthenticatedUser docs --- docs/useCases.md | 26 +++++++++++++++++-- .../useCases/GetCurrentAuthenticatedUser.ts | 5 ++++ 2 files changed, 29 insertions(+), 2 deletions(-) diff --git a/docs/useCases.md b/docs/useCases.md index 1c65667a..60a95706 100644 --- a/docs/useCases.md +++ b/docs/useCases.md @@ -28,8 +28,10 @@ The different use cases currently available in the package are classified below, - [List Files in a Dataset](#list-files-in-a-dataset) - [Metadata Blocks](#metadata-blocks) - [Metadata Blocks read use cases](#metadata-blocks-read-use-cases) - - [Get Metadata Block By Name](#get-metadata-block-by-name) + - [Get Metadata Block By Name](#get-metadata-block-by-name) - [Users](#Users) + - [Users read use cases](#users-read-use-cases) + - [Get Current Authenticated User](#get-current-authenticated-user) - [Info](#Info) ## Datasets @@ -514,7 +516,27 @@ _See [use case](../src/metadataBlocks/domain/useCases/GetMetadataBlockByName.ts) ## Users -TODO +### Users read use cases + +#### Get Current Authenticated User + +Returns the current [AuthenticatedUser](../src/users/domain/models/AuthenticatedUser.ts) corresponding to the authentication mechanism provided through `ApiConfig`. + +##### Example call: + +```typescript +import { getCurrentAuthenticatedUser } from '@iqss/dataverse-client-javascript'; + +/* ... */ + +getCurrentAuthenticatedUser.execute().then((user: AuthenticatedUser) => { + /* ... */ +}); + +/* ... */ +``` + +_See [use case](../src/users/domain/useCases/GetCurrentAuthenticatedUser.ts) implementation_. ## Info diff --git a/src/users/domain/useCases/GetCurrentAuthenticatedUser.ts b/src/users/domain/useCases/GetCurrentAuthenticatedUser.ts index 1b9acb85..6724b518 100644 --- a/src/users/domain/useCases/GetCurrentAuthenticatedUser.ts +++ b/src/users/domain/useCases/GetCurrentAuthenticatedUser.ts @@ -9,6 +9,11 @@ export class GetCurrentAuthenticatedUser implements UseCase { this.usersRepository = usersRepository; } + /** + * Returns the current AuthenticatedUser corresponding to the authentication mechanism provided through ApiConfig. + * + * @returns {Promise} + */ async execute(): Promise { return await this.usersRepository.getCurrentAuthenticatedUser(); } From 6131aceb67ede345a90f404e5aee25d816cfc81e Mon Sep 17 00:00:00 2001 From: GPortas Date: Mon, 5 Feb 2024 09:08:30 +0000 Subject: [PATCH 30/51] Added: docs for getDataverseVersion --- docs/useCases.md | 21 ++++++++++++++++++- .../domain/useCases/GetDataverseVersion.ts | 5 +++++ 2 files changed, 25 insertions(+), 1 deletion(-) diff --git a/docs/useCases.md b/docs/useCases.md index 60a95706..614b5970 100644 --- a/docs/useCases.md +++ b/docs/useCases.md @@ -33,6 +33,7 @@ The different use cases currently available in the package are classified below, - [Users read use cases](#users-read-use-cases) - [Get Current Authenticated User](#get-current-authenticated-user) - [Info](#Info) + - [Get Dataverse Backend Version](#get-dataverse-backend-version) ## Datasets @@ -540,4 +541,22 @@ _See [use case](../src/users/domain/useCases/GetCurrentAuthenticatedUser.ts) imp ## Info -TODO +#### Get Dataverse Backend Version + +Returns a [DataverseVersion](../src/info/domain/models/DataverseVersion.ts) object, which contains version information for the Dataverse backend installation. + +##### Example call: + +```typescript +import { getDataverseVersion } from '@iqss/dataverse-client-javascript'; + +/* ... */ + +getDataverseVersion.execute().then((version: DataverseVersion) => { + /* ... */ +}); + +/* ... */ +``` + +_See [use case](../src/info/domain/useCases/GetDataverseVersion.ts) implementation_. diff --git a/src/info/domain/useCases/GetDataverseVersion.ts b/src/info/domain/useCases/GetDataverseVersion.ts index 4937b9d1..51455549 100644 --- a/src/info/domain/useCases/GetDataverseVersion.ts +++ b/src/info/domain/useCases/GetDataverseVersion.ts @@ -9,6 +9,11 @@ export class GetDataverseVersion implements UseCase { this.dataverseInfoRepository = dataverseInfoRepository; } + /** + * Returns a DataverseVersion object, which contains version information for the Dataverse backend installation. + * + * @returns {Promise} + */ async execute(): Promise { return await this.dataverseInfoRepository.getDataverseVersion(); } From 048d4b2e68b1c96bd04f777d2d610df6fe775eef Mon Sep 17 00:00:00 2001 From: GPortas Date: Mon, 5 Feb 2024 09:11:47 +0000 Subject: [PATCH 31/51] Added: docs for GetMaxEmbargoDurationInMonths --- docs/useCases.md | 21 +++++++++++++++++++ .../useCases/GetMaxEmbargoDurationInMonths.ts | 5 +++++ 2 files changed, 26 insertions(+) diff --git a/docs/useCases.md b/docs/useCases.md index 614b5970..c1651ffe 100644 --- a/docs/useCases.md +++ b/docs/useCases.md @@ -34,6 +34,7 @@ The different use cases currently available in the package are classified below, - [Get Current Authenticated User](#get-current-authenticated-user) - [Info](#Info) - [Get Dataverse Backend Version](#get-dataverse-backend-version) + - [Get Maximum Embargo Duration In Months](#get-maximum-embargo-duration-in-months) ## Datasets @@ -560,3 +561,23 @@ getDataverseVersion.execute().then((version: DataverseVersion) => { ``` _See [use case](../src/info/domain/useCases/GetDataverseVersion.ts) implementation_. + +#### Get Maximum Embargo Duration In Months + +Returns a number indicating the configured maximum embargo duration in months. + +##### Example call: + +```typescript +import { getMaxEmbargoDurationInMonths } from '@iqss/dataverse-client-javascript'; + +/* ... */ + +getMaxEmbargoDurationInMonths.execute().then((months: number) => { + /* ... */ +}); + +/* ... */ +``` + +_See [use case](../src/info/domain/useCases/GetMaxEmbargoDurationInMonths.ts) implementation_. diff --git a/src/info/domain/useCases/GetMaxEmbargoDurationInMonths.ts b/src/info/domain/useCases/GetMaxEmbargoDurationInMonths.ts index b10c4d1e..3c3b62be 100644 --- a/src/info/domain/useCases/GetMaxEmbargoDurationInMonths.ts +++ b/src/info/domain/useCases/GetMaxEmbargoDurationInMonths.ts @@ -8,6 +8,11 @@ export class GetMaxEmbargoDurationInMonths implements UseCase { this.dataverseInfoRepository = dataverseInfoRepository; } + /** + * Returns a number indicating the configured maximum embargo duration in months. + * + * @returns {Promise} + */ async execute(): Promise { return await this.dataverseInfoRepository.getMaxEmbargoDurationInMonths(); } From 0e825a977d3265d08da17cd78c4a934d4db7c261 Mon Sep 17 00:00:00 2001 From: GPortas Date: Mon, 5 Feb 2024 09:26:33 +0000 Subject: [PATCH 32/51] Added: GetZipDownloadLimit docs --- docs/useCases.md | 21 +++++++++++++++++++ .../domain/useCases/GetZipDownloadLimit.ts | 5 +++++ 2 files changed, 26 insertions(+) diff --git a/docs/useCases.md b/docs/useCases.md index c1651ffe..7ed393bc 100644 --- a/docs/useCases.md +++ b/docs/useCases.md @@ -35,6 +35,7 @@ The different use cases currently available in the package are classified below, - [Info](#Info) - [Get Dataverse Backend Version](#get-dataverse-backend-version) - [Get Maximum Embargo Duration In Months](#get-maximum-embargo-duration-in-months) + - [Get ZIP Download Limit](#get-zip-download-limit) ## Datasets @@ -581,3 +582,23 @@ getMaxEmbargoDurationInMonths.execute().then((months: number) => { ``` _See [use case](../src/info/domain/useCases/GetMaxEmbargoDurationInMonths.ts) implementation_. + +#### Get ZIP Download Limit + +Returns a number indicating the configured ZIP download limit in bytes. + +##### Example call: + +```typescript +import { getZipDownloadLimit } from '@iqss/dataverse-client-javascript'; + +/* ... */ + +getZipDownloadLimit.execute().then((downloadLimit: number) => { + /* ... */ +}); + +/* ... */ +``` + +_See [use case](../src/info/domain/useCases/GetZipDownloadLimit.ts) implementation_. diff --git a/src/info/domain/useCases/GetZipDownloadLimit.ts b/src/info/domain/useCases/GetZipDownloadLimit.ts index 84e8af4b..aa93bb6b 100644 --- a/src/info/domain/useCases/GetZipDownloadLimit.ts +++ b/src/info/domain/useCases/GetZipDownloadLimit.ts @@ -8,6 +8,11 @@ export class GetZipDownloadLimit implements UseCase { this.dataverseInfoRepository = dataverseInfoRepository; } + /** + * Returns a number indicating the configured ZIP download limit in bytes. + * + * @returns {Promise} + */ async execute(): Promise { return await this.dataverseInfoRepository.getZipDownloadLimit(); } From f0d9b386f2c1f88c17e0a4ea505c6c8d1b76dce5 Mon Sep 17 00:00:00 2001 From: GPortas Date: Mon, 5 Feb 2024 09:26:50 +0000 Subject: [PATCH 33/51] Changed: CONTRIBUTING.md --- CONTRIBUTING.md | 26 +++++++++++++++++--------- 1 file changed, 17 insertions(+), 9 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d9c3ee2b..244647c4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -3,31 +3,39 @@ First of all thank you very much for your interest in contributing to this project! ## Getting started -1. Make sure that you have installed the project dependencies -2. Build the project as explained in [README.md](README.md) -3. Fork the repository -4. Apply changes in your own branch -5. Create a pull request that we will review -6. Update README.md if necessary + +1. Fork the repository and clone your fork locally +2. Follow the [Local Development](./docs/localDevelopment.md) guide for setting up your local development environment +3. Create a branch and apply the desired changes on it +4. Create a pull request from your fork branch targeting the develop branch of the root repository ## Checklist before creating PR + - Project builds - Lint and format checks pass -- Unit tests pass -- Unit tests for new functionality/fix are added +- Unit and integration tests pass +- Unit and integration tests for new functionality/fix are added +- Documentation is updated (Any new use case added or modified should be documented in the [Use Cases](./docs/useCases.md) section) ## Code of Conduct + We abide by the upstream Code of Conduct at https://github.com/IQSS/dataverse/blob/develop/CODE_OF_CONDUCT.md and in addition ask the following. ### Git + - Branch names are self descriptive - Commit messages are short and concise - Branch is put up to date before creating PR ### Our responsibilities + - To keep the code clean - To provide constructive feedback to other developers - To maintain readable code at all times ## Getting help -Please feel free to reach out in https://chat.dataverse.org or https://groups.google.com/g/dataverse-dev \ No newline at end of file + +Please, do not hesitate to contact us through: + +- Zulip: https://dataverse.zulipchat.com/#narrow/stream/410361-ui-dev +- Google Groups: https://groups.google.com/g/dataverse-dev From 4deb4f99a8c483d57a0df486635e5ca5a6b19b3f Mon Sep 17 00:00:00 2001 From: GPortas Date: Mon, 5 Feb 2024 09:29:21 +0000 Subject: [PATCH 34/51] Added: doc tweaks --- CONTRIBUTING.md | 2 +- README.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 244647c4..432eb098 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -38,4 +38,4 @@ We abide by the upstream Code of Conduct at https://github.com/IQSS/dataverse/bl Please, do not hesitate to contact us through: - Zulip: https://dataverse.zulipchat.com/#narrow/stream/410361-ui-dev -- Google Groups: https://groups.google.com/g/dataverse-dev +- Google Group: https://groups.google.com/g/dataverse-dev diff --git a/README.md b/README.md index 97440490..c88d7b79 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# dataverse-client-javascript +# js-dataverse [![npm](https://img.shields.io/npm/v/js-dataverse.svg)](https://www.npmjs.com/package/js-dataverse) From 39ee39f15de1fc36fcf7787832209e9f68a89d11 Mon Sep 17 00:00:00 2001 From: GPortas Date: Mon, 5 Feb 2024 10:15:18 +0000 Subject: [PATCH 35/51] Added: docs for GetFile use case --- docs/useCases.md | 28 ++++++++++++++++++++++++++++ src/files/domain/useCases/GetFile.ts | 7 +++++++ 2 files changed, 35 insertions(+) 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, From 9e39abf59ccbd07ddbaab00ad8842467a6db1b32 Mon Sep 17 00:00:00 2001 From: GPortas Date: Mon, 5 Feb 2024 10:16:34 +0000 Subject: [PATCH 36/51] Fixed: doc link --- docs/useCases.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/useCases.md b/docs/useCases.md index 7344934f..ff12bae6 100644 --- a/docs/useCases.md +++ b/docs/useCases.md @@ -241,7 +241,7 @@ The `DatasetPreviewSubset`returned instance contains a property called `totalDat #### Get a File -Returns a [File](../src/files/domain/models/Dataset.ts) instance, given the search parameters to identify it. +Returns a [File](../src/files/domain/models/File.ts) instance, given the search parameters to identify it. ##### Example call: From c846f8535ba13c71bc39cb2ff5f3da9574de54b3 Mon Sep 17 00:00:00 2001 From: MellyGray Date: Mon, 19 Feb 2024 12:20:19 +0100 Subject: [PATCH 37/51] feat(Guide): add .npmrc instructions --- docs/installation.md | 55 +++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 52 insertions(+), 3 deletions(-) diff --git a/docs/installation.md b/docs/installation.md index d3177635..f347c604 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -1,8 +1,8 @@ # Installation -## NPM +Recommended versions node >=16 and npm >=8. -### Stable version +## Getting Started with the Stable version A stable 1.x version of this package is available as `js-dataverse` at https://www.npmjs.com/package/js-dataverse @@ -12,12 +12,61 @@ Install the package stable version using npm: npm install js-dataverse ``` -### Development versions +## Getting Started with the Development Version An unstable 2.x version of this package with breaking changes is under development. Until a 2.0 version is officially released, it can be installed from https://github.com/IQSS/dataverse-client-javascript/pkgs/npm/dataverse-client-javascript + +### Create a `.npmrc` file and add a token + +To install the [@iqss/dataverse-client-javascript](https://github.com/IQSS/dataverse-client-javascript/pkgs/npm/dataverse-client-javascript) +from the GitHub registry, follow these steps to create an `.npmrc` file in the root of your project using your GitHub token. + +1. **Create `.npmrc`** in your project's root directory. + + ```bash + touch .npmrc + ``` + +2. **Replace the Token** + + Open the newly created `.npmrc` file and replace `YOUR_GITHUB_TOKEN` with your actual GitHub token. + + ```plaintext + legacy-peer-deps=true + + //npm.pkg.github.com/:_authToken= + @iqss:registry=https://npm.pkg.github.com/ + ``` + +#### How to Get a GitHub Token + +If you don't have a GitHub token yet, follow these steps: + +1. Go to your GitHub account settings. + +2. Navigate to "Developer settings" -> "Personal access tokens." + +3. Click "Personal access tokens" -> "Tokens (classic)" -> "Generate new token (classic)". + +4. Give the token a name and select the "read:packages" scope. + +5. Copy the generated token. + +6. Replace `YOUR_GITHUB_AUTH_TOKEN` in the `.npmrc` file with the copied token. + +Now, you should be able to install the Dataverse JavaScript client using npm. + +### Install the package + +Install the package development version using npm: + +```bash +npm install @iqss/dataverse-client-javascript +``` + ## Initialization In order for the package to connect to the Dataverse API, there is an `APIConfig` object that should be initialized to set the preferred authentication mechanism with the associated credentials for connecting to the Dataverse API. From dbdbeaee421f215a79e7fea9958e9d4f92b09b67 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Melina=20Hern=C3=A1ndez?= Date: Mon, 19 Feb 2024 12:23:15 +0100 Subject: [PATCH 38/51] feat(Guide): re-write some lines for clarity Co-authored-by: Ellen Kraffmiller --- docs/installation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/installation.md b/docs/installation.md index d3177635..97d73fb7 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -26,7 +26,7 @@ Currently, the supported authentication mechanisms are: - **API Key**: The recommended authentication mechanism. The API Key should correspond to a particular Dataverse user account. -- **Session Cookie**: This is an experimental feature primarily designed for Dataverse SPA development. It is necessary to enable the corresponding feature flag in the Dataverse installation to use this mechanism (See https://guides.dataverse.org/en/latest/installation/config.html?#feature-flags). It is recommended not to use this mechanism and instead use API Key authentication. +- **Session Cookie**: This is an experimental feature primarily designed for Dataverse SPA development. To use this mechanism, you must enable the corresponding feature flag in the Dataverse installation (See https://guides.dataverse.org/en/latest/installation/config.html?#feature-flags). It is recommended not to use this mechanism and instead use API Key authentication. It is recommended to globally initialize the `ApiConfig` object from the consuming application, as the configuration will be read on every API call made by the package's use cases. From 04b20d4b97c803cadf07a6f7bd936be929f0731f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Melina=20Hern=C3=A1ndez?= Date: Mon, 19 Feb 2024 12:26:40 +0100 Subject: [PATCH 39/51] fix(Guides): wrong import in code example Co-authored-by: Ellen Kraffmiller --- docs/useCases.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/useCases.md b/docs/useCases.md index ff12bae6..192e465e 100644 --- a/docs/useCases.md +++ b/docs/useCases.md @@ -49,7 +49,7 @@ Returns a [Dataset](../src/datasets/domain/models/Dataset.ts) instance, given th ##### Example call: ```typescript -import { getAllDatasetPreviews } from '@iqss/dataverse-client-javascript'; +import { getDataset } from '@iqss/dataverse-client-javascript'; /* ... */ From e4135557989afa7a2c2ed732f194aee32a6282d4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Melina=20Hern=C3=A1ndez?= Date: Mon, 19 Feb 2024 12:28:06 +0100 Subject: [PATCH 40/51] fix(Guides): add optional `datasetVersionId` Co-authored-by: Ellen Kraffmiller --- docs/useCases.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/useCases.md b/docs/useCases.md index 192e465e..726a7d4b 100644 --- a/docs/useCases.md +++ b/docs/useCases.md @@ -67,7 +67,7 @@ _See [use case](../src/datasets/domain/useCases/GetDataset.ts)_ definition. The `datasetId` 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`. +The optional `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 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`. From 37e0fb008200ab5ce5a61c9b2dd5251b5534fc54 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Melina=20Hern=C3=A1ndez?= Date: Mon, 19 Feb 2024 12:28:23 +0100 Subject: [PATCH 41/51] fix(Guides): optional `datasetVersionId` Co-authored-by: Ellen Kraffmiller --- docs/useCases.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/useCases.md b/docs/useCases.md index 726a7d4b..ccdc43ef 100644 --- a/docs/useCases.md +++ b/docs/useCases.md @@ -264,7 +264,7 @@ _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`. +The optional `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 From 4fe029ade62747cbb5bdb0718a80da607eed7ba2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Melina=20Hern=C3=A1ndez?= Date: Mon, 19 Feb 2024 12:41:57 +0100 Subject: [PATCH 42/51] fix(Guides): add optional `datasetVersionId` to GetDatasetFileCounts Co-authored-by: Ellen Kraffmiller --- docs/useCases.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/useCases.md b/docs/useCases.md index ccdc43ef..93a12904 100644 --- a/docs/useCases.md +++ b/docs/useCases.md @@ -295,7 +295,7 @@ getDatasetFileCounts.execute(datasetId, datasetVersionId).then((fileCounts: File _See [use case](../src/files/domain/useCases/GetDatasetFileCounts.ts) 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](../src/datasets/domain/models/DatasetNotNumberedVersion.ts) 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](../src/files/domain/models/FileCriteria.ts) object to retrieve counts only for files that match the specified criteria. From 19559a0a6f316bb80a57b0ea25ab3f46388d5e4f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Melina=20Hern=C3=A1ndez?= Date: Mon, 19 Feb 2024 12:42:58 +0100 Subject: [PATCH 43/51] fix(Guides): add optional datasetVersionId to GetDatasetFilesTotalDownloadSize Co-authored-by: Ellen Kraffmiller --- docs/useCases.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/useCases.md b/docs/useCases.md index 93a12904..946de3c0 100644 --- a/docs/useCases.md +++ b/docs/useCases.md @@ -395,7 +395,7 @@ getDatasetFilesTotalDownloadSize.execute(datasetId, datasetVersionId).then((size _See [use case](../src/files/domain/useCases/GetDatasetFilesTotalDownloadSize.ts) 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](../src/datasets/domain/models/DatasetNotNumberedVersion.ts) 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](../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 From 99afa32803c3cae26c580b726c88826e30f937d0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Melina=20Hern=C3=A1ndez?= Date: Mon, 19 Feb 2024 12:43:26 +0100 Subject: [PATCH 44/51] fix(Guides): add optional datasetVersionId to GetDatasetFiles Co-authored-by: Ellen Kraffmiller --- docs/useCases.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/useCases.md b/docs/useCases.md index 946de3c0..fc232ec5 100644 --- a/docs/useCases.md +++ b/docs/useCases.md @@ -484,7 +484,7 @@ getDatasetFiles.execute(datasetId, datasetVersionId).then((subset: FilesSubset) _See [use case](../src/files/domain/useCases/GetDatasetFiles.ts) 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](../src/datasets/domain/models/DatasetNotNumberedVersion.ts) 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`. From dd4fbee369702f932be8435de3636ed81952c31d Mon Sep 17 00:00:00 2001 From: MellyGray Date: Mon, 19 Feb 2024 12:56:02 +0100 Subject: [PATCH 45/51] fix(Guides): add embargo duration returned values explanation --- docs/installation.md | 2 +- docs/useCases.md | 5 ++++- 2 files changed, 5 insertions(+), 2 deletions(-) diff --git a/docs/installation.md b/docs/installation.md index 1b4aa4fc..df3efac0 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -2,7 +2,7 @@ Recommended versions node >=16 and npm >=8. -## Getting Started with the Stable version +## Getting Started with the Stable Version A stable 1.x version of this package is available as `js-dataverse` at https://www.npmjs.com/package/js-dataverse diff --git a/docs/useCases.md b/docs/useCases.md index ccdc43ef..4432f294 100644 --- a/docs/useCases.md +++ b/docs/useCases.md @@ -593,7 +593,10 @@ _See [use case](../src/info/domain/useCases/GetDataverseVersion.ts) implementati #### Get Maximum Embargo Duration In Months -Returns a number indicating the configured 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](https://guides.dataverse.org/en/latest/installation/config.html#maxembargodurationinmonths). + ##### Example call: From 0b358a70e5388d8da7c03d7ac45cf64feb7e88b8 Mon Sep 17 00:00:00 2001 From: MellyGray Date: Mon, 19 Feb 2024 15:33:13 +0100 Subject: [PATCH 46/51] fix: replace turndown library by NodeHtmlMarkdown to fix nextjs incompatibility --- package-lock.json | 133 ++++++++++++++++++ package.json | 13 +- .../transformers/datasetTransformers.ts | 6 +- test/testHelpers/datasets/datasetHelper.ts | 8 +- 4 files changed, 145 insertions(+), 15 deletions(-) diff --git a/package-lock.json b/package-lock.json index d54b28f2..fed65deb 100644 --- a/package-lock.json +++ b/package-lock.json @@ -12,6 +12,7 @@ "@types/node": "^18.15.11", "@types/turndown": "^5.0.1", "axios": "^1.3.4", + "node-html-markdown": "^1.3.0", "turndown": "^7.1.2", "typescript": "^4.9.5" }, @@ -2027,6 +2028,11 @@ "readable-stream": "^3.4.0" } }, + "node_modules/boolbase": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/boolbase/-/boolbase-1.0.0.tgz", + "integrity": "sha512-JZOSA7Mo9sNGB8+UjSgzdLtokWAky1zbztM3WRLCbZ70/3cTANmQmOdR7y2g+J0e2WXywy1yS468tY+IruqEww==" + }, "node_modules/brace-expansion": { "version": "1.1.11", "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.11.tgz", @@ -2419,6 +2425,32 @@ "node": ">= 8" } }, + "node_modules/css-select": { + "version": "5.1.0", + "resolved": "https://registry.npmjs.org/css-select/-/css-select-5.1.0.tgz", + "integrity": "sha512-nwoRF1rvRRnnCqqY7updORDsuqKzqYJ28+oSMaJMMgOauh3fvwHqMS7EZpIPqK8GL+g9mKxF1vP/ZjSeNjEVHg==", + "dependencies": { + "boolbase": "^1.0.0", + "css-what": "^6.1.0", + "domhandler": "^5.0.2", + "domutils": "^3.0.1", + "nth-check": "^2.0.1" + }, + "funding": { + "url": "https://github.com/sponsors/fb55" + } + }, + "node_modules/css-what": { + "version": "6.1.0", + "resolved": "https://registry.npmjs.org/css-what/-/css-what-6.1.0.tgz", + "integrity": "sha512-HTUrgRJ7r4dsZKU6GjmpfRK1O76h97Z8MfS1G0FozR+oF2kG6Vfe8JE6zwrkbxigziPHinCJ+gCPjA9EaBDtRw==", + "engines": { + "node": ">= 6" + }, + "funding": { + "url": "https://github.com/sponsors/fb55" + } + }, "node_modules/debug": { "version": "4.3.4", "resolved": "https://registry.npmjs.org/debug/-/debug-4.3.4.tgz", @@ -2581,11 +2613,62 @@ "node": ">=6.0.0" } }, + "node_modules/dom-serializer": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/dom-serializer/-/dom-serializer-2.0.0.tgz", + "integrity": "sha512-wIkAryiqt/nV5EQKqQpo3SToSOV9J0DnbJqwK7Wv/Trc92zIAYZ4FlMu+JPFW1DfGFt81ZTCGgDEabffXeLyJg==", + "dependencies": { + "domelementtype": "^2.3.0", + "domhandler": "^5.0.2", + "entities": "^4.2.0" + }, + "funding": { + "url": "https://github.com/cheeriojs/dom-serializer?sponsor=1" + } + }, + "node_modules/domelementtype": { + "version": "2.3.0", + "resolved": "https://registry.npmjs.org/domelementtype/-/domelementtype-2.3.0.tgz", + "integrity": "sha512-OLETBj6w0OsagBwdXnPdN0cnMfF9opN69co+7ZrbfPGrdpPVNBUj02spi6B1N7wChLQiPn4CSH/zJvXw56gmHw==", + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/fb55" + } + ] + }, + "node_modules/domhandler": { + "version": "5.0.3", + "resolved": "https://registry.npmjs.org/domhandler/-/domhandler-5.0.3.tgz", + "integrity": "sha512-cgwlv/1iFQiFnU96XXgROh8xTeetsnJiDsTc7TYCLFd9+/WNkIqPTxiM/8pSd8VIrhXGTf1Ny1q1hquVqDJB5w==", + "dependencies": { + "domelementtype": "^2.3.0" + }, + "engines": { + "node": ">= 4" + }, + "funding": { + "url": "https://github.com/fb55/domhandler?sponsor=1" + } + }, "node_modules/domino": { "version": "2.1.6", "resolved": "https://registry.npmjs.org/domino/-/domino-2.1.6.tgz", "integrity": "sha512-3VdM/SXBZX2omc9JF9nOPCtDaYQ67BGp5CoLpIQlO2KCAPETs8TcDHacF26jXadGbvUteZzRTeos2fhID5+ucQ==" }, + "node_modules/domutils": { + "version": "3.1.0", + "resolved": "https://registry.npmjs.org/domutils/-/domutils-3.1.0.tgz", + "integrity": "sha512-H78uMmQtI2AhgDJjWeQmHwJJ2bLPD3GMmO7Zja/ZZh84wkm+4ut+IUnUdRa8uCGX88DiVx1j6FRe1XfxEgjEZA==", + "dependencies": { + "dom-serializer": "^2.0.0", + "domelementtype": "^2.3.0", + "domhandler": "^5.0.3" + }, + "funding": { + "url": "https://github.com/fb55/domutils?sponsor=1" + } + }, "node_modules/electron-to-chromium": { "version": "1.4.394", "resolved": "https://registry.npmjs.org/electron-to-chromium/-/electron-to-chromium-1.4.394.tgz", @@ -2619,6 +2702,17 @@ "once": "^1.4.0" } }, + "node_modules/entities": { + "version": "4.5.0", + "resolved": "https://registry.npmjs.org/entities/-/entities-4.5.0.tgz", + "integrity": "sha512-V0hjH4dGPh9Ao5p0MoRY6BVqtwCjhz6vI5LT8AJ55H+4g9/4vbHx1I54fS0XuclLhDHArPQCiMjDxjaL8fPxhw==", + "engines": { + "node": ">=0.12" + }, + "funding": { + "url": "https://github.com/fb55/entities?sponsor=1" + } + }, "node_modules/error-ex": { "version": "1.3.2", "resolved": "https://registry.npmjs.org/error-ex/-/error-ex-1.3.2.tgz", @@ -3274,6 +3368,14 @@ "node": ">=8" } }, + "node_modules/he": { + "version": "1.2.0", + "resolved": "https://registry.npmjs.org/he/-/he-1.2.0.tgz", + "integrity": "sha512-F/1DnUGPopORZi0ni+CvrCgHQ5FyEAHRLSApuYWMmrbSwoN2Mn/7k+Gl38gJnR7yyDZk6WLXwiGod1JOWNDKGw==", + "bin": { + "he": "bin/he" + } + }, "node_modules/html-escaper": { "version": "2.0.2", "resolved": "https://registry.npmjs.org/html-escaper/-/html-escaper-2.0.2.tgz", @@ -4547,6 +4649,26 @@ } } }, + "node_modules/node-html-markdown": { + "version": "1.3.0", + "resolved": "https://registry.npmjs.org/node-html-markdown/-/node-html-markdown-1.3.0.tgz", + "integrity": "sha512-OeFi3QwC/cPjvVKZ114tzzu+YoR+v9UXW5RwSXGUqGb0qCl0DvP406tzdL7SFn8pZrMyzXoisfG2zcuF9+zw4g==", + "dependencies": { + "node-html-parser": "^6.1.1" + }, + "engines": { + "node": ">=10.0.0" + } + }, + "node_modules/node-html-parser": { + "version": "6.1.12", + "resolved": "https://registry.npmjs.org/node-html-parser/-/node-html-parser-6.1.12.tgz", + "integrity": "sha512-/bT/Ncmv+fbMGX96XG9g05vFt43m/+SYKIs9oAemQVYyVcZmDAI2Xq/SbNcpOA35eF0Zk2av3Ksf+Xk8Vt8abA==", + "dependencies": { + "css-select": "^5.1.0", + "he": "1.2.0" + } + }, "node_modules/node-int64": { "version": "0.4.0", "resolved": "https://registry.npmjs.org/node-int64/-/node-int64-0.4.0.tgz", @@ -4580,6 +4702,17 @@ "node": ">=8" } }, + "node_modules/nth-check": { + "version": "2.1.1", + "resolved": "https://registry.npmjs.org/nth-check/-/nth-check-2.1.1.tgz", + "integrity": "sha512-lqjrjmaOoAnWfMmBPL+XNnynZh2+swxiX3WUE0s4yEHI6m+AwrK2UZOimIRl3X/4QctVqS8AiZjFqyOGrMXb/w==", + "dependencies": { + "boolbase": "^1.0.0" + }, + "funding": { + "url": "https://github.com/fb55/nth-check?sponsor=1" + } + }, "node_modules/once": { "version": "1.4.0", "resolved": "https://registry.npmjs.org/once/-/once-1.4.0.tgz", diff --git a/package.json b/package.json index 3a9330ba..d02075f2 100644 --- a/package.json +++ b/package.json @@ -31,25 +31,26 @@ }, "homepage": "https://github.com/IQSS/dataverse-client-javascript#readme", "devDependencies": { + "@types/chai": "^4.3.4", "@types/jest": "^29.4.0", "@types/sinon": "^10.0.13", - "@types/chai": "^4.3.4", "@typescript-eslint/eslint-plugin": "^5.54.0", "@typescript-eslint/parser": "^5.52.0", + "chai": "^4.3.7", "eslint": "^8.35.0", "eslint-plugin-jest": "^27.2.1", "jest": "^29.4.3", - "chai": "^4.3.7", "prettier": "^2.8.4", - "ts-jest": "^29.0.5", "sinon": "^15.0.3", - "testcontainers": "^9.9.1" + "testcontainers": "^9.9.1", + "ts-jest": "^29.0.5" }, "dependencies": { "@types/node": "^18.15.11", "@types/turndown": "^5.0.1", "axios": "^1.3.4", - "typescript": "^4.9.5", - "turndown": "^7.1.2" + "node-html-markdown": "^1.3.0", + "turndown": "^7.1.2", + "typescript": "^4.9.5" } } diff --git a/src/datasets/infra/repositories/transformers/datasetTransformers.ts b/src/datasets/infra/repositories/transformers/datasetTransformers.ts index 758e832d..b7e614bd 100644 --- a/src/datasets/infra/repositories/transformers/datasetTransformers.ts +++ b/src/datasets/infra/repositories/transformers/datasetTransformers.ts @@ -8,9 +8,7 @@ import { DatasetMetadataBlocks, } from '../../../domain/models/Dataset'; import { AxiosResponse } from 'axios'; -import TurndownService from 'turndown'; - -const turndownService = new TurndownService(); +import { NodeHtmlMarkdown } from 'node-html-markdown'; export const transformVersionResponseToDataset = (response: AxiosResponse): Dataset => { const versionPayload = response.data.data; @@ -104,5 +102,5 @@ const transformPayloadToDatasetMetadataFieldValue = (metadataFieldValuePayload: }; const transformHtmlToMarkdown = (source: string): string => { - return turndownService.turndown(source); + return NodeHtmlMarkdown.translate(source); }; diff --git a/test/testHelpers/datasets/datasetHelper.ts b/test/testHelpers/datasets/datasetHelper.ts index b257a0b8..8415fce6 100644 --- a/test/testHelpers/datasets/datasetHelper.ts +++ b/test/testHelpers/datasets/datasetHelper.ts @@ -1,10 +1,8 @@ import { Dataset, DatasetVersionState, DatasetLicense } from '../../../src/datasets/domain/models/Dataset'; -import TurndownService from 'turndown'; +import { NodeHtmlMarkdown } from 'node-html-markdown'; import axios, { AxiosResponse } from 'axios'; import { TestConstants } from '../TestConstants'; -const turndownService = new TurndownService(); - const DATASET_CREATE_TIME_STR = '2023-05-15T08:21:01Z'; const DATASET_UPDATE_TIME_STR = '2023-05-15T08:21:03Z'; const DATASET_RELEASE_TIME_STR = '2023-05-15T08:21:03Z'; @@ -50,7 +48,7 @@ export const createDatasetModel = (license?: DatasetLicense): Dataset => { subject: ['Subject1', 'Subject2'], dsDescription: [ { - dsDescriptionValue: turndownService.turndown(DATASET_HTML_DESCRIPTION), + dsDescriptionValue: NodeHtmlMarkdown.translate(DATASET_HTML_DESCRIPTION), }, ], datasetContact: [ @@ -185,7 +183,7 @@ export const createDatasetVersionPayload = (license?: DatasetLicense): any => { return datasetPayload; }; -export const createDatasetLicenseModel = (withIconUri: boolean = true): DatasetLicense => { +export const createDatasetLicenseModel = (withIconUri = true): DatasetLicense => { const datasetLicense: DatasetLicense = { name: 'CC0 1.0', uri: 'https://creativecommons.org/publicdomain/zero/1.0/', From a687c63a5a9063c0fe9af06afaa8cf1eb959c6e4 Mon Sep 17 00:00:00 2001 From: MellyGray Date: Mon, 19 Feb 2024 15:50:41 +0100 Subject: [PATCH 47/51] fix: FileAccessStatus enum values --- src/files/domain/models/FileCriteria.ts | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/files/domain/models/FileCriteria.ts b/src/files/domain/models/FileCriteria.ts index 3285624a..5ad26aa1 100644 --- a/src/files/domain/models/FileCriteria.ts +++ b/src/files/domain/models/FileCriteria.ts @@ -70,6 +70,6 @@ export enum FileOrderCriteria { export enum FileAccessStatus { PUBLIC = 'Public', RESTRICTED = 'Restricted', - EMBARGOED = 'EmbargoedThenRestricted', - EMBARGOED_RESTRICTED = 'EmbargoedThenPublic', + EMBARGOED = 'EmbargoedThenPublic', + EMBARGOED_RESTRICTED = 'EmbargoedThenRestricted', } From ea8f2a8dde1ef4414b2a71bc27e6b321c81a4de4 Mon Sep 17 00:00:00 2001 From: GPortas Date: Wed, 21 Feb 2024 12:55:33 +0000 Subject: [PATCH 48/51] Added: use case docs for CreateDataset --- docs/useCases.md | 71 ++++++++++++++++++- src/datasets/domain/useCases/CreateDataset.ts | 10 +++ 2 files changed, 78 insertions(+), 3 deletions(-) diff --git a/docs/useCases.md b/docs/useCases.md index 1b3497e0..cff79904 100644 --- a/docs/useCases.md +++ b/docs/useCases.md @@ -18,6 +18,8 @@ The different use cases currently available in the package are classified below, - [Get Dataset Summary Field Names](#get-dataset-summary-field-names) - [Get User Permissions on a Dataset](#get-user-permissions-on-a-dataset) - [List All Datasets](#list-all-datasets) + - [Datasets write use cases](#datasets-write-use-cases) + - [Create a Dataset](#create-a-dataset) - [Files](#Files) - [Files read use cases](#files-read-use-cases) - [Get a File](#get-a-file) @@ -235,6 +237,70 @@ Note that `limit` and `offset` are optional parameters for pagination. The `DatasetPreviewSubset`returned 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 [NewDatasetDTO](../src/datasets/domain/dtos/NewDatasetDTO.ts) 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](../src/core/domain/useCases/validators/errors/ResourceValidationError.ts), which include sufficient information to determine which field value is invalid and why. + +##### Example call: + +```typescript +import { createDataset } from '@iqss/dataverse-client-javascript'; + +/* ... */ + +const newDatasetDTO: NewDatasetDTO = { + metadataBlockValues: [ + { + name: 'citation', + fields: { + title: 'New Dataset', + author: [ + { + authorName: 'John Doe', + authorAffiliation: 'Dataverse', + }, + { + authorName: 'John Lee', + authorAffiliation: 'Dataverse', + }, + ], + datasetContact: [ + { + datasetContactEmail: 'johndoe@dataverse.com', + datasetContactName: 'John', + }, + ], + dsDescription: [ + { + dsDescriptionValue: 'This is the description of our new dataset', + }, + ], + subject: 'Earth and Environmental Sciences', + + /* Rest of field values... */ + + }, + }, + ], +}; + +createDataset.execute(newDatasetDTO).then((newDatasetIds: CreatedDatasetIdentifiers) => { + /* ... */ +}); + +/* ... */ +``` + +_See [use case](../src/datasets/domain/useCases/CreateDataset.ts) 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](../src/datasets/domain/models/CreatedDatasetIdentifiers.ts) object, which includes the persistent and numeric identifiers of the created dataset. + ## Files ### Files read use cases @@ -593,11 +659,10 @@ _See [use case](../src/info/domain/useCases/GetDataverseVersion.ts) implementati #### 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: +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](https://guides.dataverse.org/en/latest/installation/config.html#maxembargodurationinmonths). - ##### Example call: ```typescript diff --git a/src/datasets/domain/useCases/CreateDataset.ts b/src/datasets/domain/useCases/CreateDataset.ts index ca352d82..4b71167f 100644 --- a/src/datasets/domain/useCases/CreateDataset.ts +++ b/src/datasets/domain/useCases/CreateDataset.ts @@ -21,6 +21,16 @@ export class CreateDataset implements UseCase { this.newDatasetValidator = newDatasetValidator; } + /** + * Creates a new Dataset in a collection, given a NewDatasetDTO object and an optional collection identifier, which defaults to root. + * + * @param {NewDatasetDTO} [newDataset] - NewDatasetDTO object including the new dataset metadata field values for each metadata block. + * @param {string} [collectionId] - Specifies the collection identifier where the new dataset should be created (optional, defaults to root). + * @returns {Promise} + * @throws {ResourceValidationError} - If there are validation errors related to the provided information. + * @throws {ReadError} - If there are errors while reading data. + * @throws {WriteError} - If there are errors while writing data. + */ async execute(newDataset: NewDatasetDTO, collectionId: string = 'root'): Promise { const metadataBlocks = await this.getNewDatasetMetadataBlocks(newDataset); this.newDatasetValidator.validate(newDataset, metadataBlocks); From 3e71ba9b5ac2de7c0cb34dacfef536fcf3690613 Mon Sep 17 00:00:00 2001 From: GPortas Date: Wed, 21 Feb 2024 13:00:39 +0000 Subject: [PATCH 49/51] Fixed: GetDatasetCitation method docs --- src/datasets/domain/useCases/GetDatasetCitation.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/datasets/domain/useCases/GetDatasetCitation.ts b/src/datasets/domain/useCases/GetDatasetCitation.ts index fd158f84..11dbb089 100644 --- a/src/datasets/domain/useCases/GetDatasetCitation.ts +++ b/src/datasets/domain/useCases/GetDatasetCitation.ts @@ -15,7 +15,7 @@ export class GetDatasetCitation implements UseCase { * @param {number} [datasetId] - The dataset identifier. * @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 {boolean} [includeDeaccessioned=false] - Indicates whether to consider deaccessioned versions in the dataset search or not. The default value is false - * @returns {Promise} + * @returns {Promise} */ async execute( datasetId: number, From c20cd3b0bd4da8346715036deebb687fbc34d233 Mon Sep 17 00:00:00 2001 From: GPortas Date: Wed, 21 Feb 2024 13:01:43 +0000 Subject: [PATCH 50/51] Added: use case docs for GetFileCitation --- docs/useCases.md | 26 ++++++++++++++++++++ src/files/domain/useCases/GetFileCitation.ts | 8 ++++++ 2 files changed, 34 insertions(+) diff --git a/docs/useCases.md b/docs/useCases.md index cff79904..850ab448 100644 --- a/docs/useCases.md +++ b/docs/useCases.md @@ -23,6 +23,7 @@ The different use cases currently available in the package are classified below, - [Files](#Files) - [Files read use cases](#files-read-use-cases) - [Get a File](#get-a-file) + - [Get File Citation Text](#get-file-citation-text) - [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) @@ -332,6 +333,31 @@ The `fileId` parameter can be a string, for persistent identifiers, or a number, The optional `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 Citation Text + +Returns the File citation text. + +##### Example call: + +```typescript +import { getFileCitation } from '@iqss/dataverse-client-javascript'; + +/* ... */ + +const fileId = 3; +const datasetVersionId = '1.0'; + +getFileCitation.execute(fileId, datasetVersionId).then((citationText: string) => { + /* ... */ +}); + +/* ... */ +``` + +_See [use case](../src/files/domain/useCases/GetFileCitation.ts) implementation_. + +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](../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/GetFileCitation.ts b/src/files/domain/useCases/GetFileCitation.ts index 2daccc1d..8c488662 100644 --- a/src/files/domain/useCases/GetFileCitation.ts +++ b/src/files/domain/useCases/GetFileCitation.ts @@ -9,6 +9,14 @@ export class GetFileCitation implements UseCase { this.filesRepository = filesRepository; } + /** + * Returns the File citation text. + * + * @param {number} [fileId] - The dataset identifier. + * @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 {boolean} [includeDeaccessioned=false] - Indicates whether to consider deaccessioned versions in the dataset search or not. The default value is false + * @returns {Promise} + */ async execute( fileId: number, datasetVersionId: string | DatasetNotNumberedVersion = DatasetNotNumberedVersion.LATEST, From c75139ec3c787d3d4dc1d450266ada9b13e74352 Mon Sep 17 00:00:00 2001 From: GPortas Date: Wed, 21 Feb 2024 13:04:19 +0000 Subject: [PATCH 51/51] Added: doc tweaks for GetFileCitation --- docs/useCases.md | 2 ++ src/files/domain/repositories/IFilesRepository.ts | 1 + src/files/domain/useCases/GetFileCitation.ts | 2 +- 3 files changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/useCases.md b/docs/useCases.md index 850ab448..b9812185 100644 --- a/docs/useCases.md +++ b/docs/useCases.md @@ -356,6 +356,8 @@ getFileCitation.execute(fileId, datasetVersionId).then((citationText: string) => _See [use case](../src/files/domain/useCases/GetFileCitation.ts) 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 diff --git a/src/files/domain/repositories/IFilesRepository.ts b/src/files/domain/repositories/IFilesRepository.ts index efd38b2d..e3f16127 100644 --- a/src/files/domain/repositories/IFilesRepository.ts +++ b/src/files/domain/repositories/IFilesRepository.ts @@ -39,5 +39,6 @@ export interface IFilesRepository { getFileDataTables(fileId: number | string): Promise; getFile(fileId: number | string, datasetVersionId: string): Promise; + getFileCitation(fileId: number | string, datasetVersionId: string, includeDeaccessioned: boolean): Promise; } diff --git a/src/files/domain/useCases/GetFileCitation.ts b/src/files/domain/useCases/GetFileCitation.ts index 8c488662..196968f0 100644 --- a/src/files/domain/useCases/GetFileCitation.ts +++ b/src/files/domain/useCases/GetFileCitation.ts @@ -12,7 +12,7 @@ export class GetFileCitation implements UseCase { /** * Returns the File citation text. * - * @param {number} [fileId] - The dataset identifier. + * @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 * @param {boolean} [includeDeaccessioned=false] - Indicates whether to consider deaccessioned versions in the dataset search or not. The default value is false * @returns {Promise}