Javascript library to create and manipulate a provenance graph. The provenance graph can be used as a non-linear undo graph.
API documentation at https://visualstorytelling.github.io/provenance-core/
provenance-core
is designed to record and replay user interaction in web applications. Furthermore the aim is to provide tools around it to recombine this interaction history data into slides / stories (see e.g. @visualstorytelling/provenance-tree-visualization and @visualstorytelling/slide-deck-visualization.
For a simple demo, see: provenance-tree-calculator-demo.
If provenance-core
is to track the provenance in your application you will need to provide it with user actions. This probably means hooking up your event emitters to a ProvenanceGraph through a ProvenanceTracker.
By applying Actions that are mapped to ActionFunctions
in an ActionFunctionRegistry, we can build a serializable graph that can undo and replay all actions.
ProvenanceTraverser can then be used to go back and forward to any previous/future state: it will figure out the path through the graph and execute all the actions to get to the target Node.
ProvenanceGraph
s can be (de-)serialized using serializeProvenanceGraph() and restoreProvenanceGraph() so that they can be stored and retrieved.
For a simple example on how to track provenance (in this case, of a basic button) see this JSFiddle
Record the actions performed on a simple calculator. Traverse undo graph to any point will undo/redo all actions to get to that point.
import {
ActionFunctionRegistry,
ProvenanceGraph,
ProvenanceGraphTraverser,
ProvenanceTracker
} from '@visualstorytelling/provenance-core';
class Calculator {
result = 0;
async add(offset) {
this.result += offset;
}
async subtract(offset) {
this.result -= offset;
}
}
async function runme() {
const calculator = new Calculator();
const registry = new ActionFunctionRegistry();
registry.register('add', calculator.add, calculator);
registry.register('subtract', calculator.subtract, calculator);
const graph = new ProvenanceGraph({name: 'myapplication', version:'1.2.3'});
const tracker = new ProvenanceTracker(registry, graph);
const traverser = new ProvenanceGraphTraverser(registry, graph);
// Call the add function on the calculator via the provenance tracker
result = await tracker.applyAction({
do: 'add',
doArguments: [13],
undo: 'subtract',
undoArguments: [13]
});
// calculator.result == 13
// Undo action by going back to parent
traverser.toStateNode(result.parent.id);
// calculator.result == 0
}
runme();
- ProvenanceTreeVisualization: A user interface based on
d3
for displaying / navigating through the graph. - SlidedeckVisualization: A user interface based on
d3
for creating presentation slide decks / stories.
npm install @visualstorytelling/provenance-core
git clone https://github.com/VisualStorytelling/provenance-core.git
cd provenance-core
npm install
npm t
: Run test suitenpm start
: Runnpm run build
in watch modenpm run test:watch
: Run test suite in interactive watch modenpm run test:prod
: Run linting and generate coveragenpm run build
: Generate bundles and typings, create docsnpm run lint
: Lints codenpm run commit
: Commit using conventional commit style (husky will tell you to use it if you haven't 😉)
On library development, one might want to set some peer dependencies, and thus remove those from the final bundle. You can see in Rollup docs how to do that.
Good news: the setup is here for you, you must only include the dependency name in external
property within rollup.config.js
. For example, if you want to exclude lodash
, just write there external: ['lodash']
.
Prerequisites: you need to create/login accounts and add your project to:
Prerequisite for Windows: Semantic-release uses node-gyp so you will need to install Microsoft's windows-build-tools using this command:
npm install --global --production windows-build-tools
Follow the console instructions to install semantic release and run it (answer NO to "Do you want a .travis.yml
file with semantic-release setup?").
npm install -g semantic-release-cli
semantic-release-cli setup
# IMPORTANT!! Answer NO to "Do you want a `.travis.yml` file with semantic-release setup?" question. It is already prepared for you :P
From now on, you'll need to use npm run commit
, which is a convenient way to create conventional commits.
Automatic releases are possible thanks to semantic release, which publishes your code automatically on github and npm, plus generates automatically a changelog. This setup is highly influenced by Kent C. Dodds course on egghead.io
There is already set a precommit
hook for formatting your code with Prettier 💅
By default, there are two disabled git hooks. They're set up when you run the npm run semantic-release-prepare
script. They make sure:
- You follow a conventional commit message
- Your build is not going to fail in Travis (or your CI server), since it's runned locally before
git push
This makes more sense in combination with automatic releases
- Bump the version in package.json
- Run
npm run build
- Publish on npmjs
3.1 Login to npmjs with
npm login
3.2npm publish --access public
to publish package - Create a GitHub release
- Verify Zenodo entry