Merge pull request #49 from EOSIO/develop

Release 4.0.0

.npmignore

@@ -1,12 +1,19 @@
-src
-tsconfig.json
-tslint.json
 dist/**/*.test.*
+dist/testHelpers/
+docs/
+examples/
+scripts/
+src/
+.eslintrc.json
+.gitignore
 .idea
-yarn-error.log
+.npmignore
+.npmrc.template
+.nvmrc
 .travis.yml
-.eslintrc.json
+CONTRIBUTING.md
 README.md
-build-docs.sh
-.npmrc.template
-scripts/*
+tsconfig.json
+tslint.json
+yarn.lock
+yarn-error.log

.nvmrc

@@ -1 +1 @@
-8.9.4
+10.15.1

.travis.yml

@@ -1,29 +1,42 @@
 sudo: false
 language: node_js
 node_js:
-  - '10.0.0'
+- '10.0.0'
 before_install:
-  - npm i -g [email protected]
-  - npm install -g typescript
+- npm i -g [email protected]
+- npm install -g typescript
 stages:
-  - test
-  - name: deploy
-    if: (NOT type IN (pull_request)) AND (branch = develop)
+- test
+- name: publish-edge
+  if: (NOT type IN (pull_request)) AND (branch = develop)
+- name: publish-latest
+  # Travis assigns the tag to branch for some reason. This matches any valid semver version.
+  if: branch =~ ^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$
 jobs:
   include:
-    - stage: test
-      name: "Lint and Test"
-      script:
-        - npm run lint
-        - npm run test
-    - stage: deploy    
-      name: "Deploy to NPM"
-      script:
-        - npm run build
-      deploy:
-        provider: script
-        skip_cleanup: true
-        script: 
-          - ./scripts/publish.sh
-        on:
-          branch: develop
+  - stage: test
+    name: "Lint and Test"
+    script:
+    - npm run lint
+    - npm run test
+  - stage: publish-edge
+    name: "Publish @edge to NPM"
+    script:
+    - npm run build
+    deploy:
+      provider: script
+      skip_cleanup: true
+      script: ./scripts/publish-edge.sh
+      on:
+        branch: develop
+  - stage: publish-latest
+    name: "Publish @latest to NPM"
+    script:
+    - npm run build
+    deploy:
+      provider: script
+      skip_cleanup: true
+      script: ./scripts/publish-latest.sh
+      on:
+        all_branches: true
+        condition: $TRAVIS_TAG =~ ^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$

README.md

@@ -16,7 +16,65 @@ npm install massive --save
 
 ### MassiveActionHandler
 
-The MassiveActionHandler uses [massive-js](https://github.com/dmfay/massive-js) to interact with a Postgres database for storing internal demux state as well as the state calculated by updaters.
+The `MassiveActionHandler` uses [massive-js](https://github.com/dmfay/massive-js) to interact with a Postgres database for storing internal demux state and state calculated by Updaters. Rollback of state due to forks is supported by committing all database writes to per-block databases transactions, and utilizing [Cyan Audit](https://bitbucket.org/neadwerx/cyanaudit/overview) to reverse those transactions in reverse order when needed.
+
+#### Setup
+
+In order to instantiate a `MassiveActionHandler`, four arguments are needed:
+
+- `handlerVersions`: This is an array of `HandlerVersion`s. For more information, [see the `demux-js` documentation](https://eosio.github.io/demux-js/classes/abstractactionhandler.html#applyupdaters). 
+
+- `massiveInstance`: A connected massive database connection object. demux-js-postgress requires that you have a Postgres server running version 9.6 or greater. For more information on how to configure and instantiate this object, see the [massivejs documentation](https://github.com/dmfay/massive-js#connecting-to-a-database).
+
+- `dbSchema`: The name of the schema we will operate in.
+
+- `migrationSequences`: *(See next section below)*
+
+#### Migrations
+
+The `MassiveActionHandler` will manage all of the Postgres migrations relevant to demux operations. In addition to setting up all internal requirements (idempotently creating the specified `dbSchema` and required internal tables, installing/activating Cyan Audit), you may create additional migrations that run either at initial setup, or are triggered by an action at some point in the future. This is done by writing your migrations as SQL files, loading them via the `Migration` constructor, and collecting them into an array of `MigrationSequence`s:
+
+*create_todo_table.sql*
+```sql
+CREATE TABLE ${schema~}.todo (
+  id int PRIMARY KEY,
+  name text NOT NULL
+);
+```
+
+*migrationSequences.js*
+```javascript
+import { Migration } from "demux-postgres"
+
+const createTodoTable = new Migration(
+  "createTodoTable", // name
+  "myschema", // schema
+  "create_todo_table.sql", // SQL file
+)
+
+// MigrationSequence[]
+// See: https://github.com/EOSIO/demux-js-postgres/blob/develop/src/interfaces.ts
+module.exports = [{
+  migrations: [createTodoTable],
+  sequenceName: "init"
+}]
+```
+
+You can then use this object for the `migrationSequences` argument of the `MassiveActionHandler` constructor.
+
+Once you have instantiated the `MassiveActionHandler`, you can set up your database via the `setupDatabase()` method. If you have a `MigrationSequence` with the name `"init"`, then this migration sequence will run after all other internal database setup is finished.
+
+It can be useful to trigger migrations from actions (for example, when a contract updates), much in the same way it is useful to [update HandlerVersions](https://eosio.github.io/demux-js/classes/abstractactionhandler.html#applyupdaters). You may do this from an Updater's `apply` function via `db.migrate(<MigrationSequence.sequenceName>)`:
+
+```javascript
+async function migrateDatabase(db, payload) {
+  await db.migrate(payload.sequenceName) // Blockchain will determine when and what migrations will run
+}
+```
+
+This is also important for maintaining determinism of data (e.g. during replays) if schema changes are needed.
+
+### Example
 
 ```javascript
 const { BaseActionWatcher } = require("demux")
@@ -28,6 +86,9 @@ const massive = require("massive")
 // See https://eosio.github.io/demux-js/ for info on Handler Versions, Updaters, and Effects
 const handlerVersions = require("./handlerVersions") // Import your handler versions
 
+// See "Migrations" section above
+const migrationSequences = require("./migrationSequences")
+
 // See https://dmfay.github.io/massive-js/connecting.html for info on massive configuration
 const dbConfig = { ... }
 
@@ -36,7 +97,8 @@ massive(dbConfig).then((db) => {
   const actionHandler = new MassiveActionHandler(
     handlerVersions,
     db,
-    dbConfig.schema
+    dbConfig.schema,
+    migrationSequences
   )
   const actionWatcher = new BaseActionWatcher(actionReader, actionHander, 500)
   actionWatcher.watch()