@valueflows/vf-graphql-holochain
v0.0.2-alpha.1
Published
GraphQL schema bindings for the Holochain implementation of ValueFlows
Downloads
463
Readme
hREA GraphQL schema binding
Binds Holochain cell connections for hREA to the ValueFlows protocol spec, thus creating a pluggable and extensible ValueFlows implementation backed by multiple distributed & interconnected Holochain networks.
Work in progress!
Usage
This module provides a runtime-configurable generator function which returns a GraphQL schema for any configured arrangement of hREA modules. You can think of the objects returned by this function as single "collaboration spaces", where groups of Holochain DNA modules with specific, coordinated purposes are arranged together to form one coherent logical "place" that people hang out in.
1 instance of bindSchema()
= 1 agent acting within 1 collaboration space. It is important to remember this in an agent-centric environment, especially when composing multiple hREA collaboration spaces together to form "cross-membrane" interfaces.
It is expected that you will most often use this module in an Apollo-based application. In the simplest case, your app initialisation logic will probably look something like the @vf-ui/graphql-client-holochain
module (also available in this repository), which wraps the @valueflows/vf-graphql-holochain
schema in a GraphQLClient
interface compatible with @vf-ui/graphql-client-mock
.
In most cases, you should be able to use @vf-ui/graphql-client-holochain
directly from NPM. This module is for advanced usage in client applications seeking to overlay and interweave collaboration spaces in specific and nuanced ways.
Required options
conductorUri
specifies the websocket URI for connecting to the Holochain conductor for this set of DNA connections. Usually this isws://localhost:4001
. Note that you can create multiple instances connected to multipleconductorUri
s in order to simulate disparate hosts in multi-agent testing or usage.adminConductorUri
specifies the websocket URI for connecting to the Holochain conductor "admin service" for this set of DNA connections.dnaConfig
takes a mapping of pre-specified string module identifiers and associates them with the actual HolochainCellId
to connect to. There are different ways of determining appropriateCellId
s depending on the executing context.
See types.ts
for a complete reference of configuration options.
Schema extension and additional service integration
The two optional parameters extensionSchemas
and extensionResolvers
allow the dynamic injection of other non-VF functionality into the collaboration space. For example: geolocation functionality, file uploads, commenting, tagging, chat, blogging…
Simply specify extensionSchemas
as an array of GraphQL SDL schema strings, and extensionResolvers
as an additional mapping of GraphQL resolver callbacks to include the additional functionality within the collaboration space's API bindings.
Partial schema generation
The enabledVFModules
option, if specified, controls the subset of ValueFlows modules to bind when initialising the collaboration space. Not all economic networks require all features, and this option allows your network to shed unnecessary extra weight. Both the schema fields and resolvers for non-present modules will be omitted from the generated schema.
Multiple collaboration spaces
The dnaConfig
option allows the callee to specify custom DNA identifiers to bind GraphQL functions to. For each hREA module ID (see the directory names under /bundles/dna
in this repository), a runtime CellId
must be provided as an instance of that DNA to bind to.
By targeting multiple sets of DNAs, multiple "collaboration spaces" can be initialised for a single client application. Several GraphQL APIs can be interacted with via the standard ValueFlows specification. User interfaces should make explicit the scope of data and destination networks to perform query and mutation operations against.
TODO: locate or author combinators for composing collaboration spaces. See https://github.com/h-REA/hREA/issues/159
For more examples of scenarios involving complexly overlapping collaboration spaces, see the tests under /test/social-architectures
in the hREA repository.
Direct access to resolver callbacks
In some cases, tooling may require low-level access to the GraphQL resolver callbacks (for example when requiring resolvers to be passed separately to an SDL schema string). You can use the provided generateResolvers(options: ResolverOptions)
method to create such functions, bound to the set of DNA modules specified via options.dnaConfig
.
import { makeExecutableSchema } from '@graphql-tools/schema'
import { generateResolvers, VfModule, hreaExtensionSchemas } from '@valueflows/vf-graphql-holochain'
const { buildSchema, printSchema } = require('@valueflows/vf-graphql')
const enabledVFModules = [VfModule.Measurement, VfModule.Knowledge, VfModule.Observation]
const conductorUri = '...'
const adminConductorUri = '...'
const appId = '...'
const dnaConfig = {
//...
}
const resolvers = generateResolvers({
enabledVFModules,
conductorUri,
adminConductorUri,
appId,
dnaConfig
})
const extensionSchemas = [hreaExtensionSchemas.associateMyAgentExtension]
const schema = makeExecutableSchema({
typeDefs: printSchema(buildSchema(enabledVFModules, extensionSchemas)),
resolvers,
})
Note that the IDs of ValueFlows modules in enabledVFModules
above do not map exactly 1:1 with the hREA DNA identifiers in dnaConfig
. For example, if the hREA specification DNA is in use, you may wish to include VfModule.Action
, VfModule.Unit
, VfModule.ProcessSpecification
and VfModule.ResourceSpecification
all of which are included in that DNA. The DNAs are more "umbrellas" and the VfModule
s are more granular.
Repository structure
types.ts
contains implementations for the GraphQL scalar types defined in the VF spec. Any system connecting to a VF-compatible schema requires these scalar types to be defined.connection.ts
is the Holochain conductor websocket connection handling logic.
Other files implement the query bindings between the linked hREA app DNAs and GraphQL entity relationships:
queries/*.ts
implement the root-level queries exposed by the API.mutations/*.ts
implement write operations for interacting with the app DNAs.resolvers/*.ts
contains the logic for resolving links between different records.
Building and publishing to NPM
- You will need to be given access to the VF NPM org in order to update the module on the registry. You can request access in Discord
- Bump the version in
package.json
& commit to the repository - Run
pnpm run build
from this directory orpnpm run build:graphql:adapter
from the root of the hREA repository - Run
pnpm publish --access public
from this directory - Tag the current release in git and push the tag to
origin
License
Licensed under an Apache 2.0 license.