EliasDB Event Condition Action Language
=======================================

EliasDB supports a scripting language called [Event Condition Action Language (ECAL)](https://devt.de/krotik/ecal/) to enable rule based scripting functionality.

EliasDB specific events which can be handled:
--
The ECAL interpreter in EliasDB receives the following events:

EliasDB Graph Event | ECAL event kind | Event state contents | Description
-|-|-|-
graph.EventNodeCreated | `db.node.created` | part, trans, node | A node was created.
graph.EventNodeUpdated | `db.node.updated` | part, trans, node, old_node | A node was updated.
graph.EventNodeDeleted | `db.node.deleted` | part, trans, node | A node was deleted.
graph.EventEdgeCreated | `db.edge.created` | part, trans, edge | An edge was created.
graph.EventEdgeUpdated | `db.edge.updated` | part, trans, edge, old_edge | An edge was updated.
graph.EventEdgeDeleted | `db.edge.deleted` | part, trans, edge | An edge was deleted.
graph.EventNodeStore | `db.node.store` | part, trans, node | A node is about to be stored (always overwriting existing values).
graph.EventNodeUpdate | `db.node.update` | part, trans, node | A node is about to be updated. Only thrown when graph.UpdateNode is called directly.
graph.EventNodeDelete | `db.node.delete` | part, trans, key, kind | A node is about to be deleted.
graph.EventEdgeStore | `db.edge.store` | part, trans, edge | An edge is about to be stored.
graph.EventEdgeDelete | `db.edge.delete` | part, trans, key, kind | An edge is about to be deleted.

TODO: Explaination
Add special function to signal that an event has been handled

Note: EliasDB will wait for the event cascade to be finished before performing the actual operation (e.g. inserting a node). If the event handling requires a time consuming operation then a new event cascade should be started using `addEvent` with a scope:
```
addEvent("request", "foo.bar.xxx", {
   "payload" : 123
}, {
   "": true  # This scope allows all events
})
```

EliasDB specific functions:
--
The ECAL interpreter in EliasDB supports the following EliasDB specific functions:

#### `db.storeNode(partition, nodeMap, [transaction])`
Inserts or updates a node in EliasDB.

Parameter | Description
-|-
partition | Partition of the node
nodeMap | Node object as a map with at least a key and a kind attribute
transaction | Optional a transaction to group a set of changes

Example:
```
db.storeNode("main", {
  "key" : "foo",
  "kind" : "bar",
  "data" : 123,
})
```

#### `db.removeNode(partition, nodeKey, nodeKind, [transaction])`
Removes a node in EliasDB.

Parameter | Description
-|-
partition | Partition of the node
nodeKey | Key attribute of the node to remove
nodeKind | Kind attribute of the node to remove
transaction | Optional a transaction to group a set of changes

Example:
```
db.removeNode("main", "foo", "bar")
```

#### `db.fetchNode(partition, nodeKey, nodeKind)`
Fetches a node in EliasDB.

Parameter | Description
-|-
partition | Partition of the node
nodeKey | Key attribute of the node to fetch
nodeKind | Kind attribute of the node to fetch

Example:
```
db.fetchNode("main", "foo", "bar")
```

#### `db.storeEdge(partition, edgeMap, [transaction])`
Inserts or updates an edge in EliasDB.

Parameter | Description
-|-
partition | Partition of the edge
edgeMap | Edge object as a map with at least the main attributes: key, kind, end1cascading, end1key, end1kind, end1role, end2cascading, end2key, end2kind, end2role
transaction | Optional a transaction to group a set of changes

Example:
```
db.storeEdge("main", {
  "key":           "123",
  "kind":          "myedges",
  "end1cascading": true,
  "end1key":       "foo",
  "end1kind":      "bar",
  "end1role":      "role1",
  "end2cascading": false,
  "end2key":       "key2",
  "end2kind":      "kind2",
  "end2role":      "role2",
})
```

#### `db.removeEdge(partition, edgeKey, edgeKind, [transaction])`
Removes an edge in EliasDB.

Parameter | Description
-|-
partition | Partition of the edge
edgeKey | Key attribute of the edge to remove
edgeKind | Kind attribute of the edge to remove
transaction | Optional a transaction to group a set of changes

Example:
```
db.removeEdge("main", "123", "myedges")
```

#### `db.fetchEdge(partition, edgeKey, edgeKind)`
Fetches an edge in EliasDB.

Parameter | Description
-|-
partition | Partition of the edge
edgeKey | Key attribute of the edge to fetch
edgeKind | Kind attribute of the edge to fetch

Example:
```
db.fetchEdge("main", "123", "myedges")
```

#### `db.traverse(partition, nodeKey, nodeKind, traversalSpec)`
Traverses an edge in EliasDB from a given node. Returns a list of nodes which were
reached and a list of edges which were followed.

Parameter | Description
-|-
partition | Partition of the node
nodeKey | Key attribute of the node to traverse from
nodeKind | Kind attribute of the node to traverse from
traversalSpec | Traversal spec

Example:
```
[nodes, edges] := db.traverse("main", "foo", "bar", "role1:myedges:role2:kind2")
```

#### `db.newTrans()`
Creates a new transaction for EliasDB.

Example:
```
trans := db.newTrans()
```

#### `db.newRollingTrans(n)`
Creates a new rolling transaction for EliasDB. A rolling transaction commits after n entries.

Parameter | Description
-|-
n | Rolling threshold (number of operations before rolling)

Example:
```
trans := db.newRollingTrans(5)
```

#### `db.commit(transaction)`
Commits an existing transaction for EliasDB.

Parameter | Description
-|-
transaction | Transaction to execute

Example:
```
db.commit(trans)
```

#### `db.query(partition, query)`
Run an EQL query.

Parameter | Description
-|-
partition | Partition to query
query | Query to execute

Example:
```
db.commit("main", "get bar")
```

#### `db.graphQL(partition, query, [variables], [operationName])`
Run a GraphQL query.

Parameter | Description
-|-
partition | Partition to query
query | Query to execute
variables | Map of variables for the query
operationName | Operation to execute (useful if the query defines more than a single operation)

Example:
```
db.graphQL("main", "query myquery($x: string) { bar(key:$x) { data }}", {
  "x": "foo",  
}, "myquery")
```

#### `db.raiseGraphEventHandled()`
When handling a graph event, notify the GraphManager of EliasDB that no further action is necessary.

Example:
```
sink mysink
  kindmatch [ "db.*.*" ],
{
  db.raiseGraphEventHandled()
}
```