Highlights

BaseActionWatcher and ExpressActionWatcher

The BaseActionWatcher has three new public methods: start, pause, and info, which can be called at any time after instantiation to start or pause the polling loop, or get information about the Watcher as well as its internal Reader and Handler. The new ExpressActionWatcher subclass exposes these methods on a REST API endpoint via Express. This now makes Demux interactive, which opens up new production and development workflows. The ExpressActionWatcher is now recommended as the preferred ActionWatcher.

Deferred Effects

When defining your Effects, you may now add an optional property, deferUntilIrreversible. When true, the effect will only run when the block that triggered it becomes irreversible.

Fixed continuation / rollback bug

There was a pesky bug that prohibited you from continuing indexing after stopping demux in certain cases, which also caused problems when rolling back from micro forks. This issue has been resolved.

Error Classes

Custom error classes have been created, which make it easier to handle specific errors that are thrown by Demux.

Complete API changes

AbstractActionHandler

• Changed lastProcessedBlockNumber, lastProcessedBlockHash, and handlerVersionName properties to be public.
• Changed the signature of handleBlock to (nextBlock: NextBlock, isReplay: boolean)
• handleBlock method now returns either null or a number, if it needs to request the Action Reader for a specific block by number.
• New public info property, which returns information about the handler's state
• New abstract protected setup method, which is implemented to set up any dependent structures needed by the implemented class (such as database connections).
• New public initialize method, which runs the above setup method as well as any other internally needed initialization.
• New protected matchActionType method, which is used when comparing action types from block data and the action types that Updaters and Effects are subscribed to, returning true of false if it should match or not. By default, this function checks for equivalency (===), however this can be implemented to match wildcards, for example.
• Changed the signature of applyUpdaters to (state: any, block: Block, context: any, isReplay: boolean,)
• Changed the signature of runEffects to (versionedActions: VersionedAction[], context: any, nextBlock: NextBlock)
• Changed the signature of handleActions to (state: any, context: any, nextBlock: NextBlock, isReplay: boolean)

AbstractActionReader

• Signature of constructor has changed to a single options object: (options: ActionReaderOptions = {})
• Within the options object, there is no maxHistoryLength, as the history is now optimized in length via lastIrreversibleBlock.
• Public method nextBlock has been renamed to getNextBlock and its return type is now Promise<NextBlock>
• New public info property, which returns information about the reader's state
• New abstract protected setup method, which is implemented to set up any dependent structures needed by the implemented class (such as blockchain connections).
• New public initialize method, which runs the above setup method as well as any other internally needed initialization.

BaseActionWatcher

• New public method start, which will start the watcher's polling loop if paused.
• New public method pause, which will pause the watcher's polling loop.
• New public info property, which returns information about the watcher's state, as well as the states of the passed in reader and handler.
• New public status property, which returns the watcher's status, which is one of the IndexingStatus enum.

Interfaces

• All interfaces are now exported and available to external modules
• New ActionReaderOptions interface, which describes the possible options passed to the AbstractActionReader constructor.
• New NextBlock interface, which contains information about the next block the handler should process.
• New BlockMeta interface, which contains supplementary information about the Block passed to the ActionHandler.
• Interface Effect now has optional deferUntilIrreversible property, which, when true, indicates the effect should not run until irreversibility of the block that triggered it is reached.
• New VersionedAction interface, which helps the ActionHandler correlate the ActionType with the HandlerVersion needed to trigger Effects.
• New CurriedEffectRun interface, which curries the run function on deferred Effects with arguments, preparing it to be run once irreversibility is reached.
• New DeferredEffects interface, which keys block numbers to their respective CurriedEffectRuns.
• New ReaderInfo interface, which is used for the AbstractActionReader's info property.
• New HandlerInfo interface, which is used for the AbstractActionHandler's info property.
• New DemuxInfo interface, which is used for the BaseActionWatcher's info property.
• New IndexingStatus enum, which contains all the possible statuses for the BaseActionWatcher.

Block.one makes its contribution on a voluntary basis as a member of the EOSIO community and is not responsible for ensuring the overall performance of the software or any applications related thereto. We make no representation, warranty, guarantee or undertaking in respect of the releases described herein and the related GitHub release or the EOSIO software, whether expressed or implied, and disclaim all liability that may arise from any use of the software for any purpose.

Breaking changes

On the AbstractActionReader:

• Protected method historyExhausted was removed.
• A new public abstract method getLastIrreversibleBlockNumber was added.

Bug Fixes

Effects are now handled correctly when using HandlerVersions.

This release enables the ability to change sets of Updater and Effects facilitated by the interface HandlerVersion. HandlerVersions have a versionName string, and also Updater and Effect arrays. When you instantiate an implementation of AbstractActionHandler, you give it an array of HandlerVersions. By default, it will load either the one named v1 or the first one, if one by that name does not exist. To change versions, simply return a string from your Updater's apply function. If a HandlerVersion exists with a versionName as the returned string, it will switch to that HandlerVersion.

Breaking changes

• Interfaces have been updated/restructured
  • There is now a parent interface ActionListener that Updater and Effect interfaces inherit from
  • Updater's run attribute has been renamed to apply; new optional revert attribute
  • New optional onRollback parameter on Effect
  • New HandlerVersion interface
  • IndexState now requires an additional handlerVersionName attribute
  • IndexState now keeps track of isReplay state
• AbstractActionHandler
  • Constructor now takes an array of HandlerVersions instead of Updater and Effect arrays
  • updateIndexState now takes a handlerVersionName parameter
  • runUpdaters has been renamed to applyUpdaters
  • When the apply method on Updaters return a value, this signals runUpdaters to update the HandlerVersion to the returned versionName
  • To accommodate changing HandlerVersions in the middle of a block, runEffects now takes a versionedActions argument to decide which effects to run

Bugfixes

• Example now successfully recovers from micro-forks

Breaking changes

On the AbstractActionReader:

• Protected method rollback has been renamed to resolveFork
• Protected method rollbackExhausted has been renamed to historyExhausted

This is to differentiate the methods from the AbstractActionHandler's rollbackTo method. If you were overriding these methods, you will need to update their names.

Bug Fixes

Fork resolution now rolls back the correct number of blocks.

• Better test coverage
• Various bug fixes

npm package name is now demux

We have obtained the NPM package name demux and in this release we have switched to it.

This is a project restructure that removes abstract class implementations. Class implementations will now reside in separate repositories.

Breaking changes

• Project now has simpler, flatter directory structure, and flatter import tree. Classes are now available at the root level, e.g.:

// ES6
import { AbstractActionHandler } from "demux-js"
// Using require
const { AbstractActionHandler } = require("demux-js")

• Since class implementations are removed, you'll now have to require either demux-eos or demux-postgres depending on which one you need.

• Block info has now been factored into its own interface BlockInfo, and is thus nested as its own attribute inside Block. This is useful if you ever need to extend block info within your own implementations.

Initial release of demux-js.