Merge pull request #12 from EOSIO/typedoc-docs

Typedoc docs

README.md

@@ -1,3 +1,5 @@
+# demux-js
+
 Demux is a backend infrastructure pattern for sourcing blockchain events to deterministically update queryable datastores and trigger side effects. This library serves as a reference implementation of that pattern for use with Node applications.
 
 ## Installation

build-docs.sh

@@ -0,0 +1 @@
+./node_modules/.bin/typedoc --mode file --theme minimal --target "ES6" --exclude "**/*.test.ts,**/testHelpers/*" --hideGenerator --excludeExternals --excludeNotExported --includeDeclarations --readme none --out docs

package.json

@@ -30,14 +30,16 @@
     "ts-jest": "^23.0.0",
     "tslint": "^5.10.0",
     "tslint-eslint-rules": "^5.3.1",
+    "typedoc": "^0.11.1",
     "typescript": "^2.9.2"
   },
   "scripts": {
     "compile": "tsc",
     "watch": "tsc -w",
     "example": "./run-example.sh",
     "lint": "tslint -c tslint.json src/**/*.ts",
-    "test": "jest"
+    "test": "jest",
+    "build-docs": "./build-docs.sh"
   },
   "jest": {
     "moduleFileExtensions": [

src/demux/handlers/AbstractActionHandler.test.ts

@@ -1,5 +1,5 @@
 import { Block, IndexState } from "../../../index"
-import AbstractActionHandler from "./AbstractActionHandler"
+import { AbstractActionHandler } from "./AbstractActionHandler"
 
 class TestActionHandler extends AbstractActionHandler {
   // tslint:disable-next-line

src/demux/handlers/AbstractActionHandler.ts

@@ -1,6 +1,12 @@
-import {Block, Effect, IndexState, Updater} from "../../../index"
-
-export default abstract class AbstractActionHandler {
+import { Block, Effect, IndexState, Updater } from "../../../index"
+
+/**
+ * Takes `block`s output from implementations of `AbstractActionReader` and processes their actions through
+ * `Updater`s and `Effect`s. Pass an object exposing a persistence API as `state` in the `handleWithState`
+ * method. Persist and retrieve information about the last block processed with `updateIndexState` and
+ * `loadIndexState`.
+ */
+export abstract class AbstractActionHandler {
   protected lastProcessedBlockNumber: number = 0
   protected lastProcessedBlockHash: string = ""
 
@@ -12,11 +18,6 @@ export default abstract class AbstractActionHandler {
 
   /**
    * Receive block, validate, and handle actions with updaters and effects
-   * @param {Block} block
-   * @param {boolean} isRollback
-   * @param {boolean} isFirstBlock
-   * @param {boolean} isReplay
-   * @returns {Promise<[boolean, number]>}
    */
   public async handleBlock(
     block: Block,
@@ -66,21 +67,27 @@ export default abstract class AbstractActionHandler {
     return [false, 0]
   }
 
+  /**
+   * Updates the `lastProcessedBlockNumber` and `lastProcessedBlockHash` meta state, coinciding with the block
+   * that has just been processed. These are the same values read by `updateIndexState()`.
+   */
   protected abstract async updateIndexState(state: any, block: Block, isReplay: boolean, context?: any): Promise<void>
 
+  /**
+   * Returns a promise for the `lastProcessedBlockNumber` and `lastProcessedBlockHash` meta state, coinciding with the block
+   * that has just been processed. These are the same values written by `updateIndexState()`.
+   * @returns A promise that resolves to an `IndexState`
+   */
   protected abstract async loadIndexState(): Promise<IndexState>
 
   /**
-   * Calls handleActions with the appropriate state using the passed in handle function
-   * @param {(state: any) => void} handle
+   * Calls handleActions with the appropriate state passed by calling the `handle` parameter function.
+   * Optionally, pass in a `context` object as a second parameter.
    */
   protected abstract async handleWithState(handle: (state: any, context?: any) => void): Promise<void>
 
   /**
    * Process actions against deterministically accumulating updater functions.
-   * @param {any} state
-   * @param {Block} block
-   * @param {any} context
    */
   protected async runUpdaters(
     state: any,
@@ -100,9 +107,6 @@ export default abstract class AbstractActionHandler {
 
   /**
    * Process actions against asynchronous side effects.
-   * @param {any} state
-   * @param {Block} block
-   * @param {any} context
    */
   protected runEffects(
     state: any,
@@ -124,18 +128,11 @@ export default abstract class AbstractActionHandler {
    * Will run when a rollback block number is passed to handleActions. Implement this method to
    * handle reversing actions full blocks at a time, until the last applied block is the block
    * number passed to this method. If replay is true, effects should not be processed
-   *
-   * @param {number} blockNumber
-   * @returns {Promise<void>}
    */
   protected abstract async rollbackTo(blockNumber: number): Promise<void>
 
   /**
-   * Calls runUpdaters and runEffects on the given actions
-   * @param {any} state
-   * @param {Block} block
-   * @param {any} context
-   * @param {boolean} isReplay
+   * Calls `runUpdaters` and `runEffects` on the given actions
    */
   protected async handleActions(
     state: any,

src/demux/handlers/index.ts

@@ -1,9 +1,7 @@
-import AbstractActionHandler from "./AbstractActionHandler"
-import MassiveActionHandler from "./postgres/MassiveActionHandler"
+import { AbstractActionHandler } from "./AbstractActionHandler"
+import { postgres } from "./postgres"
 
-module.exports = {
+export const handlers = {
   AbstractActionHandler,
-  postgres: {
-    MassiveActionHandler,
-  },
+  postgres,
 }

src/demux/handlers/postgres/MassiveActionHandler.test.ts

@@ -1,7 +1,7 @@
 import Docker from "dockerode"
 import massive from "massive"
-import MassiveActionHandler from "./MassiveActionHandler"
-import JsonActionReader from "../../readers/testing/JsonActionReader"
+import { MassiveActionHandler } from "./MassiveActionHandler"
+import { JsonActionReader } from "../../readers/testing/JsonActionReader"
 import blockchain from "./testHelpers/blockchain.json"
 import * as migrate from "./testHelpers/migrate"
 import * as dockerUtils from "./testHelpers/docker"

src/demux/handlers/postgres/MassiveActionHandler.ts

@@ -1,7 +1,11 @@
-import AbstractActionHandler from "../AbstractActionHandler"
-import {Block, Effect, IndexState, Updater} from "../../../../index"
+import { AbstractActionHandler } from "../AbstractActionHandler"
+import { Block, Effect, IndexState, Updater } from "../../../../index"
 
-export default class MassiveActionHandler extends AbstractActionHandler {
+/**
+ * Connects to a Postgres database using [MassiveJS](https://github.com/dmfay/massive-js). This expects that
+ * the database is already migrated, including an `_index_state` table. Refer to the tests for more information.
+ */
+export class MassiveActionHandler extends AbstractActionHandler {
   constructor(
     protected updaters: Updater[],
     protected effects: Effect[],

src/demux/handlers/postgres/index.ts

@@ -0,0 +1,3 @@
+import { MassiveActionHandler } from "./MassiveActionHandler"
+
+export const postgres = { MassiveActionHandler }

src/demux/readers/AbstractActionReader.ts

@@ -1,6 +1,9 @@
 import { Block } from "../../../index"
 
-export default abstract class AbstractActionReader {
+/**
+ * Reads blocks from a blockchain, outputting normalized `Block` objects.
+ */
+export abstract class AbstractActionReader {
   public headBlockNumber: number = 0
   public currentBlockNumber: number
   public isFirstBlock: boolean = true
@@ -139,16 +142,15 @@ export default abstract class AbstractActionReader {
   }
 
   /**
-   * When history is exhausted in rollback(), this is run to handle the situation.
+   * When history is exhausted in rollback(), this is run to handle the situation. If left unimplemented,
+   * then only instantiate with `onlyIrreversible` set to true.
    */
-  public rollbackExhausted() {
+  protected rollbackExhausted() {
     throw Error("Rollback history has been exhausted, and no rollback exhaustion handling has been implemented.")
   }
 
   /**
    * Move to the specified block.
-   * @param {number} blockNumber
-   * @returns {Promise<void>}
    */
   public async seekToBlock(blockNumber: number): Promise<void> {
     // Clear current block data

src/demux/readers/eos/NodeosActionReader.test.ts

@@ -1,4 +1,4 @@
-import NodeosActionReader from "./NodeosActionReader"
+import { NodeosActionReader } from "./NodeosActionReader"
 
 const rawBlock = {
   timestamp: "2018-06-16T05:59:49.500",

src/demux/readers/eos/NodeosActionReader.ts

@@ -1,17 +1,14 @@
-/**
- * Reads an EOSIO nodeos node to get actions.
- * It is important to note that deferred transactions will not be included, as these are not accessible without plugins.
- */
-
-import AbstractActionReader from "../AbstractActionReader"
-import NodeosBlock from "./NodeosBlock"
+import { AbstractActionReader } from "../AbstractActionReader"
+import { NodeosBlock } from "./NodeosBlock"
 
 import request from "request-promise-native"
 
 /**
- * Implementation of an ActionReader that polls a node using `get_block`.
+ * Reads from an EOSIO nodeos node to get blocks of actions.
+ * It is important to note that deferred transactions will not be included,
+ * as these are currently not accessible without the use of plugins.
  */
-export default class NodeosActionReader extends AbstractActionReader {
+export class NodeosActionReader extends AbstractActionReader {
   protected nodeosEndpoint: string
   constructor(
     nodeosEndpoint: string = "http://localhost:8888",
@@ -25,6 +22,9 @@ export default class NodeosActionReader extends AbstractActionReader {
     this.nodeosEndpoint = nodeosEndpoint.replace(/\/+$/g, "")
   }
 
+  /**
+   * Returns a promise for the head block number.
+   */
   public async getHeadBlockNumber(): Promise<number> {
     const blockInfo = await this.httpRequest("get", {
       url: `${this.nodeosEndpoint}/v1/chain/get_info`,
@@ -36,6 +36,9 @@ export default class NodeosActionReader extends AbstractActionReader {
     return blockInfo.head_block_num
   }
 
+  /**
+   * Returns a promise for a `NodeosBlock`.
+   */
   public async getBlock(blockNumber: number): Promise<NodeosBlock> {
     const rawBlock = await this.httpRequest("post", {
       url: `${this.nodeosEndpoint}/v1/chain/get_block`,

src/demux/readers/eos/NodeosBlock.test.ts

@@ -1,4 +1,4 @@
-import NodeosBlock from "./NodeosBlock"
+import { NodeosBlock } from "./NodeosBlock"
 
 const rawBlock = {
   timestamp: "2018-06-16T05:59:49.500",

src/demux/readers/eos/NodeosBlock.ts

@@ -1,7 +1,7 @@
 import { EosAction } from "./interfaces"
 import { Block } from "../../../../index"
 
-export default class NodeosBlock implements Block {
+export class NodeosBlock implements Block {
   public actions: EosAction[]
   public blockHash: string
   public blockNumber: number

src/demux/readers/eos/index.ts

@@ -1,5 +1,3 @@
-import NodeosActionReader from "./NodeosActionReader"
+import { NodeosActionReader } from "./NodeosActionReader"
 
-module.exports = {
-  NodeosActionReader,
-}
+export const eos = { NodeosActionReader }

src/demux/readers/eos/interfaces.ts

@@ -1,11 +1,11 @@
 import { Action } from "../../../../index"
 
-interface EosAuthorization {
+export interface EosAuthorization {
   actor: string
   permission: string
 }
 
-interface EosPayload {
+export interface EosPayload {
   account: string
   actionIndex: number
   authorization: EosAuthorization[]

src/demux/readers/index.ts

@@ -1,7 +1,9 @@
-import AbstractActionReader from "./AbstractActionReader"
-import * as eos from "./eos"
+import { AbstractActionReader } from "./AbstractActionReader"
+import { eos } from "./eos"
+import { testing } from "./testing"
 
-module.exports = {
+export const readers = {
   AbstractActionReader,
   eos,
+  testing,
 }

src/demux/readers/testing/JsonActionReader.ts

@@ -1,8 +1,11 @@
-import AbstractActionReader from "../AbstractActionReader"
+import { AbstractActionReader } from "../AbstractActionReader"
 import request from "request-promise-native"
 import { Block } from "../../../../index"
 
-export default class JsonActionReader extends AbstractActionReader {
+/**
+ * Reads from an array of `Block` objects, useful for testing.
+ */
+export class JsonActionReader extends AbstractActionReader {
   constructor(
     protected blockchain: Block[],
     public startAtBlock: number = 1,

src/demux/readers/testing/index.ts

@@ -0,0 +1,3 @@
+import { JsonActionReader } from "./JsonActionReader"
+
+export const testing = { JsonActionReader }

src/demux/watchers/BaseActionWatcher.ts

@@ -1,21 +1,27 @@
-import AbstractActionHandler from "../handlers/AbstractActionHandler"
-import AbstractActionReader from "../readers/AbstractActionReader"
+import { AbstractActionHandler } from "../handlers/AbstractActionHandler"
+import { AbstractActionReader } from "../readers/AbstractActionReader"
 
-export default class BaseActionWatcher {
+/**
+ * Cooredinates implementations of `AbstractActionReader`s and `AbstractActionHandler`s in
+ * a polling loop.
+ */
+export class BaseActionWatcher {
   constructor(
     protected actionReader: AbstractActionReader,
     protected actionHandler: AbstractActionHandler,
     protected pollInterval: number) {
   }
 
+  /**
+   * Starts a polling loop running in replay mode.
+   */
   public async replay() {
     await this.actionReader.seekToBlock(this.actionReader.startAtBlock)
     await this.watch()
   }
 
   /**
    * Uses the given actionReader and actionHandler to poll and process new blocks.
-   * @returns {Promise<void>}
    */
   protected async watch() {
     // Record start time

src/demux/watchers/index.ts

@@ -1,5 +1,3 @@
-import BaseActionWatcher from "./BaseActionWatcher"
+import { BaseActionWatcher } from "./BaseActionWatcher"
 
-module.exports = {
-  BaseActionWatcher,
-}
+export const watchers = { BaseActionWatcher }

src/index.ts

@@ -1,9 +1,3 @@
-import * as handlers from "./demux/handlers"
-import * as readers from "./demux/readers"
-import * as watchers from "./demux/watchers"
-
-export {
-  handlers,
-  readers,
-  watchers,
-}
+export { handlers } from "./demux/handlers"
+export { readers } from "./demux/readers"
+export { watchers } from "./demux/watchers"