This is the class that holds all the logic and configuration of your, well, app ;)
-The basic constructor is:
+The basic constructor is:
```js
-const newApp = new Sealious.App(config, manifest)
+const newApp = new Sealious.App(config, manifest);
```
`config` and `manifest` both influence how the app will be set up.
@@ -20,15 +20,15 @@
`config` is considered secret, and contains information on the infrastructure, as well as SMTP passwords and the like.
-It's best to be kept in a separate json/yml file, and imported with
+It's best to be kept in a separate json/yml file, and imported with
```js
-const config = require("./config.json")
+const config = require("./config.json");
```
in your app.
-The default config is:
+The default config is:
```json
{
@@ -65,16 +65,16 @@
* `name` (string) - the name of your app
* `logo` (string) - path to an image with the logo of your app
-* `version` (string) - the version of your app
+* `version` (string) - the version of your app
* `colors.primary` (string) - the primary color of your brand
* `default_language` (string) - the default language for your app. Email templates use this
* `admin_email` (string) - the email address of the admin. It might be publicly revealed within the app. Used to create the initial admin account. Whenever the app starts and there's no user with that email, a registration intent is created, causing an email to be sent to this address.
-You can also include your own fields/values, so they can be easily shared across different modules on both back-end and front-end.
+You can also include your own fields/values, so they can be easily shared across different modules on both back-end and front-end.
## Configuring your app
-Every Sealious application has an `App.ConfigManager` interface through which you can configure settings available throughout all the various components of your application. It comes with some sane defaults.
+Every Sealious application has an `App.ConfigManager` interface through which you can configure settings available throughout all the various components of your application. It comes with some sane defaults.
Each field can implement its own filtering logic, by the means of the `filter_to_query` method. It's goal is to transform user input (like `{">": 52}`) into a Mongo `$match` operator (like `{$gt: 52}`). It should be an `async` function.
+
+## AND and OR access strategy optimization
+
+Sealious communicates with mongo using mainly MongoDB Pipelines, which are represented as arrays of stages. Two main pipeline stages are `lookups` and `matches` (equivalents of SQL `joins` and `wheres`). Lookups are quite expensive in comparison to matches; thus, we would like to do them as lately as possible. However, we cannot just place them in the end because some matches can be dependent on some lookups, as they use fields fetched by lookups. In addition, some lookups can also be done only after another lookup(s) takes place. Hence, we have to build a dependency graph and run a kind of priority-first search algorithm on it.
+
+The construction of dependency graph is straightforward. Firstly, a new node, which is an equivalent of a single pipeline stage, is just inserted to the graph as a seperate node. If it represents `match` and queries more than one field, it will be split. For instance:
+will create two seperate nodes. The split is done because of optimization reasons - some fields within single `match` may be dependent on other nodes, while other are dependency free. Then, if node has dependencies an edge from the direct dependency is added. Note that it is enough because any additional dependencies are also undoubtly parents for the direct dependency (it simply means that a field required a few lookups to access it).
+
+The order of visiting the nodes depends on two sets: the _front_, denoted by _F_, and the _candidates_, denoted by _C_. _F_ embraces the nodes, which have already been visited, but at least one of their children is still to be visited. To simplify the notation we can distinguish dummy node _Ø_, which is a parent to orphans. Consequently, _C_ embraces all direct children of nodes in _F_. Thus, while traversing the graph we evaluate next step from the perspective of the whole front instead of single node.
+For the first two steps _F_ only embraces our dummy node. First visitee is obviously `M3`, as matches have the highest priority. It doesn't become a part of front because it has no children. The second visitee is determined by calculating the additional fitness measure which is average priority of children of each candidate. The fitness of single match is definetely better than the average of lookup and match, so `L1` is our choice.
+At last _Ø_ leaves _F_. The front moves down the right subtree of `L4`.
+
+<pre>
+<b>7.</b>
+ +-------Ø--------+
+ | | |
+ | | |
+ v v v
+L1 M3 +----L4----+
+ + | |
+ | | |
+ v v v
+M2 L5* M6
+ +
+ |
+ v
+ M7
+<em>F</em>:
+<em>C</em>: <em>L5</em>
+</pre>
+
+The only node left in candidates is `L5`, so algorithm picks it up. We traversed the whole graph, so that's it.
+
+## Query class
+
+Whenever possible we try to use `Query` class instead of raw MongoDB queries. The following classes extend `Query` class (their names are rather self-explanatory):
+
+* `Query.And`
+* `Query.Or`
+* `Query.Not`
+* `Query.DenyAll`
+* `Query.AllowAll`
+
+Every class which belongs to `Query` group has to expose the functions below. The usage examples can be find in `lib/datastore/query.test.js`.
+
+### `lookup(body)`
+
+Adds lookup to the query.
+
+Returns hexadecimal hash of passed lookup.
+
+### `match(body)`
+
+Adds match to the query.
+
+### `dump()`
+
+Usually other queries are supplied with its return value. It is rather used internally by classes implementing `Query`.
+
+Returns the inner representation of the query.
+
+### `toPipeline()`
+
+Returns the MongoDB aggregation pipeline.
+
+### `fromSingleMatch(body)`
+
+Returns the query object on which `match(body)` has been called.
+
+### `fromCustomPipeline(pipeline)`
+
+Returns the query object equivalent to the given pipeline.
+
+---
+
+Classes that implement operators requiring multiple subqueries expose also the following:
+
+### `addQuery(query)`
+
+Adds argument as the another parameter of the operator connected with base query (`and`, `or`, etc.)