npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@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 is ws://localhost:4001. Note that you can create multiple instances connected to multiple conductorUris 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 Holochain CellId to connect to. There are different ways of determining appropriate CellIds 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 VfModules 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 or pnpm 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.