IMPROVE readme

README.md

@@ -2,7 +2,7 @@
 
 <h1 align="center">Event-Reduce</h1>
 <p align="center">
-  <strong>An optimisation algorithm to speed up database queries that run multiple times</strong>
+  <strong>An algorithm to optimize database queries that run multiple times</strong>
 </p>
 
 <br/>
@@ -13,16 +13,16 @@
 
 
 <ul>
-    <li>You make a query to the database which returns the result in X milliseconds</li>
-    <li>A write event happens to the database and changes some data</li>
-    <li>To get the new version of the query-results you now have three options:</li>
+    <li>You make a query to the database which returns the result in 100 milliseconds</li>
+    <li>A write event occurs on the database and changes some data</li>
+    <li>To get the new version of the query's results you now have three options:</li>
     <ul>
-        <li>Run the query over the database again which takes another X milliseconds</li>
+        <li>Run the query over the database again which takes again 100 milliseconds</li>
         <li>
             Write complex code that calculates the new result depending on many different states and conditions
         </li>
         <li>
-            Use <b>Event-Reduce</b> to calculate the new results without disc-IO <b>nearly instant</b>
+            Use <b>Event-Reduce</b> to calculate the new results on the CPU without disc-IO <b>nearly instant</b>
         </li>
     </ul>
 </ul>
@@ -37,58 +37,44 @@
 
 <br/>
 
-* * *
+## Efficiency
+
+In the [browser demo](https://pubkey.github.io/event-reduce) you can see that for randomly generated events, about **94%** of them could be optimized by EventReduce. In real world usage, with non-random events, this can be even higher. For the different implementations in common browser databases, we can observe an up to **12 times** faster displaying of new query results after a write occurred.
+
+## How they do it
+
+EventReduce uses 17 different `state functions` to 'describe' an event+previousResults combination. A state function is a function that returns a boolean value like `isInsert()`, `wasResultsEmpty()`, `sortParamsChanged()` and so on.
 
-### Efficiency
+Also there are 14 different `action functions`. An action function gets the event+previousResults and modifies the results array in a given way like `insertFirst()`, `replaceExisting()`, `insertAtSortPosition()`, `doNothing()` and so on.
 
-### When to use this
+For each of our `2^17` state combinations, we calculate which action function gives the same results that the database would return when the full query is executed again.
 
-### How it works
+From this state-action combinations we create a big truth table that is used to create a [binary decision diagram](https://github.com/pubkey/binary-decision-diagram). The BDD is then optimized to call as less `state functions` as possible to determine the correct action of an incoming event-results combination.
 
-### Implementations
+The resulting optimized BDD is then shipped as the EventReduce algoritm and can be used in different programming languages and implementations.
 
-### When not to use this
+## When to use this
 
-### Limitations
+You can use this to..
 
-- EventReduce only works with queries that have a predictable sort-order for any given documents https://stackoverflow.com/a/11599283
+* ..reduce the latency until a change to the database updates your application
+* ..make observing query results more scalable by doing less disk-io
+* ..reduce the bandwith when streaming realtime query results from the backend to the client
 
-So if you sort by `gender` and `age` and two documents have the same `gender` and `age` the sorting is not predictable. Therefore you could add the primary key as third sort parameter.
+## Limitations
 
+- EventReduce only works with queries that have a [predictable](https://stackoverflow.com/a/11599283) sort-order for any given documents. (you can make any query predicable by adding the primary key as last sort parameter)
 
-### Previous Work
+- EventReduce can be used with relational databases but not on relational queries that run over multiple tables/collections. (you can use views as workarround)
 
+## Implementations
 
+At the moment there is only the [javascript implementation](./javascript/) that you can use over npm. Pull requests for other languages are welcomed.
 
+## Previous Work
 
-states:
-- wasInResult
-- wasMatching
-- doesMatchNow
-- hasSkip
-- hasLimit
-- wasLimitReached
-- wasSortedBeforeFirst
-- wasSortedAfterLast
-- isSortedBeforeFirst
-- isSortedAfterLast
-- isSortedBeforeFirst
-- isSortedAfterFirst
-- sortParamsChanged
-- previousStateUnknown
-- isDelete
-- isInsert
-- isUpdate
+- Meteor uses a feature called [OplogDriver](https://github.com/meteor/docs/blob/master/long-form/oplog-observe-driver.md) that is limited on queries that do not use `skip` or `sort`. Also watch [this video](https://www.youtube.com/watch?v=_dzX_LEbZyI&t=2047s) to learn how OpLogDriver works.
 
-actions:
+- RxDB used the [QueryChangeDetection](https://github.com/pubkey/rxdb/blob/a7202ac7e2985ff088d53d6a0c86d90d0b438467/docs-src/query-change-detection.md) which works by many handwritten if-else comparisons. RxDB will switch to EventReduce in it's next major release.
 
-- doNothing
-- insertFirst
-- insertLast
-- insertAtSortPosition
-- replaceExisting
-- removeExisting
-- removeExistingAndInsertAtSortPosition
-- removeLastItem
-- removeFirstItem
-- Fallback: runFullQueryAgain
+- Baqend is [creating a database](https://vsis-www.informatik.uni-hamburg.de/getDoc.php/publications/620/invalidb_4-pages.pdf) that optimizes for realtime queries. Watch the video [Real-Time Databases Explained: Why Meteor, RethinkDB, Parse & Firebase Don't Scale](https://www.youtube.com/watch?v=HiQgQ88AdYo&t=1703s) to learn more.

orga/event-reduce.drawio

@@ -0,0 +1 @@
+<mxfile host="www.draw.io" modified="2020-02-21T19:41:31.097Z" agent="Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/79.0.3945.88 Safari/537.36" etag="kqVLrisDNEIyxuVWzBLi" version="12.7.3" type="device"><diagram id="C5RBs43oDa-KdzZeNtuy" name="Page-1">3Zddk5owFIZ/DZc6QADlcnVd227babttvY4QIWMgbAiK++ubQFC+HIe2jNNyoeHNF3nOyTmJBpZRvmYwCT9RHxHN1P1cA4+aac5NXfxK4VQKwFVCwLBfSsZFeMFvSIlVswz7KG005JQSjpOm6NE4Rh5vaJAxemw221HSnDWBAeoILx4kXXWDfR5Wy5pd9HcIB2E1s+G4ZU0Eq8ZqJWkIfXqsSWClgSWjlJelKF8iItlVXDbvTxvyce+sP3xNX+GPxfP3zz8n5WBPQ7qcl8BQzH976Nzxn92HtZsna/YlPuxSboCJYZdjHyDJFDC1WH6qCIp1J7KIcjH5wqfZtqgxxAujWewjOYEu3o4h5uglgZ6sPgpvElrII6Ia7zAhS0ooK4YFT8Uj9JQzukd9NerbEOMob1nzBgrjbB/h14hGiLOT6HeseUDloGHN+hZQIlReF5z7XsiKgoI7ALTZ4Swd2dRfM1R8mWY6ROLdMlEKZImhNCM87ZhjEPO/TrAKC4qTCgpGxa0G2DB7AM/H4gs6fFcHucDr9Iz70QN6C5/Vg0/vweeMhW9AGPAYTdPBu10vnhGZmuZsareonpUaV8vu2fb2SFjd21j/JISODtWyWo5qdx3V6fFTYyw/rQb+f4jO7020m5lidBRJCEYSVbxN5d8/mqbsNu275ymjm6iuR9qMkdOCQW+P+G2Gzcx2za8Z5ZBjGgt54o7p6MB2p2DWoD+xhDTvGKCPv+3Op7OxorJhXTss6N+Qnwm+bYvw8uxbow0JDiRET/RDAvJCEsTi2vGgKiLs+7K73CD4DZZnZgk8oTjmxZLshWY/yrEyTtPy4jTqqcNs5sdznKnZwu2xhTl8L4jXy72oqKtdLsHqFw==</diagram></mxfile>