graphxr-api v0.0.176

graphxr-api

graphxr-api is a module which provides an API to GraphXR internals

Documentation

Documentation is hosted on GitHub

Usage

// Latest
GraphXR = (await require('graphxr-api')).init()

// Target a version
GraphXR = (await require('graphxr-api@0.0.3')).init()

// Get nodes
GraphXR.getNodes()

Minimum Version Requirements

If a version of the API depends on a version of GraphXR which has not been released, please increase the minimum required version in src/minimumRequirements.ts. For example:

export const MINIMUM_GRAPHXR_VERSION = "2.11.0";

On init, the API will ask GraphXR for its version by fetching /api/install/version. If the version is greater than the minimum version, the API will throw an exception.

If GraphXR cannot be detected, init will log a warning to the console.

If the minimum requirements are met, init will return the API.

Build

yarn build

Testing

Unit (src/__tests__/)

These are fast and mock GraphXR internals.

Run once: yarn test

Run on save: yarn test:watch

Integration (cypress/)

The integration tests are slower and run the API against a local GraphXR instance.

First create file .env in the root folder (web/api/.env) with contents.

# Points at a GraphXR instance
CYPRESS_baseUrl=https://localhost:3000

# A GraphXR user's username
CYPRESS_ADMIN_EMAIL=cypress@kineviz.com

# A GraphXR user's password
CYPRESS_ADMIN_PASSWORD=4SuG2GvbZs2K4fN

Run once: yarn test:integration

Coverage

Running the tests will result in a text report:

-------------------|---------|----------|---------|---------|-------------------
File               | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s
-------------------|---------|----------|---------|---------|-------------------
All files          |     100 |      100 |     100 |     100 |
 addNodes.ts       |     100 |      100 |     100 |     100 |
 clearGraph.ts     |     100 |      100 |     100 |     100 |
 getNodes.ts       |     100 |      100 |     100 |     100 |
 getScene.ts       |     100 |      100 |     100 |     100 |
 index.ts          |     100 |      100 |     100 |     100 |
 makeNode.ts       |     100 |      100 |     100 |     100 |
 removeNodeById.ts |     100 |      100 |     100 |     100 |
 setRuntime.ts     |     100 |      100 |     100 |     100 |
-------------------|---------|----------|---------|---------|-------------------

This project enforces 100% coverage across the board.

A more detailed report is located at coverage/lcov-report/index.html.

Documentation

yarn build:docs will run tsdoc and generate html at docs/index.html

Contributing

This project enforces code linting and styling rules via pre-commit hooks.

How to add a function

1. Create a new file for the function e.g. src/myFunction.ts
2. Write a unit test e.g. src/__tests__/myFunction.spec.ts
3. Write an integration test e.g. cypress/integration/graphxr-api.spec.ts
4. Run unit tests: yarn test
5. Start a GraphXR instance and run integration tests: yarn test:integration
6. Commit your change
7. [optional] Publish a new version to NPM

How to edit existing code.

1. Make changes to one or more files
2. Update unit and integration tests appropriately
3. Run unit and integration tests

Publishing to NPM

This process will do the following

• ensure you are logged into npm
• ensure working directory is clean
• run tests
• build the API bundle
• build the documentation
• bump the package.json version
• commit the bundle, docs, and package.json
• tag the commit with the new version
• push the commits
• push the tag
• publish the package to npm

In a terminal:

1. yarn login
2. yarn release

Most of the time you will run yarn release

Optional arguments to yarn release

• --no-verify Optional. Skips the tests
• --no-publish-docs Optional. Skips building and publishing docs
• -v, --version <version> Optional. Release type: v1.0.34 | patch | minor | major
• -m, --tag-message <message> Optional. Tag message.