Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

New documentation for js-dataverse v2 #118

Merged
merged 56 commits into from
Feb 23, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
56 commits
Select commit Hold shift + click to select a range
e27af2d
Stash: new docs structure WIP
GPortas Jan 24, 2024
6fb2f1b
Added: new useCases section and Api Config installation subsection (e…
GPortas Jan 24, 2024
4e63e54
Stash: initialization docs WIP
GPortas Jan 24, 2024
e79e4d1
Added: info to installation/initialization section
GPortas Jan 24, 2024
0db5faa
Stash: useCase docs WIP. Added initial docs for GetAllDatasetPreviews…
GPortas Jan 24, 2024
9d0dbcb
Added: GetAllDatasetPreviews doc tweak
GPortas Jan 24, 2024
16cdf9a
Added: table of contents to useCases md and structure tweaks
GPortas Jan 26, 2024
a0f4ffd
Added: empty TOC sections to useCases.md
GPortas Jan 26, 2024
167801e
Added: DDD link
GPortas Jan 26, 2024
e65723e
Added: GetDataset use case docs
GPortas Jan 26, 2024
bd407a9
Added: doc tweaks
GPortas Jan 26, 2024
579b98e
Stash: GetDatasetCitation docs WIP
GPortas Jan 26, 2024
291b4a0
Added: GetDatasetCitation docs
GPortas Jan 31, 2024
c1039f1
Added: getDatasetLocks docs
GPortas Jan 31, 2024
5a76991
Added: GetDatasetSummaryFieldNames docs
GPortas Jan 31, 2024
2a175bc
Added: GetDatasetUserPermissions docs
GPortas Jan 31, 2024
ed05893
Added: Private URL use cases docs
GPortas Jan 31, 2024
4cb3808
Merge branch 'develop' of github.com:IQSS/dataverse-client-javascript…
GPortas Jan 31, 2024
54d92f0
Added: GetDatasetFiles docs
GPortas Feb 1, 2024
71cc2f0
Fixed: usecase doc title
GPortas Feb 1, 2024
4f19efd
Added: GetDatasetFileCounts docs
GPortas Feb 1, 2024
4714b74
Added: doc tweaks for getDatasetFileCounts use case
GPortas Feb 2, 2024
b419cd4
Added: getDatasetFilesTotalDownloadSize docs
GPortas Feb 2, 2024
b1886fe
Added: GetFileDownloadCount docs and general doc structure tweaks
GPortas Feb 2, 2024
4c93176
Fixed: docs structure
GPortas Feb 2, 2024
7e9a384
Added: getFileDataTables docs
GPortas Feb 2, 2024
bc65e6e
Added: GetFileUserPermissions docs
GPortas Feb 2, 2024
53c7da7
Added: GetMetadataBlockByName docs
GPortas Feb 2, 2024
236e862
Added: table of contents tweak
GPortas Feb 2, 2024
5d2bd02
Added: GetCurrentAuthenticatedUser docs
GPortas Feb 2, 2024
6131ace
Added: docs for getDataverseVersion
GPortas Feb 5, 2024
048d4b2
Added: docs for GetMaxEmbargoDurationInMonths
GPortas Feb 5, 2024
0e825a9
Added: GetZipDownloadLimit docs
GPortas Feb 5, 2024
f0d9b38
Changed: CONTRIBUTING.md
GPortas Feb 5, 2024
4deb4f9
Added: doc tweaks
GPortas Feb 5, 2024
ffd0e52
Merge branch 'develop' of github.com:IQSS/dataverse-client-javascript…
GPortas Feb 5, 2024
39ee39f
Added: docs for GetFile use case
GPortas Feb 5, 2024
9e39abf
Fixed: doc link
GPortas Feb 5, 2024
c846f85
feat(Guide): add .npmrc instructions
MellyGray Feb 19, 2024
dbdbeae
feat(Guide): re-write some lines for clarity
MellyGray Feb 19, 2024
04b20d4
fix(Guides): wrong import in code example
MellyGray Feb 19, 2024
e413555
fix(Guides): add optional `datasetVersionId`
MellyGray Feb 19, 2024
37e0fb0
fix(Guides): optional `datasetVersionId`
MellyGray Feb 19, 2024
73fe572
Merge branch '113-documentation-v2' of https://github.com/IQSS/datave…
MellyGray Feb 19, 2024
4fe029a
fix(Guides): add optional `datasetVersionId` to GetDatasetFileCounts
MellyGray Feb 19, 2024
19559a0
fix(Guides): add optional datasetVersionId to GetDatasetFilesTotalDow…
MellyGray Feb 19, 2024
99afa32
fix(Guides): add optional datasetVersionId to GetDatasetFiles
MellyGray Feb 19, 2024
dd4fbee
fix(Guides): add embargo duration returned values explanation
MellyGray Feb 19, 2024
77d894c
Merge branch '113-documentation-v2' of https://github.com/IQSS/datave…
MellyGray Feb 19, 2024
0b358a7
fix: replace turndown library by NodeHtmlMarkdown to fix nextjs incom…
MellyGray Feb 19, 2024
a687c63
fix: FileAccessStatus enum values
MellyGray Feb 19, 2024
3fc1ad2
Merge branch 'develop' of github.com:IQSS/dataverse-client-javascript…
GPortas Feb 20, 2024
ea8f2a8
Added: use case docs for CreateDataset
GPortas Feb 21, 2024
3e71ba9
Fixed: GetDatasetCitation method docs
GPortas Feb 21, 2024
c20cd3b
Added: use case docs for GetFileCitation
GPortas Feb 21, 2024
c75139e
Added: doc tweaks for GetFileCitation
GPortas Feb 21, 2024
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 17 additions & 9 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Please, do not hesitate to contact us through:

- Zulip: https://dataverse.zulipchat.com/#narrow/stream/410361-ui-dev
- Google Group: https://groups.google.com/g/dataverse-dev
86 changes: 6 additions & 80 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,85 +1,11 @@
# dataverse-client-javascript
# js-dataverse

[![npm](https://img.shields.io/npm/v/js-dataverse.svg)](https://www.npmjs.com/package/js-dataverse)

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](./docs/useCases.md)
- [Local Development](./docs/localDevelopment.md)
- [Contributing](./CONTRIBUTING.md)
- [License](./LICENSE)
108 changes: 108 additions & 0 deletions docs/installation.md
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I tried installing js-dataverse and testing it in a Vite and a Nextjs project. It worked with Vite, but with Next.js I got an error:
Screenshot 2024-02-07 at 11 58 43 AM
@MellyGray suggested in Slack that moving turndown to devDependencies might fix it https://iqss.slack.com/archives/C053B9C65T3/p1707326560379899

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@ekraffmiller @GPortas, I was mistaken; the library is used not only in the tests but also in the source code. There are open issues in both the Turndown and Next.js repositories, indicating that this problem remains unresolved.

Turndown Issue #378

Next.js Issue #59312

Considering this, I'm thinking about switching to a different library for HTML to Markdown conversion, such as node-html-markdown. What are your thoughts?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You can give it a try to change it if it's straightforward, if it isn't, I suggest to create a separate issue to fix it.

Original file line number Diff line number Diff line change
@@ -0,0 +1,108 @@
# Installation

Recommended versions node >=16 and npm >=8.

## 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

Install the package stable version using npm:

```bash
npm install js-dataverse
```

## 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
ekraffmiller marked this conversation as resolved.
Show resolved Hide resolved
ekraffmiller marked this conversation as resolved.
Show resolved Hide resolved


### 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=<YOUR_GITHUB_AUTH_TOKEN>
@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.

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. 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.

For example, in a React application, we can globally initialize the `ApiConfig` object in the `App` file, like this:

```typescript
ApiConfig.init(<DATAVERSE_API_BASE_URL>, DataverseApiAuthMechanism.API_KEY, <DATAVERSE_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.
95 changes: 95 additions & 0 deletions docs/localDevelopment.md
Original file line number Diff line number Diff line change
@@ -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
```
Loading
Loading