Aragon Connect 0.7.0

This version adds two main things: error-first callbacks and important improvements to the React API. Please read carefully these release notes before updating to 0.7.0, as it contains breaking changes.

Error-first callbacks 🐢🚀

Starting with Connect 0.7.0, every subscription callback receives an optional error as a first parameter. This is a breaking change. Errors are now properly passed to subscription methods, the same way async methods receive them by using try / catch.

Pull request

• Move to Node-style callbacks in every subscription (#229)

Align app connector methods 📏

A number of changes have been made to align the subscription methods of the app connectors with their async counterparts, by moving their callback at the end, and accepting the same filter object.

Here is a list of the changes:

Finance

• Interface: move the callback at the end.

Tokens

• Fixes an issue on the Tokens connector where onHolders() was using the address of the app rather than the address of the token contract.
• The onHolders method now accepts filters.

Voting

• Align onCasts() with casts(): the method now accepts filters.
• Connector interface: move the callback at the end.

Pull requests

• App connectors: align subscription methods (#240)
• Update docs: Finance, Tokens and Voting (#236)

React API updates 🏗️

createAppHook() changes

Connector configuration

When using the @aragon/connect API, app connectors can receive a source connector and its options, and up to this point, passing options wasn’t possible with createAppHook(). A second parameter has been added to createAppHook(), allowing to pass a specific connector with its options:

import connectVoting from '@aragon/connect-voting'
import { createAppHook } from '@aragon/connect-react'

const useVoting = createAppHook(connectVoting, [
  'thegraph',
  { subgraphUrl: 'https://…' },
])

Dependency array to control updates

Hooks created through createAppHook() now accept a dependency array, that can get used to refresh the callback passed to it. It behaves in a very similar way to the useEffect() or useMemo() hooks, except that when no dependency array is passed, the callback doesn’t update.

import connect from '@aragon/connect'
import connectVoting from '@aragon/connect-voting'
import { createAppHook, useApp } from '@aragon/connect-react'

const useVoting = createAppHook(connectVoting)

function App() {
  const [page, setPage] = useState(0)

  const [voting] = useApp('voting')
  const [votes] = useVoting(
    voting,
    (app) => app.votes({ first: 10, skip: 10 * page }),
    [page]
  )

  return (
    <div>
      <button onClick={() => setPage(page + 1)}>prev</button>
      <button onClick={() => setPage(page - 1)}>next</button>
    </div>
  )
}

Subscribe to app connector methods

Prior to 0.7.0, it was not possible to subscribe to app methods using createAppHook(). The fetched data was returned once, and only updated when the component was mounted again. This feature has been added, and we can now subscribe to any app method, the same way non-dynamic hooks (useApp(), usePermissions(), …) update automatically. Every part of the React API is now listening to changes and reacting accordingly.

To use this feature, the subscription methods (onX) should be called without passing a callback. createAppHook() will take care of handling the subscription.

import connect from '@aragon/connect'
import connectVoting from '@aragon/connect-voting'
import { createAppHook, useApp } from '@aragon/connect-react'

const useVoting = createAppHook(connectVoting)

function App() {
   const [voting, votingStatus] = useApp('voting')

   // To enable a subscription, use app.onVotes() rather than app.votes().
   const [votes, votesStatus] = useVoting(voting, app => app.onVotes())

   return (
      // …
   )
}

Of course, it also works with the dependencies array, taking care of replacing the subscription by a new one:

import connect from '@aragon/connect'
import connectVoting from '@aragon/connect-voting'
import { createAppHook, useApp } from '@aragon/connect-react'

const useVoting = createAppHook(connectVoting)

function App() {
   const [page, setPage] = useState(0)

   const [voting] = useApp('voting')
   const [votes] = useVoting(voting, app => (

      // Note the app.onVotes() rather than app.votes().
      app.onVotes({ first: 10, skip: 10 * page })

   // The subscription will refresh every time `page` changes.
   ), [page])

   return (
      // …
   )
}

Important: this only works with app connectors enabling this syntax. The core app connectors have been updated (@aragon/connect-voting, @aragon/connect-tokens and @aragon/connect-finance), but third party app connectors need to be updated in order to support it.

Populate status.error correctly

In many cases, errors were thrown rather than populating the status.error object in the React API. It is an issue that was also happening with the JS API (see #229). It has now been fixed.

import connect from '@aragon/connect'
import connectVoting from '@aragon/connect-voting'
import { createAppHook, useApp } from '@aragon/connect-react'

const useVoting = createAppHook(connectVoting)

function App() {

   const [voting, votingStatus] = useApp('voting')
   const [votes, votesStatus] = useVoting(voting, app => app.votes())

   if (votingStatus.error) {
      return (
         <h1>Error: {votingStatus.error.message}</h1>
      )
   }

   if (votesStatus.error) {
      return (
         <h1>Error: {votesStatus.error.message}</h1>
      )
   }

   return (
      // …
   )
}

Less frequent updates

Since we replaced the GraphQL subscriptions by queries with polling (see #203), the hooks provided by the React API were updating too often, and incorrectly (see #216). Since 0.7.0, the React Hooks are now taking care of only triggering updates when a changed happened, and to only use a loading state when necessary.

Pull request

• React API improvements (#233)

Other changes

• Bump radspec version (#253)
• Finance connector: remove non-null operators (#244)
• Ethers: use named imports (#208)
• Add missing SubscriptionCallback types (#241)
• Docs: Remove features we don't support yet (#213)
• Tests: Use aragon subgraph on finance connector (#251)
• Add pre release instructions (#267)
• Run prettier on commits (through husky + precise-commits) (#207)
• publish-version.sh: add the possibility to specify a version and tag (#248, #249)