-
Notifications
You must be signed in to change notification settings - Fork 8
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
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 6fb2f1b
Added: new useCases section and Api Config installation subsection (e…
GPortas 4e63e54
Stash: initialization docs WIP
GPortas e79e4d1
Added: info to installation/initialization section
GPortas 0db5faa
Stash: useCase docs WIP. Added initial docs for GetAllDatasetPreviews…
GPortas 9d0dbcb
Added: GetAllDatasetPreviews doc tweak
GPortas 16cdf9a
Added: table of contents to useCases md and structure tweaks
GPortas a0f4ffd
Added: empty TOC sections to useCases.md
GPortas 167801e
Added: DDD link
GPortas e65723e
Added: GetDataset use case docs
GPortas bd407a9
Added: doc tweaks
GPortas 579b98e
Stash: GetDatasetCitation docs WIP
GPortas 291b4a0
Added: GetDatasetCitation docs
GPortas c1039f1
Added: getDatasetLocks docs
GPortas 5a76991
Added: GetDatasetSummaryFieldNames docs
GPortas 2a175bc
Added: GetDatasetUserPermissions docs
GPortas ed05893
Added: Private URL use cases docs
GPortas 4cb3808
Merge branch 'develop' of github.com:IQSS/dataverse-client-javascript…
GPortas 54d92f0
Added: GetDatasetFiles docs
GPortas 71cc2f0
Fixed: usecase doc title
GPortas 4f19efd
Added: GetDatasetFileCounts docs
GPortas 4714b74
Added: doc tweaks for getDatasetFileCounts use case
GPortas b419cd4
Added: getDatasetFilesTotalDownloadSize docs
GPortas b1886fe
Added: GetFileDownloadCount docs and general doc structure tweaks
GPortas 4c93176
Fixed: docs structure
GPortas 7e9a384
Added: getFileDataTables docs
GPortas bc65e6e
Added: GetFileUserPermissions docs
GPortas 53c7da7
Added: GetMetadataBlockByName docs
GPortas 236e862
Added: table of contents tweak
GPortas 5d2bd02
Added: GetCurrentAuthenticatedUser docs
GPortas 6131ace
Added: docs for getDataverseVersion
GPortas 048d4b2
Added: docs for GetMaxEmbargoDurationInMonths
GPortas 0e825a9
Added: GetZipDownloadLimit docs
GPortas f0d9b38
Changed: CONTRIBUTING.md
GPortas 4deb4f9
Added: doc tweaks
GPortas ffd0e52
Merge branch 'develop' of github.com:IQSS/dataverse-client-javascript…
GPortas 39ee39f
Added: docs for GetFile use case
GPortas 9e39abf
Fixed: doc link
GPortas c846f85
feat(Guide): add .npmrc instructions
MellyGray dbdbeae
feat(Guide): re-write some lines for clarity
MellyGray 04b20d4
fix(Guides): wrong import in code example
MellyGray e413555
fix(Guides): add optional `datasetVersionId`
MellyGray 37e0fb0
fix(Guides): optional `datasetVersionId`
MellyGray 73fe572
Merge branch '113-documentation-v2' of https://github.com/IQSS/datave…
MellyGray 4fe029a
fix(Guides): add optional `datasetVersionId` to GetDatasetFileCounts
MellyGray 19559a0
fix(Guides): add optional datasetVersionId to GetDatasetFilesTotalDow…
MellyGray 99afa32
fix(Guides): add optional datasetVersionId to GetDatasetFiles
MellyGray dd4fbee
fix(Guides): add embargo duration returned values explanation
MellyGray 77d894c
Merge branch '113-documentation-v2' of https://github.com/IQSS/datave…
MellyGray 0b358a7
fix: replace turndown library by NodeHtmlMarkdown to fix nextjs incom…
MellyGray a687c63
fix: FileAccessStatus enum values
MellyGray 3fc1ad2
Merge branch 'develop' of github.com:IQSS/dataverse-client-javascript…
GPortas ea8f2a8
Added: use case docs for CreateDataset
GPortas 3e71ba9
Fixed: GetDatasetCitation method docs
GPortas c20cd3b
Added: use case docs for GetFileCitation
GPortas c75139e
Added: doc tweaks for GetFileCitation
GPortas File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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 | ||
``` |
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
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:
@MellyGray suggested in Slack that moving turndown to devDependencies might fix it https://iqss.slack.com/archives/C053B9C65T3/p1707326560379899
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
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.