connoropolous-hc-web-client

hc-web-client

Thin wrapper around rpc-websockets to enable calling zome functions in Holochain apps installed in a conductor. This module aims to fill a similar role to web3.js and allow for connecting to a holochain instance in a variety of scenarios.

Installation

The module can either be imported and used as part of a compiled web application or used in pure HTML. In the first case it is reccomended to download and install via npm npm install @holochain/hc-web-client. It can then be imported or required using

const { connect } = require('@holochain/hc-web-client')
// or
import { connect } from '@holochain/hc-web-client'

For the pure HTML case the hc-web-client.js file in the dist/ folder must be moved to your project directory and imported using

<script type="text/javascript" src="path/to/hc-web-client-0.0.1.browser.min.js"></script>

This will add a holochainclient field to the window object.

Usage

Scenario 1

A full URL including port to the holochain interface is known and will never change. This is ok for development or very specific applications. Usage:

connect({ url: "ws://localhost:3000" }).then(({ callZome, close, onSignal }) => {
    callZome('instanceId', 'zome', 'funcName')(params)
})

Scenario 2

UI is being served by the holochain conductor. This is the most commonly anticipated usage. Interface port is unknown but valid interface is defined in the conductor config. In this case no url parameter is required and it will automatically call the conductor to retrieve the correct port to make calls on. Usage:

connect().then(({ callZome, close, onSignal }) => {
    callZome('instanceId', 'zome', 'funcName')(params)
})

Signals

It is possible for DNA source code to send signals via the Conductor, through to connected websocket clients. hc-web-client offers a built-in affordance for helping with this as well. Using it is as simple as calling onSignal with a callback to run every time that a signal is received from the conductor. Note that this can be a product of a DNA emitting a signal, or the Conductor itself emits certain types of signals, such as InstanceStats if the interface is set to admin = true in the conductor configuration hc-web-client connects to.

Example Usage

connect().then(({ callZome, close, onSignal }) => {
    onSignal((signal) => {
        console.log(signal)
    })
})

Read about how to use hdk::emit_signal in DNA source code here or here.

Conductor RPC calls

The holochain conductor exposes methods for each function of each zome of each running instance.

If the web client is connected to an admin interface there are also RPC methods to manage DNAs, UIs, interfaces and bridges. These can be called from the web client for exampe as:

connect().then(({call, close}) => {
    call('admin/dna/install_from_file')(params)
})

View the Holochain JSON-RPC API documentation.

Building

• To build for node/babel use npm run build. This will build to ./lib
• and to package for the web use npm run build:web. This will build to ./src

Contributing

Running tests

Tests can be run using npm run test

Publishing

To publish a new release to npm use the following steps. Ensure you are on the master branch then run

• npm version patch
• npm publish --access public

This will automatically build, lint, commit and push a new git tag before publishing. You can alternatively use npm version major|minor|patch to increment the correct version number. Please do not modify the version number in the package.json directly.

License

This project is licensed under the AGPL-3.0 License